02 — Agent Harness 架构：Harness 模式解析

Agent Harness 架构：Harness 模式解析

学习目标

理解 CodeWhale 如何将 Harness 架构落地为具体的工程实践，包括失败可见性机制、修正向量注入和递归改进循环。

前置知识

• Agent Harness 架构模式 — Harness 范式的通用原理
• Agent 核心循环设计 — Agent 的 Session/Turn 两层循环

下文假设你已理解上述概念，直接聚焦 CodeWhale 的具体实现。

项目实践

Harness 在 CodeWhale 中的定义

CodeWhale README 开篇即定义：

“A model answers a question. An agent finishes a task. The difference is the harness — a system of rules, evidence, and feedback that keeps the model oriented instead of drifting.”

这不是 Agent 框架（如 LangGraph）的状态图编排，而是围绕模型的约束、证据与反馈系统。

三个核心原则的工程落地

Start with Trust

在代码中的体现：

• 模型每次 turn 从”A”开始——可能性先于确定性
• 用户消息默认善意，不先质疑请求的合理性
• 输入格式仍然验证，但意图默认正面

Clear Jurisdiction

通过 Constitution 九级权限链实现（详见 01 章）。关键实现点：

• prompts/base.md 中七条文 + 九级的完整定义
• EngineConfig.instructions 加载的项目指令被包装为 <instructions source="..."> 区块，明确标注为 Tier 5
• 用户记忆（<user_memory> 块）放在 volatile-content boundary 上方，明确标注为 Tier 7

Recursive Improvement

实现路径：

1. 模型在任务中发现持久性知识
2. 通过 remember 工具写入 ~/.codewhale/memory.md
3. 下一会话启动时加载该文件
4. 模型基于更完整的上下文做出更好决策

失败可见性：修正向量注入

CodeWhale 将失败显式化为修正向量，而非隐藏的错误：

LSP 诊断注入（v0.8.6 引入）：

• 每次 edit_file / apply_patch / write_file 成功后，引擎运行 run_post_edit_lsp_hook()
• 收集 rust-analyzer、pyright、typescript-language-server 等诊断
• 在下一轮 API 请求前，flush_pending_lsp_diagnostics() 将诊断作为合成用户消息注入
• 模型在下一步就能看到错误，不需要等到用户手动运行测试

能力流（Capacity Flow）防护

core/engine/capacity_flow.rs 实现了容量控制的检查点和干预机制：

• 上下文窗口压力检测
• 自动压缩触发建议
• 降级策略：当资源不足时降低期望而非崩溃

问题与规避

陷阱：Harness 与框架混淆

Harness 不是 Agent 框架的替代品。如果任务是”编排 5 个工具的调用顺序”，用 LangGraph；如果任务是”确保模型不会因为收到冲突指令而迷失”，用 Harness。

规避：CodeWhale 本身是一个 Harness，但内部也使用状态图（turn loop）来编排工具调用。Harness 和框架可以共存——Harness 约束模型行为，框架编排执行流程。

陷阱：修正向量过多导致上下文膨胀

如果每次失败都完整注入错误信息，长任务中上下文会被错误信息占满。

规避：CodeWhale 使用截断策略——只保留关键错误信息、退出码和文件路径，完整日志通过 handle_read 按需查询。

设计取舍

Harness vs 软约束

维度	Harness（硬约束）	软约束
可靠性	高——明确的权限链	低——模型可能忽略
维护成本	高——需要持续维护 Constitution	低——自然语言描述即可
灵活性	低——修改 Constitution 需要谨慎	高——随时调整提示词
可迁移性	中——核心原则可迁移，具体条文需要适配	高——自然语言通用

CodeWhale 选择硬约束的原因是 DeepSeek V4 在面对冲突指令时表现出明确的”听从最高权威”行为——这使得正式化的权限链可以实际生效。

为什么 LSP 注入是合成用户消息而非系统提示

LSP 诊断作为”用户消息”注入而非系统提示：

• 系统提示的权重低于用户当前消息（Tier 1 vs Tier 2）
• 工具输出作为证据（Tier 6）比系统提示中的指导（Tier 3-4）更具说服力
• 模型更倾向于响应”用户说有问题”而非”系统说可能有问题”

参考来源

• CodeWhale README: “What Is It?” 和 “How the Harness Works” 章节
• crates/tui/src/core/engine/turn_loop.rs — 流式 turn 循环与工具编排
• crates/tui/src/core/engine/capacity_flow.rs — 容量控制检查点
• crates/tui/src/core/engine/lsp_hooks.rs — LSP 诊断注入钩子