12种 Agent Harness 设计模式
摘要
对 Agent 外层执行框架 Harness 的 12 种关键设计模式做系统分类。它们回答了「怎样给 Agent 一份好上下文、怎样让它可靠编排、怎样给它安全工具、怎样自动化规范动作」。
分为四大类:记忆与上下文(5)· 工作流与编排(3)· 工具与权限(3)· 自动化(1)。
来源:抖音图文 @LeO的AI产品进阶
全景速览
| # | 模式 | 类别 | 一句话 |
|---|---|---|---|
| 1 | 持久化指令文件 | 记忆与上下文 | 给 Agent 一份随仓库发布的持久规则文件 |
| 2 | 作用域上下文组装 | 记忆与上下文 | 按目录动态组装多层指令 |
| 3 | 分层记忆 | 记忆与上下文 | 记忆按层级 + 不同加载策略 |
| 4 | 梦境巩固 | 记忆与上下文 | 后台定期去重、修剪、重组记忆 |
| 5 | 渐进式上下文压缩 | 记忆与上下文 | 按历史新旧程度分级压缩 |
| 6 | 探索-计划-行动循环 | 工作流与编排 | 三阶段、写权限逐步提升 |
| 7 | 上下文隔离子代理 | 工作流与编排 | 子 Agent 各自独立上下文与工具 |
| 8 | 分叉-汇合并行 | 工作流与编排 | 多子 Agent 在隔离工作树并行 + 自动合并 |
| 9 | 逐步扩展工具 | 工具与权限 | 以小工具集起步,按需启用更多 |
| 10 | 命令风险分类 | 工具与权限 | 预先给每条命令定风险与动作 |
| 11 | 单一职责工具 | 工具与权限 | 专用工具取代通用 shell |
| 12 | 确定性生命周期钩子 | 自动化 | 在生命周期节点强制执行必备动作 |
📷 图解全景


类别一:记忆与上下文(Memory & Context)
这五种模式构成一条渐进路径:从给 Agent 一份静态规则文件 → 按目录范围限定规则 → 将记忆分层 → 后台清理记忆 → 上下文满载时压缩对话本身。




1. 持久化指令文件模式(Persistent Instruction File)
- 问题:没有持久指令文件,每次会话从空白开始,重复定义约定/命令/边界;第 5 次会话还犯第 1 次同样的错。
- 做法:引入随仓库发布的持久项目级配置文件(如
CLAUDE.md),每次会话自动加载,定义构建/测试命令、架构规则、命名规范与编码标准。 - 核心作用:多会话处理同一代码库时用。权衡:文件需随项目演进持续维护;过时的指令文件比没有更糟(会教会 Agent 过时规则)。
2. 作用域上下文组装模式(Scoped Context Assembly)
- 问题:项目变大后,单一指令文件要么变成难以维护的「大泥团」,要么太通用、对各目录无实际意义。
- 做法:从多个文件按不同作用域(组织 / 用户 / 项目根 / 父级 / 子目录)动态加载指令;Agent 按在代码库中的位置看到不同规则;导入语法支持拆分成多个文件、避免重复定义。
- 核心作用:单体仓库/多语言/不同目录不同规范的项目。权衡:可发现性——配置分散时更难理解 Agent 实际看到什么;作用域冲突可能导致意外行为。
3. 分层记忆模式(Tiered Memory)
- 问题:以相同方式记所有内容的 Agent 什么都记不牢;每轮全量加载既费 token 又触发尺寸限制、还淹没有用信息。
- 做法:把记忆分成多个独立层次、采用不同加载策略:①精简索引(如最多保留 200 行)始终在上下文;②主题文件按需加载;③完整会话记录存磁盘、仅需要时检索。
- 核心作用:跨会话保留偏好/决策/工作流状态。权衡:需决定信息放哪层、何时升降层、保持索引同步,复杂度高。
4. 梦境巩固模式(Dream Consolidation)
- 问题:即使分层,记忆仍会随时间退化——重复条目累积、过时与新信息矛盾、索引膨胀。
- 做法:运行一个后台进程,在空闲时段定期审查、去重、修剪、重组记忆——可视作 Agent 状态的「垃圾回收」。
- 核心作用:Agent 在多个会话积累大量记忆且无法靠人工整理时用。权衡:整合过程消耗 token 且可能出错;过度修剪可能误删仍需要的内容。
5. 渐进式上下文压缩模式(Progressive Context Compaction)
- 问题:长会话最终触达上下文窗口上限,要么丢最早的上下文、要么停止运行,多轮推理任务两者都不可接受。
- 做法:应用多级压缩,按历史新旧分级:新轮次保持完整细节、较旧轮次轻度摘要、非常久远轮次大幅折叠。
- 核心作用:会话经常超过 20-30 轮时用。权衡:有损压缩——每级摘要都会丢细节;后续需从折叠片段取信息时,Agent 可能「编造」而非承认遗忘。
类别二:工作流与编排(Workflow & Orchestration)


6. 探索-计划-行动循环模式(Explore-Plan-Act Loop)
- 问题:Agent 直接进入编辑,往往基于不完整理解就动手——误改文件、遗漏依赖、忽视现有模式。
- 做法:把工作流分成三阶段,写权限逐步提升:探索(只读、搜索、绘制代码库结构)→ 计划(与用户讨论方案)→ 执行(获得工具完全访问权)。
- 核心作用:陌生代码库 / 需在多个文件做非平凡修改的任务。权衡:速度——强制探索与规划在输出前增加额外回合,简单任务显得慢。
7. 上下文隔离子代理模式(Context-Isolated Subagents)
- 问题:长会话中上下文不断累积研究、规划、代码修改、测试结果、错误日志,到编辑阶段已被无关内容污染。
- 做法:运行多个独立 Agent,各自拥有独立上下文窗口、系统提示和受限工具(研究 Agent 不能编辑代码、规划 Agent 不能执行命令),每个只见与其任务相关的信息。
- 核心作用:长会话、多阶段、或上下文需求差异大的任务。权衡:协调开销——主 Agent 要决定传给每个子 Agent 什么;早期阶段的重要细节可能在交接中丢失。
8. 分叉-汇合并行模式(Fork-Join Parallelism)
- 问题:大任务虽可拆成独立单元,但一次只处理一个时仍是顺序执行(如 20 个文件各有独立迁移,仍要依次跑 20 步)。
- 做法:并行启动多个子 Agent,各自在仓库独立副本的隔离 Git 工作树中运行;父进程缓存上下文被各分支复用(token 成本几乎无额外开销);全部完成后自动合并。
- 核心作用:可并行拆分的大任务,追求吞吐。权衡:合并冲突与一致性管理。
类别三:工具与权限(Tools & Permissions)


9. 逐步扩展工具模式(Progressive Tool Expansion)
- 问题:同时给 Agent 所有工具会造成选择难题——60 种工具可见时模型更耗时、更容易选错。
- 做法:先给一个小的默认工具集(如 <20 个:读取/编辑/写入/Bash/Grep/Glob 等),按需启用更多;MCP 工具、远程工具、自定义技能仅在使用时激活。
- 核心作用:Agent 可访问多种工具但多数任务只用其中少数时。权衡:扩展逻辑增加复杂性(Agent 要决定何时启用);启用过晚会让它在缺乏能力时浪费行动次数。
10. 命令风险分类模式(Command Risk Classification)
- 问题:让 Agent 不加检查执行任意 shell 命令危险;但每条都要求用户确认又令人疲惫、最终全点「是」。
- 做法:执行前应用确定性的预解析与基于工具的权限控制;每种工具设独立「允许/询问/拒绝」规则并支持模式匹配(如
npm test→安全自动跑、git push --force→风险询问、rm -rf /→危险拦截)。 - 核心作用:Agent 会执行 shell 命令或与外部系统交互时。权衡:刚性——确定性分类器无法预判所有安全/危险命令,规则需持续调整。
11. 单一职责工具设计模式(Single-Purpose Tool Design)
- 问题:所有文件操作都走通用 shell(cat/sed/grep/find)时,更难审查、更难做权限管控、更难被模型正确理解——一条编辑文件的 sed 与一条破坏文件的 sed 结构几乎相同。
- 做法:用针对每种常见操作的专用工具取代通用 shell:
FileReadTool、FileEditTool、GrepTool、GlobTool;每个工具具有类型化输入、受限作用域与独立权限规则。 - 核心作用:Agent 频繁执行常见文件和搜索操作时。权衡:灵活性——专用工具覆盖不了所有边界情况,仍需通用 shell 备用。
类别四:自动化(Automation)

12. 确定性生命周期钩子模式(Deterministic Lifecycle Hooks)
- 问题:有些操作必须每次不容例外地执行(每次编辑后跑格式化、执行命令前验证、工作目录变化时重载配置);依赖模型记住这些不可靠——它会受上下文压力遗忘、跳过或重新解释。
- 做法:在 Agent 生命周期的特定节点自动执行(SessionStart / ToolUse / CwdChanged 等事件的前置/后置钩子),完全无需用户干预;凡是每次都要执行的操作放进钩子、而非写进指令。
- 核心作用:遇到不应被跳过的固定行为时用。权衡:调试难度——钩子在对话之外执行,异常时比提示级指令更难排查。
设计哲学
记忆与上下文模式管「Agent 知道什么」,工作流模式管「它怎么运作」,工具与权限管「它被允许做什么」,自动化模式贯穿所有类别(因为模型无法可靠记住必须每次都执行的程序性步骤)。
📚 相关笔记
- Claude Code 架构深度拆解 — 上述模式在真实生产级 Agent Runtime 中的落地实例
- 看完这条:AI 七层全貌 — Harness 在这七层体系中的定位
- Anthropic-Agent产品设计新范式 — Harness 把关工具 / 上下文分层的官方新范式
- AI 大模型 MOC