Hook 机制为什么是 Agent Harness 最重要的资产

1. 这篇文章想表达什么

最近我在整理 Agent Harness 的工程化经验时，越来越明确一个判断：真正可靠的 Agent 系统，核心资产不是一段很长的 Prompt，而是一套可治理的执行链路。

Prompt 和 Skill 可以告诉 Agent 应该怎么做，但它们本质上仍然是“说明书”。说明书越长，Agent 越容易遗漏；说明书越分散，后续越难维护。生产级 Agent Harness 不能只靠文字约束模型，而要把关键规则沉淀到 MCP、Hook、权限、审计和验证机制里。

我的结论是：

• Prompt 负责指路：告诉 Agent 去哪里找规则和能力。
• Skill 负责教程：告诉 Agent 一类任务应该按什么流程完成。
• MCP 负责能力：把可执行操作封装成结构化、可校验的工具。
• Hook 负责强约束：在系统层拦截、检查、修正和拒绝不合规行为。

如果说 Agent Loop 让 Agent 能“动起来”，那么 Hook 系统让 Agent 能“被管住”。

2. 第一原则：保持唯一真相源

Agent 系统最容易失控的地方，是同一条规则被写在太多地方。

例如：

• system prompt 里写一份规则；
• skill.md 里再写一份规则；
• 项目文档里又写一份规则；
• 工具脚本里隐含另一份规则；
• 团队经验靠口口相传。

短期看，每个地方都“补充了一点说明”；长期看，规则开始冲突，Agent 不知道该听谁的，维护者也不知道该改哪里。

更合理的方式是明确边界：

System Prompt → 告诉 Agent 去哪里找能力和规则
Skill.md      → 描述任务流程、适用场景和调用方式
MCP Tool      → 提供真正可执行、可校验的操作
Hook          → 执行前后做强制检查和治理
Docs          → 解释背景、原则和人类维护说明

这里的重点不是“文档不能写规则”，而是不要把必须执行的强约束只写在文档里。只写在 Markdown 里的规则，最多是建议；进入 MCP 和 Hook 的规则，才真正变成系统行为。

所以我更推荐把规则分成两类：

• 解释性规则：写在文档或 Skill 中，用来帮助人和 Agent 理解背景。
• 强制性规则：写进 MCP、Hook、权限系统、校验器和测试中，用来保证一定执行。

这就是“唯一真相源”的核心：不是所有信息都放在一个文件里，而是每类信息都有唯一负责的层。

3. MCP 的价值：把能力变成可控边界

MCP 的价值不只是“多了一种调用工具的协议”。从工程角度看，它更重要的作用是把外部操作封装成可治理的边界。

相比让 Agent 直接拼 bash 命令，MCP 通常更适合承载自定义能力：

• 参数可以结构化定义，减少自然语言歧义；
• 输入可以统一校验，避免危险参数直接执行；
• 输出可以结构化返回，方便 Agent 判断下一步；
• 权限可以集中管理，避免每个脚本各管各的；
• 日志和 Trace 可以统一记录，方便复盘和审计。

这并不是说 bash 没价值。bash 适合快速验证和本地操作，但如果某个动作会被 Agent 反复调用、影响关键状态、涉及权限或有失败恢复需求，就应该考虑封装成 MCP。

一个实用的判断标准是：

一次性操作 → bash 可以接受
可复用操作 → 脚本化
高频/高风险/跨环境操作 → MCP 化
必须强约束的操作 → MCP + Hook

如果确实需要让 Agent 执行 bash，我也更推荐让 bash 调一个受控脚本，而不是让 Agent 每次自由拼一长串命令。脚本内部可以做参数检查、路径约束、dry-run、日志记录和错误提示，这比依赖 Agent 记住所有注意事项可靠得多。

4. Hook 是 Harness 的治理层

这里说的 Hook，不只是一种单点插件机制，而是广义上的“执行链路拦截层”。它可以出现在 App Server、CLI Runtime、MCP Server、工具调用前后、文件写入前后、命令执行前后。

Hook 的本质是：在 Agent 的指令真正产生影响之前或之后，插入系统级处理逻辑。

常见 Hook 可以分成几类：

• Pre-check Hook：执行前检查权限、路径、参数、风险等级和上下文状态。
• Post-check Hook：执行后检查结果、产物、日志、格式和是否需要补救。
• Policy Hook：根据规则拒绝危险操作，例如越权访问、删除敏感目录、泄露密钥。
• Reminder Hook：在关键时机提醒 Agent 补充验证、记录原因或走人工确认。
• Audit Hook：记录输入、输出、耗时、调用方、影响范围和失败原因。

为什么 Hook 重要？因为 Agent 可能会忘记 Skill 里的约束，但系统层 Hook 不会“忘”。

Agent 是概率系统，它会受上下文长度、任务复杂度、模型能力和提示顺序影响。把关键约束只放在 Prompt 里，本质是在赌模型每次都能遵守。Hook 则把约束从“模型应该记得”升级为“系统必须执行”。

这就是 Harness 和普通 Agent Demo 的差别：Demo 追求跑通，Harness 追求可控。

5. 一个更稳定的分层方式

我现在更倾向于把 Agent Harness 的规则和能力分成四层：

用户目标
  ↓
Prompt / System Instruction：只负责方向和入口
  ↓
Skill：沉淀任务方法论和调用流程
  ↓
MCP：提供结构化能力和受控操作
  ↓
Hook：做权限、校验、审计、提醒和兜底
  ↓
真实环境：文件、命令、接口、数据库、外部系统

这套分层能解决一个关键问题：不要让 Agent 自己同时负责理解规则、选择工具、执行操作、判断风险和验证结果。

Agent 最擅长的是理解目标、拆解任务、选择下一步和生成内容；系统更适合负责边界、权限、校验、审计和强制流程。把两者职责拆开，Agent 反而会更稳定。

6. 反模式：用散落文本控制 Agent

我认为需要警惕几种常见反模式。

反模式一：把具体执行规则塞进 System Prompt

System Prompt 越写越长，短期看能解决问题，长期会变成不可维护的规则堆。尤其是项目事实、路径、命令、发布流程、团队规范，不应该全部塞进全局 Prompt。

更好的做法是：System Prompt 只告诉 Agent 去读项目规则、技能说明和可用工具。

反模式二：Skill 既写流程又写大量具体代码

Skill 适合描述“什么时候用、怎么判断、调用什么工具、如何验证”。如果把大量业务代码、路径常量、项目私有规则都塞进 Skill，Skill 会失去可复用性，也会和项目文档互相冲突。

更好的做法是：Skill 写方法论，项目事实写仓库级规则，具体执行沉淀到 MCP 或脚本。

反模式三：让 Agent 自由拼高风险命令

让 Agent 自由拼命令非常灵活，但风险也最高。路径错误、通配符误用、环境差异、权限边界不清，都可能导致不可逆结果。

更好的做法是：高频动作脚本化，高风险动作 MCP 化，并在 Hook 里做路径、权限和影响范围检查。

反模式四：只靠文字提醒做安全控制

“不要删除重要文件”“不要泄露密钥”“改完记得测试”这类提醒有价值，但不能作为唯一防线。真正关键的控制必须进入系统层。

更好的做法是：提醒留给人类理解，强约束交给 Hook 执行。

7. 可落地的设计清单

如果要设计一个更可靠的 Agent Harness，我会优先做这些事：

1. 梳理规则归属：区分哪些规则属于全局偏好、项目事实、任务方法、工具能力和安全策略。
2. 减少重复规则：同一条规则只保留一个权威位置，其他地方只做引用。
3. 把高频操作 MCP 化：不要让 Agent 每次重新理解一段复杂 bash。
4. 给 MCP 增加前置校验：参数、路径、权限、环境、依赖状态都要检查。
5. 给 MCP 增加后置校验：执行结果、文件产物、状态变化和失败原因都要可观察。
6. 为危险操作设置 Hook：删除、覆盖、发送、发布、访问敏感数据都需要拦截或确认。
7. 把经验提醒变成机制：如果某个提醒反复出现，就应该沉淀为 Hook、测试或脚本检查。
8. 保留执行轨迹：记录 Agent 调用了什么、为什么调用、结果是什么、是否通过验证。
9. 让小模型也能稳定执行：把复杂判断外移到系统层，降低对模型一次性记忆和推理的依赖。

这套清单的目标不是把 Agent 限制死，而是让 Agent 在清晰边界内发挥能力。

8. 对小模型的意义

Hook 系统还有一个容易被忽略的价值：它能降低对大模型的依赖。

如果所有约束都靠 Prompt，大模型可能还能勉强遵守，小模型很容易漏步骤、误解规则或忽略边界。但如果把关键约束固化到 MCP 和 Hook 中，小模型只需要做好“理解目标 + 调用能力 + 根据反馈调整”这几件事。

也就是说，好的 Harness 会把复杂性从模型上下文里搬到系统结构里。模型不需要记住所有规则，因为系统会在关键位置提醒、拦截和校验。

这会让 Agent 更像一个“听话的执行者”，而不是一个需要不断被长 Prompt 训诫的自由发挥者。

9. 和站内其他内容的关系

这篇文章可以和几类内容一起看：

• 从 RAG 到生产级 Agent Harness 的工程化学习路线：理解 Agent Harness 在整体学习路线中的位置。
• Harness Engineering 源码拆解：从源码视角看 Harness 里有哪些工程模块。
• MCP Server 工程化：理解 MCP 如何作为工具边界承载外部能力。
• Tool Calling：理解工具调用、参数 Schema 和权限控制的基础概念。
• Agent Trace 执行轨迹：理解为什么 Hook 和 MCP 需要留下可复盘的执行记录。

10. 总结

Agent Harness 的工程重点，不是写出一段越来越长的 Prompt，而是建立一套可执行、可审计、可演进的控制面。

我的阶段性判断是：

• System Prompt 不应该承载大量项目事实和具体规则；
• Skill 不应该变成规则和代码的大杂烩；
• MCP 应该承载可复用、可校验、可追踪的执行能力；
• Hook 应该承载强约束、风险拦截、经验提醒和治理逻辑。

当规则只存在于文字里时，Agent 可能遵守，也可能忘记。当规则进入 MCP 和 Hook 后，系统才真正拥有了稳定边界。

所以，Hook 机制是 Agent Harness 最重要的资产之一。它让 Agent 不只是“能做事”，而是能在可控范围内持续、稳定、可复盘地做事。