第 20 章 · 工作流哲学与团队实践
本章目标：精读 pi 的设计哲学，理解"极简核心 + 按需加装"背后的取舍，并落地一套可直接复制的团队工作流：上下文文件规范、模板/技能/扩展组合、会话分享与推广检查单。
20.1 Philosophy 精读：六个"不做"
pi 的 README 用一整节声明了它刻意不内置的功能，每一条都有明确替代路径：
| 不内置 | 官方替代方案 |
|---|---|
| No MCP | 给 CLI 工具写 README 当技能用；或写一个提供 MCP 支持的扩展 |
| No sub-agents | 用 tmux 起多个 pi 实例；或用扩展自建；或装第三方包 |
| No permission popups | 跑在容器里；或用扩展按你的环境实现确认流 |
| No plan mode | 计划写成文件；或扩展实现；或装包 |
| No built-in to-dos | "它们会让模型困惑"——用 TODO.md 文件，或扩展实现 |
| No background bash | 用 tmux，获得完整可观测性与直接交互 |
这六条背后是同一条原则：凡是团队间分歧大的工作流偏好，都不该焊死在核心里。内置 = 替你做决定 = 不合用的功能变成负担。pi 选择把核心压到最小（模型 + 7 个工具 + 会话树），把"子代理怎么做、计划怎么管"留给扩展与包生态。
与"大而全"工具的对比思路
不是说不该有这些能力，而是说它们应该以可替换的组件存在。你不喜欢官方默认？装别人的包，或者让 pi 自己给你写一个扩展——这正是前几章 Extensions/Skills/Packages 的意义。
20.2 一套推荐的团队组合
基于前十九章的内容，给出一套经过验证的最小组合（全部落在仓库里随代码走）：
repo/
├── AGENTS.md # 项目约定（下一节详讲）
├── .pi/
│ ├── settings.json # 项目级设置（defaultProjectTrust 等由个人全局管）
│ ├── prompts/
│ │ └── review.md # /review 提示词模板
│ ├── skills/
│ │ └── deploy/SKILL.md # 部署流程技能
│ └── extensions/
│ └── guardrails.ts # 危险命令确认扩展分工逻辑：
- AGENTS.md 管"这个项目是什么、规矩是什么"——静态、人人相同；
- Prompt Templates 管高频指令的标准化——
/review、/release-notes这类动作统一措辞； - Skills 管多步流程知识——部署、发布这类有固定顺序的操作写成技能，模型按 SKILL.md 执行；
- Extensions 管行为约束与 UI——比如拦截
rm -rf类命令要求二次确认（自己实现的 permission popup）； - 个人差异（主题、思考级别、API key）放用户全局目录，不进仓库。
20.3 上下文文件工程：AGENTS.md 写法规范
加载规则回顾（详见 usage 文档）：启动时从 ~/.pi/agent/AGENTS.md（全局）→ 当前目录的各层父目录 → 当前目录逐层加载；同目录若有 AGENTS.override.md 则取代该目录的 AGENTS.md/CLAUDE.md。需要整体替换系统提示词时用 .pi/SYSTEM.md，只追加用 .pi/APPEND_SYSTEM.md。
一份好的项目 AGENTS.md 应包含四块内容（这也是官方建议的用途：项目约定、命令、安全规则、偏好）：
# 项目约定
## 构建与测试
- 包管理器用 pnpm，不要用 npm install
- 测试命令：pnpm test --filter <pkg>；全量测试超过 5 分钟，禁止主动全跑
## 代码风格
- 提交信息遵循 Conventional Commits
- TypeScript strict 模式，禁用 any 断言
## 安全红线
- 不要修改 .github/workflows/ 下任何文件
- 数据库迁移必须人工审查后才执行
- 密钥一律走环境变量，出现硬编码立即报告
## 已知坑
- src/legacy/ 下是待下线代码，不要重构它写作要诀：具体、可判定、少量高价值。"写好注释"这种模糊要求没有用；"禁止全量测试"这种硬约束最有用。上下文文件会占 token，保持在一屏到两屏内。
20.4 会话分享与团队学习
pi 把"怎么用 agent"本身变成可沉淀的知识：
# 交互内：导出为 HTML / 上传私有 GitHub gist 拿到可分享链接
/export review-demo.html
/share
# 命令行：把任意历史会话导出成网页归档
pi --export ~/.pi/agent/sessions/--path--/2024_xxx.jsonl out.html做开源的同学还可以用社区的 badlogic/pi-share-hf 把会话发布成 Hugging Face 数据集——真实开发会话对提示词、工具和评测的研究都很有价值。团队内部建议：每个疑难 bug 的攻坚会话用 /share 归档进 wiki，新人通过读"高手是怎么跟 agent 协作的"来上手，比读文档快得多。
20.5 团队落地检查单
从零在团队推行 pi 工作流的顺序清单：
- [ ] 统一版本：全员升级到同一 pi 版本（
pi update --self），避免行为漂移； - [ ] 全局底线：每人配置好 provider 凭据（
/login或环境变量），关闭遥测按需选择； - [ ] 仓库接入：提交
AGENTS.md（先从构建命令和安全红线两块写起）； - [ ] 标准动作模板化：把 code review、发版说明等高频指令做成
.pi/prompts/； - [ ] 流程技能化：部署/排障 SOP 写成 skills，让新手也能走专家路径；
- [ ] 行为护栏扩展化：危险命令确认、输出过滤等用 extensions 兜底；
- [ ] 隔离策略：约定什么任务必须容器里跑（第 19 章），CI 统一用
-na+ 显式参数； - [ ] 知识回流：定期
/share典型会话，迭代 AGENTS.md 的"已知坑"区。
20.6 本章小结
- 六个"不做"共享同一哲学：有争议的工作流决策不进核心，交给扩展/技能/包生态；
- 团队组合公式：AGENTS.md 管约定 + prompts 管高频指令 + skills 管流程 + extensions 管约束，个人偏好留在全局；
- AGENTS.md 要具体可判定，覆盖约定/命令/红线/已知坑四块，控制篇幅；
/export、/share、pi --export让协作过程本身可归档、可学习；- 推行顺序：版本统一 → 全局凭据 → 仓库接入 → 模板 → 技能 → 护栏 → 隔离 → 知识回流。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. pi 官方不内置 to-do 功能的理由是？
2. 同一目录下同时存在 AGENTS.md 和 AGENTS.override.md 时，pi 会？
3. 关于团队组合中各类资源的分工，正确的是？
4. 想把一次疑难 bug 的完整排查过程归档给团队学习，最合适的做法是？
🛠️ 动手实践
- 为你的团队仓库起草第一版
AGENTS.md：只写构建命令、三条安全红线和两条已知坑，控制在 30 行以内，然后验证 pi 是否真的遵守了其中每一条。 - 选一个团队里最常被问到的操作（如"如何本地起完整环境"），做成 prompt template 或 skill，请两位同事实测并收集反馈迭代一版。
- 完整走一遍第 20.5 节检查单的前 4 项，记录每一项在你的团队中遇到的实际阻力与解决办法。