/agentic-harness-patterns-zh

name: agentic-harness-patterns-zh
description: >-
  AI Agent Harness 设计模式 — 记忆、权限、上下文工程、委派、技能、
  Hook、Bootstrap。中文版。
when_to_use: >-
  触发词: harness 工程, 工具安全, 权限管道, agent 记忆, 记忆持久化,
  委派模式, 上下文预算, bootstrap 序列, 技能运行时, hook 生命周期,
  工具编排, agent harness, 上下文工程, 多 agent 协调。
license: MIT

Agentic Harness Patterns（中文版）

生产级 AI 编程助手不只是"大模型 + 工具调用循环"。循环本身很简单。**Harness** — 记忆、技能、安全、上下文控制、委派、可扩展性 — 才是让 Agent 可靠、安全、大规模运行的关键。

**适合：** 正在构建或扩展 AI Agent 运行时、自定义 Agent、或高级多 Agent 工作流的工程师。 **不适合：** Prompt 工程、模型选择、通用软件架构、LLM API 入门。

所有原则均从生产级运行时决策中提炼而来。Claude Code 作为实证依据，而非唯一实现。

选择你的问题

| 你想要... | 阅读 | |---|---| | 让 Agent 跨会话记住并持续改进 | [记忆系统](#1-记忆系统) | | 打包可复用的工作流和专业知识 | [技能系统](#2-技能系统) | | 让 Agent 强大地使用工具但不危险 | [工具与安全](#3-工具与安全) | | 给 Agent 正确的上下文、合理的成本 | [上下文工程](#4-上下文工程) | | 将工作拆分给多个 Agent 而不失控 | [多 Agent 协调](#5-多-agent-协调) | | 通过 Hook、后台任务或启动逻辑扩展行为 | [生命周期与可扩展性](#6-生命周期与可扩展性) |

**开始构建之前：** 先读 [踩坑指南](#踩坑指南) — 这些是最不直觉但最烧时间的失败模式。

---

1. 记忆系统

**用户痛点：** "我的 Agent 下次对话就忘了所有纠正和项目规则。"

**黄金法则：** 区分 Agent *知道的*（指令记忆）、Agent *学到的*（自动记忆）、和 Agent *提取的*（会话记忆）。三层的持久性、信任度、审查需求各不相同。

**适用场景：** 任何跨会话运行或需要持续积累项目知识的 Agent。

**工作原理：**

• **指令记忆** 是人工策划的、分层的配置，按优先级注入系统上下文（组织级 → 用户级 → 项目级 → 本地级；本地优先）。项目编码规范、行为规则都在这里。它是人类编写的，稳定不变。
• **自动记忆** 是 Agent 自主写入的持久知识，带有类型分类法（用户 / 反馈 / 项目 / 引用）和有上限的索引。写入是两步操作：先写主题文件，再更新索引。上限防止无限增长 — 不清理的话，新条目会被静默截断。
• **会话提取** 以后台 Agent 的形式在会话结束时运行。它直接写入自动记忆 — 先主题文件再索引 — 遵循相同的两步保存不变式。互斥锁确保：如果主 Agent 在当轮已经写过记忆，提取器直接跳过。这是自主学习循环。
• **审查与晋升** 审计所有记忆层并提议跨层移动（自动记忆 → 项目规范、个人设置或团队记忆）。它永远不自主应用更改 — 提议需要用户明确批准。

**从这里开始：** 定义你的记忆层（指令、自动、提取）。实现两步保存不变式（先主题文件，再索引）。核心写入路径稳定后再加后台提取。

> **在 Claude Code 中：** 使用 `/remember` 审计和晋升各层自动记忆条目。

**权衡：**

• 更多记忆层 = 更丰富的回忆但更高的维护负担。不定期清理的话，索引上限导致静默数据丢失。
• 会话提取在会话结束时增加延迟，但大幅提升跨会话学习能力。

**深入阅读：** [references/memory-persistence-pattern.md](references/memory-persistence-pattern.md)

---

2. Skills 系统

**用户痛点：** "我想让 Agent 复用工作流和领域知识，不用每次重新解释。"

**黄金法则：** 技能是懒加载的指令集，不是立即注入的 prompt。发现必须廉价（仅元数据）；完整内容只在激活时加载。

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

**工作原理：**

• **发现** 是预算约束的：Agent 看到所有可用技能的紧凑列表（名称、描述、触发提示拼接在一起），每条硬限在固定字符数，总量限制在上下文窗口的约 1%。把触发关键词放在前面 — 后面会被截断。
• **加载** 是懒的：只有元数据进入始终在线的上下文。完整技能内容只在激活时加载，闲置 token 成本接近零。
• **执行** 可以是内联的（共享上下文）或隔离的（fork 子 Agent，有自己的 token 预算）。隔离防止重型技能耗尽父级上下文。
• **来源** 可以是内置的、用户安装的、或从插件动态加载的。通过规范路径去重，防止同一技能在重叠的源目录中出现两次。

**从这里开始：** 选一种元数据格式（推荐 frontmatter）。实现两阶段发现：启动时廉价列表，调用时懒加载内容。在目录增长前设好每条字符上限。

**权衡：**

• 懒加载省 token 但首次激活多一轮延迟。
• Fork 执行提供隔离但失去父级已积累的上下文。

**深入阅读：** [references/skill-runtime-pattern.md](references/skill-runtime-pattern.md)

---

3. 工具与安全

**用户痛点：** "我想让 Agent 强大地使用工具，但不要危险。"

**黄金法则：** 默认关闭（fail-closed）。工具是串行的、有门控的，除非显式标记为并发安全且通过了权限管道。

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

**工作原理：**

• **注册** 使用 fail-closed 默认值：工具默认不可并发、非只读，除非开发者主动标记。这防止状态变更操作的意外并行执行。
• **并发分类** 是按调用的，不是按工具类型：同一工具对某些输入安全、对另一些不安全。运行时将一批工具调用分成连续组 — 安全调用并行执行，任何不安全调用开始一个串行段。
• **权限管道** 从多个来源按严格优先级顺序评估规则，涵盖配置文件（用户、项目、本地、标志、策略）、CLI 参数、命令级规则和会话授权。评估器是有状态的 — 它追踪拒绝次数、转换模式、更新状态作为副作用。
• **处理器分发** 因执行环境而异：交互式（人类提示）、自动化（协调器）或异步（Swarm Agent）。相同的权限规则供给不同的审批界面。

**从这里开始：** 让每个工具调用都通过一个权限关卡。默认 fail-closed（拒绝/询问）。在上线任何自动批准模式之前，先加上受保护路径的免豁免规则。

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

**权衡：**

• Fail-closed 默认值意味着新工具开箱即安全，但开发者必须主动标记并发安全 — 忘记标记只读工具会静默降低吞吐量。
• 多来源权限分层功能强大但规则冲突时难以调试。

**深入阅读：** [references/tool-registry-pattern.md](references/tool-registry-pattern.md) | [references/permission-gate-pattern.md](references/permission-gate-pattern.md)

---

4. 上下文工程

**用户痛点：** "我的 Agent 看到太多、太少、或者看错了。"

**黄金法则：** 把上下文当预算管，不是垃圾桶。窗口里的每个 token 都必须通过四种操作之一赢得它的位置：选择、写回、压缩、隔离。

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

**工作原理：**

• **选择** — 按需加载，不要一次全加载。使用三级渐进披露：元数据（始终存在，廉价）、指令（激活时加载）、资源（按需加载）。记忆化昂贵的上下文构建器，只在已知变更点失效 — 不要响应式。
• **写回** — 上下文不是只读的。Agent 将信息写回持久存储：自动记忆条目、后台提取输出、任务状态、权限规则。写回循环是把无状态工具调用者变成学习系统的关键。
• **压缩** — 长会话耗尽窗口。响应式压实在会话中间总结旧轮次，保留近期上下文同时回收预算。将快照数据标记为快照，让模型知道要重新获取当前状态。
• **隔离** — 委派工作不能污染父级上下文。协调器 worker 零上下文继承（只有显式 prompt）。Fork 子级继承全部上下文但单层限制（不能递归 fork）。文件系统级隔离（worktree）给 Agent 自己的工作副本。

**从这里开始：** 审计你当前每轮的上下文成本。对每个变长块加硬上限。在启用任何压缩之前，先加截断恢复指针（告诉模型调用哪个工具获取完整输出）。

**权衡：**

• 激进缓存降低延迟但有过时风险 — 每个变更点必须显式清除缓存，否则模型在剩余会话中用过时数据。
• 渐进披露省 token 但意味着模型在技能激活前无法推理其完整能力。

**深入阅读：** [references/context-engineering-pattern.md](references/context-engineering-pattern.md)（索引） | [select](references/context-engineering/select-pattern.md) | [compress](references/context-engineering/compress-pattern.md) | [isolate](references/context-engineering/isolate-pattern.md)

---

5. 多 Agent 协调

**用户痛点：** "我要并行、专业化和协调，但不要混乱。"

**黄金法则：** 协调者必须自己综合，不能委派理解。"基于你的发现，修复它" 是反模式 — 协调者应该消化 worker 结果成精确规格，然后再派发实现。

**适用场景：** 当任务对单个 Agent 太大时、需要并行探索时、或想要持久化的专业队友时。

**工作原理：**

三种委派模式服务不同的任务形态：

| 模式 | 上下文共享 | 适合 | |---------|----------------|----------| | **Coordinator** | 无 — worker 从零开始 | 复杂多阶段任务（研究 → 综合 → 实现 → 验证） | | **Fork** | 全部 — 子级继承父级历史 | 共享已加载上下文的快速并行拆分 | | **Swarm** | 对等共享任务列表 | 长期运行的独立工作流 |

关键约束：

• Fork 只有单层 — 递归 fork 会指数级放大上下文成本。
• Swarm 队友不能生成其他队友 — 名单是扁平的，防止不受控增长。
• 结果异步到达；即发即忘注册立即返回 ID，父级可以继续工作。

**从这里开始：** 选一种委派模式并完整实现，再考虑混合模式。每个子 Agent prompt 写成自包含文档。在研究和实现 worker 之间加综合步骤 — 这是协调者创造价值的地方。

**Coordinator 模式实现清单：**

1. 定义阶段化工作流：研究 → 综合 → 实现 → 验证 2. 为每个 worker 写自包含 prompt（不要"基于你的发现"） 3. 过滤每个 worker 的工具集，只给它需要的 4. 决定继续 vs 新建策略：上下文重叠就继续，验证阶段必须新建

**权衡：**

• Coordinator 最安全但最慢 — 每阶段等前一阶段完成。
• Fork 最快但只有一层，共享父级全部上下文成本。
• Swarm 最灵活但最难协调 — 对等方只能通过共享任务列表通信。

**深入阅读：** [references/agent-orchestration-pattern.md](references/agent-orchestration-pattern.md)

---

6. 生命周期与可扩展性

**用户痛点：** "我需要 Hook、后台任务和干净的启动序列。"

**黄金法则：** 可扩展性是注入点，不是继承层次。Hook 在生命周期时刻附加副作用；任务用严格状态机追踪异步工作；Bootstrap 以记忆化阶段按依赖顺序初始化。

**适用场景：** 需要不修改核心代码就扩展 Agent 行为、追踪长期运行的后台工作、或为多种入口模式结构化初始化时。

**工作原理：**

• **Hook** 在定义的生命周期时刻附加副作用（工具执行前/后、prompt 提交、Agent 启停）。信任是全有或全无：工作区不受信任时所有 Hook 跳过 — 不只是可疑的那些。会话级 Hook 是临时的，会话结束时清理。
• **长期运行工作** 通过带类型的状态机追踪。每个工作单元有带类型前缀的 ID、严格生命周期（运行中 → 完成 / 失败 / 被杀）、和磁盘后备输出。回收是两阶段的：终态时立即清磁盘，父级收到通知后才懒清内存。
• **Bootstrap** 将初始化结构化为按依赖排序的、记忆化的阶段。信任边界 — 用户授权同意的时刻 — 是关键拐点：安全敏感子系