agentic-harness-patterns-zh

Name: agentic-harness-patterns-zh
Author: keli-wen

168installs48forks

How to install agentic-harness-patterns-zh?

keli-wen/agentic-harness-patterns-skill/agentic-harness-patterns-zh

$npx -y skills add keli-wen/agentic-harness-patterns-skill --skill agentic-harness-patterns-zh

Installs into the current project.

Summary

AI Agent Harness 设计模式 — 记忆、权限、上下文工程、委派、技能、 Hook、Bootstrap。中文版。

Files · 1

View on GitHub

SKILL.md

1	# Agentic Harness Patterns（中文版）
2
3	生产级 AI 编程助手不只是"大模型 + 工具调用循环"。循环本身很简单。Harness — 记忆、技能、安全、上下文控制、委派、可扩展性 — 才是让 Agent 可靠、安全、大规模运行的关键。
4
5	适合：正在构建或扩展 AI Agent 运行时、自定义 Agent、或高级多 Agent 工作流的工程师。
6	不适合： Prompt 工程、模型选择、通用软件架构、LLM API 入门。
7
8	所有原则均从生产级运行时决策中提炼而来。Claude Code 作为实证依据，而非唯一实现。
9
10	## 选择你的问题
11
12	\| 你想要... \| 阅读 \|
13	\|---\|---\|
14	\| 让 Agent 跨会话记住并持续改进 \| [记忆系统](#1-记忆系统) \|
15	\| 打包可复用的工作流和专业知识 \| [技能系统](#2-技能系统) \|
16	\| 让 Agent 强大地使用工具但不危险 \| [工具与安全](#3-工具与安全) \|
17	\| 给 Agent 正确的上下文、合理的成本 \| [上下文工程](#4-上下文工程) \|
18	\| 将工作拆分给多个 Agent 而不失控 \| [多 Agent 协调](#5-多-agent-协调) \|
19	\| 通过 Hook、后台任务或启动逻辑扩展行为 \| [生命周期与可扩展性](#6-生命周期与可扩展性) \|
20
21	开始构建之前：先读 [踩坑指南](#踩坑指南) — 这些是最不直觉但最烧时间的失败模式。
22
23	---
24
25	## 1. 记忆系统
26
27	用户痛点： "我的 Agent 下次对话就忘了所有纠正和项目规则。"
28
29	黄金法则：区分 Agent 知道的（指令记忆）、Agent 学到的（自动记忆）、和 Agent 提取的（会话记忆）。三层的持久性、信任度、审查需求各不相同。
30
31	适用场景：任何跨会话运行或需要持续积累项目知识的 Agent。
32
33	工作原理：
34
35	- 指令记忆是人工策划的、分层的配置，按优先级注入系统上下文（组织级 → 用户级 → 项目级 → 本地级；本地优先）。项目编码规范、行为规则都在这里。它是人类编写的，稳定不变。
36	- 自动记忆是 Agent 自主写入的持久知识，带有类型分类法（用户 / 反馈 / 项目 / 引用）和有上限的索引。写入是两步操作：先写主题文件，再更新索引。上限防止无限增长 — 不清理的话，新条目会被静默截断。
37	- 会话提取以后台 Agent 的形式在会话结束时运行。它直接写入自动记忆 — 先主题文件再索引 — 遵循相同的两步保存不变式。互斥锁确保：如果主 Agent 在当轮已经写过记忆，提取器直接跳过。这是自主学习循环。
38	- 审查与晋升审计所有记忆层并提议跨层移动（自动记忆 → 项目规范、个人设置或团队记忆）。它永远不自主应用更改 — 提议需要用户明确批准。
39
40	从这里开始：定义你的记忆层（指令、自动、提取）。实现两步保存不变式（先主题文件，再索引）。核心写入路径稳定后再加后台提取。
41
42	> 在 Claude Code 中：使用 `/remember` 审计和晋升各层自动记忆条目。
43
44	权衡：
45
46	- 更多记忆层 = 更丰富的回忆但更高的维护负担。不定期清理的话，索引上限导致静默数据丢失。
47	- 会话提取在会话结束时增加延迟，但大幅提升跨会话学习能力。
48
49	深入阅读： [references/memory-persistence-pattern.md](references/memory-persistence-pattern.md)
50
51	---
52
53	## 2. Skills 系统
54
55	用户痛点： "我想让 Agent 复用工作流和领域知识，不用每次重新解释。"
56
57	黄金法则：技能是懒加载的指令集，不是立即注入的 prompt。发现必须廉价（仅元数据）；完整内容只在激活时加载。
58
59	适用场景：任何需要可复用、可组合工作流并根据用户意图匹配激活的 Agent。
60
61	工作原理：
62
63	- 发现是预算约束的：Agent 看到所有可用技能的紧凑列表（名称、描述、触发提示拼接在一起），每条硬限在固定字符数，总量限制在上下文窗口的约 1%。把触发关键词放在前面 — 后面会被截断。
64	- 加载是懒的：只有元数据进入始终在线的上下文。完整技能内容只在激活时加载，闲置 token 成本接近零。
65	- 执行可以是内联的（共享上下文）或隔离的（fork 子 Agent，有自己的 token 预算）。隔离防止重型技能耗尽父级上下文。
66	- 来源可以是内置的、用户安装的、或从插件动态加载的。通过规范路径去重，防止同一技能在重叠的源目录中出现两次。
67
68	从这里开始：选一种元数据格式（推荐 frontmatter）。实现两阶段发现：启动时廉价列表，调用时懒加载内容。在目录增长前设好每条字符上限。
69
70	权衡：
71
72	- 懒加载省 token 但首次激活多一轮延迟。
73	- Fork 执行提供隔离但失去父级已积累的上下文。
74
75	深入阅读： [references/skill-runtime-pattern.md](references/skill-runtime-pattern.md)
76
77	---
78
79	## 3. 工具与安全
80
81	用户痛点： "我想让 Agent 强大地使用工具，但不要危险。"
82
83	黄金法则：默认关闭（fail-closed）。工具是串行的、有门控的，除非显式标记为并发安全且通过了权限管道。
84
85	适用场景：任何需要工具注册、并发控制或权限门控的 Agent 运行时。
86
87	工作原理：
88
89	- 注册使用 fail-closed 默认值：工具默认不可并发、非只读，除非开发者主动标记。这防止状态变更操作的意外并行执行。
90	- 并发分类是按调用的，不是按工具类型：同一工具对某些输入安全、对另一些不安全。运行时将一批工具调用分成连续组 — 安全调用并行执行，任何不安全调用开始一个串行段。
91	- 权限管道从多个来源按严格优先级顺序评估规则，涵盖配置文件（用户、项目、本地、标志、策略）、CLI 参数、命令级规则和会话授权。评估器是有状态的 — 它追踪拒绝次数、转换模式、更新状态作为副作用。
92	- 处理器分发因执行环境而异：交互式（人类提示）、自动化（协调器）或异步（Swarm Agent）。相同的权限规则供给不同的审批界面。
93
94	从这里开始：让每个工具调用都通过一个权限关卡。默认 fail-closed（拒绝/询问）。在上线任何自动批准模式之前，先加上受保护路径的免豁免规则。
95
96	> 在 Claude Code 中：使用 `/update-config` 配置权限规则和 Hook。
97
98	权衡：
99
100	- Fail-closed 默认值意味着新工具开箱即安全，但开发者必须主动标记并发安全 — 忘记标记只读工具会静默降低吞吐量。
101	- 多来源权限分层功能强大但规则冲突时难以调试。
102
103	深入阅读： [references/tool-registry-pattern.md](references/tool-registry-pattern.md) \| [references/permission-gate-pattern.md](references/permission-gate-pattern.md)
104
105	---
106
107	## 4. 上下文工程
108
109	用户痛点： "我的 Agent 看到太多、太少、或者看错了。"
110
111	黄金法则：把上下文当预算管，不是垃圾桶。窗口里的每个 token 都必须通过四种操作之一赢得它的位置：选择、写回、压缩、隔离。
112
113	适用场景：任何在长会话中性能下降、委派工作污染父上下文、或因急切加载导致启动慢的 Agent。
114
115	工作原理：
116
117	- 选择 — 按需加载，不要一次全加载。使用三级渐进披露：元数据（始终存在，廉价）、指令（激活时加载）、资源（按需加载）。记忆化昂贵的上下文构建器，只在已知变更点失效 — 不要响应式。
118	- 写回 — 上下文不是只读的。Agent 将信息写回持久存储：自动记忆条目、后台提取输出、任务状态、权限规则。写回循环是把无状态工具调用者变成学习系统的关键。
119	- 压缩 — 长会话耗尽窗口。响应式压实在会话中间总结旧轮次，保留近期上下文同时回收预算。将快照数据标记为快照，让模型知道要重新获取当前状态。
120	- 隔离 — 委派工作不能污染父级上下文。协调器 worker 零上下文继承（只有显式 prompt）。Fork 子级继承全部上下文但单层限制（不能递归 fork）。文件系统级隔离（worktree）给 Agent 自己的工作副本。
121
122	从这里开始：审计你当前每轮的上下文成本。对每个变长块加硬上限。在启用任何压缩之前，先加截断恢复指针（告诉模型调用哪个工具获取完整输出）。
123
124	权衡：
125
126	- 激进缓存降低延迟但有过时风险 — 每个变更点必须显式清除缓存，否则模型在剩余会话中用过时数据。
127	- 渐进披露省 token 但意味着模型在技能激活前无法推理其完整能力。
128
129	深入阅读： [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)
130
131	---
132
133	## 5. 多 Agent 协调
134
135	用户痛点： "我要并行、专业化和协调，但不要混乱。"
136
137	黄金法则：协调者必须自己综合，不能委派理解。"基于你的发现，修复它" 是反模式 — 协调者应该消化 worker 结果成精确规格，然后再派发实现。
138
139	适用场景：当任务对单个 Agent 太大时、需要并行探索时、或想要持久化的专业队友时。
140
141	工作原理：
142
143	三种委派模式服务不同的任务形态：
144
145	\| 模式 \| 上下文共享 \| 适合 \|
146	\|---------\|----------------\|----------\|
147	\| Coordinator \| 无 — worker 从零开始 \| 复杂多阶段任务（研究 → 综合 → 实现 → 验证） \|
148	\| Fork \| 全部 — 子级继承父级历史 \| 共享已加载上下文的快速并行拆分 \|
149	\| Swarm \| 对等共享任务列表 \| 长期运行的独立工作流 \|
150
151	关键约束：
152
153	- Fork 只有单层 — 递归 fork 会指数级放大上下文成本。
154	- Swarm 队友不能生成其他队友 — 名单是扁平的，防止不受控增长。
155	- 结

keli-wenPublisher · 3 listings

Preview

keli-wen/agentic-harness-patterns-skill

# Agentic Harness Patterns（中文版）

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

**适合：** 正在构建或扩展 AI Agent 运行时、自定义 Agent、或高级多 Agent 工作流的工程师。

**不适合：** Prompt 工程、模型选择、通用软件架构、LLM API 入门。

Repokeli-wen/agentic-harness-patterns-skill

LicenseMIT

TypeSkills

CategoryCoding

UpdatedApr 2026

Repo stars295

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type

agentic-harness-patterns-zh

168installs48forks

View on GitHub

How to install agentic-harness-patterns-zh?

keli-wen/agentic-harness-patterns-skill/agentic-harness-patterns-zh

$npx -y skills add keli-wen/agentic-harness-patterns-skill --skill agentic-harness-patterns-zh

Installs into the current project.

Summary

AI Agent Harness 设计模式 — 记忆、权限、上下文工程、委派、技能、 Hook、Bootstrap。中文版。

Files · 1

View on GitHub

SKILL.md

1	# Agentic Harness Patterns（中文版）
2
3	生产级 AI 编程助手不只是"大模型 + 工具调用循环"。循环本身很简单。Harness — 记忆、技能、安全、上下文控制、委派、可扩展性 — 才是让 Agent 可靠、安全、大规模运行的关键。
4
5	适合：正在构建或扩展 AI Agent 运行时、自定义 Agent、或高级多 Agent 工作流的工程师。
6	不适合： Prompt 工程、模型选择、通用软件架构、LLM API 入门。
7
8	所有原则均从生产级运行时决策中提炼而来。Claude Code 作为实证依据，而非唯一实现。
9
10	## 选择你的问题
11
12	\| 你想要... \| 阅读 \|
13	\|---\|---\|
14	\| 让 Agent 跨会话记住并持续改进 \| [记忆系统](#1-记忆系统) \|
15	\| 打包可复用的工作流和专业知识 \| [技能系统](#2-技能系统) \|
16	\| 让 Agent 强大地使用工具但不危险 \| [工具与安全](#3-工具与安全) \|
17	\| 给 Agent 正确的上下文、合理的成本 \| [上下文工程](#4-上下文工程) \|
18	\| 将工作拆分给多个 Agent 而不失控 \| [多 Agent 协调](#5-多-agent-协调) \|
19	\| 通过 Hook、后台任务或启动逻辑扩展行为 \| [生命周期与可扩展性](#6-生命周期与可扩展性) \|
20
21	开始构建之前：先读 [踩坑指南](#踩坑指南) — 这些是最不直觉但最烧时间的失败模式。
22
23	---
24
25	## 1. 记忆系统
26
27	用户痛点： "我的 Agent 下次对话就忘了所有纠正和项目规则。"
28
29	黄金法则：区分 Agent 知道的（指令记忆）、Agent 学到的（自动记忆）、和 Agent 提取的（会话记忆）。三层的持久性、信任度、审查需求各不相同。
30
31	适用场景：任何跨会话运行或需要持续积累项目知识的 Agent。
32
33	工作原理：
34
35	- 指令记忆是人工策划的、分层的配置，按优先级注入系统上下文（组织级 → 用户级 → 项目级 → 本地级；本地优先）。项目编码规范、行为规则都在这里。它是人类编写的，稳定不变。
36	- 自动记忆是 Agent 自主写入的持久知识，带有类型分类法（用户 / 反馈 / 项目 / 引用）和有上限的索引。写入是两步操作：先写主题文件，再更新索引。上限防止无限增长 — 不清理的话，新条目会被静默截断。
37	- 会话提取以后台 Agent 的形式在会话结束时运行。它直接写入自动记忆 — 先主题文件再索引 — 遵循相同的两步保存不变式。互斥锁确保：如果主 Agent 在当轮已经写过记忆，提取器直接跳过。这是自主学习循环。
38	- 审查与晋升审计所有记忆层并提议跨层移动（自动记忆 → 项目规范、个人设置或团队记忆）。它永远不自主应用更改 — 提议需要用户明确批准。
39
40	从这里开始：定义你的记忆层（指令、自动、提取）。实现两步保存不变式（先主题文件，再索引）。核心写入路径稳定后再加后台提取。
41
42	> 在 Claude Code 中：使用 `/remember` 审计和晋升各层自动记忆条目。
43
44	权衡：
45
46	- 更多记忆层 = 更丰富的回忆但更高的维护负担。不定期清理的话，索引上限导致静默数据丢失。
47	- 会话提取在会话结束时增加延迟，但大幅提升跨会话学习能力。
48
49	深入阅读： [references/memory-persistence-pattern.md](references/memory-persistence-pattern.md)
50
51	---
52
53	## 2. Skills 系统
54
55	用户痛点： "我想让 Agent 复用工作流和领域知识，不用每次重新解释。"
56
57	黄金法则：技能是懒加载的指令集，不是立即注入的 prompt。发现必须廉价（仅元数据）；完整内容只在激活时加载。
58
59	适用场景：任何需要可复用、可组合工作流并根据用户意图匹配激活的 Agent。
60
61	工作原理：
62
63	- 发现是预算约束的：Agent 看到所有可用技能的紧凑列表（名称、描述、触发提示拼接在一起），每条硬限在固定字符数，总量限制在上下文窗口的约 1%。把触发关键词放在前面 — 后面会被截断。
64	- 加载是懒的：只有元数据进入始终在线的上下文。完整技能内容只在激活时加载，闲置 token 成本接近零。
65	- 执行可以是内联的（共享上下文）或隔离的（fork 子 Agent，有自己的 token 预算）。隔离防止重型技能耗尽父级上下文。
66	- 来源可以是内置的、用户安装的、或从插件动态加载的。通过规范路径去重，防止同一技能在重叠的源目录中出现两次。
67
68	从这里开始：选一种元数据格式（推荐 frontmatter）。实现两阶段发现：启动时廉价列表，调用时懒加载内容。在目录增长前设好每条字符上限。
69
70	权衡：
71
72	- 懒加载省 token 但首次激活多一轮延迟。
73	- Fork 执行提供隔离但失去父级已积累的上下文。
74
75	深入阅读： [references/skill-runtime-pattern.md](references/skill-runtime-pattern.md)
76
77	---
78
79	## 3. 工具与安全
80
81	用户痛点： "我想让 Agent 强大地使用工具，但不要危险。"
82
83	黄金法则：默认关闭（fail-closed）。工具是串行的、有门控的，除非显式标记为并发安全且通过了权限管道。
84
85	适用场景：任何需要工具注册、并发控制或权限门控的 Agent 运行时。
86
87	工作原理：
88
89	- 注册使用 fail-closed 默认值：工具默认不可并发、非只读，除非开发者主动标记。这防止状态变更操作的意外并行执行。
90	- 并发分类是按调用的，不是按工具类型：同一工具对某些输入安全、对另一些不安全。运行时将一批工具调用分成连续组 — 安全调用并行执行，任何不安全调用开始一个串行段。
91	- 权限管道从多个来源按严格优先级顺序评估规则，涵盖配置文件（用户、项目、本地、标志、策略）、CLI 参数、命令级规则和会话授权。评估器是有状态的 — 它追踪拒绝次数、转换模式、更新状态作为副作用。
92	- 处理器分发因执行环境而异：交互式（人类提示）、自动化（协调器）或异步（Swarm Agent）。相同的权限规则供给不同的审批界面。
93
94	从这里开始：让每个工具调用都通过一个权限关卡。默认 fail-closed（拒绝/询问）。在上线任何自动批准模式之前，先加上受保护路径的免豁免规则。
95
96	> 在 Claude Code 中：使用 `/update-config` 配置权限规则和 Hook。
97
98	权衡：
99
100	- Fail-closed 默认值意味着新工具开箱即安全，但开发者必须主动标记并发安全 — 忘记标记只读工具会静默降低吞吐量。
101	- 多来源权限分层功能强大但规则冲突时难以调试。
102
103	深入阅读： [references/tool-registry-pattern.md](references/tool-registry-pattern.md) \| [references/permission-gate-pattern.md](references/permission-gate-pattern.md)
104
105	---
106
107	## 4. 上下文工程
108
109	用户痛点： "我的 Agent 看到太多、太少、或者看错了。"
110
111	黄金法则：把上下文当预算管，不是垃圾桶。窗口里的每个 token 都必须通过四种操作之一赢得它的位置：选择、写回、压缩、隔离。
112
113	适用场景：任何在长会话中性能下降、委派工作污染父上下文、或因急切加载导致启动慢的 Agent。
114
115	工作原理：
116
117	- 选择 — 按需加载，不要一次全加载。使用三级渐进披露：元数据（始终存在，廉价）、指令（激活时加载）、资源（按需加载）。记忆化昂贵的上下文构建器，只在已知变更点失效 — 不要响应式。
118	- 写回 — 上下文不是只读的。Agent 将信息写回持久存储：自动记忆条目、后台提取输出、任务状态、权限规则。写回循环是把无状态工具调用者变成学习系统的关键。
119	- 压缩 — 长会话耗尽窗口。响应式压实在会话中间总结旧轮次，保留近期上下文同时回收预算。将快照数据标记为快照，让模型知道要重新获取当前状态。
120	- 隔离 — 委派工作不能污染父级上下文。协调器 worker 零上下文继承（只有显式 prompt）。Fork 子级继承全部上下文但单层限制（不能递归 fork）。文件系统级隔离（worktree）给 Agent 自己的工作副本。
121
122	从这里开始：审计你当前每轮的上下文成本。对每个变长块加硬上限。在启用任何压缩之前，先加截断恢复指针（告诉模型调用哪个工具获取完整输出）。
123
124	权衡：
125
126	- 激进缓存降低延迟但有过时风险 — 每个变更点必须显式清除缓存，否则模型在剩余会话中用过时数据。
127	- 渐进披露省 token 但意味着模型在技能激活前无法推理其完整能力。
128
129	深入阅读： [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)
130
131	---
132
133	## 5. 多 Agent 协调
134
135	用户痛点： "我要并行、专业化和协调，但不要混乱。"
136
137	黄金法则：协调者必须自己综合，不能委派理解。"基于你的发现，修复它" 是反模式 — 协调者应该消化 worker 结果成精确规格，然后再派发实现。
138
139	适用场景：当任务对单个 Agent 太大时、需要并行探索时、或想要持久化的专业队友时。
140
141	工作原理：
142
143	三种委派模式服务不同的任务形态：
144
145	\| 模式 \| 上下文共享 \| 适合 \|
146	\|---------\|----------------\|----------\|
147	\| Coordinator \| 无 — worker 从零开始 \| 复杂多阶段任务（研究 → 综合 → 实现 → 验证） \|
148	\| Fork \| 全部 — 子级继承父级历史 \| 共享已加载上下文的快速并行拆分 \|
149	\| Swarm \| 对等共享任务列表 \| 长期运行的独立工作流 \|
150
151	关键约束：
152
153	- Fork 只有单层 — 递归 fork 会指数级放大上下文成本。
154	- Swarm 队友不能生成其他队友 — 名单是扁平的，防止不受控增长。
155	- 结