阶段三 · 集成与实践

协议与集成 —— 让程序也能用这个 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)

三个决定:

  1. 缓冲以行为单位:切完把最后一段放回缓冲,半包自动等下一次,粘包自动拆开。不数长度、不猜对齐。
  2. 坏帧是协议错误,不是流终止:报给调用方,缓冲区状态由调用方决定要不要重置。
  3. 无界缓冲有上限:一行恶意超长输入不能吃光内存——超限就清空并报错。

这三条正好对应上一节说的"Pi 没有大小上限,但消费者应该有"。

rpc_console.py 在它之上实现了一个白名单接口:只支持一种方法,返回 JSON,不创建子进程、不执行命令。它演示了三件事:标准输出只走协议、方法要有白名单、错误是数据。

验证方式

python3 -m unittest tests.test_10_rpc_jsonl tests.test_11_projects -v

边界与安全

  • 生产集成要限制:可调用的方法、消息大小、超时、凭据范围;不要把协议参数拼进 shell 命令。
  • 协议与 SDK 都不是绕过认证、拦截、会话管理的捷径。
  • 远端传来的内容不应被当作可信指令。
  • 自己实现客户端时务必加记录大小上限——服务端没有这条限制。

自测三问

  • 为什么分帧只能认换行符,不能用运行时自带的逐行读取?
  • 命令的编号为什么是可选的?不传会失去什么?
  • 想看"这一轮真的结束了",该等哪个信号?为什么不是运行结束?

回顾

  • 标准输出是协议:诊断走错误输出,一行一条消息。
  • 按行分帧:粘包、半包、坏行、未知消息四个边界;只认换行。
  • 协议有四类记录:命令、应答、事件、界面请求;编号可选。
  • 结束看结算完成,不是运行结束。
  • 旧的二进制协议栈已删除:现在只有命令行与 SDK 两条路。

机制都讲完了——最后一章实战与评测,用四个离线项目把前面所有机制组装起来。