tomevault-io Agentic Harness Patterns（中文版）
生产级 AI 编程助手不只是"大模型 + 工具调用循环"。循环本身很简单。Harness — 记忆、技能、安全、上下文控制、委派、可扩展性 — 才是让 Agent 可靠、安全、大规模运行的关键。
适合： 正在构建或扩展 AI Agent 运行时、自定义 Agent、或高级多 Agent 工作流的工程师。 不适合： Prompt 工程、模型选择、通用软件架构、LLM API 入门。
所有原则均从生产级运行时决策中提炼而来。Claude Code 作为实证依据，而非唯一实现。
选择你的问题
| 你想要... | 阅读 |
|---|---|
| 让 Agent 跨会话记住并持续改进 | 记忆系统 |
| 打包可复用的工作流和专业知识 | 技能系统 |
| 让 Agent 强大地使用工具但不危险 | 工具与安全 |
| 给 Agent 正确的上下文、合理的成本 | 上下文工程 |
| 将工作拆分给多个 Agent 而不失控 | 多 Agent 协调 |
| 通过 Hook、后台任务或启动逻辑扩展行为 | 生命周期与可扩展性 |
开始构建之前： 先读 踩坑指南 — 这些是最不直觉但最烧时间的失败模式。
1. 记忆系统
用户痛点： "我的 Agent 下次对话就忘了所有纠正和项目规则。"
黄金法则： 区分 Agent 知道的（指令记忆）、Agent 学到的（自动记忆）、和 Agent 提取的（会话记忆）。三层的持久性、信任度、审查需求各不相同。
适用场景： 任何跨会话运行或需要持续积累项目知识的 Agent。
工作原理：
- 指令记忆 是人工策划的、分层的配置，按优先级注入系统上下文（组织级 → 用户级 → 项目级 → 本地级；本地优先）。项目编码规范、行为规则都在这里。它是人类编写的，稳定不变。
- 自动记忆 是 Agent 自主写入的持久知识，带有类型分类法（用户 / 反馈 / 项目 / 引用）和有上限的索引。写入是两步操作：先写主题文件，再更新索引。上限防止无限增长 — 不清理的话，新条目会被静默截断。
- 会话提取 以后台 Agent 的形式在会话结束时运行。它直接写入自动记忆 — 先主题文件再索引 — 遵循相同的两步保存不变式。互斥锁确保：如果主 Agent 在当轮已经写过记忆，提取器直接跳过。这是自主学习循环。
- 审查与晋升 审计所有记忆层并提议跨层移动（自动记忆 → 项目规范、个人设置或团队记忆）。它永远不自主应用更改 — 提议需要用户明确批准。
从这里开始： 定义你的记忆层（指令、自动、提取）。实现两步保存不变式（先主题文件，再索引）。核心写入路径稳定后再加后台提取。
在 Claude Code 中： 使用
/remember审计和晋升各层自动记忆条目。
权衡：
- 更多记忆层 = 更丰富的回忆但更高的维护负担。不定期清理的话，索引上限导致静默数据丢失。
- 会话提取在会话结束时增加延迟，但大幅提升跨会话学习能力。
深入阅读： references/memory-persistence-pattern.md
2. Skills 系统
用户痛点： "我想让 Agent 复用工作流和领域知识，不用每次重新解释。"
黄金法则： 技能是懒加载的指令集，不是立即注入的 prompt。发现必须廉价（仅元数据）；完整内容只在激活时加载。
适用场景： 任何需要可复用、可组合工作流并根据用户意图匹配激活的 Agent。
工作原理：
- 发现 是预算约束的：Agent 看到所有可用技能的紧凑列表（名称、描述、触发提示拼接在一起），每条硬限在固定字符数，总量限制在上下文窗口的约 1%。把触发关键词放在前面 — 后面会被截断。
- 加载 是懒的：只有元数据进入始终在线的上下文。完整技能内容只在激活时加载，闲置 token 成本接近零。
- 执行 可以是内联的（共享上下文）或隔离的（fork 子 Agent，有自己的 token 预算）。隔离防止重型技能耗尽父级上下文。
- 来源 可以是内置的、用户安装的、或从插件动态加载的。通过规范路径去重，防止同一技能在重叠的源目录中出现两次。
从这里开始： 选一种元数据格式（推荐 frontmatter）。实现两阶段发现：启动时廉价列表，调用时懒加载内容。在目录增长前设好每条字符上限。
权衡：
- 懒加载省 token 但首次激活多一轮延迟。
- Fork 执行提供隔离但失去父级已积累的上下文。
深入阅读： 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/permission-gate-pattern.md
4. 上下文工程
用户痛点： "我的 Agent 看到太多、太少、或者看错了。"
黄金法则： 把上下文当预算管，不是垃圾桶。窗口里的每个 token 都必须通过四种操作之一赢得它的位置：选择、写回、压缩、隔离。
适用场景： 任何在长会话中性能下降、委派工作污染父上下文、或因急切加载导致启动慢的 Agent。
工作原理：
- 选择 — 按需加载，不要一次全加载。使用三级渐进披露：元数据（始终存在，廉价）、指令（激活时加载）、资源（按需加载）。记忆化昂贵的上下文构建器，只在已知变更点失效 — 不要响应式。
- 写回 — 上下文不是只读的。Agent 将信息写回持久存储：自动记忆条目、后台提取输出、任务状态、权限规则。写回循环是把无状态工具调用者变成学习系统的关键。
- 压缩 — 长会话耗尽窗口。响应式压实在会话中间总结旧轮次，保留近期上下文同时回收预算。将快照数据标记为快照，让模型知道要重新获取当前状态。
- 隔离 — 委派工作不能污染父级上下文。协调器 worker 零上下文继承（只有显式 prompt）。Fork 子级继承全部上下文但单层限制（不能递归 fork）。文件系统级隔离（worktree）给 Agent 自己的工作副本。
从这里开始： 审计你当前每轮的上下文成本。对每个变长块加硬上限。在启用任何压缩之前，先加截断恢复指针（告诉模型调用哪个工具获取完整输出）。
权衡：
- 激进缓存降低延迟但有过时风险 — 每个变更点必须显式清除缓存，否则模型在剩余会话中用过时数据。
- 渐进披露省 token 但意味着模型在技能激活前无法推理其完整能力。
深入阅读： references/context-engineering-pattern.md（索引） | select | compress | isolate
5. 多 Agent 协调
用户痛点： "我要并行、专业化和协调，但不要混乱。"
黄金法则： 协调者必须自己综合，不能委派理解。"基于你的发现，修复它" 是反模式 — 协调者应该消化 worker 结果成精确规格，然后再派发实现。
适用场景： 当任务对单个 Agent 太大时、需要并行探索时、或想要持久化的专业队友时。
工作原理：
三种委派模式服务不同的任务形态：
| 模式 | 上下文共享 | 适合 |
|---|---|---|
| Coordinator | 无 — worker 从零开始 | 复杂多阶段任务（研究 → 综合 → 实现 → 验证） |
| Fork | 全部 — 子级继承父级历史 | 共享已加载上下文的快速并行拆分 |
| Swarm | 对等共享任务列表 | 长期运行的独立工作流 |
关键约束：
- Fork 只有单层 — 递归 fork 会指数级放大上下文成本。
- Swarm 队友不能生成其他队友 — 名单是扁平的，防止不受控增长。
- 结果异步到达；即发即忘注册立即返回 ID，父级可以继续工作。
从这里开始： 选一种委派模式并完整实现，再考虑混合模式。每个子 Agent prompt 写成自包含文档。在研究和实现 worker 之间加综合步骤 — 这是协调者创造价值的地方。
Coordinator 模式实现清单：
- 定义阶段化工作流：研究 → 综合 → 实现 → 验证
- 为每个 worker 写自包含 prompt（不要"基于你的发现"）
- 过滤每个 worker 的工具集，只给它需要的
- 决定继续 vs 新建策略：上下文重叠就继续，验证阶段必须新建
权衡：
- Coordinator 最安全但最慢 — 每阶段等前一阶段完成。
- Fork 最快但只有一层，共享父级全部上下文成本。
- Swarm 最灵活但最难协调 — 对等方只能通过共享任务列表通信。
深入阅读： references/agent-orchestration-pattern.md
6. 生命周期与可扩展性
用户痛点： "我需要 Hook、后台任务和干净的启动序列。"
黄金法则： 可扩展性是注入点，不是继承层次。Hook 在生命周期时刻附加副作用；任务用严格状态机追踪异步工作；Bootstrap 以记忆化阶段按依赖顺序初始化。
适用场景： 需要不修改核心代码就扩展 Agent 行为、追踪长期运行的后台工作、或为多种入口模式结构化初始化时。
工作原理：
- Hook 在定义的生命周期时刻附加副作用（工具执行前/后、prompt 提交、Agent 启停）。信任是全有或全无：工作区不受信任时所有 Hook 跳过 — 不只是可疑的那些。会话级 Hook 是临时的，会话结束时清理。
- 长期运行工作 通过带类型的状态机追踪。每个工作单元有带类型前缀的 ID、严格生命周期（运行中 → 完成 / 失败 / 被杀）、和磁盘后备输出。回收是两阶段的：终态时立即清磁盘，父级收到通知后才懒清内存。
- Bootstrap 将初始化结构化为按依赖排序的、记忆化的阶段。信任边界 — 用户授权同意的时刻 — 是关键拐点：安全敏感子系统（遥测、秘密环境变量）不能在信任建立前激活。多种入口模式（CLI、服务器、SDK）共享同一 Bootstrap 路径，不同入口点。
从这里开始： 让所有 Hook 通过单一分发点。在加任何外部 Hook 类型之前先实现信任门控。在 init 时注册清理处理器，不在使用点。
在 Claude Code 中： 使用
/update-config配置 Hook（工具执行前/后、prompt 提交）。
权衡：
- 全有或全无的 Hook 信任简单但粗糙 — 一个不受信任的 Hook 禁用整个扩展系统。
- 磁盘后备任务输出保持内存恒定但增加与并发工作单元成正比的 I/O 延迟。
深入阅读： 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 的，不是：
- Prompt 工程或系统 prompt 设计
- 模型选择或微调
- 通用软件架构（MVC、微服务）
- 聊天 UI 或对话界面
- LLM API 集成基础
如果你的问题是关于模型本身而非模型周围的系统，本技能不适用。
Source: keli-wen/agentic-harness-patterns-skill — distributed by TomeVault.