← Pi Agents

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 直言不讳地说项目信任"并不限制工具调用能访问或影响什么。”

所以遗留下来的问题不是如何与智能体对话。而是智能体能够碰到什么,以及它的哪些能力是你可以依赖的承诺、哪些是你必须自己提供的判断。

那个问题还得再等一个部分,因为还有一个层次本书只描述过、还没有用过。第一至第四部分的一切都运行在编码智能体内部,而第四部分展示了驱动它的五种方式。第五部分下潜到它之下,下到编码智能体所构建于其上的模型访问与智能体内核,并用它们构建出一样东西。

下一章:没有编码智能体的模型访问——一次返回类型化值的单次模型调用,没有循环、没有会话,也没有终端。