所属阶段：第二阶段「组件精讲」（第 4-15 课） 前置条件：第 5 课 本课收获：掌握 Agent 的四个 frontmatter 字段及其设计要点
一、本课概述
Agent 是 ECC 中最"活跃"的组件 — 它们是真正执行任务的专家。本课我们将：
- 解析 Agent 文件结构 — YAML frontmatter + Markdown 正文
- 深入四个字段 — name、description、tools、model 各有什么设计考量
- 学习 description 的精准写法 — 这是 Agent 的"简历"，决定了触发效果
- 理解 tools 的最小权限 — 不同 Agent 为什么需要不同的工具集
- 掌握 model 的选择策略 — Haiku、Sonnet、Opus 各在什么场景使用
- 建立 Agent 全景视图 — 47 个 Agent 的分类和定位
二、Agent 文件结构
每个 Agent 文件由两部分组成：
┌────────────────────────────────────┐
│ YAML Frontmatter（结构化元数据） │
│ --- │
│ name: code-reviewer │
│ description: Expert code review...│
│ tools: ["Read", "Grep", "Glob"] │
│ model: sonnet │
│ --- │
├────────────────────────────────────┤
│ Markdown 正文（行为定义） │
│ │
│ 角色定义 │
│ 工作流程 │
│ 输出格式 │
│ 约束条件 │
│ ... │
└────────────────────────────────────┘
2.1 完整示例
以 agents/code-reviewer.md 为例：
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. MUST BE USED for all code changes.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---
正文部分定义了：
- 角色："You are a senior code reviewer ensuring high standards of code quality and security."
- 流程：收集上下文 → 理解范围 → 阅读周围代码 → 应用审查清单 → 报告发现
- 输出格式：按 CRITICAL / HIGH / MEDIUM / LOW 分级报告
- 约束：只报告 80% 以上确信度的问题
2.2 Frontmatter vs 正文的分工
| 部分 | 职责 | 谁读 |
|---|---|---|
| Frontmatter | 结构化元数据，供系统路由和配置 | Claude 的调度系统 |
| 正文 | 行为定义，指导 Agent 如何工作 | 被委派任务的 Agent 实例 |
Frontmatter 决定 Agent 何时被调用、能用什么工具、用什么模型。正文决定 Agent 被调用后具体做什么。
三、四个字段设计决策表
| 字段 | 类型 | 设计目标 | 关键原则 |
|---|---|---|---|
name | 字符串 | 简短语义化标识 | 一看就知道做什么 |
description | 字符串 | 精确触发描述 | Agent 的"简历"，影响调度 |
tools | 字符串数组 | 可用工具列表 | 最小权限原则 |
model | 字符串 | 推荐使用的模型 | 按任务复杂度选择 |
四、name 字段 — 简短语义化
4.1 命名规范
- 使用小写字母 + 连字符（kebab-case）
- 简短但语义清晰
- 名称应该能一眼看出 Agent 的职责
4.2 命名模式
| 模式 | 示例 | 含义 |
|---|---|---|
<动作>er | code-reviewer, planner | 执行某个动作的角色 |
<语言>-reviewer | go-reviewer, python-reviewer | 语言特定审查者 |
<语言>-build-resolver | go-build-resolver, rust-build-resolver | 语言特定构建修复 |
<领域>-specialist | seo-specialist | 领域专家 |
<功能>-<角色> | tdd-guide, doc-updater | 功能 + 角色 |
4.3 反面示例
# 太模糊
name: helper # 帮什么？
name: agent-1 # 无语义
# 太长
name: code-quality-and-security-review-specialist # 过度描述
# 正确
name: code-reviewer # 简短、明确、一目了然
五、description 字段 — 精确触发
5.1 为什么 description 最重要
description 是 Agent 的"简历"。当 Claude 需要决定是否委派任务给某个 Agent 时，主要依据就是 description。
写得太泛 → 误触发（不该调用的时候被调用） 写得太窄 → 漏触发（该调用的时候没被调用）
5.2 好的 description 的特征
分析几个实际的 description：
code-reviewer：
Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. MUST BE USED for all code changes.
拆解：
Expert code review specialist— 身份定义Proactively reviews code for quality, security, and maintainability— 能力描述Use immediately after writing or modifying code— 触发时机MUST BE USED for all code changes— 强制使用指令
planner：
Expert planning specialist for complex features and refactoring. Use PROACTIVELY when users request feature implementation, architectural changes, or complex refactoring. Automatically activated for planning tasks.
拆解：
Expert planning specialist— 身份for complex features and refactoring— 擅长领域Use PROACTIVELY when...— 触发条件列表Automatically activated— 自动触发提示
5.3 Description 写作公式
<身份/专业> + <能力范围> + <触发时机/条件> + [强制性指令]
触发关键词：
Use PROACTIVELY when...— 告诉调度系统主动调用MUST BE USED for...— 强制调用Automatically activated for...— 自动激活
5.4 反面示例
# 太泛：什么代码都可能匹配
description: Helps with code.
# 太窄：只提到一个场景
description: Reviews Python Flask API endpoints for SQL injection.
# 没有触发时机
description: Expert security specialist focused on vulnerabilities.
# 改进：加上 "Use PROACTIVELY after writing code that handles user input..."
六、tools 字段 — 最小权限原则
6.1 原则
每个 Agent 只应该拥有完成其任务所需的最少工具。这是安全设计的核心原则。
6.2 可用工具列表
ECC Agent 可以使用的工具：
| 工具 | 能力 | 风险级别 |
|---|---|---|
Read | 读取文件内容 | 低 |
Grep | 搜索文件内容 | 低 |
Glob | 搜索文件路径 | 低 |
Bash | 执行命令行命令 | 高 |
Write | 创建/覆盖文件 | 高 |
Edit | 修改文件内容 | 高 |
WebSearch | 网络搜索 | 中 |
WebFetch | 获取网页内容 | 中 |
6.3 典型的工具组合
| 工具组合 | 适用类型 | 示例 Agent |
|---|---|---|
| Read, Grep, Glob | 只读分析型 | planner, architect, code-reviewer |
| Read, Grep, Glob, Bash | 分析 + 运行命令 | go-reviewer, python-reviewer |
| Read, Write, Edit, Bash, Grep, Glob | 完整读写型 | tdd-guide, security-reviewer, build-error-resolver |
| Read, Write, Grep, Glob | 读写但不运行命令 | gan-planner |
| Read, Grep, Glob, Bash, WebSearch, WebFetch | 分析 + 网络访问 | seo-specialist |
6.4 设计决策分析
为什么 planner 只有 Read/Grep/Glob？
planner 的职责是制定实施计划，不是执行计划。它需要读取代码来理解现状，但不应该修改任何东西。给它 Write 或 Bash 权限是不必要的风险。
# planner — 只读，只需要理解代码
tools: ["Read", "Grep", "Glob"]
为什么 code-reviewer 有 Bash 但没有 Write/Edit？
code-reviewer 需要运行 git diff 来查看变更，但它的职责是审查代码，不是修改代码。审查结果以文字报告形式输出，不需要写文件。
# code-reviewer — 读取 + 运行 git 命令，但不修改
tools: ["Read", "Grep", "Glob", "Bash"]
为什么 tdd-guide 需要完整工具集？
tdd-guide 需要写测试文件（Write/Edit）、运行测试（Bash）、查找相关代码（Read/Grep）。它是一个端到端执行 TDD 流程的 Agent，必须有完整的读写执行能力。
# tdd-guide — 完整 TDD 流程需要所有工具
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
为什么 doc-updater 用 haiku 但有完整工具集？
doc-updater 的任务相对简单（更新文档），不需要深度推理。但它确实需要读取代码、修改文档文件、运行命令生成文档。因此工具集是完整的，但模型选了最轻量的 haiku。
# doc-updater — 简单任务，完整工具，轻量模型
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: haiku
七、model 字段 — 按复杂度选择
7.1 三种模型定位
| 模型 | 能力 | 成本 | 适用场景 |
|---|---|---|---|
| haiku | Sonnet 的 ~90% 能力 | Sonnet 的 1/3 | 轻量高频任务 |
| sonnet | 最佳编码模型 | 中等 | 主力开发任务 |
| opus | 最深推理能力 | 最高 | 深度分析和决策 |
7.2 模型选择的实际分布
在 ECC 的 47 个 Agent 中，模型分布如下：
| 模型 | Agent 数量 | 占比 | 代表性 Agent |
|---|---|---|---|
| sonnet | ~38 个 | ~81% | code-reviewer, tdd-guide, security-reviewer, build-error-resolver |
| opus | ~6 个 | ~13% | planner, architect, gan-planner |
| haiku | ~3 个 | ~6% | doc-updater |
7.3 选择策略
需要深度推理？（架构设计、复杂规划、多步推导）
├── 是 → opus
└── 否 →
任务简单且高频？（文档更新、简单检查、Worker）
├── 是 → haiku（节省 2/3 成本）
└── 否 → sonnet（主力选择）
7.4 决策示例
| Agent | 选择 | 理由 |
|---|---|---|
| planner | opus | 需要深度推理来分析需求、拆解任务、预判风险 |
| architect | opus | 系统设计需要最深的架构思考能力 |
| code-reviewer | sonnet | 代码审查是主力任务，sonnet 已足够 |
| tdd-guide | sonnet | TDD 流程复杂但模式化，sonnet 胜任 |
| build-error-resolver | sonnet | 修复构建错误需要代码理解，但不需最深推理 |
| doc-updater | haiku | 文档更新是结构化的轻量任务，haiku 足以胜任 |
八、Agent 分类全景
47 个 Agent 可以按职能分为五大类：
8.1 核心流程类（6 个）
开发生命周期中的核心角色：
| Agent | model | tools 特点 | 职责 |
|---|---|---|---|
| planner | opus | 只读 | 实施规划 |
| architect | opus | 只读 | 系统设计 |
| code-reviewer | sonnet | 读 + Bash | 代码审查 |
| tdd-guide | sonnet | 完整读写 | TDD 引导 |
| security-reviewer | sonnet | 完整读写 | 安全审查 |
| build-error-resolver | sonnet | 完整读写 | 构建修复 |
8.2 代码质量类（6 个）
专注于代码质量改进：
| Agent | 职责 |
|---|---|
| refactor-cleaner | 死代码清理和重构 |
| performance-optimizer | 性能分析和优化 |
| code-simplifier | 代码简化 |
| code-explorer | 代码库探索和理解 |
| type-design-analyzer | 类型设计分析 |
| silent-failure-hunter | 静默失败检测 |
8.3 语言审查类（10+ 个）
针对特定语言的代码审查：
| Agent | 语言 |
|---|---|
| go-reviewer | Go |
| python-reviewer | Python |
| typescript-reviewer | TypeScript |
| rust-reviewer | Rust |
| java-reviewer | Java |
| kotlin-reviewer | Kotlin |
| cpp-reviewer | C++ |
| csharp-reviewer | C# |
| dart-build-resolver / flutter-reviewer | Dart / Flutter |
8.4 构建修复类（6+ 个）
针对特定语言/框架的构建错误修复：
| Agent | 目标 |
|---|---|
| go-build-resolver | Go 构建错误 |
| rust-build-resolver | Rust 编译错误 |
| java-build-resolver | Java/Maven/Gradle |
| kotlin-build-resolver | Kotlin 构建错误 |
| cpp-build-resolver | C++ 编译错误 |
| pytorch-build-resolver | PyTorch 构建环境 |
8.5 特殊领域类（10+ 个）
面向特定领域的专家：
| Agent | 领域 |
|---|---|
| database-reviewer | PostgreSQL / 数据库 |
| seo-specialist | SEO 优化 |
| healthcare-reviewer | 医疗健康合规 |
| doc-updater | 文档维护 |
| e2e-runner | E2E 测试 |
| gan-planner / gan-generator / gan-evaluator | GAN 多代理协作 |
| harness-optimizer | ECC 自身优化 |
| opensource-forker / opensource-packager / opensource-sanitizer | 开源项目处理 |
九、本课练习
练习 1：浏览 10 个 Agent 的 frontmatter（15 分钟）
打开以下 10 个 Agent 文件，只看 frontmatter 部分，填写对比表：
# 分别打开这些文件
cat agents/planner.md
cat agents/code-reviewer.md
cat agents/tdd-guide.md
cat agents/security-reviewer.md
cat agents/build-error-resolver.md
cat agents/doc-updater.md
cat agents/architect.md
cat agents/go-reviewer.md
cat agents/performance-optimizer.md
cat agents/seo-specialist.md
| Agent | tools 数量 | 有 Write/Edit? | model |
|---|---|---|---|
| planner | |||
| code-reviewer | |||
| tdd-guide | |||
| security-reviewer | |||
| build-error-resolver | |||
| doc-updater | |||
| architect | |||
| go-reviewer | |||
| performance-optimizer | |||
| seo-specialist |
练习 2：分析 description 的触发关键词（10 分钟）
重新阅读练习 1 中 10 个 Agent 的 description，回答：
- 有多少个包含 "PROACTIVELY"？
- 有多少个包含 "MUST BE USED"？
- 哪些用了 "Automatically activated"？
- 这些关键词有什么区别？
练习 3：设计一个新 Agent 的 frontmatter（10 分钟）
假设你要创建一个"API 文档生成"Agent，设计它的 frontmatter：
---
name: ???
description: ???
tools: [???]
model: ???
---
思考：
- name 应该简短明确
- description 应该包含触发时机
- tools 需要什么？（只读还是读写？需要 Bash 吗？）
- model 选哪个？（简单任务还是复杂推理？）
练习 4（选做）：统计工具分布
浏览全部 47 个 Agent 文件的 frontmatter，统计：
- 有多少个 Agent 只有只读工具（Read/Grep/Glob）？
- 有多少个 Agent 有完整读写工具？
- 有多少个 Agent 使用了 WebSearch/WebFetch？
十、本课小结
| 你应该记住的 | 内容 |
|---|---|
| 文件结构 | YAML frontmatter（4 个字段）+ Markdown 正文 |
| name | 小写连字符，简短语义化 |
| description | Agent 的"简历"，决定触发效果；包含身份 + 能力 + 触发时机 |
| tools | 最小权限原则；只读型 vs 完整读写型 |
| model 分布 | sonnet ~81%、opus ~13%、haiku ~6% |
| 选择策略 | 深度推理 → opus，主力任务 → sonnet，轻量高频 → haiku |
| Agent 总数 | 47 个，分为核心流程 / 代码质量 / 语言审查 / 构建修复 / 特殊领域五大类 |
十一、下节预告
第 7 课：Agents（下）— 行为定义与编排模式
下节课我们将深入 Agent 的 Markdown 正文部分，学习如何定义 Agent 的行为、工作流和输出格式。还将学习多 Agent 编排模式：串行委派、并行执行、GAN 对抗等。
预习建议：完整阅读 agents/code-reviewer.md 和 agents/tdd-guide.md 的正文部分（不只是 frontmatter），注意它们如何定义工作流和输出格式。
