// AI Agent Harness 设计模式 — 记忆、权限、上下文工程、委派、技能、 Hook、Bootstrap。中文版。
| name | agentic-harness-patterns-zh |
| description | AI Agent Harness 设计模式 — 记忆、权限、上下文工程、委派、技能、 Hook、Bootstrap。中文版。 |
| when_to_use | 触发词: harness 工程, 工具安全, 权限管道, agent 记忆, 记忆持久化, 委派模式, 上下文预算, bootstrap 序列, 技能运行时, hook 生命周期, 工具编排, agent harness, 上下文工程, 多 agent 协调。 |
| license | MIT |
生产级 AI 编程助手不只是"大模型 + 工具调用循环"。循环本身很简单。Harness — 记忆、技能、安全、上下文控制、委派、可扩展性 — 才是让 Agent 可靠、安全、大规模运行的关键。
适合： 正在构建或扩展 AI Agent 运行时、自定义 Agent、或高级多 Agent 工作流的工程师。 不适合： Prompt 工程、模型选择、通用软件架构、LLM API 入门。
所有原则均从生产级运行时决策中提炼而来。Claude Code 作为实证依据，而非唯一实现。
| 你想要... | 阅读 |
|---|---|
| 让 Agent 跨会话记住并持续改进 | 记忆系统 |
| 打包可复用的工作流和专业知识 | 技能系统 |
| 让 Agent 强大地使用工具但不危险 | 工具与安全 |
| 给 Agent 正确的上下文、合理的成本 | 上下文工程 |
| 将工作拆分给多个 Agent 而不失控 | 多 Agent 协调 |
| 通过 Hook、后台任务或启动逻辑扩展行为 | 生命周期与可扩展性 |
开始构建之前： 先读 踩坑指南 — 这些是最不直觉但最烧时间的失败模式。
用户痛点： "我的 Agent 下次对话就忘了所有纠正和项目规则。"
黄金法则： 区分 Agent 知道的（指令记忆）、Agent 学到的（自动记忆）、和 Agent 提取的（会话记忆）。三层的持久性、信任度、审查需求各不相同。
适用场景： 任何跨会话运行或需要持续积累项目知识的 Agent。
工作原理：
从这里开始： 定义你的记忆层（指令、自动、提取）。实现两步保存不变式（先主题文件，再索引）。核心写入路径稳定后再加后台提取。
在 Claude Code 中： 使用
/remember审计和晋升各层自动记忆条目。
权衡：
深入阅读： references/memory-persistence-pattern.md
用户痛点： "我想让 Agent 复用工作流和领域知识，不用每次重新解释。"
黄金法则： 技能是懒加载的指令集，不是立即注入的 prompt。发现必须廉价（仅元数据）；完整内容只在激活时加载。
适用场景： 任何需要可复用、可组合工作流并根据用户意图匹配激活的 Agent。
工作原理：
从这里开始： 选一种元数据格式（推荐 frontmatter）。实现两阶段发现：启动时廉价列表，调用时懒加载内容。在目录增长前设好每条字符上限。
权衡：
深入阅读： references/skill-runtime-pattern.md
用户痛点： "我想让 Agent 强大地使用工具，但不要危险。"
黄金法则： 默认关闭（fail-closed）。工具是串行的、有门控的，除非显式标记为并发安全且通过了权限管道。
适用场景： 任何需要工具注册、并发控制或权限门控的 Agent 运行时。
工作原理：
从这里开始： 让每个工具调用都通过一个权限关卡。默认 fail-closed（拒绝/询问）。在上线任何自动批准模式之前，先加上受保护路径的免豁免规则。
在 Claude Code 中： 使用
/update-config配置权限规则和 Hook。
权衡：
深入阅读： references/tool-registry-pattern.md | references/permission-gate-pattern.md
用户痛点： "我的 Agent 看到太多、太少、或者看错了。"
黄金法则： 把上下文当预算管，不是垃圾桶。窗口里的每个 token 都必须通过四种操作之一赢得它的位置：选择、写回、压缩、隔离。
适用场景： 任何在长会话中性能下降、委派工作污染父上下文、或因急切加载导致启动慢的 Agent。
工作原理：
从这里开始： 审计你当前每轮的上下文成本。对每个变长块加硬上限。在启用任何压缩之前，先加截断恢复指针（告诉模型调用哪个工具获取完整输出）。
权衡：
深入阅读： references/context-engineering-pattern.md（索引） | select | compress | isolate
用户痛点： "我要并行、专业化和协调，但不要混乱。"
黄金法则： 协调者必须自己综合，不能委派理解。"基于你的发现，修复它" 是反模式 — 协调者应该消化 worker 结果成精确规格，然后再派发实现。
适用场景： 当任务对单个 Agent 太大时、需要并行探索时、或想要持久化的专业队友时。
工作原理：
三种委派模式服务不同的任务形态：
| 模式 | 上下文共享 | 适合 |
|---|---|---|
| Coordinator | 无 — worker 从零开始 | 复杂多阶段任务（研究 → 综合 → 实现 → 验证） |
| Fork | 全部 — 子级继承父级历史 | 共享已加载上下文的快速并行拆分 |
| Swarm | 对等共享任务列表 | 长期运行的独立工作流 |
关键约束：
从这里开始： 选一种委派模式并完整实现，再考虑混合模式。每个子 Agent prompt 写成自包含文档。在研究和实现 worker 之间加综合步骤 — 这是协调者创造价值的地方。
Coordinator 模式实现清单：
权衡：
深入阅读： references/agent-orchestration-pattern.md
用户痛点： "我需要 Hook、后台任务和干净的启动序列。"
黄金法则： 可扩展性是注入点，不是继承层次。Hook 在生命周期时刻附加副作用；任务用严格状态机追踪异步工作；Bootstrap 以记忆化阶段按依赖顺序初始化。
适用场景： 需要不修改核心代码就扩展 Agent 行为、追踪长期运行的后台工作、或为多种入口模式结构化初始化时。
工作原理：
从这里开始： 让所有 Hook 通过单一分发点。在加任何外部 Hook 类型之前先实现信任门控。在 init 时注册清理处理器，不在使用点。
在 Claude Code 中： 使用
/update-config配置 Hook（工具执行前/后、prompt 提交）。
权衡：
深入阅读： references/hook-lifecycle-pattern.md | references/task-decomposition-pattern.md | references/bootstrap-sequence-pattern.md
违反这些原则会导致 bug 的非直觉设计：
并发分类是按调用的，不是按工具类型。 同一工具对某些输入安全、对另一些不安全。不要假设工具的并发行为是静态的 — 运行时按调用决定。
权限评估有副作用。 权限检查器追踪拒绝次数、转换模式、更新状态。不要把它当纯查询函数。
大多数异步工作跳过 "pending" 状态。 实践中，工作单元直接注册为 "running"。不要构建假设每个工作单元从 pending 开始的 UI。
Fork 子级不能 fork。 递归保护维护单层不变式。Fork 工具留在子级工具池中（为了 prompt 缓存共享）但在调用时被阻止。
上下文构建器是记忆化的但手动失效。 添加上下文源而不添加对应的失效点，模型在整个会话中看到过时数据。
记忆索引有硬上限。 超过上限的条目被静默截断。不定期清理的话，新条目变得不可见。
技能列表预算很紧。 描述被拼接并按条目限制字符。把最具区分度的触发语言放在前面 — 后面会被截掉。
Hook 信任是全有或全无。 工作区不受信任时，整个 Hook 系统被禁用，不只是个别可疑的 Hook。
工具的默认权限是 "allow"。 没有实现自定义权限逻辑的工具完全委托给基于规则的系统。只在需要工具特定门控（路径 ACL、配额等）时才覆盖。
回收需要通知。 终态工作单元只有在父级收到完成信号后才可被 GC。在通知前回收会产生竞态，父级永远读不到结果。
本技能是关于 Agent 周围的 harness 的，不是：
如果你的问题是关于模型本身而非模型周围的系统，本技能不适用。
