附录 G · Paseo —— 给编码 Agent 配一个"指挥官"

🐣 小a的烦恼
小a在 pi 工坊越干越顺手,老z开始同时给它派好几个活:"这个 bug 你修着,那个功能你也写,顺便把测试补一下。"
小a没长八只手,急得团团转。更糟的是,老z出门喝咖啡了,只留下一部手机:"我路上盯着你,有事我语音喊你。"
小a傻眼了:它只会跑在终端里,手机怎么看?语音怎么听?
这时候,隔壁工坊推门进来一个家伙——它不写代码,它专门指挥别人写代码。它就是 Paseo。

G.1 Paseo 是什么:不写代码,只指挥别人写

先说清楚 Paseo 的定位,因为它很容易被误解成"又一个 Agent 框架"。

🧙 一句话定义
Paseo 是一个开源的多端"指挥台",让你从桌面、手机、网页、命令行任何地方,远程控制多个编码 Agent(Claude Code、Codex、Cursor、OpenCode、pi)。
官方原话:"Orchestrate multiple coding agents from desktop and mobile"——从桌面和移动端编排多个编码 agent。

关键认知:Paseo 自己不调 LLM,不写代码。它是"指挥官",不是"士兵"。被它指挥的士兵,才是真正的编码 agent(pi、Claude Code 等)。

🧙 老z打比方:
pi / Claude Code / Codex = 一线干活的程序员(本书的主角们)
Paseo = 项目经理 + 调度台 + 监控屏
你可以用 Paseo 同时开三个 agent 干三件事,出门用手机盯着它们,语音喊一句"再加个测试",它们就接着干。

这与本书已经讲过的东西形成清晰对比:

	它干什么	干活的是谁
pi(本书主角)	自己写代码	pi 自己(调 LLM)
Paseo(本附录)	指挥别人写代码	pi / Claude Code / Codex(子进程)

所以 Paseo 和 pi 不是竞争,是上下游——Paseo 把 pi 当作一个被编排的对象。官方 topic 里就挂着 pi,社区里也有人直说:"Paseo 是个很好的 pi 界面。"

G.2 Paseo 解决什么问题

老z列举了 Paseo 解决的四个真实痛点:

痛点 1:Agent 被钉死在桌前

传统编码 agent 跑在终端里,你必须坐在电脑前盯着它。它跑个半小时,你就得守半小时。Paseo 让你起身、出门、用手机继续盯。

痛点 2:多 Agent 并行管理混乱

你想同时跑 Claude Code 改 bug、pi 写新功能——得开两个终端窗口,来回切。Paseo 给你一个统一界面,同时管多个 agent。

痛点 3:并行开发的冲突

两个 agent 同时改同一个仓库、抢同一个端口(localhost:3000),互相打架。Paseo 用 git worktree + 动态端口隔离它们(G.4 详讲)。

痛点 4:不想换工具

你已经习惯了 Claude Code 的配置、买了订阅、配好了 MCP server。换框架意味着全推倒重来。Paseo 不改 agent 的行为——它原样启动 agent 的本地 CLI,你的订阅、技能、配置、MCP server 全部照旧。

G.3 核心架构:Daemon + Client(实现原理①)

这是 Paseo 最值得拆的部分。它的架构是**解耦的"守护进程 + 客户端"**模式。

一张架构图

                  ┌─────────────────────────────────────┐
                  │        你的代码仓库 / 服务器          │
                  │                                     │
                  │   ┌──────────────────────────┐      │
                  │   │   Paseo Daemon(守护进程)│      │
                  │   │   - 管理执行环境          │      │
                  │   │   - 启动/监控 agent 子进程│      │
                  │   │   - 转发输入输出流        │      │
                  │   └──┬──────────┬────────────┘      │
                  │      │          │                   │
                  │   ┌──┴───┐  ┌───┴────┐             │
                  │   │ pi   │  │Codex   │  ← agent 子进程
                  │   │(子进程)│  │(子进程) │    (各自独立 CLI)
                  │   └──────┘  └────────┘             │
                  └──────┬──────────────────┬──────────┘
                         │                  │
            ┌────────────┘                  └─────────────┐
            │ ① 直连(局域网/Tailscale/Cloudflare)        │
            ▼                                            ▼
   ┌────────────────┐                          ┌────────────────┐
   │  桌面/手机/网页 │                          │  E2E 加密 Relay │
   │  客户端         │ ◄──── 端到端加密 ──────► │ (Paseo 托管中转)│
   └────────────────┘                          └────────────────┘

三个关键设计

🧙 设计 1:Daemon 才是大脑,客户端只是"遥控器"
真正干活的是 daemon(守护进程)——它跑在你的电脑或服务器上,负责启动 agent、监控输出、转发指令。手机和桌面客户端只是"显示屏 + 遥控器",不跑代码。
好处:代码始终留在你的机器上,不上云。 这点呼应附录 F 的"本地 vs 云端"——Paseo 虽然支持远程访问,但执行在本地,数据不出门。

🧙 设计 2:两种连接方式,直连和加密中转
客户端连 daemon 有两条路:
直连:局域网,或自建隧道(Tailscale / Cloudflare)。适合在公司内网或自己搭 VPN。
E2E 加密 Relay:Paseo 官方托管的"中转服务器",让你出门在外也能连家里的 daemon。关键:端到端加密,Paseo 自己也读不到你的流量。
这是远程访问与隐私的平衡术——你要么自己搭隧道(完全自主),要么用 Paseo 的中转(图省事但仍加密)。

🧙 设计 3:Agent 是子进程,不改其行为
Paseo 怎么"指挥" pi?不是调用 pi 的 API,而是把 pi 的本地 CLI 当作子进程启动——spawn('pi', [...])。然后:
捕获 pi 的输出流(stdout),转发给客户端显示
把客户端的输入注入回 pi 的 stdin
这是最聪明的设计:Paseo 对 agent 是"无感"的。pi 根本不知道自己在被 Paseo 指挥,它以为自己在跟一个普通终端对话。所以 pi 的所有原生配置(订阅、技能、MCP server)都不用动。

这个架构的精髓:进程即边界

🐣 小a问:"为什么要用子进程,不能直接调 LLM API 吗?"
🧙 "因为那样就变成『重造一个 pi』了。Paseo 刻意选择编排现成的 agent,而不是自己实现 agent。子进程是最干净的边界——每个 agent 在自己的进程里跑,互不干扰,Paseo 只负责喂输入、收输出。这是 Unix 哲学:让每个程序做好一件事,用进程间通信把它们串起来。"

这个设计思想和本书反复强调的"简单优先"完全一致(见 Part III 的 YAGNI 主题)。

G.4 隔离开发:Git Worktree + 动态端口(实现原理②)

这是 Paseo 解决"多 agent 并行不冲突"的核心机制,也是它最有技术含量的部分。

问题:并行 Agent 会打架

假设你同时让两个 agent 干活:

Agent A:修 fix-auth 分支的 bug
Agent B:在 add-search 分支加搜索功能

如果不隔离,它们会:

改同一个工作目录 → 文件互相覆盖
抢同一个端口 → 一个起 localhost:3000,另一个也起 3000,冲突

解法 1:Git Worktree 隔离工作区

🧙 Git worktree 是什么?

Git 允许把同一个仓库的不同分支,checkout 到不同的目录。每个 worktree 是一个独立的工作区,改一个不影响主目录。

my-app/              ← 主工作目录(你在用的)
  ├── .git/
  └── src/

my-app-worktrees/
  ├── fix-auth/      ← worktree 1:checkout 了 fix-auth 分支
  │   └── src/       ←   Agent A 在这里干活
  └── add-search/    ← worktree 2:checkout 了 add-search 分支
      └── src/       ←   Agent B 在这里干活

Paseo 在启动 agent 时,可选创建一个 git worktree,把 agent 关进这个隔离目录。这样 agent 改的代码不会碰你的主工作区。

🐣 小a恍然:"所以多个 agent 能同时改同一个仓库的不同分支,互不干扰?"
🧙 "对。这正是 pi 自己也用的机制——pi 的 harness/session/fork.ts(Part II 第 18 章)做会话分叉时,底层也是 git worktree 的思路。会话分叉隔离历史,worktree 隔离工作区,本质都是『分身不打架』。"

解法 2:动态端口 + 基于分支名的 URL

光隔离文件不够——两个 agent 都要起本地 dev server(比如 npm run dev)时,端口会撞。

Paseo 的做法:不给随机端口,而是给每个 agent 一个基于分支名的 URL:

Agent A(fix-auth 分支)→ web.fix-auth.my-app.localhost
Agent B(add-search 分支)→ web.add-search.my-app.localhost

这样每个 agent 有可预测、不冲突的本地地址,你还能一眼看出哪个 URL 对应哪个分支。

🧙 这背后是端口拦截 + 路由:Paseo 在本地起一个反向代理,把 *.localhost 的请求按分支名路由到对应的 agent 进程。比"随机分配 3001、3002"优雅得多——可读且不撞。

G.5 语音控制:本地化的 STT/TTS(实现原理③)

Paseo 有个很酷的功能:语音喊 agent 干活。它怎么实现的?

架构

你说:"给登录页加个测试"
        │
        ▼
   ┌──────────────────┐
   │ 本地 STT(语音转文字)│  ← 跑在你机器上,不上云
   └────────┬─────────┘
            │ 转成文字:"给登录页加个测试"
            ▼
   ┌──────────────────┐
   │ 注入 agent 的输入 │  ← 当作普通 prompt 喂给 agent
   └──────────────────┘
            │
            ▼
   agent 回答(文字)
            │
            ▼
   ┌──────────────────┐
   │ 本地 TTS(文字转语音)│  ← 也跑在本地
   └────────┬─────────┘
            │
            ▼
       你听到了回答

关键设计:隐私优先

🧙 STT(语音转文字)和 TTS(文字转语音)默认全跑在本地,不出你的网络。
这是有意为之。语音数据极其敏感(可能包含你的代码思路、项目机密),如果发到云端转写,等于把想法先送给别人。Paseo 选本地化,代价是音质/准确率可能不如云端,但换来了隐私。
如果你不在乎,也可以配置用 OpenAI 的云端语音服务换更好的效果——选择权给你。

这呼应了本书"数据敏感度"的主题(附录 F 决策树之五):隐私不是默认给的,是架构选出来的。

G.6 Paseo 与 pi 的关系

这是本书读者最关心的。老z画了一张"生态图":

        ┌─────────────────────────────────┐
        │           Paseo 指挥台           │
        │  (daemon + 多端客户端 + 语音)    │
        └──┬───────┬───────┬───────┬──────┘
           │       │       │       │
        ┌──┴──┐ ┌──┴──┐ ┌──┴──┐ ┌──┴──┐
        │ pi  │ │Claude│ │Codex│ │ ... │   ← 被编排的 agent
        │     │ │ Code │ │     │ │     │      (各自独立子进程)
        └─────┘ └──────┘ └─────┘ └─────┘

Paseo 把 pi 视作众多"被编排的 agent"之一,通过启动 pi 的本地 CLI 来控制它。pi 在 Paseo 里运行时:

✅ pi 的所有原生能力(tool、skill、MCP server、订阅配置)都照常工作
✅ pi 的输出被 Paseo 捕获,转发到手机/网页
✅ 你在手机上打的字/说的话,被 Paseo 注入回 pi 的输入
❌ pi 不知道自己在被远程控制——它以为自己在普通终端里

这呼应了本书哪一章?

Part I 第 12 章(多 Agent):Paseo 是"多 agent 编排"的一种实现——但它编排的是进程级的 agent,不是协议级(ACP/A2A)。它不上通信协议,靠"启动子进程 + 转发 IO"这种最朴素的方式协调。
附录 F(本地 vs 云端):Paseo 是个有趣的混合体——执行在本地(daemon),访问可远程(relay),控制可移动(手机)。它既不是纯本地工具,也不是云框架。
Part II 第 22 章(server/client):pi 自己也有远程会话能力(server/client 包)。但 pi 的远程是"一个 server 管自己的会话",Paseo 的远程是"一个 daemon 管多个不同 agent"。粒度不同。

G.7 Paseo 的设计哲学(给本书读者的启示)

老z让小a总结 Paseo 教会它的三件事:

🐣 启示 1:编排 ≠ 实现
Paseo 不自己造 agent,而是编排现成的。这证明了一个道理:很多时候,最高效的方案不是"自己全做",而是"做好胶水,把现成的优质工具粘起来"。 Unix 哲学的胜利。

🐣 启示 2:进程是最干净的边界
Paseo 用"子进程 + IO 转发"协调 agent,而不是用复杂的协议。这提醒我们:能用进程隔离解决的事,别上协议。 进程边界天然提供隔离、故障隔离、独立配置——便宜又好用。

🐣 启示 3:隐私是架构选择,不是事后补丁
语音走本地、代码留本机、中转端到端加密——Paseo 把隐私做进了架构,而不是事后加个"隐私模式"开关。好的隐私设计,从第一行代码就开始了。

G.8 选型建议:你该用 Paseo 吗?

你的情况	建议
单人、单 agent、就坐电脑前用	不需要 Paseo。直接用 pi 即可,Paseo 是多此一举。
想同时跑多个 agent 干多个任务	✅ Paseo 的统一管理正合适。
经常出门,想用手机盯 agent	✅ Paseo 的多端 + 远程是核心卖点。
团队需要隔离多个 agent 的开发环境	✅ Paseo 的 worktree + 动态端口解决冲突。
想语音控制 agent	✅ Paseo 的本地语音栈很省心。
只想深度定制一个 agent 的内部行为	❌ Paseo 不改 agent 内部,它只编排。看 Part III 自己造。

🧙 老z的忠告
"Paseo 解决的是『指挥』问题,不是『干活』问题。如果你只有一个 pi、就在一台电脑前用,Paseo 是过度工程。 它的价值在多 agent、多设备、并行隔离这些场景才显现。别为了酷而上 Paseo——先问自己:我真的需要同时管多个 agent 吗?"

G.9 一句话总结

Paseo 是编码 Agent 的"指挥台"——它不写代码,只负责从任何地方、用任何方式(键鼠/语音)、编排多个 agent 干活,并用 git worktree + 动态端口让它们和平共处。
它和 pi 是搭档,不是对手:pi 是士兵,Paseo 是指挥官。

参考

Paseo 仓库:github.com/getpaseo/paseo
官网:paseo.sh(本附录信息取自官网与仓库,2026-08 核实)
核心定位:"Orchestrate multiple coding agents from desktop and mobile"
技术栈:TypeScript(主体)+ Kotlin/Swift(原生移动端)+ Nix/Dockerfile(部署)
相关章节:Part I 第 12 章(多 Agent)、附录 F(本地 vs 云端)、Part II 第 22 章(pi 的 server/client)

G.1 Paseo 是什么:不写代码,只指挥别人写 ​

G.2 Paseo 解决什么问题 ​

痛点 1:Agent 被钉死在桌前 ​

痛点 2:多 Agent 并行管理混乱 ​

痛点 3:并行开发的冲突 ​

痛点 4:不想换工具 ​

G.3 核心架构:Daemon + Client(实现原理①) ​

一张架构图 ​

三个关键设计 ​

这个架构的精髓:进程即边界 ​

G.4 隔离开发:Git Worktree + 动态端口(实现原理②) ​

问题:并行 Agent 会打架 ​

解法 1:Git Worktree 隔离工作区 ​

解法 2:动态端口 + 基于分支名的 URL ​

G.5 语音控制:本地化的 STT/TTS(实现原理③) ​

架构 ​

关键设计:隐私优先 ​

G.6 Paseo 与 pi 的关系 ​

这呼应了本书哪一章? ​

G.7 Paseo 的设计哲学(给本书读者的启示) ​

G.8 选型建议:你该用 Paseo 吗? ​

G.9 一句话总结 ​

参考 ​