Harness Agent 的组成要素：从七层到八层横切面的完整模型

前文《AI 友好型架构：从 Context Engineering 到 Harness Engineering》提出了一个七层 Harness 体系。经过一段时间实践，以及对照了 LangChain 的 Agent Harness 拆解、Anthropic 的 Building Effective Agents 方法论、Martin Fowler 的 Harness Engineering 框架和 2026 年提出的 AI Harness Engineering（AHE）研究之后，我对这个模型做了大幅调整。

这篇文章先给出最终的完整模型，然后逐层说明每层的职责、当前覆盖和缺失，最后解释为什么需要把三个不同性质的能力区分开。

完整模型

这套体系核心想表达的是 Harness 不是给模型堆一组能力，而是把「任务契约—执行—环境反馈—验证—归因—演进」做成一个可运行、可审计、可恢复、可持续改进的闭环系统。

对照 2026 年提出的一套 AI Harness Engineering 框架将 Harness 责任拆成了 11 项：任务规格、上下文选择、工具访问、项目记忆、任务状态、可观测性、失败归因、验证、权限、熵审计和人工干预记录。当前模型明确覆盖了约 8 项（arXiv 2605.13357）。

三种性质的能力

在逐层展开之前，先说明一个关键的结构调整：原来的七层全部堆叠在一起，掩盖了不同能力之间的性质差异。实际应分为三个面：

数据面（层①~⑤）是 Agent 执行任务的主链路，从任务契约到最终产物生产，数据单向流动。

控制面（层⑥ + 治理）横切所有层，负责约束和观察。治理控制每层允许做什么，可观测性记录每层实际做了什么。

演进面（层⑦⑧）根据运行结果改进整个 Harness。它消费控制面的数据，通过失败归因形成修改假设，再通过验证确定收益。

① 任务规格与完成契约

最明显缺失的独立能力。当前没有明确回答：Agent 到底被要求完成什么？怎样才算完成？

当前覆盖：不完整。Claude Code 的 CLAUDE.md 和 Agent Skills 提供了一部分前馈指导，但缺少结构化的任务契约。没有这一层，Planner 不知道如何正确分解，Validator 不知道该验证什么，Agent 不知道什么时候应该停止。

建议包含：

• 用户意图澄清
• Task Spec：目标、范围、非目标
• 约束条件（允许修改路径、禁止修改路径）
• 需求分解
• Acceptance Criteria
• Definition of Done（可执行验证器）
• 输出 Schema
• 风险等级
• 完成证据要求

一个任务契约不应只是「修复订单页面卡顿」，而应形成：

goal: 修复订单页面首次渲染卡顿
scope:
  allowed_paths: [app/order/**]
  forbidden_paths: [infrastructure/**]
acceptance:
  - 首屏 P95 < 1200ms
  - 所有现有测试通过
  - 不改变接口 Schema
evidence:
  - benchmark-before.json
  - benchmark-after.json
  - test-report.xml

② 执行环境与工具

当前覆盖：方向正确，但范围偏窄。目前有 Agent Loop、Tool Registry、Sandbox，这是 Harness 最基础的部分。

业界广义定义（LangChain: The Anatomy of an Agent Harness）通常还包括文件系统、执行环境、工具与技能、Hook/Middleware、状态维护和确定性反馈机制，而不只是工具调用。

建议补充：

• Environment Manager：容器、工作区、依赖安装、网络环境
• Tool Gateway：参数校验、超时、重试、限流、幂等
• Hook / Middleware：工具调用前后拦截、自动压缩、自动续跑、测试钩子
• Checkpoint / Resume：长任务断点恢复
• Cancellation / Deadline：任务取消、超时和最大步数
• Artifact I/O：代码、Diff、报告、截图、构建物的读写

③ Agent 运行时与编排

当前覆盖：Planner / Coder / Validator / Refiner 是一种具体的 Agent 拓扑，不是编排层本身。

一个完整的编排能力应同时支持（Anthropic: Building Effective Agents）：

• 单 Agent 自主循环
• 确定性 Workflow / DAG
• 多 Agent 分工
• Sub-agent 动态创建
• Handoff（Agent 间交接）
• 并行、串行、投票、竞争
• 模型路由（不同任务选不同模型）
• 停止条件（最大步数、预算、通过验证）
• 预算与并发控制

Anthropic 对 Agent 架构的划分也区分了单 Agent、固定工作流、Orchestrator-Workers 和 Evaluator-Optimizer 四种模式，而不是把多 Agent 当成必选项。

④ 上下文、知识与技能

当前覆盖：较好。Token 预算、压缩、AGENTS.md 注入都有。但更偏向「上下文装载与容量管理」。

Martin Fowler 的 Harness 模型（Harness engineering for coding agent users）指出：上下文工程是让 Agent 获得 Guides 和 Sensors 的手段。AGENTS.md 只是其中一种前馈 Guide，而测试、Lint、日志等则属于反馈 Sensor。

建议补充：

• Context Selection：当前任务到底需要哪些文件和信息
• Retrieval：代码搜索、文档检索、符号检索、历史任务召回
• Context Assembly：按当前步骤动态组装，而不是一次性塞满
• Provenance：上下文来自哪里、版本是什么、是否过期
• Scope Control：禁止无关目录、秘密文件进入上下文
• Context Cache：减少重复的上下文构建
• JIT Context：需要时才加载工具定义和材料

⑤ 状态、记忆、产物与技能：四种不同东西

这是当前模型最大的结构问题。原七层将「会话状态 / 项目记忆 / 技能系统」放在了一起，但它们属于完全不同的概念。

Task State 任务状态

回答「正在做到哪里」：

• 当前计划、已完成步骤、Pending TODO
• 当前分支、已执行测试
• 子 Agent 状态、失败次数
• Lease、锁和任务心跳

服务的是：断点续跑、并发协作和流程一致性。这不是 Memory。

Memory 长期记忆

回答「过去学到了什么」：

• 用户偏好、项目约定
• 历史失败经验、某类任务的最佳策略
• 模块负责人、架构知识
• 已验证的经验规律

服务的是：跨任务复用经验。这不是当前任务的进度记录。

Artifact 产物

记录「本次任务生产了什么」：

• 代码 Diff、计划文档、测试报告
• 构建产物、截图、失败日志
• 验证报告、Episode Package

Artifact 应有命名、版本、来源、生命周期和权限。Google ADK 也将 Artifact 独立于 Session、State 和 Memory 进行管理（Google ADK Artifacts）。

Skill 技能

回答「Agent 能做什么以及怎么做」：

• 操作指南、Prompt、脚本
• 工具组合、触发条件
• 输入输出 Schema、验证方法

AHE 研究发现，性能提升更多来自工具、Middleware 和长期记忆，而不只是 System Prompt，这也说明这些组件必须能被分别表达、修改、评测和回滚（arXiv 2604.25850）。

建议：在概念模型中拆开，物理实现可以共用文件系统或数据库。

⑥ 可观测与归因

当前覆盖：轨迹、事件图、Token 追踪都有。但「看到了什么」不等于「知道为什么失败」。

完整可观测性还应包括：

• Prompt / Context 快照（每次 Agent 调用时的完整上下文）
• Tool 输入输出
• Agent 与子 Agent 调度关系
• 模型、工具、Skill、配置版本
• 延迟、Token、费用
• 重试、超时、取消
• 环境状态变化
• 文件与 Artifact 变化
• 用户审批与人工干预

尤其要建立失败归因因果链：

否则 AHE 很容易退化成：失败了 → 随便改 Prompt → 再跑一次。

AI Harness Engineering 框架也明确把 failure attribution、entropy auditing、intervention recording 列为独立责任，而不只是 Trace（arXiv 2605.13357）。

⑦ 验证与质量闭环

这是在线闭环，在 Agent 执行过程中持续发生：

• 编译是否通过
• 单测是否通过
• 功能是否满足需求
• 是否引入回归
• 是否符合架构规范
• 是否满足 Definition of Done
• 是否可以结束 Agent Loop

Martin Fowler 的 Harness 模型强调，Agent 需要同时具备前馈 Guide 和反馈 Sensor。测试、静态分析、日志和审查 Agent 都属于反馈控制，用于在结果到达人类之前自我修正。

注意：不要把 Verification 和 Evaluation 混为一层。

⑧ 评测与演进控制面

这是离线或准在线评估，跨任务、跨模型、跨版本：

• 通用 Benchmark
• 领域任务集
• 回归套件
• 多次 Trial、Pass@k
• 成功率、成本、延迟
• 安全违规率、人工接管率
• 长任务完成率、跨模型迁移效果

Agent 评测通常需要任务、环境、多轮执行和多个 Grader，而不是只评最终文本。同一任务还需要多次 Trial 来对抗随机性（Anthropic: Demystifying evals for AI agents）。

AHE：不是 Eval 的子功能

AHE（Agentic Harness Engineering）是一个元闭环，它消费 Eval 和 Trace 的输出，再反向修改 Harness 组件：

2026 年提出的 Agentic Harness Engineering 中，AHE 依赖三个可观测支柱（arXiv 2604.25850）：

1. 组件可观测：所有可编辑 Harness 组件都有显式、可回滚的文件级表示
2. 经验可观测：将海量轨迹压缩成可钻取的经验语料
3. 决策可观测：每次修改先声明预期，再用下一轮结果验证

横切控制面：安全、权限与治理

当前覆盖：审批门、Sandbox、YOLO Classifier 都有价值，但主要解决的是「这次操作要不要允许？」

治理还应包括：

• Agent 身份与租户隔离
• 最小权限授权
• 文件、命令、网络、MCP 的独立权限
• Secrets 管理
• 数据分类和脱敏
• Prompt Injection 防御
• Policy Engine（策略引擎）
• 预算、Token、调用次数配额
• 人工接管和升级策略
• 审计日志、人工干预记录
• 操作影响范围和回滚能力

YOLO Classifier 更适合作为权限决策机制之一，而不是治理层的代表能力。

最终判断

原始七层体系已经足够作为一个对外介绍版的一级能力地图。但要真正指导平台建设、团队分工和技术规划，至少要做四个调整：

1. 新增任务规格与完成契约（层①）
2. 把在线 Verification 从离线 Eval 中拆出来（层⑦ vs 层⑧）
3. 把 State、Memory、Artifact、Skill 分开（层⑤内部）
4. 把 Governance、Observability、AHE 改成横切控制面与反馈回路

最核心的一句话是：Harness 不是给模型堆一组能力，而是把「任务契约—执行—环境反馈—验证—归因—演进」做成一个可运行、可审计、可恢复、可持续改进的闭环系统。