Pi Agent 使用技巧

Pi（pi.dev）是 Earendil Inc. 出品的最小化、可扩展终端 AI 编程 agent（agent harness），npm 包 @earendil-works/pi-coding-agent。
核心理念：「改的是 harness，不是你的工作流」——它只给原语（extensions / skills / prompt templates / themes），sub-agents、plan mode、权限弹窗等都不内置，需要时让 Pi 自己造或装个包。

1. 首次连接

• 配置目录默认 ~/.pi/agent/，AGENTS.md、SYSTEM.md、keybindings.json、skills、prompt templates 都放这里。
• 首次启动按提示连接模型（API key 或 OAuth），支持 15+ 提供商：Anthropic / OpenAI / Google / Azure / Bedrock / Mistral / Groq / Cerebras / xAI / HF / Kimi / MiniMax / NVIDIA / OpenRouter / Ollama 等。

2. 模型使用技巧

技巧：

• 会话中途换模型：长上下文用便宜模型做检索/总结，关键步骤 Ctrl+L 切到强模型，无需重启会话。
• 自定义 provider / 模型：编辑 models.json，或写个 custom-provider extension 接私有网关 / 兼容端点。
• Ollama 本地模型：离线或隐私场景直接选 Ollama provider，零外发。

3. 会话是树，不是线

Pi 把会话存成树，所有分支共用一个文件。这是它最值得用的特性。

技巧：

• 试错不覆盖：拿不准的方向先 /fork，两条分支并行对比，留下效果更好的那条。
• 给关键节点打 label：在 /tree 里 Shift+L 编辑标签，Ctrl+L 过滤只看 labeled，长会话里快速定位。
• 分享排错过程：/share 生成 URL 直接贴给同事，比截图完整。

4. 上下文工程（Pi 的核心卖点）

Pi 系统提示极简，把上下文控制权交给你：

• AGENTS.md：启动时从 ~/.pi/agent/、各级父目录、当前目录加载，叠加生效。放项目约定、编码规范、目录说明。
• SYSTEM.md：按项目替换或追加默认系统提示，比 AGENTS.md 更底层。
• Skills：带指令 + 工具的能力包，按需加载，不会一上来撑爆 prompt cache。适合「用到才加载」的重型能力。
• Prompt templates：把常用 prompt 存成 Markdown，输入 /name 即展开。重复任务一键复用。
• Compaction：逼近上下文上限时自动总结旧消息。可写 extension 做主题式压缩 / 代码感知摘要 / 换模型总结。

技巧：

• 分层放 AGENTS.md：~/.pi/agent/AGENTS.md 放全局偏好（语言、风格），项目根放项目约定，子目录放模块局部规则，自动叠加。
• 用 SYSTEM.md 锁死角色：不希望被项目 AGENTS.md 稀释时，用 SYSTEM.md 直接替换默认提示。
• 重型能力做成 Skill：比如「数据库迁移审查」只在触发时加载，平时不占上下文。
• 自定义 compaction：默认总结可能丢代码细节，写个 code-aware compaction extension 保留关键 diff。

5. Steering：中途纠偏不打断

agent 跑起来时你仍能输入：

技巧：

• 跑偏立刻 steer：Enter 发「停，先看 X 文件」能及时止损，不必等它把错路走完。
• 补充需求用 follow-up：Alt+Enter 排「顺便加测试」，不打断当前节奏。
• Escape 随时中断取消整轮。

6. 让 Pi 改造自己（self-modify）

Pi 不是密封产品。缺命令 / 工具 / UI 调整，直接让 Pi 现场造：

1. 告诉它：「给我加一个 xxx 命令 / extension」
2. 它就地改自己的源码 / 配置
3. 你 /reload，继续用
4. 觉得通用就打包发 npm / git

这是「primitives, not features」的实操：sub-agents、plan mode、permission gate、path protection、SSH 执行、sandbox 等都有现成示例 extension 可抄。

7. 扩展与包

pi install npm:@foo/pi-tools          # 从 npm 装
pi install git:github.com/badlogic/pi-doom   # 从 git 装

• Extension：TypeScript 模块，可挂工具、命令、快捷键、事件、TUI（状态栏 / overlay / 自定义编辑器）。
• 包 = extensions + skills + prompts + themes 的打包，npm / git 分发。
• 浏览可用包：pi.dev/packages。

缺能力时的决策树：先问 Pi 造 → 造不出就装包 → 都没有就自己写 extension。

8. 四种模式与自动化

技巧：

• CI 里跑 Pi：pi -p "给 src/ 加单测并跑 vitest" --mode json，解析事件流拿结果。
• 编辑器集成：用 RPC 模式起一个常驻 Pi 进程，前端发指令、收流式输出。

9. MCP + Codemode

• MCP 内置：直接连 MCP server，无需额外桥（旧 MCP extension 仍兼容）。
• Codemode：让 agent 在 JavaScript sandbox 里组合工具调用，适合需要「先调 A 再用 A 的结果调 B」的复杂编排。

10. 常用快捷键速查

运行 /hotkeys 查看当前生效的全部快捷键；改 ~/.pi/agent/keybindings.json 后 /reload 生效。

11. 常用斜杠命令速查

12. 安全与最佳实践

• 工具以 Pi 进程权限运行，不沙箱化：别在含密钥 / 生产凭证的目录裸跑，或先写个 permission-gate extension / protected-paths。
• 跑不可信仓库 / extension：放容器里（见 containerization 文档），别直接在主机。
• 无人值守自动化：务必加确认流 extension，避免 agent 自主跑危险命令。
• background bash 用 tmux：Pi 不内置后台 shell，开 tmux 窗口给 agent，全程可观测、可直接交互，比黑盒后台更安全。
• sub-agents 用 tmux 或 extension：多开 Pi 实例各管一摊，比单进程塞子代理更可控。

13. 避坑清单