阶段三 · 集成与实践
协议与集成 —— 让程序也能用这个 Agent
Agent 不只给人用,还要被脚本、CI、编辑器调用。Pi 提供了几种"无头"形态,共享同一个核心,区别只在外层怎么把事件交出去。这一章讲清按行分帧的四个边界、协议里有哪几类消息,以及"什么才算真的结束了"。
具体回答三个问题:程序怎么拿到过程,而不只是结果?一条流被切碎了怎么办?怎么确定它真的结束了?
学习目标
- 掌握按行分帧要处理的四个边界:粘包、半包、坏行、不认识的消息。
- 分清三种无头形态的用途与差别。
- 理解协议里不只有事件,还有应答与界面请求,以及为什么"编号"是可选的。
- 知道判断"结束"应该看哪个信号。
一、问题:程序怎么调用 Agent
人在终端里敲字,程序要的是可解析的输出。一次性的问题可以只看最后一句回答;但要接入自己的宿主程序(网页、编辑器插件、CI),你需要结构化的过程——最好是事件流。
Pi 的形态可以这么理解(终端交互是默认形态,其余三种是无头形态):
| 形态 | 启动方式 | 输出什么 | 适合什么 |
|---|---|---|---|
| 终端交互 | 直接运行 | 界面 | 人机对话 |
| 一次性 | 加一个"打印"开关 | 最终文本 | 脚本、单次查询 |
| 事件流 | 指定结构化模式 | 一行一个事件 | 程序消费过程 |
| 双向协议 | 指定协议模式 | 标准输出上的应答与事件,标准输入上的命令 | 长驻集成、远程控制 |
四种形态共享同一个核心,这正是第 01 章"界面消费事件"的实际体现。
一个容易混的细节:模式开关只有三个取值(文本、结构化、协议),终端交互是默认形态,不是靠开关选出来的。
二、标准输出是协议,诊断走错误输出
无头形态的第一原则:标准输出只留给协议数据,诊断信息写错误输出。
任何一句调试打印混进标准输出,都会把协议帧搅乱——消费者会把日志当成事件解析,然后崩溃。所以"我在代码里随手打印一行"这件小事,在协议模式下是事故。
结构化模式还有一个启动细节:第一帧是会话头(版本、编号、工作目录),之后才是消息与事件。协议模式没有这个头,要主动发一条"取状态"的命令去问。
三、按行分帧的四个边界
协议与事件流都是一行一个 JSON。消费者必须处理四种情况:
| 边界 | 现象 | 正确处理 |
|---|---|---|
| 粘包 | 一次读取拿到好几条 | 循环逐条吐出 |
| 半包 | 一条被切成两段到达 | 缓冲到换行符再交付 |
| 坏行 | 某行不是合法 JSON | 报错,但不吞掉后续 |
| 不认识的消息 | 新版本加了新类型 | 保留并跳过,不能崩 |
做法是一个很小的状态机:把字节流切成"完整行"交给业务层,业务层只关心"一行 = 一条消息"。
分帧必须只认换行符。Pi 的实现刻意不用运行时自带的逐行读取工具,因为那个工具会把 JSON 字符串里合法的 Unicode 行分隔符也当成行尾,切出半个 JSON。这个问题很隐蔽:平时测不出来,直到某段文本里恰好出现那个字符。
还有一个区别要说清:Pi 自己的读取器没有"单条记录大小上限"。它按行累积,遇到换行才交付。"未终止的超长记录必须拒绝"是给消费者的建议(也是本课程实现的策略),目的是防内存耗尽——但它不是 Pi 协议的规定,别把它写成事实。
四、协议里跑的不只是事件
双向协议是真正的双向:标准输入上有命令,标准输出上不只有事件,还有应答和界面请求。四类记录:
| 记录 | 方向 | 说明 |
|---|---|---|
| 命令 | 标准输入 | 客户端发起,编号可选 |
| 应答 | 标准输出 | 对某条命令的回复;带编号时用来对上号 |
| 会话事件 | 标准输出 | Agent 的过程事件,含队列状态变化 |
| 界面请求 | 标准输出 | 扩展要弹窗时的请求,等客户端回一条应答 |
几条容易记错的约定:
- 编号是可选的。不传就没有对号依据;需要并发发多条命令时,自己带唯一编号。
- 失败也是数据:未知命令、参数错误都回一条结构化错误,进程不退出。
- 队列可以清空:积压的插话与跟进消息能取出来,配套有队列状态事件,所以队列从"只进不出"变成了可观察、可干预。
- 界面请求是独立子协议:选择、确认、输入、编辑器四类弹窗会阻塞等待客户端答复;通知类的只单向发;"自定义面板"在协议模式下会降级。
- 协议文档已经拆成三部分:协议本体、命令清单、界面子协议。只读第一部分会漏掉后两块。
什么才算真的结束
看交付完成信号,而不是"运行结束"。
原因在前面提过:运行结束之后还可能发生自动重试、压缩、排队续跑。只有"结算完成"才表示这一轮彻底收尾,它还带一个"是不是被取消"的标记。
五、几种集成面,别只盯着协议
| 集成面 | 适合什么 |
|---|---|
| 一次性输出 | 最简单的脚本调用 |
| 事件流 | 要过程、要增量渲染 |
| 双向协议 | 长驻、需要中途控制 |
| SDK | 在同一个进程里直接建会话、订阅事件 |
| 脚本化调用 | 模型自己写脚本,一次编排多个工具 |
| 外部工具服务器 | 把第三方工具接进工具池 |
最后两个不是"调用 Pi"的接口,而是"Pi 调用外部世界"的接口——但在集成地图上它们同等重要:一个产品往往同时用协议对外、用外部工具服务器对内。
历史上还有过一套"二进制协议 + 服务端"的实验栈,它在 1.2 版本里被整体删除。现在跨进程集成只有命令行与 SDK 两条路,别再按旧资料去找那两个包。
当前 Pi 行为
- 无头形态有三种:文本、结构化事件、双向协议;终端交互是默认形态,不属于开关选项。
- 结构化事件模式的第一帧是会话头;协议模式没有头,要主动取状态。
- 分帧只认换行;Pi 的读取器没有单条记录大小上限。
- 协议有命令、应答、会话事件、界面请求四类记录;命令编号可选。
- 队列可清空,也能远程设置/中止重试。
- 判断结束看"结算完成"(带是否取消的标记),不是"运行结束"。
- 实验性的二进制协议与服务端包已在 1.2 版本删除,现在不存在。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 模式开关 | --mode text / json / rpc |
| 一次性输出 | -p / --print |
| 分帧读取器 | attachJsonlLineReader |
| 清空队列 | clear_queue |
| 结算完成 | agent_settled |
| SDK 入口 | createAgentSession() |
| SDK 订阅 | session.subscribe(...) |
源码位置
packages/coding-agent/src/modes/rpc/:协议实现与分帧读取。packages/coding-agent/docs/json.md、rpc.md、rpc-commands.md、rpc-extension-ui.md:四份一手参考。packages/coding-agent/docs/cli-integration.md:把 Pi 当子进程集成的说明。
失败与边界实验
lab rpc-jsonl 与对应测试覆盖三种病态输入:
| 输入 | 症状 | 正确处理 |
|---|---|---|
| 两条粘在一起一次到达 | 按块解析直接报错 | 按行缓冲,逐行解析 |
| 半条先到、后半条后到 | 前段解析失败、后段是垃圾 | 缓冲到出现完整行 |
| 一行不是合法 JSON | 整个流崩溃 | 报帧错误,保留后续帧 |
三种错误指向同一个结论:解析按帧(行),不按块。这也是为什么标准输出要留给协议——帧边界是双方唯一都认同的分隔符,任何"我猜它到齐了"的解析,在真实网络上都会碎。
python3 -m learn_pi_lab lab rpc-jsonl
python3 -m unittest tests.test_10_rpc_jsonl -v
在 Pi 里怎么操作
pi -p "总结一下这个仓库" # 一次性
pi --mode json "看下测试为什么失败" # 事件流
pi --mode rpc # 双向协议
pi mcp list # 外部工具服务器列表
Python 实验
rpc_jsonl.py 用不到一百行实现一个最小分帧器:
def feed(self, chunk: str) -> tuple[RpcRequest, ...]:
candidate = self._buffer + chunk
if len(candidate.encode("utf-8")) > self._max_buffer_bytes and "\n" not in candidate:
self._buffer = ""
raise RpcProtocolError("unterminated record exceeds buffer limit")
records = candidate.split("\n")
self._buffer = records.pop() # 半包:最后一段留到下次
for record in records:
if not record.strip():
continue # 空行跳过
messages.append(_validate_record(json.loads(record)))
return tuple(messages)
三个决定:
- 缓冲以行为单位:切完把最后一段放回缓冲,半包自动等下一次,粘包自动拆开。不数长度、不猜对齐。
- 坏帧是协议错误,不是流终止:报给调用方,缓冲区状态由调用方决定要不要重置。
- 无界缓冲有上限:一行恶意超长输入不能吃光内存——超限就清空并报错。
这三条正好对应上一节说的"Pi 没有大小上限,但消费者应该有"。
rpc_console.py 在它之上实现了一个白名单接口:只支持一种方法,返回 JSON,不创建子进程、不执行命令。它演示了三件事:标准输出只走协议、方法要有白名单、错误是数据。
验证方式
python3 -m unittest tests.test_10_rpc_jsonl tests.test_11_projects -v
边界与安全
- 生产集成要限制:可调用的方法、消息大小、超时、凭据范围;不要把协议参数拼进 shell 命令。
- 协议与 SDK 都不是绕过认证、拦截、会话管理的捷径。
- 远端传来的内容不应被当作可信指令。
- 自己实现客户端时务必加记录大小上限——服务端没有这条限制。
自测三问
- 为什么分帧只能认换行符,不能用运行时自带的逐行读取?
- 命令的编号为什么是可选的?不传会失去什么?
- 想看"这一轮真的结束了",该等哪个信号?为什么不是运行结束?
回顾
- 标准输出是协议:诊断走错误输出,一行一条消息。
- 按行分帧:粘包、半包、坏行、未知消息四个边界;只认换行。
- 协议有四类记录:命令、应答、事件、界面请求;编号可选。
- 结束看结算完成,不是运行结束。
- 旧的二进制协议栈已删除:现在只有命令行与 SDK 两条路。
机制都讲完了——最后一章实战与评测,用四个离线项目把前面所有机制组装起来。