用例与示例

最后更新：2026-10-10

Pi 不是又一个黑盒聊天机器人，而是一套「可自我扩展」的 AI 编码代理工具集。它最擅长把「读代码 → 改代码 → 跑命令 → 看结果」这一串繁琐动作串成一条可审阅、可回退的工作流。下面用三个真实场景说明它怎么帮你干活。

场景一：让编码代理重构一个函数

你接手了一段用回调写的老代码，想把它升级成 async/await，但函数里嵌套很深，手动改容易漏。让 pi-coding-agent 来做：它先读懂上下文，再给出 diff，你确认后才落盘。

1. 进入目标仓库并启动代理：在仓库根目录运行 ./pi-test.sh，进入交互式编码代理。
2. 描述重构意图：用自然语言说明目标，例如「把 getUser 的回调写法改成 async/await，保持对外签名不变」。
3. 审阅代理给出的 diff：代理会列出所有将要修改的文件与差异，你可以逐处确认。
4. 让代理补测试并运行：要求它为新实现补充单元测试，并执行测试套件验证正确性。
5. 接受或回退：测试通过后接受变更；不满意可在 JSONL 会话树上回退到任意节点重来。

# 启动交互式编码代理
./pi-test.sh

# 在会话里直接说：
# “把 src/db.js 里的 getUser 从回调改成 async/await，
#  并补一个测试覆盖错误分支”

场景二：自动跑测试并修复失败

合并了一堆 PR 之后测试红了，但你不想一个个点开日志。把「跑测试」交给 Pi，它会在读到失败信息后定位用例、尝试修复、再跑一遍，直到绿了或明确说「这块我搞不定，需要你来看」。

# 让代理接管测试修复循环
./pi-test.sh
# “运行 npm test，把失败的用例修好，每修一处就重跑一次”

代理内部走的是同一条核心循环：准备上下文（测试输出）→ 请求模型 → 执行工具（改文件 / 跑命令）→ 写回结果 → 继续或停止。每一轮的输入输出都落进会话树，你随时能翻看它「当时为什么这么改」。

场景三：探索陌生仓库

刚 clone 一个不熟悉的 monorepo，不知道入口在哪、某个 API 是哪个包提供的。与其全文搜索，不如直接问代理：它受过仓库结构训练，能顺着 import 关系把调用链讲清楚。

./pi-test.sh
# “这个仓库里谁负责把请求转发给 LLM？
#  给我从 CLI 入口到 pi-ai 调用的完整链路”

它会结合 核心包 的分工（pi-ai 统一模型、pi-agent-core 运行时、pi-coding-agent 编码 CLI、pi-tui 终端 UI）来回答，而不是凭空编。想深入某个包的职责，直接跳去看对应文档即可。

还能怎么组合

• 安全加固安装：所有依赖用 npm install --ignore-scripts 安装，避免不可信的生命周期脚本，详见 运行与调试。
• 离线开发：用 MockModel 跑通工具与循环逻辑，不花真实 token，详见 快速上手。
• 自托管：整套工具集 MIT 开源，可私有化部署，不依赖任何厂商云服务。