CASE 03

Pi Bridge — 多 Agent 委派的协议工程

把「让另一个 AI 干活」从一次性动作,变成有状态、可观测、可恢复的协议层:NDJSON 单行流 + 超时三档 + TIMEOUT ≠ ERROR + 零产出保护 + 断点续作 + 有界回退。

类别
协议 / 委派链路
时间跨度
2026-09-09 → 10-17
技术栈
Python · 572 行 · aegis_pi_bridge.py
状态
全链路接入 Job Manager
01

接入协议

原生 pi -p --mode json 的 NDJSON 事件流。不做 GUI 自动化、不装第三方扩展,协议在一行 stream 内收口。

02

时间边界

超时三档:600s 默认 / 对长任务 900s / 显式规定覆盖,优先级 explicit > auto > 默认。

03

状态边界

TIMEOUT ≠ ERROR:超时不等于代码故障,不能被归成 FAILED 误导 Job Manager。

04

零产出保护

stopReason=length 且无文本、无成功工具调用 → ERROR(旧版会误报 DONE)。

真实发生过的问题

EVIDENCE 01

一条 23 秒任务的协议事件流

run_20260916_201012_DONE.log 内 NDJSON 事件计数(原样统计,未抽样):

事件类型条数在链路中的含义
session / agent_start1 / 1Bridge 建立会话,拿到 session id 与 cwd
turn_start / turn_end15 / 1515 个回合(14 次工具调用 + 收尾)
tool_execution_start / end14 / 14bash 9 · read 3 · edit 1 · write 1
message_update331流式增量(文本/思考/工具输出),供上层实时展示
agent_end / agent_settled1 / 1终态:DONE(rc=0,23.0 s)
EVIDENCE 02

全部日志的状态分布

DONE 47 ERROR 22 NEEDS_INPUT 1目录合计 70 份
运行痕迹 · E1
  • logs/ 70 份(2026-10-19 复核):DONE 47 / ERROR 22 / NEEDS_INPUT 1;审计记录为 78 份,差额待核实
  • 402 / 429 / Request timed out 三类 ERROR 均已归因:provider 余额、限流、上游超时——属于上游/额度问题,不是代码故障
  • Job Manager 接入 Bridge 的 DONE / NEEDS_INPUT / TIMEOUT / ERROR 全部映射到 SQLite 工单,形成闭环
← Token Monitor D-006 — 全部 Review 通过后,系统仍然坏着Hindsight 记忆后端 — 一次失败背后的三层根因 →