Agent Harness 架构模式

Agent Harness 架构模式

学习目标

理解 Agent Harness 作为一种架构范式，与 Agent 框架（如 LangGraph、CrewAI）的本质区别。掌握 Harness 的核心设计原则、权威链设计与失败可见性机制。

什么是 Agent Harness

Agent Harness 是一种围绕 AI 模型构建的规则、证据与反馈系统。它的核心目标不是编排工具调用或管理 Agent 状态（那是 Agent 框架的职责），而是防止模型在复杂任务中迷失方向。

Harness vs Agent 框架

维度	Agent 框架（LangGraph/CrewAI）	Agent Harness（CodeWhale 等）
核心关注	状态图编排、工具调度、多 Agent 协作	模型方向感、权威链、验证纪律
解决的问题	”如何让多个工具/Agent 协同工作"	"当模型收到冲突指令时，该听谁的”
架构重心	控制流（状态图、工作流）	约束流（规则、层级、反馈）
失败处理	状态回退、重试、超时	将失败作为修正向量注入模型上下文
典型代表	LangGraph、CrewAI、AutoGen	CodeWhale、部分终端 Agent

Harness 的核心定义

Harness 是一套规则、证据和反馈系统，让模型在面对冲突信息时保持方向感而非迷失。

在典型的 Agent 交互中，模型会同时接收：

• 用户意图（当前消息）
• 项目指令（AGENTS.md、CLAUDE.md）
• 系统默认值
• 工具输出
• 过期记忆
• 人格设定

如果没有明确的权威链，模型会在这些冲突源之间”迷失”——听从过时的项目指令而忽略用户当前的请求，或者根据记忆中的”事实”做出与当前工具输出矛盾的结论。

Harness 的三层核心原则

原则一：Start with Trust（始于信任）

每轮交互从信任出发——可能性先于确定性，工艺先于便利。模型在每次 turn 开始时假设用户意图是善意的、可实现的，而不是先质疑用户请求的合理性。

这不同于防御性编程中的”不信任输入”——Harness 的信任是对用户意图的信任，而非对用户输入格式的信任。输入仍然需要验证，但意图默认正面。

原则二：Clear Jurisdiction（明确的管辖权）

这是 Harness 最核心的设计。必须有一个书面的权威层次体系，明确规定当不同指令源冲突时谁胜出。

典型的九级权限链（从高到低）：

关键规则：

• 用户当前消息 > 过时的项目指令
• 实时工具输出 > 模型假设
• 验证 > 自信（声明）
• 高层级永远不会被低层级覆盖

原则三：Recursive Improvement（递归改进）

Harness 不仅是约束系统，也是自改进系统。模型在执行任务时产生的洞察（新的项目约定、测试中的不稳定行为、代码中的隐含模式）可以被持久化为记忆或指令，供后续会话使用。

递归的闭环：

1. 模型在任务中发现持久性知识
2. 通过记忆工具或技能写入持久存储
3. 下一会话加载该知识
4. 模型基于更完整的上下文做出更好的决策
5. 产生更多持久性知识

Harness 的关键设计模式

验证纪律（Verification Discipline）

每个行动都必须留下证据。这不是建议，是宪法级别的强制要求：

• 文件写入后：回读确认内容
• 命令执行后：检查 stdout，不只检查退出码
• 搜索后：确认匹配结果符合预期
• 声明成功前：有工具结果支撑

验证失败不是”执行出了点小问题”——它是明确的失败，必须报告。

失败可见性（Failure Visibility）

在 Harness 架构中，失败不是隐藏的错误——它们是显式的修正向量：

• 非零退出码 → 注入下一轮上下文
• 类型错误（LSP 诊断）→ 作为用户消息注入
• 沙箱拒绝 → 告知模型权限边界
• 工具超时 → 报告超时原因

模型使用自己的偏差来自我纠正。失败不是终点，是修正的起点。

宪法作为缓存边界

Harness 的宪法/规则体系通常很长（数千 tokens），但它是稳定的——不会在会话内变化。这使得它成为 LLM 提供商前缀缓存（prefix cache）的理想候选：

• 宪法作为系统提示的固定前缀
• 利用 DeepSeek/Claude 的 KV 前缀缓存
• 每次 turn 复用已缓存的宪法 tokens
• 缓存命中的成本约为冷读的 1/100

这使得”写一个长宪法”从成本角度变得可行——一旦缓存，每次 turn 的边际成本极低。

行动者而非叙述者（Agent, Not Narrator）

Harness 明确要求模型是行动者：

• 不要描述你会做什么——现在就做
• 不要以”下一步我会……”结束 turn——现在就执行
• 回答要么包含工具调用，要么给出最终结果
• 对于明显的默认解释，直接行动而非追问澄清

潜在陷阱与规避策略

陷阱一：权限链过于复杂

九级权限链看起来很优雅，但在实际实现中，大多数 Agent 只需要 3-4 级：

1. 安全/宪法约束（不可协商）
2. 用户当前消息
3. 项目指令
4. 工具输出（事实）

规避策略：从简开始，只在发现真实冲突场景时才增加层级。

陷阱二：宪法与模型指令混淆

宪法约束的是行为边界（“不要撒谎”、“验证每个行动”），模型指令定义的是行为方式（“用中文回答”、“先读文件再修改”）。两者不应混在同一个 prompt 层级。

规避策略：宪法条目应该是原则性的、不可协商的；操作指令应该是具体的、可被用户覆盖的。

陷阱三：前缀缓存漂移

当系统提示中”稳定”的部分实际上在 turn 间变化（如动态注入的项目上下文），前缀缓存命中率急剧下降。

规避策略：

• 宪法部分保持静态，不注入动态内容
• 动态内容（项目指令、工具输出）放在宪法之后的独立区块
• 使用 cache_control 标记明确标注缓存边界

设计权衡

优势

• 模型不迷失：明确的权威链让冲突场景下的行为可预测
• 失败可追踪：修正向量让模型的错误成为改进的燃料
• 缓存友好：稳定的宪法前缀降低每轮成本
• 跨模型通用：Harness 原则不依赖特定模型，可迁移

代价

• 宪法维护成本：编写和维护高质量的宪法需要持续投入
• 灵活性受限：严格的权限链可能限制某些创造性场景
• 实现复杂度：需要精确的 prompt 装配和缓存边界管理

替代方案

• 软约束：在系统提示中用自然语言描述偏好，而非正式层级。更灵活但不可靠。
• 工具级约束：在工具层实现安全策略（如审批门），而非 prompt 层。更可靠但覆盖面窄。
• 后处理验证：在模型输出后检查合规性。可以拦截但不预防。

参考来源

• CodeWhale Constitution: prompts/base.md 中的七条文与九级权限链
• ReAct 论文：Yao et al., “ReAct: Synergizing Reasoning and Acting in Language Models”, arXiv:2210.03629
• DeepSeek 前缀缓存文档：https://platform.deepseek.com/api_keys