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确定性生命周期钩子自动化在生命周期节点强制执行必备动作

📷 图解全景

AI大模型/Agent/12种Agent Harness设计模式_图文/img_01.webp
AI大模型/Agent/12种Agent Harness设计模式_图文/img_02.webp


类别一:记忆与上下文(Memory & Context)

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

AI大模型/Agent/12种Agent Harness设计模式_图文/img_03.webp
AI大模型/Agent/12种Agent Harness设计模式_图文/img_04.webp
AI大模型/Agent/12种Agent Harness设计模式_图文/img_05.webp
AI大模型/Agent/12种Agent Harness设计模式_图文/img_06.webp

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)

AI大模型/Agent/12种Agent Harness设计模式_图文/img_07.webp
AI大模型/Agent/12种Agent Harness设计模式_图文/img_08.webp

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)

AI大模型/Agent/12种Agent Harness设计模式_图文/img_09.webp
AI大模型/Agent/12种Agent Harness设计模式_图文/img_10.webp

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)

AI大模型/Agent/12种Agent Harness设计模式_图文/img_11.webp

12. 确定性生命周期钩子模式(Deterministic Lifecycle Hooks)

  • 问题:有些操作必须每次不容例外地执行(每次编辑后跑格式化、执行命令前验证、工作目录变化时重载配置);依赖模型记住这些不可靠——它会受上下文压力遗忘、跳过或重新解释。
  • 做法:在 Agent 生命周期的特定节点自动执行(SessionStart / ToolUse / CwdChanged 等事件的前置/后置钩子),完全无需用户干预;凡是每次都要执行的操作放进钩子、而非写进指令。
  • 核心作用:遇到不应被跳过的固定行为时用。权衡:调试难度——钩子在对话之外执行,异常时比提示级指令更难排查。

设计哲学

记忆与上下文模式管「Agent 知道什么」,工作流模式管「它怎么运作」,工具与权限管「它被允许做什么」,自动化模式贯穿所有类别(因为模型无法可靠记住必须每次都执行的程序性步骤)。


📚 相关笔记