你用过裸模型——打开 ChatGPT 或 Claude.ai，一问一答，很聪明。你也用过 Claude Code——同一个 Claude 模型，但这次它能读文件、改代码、跑测试、创建子代理分担工作、甚至在你睡着时自主推进任务。同一个模型，为什么表现差距这么大？

答案藏在模型之外的那层软件里。2026 年 2 月，HashiCorp 联合创始人 Mitchell Hashimoto 给了这层软件一个名字：Agent Harness。他提出的核心公式只有五个词：

Coding Agent = AI Model + Harness

本文将深入拆解 Agent Harness 的概念、架构和实现——你将理解为什么它是 AI 编程从" demo 惊艳"走向"生产可用"的关键基础设施，以及如何在自己的项目中思考和设计 Harness。

什么是 Agent Harness

Agent Harness（代理驾驭层）是位于大语言模型与真实世界之间的运行时基础设施。模型生成文本；Harness 决定这些文本能触碰什么、不能触碰什么。

把这个定义展开，Harness 具体负责五件事：

  1. 工具注册与分发：模型说"我想读文件"，Harness 找到对应的 Read 工具，执行它，把结果传回模型
  2. 权限门控：并非所有工具调用都该放行。Harness 在执行前拦截、评估、决定"允许 / 询问用户 / 拒绝"
  3. 上下文管理：模型有上下文窗口限制。Harness 负责压缩旧消息、管理缓存、在需要时把信息归档到持久记忆
  4. 会话状态与记忆：跨会话持久化用户偏好、项目规则、历史决策，让 Agent 不是每次从零开始
  5. 子任务编排：把大任务拆解为子任务，分发给隔离的"子代理"并行执行，然后汇总结果

一句话概括：模型是大脑，Harness 是身体和规章制度。大脑决定"想做什么"，身体和制度决定"实际能做什么、怎么做、做没做对"。

为什么 Harness 不可替代

你可能会问：模型越来越强，GPT-5.4、Claude Opus 4.7 已经能做多步推理了，还需要 Harness 吗？

答案是需要，而且越来越需要。原因有三个：

第一，模型没有操作系统权限。 模型运行在推理服务器上，它无法直接读写你的文件系统、执行 Shell 命令、访问数据库。它只能输出文本。是 Harness 把文本中的工具调用意图翻译成真实的系统操作。

第二，模型无法自我约束。 一个聪明的模型既能写出优雅的代码，也能执行 rm -rf /。模型自身的"安全对齐"是可被绕过的——提示注入、越狱提示词、甚至模型幻觉都可能导致危险操作。Harness 在模型和系统之间设置了程序化护栏——代码逻辑不会被话术说服。

第三，单次推理有上限。 即使是最好的模型，单次推理也有上下文窗口限制（通常是 200K tokens）。一个真实的软件工程任务可能需要读取数百个文件、运行数十次测试、与多个外部服务交互。Harness 负责把长任务分片、压缩历史、用子代理隔离上下文——这些是模型本身不关心的工程问题。

Harness 的核心组件

一个完整的 Agent Harness 由五个子系统组成。它们各自独立、又相互配合，共同构成从"模型输出文本"到"安全完成真实任务"的完整链路。

1. 工具分发系统（Tool Dispatch）

这是 Harness 最外层的接口。模型输出一个结构化的"工具调用"（例如 "调用 Read 工具，参数是 /src/main.py"），Harness 需要完成以下流程：

模型输出 → 解析工具调用 → 匹配注册表 → 参数校验 → 权限检查 → 执行 → 序列化结果 → 返回模型

每一步都可能出错：模型输出的 JSON 格式不对、工具名不存在、参数类型不匹配、执行超时、返回结果太大超出上下文窗口。一个健壮的 Harness 对每种异常都有处理策略——格式错误时尝试修复或重试，结果太大时截断并告诉模型"只返回了前 N 行"。

Claude Code 当前暴露了约 19-40 个工具（数量取决于是否计入 LSP 集成和子代理内部工具），涵盖文件读写、Shell 执行、代码搜索、Web 获取、笔记本编辑等类型。每个工具都有独立的参数 Schema 和权限配置。

2. 权限门控（Permission Gating）

权限系统是 Harness 的安全边界。它的核心逻辑是三级评估链：

deny 规则 → ask 规则 → allow 规则

deny 永远胜出——如果某条规则匹配了"拒绝"，后续的允许规则全部无效。这保证了安全规则的不可协商性。

Claude Code 提供了六种权限模式，从"所有操作都需确认"到"自动批准大多数操作"。2026 年 3 月起，自动模式引入了基于 Sonnet 4.6 的后台分类器——它在工具调用执行前判断操作风险等级，低风险操作自动放行，高风险操作仍弹出确认框。这个分类器本身也是一个模型调用，但它独立于主模型，不受主模型指令的影响——这是 Harness 中"不同层级用不同模型做决策"的典型设计。

权限的另一个维度是作用域：全局配置（~/.claude/settings.json）和项目配置（.claude/settings.json）分开管理，项目级权限不会扩散到其他项目。

3. Hook 系统（Hooks）

如果说权限门控是"规则检查"，Hook 系统就是"程序化拦截"。Hook 是 Harness 中最强大的约束机制——它让规则变成结构性不可违反的代码，而非模型可以忽略的提示文本。

Hook 是外部可执行脚本，Harness 在特定的生命周期事件（工具调用前/后、会话启停、用户提交等）触发它们。流程如下：

Harness 触发事件 → 写 JSON payload 到 Hook 的 stdin → 执行 Hook 脚本 → 读取 exit code
    exit 0 → 放行
    exit 2 → 拦截（stderr 作为拒绝原因返回给模型）

关键设计在于：exit 2 是结构性拦截。无论模型多能说会道，它无法改变一个独立进程的返回值。这解决了 CLAUDE.md 文本规则的固有问题——规则写了但模型可能忽略，尤其是长会话中规则被上下文压缩吞掉之后。

一个真实案例来自 GovForge 项目（2026 年 4 月）：一个 320 行的 PreToolUse:Bash Hook 阻止 Agent 直接推送到受保护分支。它不仅要拦截 git push origin main，还要处理绕过模式：嵌套 Shell（bash -c "git push origin main"）、refspec 改写、链式命令、--force 标志。这个 Hook 成了项目的"代码合入门禁"——任何 Agent 都无法绕过它，因为它是操作系统级别的执行前检查。

Hook 的典型用途：

4. 上下文管理（Context Management）

模型的上下文窗口是有限且昂贵的。一个典型的 Claude Code 会话可能涉及数百次工具调用的往返——如果不加管理，上下文窗口会迅速被工具结果填满，导致模型"忘记"早期的关键信息。

Harness 的上下文管理策略包括：

上下文管理的一个反直觉事实：并非所有信息都值得保留。一个好的 Harness 知道什么该压缩、什么该归档、什么该直接丢弃。这需要理解任务的语义——而这个判断本身也常常由一个独立的"管理模型"来完成。

5. 子代理调度（Subagent Dispatch）

子代理是 Agent Harness 中最能体现"工程思维"的设计。核心思想很简单：不让一个 Agent 的上下文窗口被大量低价值信息污染。

子代理是独立的 Claude 实例，拥有自己的上下文窗口。它接收任务描述，独立工作，完成后只把结果摘要返回给主 Agent。主 Agent 的上下文窗口只看到"结果是什么"，不看到"中间翻了多少个文件、搜了多少次代码"。

Claude Code 内置了三种专用子代理类型：

子代理 定位 典型用法
Explore 快速只读代码搜索 "找到所有调用 auth 模块的文件"
Plan 架构研究与方案设计 "在改 API 之前，先研究现有的错误处理模式"
General-purpose 复杂多步骤任务 "重构 user 模块，把 ORM 调用从路由层抽到 service 层"

2026 年 2 月起，Claude Code 引入了 Agent Teams——多个子代理不再只是向主 Agent 汇报，它们之间可以通过 TaskCreate / TaskUpdate / SendMessage 互相协作，共享任务列表和状态。每个子代理跑在自己的 git worktree 中，文件隔离、互不干扰。

子代理调度的三个关键决策：

Claude Code 的 Harness 架构

现在我们把上面五个组件串起来，看一个完整的 Claude Code Harness 架构。

Claude Code Harness 架构图

上图展示了从用户输入到任务完成的完整链路：

  1. 用户输入进入会话循环
  2. 循环每次迭代：模型生成响应 → 如果只是文本就返回给用户；如果包含工具调用就进入 Harness 层
  3. 权限门控先评估——被 deny 的直接拒绝，需要 confirm 的弹出询问，allow 的放行
  4. 通过门控后，Hook 系统执行 PreToolUse 钩子——任何 exit 2 都会阻断执行
  5. 工具真正执行——可能是文件操作、Shell 命令，也可能是派发子代理
  6. PostToolUse 钩子执行（审计、格式化、通知）
  7. 结果返回模型，进入下一轮迭代
  8. 当模型不再输出工具调用时，循环结束

权限机制的层级防御

Claude Code 的 Harness 提供了四层防御，从软到硬：

层级 机制 性质 被绕过的条件
系统提示（System Prompt） "请勿执行危险命令" 文本约束 提示注入、模型忽略
CLAUDE.md 规则 项目级文本规则 文本约束 上下文压缩吞掉、模型忽略
权限门控 deny/ask/allow 规则 + 分类器 程序化检查 配置错误
Hook（exit 2） 独立进程的 exit code 结构性不可违反 无（除非修改 Hook 脚本本身）

这就是 Mitchell Hashimoto 所说的 Harness Engineering 的核心洞见：真正的安全保障不在提示词里，在代码里。Hook 层是 Harness 的"硬护栏"——它不需要模型的配合，不依赖模型的理解，不因上下文长度而失效。

行业对比：不同的 Harness 实现

Agent Harness 不是 Claude Code 独有的概念。2025-2026 年，主流 AI 平台都在建设自己的 Harness 层。

Claude Code vs OpenAI Agents SDK

维度 Claude Code OpenAI Agents SDK（2026 重构版）
定位 编码 Agent 的完整产品 Agent 构建的 SDK 底座
工具分发 内置 19-40 个工具 + MCP 扩展 开发者自定义工具注册
权限模型 六级模式 + 分类器自动判断 程序化 guardrails
Hook 系统 外部可执行脚本，exit code 驱动 Harness + Sandbox 两层解耦
子代理 Explore / Plan / General-purpose + Agent Teams 开发者自行编排
上下文管理 自动压缩 + 提示缓存 + 记忆系统 开发者通过 SDK 管理

核心区别：Claude Code 是"电池全装"的产品——Harness 的所有组件都预配好了，用户开箱即用。OpenAI Agents SDK 是"零件箱"——给你所有零件，但组装方式由开发者决定。前者适合直接使用的工程师，后者适合构建定制 Agent 系统的平台团队。

2026 年 4 月 OpenAI 的 SDK 重构将 Harness 和 Sandbox 彻底解耦——Harness 管控制流和工具路由，Sandbox 管隔离执行——这是一个重要的架构信号：Harness 和 Sandbox 应该独立演进。

开源生态的 Harness 设计

易鑫的 Harness 治理实践

中国企业易鑫（Yixin）自 2025 年起将 Agent 嵌入汽车金融全流程——智能呼叫、面审、风控、客服——并在 2026 年世界互联网大会宣布已形成 Harness 治理体系。其关键成果：

这验证了一个判断：Harness 是 Agent 从"能说"到"能负责"的必经之路。在强合规行业（金融、医疗、法律），没有 Harness 的 Agent 无法承担真实业务责任。

Harness Engineering：新工种的诞生

Mitchell Hashimoto 在 2026 年 2 月的博客中提出了一个影响深远的观点：AI 时代的工程师职责正在从"写代码实现功能"转向"设计约束 Agent 的系统"。

传统软件工程的核心活动：写代码、修 Bug、优化性能。Harness Engineering 的核心活动：定义权限边界、设计 Hook 策略、编排子代理协作规则、管理上下文生命周期、审计 Agent 行为。

这不是说工程师不再写代码了——而是说除了写代码，工程师还需要设计" Agent 写代码时不能越过的护栏"。一个没有 Hook 的 Claude Code 项目，就像没有 lint-staged 和 CI 的项目：Agent 短期内可能表现正常，但风险随时间累积。

从规则到 Hook 的进阶路径

设计 Harness 不是一蹴而就的。推荐渐进式路径：

  1. 从 CLAUDE.md 开始：定义项目规范、命名约定、禁止事项。这是最轻量的约束
  2. 配置权限设置：在 .claude/settings.json 中设置项目级权限，决定哪些操作自动允许、哪些需要确认、哪些直接拒绝
  3. 添加简单 Hook：从 Stop Hook 开始——Agent 结束时自动运行 lint 和测试。收益立竿见影
  4. 引入 PreToolUse 拦截：在关键操作前插入检查——推送前验证分支名是否合规、执行 SQL 前检查是否有 WHERE 子句
  5. 构建完整的 Harness 策略：组合多层防御，让文本规则（CLAUDE.md）、程序化规则（权限设置）和硬性约束（Hook）形成纵深

关键原则：每一层不能做的事，交给下一层。CLAUDE.md 能管的就别加权限规则，权限规则能拦的就不用 Hook。Hook 是最后一道防线，不是第一道。

总结

Agent Harness 是 2026 年 AI 工程领域最重要的基础设施概念。它的核心认知只有三个：

  1. 模型不是 Agent。模型生成文本，Harness 把它变成真实世界中的行动
  2. 安全靠代码，不靠提示词。越是依赖模型"自觉"的约束，越不可靠。Hook 的 exit 2 胜过一千行文本规则
  3. Harness 需要设计，不只是配置。权限边界、Hook 策略、子代理编排、上下文管理——这些是工程决策，不是运维配置

如果你的团队正在或即将使用 AI Agent 做真实的开发工作，现在就是开始设计 Harness 的时候。从 CLAUDE.md 开始，逐步引入权限设置和 Hook——每一层都不是多余的，因为每一层保护的是不同的失效模式。

参考资料

--:--
加载中…