agentic-harness-patterns

Agentic Harness 模式

生产级 AI 编码 Agent 不只是循环调用工具的大模型。Harness——记忆、技能、安全、上下文控制、委派和可扩展性——才是演示项目与生产系统的区别所在。

适合： 构建或扩展编码 Agent 运行时、自定义 Agent 或高级多 Agent 工作流的工程师。 不适合： 提示词工程、模型选择、通用软件架构或大模型 API 基础知识。

所有原则均提炼自生产环境中的运行时决策。本文以 Claude Code 作为实例依据，而非唯一可能的实现方式。

选择你的问题

如果你想……	阅读
让 Agent 随时间积累记忆并不断改进	记忆
封装可复用的工作流和专业知识	技能
让 Agent 强大而安全地使用工具	工具与安全
以合适的成本为 Agent 提供恰当的上下文	上下文工程
在不失去控制的情况下将工作分配给多个 Agent	多 Agent 协调
通过钩子、后台任务或启动逻辑扩展行为	生命周期与可扩展性

开始构建前： 请阅读注意事项——这些不易察觉的故障模式最耗费时间。

---

1. 记忆

用户问题：“我的 Agent 会忘记之前的纠正意见和项目规则。”

黄金法则： 将 Agent 知道的内容（指令记忆）、Agent 学到的内容（自动记忆）和 Agent 提取的内容（会话记忆）分开。每一层在持久性、可信度和审核要求上都不同。

适用场景： 任何跨多个会话运行，或需要随时间积累项目专属知识的 Agent。

工作原理：

• 指令记忆是经过整理的分层配置，会按优先级注入系统上下文（组织级 → 用户级 → 项目级 → 本地级；本地级优先）。项目规范、编码标准和行为规则都存放在这一层。内容由人编写且保持稳定。
• 自动记忆是由 Agent 编写的持久知识，采用类型分类（用户 / 反馈 / 项目 / 参考），并设有索引上限。保存分两步：先写入主题文件，再更新索引。设置上限可防止内容无限增长——如果不清理，较新的条目会悄然消失。
• 会话提取会在会话结束时作为后台 Agent 运行。它直接写入自动记忆——先写入主题文件，再更新索引——遵循相同的两步保存约束。互斥保护机制可确保：如果主 Agent 已在本轮中写入记忆，提取器就会完全跳过。这就是自主学习循环。
• 审核与晋升会审查所有记忆层，并提议在层间迁移内容（自动记忆 → 项目规范、个人指令或团队记忆）。它绝不会自主应用更改——提议必须经用户明确批准。

从这里开始： 定义记忆层（指令、自动记忆、提取）。实现两步保存约束（先写入主题文件，再更新索引）。只有在核心写入路径稳定后，才添加后台提取。

在 Claude Code 中： 使用 /remember 跨记忆层审核并晋升自动记忆条目。

权衡：

• 记忆层越多，召回越丰富，但维护负担也越重。如果不定期清理，索引上限会导致数据悄然丢失。
• 会话提取会增加会话结束时的延迟，但能显著改善跨会话学习。

深入了解： references/memory-persistence-pattern.md

---

2. 技能

用户问题：“我希望 Agent 能重复使用工作流和领域知识，而不必每次都重新解释。”

**黄金法则：**技能是按需加载的指令集，而不是预先注入的提示词。发现过程必须开销低（仅限元数据）；只有激活技能时才加载完整正文。

**适用场景：**任何需要可重复使用、可组合工作流，并能根据匹配的用户意图激活的 Agent。

工作原理：

• 发现受预算限制：Agent 会看到所有可用技能的精简列表（每个条目包含名称、描述和何时使用的提示），每个条目都严格限制在固定字符数内，列表总长度上限约为上下文窗口的 1%。将触发语句放在前面——末尾内容会被截断。
• 加载按需进行：常驻上下文中只包含元数据。只有技能激活时才会加载完整正文，因此闲置时的 token 开销几乎为零。
• 执行可以是内联执行（共享上下文），也可以是隔离执行（分叉出拥有独立 token 预算的子 Agent）。隔离执行可避免繁重技能耗尽父级上下文。
• 来源可以是捆绑提供、由用户安装，或通过插件动态加载。按规范路径去重，可防止同一技能因来源目录重叠而重复出现。

**从这里开始：**选择一种元数据格式（推荐 frontmatter）。实现两阶段发现：启动时进行低开销列表检索，调用时再按需加载正文。在技能目录不断扩大之前，为每个条目设置字符数上限。

权衡：

• 按需加载可以节省 token，但首次激活时会增加一次往返延迟。
• 分叉执行可提供隔离，但无法访问父级已累积的上下文。

深入了解：references/skill-runtime-pattern.md

---

3. 工具与安全

用户问题：“我希望 Agent 能强大地使用工具，但又不会带来危险。”

**黄金法则：**默认采用失败关闭策略。除非明确标记为可安全并发，并通过权限流程批准，否则工具调用应串行执行并受到权限门控。

**适用场景：**任何需要工具注册、并发控制或权限门控的 Agent 运行时。

工作原理：

• 注册采用失败关闭的默认设置：除非开发者主动选择启用，否则工具不可并发执行，也不视为只读。这样可以避免意外并行执行会更改状态的操作。
• 并发分类针对每次调用，而非整个工具：同一工具对某些输入可能安全，对另一些输入则不安全。运行时会将一批工具调用划分为连续的组——安全调用并行运行，任何不安全调用都会开始一个串行片段。
• 权限流程会按照严格的优先级顺序评估来自多个来源的规则，包括设置文件（用户、项目、本地、标志和策略）、CLI 参数、限定命令的规则以及会话授权。评估器具有状态：它会跟踪拒绝记录、转换模式，并在执行过程中更新状态。
• 处理程序分发因执行环境而异：交互式（人工提示）、自动化（协调器）或异步（群组 Agent）。相同的权限规则会应用于不同的审批界面。

**从这里开始：**让每次工具调用都经过同一个权限门控。默认采用失败关闭策略（拒绝／询问）。在发布任何自动批准模式之前，为受保护路径添加无法绕过的规则。

**在 Claude Code 中：**使用 /update-config 配置权限规则和钩子。

权衡：

• 失败关闭的默认设置意味着新工具开箱即安全，但开发者必须主动启用并发——如果忘记将只读工具标记为可安全并发，吞吐量会在不知不觉中下降。
• 多来源权限分层功能强大，但不同来源的规则发生冲突时，很难排查问题。

深入了解：references/tool-registry-pattern.md | references/permission-gate-pattern.md

---

4. 上下文工程

用户问题：“我的 Agent 看到的内容要么太多、要么太少，要么不对。”

**黄金法则：**将上下文视为预算，而不是一股脑地倾倒。上下文窗口中的每个 token 都应通过以下四种操作之一证明其价值：选择、写入、压缩或隔离。

**适用场景：**任何在长会话中性能下降、委派的工作污染父级上下文，或因急切加载上下文而启动缓慢的 Agent。

工作原理：

• 选择 — 按需加载上下文，而不是一次性全部加载。采用渐进式披露，分为三个层级：元数据（始终存在，成本低）、指令（激活时加载）、资源（按需加载）。对开销较大的上下文构建器进行记忆化，并且仅在已知的变更点失效，而不是被动响应。
• 写入 — 上下文并非只读。Agent 会写回持久化存储：自动记忆条目、后台提取结果、任务状态、权限规则。正是写回循环将无状态 Agent 转变为学习系统。
• 压缩 — 长会话会耗尽上下文窗口。响应式压缩会在会话中总结较早的轮次，在保留近期上下文的同时回收预算。将快照数据标记为快照，以便模型知道需要重新获取当前状态。
• 隔离 — 委派的工作不得污染父级上下文。协调器工作进程以零上下文继承启动（仅包含明确提供的提示词）。分叉出的子进程会继承完整上下文，但仅支持单层分叉（不可递归分叉）。文件系统级隔离（工作树）可为 Agent 提供独立的工作副本。

**从这里开始：**审查当前每轮对话的上下文成本。为所有可变长度的内容块设置硬性上限。启用任何压缩功能之前，先添加截断恢复指针（告知模型调用哪个工具以获取完整输出）。

权衡：

• 激进缓存可降低延迟，但会带来数据过时的风险——每个变更点都必须显式清除缓存，否则模型在本次会话余下时间里都会基于过时数据运行。
• 渐进式披露可以节省 token，但也意味着模型在技能激活之前，无法根据该技能的完整能力进行推理。

深入了解：references/context-engineering-pattern.md（索引） | 选择 | 压缩 | 隔离

---

5. 多 Agent 协调

用户问题：“我希望实现并行处理、专业化分工和协调协作，同时避免混乱。”

**黄金法则：**协调者必须综合分析，而不是把理解任务交给别人。“根据你的发现修复它”是一种反模式——协调者应先消化工作 Agent 的结果，将其转化为精确的规范，再分派实现任务。

**适用场景：**任务规模超出单个 Agent 的处理能力、需要并行探索，或希望拥有长期协作的专业队友时。

工作原理：

三种委派模式分别适用于不同类型的任务：

模式	上下文共享	最适合
协调者	无——工作 Agent 从头开始	复杂的多阶段任务（研究 → 综合分析 → 实现 → 验证）
分叉	完整——子 Agent 继承父 Agent 的历史记录	共享已加载上下文的快速并行拆分
蜂群	通过共享任务列表进行点对点协作	长期运行的独立工作流

关键限制：

• 分叉只能进行一层——递归分叉会使上下文成本呈指数级增长。
• 蜂群成员无法再创建其他成员——团队成员列表保持扁平，以防止不受控地扩张。
• 结果会异步返回；即发即弃式注册会立即返回 ID，以便父 Agent 继续工作。

**从这里开始：**选择一种委派模式，并在混用多种模式之前将其完整实现。将每个子 Agent 的提示词写成独立完整的文档。在研究和实现工作 Agent 之间加入综合分析步骤——这正是协调者发挥价值的地方。

协调者模式的实现清单：

1. 定义分阶段工作流：研究 → 综合分析 → 实现 → 验证
2. 为每个工作 Agent 编写独立完整的提示词（不要写“根据你的发现”）
3. 将每个工作 Agent 的工具集限制为其所需的工具
4. 制定继续执行还是创建新 Agent 的策略：上下文有重叠时继续执行，验证时创建全新的 Agent

权衡：

• 协调者模式最安全，但也最慢——每个阶段都要等待前一阶段完成。
• 分叉速度最快，但仅限一层，并且会承担父 Agent 的全部上下文成本。
• 蜂群最灵活，但最难协调——成员之间只能通过共享任务列表进行交流。

深入了解：references/agent-orchestration-pattern.md

---

6. 生命周期与可扩展性

用户问题：“我需要钩子、后台任务和清晰的启动顺序。”

**黄金法则：**可扩展性应通过注入点实现，而不是建立继承层级。钩子在生命周期节点附加副作用；任务通过严格的状态机跟踪异步工作；引导流程则按顺序分层初始化，并缓存各阶段的结果。

**适用场景：**当你需要在不修改核心代码的情况下扩展 Agent 行为、跟踪长时间运行的后台工作，或为多种入口模式组织初始化流程时。

工作原理：

• 钩子通过在指定的生命周期节点（工具执行前后、提交提示词、Agent 开始/结束）附加副作用来扩展行为。信任控制是全有或全无：如果工作区不受信任，所有钩子都会跳过，而不只是可疑的钩子。会话作用域的钩子是临时的，会在会话结束时清理。
• 长时间运行的工作通过类型化状态机跟踪。每个工作单元都有一个带类型前缀的 ID、严格的生命周期（运行中 → 已完成 / 失败 / 已终止），以及存储在磁盘上的输出。清理分为两个阶段：终止状态时立即清理磁盘输出；父级收到通知后，再延迟清理内存中的记录。
• 引导流程将初始化组织为按依赖顺序执行、结果可缓存的阶段。信任边界——用户授予同意的时点——是关键转折点：遥测、机密环境变量等安全敏感子系统必须等到建立信任后才能启用。多种入口模式（CLI、服务、SDK）共享相同的引导路径，但入口点各不相同。

**从这里开始：**将所有钩子通过单一分发点进行调度。添加任何外部钩子类型之前，先实现信任检查。应在初始化时注册清理处理程序，而不是在使用位置注册。

**在 Claude Code 中：**使用 /update-config 配置钩子（工具执行前后、提交提示词）。

权衡：

• 全有或全无的钩子信任机制简单，但不够精细——一个不受信任的钩子就会禁用整个扩展系统。
• 将任务输出存储在磁盘上可保持内存占用恒定，但会增加 I/O 延迟，且延迟与并发工作单元数量成正比。

深入了解：references/hook-lifecycle-pattern.md | references/task-decomposition-pattern.md | references/bootstrap-sequence-pattern.md

---

易忽略的问题

违反以下不明显的原则会导致错误：

1. 并发分类针对每次调用，而非每个工具。 某个工具对某些输入可能是安全的，对其他输入则不安全。不要假设工具的并发行为是固定的——运行时会针对每次调用进行判断。

2. 权限评估会产生副作用。 权限检查器会跟踪拒绝记录、转换模式并更新状态。不要把它当作纯查询函数。

3. 大多数异步工作都会跳过“pending”状态。 实际上，工作单元会直接注册为“running”。不要构建假设每个工作单元都从 pending 状态开始的 UI。

4. 分叉出的子项不能再分叉。 递归保护机制会维持单层不变量。分叉工具仍保留在子项的工具池中（以共享提示词缓存），但在调用时会被阻止。

5. 上下文构建器会被记忆化，但需要手动失效。 如果添加上下文来源，却没有添加相应的失效点，模型在整个会话期间都会看到过时数据。

6. 记忆索引有硬性上限。 超出上限的条目会被静默截断。如果不定期清理，近期条目就会变得不可见。

7. 技能列表的预算很紧。 描述会拼接起来，并对每个条目设定上限。把最具辨识度的触发词放在前面——尾部内容会被截断。

8. 钩子的信任机制非全即无。 如果工作区不受信任，整个钩子系统都会被禁用，而不仅是个别可疑钩子。

9. 工具的默认权限是“allow”。 未实现自定义权限逻辑的工具会完全委托给基于规则的系统。只有在需要工具专属限制（路径 ACL、配额等）时才覆盖默认行为。

10. 清退需要通知。 只有父项收到完成信号后，终态工作单元才符合 GC 条件。在通知前清退会产生竞态，导致父项永远无法读取结果。

---

何时不应使用此技能

此技能关注的是 Agent 周围的运行框架，而非：

• 提示词工程或系统提示词设计
• 模型选择或微调
• 通用软件架构（MVC、微服务）
• 聊天 UI 或对话界面
• 大模型 API 集成基础知识

如果你的问题关注的是模型本身，而非其周围的系统，则此技能不适用。