1. 为什么需要给 Pi Coding Agent 加一层工程控制1.1 从“能跑”到“跑得稳”的鸿沟Pi Coding Agent 这类编码智能体刚上手的时候确实惊艳给它一个需求它能自己读代码、改文件、跑命令、验证结果一套流程走下来像模像样。但只要你把它放进真实项目里连续跑上几天问题就会集中爆发。我自己的体感是单次任务成功率看着还行可一旦任务链条拉长到十几步中间任何一步的模型输出抖动、工具调用超时、文件状态不一致都会让整个会话崩掉而且崩得悄无声息——你只知道它停了不知道停在哪、为什么停、能不能接着跑。这就是标题里说的“工程控制层”要解决的核心矛盾。Pi Coding Agent 本身是一个执行体它擅长的是“根据上下文决定下一步做什么”。但一个能在生产环境里用的系统除了执行体还需要三样东西可观测我能看到它每一步在干什么、可恢复崩了能从断点续上、可编排多个 Agent 或多次任务能按规则协同。Pi-Harness 就是套在 Agent 外面的这层壳它不改变 Agent 的智能只负责把 Agent 的行为变成可控、可查、可重放的工程对象。打个比方Pi Coding Agent 像是一个手艺很好的师傅Pi-Harness 则是给这个师傅配的工单系统、监控摄像头和交接班记录本。师傅还是那个师傅但你现在能管理他了。1.2 谁最需要这套东西如果你只是偶尔用 Agent 写个小脚本、改个配置那确实用不上 Harness直接对话就够了。但下面这几类场景没有控制层会非常痛苦长链路重构任务比如把一个模块从回调风格改成 async/await涉及几十个文件Agent 需要多轮迭代中途断一次就前功尽弃。多 Agent 协作一个 Agent 负责写代码一个负责 review一个负责跑测试它们之间需要传递状态、串行或并行调度。需要审计的团队环境你想知道某次改动到底是 Agent 哪一步决策导致的出了问题要能回溯。CI/CD 集成把 Agent 当成流水线里的一个环节要求它有明确的输入输出、退出码、超时控制。这四类场景的共同点是Agent 不再是玩具而是流程里的一个节点。节点就必须有接口、有状态、有错误处理。Pi-Harness 的价值就在这里。1.3 整体设计思路把 Agent 当进程管而不是当聊天管我设计 Pi-Harness 时定的第一条原则是不要把 Agent 会话当成一次对话要当成一个有生命周期的进程。这个视角的转变决定了后面所有技术选型。对话模型下状态是隐式的藏在消息历史里进程模型下状态必须显式落盘。对话模型下错误就是“它没回复”进程模型下错误要分类是模型调用失败、工具执行失败还是状态校验失败。对话模型下恢复靠“你再试一次”进程模型下恢复靠 checkpoint 和事件日志。具体到架构Pi-Harness 分四层层级职责关键产出接入层接收任务、鉴权、限流任务 ID、初始上下文编排层决定任务怎么拆、给谁做、什么顺序执行计划 DAG运行时层实际驱动 Agent 执行、捕获事件事件流、checkpoint观测层存储、查询、可视化日志、指标、trace这四层里运行时层是核心也是和 Pi Coding Agent 耦合最紧的地方。我的做法是在 Agent 和它的工具调用之间插一个拦截器interceptor所有工具调用、模型输出、文件变更都先经过拦截器由它统一打点、校验、落盘再放行。这样 Agent 本身几乎不用改控制能力全部外挂。提示拦截器模式的好处是解耦。Agent 升级了、换模型了Harness 基本不用动。坏处是拦截器本身要足够轻否则会拖慢每一步。我的实测是单步额外开销控制在 50ms 以内对整体体验几乎无感。2. 可观测性让 Agent 的每一步都留下痕迹2.1 事件模型设计什么该记什么不该记可观测的第一步是定义“事件”。Agent 跑起来会产生海量信息全记下来既贵又没用记少了又查不到问题。我最后定的事件模型是五类核心事件 可扩展自定义事件task.start/task.end任务边界带任务 ID、耗时、最终状态。step.begin/step.end每一步推理的边界带步序号、输入摘要、输出摘要。tool.call/tool.result工具调用带工具名、参数、返回值、耗时、是否成功。file.change文件变更带路径、变更类型增删改、diff 摘要。error错误事件带错误类型、堆栈、上下文快照。这五类覆盖了 90% 的排查需求。剩下的 10% 用自定义事件补比如你想记录“Agent 在第几步开始偏离目标”可以自己发一个drift.detected事件。事件的结构我用了比较朴素的 JSON Lines每行一个事件字段固定{ ts: 1718000000123, task_id: t-8f3a, step: 7, type: tool.call, payload: { tool: shell, args: {cmd: pytest tests/}, cwd: /repo } }为什么用 JSON Lines 而不是数据库因为写入要快、要能追加、要能直接 grep。排查问题的时候grep和jq是最快的工具不需要起一个查询服务。等数据量真的大了再往 ClickHouse 或 Loki 里灌也不迟。2.2 关键指标别只看成功率很多人做 Agent 观测只盯一个“任务成功率”这远远不够。成功率是个滞后指标等它掉下来问题已经发生了。我建议同时盯这几个先行指标单步耗时 P95某一步突然变慢往往是模型在长上下文里挣扎或者工具在重试。工具调用失败率按工具维度拆开看某个工具失败率飙升可能是环境问题。重试次数分布重试集中在哪几步那几步就是脆弱点。上下文 token 增长曲线如果每步都在涨且不收敛说明 Agent 在“记流水账”迟早爆上下文。文件变更冲突率多个 Agent 或多次任务改同一个文件的比例高了就要考虑加锁。这些指标我在 Harness 里做成了实时面板每 10 秒刷新一次。实测下来上下文 token 增长曲线是最有用的一个——它能在任务崩掉之前 5 到 10 步就发出预警。2.3 实操把 trace 接进现有日志体系如果你团队已经有 ELK 或 Loki最省事的做法是让 Harness 直接往 stdout 打结构化日志由采集器统一收走。配置大概是这样# harness.yaml observability: sinks: - type: stdout format: jsonl - type: file path: /var/log/pi-harness/events.jsonl rotate: max_size_mb: 256 keep: 10 sampling: tool.result: 1.0 # 工具结果全采 step.end: 1.0 # 步骤边界全采 file.change: 1.0 # 文件变更全采 debug: 0.1 # 调试日志采样 10%这里有个坑不要对tool.result做采样。工具结果是排查问题的关键证据采样会导致你恰好缺了出问题那一次的数据。要省空间就省debug级别的日志核心事件一个都不能丢。注意文件变更事件里的 diff 摘要要控制长度我一般截断到 2000 字符超长的单独存 blob 并记引用。否则一个大的 lock 文件变更就能把日志撑爆。3. 可恢复性断点续跑是刚需不是加分项3.1 Checkpoint 的粒度选择可恢复的核心是 checkpoint但 checkpoint 打多密是个权衡。打太密每次落盘开销大打太疏恢复时丢的进度多。我的经验值是按“语义步骤”打而不是按“工具调用”打。什么叫语义步骤比如“读取文件 A”“修改文件 A”“运行测试”这是三个工具调用但它们合起来是一个语义步骤“修复 A 的 bug”。Checkpoint 应该打在这个语义步骤的边界而不是每个工具调用后。实现上我让 Agent 在规划阶段就输出一个步骤列表Harness 按这个列表打 checkpoint。如果 Agent 是边想边做的没有显式规划那就退而求其次按“连续同类工具调用”聚类聚类的边界就是 checkpoint。Checkpoint 里存什么三样东西任务状态当前在第几步、目标是什么、已完成哪些子目标。环境快照工作目录的 git commit hash如果有、关键文件的 hash。上下文摘要不是完整消息历史而是压缩后的摘要避免恢复时上下文爆炸。3.2 恢复流程从哪断从哪续恢复不是简单地“重放最后一步”那样会重复副作用。正确的恢复流程是加载最近的 checkpoint得到任务状态和环境快照。校验当前环境是否和快照一致文件 hash、git 状态。如果不一致说明 checkpoint 之后环境被外部改过需要提示用户或自动 rebase。一致的话从 checkpoint 的下一步开始把摘要作为上下文喂给 Agent继续执行。这里最容易出问题的是副作用重复。比如 Agent 已经执行了git commit但 checkpoint 没记上恢复后它又 commit 一次。解决办法是让所有有副作用的工具调用都幂等化commit 前先检查是否已有相同 commit文件写入前先比对内容。Harness 在拦截器层做这层幂等校验Agent 无感。3.3 实操一个可恢复的 git 工作流结合热搜里高频出现的 git 相关词我分享一个实际配置。假设 Agent 在一个 git 仓库里工作Harness 的恢复策略这样配recovery: checkpoint: strategy: semantic_step max_interval_steps: 5 # 最多 5 步强制打一次 environment: type: git verify_on_resume: true auto_stash: true # 恢复前自动 stash 未提交改动 idempotency: git_commit: true # commit 幂等 file_write: true # 文件写入幂等 shell: false # shell 命令默认不幂等需显式声明shell: false是个重要决定。shell 命令的副作用无法自动判断所以默认不幂等恢复时如果遇到未完成的 shell 步骤Harness 会暂停并询问。这比盲目重跑安全得多。提示auto_stash在恢复前把工作区未提交的改动 stash 起来恢复后再 pop。这样能避免恢复过程和残留改动打架。但要注意 stash 冲突的情况我遇到过 pop 失败导致改动丢失所以现在会先把 stash 内容备份一份再 pop。4. 多 Agent 编排从单打独斗到流水线4.1 编排模型DAG 还是状态机多 Agent 编排有两种主流模型DAG有向无环图和状态机。DAG 适合任务能提前拆清楚、依赖关系明确的场景状态机适合流程有循环、有动态分支的场景。Pi-Harness 我选了混合模型顶层用 DAG 描述 Agent 之间的依赖每个节点内部用状态机描述该 Agent 的执行流程。这样既有全局的清晰结构又有局部的灵活性。一个典型的多 Agent 编排长这样pipeline: name: feature-dev nodes: - id: planner agent: pi-coding role: 拆解需求输出任务列表 - id: coder agent: pi-coding role: 按任务列表写代码 depends_on: [planner] - id: reviewer agent: pi-coding role: review coder 的产出 depends_on: [coder] - id: tester agent: pi-coding role: 跑测试并修复 depends_on: [reviewer] loop: max_iterations: 3 until: tests_passloop是状态机能力的体现tester 节点可以循环最多 3 次直到测试通过。这种“DAG 套循环”的结构比纯 DAG 或纯状态机都更贴合实际开发流程。4.2 Agent 间通信共享工作区还是消息传递多 Agent 协作最大的争议点是它们怎么交换信息两种做法共享工作区所有 Agent 操作同一个文件系统通过文件交换信息。消息传递Agent 之间通过消息队列通信各自有独立工作区。我两个都用过结论是共享工作区为主消息传递为辅。原因是编码任务的产物本质就是文件让 Agent 直接改文件最自然也最容易被人类 review。消息传递适合传递“意图”和“反馈”比如 reviewer 给 coder 的修改意见走消息通道更清晰。Harness 里的实现是每个 Agent 节点挂载同一个工作区卷同时有一个轻量的消息总线用于节点间通信。消息总线我用了最朴素的文件队列每个节点一个 inbox 目录写文件就是发消息读文件就是收消息。简单、可观测、可重放。4.3 冲突处理两个 Agent 改同一个文件怎么办这是多 Agent 编排里最头疼的问题。我的处理策略分三层预防编排阶段就做文件级依赖分析如果两个节点会改同一文件强制串行。检测运行时拦截器监控文件变更发现并发写同一文件立即告警。解决如果已经冲突用 git 的三方合并能力自动合并合并失败则暂停并交给人类。第一层能解决 80% 的问题。做依赖分析时我让 planner Agent 在拆解任务时就标注每个子任务涉及的文件Harness 据此构建文件依赖图有交集的节点自动串行化。注意文件依赖分析不可能 100% 准确Agent 经常“顺手”改了计划外的文件。所以第二层的运行时检测不能省。我踩过的坑就是太信任静态分析结果两个 Agent 同时改了一个配置文件互相覆盖排查了半天。5. 常见问题与排查技巧实录5.1 问题速查表现象可能原因排查动作任务卡住不动工具调用超时未设上限查tool.call事件看哪个工具没返回恢复后重复执行checkpoint 未覆盖副作用检查幂等配置看git_commit是否开启上下文爆炸消息历史未压缩看 token 增长曲线检查摘要策略多 Agent 互相覆盖文件依赖分析漏了查file.change事件的时间重叠恢复后环境不一致外部改动未检测检查verify_on_resume是否开启Agent 偏离目标上下文被无关信息污染看step.begin的输入摘要找污染源5.2 三个我踩过的坑坑一checkpoint 存了完整消息历史恢复时直接爆上下文。一开始我图省事checkpoint 里存整个 messages 数组结果恢复时上下文直接超限。后来改成存摘要 最近 N 条原始消息N 取 5 到 10效果就好多了。摘要用一个小模型生成成本可忽略。坑二工具调用超时没设一个卡住的 shell 命令让整个任务挂了一小时。现在所有工具调用强制设超时默认 120 秒shell 类可以单独配。超时后不是直接失败而是发一个tool.timeout事件让 Agent 决定是重试还是换方案。坑三多 Agent 共享工作区时git 索引被并发操作搞坏。两个 Agent 同时跑git add索引文件直接损坏。解决办法是给 git 操作加文件锁Harness 层统一串行化所有 git 写操作。读操作可以并发写操作必须排队。5.3 一个实用的调试技巧当任务失败时别急着看最后的错误先看倒数第三个 checkpoint 到失败点之间的事件流。经验告诉我真正的根因往往不在最后一步而在更早的某一步埋下了雷。比如最后是“测试失败”但根因可能是三步前 Agent 误删了一个测试 fixture。Harness 提供了一个命令直接导出这个区间的事件pi-harness trace export \ --task t-8f3a \ --from-checkpoint 3 \ --to-end \ --format timeline导出的 timeline 按时间顺序排列所有事件带缩进表示嵌套关系一眼就能看出哪一步开始不对劲。6. 落地建议与扩展方向6.1 从小处着手别一上来就全套如果你刚接触这套东西我的建议是先只做可观测再做可恢复最后做编排。可观测的投入最小、收益最快一个 JSON Lines 日志加一个 grep 就能解决大部分“它到底干了啥”的问题。可恢复需要改 Agent 的执行循环投入中等。编排最复杂涉及多进程、锁、消息传递没有前两层的基础直接上会非常痛苦。我自己的落地顺序是第一周只加事件日志第二周加 checkpoint第三周才做第一个双 Agent 编排。每一步都跑稳了再进下一步。6.2 这套东西还能怎么扩展Pi-Harness 目前的形态是“控制层”往上还能长两个方向策略层根据历史数据自动调整 Agent 的行为比如发现某类任务总是重试就自动换模型或换提示词。协作层支持人类在环Agent 跑到关键步骤时暂停等人确认后再继续。这个在敏感操作比如删文件、推代码上特别有用。再往远了想如果多个团队都用 Harness事件格式统一了还能做跨团队的 Agent 行为分析看看哪类任务在什么条件下最容易失败。不过这属于后话先把单团队的闭环跑通再说。最后分享一个我个人的使用习惯每次 Agent 任务失败我都会把那次的事件流存下来攒够一批之后统一分析。跑了两个月我发现失败案例里超过一半是“上下文污染”导致的而不是模型能力不够。这个发现直接改变了我优化 Agent 的方向——与其换更强的模型不如把上下文管理做好。这个体会可能比任何技术细节都值钱。