RPC
通过 JSONL 驱动一个运行中的 Pi 子进程——四种记录族、按 ID 相互关联的命令、一个扩展 UI 子协议,以及关闭约定。
你想从一个编辑器插件、从一个 Python 服务,或者从一个 IDE 驱动 Pi——但你不想在另一门语言里重新实现 SDK 的事件类型,也不想让智能体住在你的进程里,因为一次糟糕的工具调用就能把你的服务器一起带走。
RPC 是这个递进中的第四个界面,也是唯一保住隔离性的那一个。本章讲的是协议:每个方向上流动着什么、你如何做相互关联,以及那个几乎没人意识到它存在的子协议。
RPC 是用来做什么的
rpc.md 直接给出了用例——“与语言无关的集成、进程隔离、IDE,以及自定义用户界面”——还有一张值得在这里复现的对比表,因为它是全部文档里关于 SDK/RPC 权衡最清晰的一段陈述:
| 界面 | 进程边界 | 控制模型 | 最适合 |
|---|---|---|---|
| SDK | 进程内 | 直接的 TypeScript 方法与事件 | 想要完整 API 访问的 Node.js 或 Bun 宿主 |
| RPC | 子进程 | JSONL 命令、响应与事件 | 其他语言、隔离的进程、IDE,或自定义客户端 |
拿它和第 33 章对比,那一章里你只能读。再拿它和第 34 章对比,那一章里一切都是方法调用。在四个界面中,RPC 是唯一一个你决定智能体的生命期、而智能体从不决定你的生命期的那个。
四种记录族
rpc.md 在这件事上很精确,而这种精确是重要的:
| 方向 | 记录 | 用途 |
|---|---|---|
| stdin | 命令 | 让 Pi 发出提示词、检查状态、更改配置,或管理会话 |
| stdout | 响应 | 报告某一条命令是否成功,并返回该命令的数据 |
| stdout | 会话事件 | 流式报告运行、消息、工具、队列、压缩与重试活动 |
| 双向 | 扩展 UI 记录 | 在 Pi 与客户端之间转发受支持的扩展交互 |
最后一行才是要注意的那一行。扩展 UI 记录在两个方向上流动,这使它成为一个叠加在那三个普通记录族之上的子协议。
启动这个进程:
pi --mode rpc --no-session
普通的 CLI 选项依然适用——--provider、--model、--name、--no-session、--session-dir。有一条限制:“RPC 模式拒绝 @file 提示词参数。请改用 prompt 命令发送提示词。”
分帧方式来自 rpc.md,而不是一种假设:严格的 JSONL,每条记录一个完整的 JSON 对象,以 LF 结尾。命令进 stdin,Pi 说的一切进 stdout。
sequenceDiagram
participant C as 控制器
participant P as Pi RPC 进程
C->>P: 带 id 的 prompt 命令,一行
P-->>C: response,disposition
P-->>C: 会话事件,不带命令 id
P-->>C: agent_end
P-->>C: agent_settled
C->>P: 下一条命令,或者关闭 stdin
接受与完成是不同的记录,而它们之间的间隔就是本章的全部。
第四种记录族不按顺序到达,并且会阻塞:
sequenceDiagram
participant X as 扩展
participant P as Pi
participant C as 控制器
X->>P: ctx.ui.confirm()
P-->>C: extension_ui_request,带一个 id
C-->>P: extension_ui_response,同一个 id
P-->>X: 对话框解析
在那条箭头悬而未决期间,Pi 在等控制器。忽略它,这次运行就会停滞——如果该请求带了一个 timeout,就直到那个超时到期为止,此时智能体一侧会以一个默认值自动解析。rpc-extension-ui.md 在这件事上是有条件的:自动解析是在提供了超时的情况下发生的事,所以一个没有提供超时的请求可以无限期地等下去。对于一个可能很慢或者可能缺席的控制器,请自己提供超时,而不要假定它存在。
相互关联:ID,以及一个例外
每一条命令都接受一个可选的字符串 id,而与之匹配的响应会重复它:
{"id":"req-1","type":"get_state"}
{"id":"req-1","type":"response","command":"get_state","success":true,"data":{"...":"..."}}
这条指引没有歧义:“只要可能同时有多条命令未完成,就使用唯一的 ID。命令处理是异步的,所以客户端应当按 ID 而不是按响应顺序来做相互关联。”
会话事件通常不带命令 id,因为它们描述的是会话活动,而不是一次请求。例外是 bash_execution_update:“当发起它的那条 bash 命令有一个 ID 时,它的输出事件会重复那个 ID。”
还有子协议的第三条规则:“一条 extension_ui_response 使用它的 extension_ui_request 所提供的那个 ID。它不会产生一条普通的命令响应。”
三个 ID 命名空间,三种行为。一个把它们混在一起的客户端,要么挂住,要么重复计数。
那条会绊住所有人的规则
{"id":"req-2","type":"prompt","message":"Review this repository"}
{"id":"req-2","type":"response","command":"prompt","success":true,"data":{"disposition":"started"}}
rpc.md:“一条成功的 prompt 响应意味着该提示词被接受了、排队了或被处理了。它并不意味着模型工作已完成。”
data.disposition 是 "started"、"queued" 或 "handled"。而陷阱在于:“如果它是 "handled",那么这条提示词没有启动任何运行,所以不要去等 agent_settled。”
来自 rpc-commands.md,prompt 还有一条值得读两遍的规则:如果智能体已经在流式输出,而你发送 prompt 时没有带 streamingBehavior,该命令会返回一个错误。 取值是 "steer"(在当前助手轮次执行完它的工具调用之后、在下一次 LLM 调用之前交付)和 "followUp"(只有在智能体停下来时才交付)。像 /mycommand 这样的扩展命令是例外——它们"即使在流式输出期间也会立即执行,“因为它们通过 pi.sendMessage() 管理自己的模型交互。
一个你真正能跑的客户端
rpc.md 附带了一个 Python 示例,它短到足以成为本章的核心:
import json
import subprocess
process = subprocess.Popen(
["pi", "--mode", "rpc", "--no-session"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
)
assert process.stdin is not None
assert process.stdout is not None
command = {"id": "prompt-1", "type": "prompt", "message": "Hello"}
process.stdin.write(json.dumps(command).encode("utf-8") + b"\n")
process.stdin.flush()
while line := process.stdout.readline():
record = json.loads(line)
if record.get("type") == "message_update":
update = record["assistantMessageEvent"]
if update["type"] == "text_delta":
print(update["delta"], end="", flush=True)
elif record.get("type") == "agent_settled":
print()
break
process.stdin.close()
process.wait()
有两点要注意。它等的是 agent_settled,不是 agent_end。而关闭 stdin 就是你关机的方式——rpc.md 说:“关闭子进程的 stdin 以请求一次有序关闭。Pi 会在退出前处置活动运行时。”
对于 TypeScript,rpc.md 和 cli-integration.md 都指向 @earendil-works/pi-coding-agent 里的 RpcClient,它"启动一个 Pi RPC 子进程、为请求做相互关联、暴露带类型的命令方法,并把事件交付给监听器。“它修掉了一个有文档记载的竞态:"RpcClient.promptAndWait() 会在发送提示词之前安装它的事件监听器,避免与快速完成之间发生竞态。”
命令面
rpc-commands.md 是一份很长的参考资料,所以这里只讲形状。分组方式与该文档的分组一致:
发提示词——prompt、steer、follow_up、abort、clear_queue、new_session。clear_queue 会返回排队的文本,好让你能把它恢复到你的编辑器里;有文档记载的做法是在 abort 之前发送 clear_queue,“然后把返回的文本恢复到客户端编辑器里,“因为当排队的消息仍留在会话中时 abort 会继续它们。这就是你实现终端 Escape 行为的方式。
状态——get_state(model、thinkingLevel、isStreaming、isCompacting、steeringMode、followUpMode、sessionFile、sessionId、sessionName、autoCompactionEnabled、messageCount、pendingMessageCount)、get_messages。
模型与思考——set_model、cycle_model、get_available_models、set_thinking_level、cycle_thinking_level、get_available_thinking_levels。级别是 off、minimal、low、medium、high、xhigh、max,其中 xhigh 和 max 只有在所选模型支持它们时才暴露。
队列模式——set_steering_mode 与 set_follow_up_mode,各取 all 或 one-at-a-time,两者的默认值都是 one-at-a-time。
压缩与重试——compact(可选地带 customInstructions)、set_auto_compaction、set_auto_retry、abort_retry。
Bash——bash 与 abort_bash。有一个有文档记载的细微之处会改变你对它的推理方式:bash 输出是在下一次提示词时才到达模型,而不是立刻。rpc-commands.md 说内部的 BashExecutionMessage 在发送下一条 prompt 命令时变成一个 UserMessage,并且"多条 bash 命令可以在一次提示词之前运行;Pi 会包含每一个没有设置 excludeFromContext 的输出。”
会话——get_session_stats、export_html、switch_session、fork、clone、get_fork_messages、get_entries、get_tree、get_last_assistant_text、set_session_name。
get_entries 值得一提,因为它解决了一个真实的问题:把你已经见过的最后一个 entry id 作为 since 传入,“以便只拿到严格在它之后的条目,即使客户端重启过也一样。“会话是只追加的,且 id 稳定,所以一个 entry id 就是一个耐用的游标。响应还带有 leafId,“这样一个客户端就能在一个来回之内判断活动分支是否移动过。”
可发现的命令——get_commands 列出扩展命令、提示词模板和技能,每一项都带 name、description、source 和 sourceInfo。有一个注意事项:“内置的 TUI 命令(/settings、/hotkeys 等)不包含在内。它们只在交互模式下被处理,如果通过 prompt 发送则不会执行。”
错误,以及成功并不意味着什么
一条失败的命令返回一条 success: false 的响应:
{"id":"req-3","type":"response","command":"set_model","success":false,"error":"Model not found: invalid/model"}
畸形的 JSON 会产生一条 parse 响应,它不带请求 id——command 是 "parse"。所以你的关联表需要为那些不属于任何人的响应留一个位置。
错误那一节里最重要的一句话:“一条成功响应只覆盖命令处理。提示词被接受之后的 provider 失败和中止,会出现在消息与事件流中。“响应是关于命令的,不是关于模型的。
还有 rpc.md 明确列出的客户端义务:启动失败、意外的退出、stderr 诊断、取消,以及你自己的截止时间。“不要把 stderr 当作协议数据来解析。”
扩展 UI 子协议
这是改变一个 RPC 客户端能成为什么的那一部分。rpc-extension-ui.md 对它做了完整记录,它分成两类:
对话框方法——select、confirm、input、editor——在 stdout 上发出一个 extension_ui_request,并阻塞直到你发回一个带匹配 id 的 extension_ui_response。
发后即忘的方法——notify、setStatus、setWidget、setTitle、set_editor_text——发出一个请求,但不指望任何回应。“客户端可以显示这些信息,也可以忽略它。”
所以一个在 RPC 下调用 ctx.ui.confirm() 的扩展是在等你,而一个只回答 prompt 命令的客户端还不算一个 UI。
一次完整的交换:
{"type":"extension_ui_request","id":"uuid-2","method":"confirm","title":"Clear session?","message":"All messages will be lost.","timeout":5000}
{"type":"extension_ui_response","id":"uuid-2","confirmed":true}
取消对每一个对话框都是同一个形状:{"type":"extension_ui_response","id":"uuid-3","cancelled":true},它给 select/input/editor 交付 undefined,给 confirm 交付 false。
降级清单
rpc-extension-ui.md 枚举了哪些东西不能用,而它是终端那一章的梯子的镜像:
custom()返回undefined。onTerminalInput()返回一个什么都不做的 unsubscribe。setWorkingMessage()、setWorkingVisible()、setWorkingIndicator()、setHiddenThinkingLabel()、setFooter()、setHeader()、addAutocompleteProvider()、setEditorComponent()、setToolsExpanded()都是空操作。getEditorText()返回"",getEditorComponent()返回undefined,getToolsExpanded()返回false。pasteToEditor()委托给setEditorText(),没有终端粘贴处理。getAllThemes()返回[],getTheme()返回undefined。setTheme()返回{ success: false, error: "Theme switching not supported in RPC mode" }。
把前两条和 hasUI 放在一起读:就扩展而言,一个实现了对话框子协议的 RPC 客户端是一个真正的 UI。在那里 ctx.mode 是 "rpc",ctx.hasUI 是 true。所以一个只用 hasUI 做守卫的扩展会在 RPC 下运行——然后走上一条静悄悄地什么也不做的 custom() 路径。
与前一章对比
SDK 会话是一次函数调用:session.prompt(...) 在运行结束时返回,而你的 TypeScript 编译器知道一切东西的形状。RPC 是一次消息交换:prompt 命令在该提示词被接受的那一刻就返回,而一切有意思的事情都发生在你订阅的事件里。
那一个区别造就了本章的纪律。在进程内,你等一个 promise。跨进程,你等一个事件,而你必须选对那一个——agent_settled,不是 agent_end——同时还要按 ID 做相互关联、尊重背压,并处理一个可能毫无警告就退出的子进程。
你由此换回三样东西:任何语言、一个你可以杀掉的隔离进程,以及一个让 RPC 成为构建客户端的正当目标的 UI 子协议。你付出的是分帧、相互关联和生命期。
运行了什么
examples/ch35-rpc/ 用一个手写的 JSONL 客户端驱动 --mode rpc 下交付的二进制文件,该客户端只按 LF 切分,正如本章所要求的:
- 响应会重复命令
id,而两条未完成的命令是按 ID 而不是按顺序匹配的; - 一条成功的
prompt响应意味着被接受了,而不是完成了:data.disposition是"started",而它在本次运行的第一个事件之前就到了; - 会话事件不带命令 id;
agent_end之后跟着agent_settled,而后者才是客户端要等的东西;- 在流式输出期间发出的一条没有
streamingBehavior的prompt会得到一个错误响应,而带"steer"的则被排队; - 畸形的 JSON 产生一条
command: "parse"且不带 id 的响应,而一个未知命令是一条错误响应,同时进程继续提供服务; - 关闭 stdin 是一次有序关闭,进程以 0 退出;
- RPC 模式拒绝一个
@file提示词参数; get_commands列出一条扩展命令,而不列内置的终端命令;- 扩展 UI 子协议:一个扩展的
confirm()产生了一个extension_ui_request并阻塞,在客户端回答之前该扩展没有继续,带请求 id 的extension_ui_response解析了它,并且没有为它产生普通的命令响应。用cancelled: true回答会交付false; extension_error是一条 RPC 记录:一个抛了异常的处理器被报告,而这次运行仍然完成了;get_entries用一个 entry id 当作游标:带since时它只返回更晚的条目,leafId匹配最后一个条目,而一个未知 id 是一个错误。
未运行:clear_queue 后接 abort、扩展 UI 超时默认值,以及那些不那么常用的对话框方法。
本章没有解决什么
一个让你能向一个智能体发送命令的协议,也是一个让别的东西能向一个智能体发送命令的协议。RPC 模式不是一个沙箱:进程拥有它被启动时所拥有的那些权限,它从你的工作文件夹加载扩展,而 security.md 直言不讳地说项目信任"并不限制工具调用能访问或影响什么。”
所以遗留下来的问题不是如何与智能体对话。而是智能体能够碰到什么,以及它的哪些能力是你可以依赖的承诺、哪些是你必须自己提供的判断。
那个问题还得再等一个部分,因为还有一个层次本书只描述过、还没有用过。第一至第四部分的一切都运行在编码智能体内部,而第四部分展示了驱动它的五种方式。第五部分下潜到它之下,下到编码智能体所构建于其上的模型访问与智能体内核,并用它们构建出一样东西。
下一章:没有编码智能体的模型访问——一次返回类型化值的单次模型调用,没有循环、没有会话,也没有终端。