通过 JSONL 驱动一个运行中的 Pi 子进程
发送带 id 的命令、按那个 id 关联响应、等 agent_settled 而不是 agent_end,并回答扩展 UI 对话框。
RPC 把 Pi 保留在一个单独的进程里,并以换行分隔的 JSON 与它对话,所以子进程的生命期由你决定——跨进程时你等的是一个事件,而不是一个 promise。代价是一个协议:命令与响应记录、一股不带命令 id 的会话事件流,以及第四种记录族、双向流动的扩展 UI 记录。下面的一切都是在 Pi 1.0.4 上、针对交付的二进制文件、由一个只按 LF 切分的手写客户端已观察到的。
运行它
启动 pi --mode rpc --no-session,每行发送一个 JSON 对象。标准演练是 examples/ch35-rpc/rpc.test.ts:它用一个极简的 JSONL 客户端驱动交付的 pi 二进制,在示例仓库的测试运行器上运行。不需要模型密钥,因为 provider 是脚本化的。
一次命令往返
{"id":"req-1","type":"prompt","message":"Review this repository"}
{"id":"req-1","type":"response","command":"prompt","success":true,"data":{"disposition":"started"}}响应会重复那个命令 id,这就是两条未完成的命令如何被匹配的——按 id,绝不按顺序。而一次成功的 prompt 意味着被接受、被排队或被处理,而不是已完成:这里 disposition 是 "started",而它在本次运行的第一个事件之前就到了。之后一切有意思的东西都以会话事件的形式到达,它们不带命令 id;一个客户端要等的完成是 agent_settled,它跟在 agent_end 之后。
协议走查
| 方向 | 记录 | 携带 |
|---|---|---|
| stdin | 命令 | 一次提示词、一次状态检查、一次配置更改、一次中止 |
| stdout | response |
每条命令一条:success 加 data,并重复那个 id |
| stdout | 会话事件 | 运行、工具、队列、压缩与重试活动;不带命令 id(除了 bash_execution_update,它重复发起它的那条 bash 的 id) |
| 双向 | 扩展 UI 记录 | 对话框与通知,按请求 id 相互关联 |
rpc.test.ts 的断言 |
进程做了什么 |
|---|---|
| 两条未完成的命令 | 按 id 匹配(a→get_state,b→get_available_models),而不是按顺序 |
prompt 成功 |
disposition: "started",在 agent_start 之前 |
流式输出期间的 prompt |
没有 streamingBehavior:一条错误响应;带 "steer":"queued" |
| 畸形的 JSON | 一条 parse 响应,success: false 且不带 id |
| 未知命令 | 一条错误响应;进程继续提供服务 |
| 关闭 stdin | 有序关闭;进程以 0 退出 |
@file 参数 |
在 RPC 模式下被拒绝 |
get_commands |
列出了扩展命令 ask,而不是 /settings 或 /hotkeys |
| 扩展对话框 | confirm() 发出一个 extension_ui_request 并阻塞;带同一个 id 的响应解析了它;cancelled: true 交付了 false;没有产生普通响应 |
extension_error |
一个抛出异常的处理器被报告,而这次运行仍然完成 |
get_entries |
since = 一个 entry id,只返回更晚的条目;leafId 匹配那个游标;一个未知 id 是一个错误 |
机制与局限
有文档记载:rpc.md、rpc-commands.md 和 rpc-extension-ui.md(1.0.4)定义了那四种记录族、按 id 相互关联(“按 ID 而不是按响应顺序来关联”)、disposition 契约、关闭 stdin 关机,以及带其超时默认值的扩展 UI 子协议。已观察:rpc.test.ts 针对交付的二进制断言了上面每一行。未运行:clear_queue 后接 abort、UI 超时默认值,以及那些不那么常用的对话框方法。
RPC 不是一个沙箱:子进程拥有它被启动时所拥有的那些权限,并从你的工作文件夹加载扩展。一个没有带超时发出的 extension_ui_request,可以为一个从不回答的控制器无限期地等下去,而 stderr 绝不能当作协议数据来解析。一条成功响应只覆盖命令处理——一次 prompt 被接受之后的 provider 失败和中止,会出现在消息与事件流中。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.