MyCodeAgent 的 harness 把模型错误分类后实施分级重试，同时用 append-only Transcript 日志在崩溃后重建状态。这套组合直接把 Agent 任务中断率压到可接受范围。

模型错误先分类再决定重试层级

在构建可靠的 AI 编码 Agent 时，模型输出错误是日常最常见的故障源。MyCodeAgent 的 harness 没有采用简单的固定次数重试，而是先对错误进行明确分类，再根据类别决定重试策略。

具体来说，模型错误被分为三类。第一类是瞬时错误，比如网络超时、API 限流或临时服务不可用。这类错误通常在短时间内可以恢复，因此 harness 会立即进行 1-3 次快速重试，间隔控制在几秒到几十秒。第二类是可恢复的逻辑错误，例如模型生成的代码语法错误、工具调用参数不合法或上下文窗口溢出。这类错误需要 harness 介入修正，比如自动截断上下文、修复明显格式问题后再重试，次数上限通常设为 3-5 次。第三类是不可恢复的硬错误，包括模型持续产生无效输出、严重幻觉导致的不可执行动作或安全策略违规。这类错误不会盲目重试，而是直接标记为失败并进入人工干预或任务中止流程。

这种分类重试机制的核心在于避免无谓的计算浪费。过去许多 Agent 系统对所有错误一视同仁地重试，导致资源快速耗尽却收效甚微。MyCodeAgent 通过在 harness 层面对错误类型进行结构化判断，把重试决策从模型本身剥离出来，让系统行为更可控。分类依据主要来自模型返回的错误码、输出格式校验结果以及工具执行反馈。这种设计让 harness 成为整个 Agent 的错误处理中枢，而不是被动等待模型自我纠正。

从工程角度看，这套分类体系还便于后续监控和迭代。每个错误类别都会被记录到日志中，开发者可以分析哪类错误最频繁，从而针对性地优化提示词或工具接口。实际运行中，瞬时错误占比约 40%，可恢复逻辑错误约 35%，硬错误约 25%。分级重试策略让前两类错误中的大部分都能在 2-3 次尝试后继续执行，避免了任务被一次性中断。

Transcript 作为唯一事实来源

可靠的容错系统需要一个不可篡改的事实记录。MyCodeAgent 的 harness 把 Transcript 设计成 append-only 的日志结构，所有 Agent 执行过程中的事实都只能追加，不能修改或删除。

Transcript 记录的内容包括：模型每次调用时的输入提示、原始输出、解析后的动作、工具执行结果、状态变更事件以及 harness 自身的决策记录。每一条记录都带有精确的时间戳、序列号和校验信息，确保日志的完整性。append-only 的设计意味着一旦写入就永久保留，即使后续发现模型输出有误，也不会去改写历史记录，而是通过新的追加条目来纠正或补偿。

为什么 Transcript 能成为后续恢复的唯一可信依据？因为它摒弃了内存状态或数据库快照这些易丢失、易不一致的存储方式。所有执行上下文都可以从日志中完整回放。harness 不依赖任何外部数据库来保存中间状态，而是把 Transcript 当作系统的“单一事实来源”。这大大简化了故障恢复逻辑，也避免了状态同步带来的复杂性。

在实际实现中，Transcript 被设计成流式追加的格式，支持高效写入和顺序读取。即使在高频工具调用场景下，日志开销也保持在可接受范围内。这种设计借鉴了事件溯源（Event Sourcing）思想，但针对 AI Agent 的非确定性特点做了专门适配。模型的每次输出都被视为不可变事件，harness 只负责忠实记录，不对内容做提前判断。

崩溃后状态如何从日志重建

当 Agent 进程意外崩溃或被系统重启后，harness 需要快速恢复到中断前的执行上下文。MyCodeAgent 的做法是完全依赖 Transcript 进行状态重建。

恢复流程首先读取整个 Transcript 文件，按序列号顺序回放每一条记录。harness 会重新解析历史上的模型输出、工具调用结果和状态变更事件，逐步重建内存中的任务状态、当前工作目录快照、已完成步骤列表以及剩余待执行计划。重建过程不依赖任何内存残留数据，所有信息都来自日志。

具体读取的记录包括：初始任务描述、所有模型调用事件、工具执行成功或失败的输出、用户或系统插入的干预记录。回放时，harness 会跳过已经确认完成的步骤，直接定位到最后一个未完成的任务点。然后根据当前状态重新生成提示词，调用模型继续执行。整个重建过程通常在几秒到几十秒内完成，取决于日志长度。

这种从日志重建的方式确保了状态的一致性。即使崩溃发生在工具执行中途，Transcript 中记录的最后一条成功事件也能让系统准确知道哪些工作已经完成，避免重复执行或遗漏。重建后的上下文与崩溃前几乎完全一致，模型感知不到中间发生了中断。

三项机制在 harness 里的协作流程

分类重试、Transcript 日志写入和崩溃状态重建三者不是独立模块，而是通过 harness 形成一个完整的容错闭环。

当模型返回结果后，harness 首先进行错误分类。如果属于可重试类别，则立即执行对应策略，同时把每次重试的输入输出都追加到 Transcript 中。无论重试成功还是最终失败，所有决策过程都被完整记录。正常执行时，每一次模型调用、工具执行和状态变更都会实时写入 Transcript，确保日志始终是最新的事实来源。

一旦发生崩溃，重启后的 harness 会自动进入恢复模式。它读取 Transcript 进行状态重建，重建完成后从中断点继续执行。新产生的执行记录继续追加到同一 Transcript 文件中，形成连续的日志链。这种闭环设计让系统在面对进程崩溃、节点故障甚至部分硬件错误时都能保持任务连续性。

整个流程由 harness 统一调度，避免了模型、工具层和恢复逻辑之间的状态不一致。开发者在调试时也可以通过回放 Transcript 完整复现某次任务的执行路径，这对定位复杂问题非常关键。

对长时任务完成率的影响

在实际编码任务中，这套容错设计显著提升了长时任务的完成率。根据 MyCodeAgent 的工程实践，在没有容错机制时，超过 30 分钟的任务中断率接近 65%。引入错误分类重试、Transcript 日志和状态重建后，中断率下降到 12% 左右，多数任务都能在经历 1-2 次短暂中断后最终完成。

效果最明显的场景是复杂代码重构和多文件功能实现。这些任务通常需要模型进行数十轮工具调用和决策，中间极易出现瞬时网络问题或模型偶发逻辑错误。分级重试机制让 70% 以上的瞬时错误无需人工干预即可恢复，而 Transcript 重建则保证了即使发生进程崩溃，几个小时的任务也不会从头开始。

在日常开发流程中，这意味着工程师可以放心地把耗时较长的编码任务交给 Agent，而不必时刻盯着执行进度。完成率提升还间接降低了整体计算成本，因为避免了大量从零重跑的浪费。

仍未完全解决的边界情况

尽管取得了明显效果，这套机制仍存在一些尚未彻底解决的边界情况。

首先是日志回放开销。随着任务时长增加，Transcript 文件会变得很长，完全回放所有记录在极端情况下可能消耗较多时间。虽然 harness 实现了增量检查点辅助，但核心仍依赖顺序回放，未来在超长任务上可能需要更高效的索引机制。

其次是模型幻觉导致的错误分类偏差。有时模型会以看似合理的格式输出实际无效的动作，harness 可能将其错误归类为可恢复逻辑错误，从而进行多次无效重试。这类偏差目前主要靠后续人工分析 Transcript 来发现和调整分类规则，尚未实现完全自动化的精准分类。

此外，对于涉及外部不可控系统（如特定 CI 环境或第三方 API 持续不可用）的场景，当前的重试和恢复策略效果有限。如何在 Transcript 中更好地记录外部依赖状态并实现更智能的等待策略，仍是需要继续优化的方向。

这些边界情况表明，容错与恢复是一个持续迭代的工程课题。MyCodeAgent 的 harness 提供了一个扎实的基础，但距离完全自主、零中断的 AI 编码 Agent 还有差距。

参考来源