企业官网建设流程全解析

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 分四层：

这四层里，运行时层是核心，也是和 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 里存什么？三样东西：

1. 任务状态：当前在第几步、目标是什么、已完成哪些子目标。
2. 环境快照：工作目录的 git commit hash（如果有）、关键文件的 hash。
3. 上下文摘要：不是完整消息历史，而是压缩后的摘要，避免恢复时上下文爆炸。

3.2 恢复流程：从哪断，从哪续

恢复不是简单地“重放最后一步”，那样会重复副作用。正确的恢复流程是：

1. 加载最近的 checkpoint，得到任务状态和环境快照。
2. 校验当前环境是否和快照一致（文件 hash、git 状态）。
3. 如果不一致，说明 checkpoint 之后环境被外部改过，需要提示用户或自动 rebase。
4. 一致的话，从 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_pass

loop是状态机能力的体现：tester 节点可以循环最多 3 次，直到测试通过。这种“DAG 套循环”的结构，比纯 DAG 或纯状态机都更贴合实际开发流程。

4.2 Agent 间通信：共享工作区还是消息传递

多 Agent 协作最大的争议点是：它们怎么交换信息？两种做法：

• 共享工作区：所有 Agent 操作同一个文件系统，通过文件交换信息。
• 消息传递：Agent 之间通过消息队列通信，各自有独立工作区。

我两个都用过，结论是共享工作区为主，消息传递为辅。原因是编码任务的产物本质就是文件，让 Agent 直接改文件最自然，也最容易被人类 review。消息传递适合传递“意图”和“反馈”，比如 reviewer 给 coder 的修改意见，走消息通道更清晰。

Harness 里的实现是：每个 Agent 节点挂载同一个工作区卷，同时有一个轻量的消息总线用于节点间通信。消息总线我用了最朴素的文件队列，每个节点一个 inbox 目录，写文件就是发消息，读文件就是收消息。简单、可观测、可重放。

4.3 冲突处理：两个 Agent 改同一个文件怎么办

这是多 Agent 编排里最头疼的问题。我的处理策略分三层：

1. 预防：编排阶段就做文件级依赖分析，如果两个节点会改同一文件，强制串行。
2. 检测：运行时拦截器监控文件变更，发现并发写同一文件立即告警。
3. 解决：如果已经冲突，用 git 的三方合并能力自动合并，合并失败则暂停并交给人类。

第一层能解决 80% 的问题。做依赖分析时，我让 planner Agent 在拆解任务时就标注每个子任务涉及的文件，Harness 据此构建文件依赖图，有交集的节点自动串行化。

注意：文件依赖分析不可能 100% 准确，Agent 经常“顺手”改了计划外的文件。所以第二层的运行时检测不能省。我踩过的坑就是太信任静态分析，结果两个 Agent 同时改了一个配置文件，互相覆盖，排查了半天。

5. 常见问题与排查技巧实录

5.1 问题速查表

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 的方向——与其换更强的模型，不如把上下文管理做好。这个体会，可能比任何技术细节都值钱。