Pi 能做什么: API、工具并发与 PR Review 实例

我想写个只接收 PR 的审查 Agent, 但还没弄清 Pi 能替我做多少, 尤其是多个工具同时调用的时候.

0x00 从能做的东西选入口

拿 Pi 做一个 PR reviewer, 宿主程序先获取 PR, 再给模型几个取证工具. 模型决定读哪个文件, Pi 负责执行工具、把结果放回对话、继续请求模型. 你负责定义“审查结束”以及 findings 的有效条件. 这已经能做成一个命令行工作流.

Pi 还提供比这个循环更低和更高的接口. 下面按想做的东西选, 不必一次装齐所有层.

想做什么	从哪个入口开始	还要自己写什么
给应用接不同厂商模型, 做聊天、摘要或流式展示	`pi-ai`: `createModels`, `streamSimple`, `completeSimple`	产品交互、数据和模型选择
日志诊断、知识库检索、PR 审查这样的领域 Agent	`pi-agent-core`: `Agent`, 自定义工具	业务工具、预算、结束条件
在自己的应用里嵌入代码助手	`pi-coding-agent`: `createAgentSession`	应用入口、鉴权、执行环境
给现有 Pi 加 `/review` 命令或一个公司内部工具	TypeScript extension: `registerCommand`, `registerTool`	命令处理和工具实现
做自己的 Web/IDE 界面	SDK 事件, 或 CLI 的 JSON/RPC 模式	UI、进程管理、事件转发
接 MCP 服务, 一次组合多次查询	MCP、`codemode`、`tool_search`	服务配置、输出筛选、权限边界

前三行对应 Pi 的三个包: pi-ai 管模型接口, pi-agent-core 管循环, pi-coding-agent 管代码助手会话与工具. 日志诊断、知识库检索是这些接口能支持的应用设计, 库并没有附送一套你的业务系统.

draw.io

图里每层都能单独作为入口. 小型 PR 工作流用中间层就够了; 想直接接上文件工具、持久会话与自动压缩, 再选右边的会话层.

这里固定 Pi 1.1.0, 源码为 f1b2e77. 旧地址 badlogic/pi-mono 已迁到 earendil-works/pi, 本文包名统一用 @earendil-works. 旧教程的包名和 getModel 调用, 不宜直接混进来; 编辑工具统一采用下文的 edits 数组格式.

0x01 API 调起来是什么样

只要模型回复时, 先注册 provider, 再从集合里取模型. 下例会把文本增量写到终端, 同时保留最终结构化响应. stream 本身是异步可迭代对象, 不用手动解析 SSE.

pi-ai 的接口文档也提供 completeSimple() 直接等待最终响应. 如果要让模型调用工具并继续推理, 再把 models.streamSimple.bind(models) 交给 new Agent({ streamFn, initialState: { model, systemPrompt, tools } }), 然后 await agent.prompt(input). 后面的 PR 示例就是这条调用链.

如果目标是“直接嵌入现成代码助手”, 会话 SDK会更短. 以下代码复用当前目录的配置和资源, 用内存会话避免保留这次对话, 结束时释放 session.

这些 API 沿用常见的 TypeScript 写法: async/await 表达执行, type 判别事件, TypeBox 同时描述参数类型和运行时 schema, AbortSignal 传递取消. streamFn 可以替换成测试模型; beforeToolCall、finishTurn 和上下文 hook 允许宿主控制循环.

代价也具体. AgentTool<any> 数组里的参数推导有时只剩 unknown, 后面的示例仍需用 Static<typeof schema> 局部断言. 裸 agent-core 没有自动压缩、持久任务队列和部署沙箱. 如果“现代”指有类型、能流式处理、能取消、能替换依赖, Pi 这几项都有. 做成服务时, 任务调度和执行边界仍要自己安排.

0x02 工具声明如何进入 Agent loop

让模型读文件需要两件东西: 一个描述“能传哪些参数”的 schema, 一段真正读文件的 execute. 在 PR 示例中, read_file 的实现是读取固定 Git SHA 的 blob, 所以模型传一个工作区路径也不能让它写文件.

工具的形状可以在 AgentTool 类型里对照:

content 是证据进入模型上下文的位置. 只把数据塞进 details, UI 可能能显示, 模型却拿不到. schema 也只能检查参数形状; “这个文件是否属于 PR”“这一行是否是新增行”仍是业务检查. 失败时抛异常或返回 isError: true, 才会形成失败的工具结果.

循环源码的主要顺序如下. agent.prompt() 已经包含这整个循环, 应用不需要再套一个自行执行工具的 while.

agent.subscribe() 能观察消息、轮次、工具开始/结束和增量事件. agent.abort() 请求取消, 但下游 I/O 要配合 signal; 已经写出去的文件不会因此自动恢复. 一个 Agent 持有一段可变对话, 两个独立 PR 应分别建立 Agent.

0x03 两个工具同时调用时发生什么

模型同轮提出 read_file(A) 和 read_file(B), 此时两个调用的参数都已经确定了. 如果它们读取固定 commit 的独立文件, Pi 1.1.0 默认允许并行. 宿主不用为每次调用手写 Promise.all.

默认调度实现会先逐个准备和校验调用, 再并行执行. 工具结束事件按实际完成顺序发出, 写回对话的结果则保持模型原调用顺序. 所以关联结果要看 toolCallId, 不要猜“第二个结束的就是第二个调用”.

executionMode: 'sequential' 会让整批回退到串行; 全局也有 toolExecution: 'sequential'. 它解决执行顺序, 但不能让已经生成的参数提前知道未来结果. “先找函数位置, 再读取那一行”必须等结果进入下一轮, 或写一个工具在内部完成先查后读.

自己写 read_many 这类批量工具时, 可以直接安排并发. 下面每批最多读 4 个, 每项保留成功或失败, 输出位置和输入对应. 它没有把结果截断成摘要, 所以大文件仍需分页.

这只是批量工具的实现片段; Pi 当前 loop 没有通用 maxConcurrency 参数. 若模型同轮还调用别的工具, 上面这个分批函数并不限制那些调用. 而 Promise.all 的一个成员失败, 也不会自动取消已经开始的其他成员.

0x04 只输入 PR 的完整例子

这次把入口定为 GitHub PR URL 或 owner/repo#number. 宿主用 gh 获取元数据, 在临时 bare 仓库里抓取引用并固定 head, 比较 merge-base 到 head. 首次给模型的是变更文件清单、base/head 和 PR 引用, 再按需调用三个工具:

工具	作用	宿主检查
`read_diff`	分页读取某个变更文件的 diff	必须在变更清单内
`read_file`	读取 base/head 的源码片段, 可追查 diff 外的消费者	路径合法, 读取固定 SHA
`finish_review`	提交结构化 findings	路径属于 PR, 行号是新增 HEAD 行, 单独提交

主例 review.ts 共 118 行. 为方便对照工具声明和执行, 完整放在下面. 与模型 API 有关的接线集中在 new Agent 和末尾 provider 初始化; acquire() 是这个工作流自己实现的 GitHub/Git 获取逻辑.

finish_review 先用 schema 检查字段, 再核对 finding 的 diff 坐标. 校验失败会作为工具错误返回模型, 通过后才保存报告. 这里限制在新增 HEAD 行, 因此删除行 LEFT 侧评论还不支持.

下载 package.json、package-lock.json、review.ts 和 check.ts 到同一个空目录. 使用支持直接运行 TypeScript 的 Node; 此例用 Node 26.10.0 跑过. Pi 包引擎下限是 Node 22.19+.

报告是包含 ref/base/head/findings 的 JSON, 工具进度写到 stderr. 主例不发布 GitHub 评论. check.ts验证并行峰值与结果顺序、串行回退、错误行号重试、PR 获取流程以及补丁应用. 它用预设模型输出和本地远端映射检查程序行为, 不衡量模型找 bug 的能力; 真实 GitHub 和模型服务的端到端调用尚未验证.

这个例子还设了 40 个变更文件、12 轮和 120 秒 Agent 运行预算. PR 获取阶段没有总超时, 大仓库完整历史 fetch 也可能较重. 空 findings 只能表示这次没有提交发现, 不能证明 PR 没有 bug.

0x05 上下文、文件写入和 diff 的边界

并行读十个文件可以减少等待, 但十份结果依然都要占上下文. 主例先给文件清单, 每次最多返回 120 行、16000 字符, 用 next 继续取证. 需要后续内容时再沿 next 读取, 控制每轮加入上下文的文本量.

需要长会话时, coding-agent 的 compaction会在接近窗口上限时建立摘要, 默认预留 16384 tokens, 保留近期约 20000 tokens. SessionManager 保存会话历史; 发给模型的上下文使用摘要和保留下来的近期消息. 本文的裸 core 主例没有这套自动压缩.

Tip

自己用 transformContext 裁剪时, 保留 toolCall/toolResult 配对和有效的工具声明. 1.1.0 的 system 消息可承载工具集合变化, 简单 messages.slice(-N) 可能把它们删掉. 更大输出可以放宿主 artifact, 只把摘要、SHA、路径、行号和可重读标识放入 content; 这是扩展设计, 主例未实现 artifact 服务.

修复阶段若要复用 Pi 的文件工具, 当前 edit接收 edits 数组. 每一项都在原文件上匹配, 要求唯一且不重叠; 第二项不会基于第一项的新内容继续匹配.

内置 read 支持 offset/limit, 默认最多 2000 行或 50 KiB; write 创建或覆盖文件. edit/write 使用同文件变更队列, 同一目标排队, 不同文件可并行. 这是进程内协调, 不防另一个进程改同一文件, 也不是仓库级事务.

要把变更写成可传递的 diff, 可以保存 unified patch, 再在以 base 为内容的工作区检查并应用. 下面 BASE_SHA 和 HEAD_SHA 要替换成实际 SHA; 应用会修改该工作区, 不应与同文件另一写入并发.

PR findings、展示用 diff 和可应用 patch 是三种不同输出. read_diff 页左侧的数字只是显示行号, 真正评论坐标来自 hunk 的 HEAD 行号. 后续若把报告发布到 PR, 也应先确认 PR head 仍与报告记录一致.

0x06 给现有 Pi 加能力

如果只是想在 Pi 终端里加一个命令, 不需要重写 Agent. Extension是直接加载的 TypeScript 模块, 模块导出的工厂函数收到 ExtensionAPI, 可以通过它注册命令和工具. 保存下面代码为 hello.ts, 用 pi --extension ./hello.ts 启动, 再输入 /hello.

同一 API 还可 registerTool、on、registerProvider、registerMcpServer. 长期存在的进程或连接放到 session_start 或实际调用时创建, 在 session_shutdown 清理. 扩展运行在 Pi 进程中, 使用宿主的操作系统权限.

当前 CLI 随带 MCP、codemode 和 tool_search 内置扩展. codemode 允许模型用 JS 组合工具调用, 先筛选大结果再输出给模型; MCP 工具可直接暴露, 也可通过 codemode 或延迟发现接入. SDK 不自动加载这三项 CLI 扩展, 要按 SDK 文档在 ResourceLoader 注册、启用工具并绑定扩展生命周期.

Pi 上游有意不内置子代理和 plan mode, 可以由扩展添加. 如果你想直接拿到调试器、LSP、reviewer 和子代理协作, 可以接着看 oh-my-pi 的功能与原生调试.

这个例子会检查 finding 的文件路径和新增行号. 它指出的问题是否成立, 还要结合对应代码复核.