1. 为什么 Coding Agent 需要一个工程控制层1.1 从“能跑”到“跑得稳”的鸿沟过去一年命令行形态的 Coding Agent 从演示走向日常开发很多人第一次体验时都会有一种“未来已来”的兴奋感一句自然语言描述Agent 自动读文件、改代码、跑测试、提交变更。但真正把它放进日常工程流程里跑上一周问题就会集中暴露出来。最典型的三个症状是过程不可见、失败不可续、多任务不可编排。所谓过程不可见是指 Agent 在终端里刷屏式输出你只能看到它“正在思考”“正在执行”但具体调用了哪些工具、读了哪些文件、改了哪几行、耗时分布如何全靠事后翻日志。一旦它中途跑偏你很难定位是哪一步的上下文出了问题。失败不可续则更让人头疼一个涉及十几个文件的重构任务跑到第八步因为一次工具调用超时中断重新发起时它又从零开始前面已经确认过的改动全部作废。至于多任务编排当你同时想让它修一个 bug、补一组测试、更新一份文档时只能开多个终端窗口手动协调彼此之间没有任何状态隔离和依赖管理。Pi-Harness 这个项目要解决的正是这三件事。它不是又一个 Coding Agent而是给已有的 Pi Coding Agent 套上一层工程控制层把 Agent 的每一次思考、每一次工具调用、每一次文件变更都变成可观测的事件流把整个任务拆成可持久化、可恢复的步骤把多个任务组织成有依赖关系的编排图。用一句话概括它的定位——让 Coding Agent 从“能跑”变成“跑得稳、看得清、接得上”。1.2 谁适合读这篇内容如果你只是偶尔用 Coding Agent 写个小脚本那这套东西可能有点重。但如果你符合下面任意一条Pi-Harness 的思路就值得你认真看你已经在团队里把 Coding Agent 接入日常开发流程需要审计它到底改了什么你经常跑长任务大规模重构、批量补测试、跨模块迁移中途失败代价很高你需要让多个 Agent 任务并行且它们之间有先后依赖你想给 Agent 加一层“护栏”在关键操作前做校验、在异常时做回滚。这篇文章不会停留在概念层面。我会把 Pi-Harness 的整体设计思路、核心模块的实现要点、可观测与可恢复的具体落地方式、以及编排层的调度逻辑都拆开讲清楚并且给出可以直接参考的配置和代码片段。读完之后你应该能自己搭出一个最小可用的控制层或者至少知道该往哪个方向改造你现有的 Agent 工作流。2. 整体设计思路与方案选型2.1 为什么是“控制层”而不是“重写 Agent”一个很自然的疑问是既然现有 Agent 有这么多问题为什么不直接重写一个更好的我一开始也这么想过但很快放弃了。原因有三点。第一Agent 的核心能力模型推理、工具调用、上下文管理本身迭代极快。今天你重写一套明天底层模型或工具协议一升级你的重写版本立刻落后。把控制层和 Agent 内核解耦意味着内核怎么变控制层都能通过适配器接住。第二控制层关注的是工程属性和 Agent 的智能程度正交。可观测、可恢复、可编排这些是任何长任务系统都需要的能力跟模型强不强没有直接关系。把它们抽出来单独做反而能做得更扎实。第三改造成本。给现有 Agent 套一层控制层通常只需要在它的工具调用入口和生命周期钩子上做拦截不需要动它的推理逻辑。这对已经在用 Pi Coding Agent 的人来说迁移成本最低。所以 Pi-Harness 的整体架构是典型的旁路拦截 事件驱动Agent 照常跑Harness 在它周围挂一圈钩子把关键事件捕获下来存进事件存储再由调度器决定下一步怎么走。2.2 三层架构事件层、状态层、编排层把整个系统拆开看Pi-Harness 分成三层每层职责非常清晰。事件层Observability Layer负责采集。它监听 Agent 的生命周期事件——任务开始、思考片段、工具调用请求、工具调用结果、文件写入、任务结束或异常——把每个事件标准化成统一结构带上时间戳、任务 ID、步骤序号、耗时、输入输出摘要。这一层的核心是标准化不管底层 Agent 用什么方式输出到了事件层都变成同一种格式后面的存储和分析才能统一处理。状态层Recovery Layer负责持久化。它把事件流按任务维度组织成一份可回放的状态快照。关键设计是检查点Checkpoint机制每完成一个原子步骤就把当前的任务状态、已变更文件列表、上下文摘要写一份检查点。任务中断后从最近的检查点恢复而不是从头再来。这里有个重要取舍——检查点不能太频繁写放大严重也不能太稀疏恢复代价高后面会讲具体怎么定这个粒度。编排层Orchestration Layer负责调度。它把多个任务组织成有向无环图DAG节点是任务边是依赖关系。调度器按拓扑顺序执行支持并行分支、条件分支、失败重试和人工介入节点。这一层解决的是“多个 Agent 任务怎么协同”的问题。三层之间通过事件总线通信事件层产生的事件既流向状态层做持久化也流向编排层做调度决策。这种设计的妙处在于任何一层都可以单独替换或增强不会牵一发动全身。2.3 关键选型背后的考量在具体技术选型上有几个决定值得展开说。事件存储用追加写的日志结构而不是关系表。原因是 Agent 事件本质上是时序流写入远多于读取而且需要按时间顺序回放。用追加日志类似 append-only log 的思路写入吞吐高回放简单。查询时再建索引或投影到只读视图。如果一上来就用关系表高频写入会成为瓶颈。检查点用文件系统快照 元数据分离。文件内容本身用快照或增量 diff 存元数据步骤序号、上下文摘要、依赖状态用结构化格式单独存。这样恢复时先读元数据判断恢复到哪一步再按需拉取文件内容避免一次性加载全部数据。编排用声明式 DAG 描述而不是命令式脚本。声明式的好处是编排图可以被静态分析、可视化、校验环依赖也方便做重试和补偿策略。命令式脚本写起来直观但一旦要加失败重试、并行控制代码会迅速失控。3. 可观测层把 Agent 的黑盒变成事件流3.1 事件模型设计一个事件该带哪些字段可观测做得好不好八成取决于事件模型设计得对不对。字段太少事后排查时信息不够字段太多存储和传输成本飙升。经过几轮迭代我最终定下来的核心字段如下字段类型说明是否必填event_idstring全局唯一事件 ID是task_idstring所属任务 ID是step_indexint任务内步骤序号从 0 递增是event_typeenum事件类型见下文是timestampint64毫秒级时间戳是duration_msint该步骤耗时否payloadobject事件具体内容结构随类型变化是parent_event_idstring父事件 ID用于构建调用树否event_type我定义了六种基础类型task_start、thought、tool_call、tool_result、file_change、task_end。这六种基本覆盖了 Agent 执行过程中的所有关键节点。payload的结构随类型变化比如tool_call的 payload 包含工具名和参数file_change的 payload 包含文件路径和变更前后的哈希。这里有个容易踩的坑不要把完整文件内容塞进事件 payload。我最初图省事把每次文件变更的完整内容都存进事件结果一个中等规模的重构任务产生了上百 MB 的事件日志查询和回放都变得极慢。正确做法是 payload 里只存文件路径和内容哈希完整内容交给状态层的快照去管。3.2 埋点位置在哪里挂钩子最省事埋点的位置决定了你能观测到什么。Pi-Harness 选择在三个位置挂钩子这三个位置是 Agent 执行路径上的天然分界点。第一个位置是任务生命周期入口。在 Agent 开始处理一个任务时触发task_start结束时触发task_end。这个钩子通常挂在 Agent 的主循环外层实现最简单。第二个位置是工具调用边界。这是信息量最大的地方。在工具被调用前触发tool_call调用返回后触发tool_result。这里能拿到工具名、参数、返回值、耗时、是否成功。绝大多数排查场景都靠这两个事件。第三个位置是文件系统写入点。Agent 改文件是它产生实际影响的地方必须单独观测。在文件写入前后各取一次内容哈希触发file_change事件。这样即使工具调用成功但文件没真正改比如写了个空 diff你也能从事件流里看出来。提示埋点尽量用非侵入方式比如包装工具调用函数、监听文件系统事件而不是去改 Agent 的推理代码。侵入式埋点一旦 Agent 升级就容易失效。3.3 事件流的实时消费与展示事件采集上来之后得让人能实时看到。Pi-Harness 提供了一个轻量的终端 UI把事件流按任务分组展示每个任务显示当前步骤、已耗时、最近一次工具调用。这个 UI 不是必需品但它极大提升了调试体验——你能一边看 Agent 跑一边看事件流出问题时立刻知道卡在哪一步。实时消费的实现思路是事件层写入事件后同时推一份到内存队列UI 从队列消费并渲染。这里要注意背压处理如果 Agent 产生事件的速度超过 UI 消费速度队列会堆积。我的做法是给队列设上限超过上限时丢弃低优先级的thought事件保留tool_call、tool_result、file_change这些关键事件。毕竟思考片段丢了不影响排查工具调用丢了就没法定位问题了。除了终端 UI事件流还可以导出成结构化格式接入你已有的日志或监控系统。导出时建议按任务 ID 分片避免单个文件过大。4. 可恢复层让中断的长任务能接着跑4.1 检查点粒度多久存一次才合理可恢复的核心是检查点。检查点存得太勤每次写盘都拖慢 Agent存得太稀恢复时回退太多等于白跑。这个粒度怎么定我总结了一个经验公式检查点间隔 ≈ 单个原子步骤的平均耗时 × 可接受的回退步数举个例子如果一个原子步骤比如改一个文件并跑一次相关测试平均耗时 30 秒你能接受中断后最多回退 3 步那检查点间隔就定在 90 秒左右。但更稳妥的做法是按步骤边界存而不是按时间存。因为 Agent 的步骤耗时波动很大按时间存可能正好卡在某个步骤中间恢复时状态不一致。所以 Pi-Harness 的策略是每个原子步骤完成后立即写检查点但检查点内容做增量处理。所谓增量是指只记录这一步相对上一步的变化而不是全量快照。这样即使每步都写单次写入量也很小。全量快照则每隔 N 个步骤比如 10 步做一次用于加速恢复。4.2 状态快照包含什么一个完整的检查点包含四部分内容缺一不可。第一部分是任务元状态当前步骤序号、任务整体进度、已完成的子目标列表、待办子目标列表。这部分是恢复时判断“从哪继续”的依据。第二部分是文件变更记录这一步改了哪些文件、每个文件变更前后的哈希、变更类型新增/修改/删除。恢复时据此判断工作区是否处于预期状态。第三部分是上下文摘要Agent 到目前为止积累的关键上下文比如已确认的接口约定、已排除的方案、用户的关键约束。这部分最容易被忽略但恰恰是恢复后 Agent 能不能“接上思路”的关键。如果不存上下文摘要恢复后的 Agent 虽然文件状态对了但脑子里一片空白很可能做出和之前矛盾的决策。第四部分是依赖状态如果这个任务在编排图里有上游依赖记录上游任务的完成状态和输出摘要供恢复时校验。4.3 恢复流程从检查点到继续执行恢复不是简单地“读检查点然后继续”中间有几个必须处理的校验步骤。第一步是工作区一致性校验。读检查点里记录的文件哈希和当前工作区实际文件的哈希逐一比对。如果发现不一致说明中断后有外部改动这时候不能盲目恢复要么提示人工介入要么把差异部分单独处理。第二步是上下文重建。把检查点里的上下文摘要重新注入 Agent 的上下文让它“想起”之前做了什么决策。这一步的注入方式很讲究不能简单地把摘要文本塞进去最好结构化成“已完成事项”“关键约定”“待办事项”三块让 Agent 一眼看清当前处境。第三步是步骤对齐。根据检查点的步骤序号跳过已经完成的步骤从下一个未完成步骤开始。这里要注意有些步骤可能有副作用比如已经提交了一次变更恢复时要判断是否需要补偿或跳过。注意恢复后第一次工具调用前建议强制 Agent 做一次“现状确认”比如让它先读一遍关键文件、跑一次测试确认当前状态符合预期再继续。这一步能拦住大部分因状态不一致导致的连锁错误。4.4 幂等性恢复时最容易翻车的地方恢复功能做得好不好最终取决于步骤的幂等性。如果一个步骤执行两次会产生不同结果那恢复就会出问题。比如“在文件末尾追加一行配置”这个操作执行两次就追加了两行。解决思路有两个。一是把步骤设计成幂等的比如“确保文件包含某行配置”而不是“追加某行配置”前者执行多次结果一致。二是给每个步骤记录执行状态恢复时先检查该步骤是否已执行已执行则跳过。Pi-Harness 两个都用对文件操作尽量设计成幂等语义对无法幂等的操作比如调用外部接口则严格记录执行状态。这里分享一个我踩过的坑早期版本我没做幂等处理结果一次恢复后 Agent 把同一个测试文件重复生成了三遍覆盖了原有内容。后来我在文件写入前加了一道校验——如果目标文件已存在且内容哈希与检查点记录一致就跳过写入。这个校验成本很低但拦住了大量重复写入。5. 可编排层多任务协同的调度逻辑5.1 用 DAG 描述任务依赖编排层要解决的核心问题是多个 Agent 任务之间怎么组织。最自然的表达方式是有向无环图DAG。每个节点是一个任务每条边表示“前者完成后后者才能开始”。为什么强调“无环”因为环依赖会导致死锁——A 等 BB 等 A谁也动不了。声明式 DAG 的一个好处就是可以在加载时静态检测环提前报错而不是等到运行时才发现。一个典型的编排描述长这样用 YAML 示意tasks: - id: refactor-core agent: pi prompt: 重构 core 模块拆分出独立的解析层 outputs: [changed_files, summary] - id: add-tests agent: pi depends_on: [refactor-core] prompt: 为重构后的解析层补充单元测试 inputs: changed_files: {{ refactor-core.changed_files }} - id: update-docs agent: pi depends_on: [refactor-core] prompt: 更新文档中关于解析层的说明 - id: final-review agent: pi depends_on: [add-tests, update-docs] prompt: 审查所有变更检查一致性这个图里refactor-core是根节点add-tests和update-docs可以并行final-review等两者都完成后再跑。调度器按拓扑顺序推进能并行的节点同时启动。5.2 调度器的核心逻辑调度器的工作可以概括成一个循环找出所有依赖已满足的节点启动它们等待完成更新依赖状态重复直到所有节点完成或失败。具体实现上有几个关键点。第一是依赖满足判定一个节点可执行当且仅当它所有上游节点都成功完成。如果某个上游失败下游节点要么被标记为阻塞要么触发补偿逻辑。第二是并行度控制不是所有可并行节点都该同时跑。Agent 任务通常吃资源模型调用、文件 IO并行太多会互相拖慢。我一般设一个并行上限比如同时最多跑 3 个节点超出的排队等待。第三是失败传播策略上游失败时下游怎么办有三种选择——立即中止整个图、跳过下游但继续其他分支、或者重试上游。Pi-Harness 默认是“跳过下游、继续其他分支”因为很多任务图里分支之间是独立的一个分支失败不该拖垮全部。这个策略可以按图配置。5.3 节点间的数据传递编排图里节点不是孤立的上游的输出往往要传给下游。比如重构任务产出的“变更文件列表”要传给补测试任务作为输入。数据传递的设计要点是显式声明 按需注入。每个节点在定义时声明自己产出哪些输出outputs下游节点声明自己需要哪些输入inputs调度器负责在节点完成时把输出存起来在启动下游时把输入注入进去。这里有个细节输出要存摘要而不是全量。比如“变更文件列表”存文件路径列表就够了不需要存文件内容。下游 Agent 需要内容时自己去读工作区。这样既减小了状态存储压力也保证了数据一致性——下游读到的永远是最新版本。5.4 人工介入节点全自动编排听起来很美但实际工程里总有些环节需要人拍板。比如“重构方案确认”“关键接口变更审批”。Pi-Harness 支持一种特殊节点类型人工介入节点。这种节点执行时会暂停整个图把当前上下文和待决策事项展示给人等人给出确认或修改意见后再继续。实现上它就是一个阻塞点调度器遇到它就把图状态标记为“等待人工”直到收到外部信号。这个设计在实际使用中价值很高。我通常会在“大规模重构”和“最终提交”之间插一个人工节点让 Agent 把变更摘要列出来我扫一眼确认没问题再放行。这一步花不了几分钟但能拦住很多 Agent 自作主张的改动。6. 实操落地从零搭一个最小可用版本6.1 环境准备与依赖要跑起一个最小版本的 Pi-Harness你需要准备这些东西一个能正常工作的 Pi Coding Agent 环境、一个用于存事件和检查点的本地目录、以及一个能跑调度逻辑的运行时。语言上我用的是 Python因为它和大多数 Agent 生态的对接最顺。目录结构建议这样组织pi-harness/ ├── events/ # 事件日志按任务分文件 ├── checkpoints/ # 检查点按任务分目录 ├── snapshots/ # 文件快照 ├── graphs/ # 编排图定义 └── harness/ # 控制层代码 ├── observer.py # 事件采集 ├── recovery.py # 检查点与恢复 └── scheduler.py # 编排调度事件和检查点分开存是因为它们的读写模式不同事件是高频追加写、低频顺序读检查点是低频写、随机读。分开存能各自优化。6.2 事件采集的最小实现事件采集的核心是一个包装函数把 Agent 的工具调用包起来前后各发一个事件。伪代码大致如下def wrap_tool_call(tool_name, tool_fn, task_id, step_index): def wrapped(*args, **kwargs): start now_ms() emit_event(task_id, step_index, tool_call, { tool: tool_name, args: summarize(args, kwargs) }) try: result tool_fn(*args, **kwargs) emit_event(task_id, step_index, tool_result, { tool: tool_name, status: ok, result: summarize(result) }, duration_msnow_ms() - start) return result except Exception as e: emit_event(task_id, step_index, tool_result, { tool: tool_name, status: error, error: str(e) }, duration_msnow_ms() - start) raise return wrapped注意summarize函数的作用把可能很大的参数和返回值压缩成摘要避免事件体积失控。摘要策略可以是截断、取哈希、或者只保留关键字段。6.3 检查点写入与恢复的代码骨架检查点写入的时机是每个原子步骤完成后。核心逻辑def write_checkpoint(task_id, step_index, workspace, context): cp_dir fcheckpoints/{task_id} os.makedirs(cp_dir, exist_okTrue) checkpoint { step_index: step_index, timestamp: now_ms(), files: snapshot_file_hashes(workspace), context: context.to_dict(), deps: get_dependency_state(task_id) } with open(f{cp_dir}/step_{step_index}.json, w) as f: json.dump(checkpoint, f)恢复时反向操作先读最近的检查点校验工作区一致性再重建上下文def restore(task_id, workspace): cp load_latest_checkpoint(task_id) current snapshot_file_hashes(workspace) if current ! cp[files]: raise WorkspaceMismatch(diff(cp[files], current)) context Context.from_dict(cp[context]) return cp[step_index] 1, contextWorkspaceMismatch这个异常很重要它把“工作区和检查点不一致”这个情况显式暴露出来而不是让恢复流程带着错误状态继续跑。6.4 编排调度的运行循环调度器的运行循环简化后是这样def run_graph(graph): completed set() failed set() while not all_done(graph, completed, failed): ready [n for n in graph.nodes if n not in completed and n not in failed and all(d in completed for d in n.depends_on) and not any(d in failed for d in n.depends_on)] if not ready: break for node in ready[:MAX_PARALLEL]: result run_task(node) if result.ok: completed.add(node.id) store_outputs(node.id, result.outputs) else: failed.add(node.id)这个循环每次找出所有依赖已满足的节点取前 N 个并行执行根据结果更新状态。MAX_PARALLEL就是前面说的并行上限。6.5 一个完整的编排示例把前面的东西串起来跑一个“重构 补测试 更新文档 人工审查”的完整流程。图定义用前面 YAML 那个例子执行时你会看到refactor-core启动事件流里出现一系列tool_call和file_change每完成一个原子步骤checkpoints/refactor-core/下多一个检查点文件refactor-core完成后add-tests和update-docs同时启动两者都完成后final-review启动但它是个带人工介入的节点跑到一半暂停你在终端确认变更摘要后图继续final-review完成。如果中途add-tests因为某个测试文件冲突失败调度器会标记它失败final-review因为依赖未满足被阻塞但update-docs分支不受影响继续跑完。你修好冲突后可以单独重跑add-tests然后final-review自动解锁。7. 常见问题与排查技巧实录7.1 事件丢失或乱序怎么办事件丢失通常有两个原因写入时没做同步、或者队列满了被丢弃。排查时先看事件日志文件的最后几条记录确认写入是否正常。如果是队列满导致的丢弃检查背压策略把关键事件的优先级调高。乱序问题多出现在多线程或异步场景。解决办法是给每个事件带上单调递增的序号不只是时间戳因为同一毫秒内可能产生多个事件消费时按序号排序。时间戳只用于展示排序一律用序号。7.2 恢复后 Agent 行为异常这是最常见的恢复问题表现是 Agent 恢复后做出和中断前矛盾的决策。根因通常是上下文重建不完整。排查步骤先看检查点里的context字段是否包含了关键决策信息再看恢复时是否正确注入了这些信息。如果上下文没问题但行为还是异常可能是工作区状态和 Agent 认知不一致强制它先做一次现状确认。7.3 编排图卡住不动图卡住一般是依赖判定出了问题。排查时打印每个节点的依赖状态看是不是有节点永远等不到上游完成。常见原因是上游节点失败了但没被正确标记导致下游一直等。另一个原因是人工介入节点没收到外部信号一直阻塞。给调度器加一个超时机制节点等待超过阈值就报警能快速定位这类问题。7.4 常见问题速查表现象可能原因排查方向解决思路事件流中断写入异常或队列满看日志末尾、查队列水位提高关键事件优先级、加同步写恢复后重复改文件步骤非幂等检查文件写入逻辑加哈希校验、改幂等语义编排图卡住依赖判定错误打印节点依赖状态修失败标记、加超时报警检查点写入慢全量快照太频繁看检查点文件大小改增量、降全量频率并行任务互相拖慢并行度过高看资源占用降 MAX_PARALLEL7.5 几条踩坑换来的经验第一条事件 payload 一定要做摘要。我前面提过但值得再强调一次。不做摘要的后果是存储爆炸、查询变慢而且大部分内容你根本不会看。第二条检查点要能独立校验。每个检查点都应该包含足够的信息让你能判断“当前工作区是否和这个检查点一致”。如果检查点只存了步骤序号恢复时你根本不知道文件状态对不对。第三条编排图先跑小规模验证。别一上来就编排十几个节点先用两三个节点跑通流程确认调度、数据传递、失败处理都正常再逐步扩大。我见过太多人直接上大图结果一个节点配置错误导致整图跑不起来排查半天。第四条人工介入节点要放在关键决策点。不是每个环节都需要人但“大规模变更前”和“最终提交前”这两个点加人工确认的性价比极高。第五条日志和事件要能关联。Agent 自己的日志和 Harness 的事件流是两套东西排查时经常需要在两者之间跳转。给它们加一个共同的task_id和step_index能省下大量对时间戳的功夫。这套控制层我用了几个月最大的感受是Coding Agent 的智能程度决定它能做什么而工程控制层决定它能不能被信任地用在真实项目里。前者靠模型进步后者靠工程积累。Pi-Harness 这类东西不会让你的 Agent 变聪明但它能让你的 Agent 变得可靠——而可靠才是它真正能进生产环境的前提。