agentic-harness-design

Agentic Harness 设计

用于构建多 Agent 系统的模式，让系统在耗时且复杂的任务中产出高质量结果，涵盖生成器／评估器循环、上下文管理和任务分解。

核心架构：规划器 → 生成器 → 评估器

将工作拆分给三个 Agent，可应对单 Agent 的两种主要失败模式：

1. 上下文退化 — 随着上下文窗口被填满，模型会逐渐失去连贯性；有些模型会出现“上下文焦虑”，过早收尾。
2. 自我评估偏差 — Agent 往往会过度赞扬自己的输出；将产出者与评判者分开是关键手段。

规划器接收简短的用户提示词（1–4 句话），并将其扩展为完整的产品规格。应将内容限定在交付成果和高层架构，而非细粒度的实现细节，以免错误逐级传递。请规划器找出将 AI 原生功能融入规格的机会。

生成器根据规格实现功能。模型需要辅助引导时，按冲刺工作（一次实现一个功能）。更强的模型可以在单次连续会话中运行，并通过 SDK 级别的压缩处理不断增长的上下文。在每个冲刺结束时，生成器会先进行自我评估，再移交成果。

评估器根据约定的标准对生成器的输出进行评分。使用实时浏览器工具（例如 Playwright MCP）与运行中的应用交互，而不是给静态截图打分。产出具体且可执行的改进意见。

冲刺约定

每个冲刺开始前，生成器和评估器会协商一份冲刺约定：生成器提出要构建的内容以及验证成功的方式；评估器审查并同意。这样既能衔接高层规格与可测试行为，又无需事先过度规定实现方式。

通过文件传达约定——一个 Agent 写入，另一个 Agent 读取并以同样方式回应。这能让双方都遵循已约定的范围。

上下文管理

上下文重置与压缩并不等同：

• 压缩会就地总结较早的上下文；同一个 Agent 会继续工作。上下文焦虑可能持续存在。
• 上下文重置会启动一个全新的 Agent，并提供包含先前状态和后续步骤的结构化交接文档。这样可以从干净的起点继续，但会增加编排开销。

当模型表现出上下文焦虑时（可观察到的迹象是过早收尾），应使用重置。更强的模型（例如 Opus 4.6+）通常能维持长时间会话而无需重置，因此压缩已足够。

评估器校准

评估器开箱即用时往往过于宽松。校准步骤：

1. 编写明确的评分标准，体现你的质量要求。将主观判断（“这做得好吗？”）转化为具体、可评分的条目。
2. 使用包含详细评分拆解的少样本示例，为评估器的判断提供参照。
3. 为每项标准设置硬性阈值。任何一项低于阈值，冲刺即告失败。
4. 每次运行后阅读评估器日志。如果其判断与你的判断不一致，就更新提示词以消除差异。
5. 指示评估器保持审慎；相比让生成器学会批判自己，将独立的评估器调校得更严格要容易得多。

对于设计任务，应提高模型默认表现不足的标准（原创性、连贯性）的权重，而降低其擅长处理的标准（功能正确性、技术功底）的权重。

Harness 简化原则

每个组件都体现了一个假设：模型无法独立完成某些工作。随着模型不断改进，这些假设会逐渐过时。每次模型升级后：

• 使用简化后的 Harness 重新运行有代表性的任务
• 一次移除一个组件，并衡量其对输出质量的影响
• 只有在更简单的方法明显不足时，才增加复杂性

随着模型能力提升，冲刺分解、上下文重置和逐冲刺评估循环都可能变成不必要的开销。

何时使用此技能

在以下情况下使用此技能：

• 为运行时间超过单个上下文窗口的任务构建 Agent 控制框架
• 单 Agent 方法的输出质量已达到瓶颈
• 任务包含主观质量维度（设计、用户体验），不适用二元正确性检查
• 需要决定使用上下文重置、压缩，还是全新的会话架构
• 校准评估 Agent，使其能够根据你的质量标准可靠评分