Pi实战 04：多智能体与高级工作流篇
来源：Pi 作者 Mario Zechner 博客、ruizrica2 开源项目 “agent”、HN 讨论、Reddit r/PiCodingAgent、cmux 演示。
Pi没有内置子代理（sub-agents）、没有 plan mode、没有后台 bash。官方态度很明确：“Ask Pi to build what you want, or install a package that does it your way.” 但正因如此，社区玩出了花。这一篇讲三件事：
- 用 bash 自举子代理（作者 Mario Zechner 的做法）
- 多代理编排（ruizrica2 的 28 个扩展）
- tmux 并行 + 会话树
一、经验 1：让 Pi "自己跑自己"做子代理
Mario Zechner 在博客里说得很直白：
“If you need pi to spawn itself, just ask it to run itself via bash. You could even have it spawn itself inside a tmux session for full observability.”
他的典型场景是代码审查：写一个自定义斜杠命令，让主 Agent 通过 bash 再启动一个 Pi 进程去跑审查，主进程拿到输出即可。
他给出的子代理命令 frontmatter 骨架（description: Run a code review sub-agent）：
--- description: Run a code review sub-agent --- pi --print \ --provider <provider> \ --model <model> \ --tools read,grep,find,ls \ -p "Review the current diff for correctness and security issues."怎么用：
- 把这个做成一个 prompt template（见第 02 篇），比如
/review-pr。 - 用简单提示词选具体要 review 什么、用哪个模型，甚至设思考等级。
- 可以存成临时会话（ephemeral，不落盘），或存盘后跳进那个会话继续看。
这一切最终被翻译成一个 prompt，主 Agent 读完后通过 bash 再次执行自己。虽然不如原生子代理那样"全 observable"，但足够用，而且模型/工具/思考等级都能按需指定。
关键点：Pi 没有
task工具，所以"多代理"本质是你用 bash/tmux 把它编排出来的。这恰恰是 Pi 的哲学——能力给你，怎么组你自己定。
二、经验 2：多代理编排——ruizrica2 的 “agent”
一位开发者（ruizrica2）把 Pi 改造成了一个多代理系统并开源。他的原话：
“One turned into five, five turned into 28, and at some point the whole thing became its own project: agent.”
核心做法：
- 全是扩展 + 配置文件，不 fork、不打补丁，全部通过 Pi 的扩展 API 和一个
settings.json加载 → 可移植、Pi 升级时好更新。 - Agent 定义是带 YAML frontmatter 的 Markdown 文件。加一个专家角色 = 写一个
.md文件并在配置里引用：
--- name: backend-reviewer model: anthropic/claude-sonnet-4-20250514 thinking: high tools: read,grep,bash mcp: github --- You review backend code for security and correctness. Focus on SQL injection, auth, and error handling.- 生命周期钩子 + 持久化 UI：他们 hook 进生命周期事件，在需要时更新 UI，让"主 Agent 收到子 Agent 回复"这种交互可视化。
安全层（他早期就加了，因为"不敢让 Agent 无人监督跑命令"）：
- pre-tool-hook：危险命令执行前拦截。
- content scanner：检查工具返回里有没有提示词注入。
- session start 时加固系统提示词。
- 一个
/secure命令，能审计项目并安装基础防护。
“It’s not bulletproof, but it gives me peace of mind.”
配套：还有个叫Commander的 companion 项目，充当 dashboard / Kanban / spec wizard / Jira 集成，“agent” 通过 MCP 和它双向同步任务。（两者独立，可分开用。）
三、经验 3：tmux 并行跑多个 Pi
既然 Pi 不做后台 bash，官方建议就是两个字：tmux。
- Mario Zechner：让 Pi 在 tmux session 里启动自己，获得"完全可观测 + 能直接和子代理交互"的能力。
- Reddit 有开发者晒四屏（4 个 pane）多代理setup，还做了个 Pi package 管理这些 tmux session。
- 更进阶的用cmux这类工具编排：一个
just命令一键拉起一支"agent 小队"，每个 pane 一个 agent，完成后通知你。演示里甚至同时开 Claude Code、Codex、Pi（配 MiniMax 和 GLM）组成"安全小队"扫仓库漏洞。
最小可用做法（不用任何编排工具）：
# 开一个 tmux 会话，里面并排放两个 Pitmux new-session-d-spi-nmain'pi'tmux split-window-h-tpi'pi --model gpt-5-codex'tmux attach-tpi左边用便宜模型跑探索，右边用强模型收尾，一个屏幕看两个 agent 干活。
四、经验 4：会话树——对话的"版本控制"
这是 HN 用户一致好评的功能（vorticalbox：“Sessions are stored as trees, that is actually really nice.”）。Pi 的会话不是线性列表，是一棵树，底层就是按位置存的.jsonl文件（每条消息 append 一行，极易文档化）。
实战命令：
| 命令 | 作用 |
|---|---|
/tree | 把会话历史画成树，跳到任意节点继续 |
/fork | 从当前某条消息分支，开一条新工作线 |
/clone | 把当前活跃分支复制成一个新会话 |
/resume | 捡起之前的会话继续 |
/new | 开全新会话 |
典型用法：探索复杂问题时，用/fork试方案 A，不满意再回到分叉点/fork试方案 B——不同解法互不污染。还能"rewind to any prior message, branch from there and share the entire session with others"（回退到任意消息、从那里分支、把整条会话分享给别人）。
五、实战：一套"计划-实现-验证"流水线
结合前面几篇，一个可落地的多步工作流：
- 计划：用一个
/planprompt template，让 Agent 把计划写进PLAN.md（Pi 没有 plan mode，就自己写文件）。 - 实现：主 Agent 跑；需要审查时
/review-pr起一个只读子代理（第一节）。 - 并行：把子代理丢进 tmux pane 跑，主进程继续干别的（第三节）。
- 分支复盘：对结果不满意？
/tree回到分叉点重来，不丢上下文（第四节）。 - 安全：全程有 permission-gate 拦危险命令（第 03 篇）。
社区现成的包能直接给你这套流水线，比如pi-dynamic-workflow（灵感来自 Claude Code 的 dynamic workflows）、TrailStep（把过程编码成 TS 工作流，每步有独立 scoped agent session，失败可续跑）。
六、小结
- Pi 没有原生子代理 → 用bash 自举或tmux 并行自己编排。
- 多代理 = 一堆扩展 +
settings.json+ Markdown 定义的"专家角色"。 - 安全层要自己加：pre-tool-hook 拦命令、content scanner 防注入、
/secure审计。 - 会话树是 Pi 的隐藏神器，把对话变成可分支、可回退、可分享的版本历史。
参考资料
- Hacker News 讨论《Pi – A minimal terminal coding harness》：https://news.ycombinator.com/item?id=47143754
- Ricardo Ruiz（ruizrica2）《How I Turned Pi Into a Multi-Agent Coding Assistant》：https://medium.com/@ruizrica2/how-i-turned-pi-into-a-multi-agent-coding-assistant-cb1c2f1c8145
- jasonzhou1993《Pi agent 101 — How to extend and build your own harness》：https://x.com/jasonzhou1993/article/2074471761715077153
- Reddit r/PiCodingAgent：https://www.reddit.com/r/PiCodingAgent/
- Pi 官方
pi-multiagent/pi-crew包：https://pi.dev/packages/pi-multiagent ｜ https://pi.dev/packages/pi-crew
上一篇：03 · 扩展篇 ｜ 下一篇：05 · 本地模型 · MCP · 安全沙箱篇