长时智能体工程化：如何让编码代理跨会话持续交付

一、问题不在“上下文不够长”，而在“状态如何存续”

在长时软件开发任务中，编码代理通常需要在多个离散会话中接力完成工作。一个直观想法是：只要上下文窗口足够大，代理就能读入全部历史信息，从而避免遗忘。但工程实践表明，这种假设并不可靠。

上下文窗口扩大确实提升了单轮可容纳的信息量，却没有解决跨会话状态管理问题。原因有三：

1. 会话本身是离散的。新会话不会自动继承上一轮的完整记忆、操作轨迹与中间决策。
2. 上下文压缩是有损的。摘要可以保留关键推理线索，但未必能完整保存项目状态、验证结果与下一步指令。
3. 信息越多，注意力越分散。将过多历史信息塞入同一窗口，可能降低代理对当前关键任务的判断质量。

因此，长时代理的核心挑战不是“如何记住更多”，而是“如何让系统在丢失部分上下文后依然可恢复、可验证、可继续”。

二、Harness 的本质：模型之外的工程约束

Harness 这个词在工程语境中常被理解为“测试夹具”或“执行框架”。在长时代理场景下，它指的是模型外部的工程脚手架，用于约束代理行为、保存任务状态、验证交付结果。

一个典型的 harness 至少包括以下要素：

• 提示词与任务模板；
• 工具调用约定；
• 文件结构约定；
• 增量执行循环；
• 自动化测试；
• 进度记录与恢复机制。

可以把编码代理理解为一个执行单元，而 harness 则是让这个执行单元能够稳定运行的操作系统。模型能力决定单步质量，harness 决定长程稳定性。

三、从“一次完成”转向“增量交付”

传统脚本式代理倾向于一次性生成完整实现。但在长时任务中，一次性交付会带来两个严重问题：

• 错误难以定位。当多个功能同时改动时，验证失败很难归因到具体变更。
• 状态难以恢复。一次失败可能导致大量中间信息丢失，后续会话无法接续。

更稳健的方式是引入增量交付模型。每个会话只处理一个可验证的功能单元，完成以下步骤后进入下一轮：

读取交接信息 -> 理解当前状态 -> 实现一个功能
-> 运行验证 -> 提交代码 -> 写入新的交接信息

这种方式的优势在于：

1. 每次提交都是一个可回滚的检查点；
2. 验证范围明确，失败可快速定位；
3. 下一轮代理无需遍历全部历史，只需读取结构化交接文件。

四、功能清单不是进度计分板

一个常见误区是：把功能清单中“已完成”的数量视作项目进展。事实上，功能数量只描述“做了多少”，无法单独回答“系统是否变得更好”。

考虑一个场景：清单中已有 180 项功能标记为通过，下一轮代理新增一项聊天功能，通过数变为 181。但这项改动恰好破坏了登录流程。如果只看清单，项目多完成了一项；如果看整体产品，关键用户链路发生了退化。

这说明，长时代理需要的不只是任务列表，而是包含三层信息的状态视图：

4.1 当前系统处于什么状态

包括代码版本、构建状态、关键配置和已知问题。

4.2 哪些结果经过验证

区分“已实现”与“已验证”。只有通过对应测试的功能，才能进入可信交付集合。

4.3 发生错误后能否恢复

是否保留可回滚的提交点，是否有明确的恢复路径，是否能重建验证环境。

五、单元测试之外：端到端验证的必要性

单元测试和接口检查通常只能验证局部正确性，无法发现跨模块链路问题。例如，某个接口单独调用正常，但真实用户流程中的跳转、状态传递和数据依赖可能已经失效。

在长时代理场景中，应引入端到端验证机制。简单情况下，可以通过脚本模拟用户路径；更复杂的场景下，则需要借助浏览器自动化能力，按照真实交互流程验证关键链路。

端到端验证不需要覆盖所有路径，但应至少覆盖以下三类：

• 核心用户流程，如登录、注册、支付、内容发布；
• 跨功能依赖路径，例如新增功能与已有模块的交互；
• 回归风险较高的历史缺陷场景。

通过这种分层次的验证体系，可以在“验证成本”与“可信程度”之间取得平衡。

六、结构化交接是跨会话协作的关键

如果每一轮代理都重新理解整个项目，成本会随项目复杂度指数上升。更高效的方法是定义标准化的交接文件，使其成为唯一事实来源的一部分。

交接文件至少应包含：

1. 当前项目版本与最近提交
2. 上一轮完成的功能及其验证状态
3. 已知问题与风险点
4. 下一轮建议任务
5. 需要特别关注的约束条件
6. 可复现验证命令

这样，每一轮代理不需要依赖“记忆”，而是依赖结构化状态。即使上下文被截断，也能快速恢复工作现场。

七、可观测条件下的“可靠”是什么意思

长时代理语境下的“可靠”，不应被理解为“永不失败”，而应定义为：

• 每次任务都有明确输入和预期输出；
• 每个交付单元都有对应验证；
• 每次失败都有可追踪的现场；
• 每个会话都有明确的恢复路径。

换句话说，可靠不是一次成功的同义词，而是系统在连续失败后依然能够回到正轨的能力。

八、实践建议：从最小框架开始

对于希望落地长时代理的团队，不必一开始就构建复杂系统。可以从以下最小框架起步：

首次会话：
- 建立需求清单
- 初始化仓库与启动脚本
- 创建进度文件和交接模板
- 完成首个可验证功能
后续会话：
- 读取交接文件
- 实现一个功能
- 运行验证
- 提交代码
- 更新交接文件

当团队发现“功能已完成但整体质量下降”的情况频繁出现时，说明需要引入更强的端到端验证与问题追踪机制。

九、结论：信任来自可验证的工程结构

长时编码代理的瓶颈不只在模型能力，更在于工程结构。上下文管理、功能清单、增量提交、端到端验证与交接文件，共同构成一套可验证的工作体系。

这套体系不假设代理不会犯错，而是假设错误必然发生，并通过工程手段让系统在错误后仍能继续前进。这正是 harness 工程化的核心价值。