Pi Agent 源码级教程
F09

五种接口 —— 从终端到 SDK 的五个入口

2,351 字 · 含 36 行代码 · 约 16 分钟

前面的章节都在讲「Pi 内部怎么配」。这一章换视角: 外面的人怎么把 Pi 接进去。

同一样东西有五个入口,它们共用同一套 agent、会话、资源和工具, 只是「输入怎么进、输出怎么出、进程活多久」不同。

三个问题:

  1. 我没加任何参数,为什么 Pi 突然不进交互界面了?
  2. --mode json 输出的 agent_end 之后为什么还会有东西?
  3. RPC 的 prompt 返回 success: true,是「跑完了」还是「收到了」?

一、五个入口的分工

cli-integration.md:11-16 有一张四行的表,加上 SDK 就是五个:

入口 界面 生命周期 什么时候用
交互 终端 TUI 你退出为止 人在干活
Print stdout 上最终文本 一次调用 脚本要一句话结果
JSON stdout 上 JSONL 事件 一次调用 进程要结构化进度
RPC JSONL 命令 + 响应 + 事件 长期驻留 进程要双向控制
SDK TypeScript 方法调用 宿主决定 Node / Bun 进程内嵌

前四个都被 --mode 或 -p 选中,SDK 不是 CLI 模式 (cli-integration.md:7),它把 agent 直接塞进你的进程。


二、你没选模式时,谁替你选了

resolveAppMode(main.ts:112-123)就四行逻辑,值得背下来:

条件 结果
--mode rpc rpc
--mode json json
-p / --print,或 stdin 不是 TTY,或 stdout 不是 TTY print
其它 interactive

第三条是很多人第一次被坑的地方:管道或重定向会自动切到 print 模式 (cli-integration.md:32)。所以

powershell
pi "看看这个项目" > out.txt

不会开会话,也不会等你输入。这个设计是为了让 pi "..." | jq 这类管道能用, 代价是「我想存个日志但还想交互」这件事做不到——那要先重定向 stdout, 就没有 TUI 了。

--print 后面跟的提示词还有一个细节(cli/args.ts:177-180): 下一个参数只要不以 - 开头(或是以 --- 开头),就被当作提示词吃掉。 所以 -p 后面紧跟的值别写成 -something 的形式,会被当成选项。


三、Print:只看最后一句话

powershell
pi --print "用三句话总结这个仓库"

cli-integration.md:28-30 定了三条退出码规则,写脚本必看:

情况 stdout stderr 退出码
正常 最终文本 — 0
error / aborted 结束 可能有部分 错误 非零
撞到输出 token 上限(length) 有部分文本 警告 非零

第三条最阴:模型明明说了话,stdout 也有内容,但退出码不是 0。 用 if ($LASTEXITCODE -ne 0) 判断成败时,别把「有输出」当成「成功」。

中间事件在 print 模式下完全不暴露(:28)。想看过程必须换 JSON 模式。


四、JSON:一次运行的事件流

powershell
pi --mode json "审查这个仓库" > events.jsonl

第一条记录是会话头(json.md:25-27),之后是事件:

json
{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}{"type":"agent_start"}{"type":"turn_start"}{"type":"message_start","message":{"role":"user",...}}{"type":"message_update","assistantMessageEvent":{"type":"text_delta",...}}{"type":"message_end","message":{"role":"assistant",...}}{"type":"turn_end","message":{...},"toolResults":[]}{"type":"agent_end","messages":[...],"willRetry":false}{"type":"agent_settled","aborted":false}

4.1 agent_end 不是终点

顺序表里 agent_end 后面还有 agent_settled,原因写在 json.md:48: agent_end 只结束一次底层 agent run,后面还可能有自动重试、 溢出恢复、压缩重试、steering、follow-up。

真正「Pi 不会再自己动了」的信号是 agent_settled(:56)。 所有外部集成都该等它,而不是 agent_end。

4.2 流式消息必须自己拼

message_update 里没有累积快照(json.md:72), 只有 assistantMessageEvent 里的增量。要拼一条完整消息,得监听四种 *_delta, 再用三类 *_end 的权威内容替换(:93):

阶段 该做什么
text_delta / thinking_delta 追加到缓冲区,用于实时显示
toolcall_delta 追加序列化后的参数片段
text_end / thinking_end 用 content 覆盖缓冲区(权威)
toolcall_end 用完整 ToolCall 覆盖
message_end 整条消息换成 message(最终裁判)

4.3 别用 readline

json.md:15-17 专门警告:JSON 里可以有 U+2028 / U+2029, 它们是合法的字符串内容,而 Node 的 readline 会把它们当行尾。 结果是一条 JSON 被拆成两条,解析失败。

正确做法:按字节流读,只认 \n 切分,顺手去掉前面的 \r。 rpc.md:99-130 的 Python 客户端用的是 subprocess.stdout.readline()(二进制读), 恰好符合这个要求。

4.4 JSON 模式的成败不看退出码

cli-integration.md:46:失败或被中止的响应会出现在事件流里,但本身不会让退出码非零。 只有调用本身抛异常才非零。

所以要判断这一跑成不成,得读 message_end 的 stopReason—— 这是 JSON 和 print 两个模式最大的行为差异,很容易写错。


五、RPC:让别的语言来控制 Pi

powershell
pi --mode rpc --no-session

四种记录(rpc.md:24-31):stdin 的命令、stdout 的响应、 stdout 的会话事件、双向的扩展 UI 记录。

命令带可选 id,响应原样带回(rpc.md:37-42)。 处理是异步的,所以必须按 id 关联,不能按顺序。

5.1 success: true 只代表「收到了」

json
{"id":"req-2","type":"prompt","message":"审查这个仓库"}{"id":"req-2","type":"response","command":"prompt","success":true, "data":{"disposition":"started"}}

rpc.md:60-69 说得很清楚:成功的 prompt 响应意味着已接受、已排队或已处理, 不代表模型干完了。disposition 是 "handled" 时根本没起 run, 这时候等 agent_settled 会永远等下去。

5.2 两个必守的纪律

  • 先订阅再发 prompt。否则极快的完成会在你挂上监听器之前就跑完 (rpc.md:71)。RpcClient.promptAndWait() 内部就是这么做的。
  • 持续读 stdout。虽然 Pi 尊重 backpressure,但你不读,管道缓冲满了就卡住它 (rpc.md:56)。日志写 stderr,不要把 stderr 当协议数据解析(:89)。

关闭子进程的方式是关它的 stdin(:93),Pi 会先销毁运行时再退出。

5.3 什么时候该用 RPC 而不是 SDK

rpc.md:7-10 给了判断:

你的情况 选
Node / Bun,要完整 API SDK
别的语言、要进程隔离、IDE 集成、自定义客户端 RPC

一句话:能不能接受在同一个进程里跑 agent。能,就用 SDK;不能,就用 RPC。


六、SDK:把 agent 当库调

最小可用版本(examples/sdk/01-minimal.ts,全文 27 行):

ts
import { createAgentSession } from "@earendil-works/pi-coding-agent";const { session } = await createAgentSession();try {  session.subscribe((event) => {    if (event.type === "message_update"      && event.assistantMessageEvent.type === "text_delta") {      process.stdout.write(event.assistantMessageEvent.delta);    }  });  await session.prompt("What files are in the current directory?");} finally {  session.dispose();}

createAgentSession() 不给参数时,用的是当前工作目录、自动发现的资源、 已存的设置和已配好的凭据(sdk.md:20)——和命令行一模一样。 docs/sdk.md:7-18 那版更短,省掉了订阅。

6.1 五个可换的边界

默认工厂会造 ModelRuntime、文件版 SettingsManager、持久化 SessionManager、 DefaultResourceLoader 和默认工具集。每一层都能换(sdk.md:100-108):

参数 换掉什么
modelRuntime / model / thinkingLevel / scopedModels 模型访问与选择
settingsManager 设置来源(可以纯内存)
sessionManager 会话存储(SessionManager.inMemory())
resourceLoader 扩展、技能、模板、主题、上下文文件
tools / noTools / excludeTools / customTools 工具集

宿主不需要会话文件时,用内存管理器(sdk.md:47-49):

ts
const { session } = await createAgentSession({  sessionManager: SessionManager.inMemory(),});

6.2 三件容易做错的事

第一件:session.dispose() 必须调。 它会中止在跑的工作、 让扩展上下文失效、断开 agent、移除监听(sdk.md:56)。 不调就是内存泄漏加悬挂的事件回调。

第二件:流式期间发 prompt 必须说明来意。 sdk.md:66-68: 正在流式时再 prompt() 而不指定「引导当前 run」还是「排在它后面」, 会被拒绝而不是猜。steer() 和 followUp() 是这两个行为的显式版本。

第三件:换会话之后订阅会失效。 AgentSessionRuntime 的 newSession() / switchSession() / fork() 会替换掉活动的 AgentSession (sdk.md:58-60),旧订阅属于旧对象,必须重新绑定。

6.3 SDK 不带内置扩展

这是一条和 CLI 最大的差异(sdk.md:116):CLI 把 codemode、tool_search、 MCP 当内置扩展加载,SDK 不加载。要的话得自己塞进 DefaultResourceLoader 的 extensionFactories:

扩展 工厂
codemode createCodemodeExtension()
tool_search createToolSearchExtension()
MCP createMcpExtension()

而且 codemode / tool_search 注册时是未激活状态, 要靠 defaultTools: ["+codemode"] 打开,或者让 MCP 扩展按 exposure 激活它们。 MCP 扩展在 session_start 里连服务器,所以必须先 session.bindExtensions()。

这一点和 F07 呼应:你在 CLI 里理所当然的那套,在 SDK 里要自己搭。


七、五个入口对照表

维度 交互 Print JSON RPC SDK
输入 键盘 启动参数 启动参数 stdin 命令 方法调用
输出 TUI 最终文本 JSONL 事件 JSONL 响应+事件 回调事件
中途可交互 是 否 否 是 是
完成信号 — 进程退出 agent_settled agent_settled agent_settled
成败看 — 退出码 stopReason success + 事件 stopReason
内置扩展 有 有 有 有 无,要自己加

八、自己动手验证

实验 1:验证「管道自动切 print」。

powershell
pi "说一句话" > out.txtGet-Content out.txt

你会直接拿到最终文本,没有任何 TUI。再去掉重定向跑一次, 进的是交互界面。这一条把 resolveAppMode 的第三条规则变成体感。

实验 2:数一遍 agent_settled 之前有几个事件。

powershell
pi --mode json "列出当前目录的文件" > t.jsonl

用 F03 那个 tools.mjs 的写法读 t.jsonl,打印出所有 type, 看 agent_end 与 agent_settled 之间还夹着什么。 如果这一跑触发了重试,你会额外看到 auto_retry_start / auto_retry_end。

实验 3:跑通 SDK 最小例子。

把 01-minimal.ts 存成文件,用 tsx 之类直接跑,看它输出的文件列表 和你 pi -p "列出当前目录的文件" 的结果是否一致。 一致说明两件事:默认参数确实共用一套发现逻辑;SDK 和 CLI 不是两套实现。

改一处试试

在实验 2 的命令后面加 --mode rpc,用 rpc.md:101-130 那段 Python 当客户端, 把 ["pi","--mode","rpc","--no-session"] 换成本机可执行路径。 跑通之后把 --no-session 去掉,再用 pi --resume 看会话是否被记下来—— RPC 和交互模式共用同一个会话存储。


九、工程暗坑

坑一:拿 agent_end 当完成信号。 后面还有重试、压缩恢复、队列。一律等 agent_settled。

坑二:JSON 模式靠退出码判断成败。 失败响应不会让退出码非零。读 message_end 的 stopReason。

坑三:Print 模式看到有输出就当成功。 撞输出上限时 stdout 有内容、stderr 有警告、退出码非零。三条一起看。

坑四:用 readline 读 JSONL。 U+2028 / U+2029 会把它切坏。按字节读、只认 \n。

坑五:RPC 里发了 prompt 就开始等 agent_settled。 先看 disposition,"handled" 表示根本没起 run,等下去会挂住。

坑六:SDK 里以为 codemode / MCP 还在。 SDK 不加载内置扩展。要用就自己塞扩展工厂,并记得 bindExtensions()。

坑七:忘了 session.dispose()。 在 Node 里表现为进程不退出、监听器越积越多。放在 finally 里。


十、本章源码索引

文件 行数 本章用到的位置
packages/coding-agent/src/main.ts 1,011 resolveAppMode 的四条判定
packages/coding-agent/src/cli/args.ts 481 -p/--print 与 --mode 的解析
packages/coding-agent/src/cli/initial-message.ts 44 启动提示词的处理
packages/coding-agent/examples/sdk/01-minimal.ts 27 SDK 最小闭环
packages/coding-agent/docs/cli-integration.md 107 四模式对照与退出码规则
packages/coding-agent/docs/json.md 227 事件表与流式重建规则
packages/coding-agent/docs/rpc.md 194 四类记录、id 关联、Python 客户端
packages/coding-agent/docs/sdk.md 148 五个边界、事件、内置扩展差异
packages/coding-agent/docs/usage.md 95 交互模式的键位与斜杠命令

十一、下一章

接口讲完,最后一章落到「上线前该检查什么」: Pi 在哪些地方不会问你、哪些路径默认就能写、哪些环境变量会改变行为。 F10 给三张清单——信任边界、可写边界、环境边界, 以及一份上线前的自检表。

真要把它装成一个对外服务,附录 C 把 §六 这条路走完了: 四十行 HTTP + SSE 服务、前端读流、以及四个实跑过的上线坑。 入口选型是你在这里定的,服务形态在那里落地。