企业官网建设流程全解析

1. 从"能跑"到"敢用"：Coding Agent 落地时被忽略的控制层缺口

Coding Agent 这类工具刚上手的时候，几乎所有人都会被同一件事震住：你丢一段需求过去，它自己读文件、改代码、跑测试、再根据报错回头修，一轮下来真能把一个能跑的东西交出来。但只要你把它放进稍微正经一点的项目里连续用上几天，兴奋感就会迅速被另一种情绪取代——不踏实。它到底改了哪些文件？中间那一步为什么突然重试了三次？上一次跑到一半断了，能不能接着跑？这些问题在 Demo 阶段没人关心，可一旦要把它当成日常研发流程的一部分，它们就变成了决定"能不能用"的关键。

Pi-Harness 这个项目要解决的，正是这个缺口。标题里三个词——可观测、可恢复、可编排——其实精准地概括了 Coding Agent 从"玩具"走向"工程工具"必须补齐的三块能力。所谓 Harness，直译是"挽具、约束装置"，放在工程语境里，它指的是包裹在核心 Agent 外面的一层控制框架：Agent 负责"思考和动手"，Harness 负责"记录、兜底和调度"。这两者职责分离，是理解整个项目价值的前提。

我先把结论摆在这：一个没有控制层的 Coding Agent，本质上是一个不可复现的黑盒。它可能这次跑得很好，下次因为模型采样、文件状态、上下文长度的细微差异就翻车，而你连它为什么翻车都说不清楚。Pi-Harness 的思路不是去改 Agent 的推理能力，而是在它外面套一层"工程外壳"，把每一次执行变成可追踪、可回放、可干预的过程。这个定位非常务实，因为它承认了一个现实：模型能力短期内就这样，工程侧能做的，是把不确定性关进笼子里。

这篇文章适合三类人看。第一类是已经在用各类命令行 Coding Agent、但被它的"不可控"折磨过的开发者；第二类是想把 Agent 接入 CI/CD 或内部研发平台、需要一套稳定控制层的工程团队；第三类是单纯对 Agent 工程化感兴趣、想搞清楚"可观测/可恢复/可编排"到底指什么的技术人。我会尽量把每个设计决策背后的"为什么"讲透，而不是只罗列功能点——因为这类控制层的价值，恰恰藏在那些"为什么这么设计"的取舍里。

需要提前说明的是，Pi-Harness 目前公开的细节有限，下面涉及具体实现的部分，我会基于"一个合格 Agent 工程框架在此情境下最可能采用的方案"来做合理补全，并明确标注哪些是通用实践、哪些是推测性设计。这样你读到的不是一份照抄的文档，而是一套可以迁移到你自己项目里的工程思路。

2. 可观测：把 Agent 的每一步从黑盒里拽出来

2.1 为什么"日志"远远不够

大多数人第一次给 Agent 加"可观测"，做法都是打日志：在关键函数里 print 一下，或者写进一个 log 文件。跑通之后觉得够了，直到某天 Agent 在一个循环里卡了二十分钟，你翻日志发现只有一行"calling model..."，中间发生了什么完全空白。这时候你才意识到，Agent 的可观测和传统服务的可观测，根本不是一个东西。

传统服务的调用链是确定的：请求进来、经过几个函数、返回结果，日志按时间顺序排下来就能还原。但 Agent 的执行是一条带分支的决策树：它可能先读文件 A，再决定改文件 B，改完跑测试失败，回头又去读文件 C 找线索。每一步都是一个"决策节点"，节点之间还有因果关系。你光记时间戳没用，你需要的是把"它为什么走到这一步"也记下来。

所以 Pi-Harness 在可观测这一层，核心要解决的是结构化事件流的问题。它不能只记"发生了什么"，还要记"基于什么信息做的决策"。具体来说，一次 Agent 执行应该被拆解成一系列带类型的事件：模型调用（输入 prompt、输出内容、token 消耗、耗时）、工具调用（工具名、参数、返回结果、是否报错）、文件变更（路径、diff、变更前后哈希）、状态转移（从"规划"到"执行"到"验证"）。这些事件串起来，才构成一条可读的执行轨迹。

2.2 事件模型怎么设计才不臃肿

设计事件模型最容易踩的坑是"什么都想记"，结果事件类型爆炸，几十种类型谁也记不住，最后没人看。我的经验是，事件类型应该按"消费者"来划分，而不是按"发生位置"来划分。谁会消费这些事件？大致三类：调试的人（想知道为什么失败）、审计的人（想知道改了什么）、调度的人（想知道该不该重试）。围绕这三类消费者，事件类型收敛到五到八种就够了。

下面这张表是我在实际项目里验证过的一套最小事件集，Pi-Harness 大概率也在这个范围内：

这张表的关键在于每个字段都有明确的用途，没有为了"完整性"而塞进去的冗余信息。比如file_change里记前后哈希，不是为了好看，而是为了在恢复时能判断"文件是否被外部改动过"——如果哈希对不上，说明恢复点已经失效，不能盲目续跑。这种字段设计，才是可观测真正产生价值的地方。

2.3 轨迹回放：可观测的终极形态

光有事件流还不够，真正让可观测"好用"的，是回放能力。什么叫回放？就是把一次历史执行的事件流，按时间顺序重新"播放"出来，让你像看录像一样复盘整个过程。这比翻日志强太多，因为日志是线性的文本，而回放可以做到：跳到任意一个决策节点、查看当时的完整上下文、对比"Agent 当时看到的"和"实际发生的"。

回放能力的技术前提是事件必须自包含。也就是说，每个事件里要带上足够的信息，让回放时不依赖外部状态。举个例子，tool_call事件如果只记了"调用了 read_file"，回放时你就不知道它读的是哪个文件；必须把参数也记进去。这个要求会推高存储成本，但换来的是回放的可靠性。我的建议是：对高频、低价值的事件做采样，对低频、高价值的事件（如文件变更、错误）做全量记录。这样在成本和可用性之间取得平衡。

提示：回放功能最容易被低估的价值，是它能把"偶发 bug"变成"可复现 bug"。Agent 的很多问题都是概率性的，跑十次错一次，你根本没法调试。有了回放，你可以把那次出错的事件流固定下来，反复研究，直到找到根因。

2.4 一个容易被忽略的观测维度：成本与延迟

大部分可观测方案只盯着"对不对"，忽略了"贵不贵、慢不慢"。但 Coding Agent 恰恰是个成本敏感的场景——它可能一次任务调用几十次模型，token 消耗轻松上百万。如果不在可观测层把成本和延迟记下来，你根本不知道钱花在哪了。

Pi-Harness 这类框架应该把每次模型调用的 token 数和耗时作为一等公民记录下来，并且能按任务、按阶段、按工具聚合。这样你就能回答一些很实际的问题：这个任务为什么这么贵？是模型调用次数太多，还是单次 prompt 太长？哪个阶段最耗时？是模型推理慢，还是工具执行慢？这些问题的答案，直接决定了你后续的优化方向——是换更便宜的模型，还是精简 prompt，还是优化工具实现。

3. 可恢复：让中断不再等于前功尽弃

3.1 为什么 Agent 的"恢复"比普通任务难十倍

普通任务的恢复很简单：记录进度，断了从进度点接着跑。但 Agent 的恢复难在状态太复杂。一个跑了半小时的 Agent 任务，它的状态包括：当前对话上下文、已修改的文件、已执行的工具副作用、内部的规划状态。这四样东西任何一样没恢复对，续跑就会出问题。

举个具体的例子。Agent 改了文件 A，然后基于"文件 A 已改"这个前提去改文件 B。如果恢复时只恢复了对话上下文，没恢复文件 A 的实际内容，那 Agent 续跑时会以为 A 已经改好了，直接去改 B，结果 B 的修改基于一个错误的 A，整个任务就歪了。这就是为什么文件状态的恢复和上下文的恢复必须一起做，缺一不可。

Pi-Harness 在可恢复这一层的核心设计，我推测是检查点（checkpoint）机制。检查点不是简单地存一下对话历史，而是把"恢复所需的最小状态集"打包快照。这个最小状态集至少包括：对话上下文、工作区文件快照（或变更记录）、工具执行记录、当前规划状态。只有这四样齐全，恢复才是安全的。

3.2 检查点该在什么时候打

检查点的时机选择，是个典型的工程取舍。打得太频繁，性能开销大、存储爆炸；打得太稀疏，恢复时回退太多，浪费已完成的工作。我的经验是，检查点应该打在"状态发生不可逆变化之前"。

什么叫不可逆变化？文件写入、外部 API 调用、数据库操作，这些都是。一旦执行了，就没法简单撤销。所以合理的策略是：在执行这类操作前打一个检查点，操作成功后再打一个"确认点"。这样如果操作中途失败，可以回退到操作前的检查点重试；如果操作成功但后续步骤失败，可以从确认点继续。

具体到 Coding Agent 的场景，检查点至少应该覆盖这几个时刻：

• 任务开始前：记录初始工作区状态，作为最终回退的基线。
• 每轮规划完成后：记录 Agent 的规划意图，便于恢复时知道"它本来打算干什么"。
• 每次文件批量修改前：这是最关键的一类，因为文件修改是主要的不可逆操作。
• 每次工具调用前后：对于有副作用的工具（如执行命令、调用外部服务），前后各打一个点。

这套策略听起来检查点很多，但实际可以通过增量快照来控制成本——只存变化的部分，而不是每次全量拷贝。文件快照用 diff，对话上下文用追加式存储，这样单次检查点的开销可以压到很低。

3.3 恢复时的"一致性校验"不能省

恢复最怕的是"看起来恢复了，其实状态已经不一致"。比如你从检查点恢复，但工作区的文件在中断后被别的进程改过了，这时候盲目续跑，Agent 会基于一个它以为正确、实际已经错乱的状态继续操作，后果比直接失败还严重。

所以恢复流程里必须有一个一致性校验步骤。校验什么？至少三样：文件哈希是否与检查点记录一致、对话上下文是否完整、工具执行记录是否连续。任何一样对不上，就应该拒绝自动恢复，转而提示人工介入。这个设计看起来"不够智能"，但它是安全的底线。我见过太多"智能恢复"最后把项目搞乱的案例，宁可保守一点。

注意：一致性校验失败时，不要试图"自动修复"。自动修复的逻辑本身可能出错，而且会掩盖真正的问题。正确的做法是明确报错，把不一致的细节展示出来，让人来判断。

3.4 恢复粒度：从"整任务重跑"到"单步重试"

可恢复能力其实是有层级的。最粗的粒度是"整个任务重跑"，最细的粒度是"某一步单独重试"。Pi-Harness 这类框架的价值，在于它能把恢复粒度做细。

细粒度恢复的前提是步骤之间要解耦。如果 Agent 的每一步都强依赖前一步的内存状态，那你就没法单独重试某一步。解决办法是把每一步的输入输出都显式化——上一步的输出作为下一步的输入，通过事件流传递，而不是通过共享内存。这样任何一步都可以被单独拎出来重跑，只要它的输入还在。

这个设计对 Coding Agent 特别有用。比如 Agent 跑了二十步，第十九步的工具调用因为网络抖动失败了。如果粒度够细，你只需要重试第十九步，前面十八步的成果全部保留。而如果只能整任务重跑，那前面十八步的模型调用成本就白花了。在 token 就是钱的场景下，这个差异非常可观。

4. 可编排：把单次执行变成可组合的工作流

4.1 为什么单个 Agent 不够用

用久了 Coding Agent 你会发现，很多任务它一个人干不好。比如"重构一个模块并保证测试全过"这种任务，它需要先理解代码、再规划重构、再执行、再验证、失败了还要回退重来。这一整套流程如果全塞给一个 Agent 的对话上下文，很快就会超出上下文窗口，而且中间任何一步出错都会污染整个上下文。

更合理的做法是把大任务拆成多个小任务，每个小任务交给一个独立的 Agent 执行，中间用编排层串起来。这就是"可编排"要解决的问题。编排层负责：决定任务的拆分方式、调度各个子任务的执行顺序、在子任务之间传递状态、处理子任务的失败和重试。

这个思路其实和微服务架构很像——单个服务做一件事，服务之间通过明确定义的接口通信，编排层负责整体流程。Coding Agent 的编排也是这个逻辑，只不过"服务"变成了"Agent 执行单元"。

4.2 编排的三种典型模式

在实际项目里，Agent 编排大致有三种模式，各有适用场景：

串行编排是最简单的：任务 A 完成，把结果传给任务 B，B 完成传给 C。适合有明确先后依赖的流程，比如"先分析代码，再生成修改方案，再执行修改"。优点是逻辑清晰、易于调试；缺点是任何一步失败，后面全得等。

并行编排是把互不依赖的子任务同时跑。比如"同时给五个文件加注释"，五个子任务可以并行。优点是快；缺点是状态合并复杂，如果两个子任务改了同一个文件，就会冲突。

条件编排是根据上一步的结果决定下一步走哪条分支。比如"测试通过就走部署流程，不通过就走修复流程"。这是最接近真实研发流程的模式，但也最难实现，因为分支条件需要明确定义。

Pi-Harness 作为控制层，应该同时支持这三种模式，并且允许它们嵌套组合。一个真实的任务往往是"串行为主、局部并行、关键节点带条件分支"的混合结构。

4.3 子任务之间的状态传递是编排的命门

编排最容易出问题的地方，不是调度逻辑，而是状态传递。子任务 A 产出的结果，怎么干净地交给子任务 B？如果传递的是"整个工作区快照"，那太重；如果传递的是"一段文本摘要"，那可能丢信息。

我的经验是，状态传递应该分层：结构化的数据（如文件路径、变更列表、测试结果）用结构化格式传，非结构化的信息（如分析结论、建议）用文本传，两者分开。结构化数据保证机器可处理，文本信息保证语义不丢失。子任务 B 拿到这两样，既能精确操作，又能理解上下文。

还有一个细节：子任务之间不应该共享可变状态。每个子任务应该在自己的隔离环境里跑，产出的变更通过编排层显式合并。这样即使某个子任务跑飞了，也不会污染其他子任务。这个隔离原则，是编排系统稳定性的基石。

4.4 编排层的"可观测"和"可恢复"要打通

单独看，可观测、可恢复、可编排是三件事。但在 Pi-Harness 里，它们应该是一套机制的不同侧面。编排层调度子任务时产生的调度事件，本身就是可观测数据的一部分；子任务的检查点，本身就是可恢复的锚点；而恢复一个编排流程，本质上就是"从某个子任务的检查点重新调度"。

这种打通带来的好处是一致性。如果三套机制各自为政，你会遇到"可观测记录显示任务完成了，但可恢复系统认为它没完成"这种矛盾。而如果它们共享同一套事件流和检查点，就不会出现这种问题。这也是为什么我说 Pi-Harness 的价值不在单个功能，而在于它把这三块能力统一在一个控制层里。

5. 落地这套控制层时，我踩过的和预判到的坑

5.1 别一上来就追求"全自动恢复"

我见过不少团队，做可恢复功能时第一反应是"要能自动恢复，最好用户无感知"。结果做出来的东西，在状态不一致时也硬着头皮自动续跑，最后把工作区搞得一团糟，用户还得手动清理。自动恢复的前提是状态可验证，验证不过就必须停下来。

正确的做法是分级：状态完全一致时自动恢复；有轻微不一致时提示用户确认；严重不一致时拒绝恢复并给出诊断信息。这个分级策略看起来"不够智能"，但它把控制权留给了人，而人恰恰是最后一道防线。

5.2 事件流的存储成本会超乎你想象

Agent 的事件流数据量，比传统日志大得多。一次模型调用的事件，可能就包含几千 token 的输入输出；一次文件变更，可能包含整个文件的 diff。如果全量存储且不压缩，一个中等规模的项目跑一个月，存储就能到几十 GB。

我的建议是分层存储：热数据（最近几天的）全量存，方便回放；温数据（最近几周）只存事件元信息和关键字段，diff 压缩存；冷数据（更早的）只存聚合统计，原始事件归档或丢弃。这个策略能显著降低成本，同时保留近期调试所需的能力。

5.3 检查点的"原子性"必须保证

检查点本身也是个写操作，如果写到一半系统崩了，检查点就是损坏的。恢复时读到一个损坏的检查点，比没有检查点还糟糕。所以检查点的写入必须是原子的：要么完整写入，要么完全不存在。

实现原子性的常见做法是"写临时文件 + 原子重命名"。先把检查点写到临时位置，写完后原子性地重命名到正式位置。这样即使中途崩溃，正式位置要么是旧的完整检查点，要么是新的完整检查点，不会出现半成品。这个细节很小，但漏了它，整个可恢复机制就不可靠。

5.4 编排的"死锁"和"活锁"要提前防

编排多个子任务时，两类问题最容易出现。死锁：子任务 A 等 B 的结果，B 等 A 的结果，谁也动不了。活锁：两个子任务互相重试，谁也成功不了，但系统一直在"忙"。

防死锁的关键是依赖关系必须是有向无环图，编排层在调度前要检测环。防活锁的关键是重试要有上限和退避，不能无限重试。这两个检查应该在编排层强制执行，而不是指望子任务自己守规矩。

提示：编排层最好内置一个"最大执行时间"和"最大重试次数"的硬限制。超过限制就强制终止并报告，避免一个卡住的子任务拖垮整个流程。

5.5 可观测数据本身也要"可观测"

这是个有点绕但很重要的点：你用来观测 Agent 的那套系统，它自己会不会出问题？如果事件采集丢了数据、检查点写入失败了，你怎么知道？所以控制层本身也需要自监控：采集成功率、检查点写入延迟、事件流积压量，这些指标要能被监控到。

我踩过的坑是：某次事件采集因为磁盘满了静默失败，结果那段时间的执行完全没有记录，等发现时已经过去好几天，问题现场早就没了。从那以后，我给所有采集环节都加了健康检查和告警，宁可吵一点，也不能静默丢数据。

6. 把控制层当成产品来做，而不是当成脚本

聊了这么多，最后说点偏"心法"的东西。Pi-Harness 这类项目的成败，往往不取决于技术难度，而取决于有没有把它当成一个产品来做。当成脚本做，你会只关心"功能能不能跑通"；当成产品做，你会关心"用户能不能理解它、信任它、在出问题时能不能自己排查"。

具体到 Coding Agent 的控制层，这意味着几件事。第一，错误信息要说人话。不要甩一个堆栈就完事，要告诉用户"哪一步失败了、为什么失败、可以怎么办"。第二，默认行为要保守。宁可多打一个检查点、多问一次确认，也不要自作主张地"智能处理"。第三，可观测数据要给人看，不只是给机器看。事件流要能渲染成人类可读的轨迹，而不是一堆 JSON。

我自己在做类似工具时最大的体会是：用户对 Agent 的信任，是靠一次次"出问题时它没坑我"积累起来的。可观测让你能解释问题，可恢复让你能挽回损失，可编排让你能控制范围——这三样加起来，才让用户敢把重要任务交给它。技术实现只是手段，建立信任才是目的。

如果你正在给自己的 Coding Agent 加控制层，我的建议是从可观测入手，因为它最容易做、见效最快，而且它的数据是后面两个能力的基础。等事件流跑顺了，再加检查点和恢复；等恢复稳定了，再上编排。一步一步来，别想着一次到位。这套东西的复杂度是叠加的，跳步做，最后一定会在某个环节翻车。

至于 Pi-Harness 本身，它代表的方向是明确的：Agent 的能力会越来越强，但工程侧的控制层不会自动跟上，需要有人专门去做。这个方向上的工作，短期看是"锦上添花"，长期看是"基础设施"。谁先把这套控制层做扎实，谁就能更早地把 Agent 真正用起来。