agentic-harness-patterns-zh

Category: Tools & Productivity | Uploader: keli-wen | Downloads: 0 | Version: v1.0（Latest）
Changelog: Source: GitHub https://github.com/keli-wen/agentic-harness-patterns-skill
Directory Structure

Current level: tree/master/skills/agentic-harness-patterns-zh/
📁 references/
- 📁 context-engineering/
  - 📄 compress-pattern.md 7.2 KB
  - 📄 isolate-pattern.md 8.4 KB
  - 📄 select-pattern.md 7.8 KB
- 📄 agent-orchestration-pattern.md 12.0 KB
- 📄 bootstrap-sequence-pattern.md 12.5 KB
- 📄 context-engineering-pattern.md 2.1 KB
- 📄 hook-lifecycle-pattern.md 12.9 KB
- 📄 memory-persistence-pattern.md 12.4 KB
- 📄 permission-gate-pattern.md 12.8 KB
- 📄 skill-runtime-pattern.md 12.9 KB
- 📄 task-decomposition-pattern.md 7.9 KB
- 📄 tool-registry-pattern.md 11.4 KB
📄 metadata.json 459 B
📄 SKILL.md 15.5 KB
SKILL.md

---
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** 将初始化结构化为按依赖排序的、记忆化的阶段。信任边界 — 用户授权同意的时刻 — 是关键拐点：安全敏感子系统（遥测、秘密环境变量）不能在信任建立前激活。多种入口模式（CLI、服务器、SDK）共享同一 Bootstrap 路径，不同入口点。

**从这里开始：** 让所有 Hook 通过单一分发点。在加任何外部 Hook 类型之前先实现信任门控。在 init 时注册清理处理器，不在使用点。

> **在 Claude Code 中：** 使用 `/update-config` 配置 Hook（工具执行前/后、prompt 提交）。

**权衡：**

- 全有或全无的 Hook 信任简单但粗糙 — 一个不受信任的 Hook 禁用整个扩展系统。
- 磁盘后备任务输出保持内存恒定但增加与并发工作单元成正比的 I/O 延迟。

**深入阅读：** [references/hook-lifecycle-pattern.md](references/hook-lifecycle-pattern.md) | [references/task-decomposition-pattern.md](references/task-decomposition-pattern.md) | [references/bootstrap-sequence-pattern.md](references/bootstrap-sequence-pattern.md)

---

## 踩坑指南

违反这些原则会导致 bug 的非直觉设计：

1. **并发分类是按调用的，不是按工具类型。** 同一工具对某些输入安全、对另一些不安全。不要假设工具的并发行为是静态的 — 运行时按调用决定。

2. **权限评估有副作用。** 权限检查器追踪拒绝次数、转换模式、更新状态。不要把它当纯查询函数。

3. **大多数异步工作跳过 "pending" 状态。** 实践中，工作单元直接注册为 "running"。不要构建假设每个工作单元从 pending 开始的 UI。

4. **Fork 子级不能 fork。** 递归保护维护单层不变式。Fork 工具留在子级工具池中（为了 prompt 缓存共享）但在调用时被阻止。

5. **上下文构建器是记忆化的但手动失效。** 添加上下文源而不添加对应的失效点，模型在整个会话中看到过时数据。

6. **记忆索引有硬上限。** 超过上限的条目被静默截断。不定期清理的话，新条目变得不可见。

7. **技能列表预算很紧。** 描述被拼接并按条目限制字符。把最具区分度的触发语言放在前面 — 后面会被截掉。

8. **Hook 信任是全有或全无。** 工作区不受信任时，整个 Hook 系统被禁用，不只是个别可疑的 Hook。

9. **工具的默认权限是 "allow"。** 没有实现自定义权限逻辑的工具完全委托给基于规则的系统。只在需要工具特定门控（路径 ACL、配额等）时才覆盖。

10. **回收需要通知。** 终态工作单元只有在父级收到完成信号后才可被 GC。在通知前回收会产生竞态，父级永远读不到结果。

---

## 本技能不适用于

本技能是关于 Agent **周围的 harness** 的，不是：
- Prompt 工程或系统 prompt 设计
- 模型选择或微调
- 通用软件架构（MVC、微服务）
- 聊天 UI 或对话界面
- LLM API 集成基础

如果你的问题是关于模型本身而非模型周围的系统，本技能不适用。
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
agentic-harness-patterns-zh

Directory Structure

SKILL.md

Report

Notice
