五种接口 —— 从终端到 SDK 的五个入口
前面的章节都在讲「Pi 内部怎么配」。这一章换视角: 外面的人怎么把 Pi 接进去。
同一样东西有五个入口,它们共用同一套 agent、会话、资源和工具, 只是「输入怎么进、输出怎么出、进程活多久」不同。
三个问题:
- 我没加任何参数,为什么 Pi 突然不进交互界面了?
--mode json输出的agent_end之后为什么还会有东西?- RPC 的
prompt返回success: true,是「跑完了」还是「收到了」?
一、五个入口的分工
cli-integration.md:11-16 有一张四行的表,加上 SDK 就是五个:
| 入口 | 界面 | 生命周期 | 什么时候用 |
|---|---|---|---|
| 交互 | 终端 TUI | 你退出为止 | 人在干活 |
| 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 |
|
| 其它 | interactive |
第三条是很多人第一次被坑的地方:管道或重定向会自动切到 print 模式
(cli-integration.md:32)。所以
pi "看看这个项目" > out.txt不会开会话,也不会等你输入。这个设计是为了让 pi "..." | jq 这类管道能用,
代价是「我想存个日志但还想交互」这件事做不到——那要先重定向 stdout,
就没有 TUI 了。
--print 后面跟的提示词还有一个细节(cli/args.ts:177-180):
下一个参数只要不以 - 开头(或是以 --- 开头),就被当作提示词吃掉。
所以 -p 后面紧跟的值别写成 -something 的形式,会被当成选项。
三、Print:只看最后一句话
pi --print "用三句话总结这个仓库"cli-integration.md:28-30 定了三条退出码规则,写脚本必看:
| 情况 | stdout | stderr | 退出码 |
|---|---|---|---|
| 正常 | 最终文本 | — | 0 |
error / aborted 结束 |
可能有部分 | 错误 | 非零 |
撞到输出 token 上限(length) |
有部分文本 | 警告 | 非零 |
第三条最阴:模型明明说了话,stdout 也有内容,但退出码不是 0。
用 if ($LASTEXITCODE -ne 0) 判断成败时,别把「有输出」当成「成功」。
中间事件在 print 模式下完全不暴露(:28)。想看过程必须换 JSON 模式。
四、JSON:一次运行的事件流
pi --mode json "审查这个仓库" > events.jsonl第一条记录是会话头(json.md:25-27),之后是事件:
{"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
pi --mode rpc --no-session四种记录(rpc.md:24-31):stdin 的命令、stdout 的响应、
stdout 的会话事件、双向的扩展 UI 记录。
命令带可选 id,响应原样带回(rpc.md:37-42)。
处理是异步的,所以必须按 id 关联,不能按顺序。
5.1 success: true 只代表「收到了」
{"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 行):
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):
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 里要自己搭。
七、五个入口对照表
| 维度 | 交互 | JSON | RPC | SDK | |
|---|---|---|---|---|---|
| 输入 | 键盘 | 启动参数 | 启动参数 | stdin 命令 | 方法调用 |
| 输出 | TUI | 最终文本 | JSONL 事件 | JSONL 响应+事件 | 回调事件 |
| 中途可交互 | 是 | 否 | 否 | 是 | 是 |
| 完成信号 | — | 进程退出 | agent_settled |
agent_settled |
agent_settled |
| 成败看 | — | 退出码 | stopReason |
success + 事件 |
stopReason |
| 内置扩展 | 有 | 有 | 有 | 有 | 无,要自己加 |
八、自己动手验证
实验 1:验证「管道自动切 print」。
pi "说一句话" > out.txtGet-Content out.txt你会直接拿到最终文本,没有任何 TUI。再去掉重定向跑一次,
进的是交互界面。这一条把 resolveAppMode 的第三条规则变成体感。
实验 2:数一遍 agent_settled 之前有几个事件。
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 服务、前端读流、以及四个实跑过的上线坑。 入口选型是你在这里定的,服务形态在那里落地。