Agent 架构总览

这是「GSD 全景代码解析」专题的第 22 篇。

在前 21 篇文章中，我们系统梳理了 GSD 的命令系统和工作流编排层。但工作流从不执行真正的业务逻辑——它们只是 Thin Orchestrator。真正「干活」的是位于 agents/*.md 的 33 个专业 Agent。它们是 GSD 架构中的执行层核心，是连接编排指令与代码产出的桥梁。

如果说工作流是「导演」，那么 Agent 就是「演员」。本篇将从架构视角揭开这 33 个 Agent 的设计奥秘。

---

一、Agent 系统的定位：执行具体任务的「专家工人」

GSD 对 Agent 有一个明确的角色定义：Expert Worker（专家工人）。

1.1 工作流 vs Agent：只编排 vs 只执行

在第 13 篇《工作流架构总览》中，我们强调工作流是 Thin Orchestrator——只做编排，不做重活。这个「重活」全部下推到 Agent 层：

职责	工作流（Orchestrator）	Agent（Expert Worker）
流程控制	✅ 决定执行顺序和分支	❌
状态管理	✅ 更新 STATE.md / ROADMAP.md	❌
上下文组装	✅ 加载参考文档和模板	❌
代码生成	❌	✅ gsd-executor、gsd-code-fixer
架构设计	❌	✅ gsd-planner、gsd-roadmapper
技术研究	❌	✅ gsd-project-researcher、gsd-ai-researcher
质量验证	❌	✅ gsd-verifier、gsd-plan-checker
安全审计	❌	✅ gsd-security-auditor
调试诊断	❌	✅ gsd-debugger
文档撰写	❌	✅ gsd-doc-writer

flowchart TB
    subgraph Orchestrator["工作流层（Thin Orchestrator）"]
        O1[加载上下文]
        O2[决策路由]
        O3[Spawn Agent]
        O4[收集结果]
        O5[更新 STATE.md]
    end

    subgraph AgentLayer["Agent 层（Expert Workers）"]
        A1[gsd-planner]
        A2[gsd-executor]
        A3[gsd-verifier]
        A4[gsd-debugger]
        A5[gsd-security-auditor]
        A6[gsd-code-reviewer]
    end

    O3 --> A1
    O3 --> A2
    O3 --> A3
    O3 --> A4
    O3 --> A5
    O3 --> A6

    A1 --> O4
    A2 --> O4
    A3 --> O4
    A4 --> O4
    A5 --> O4
    A6 --> O4

1.2 为什么是「专家」而非「通才」

GSD 没有使用一个「超级 Agent」来处理所有任务，而是将能力拆分为 33 个专业化角色。这个设计的核心动机是 Context Budget（上下文预算）：

一个通用 Agent 的 Prompt 需要覆盖所有场景（编码、测试、审计、文档……），其体积会迅速膨胀到 100K+ tokens，挤占留给代码库的上下文空间。而专业 Agent 的 Prompt 只聚焦于单一领域，可以在更短的指令中表达更精确的约束。

设计原则：The right expert for the right job, with the right context.

---

二、Agent 定义格式：Markdown + YAML Frontmatter

每个 Agent 都是一个标准的 Markdown 文件，位于 agents/ 目录下。GSD 仓库中 shipped 的 Agent 定义共 33 个，文件大小从 5KB 到 46KB 不等。

2.1 标准结构

---
name: gsd-executor
description: Executes GSD plans with atomic commits and deviation handling.
tools: Read, Write, Edit, Bash, Grep, Glob
---

# Role

你是一个 GSD 计划执行者。你的职责是……

## Core Principles

1. 原子提交：每个 Plan 对应一个独立的 commit
2. 偏差处理：当实际实现与计划不符时……
3. ……

## Workflow

### Step 1: Load Context

使用 `gsd-sdk query init.executor` 加载执行上下文……

### Step 2: Execute Plan

……

## Output Format

……

## Error Handling

……

2.2 Frontmatter 字段规范

Agent 文件的 YAML frontmatter 定义了运行时的核心元数据：

字段	类型	必填	说明
name	string	是	Agent 唯一标识符，用于工作流中的 subagent_type 引用
description	string	是	Agent 职责描述，运行时在 Agent 选择界面展示
tools	list	是	该 Agent 被允许调用的工具白名单
model	string	否	指定模型配置（覆盖默认配置）
max_tokens	number	否	该 Agent 的最大输出 token 限制
temperature	number	否	采样温度（创意型 Agent 可适当提高）
version	string	否	Agent 定义版本号，用于兼容性检查

示例 frontmatter：

---
name: gsd-security-auditor
description: Performs security audits on code changes, focusing on OWASP Top 10 and runtime vulnerabilities.
tools: Read, Grep, Bash
model: claude-sonnet-4-20250514
max_tokens: 8192
temperature: 0.2
---

2.3 Prompt 主体结构

Frontmatter 之后是 Agent 的 Prompt 主体，通常包含以下标准区块：

区块	作用	示例 Agent
Role	定义 Agent 的身份和核心职责	所有 Agent
Core Principles	指导性的设计原则	gsd-executor、gsd-planner
Workflow	执行步骤的详细说明	gsd-executor、gsd-debugger
Input Format	期望接收的上下文结构	gsd-verifier、gsd-plan-checker
Output Format	输出内容的结构和模板	所有 Agent
Error Handling	异常场景的处理策略	gsd-executor、gsd-debugger
References	需要 @-reference 的参考文档	gsd-code-reviewer

---

三、Agent 分类体系：九大职能家族

33 个 Agent 按职能可分为九大类，每类内部有明确的分工和协作关系。

3.1 分类总览

flowchart TB
    subgraph Planning["规划类"]
        P1[gsd-planner]
        P2[gsd-plan-checker]
        P3[gsd-roadmapper]
    end

    subgraph Execution["执行类"]
        E1[gsd-executor]
        E2[gsd-code-fixer]
    end

    subgraph Verification["验证类"]
        V1[gsd-verifier]
        V2[gsd-code-reviewer]
        V3[gsd-integration-checker]
        V4[gsd-ui-checker]
        V5[gsd-nyquist-auditor]
    end

    subgraph Research["研究类"]
        R1[gsd-project-researcher]
        R2[gsd-phase-researcher]
        R3[gsd-ai-researcher]
        R4[gsd-ui-researcher]
        R5[gsd-advisor-researcher]
        R6[gsd-research-synthesizer]
    end

    subgraph Documentation["文档类"]
        D1[gsd-doc-writer]
        D2[gsd-doc-verifier]
    end

    subgraph Debugging["调试类"]
        De1[gsd-debugger]
    end

    subgraph Security["安全类"]
        S1[gsd-security-auditor]
    end

    subgraph UI["UI 类"]
        U1[gsd-ui-auditor]
        U2[gsd-ui-researcher]
    end

    subgraph Others["其他"]
        O1[gsd-pattern-mapper]
        O2[gsd-codebase-mapper]
        O3[gsd-intel-updater]
        O4[gsd-assumptions-analyzer]
    end

3.2 各类 Agent 详解

规划类（Planning）

Agent	核心职责	触发场景
gsd-planner	将需求转化为可执行的 PLAN.md	plan-phase、quick 模式
gsd-plan-checker	审查 PLAN.md 的质量和可执行性	plan-phase 验证循环
gsd-roadmapper	从需求推导多阶段 ROADMAP.md	new-project 初始化

Planner 是 GSD 最大的 Agent 定义文件之一（46KB），它采用 Chunked Planning 策略将大规模计划拆分为多个 Chunk 分别生成。Plan-Checker 则构成验证循环的关键一环，最多支持 3 轮迭代修订。

执行类（Execution）

Agent	核心职责	触发场景
gsd-executor	执行 PLAN.md 中的具体任务	execute-phase、Wave 执行
gsd-code-fixer	精准修复代码审查中发现的问题	code-review-fix

Executor 是 GSD 最繁忙的 Agent，它遵循 原子提交协议——每个 Plan 对应一个独立的 git commit，并支持偏差检测和处理机制。Code-Fixer 则专注于最小化变更，只修改被标记为问题的代码行。

验证类（Verification）

Agent	核心职责	触发场景
gsd-verifier	验证阶段完成度，检查目标回溯	verify-phase
gsd-code-reviewer	逐文件代码审查	code-review
gsd-integration-checker	检查模块间集成兼容性	阶段完成审计
gsd-ui-checker	验证 UI 实现与设计稿一致性	UI 相关阶段
gsd-nyquist-auditor	检查采样率和信号处理逻辑	多媒体/信号处理项目

验证类 Agent 的核心价值在于 客观性——它们不直接参与代码生成，因此能够以「旁观者」的视角发现问题。Code-Reviewer 引用 verification-patterns.md 中的 40+ 条检查项进行标准化审查。

研究类（Research）

Agent	核心职责	并行策略
gsd-project-researcher	项目级别的技术调研	4 维并行
gsd-phase-researcher	特定阶段的技术研究	按需
gsd-ai-researcher	AI/ML 领域专项研究	按需
gsd-ui-researcher	UI/UX 设计趋势和组件库调研	按需
gsd-advisor-researcher	架构建议和最佳实践调研	按需
gsd-research-synthesizer	聚合多份研究报告为统一视图	串行

Research 类 Agent 是 GSD 并行度最高的 Agent 家族。以 new-project 为例，4 个 gsd-project-researcher 同时从技术栈、依赖生态、相似项目、风险因素四个维度并行调研，最后由 Synthesizer 统一汇总。

文档类（Documentation）

Agent	核心职责	协作模式
gsd-doc-writer	撰写技术文档、API 文档、README	先写
gsd-doc-verifier	审查文档的准确性和完整性	后审

文档类 Agent 采用 先写后审 的串行模式，确保文档质量。

调试类（Debugging）

Agent	核心职责	触发场景
gsd-debugger	诊断执行失败、分析错误日志	执行失败重试后

Debugger 是 GSD 的「救火队员」。当 gsd-executor 执行失败且达到最大重试次数后，工作流会 spawn Debugger 进行深度诊断，输出修复方案后重新加入执行队列。

安全类（Security）

Agent	核心职责	触发场景
gsd-security-auditor	安全审计，聚焦 OWASP Top 10	里程碑审计、敏感变更

Security-Auditor 使用只读工具集（Read、Grep、Bash），确保审计过程不会意外修改代码。

UI 类（UI）

Agent	核心职责	触发场景
gsd-ui-auditor	审查 UI 实现质量	UI 相关阶段完成时
gsd-ui-researcher	调研 UI 组件库和设计系统	前端阶段规划前

其他（Others）

Agent	核心职责	触发场景
gsd-pattern-mapper	识别代码库中的设计模式	代码库映射
gsd-codebase-mapper	生成代码库结构图谱	map-codebase
gsd-intel-updater	更新代码库智能存储	阶段完成后
gsd-assumptions-analyzer	分析需求中的隐含假设	规划阶段

3.3 Agent 协作关系图

sequenceDiagram
    participant W as Workflow (Orchestrator)
    participant R as Research Agents
    participant P as gsd-planner
    participant C as gsd-plan-checker
    participant E as gsd-executor
    participant D as gsd-debugger
    participant V as gsd-verifier
    participant A as gsd-security-auditor

    W->>R: Spawn 并行研究
    R->>W: 返回研究报告
    W->>P: Spawn 规划（附研究结论）
    P->>W: 返回 PLAN.md
    W->>C: Spawn 审查
    C->>W: 返回审查意见
    alt 审查不通过
        W->>P: 要求修订（最多 3 轮）
        P->>W: 返回修订版 PLAN.md
    end
    W->>E: Spawn 执行
    E->>W: 返回执行结果 / 失败
    alt 执行失败
        W->>D: Spawn 调试
        D->>W: 返回修复方案
        W->>E: 重新执行
    end
    W->>V: Spawn 验证
    V->>W: 返回验证报告
    W->>A: Spawn 安全审计（按需）
    A->>W: 返回审计报告

---

四、工具权限控制：最小权限原则

Agent 的 tools frontmatter 字段是它的能力边界。GSD 严格遵循最小权限原则（Principle of Least Privilege）：每个 Agent 只能获得完成其职责所必需的工具。

4.1 工具白名单机制

---
name: gsd-executor
description: Executes GSD plans with atomic commits and deviation handling.
tools: Read, Write, Edit, Bash, Grep, Glob
---

对比只读 Agent：

---
name: gsd-plan-checker
description: Reviews PLAN.md for completeness and executability.
tools: Read, Grep
---

Plan-Checker 只有 Read 和 Grep 权限，它无法修改任何文件。这种设计确保了验证者的客观性——即使它的推理出现偏差，也无法对项目造成实质性损害。

4.2 工具权限矩阵

Agent	Read	Write	Edit	Bash	Grep	Glob	权限级别
gsd-executor	✅	✅	✅	✅	✅	✅	Full
gsd-planner	✅	✅	✅	❌	✅	✅	Write
gsd-code-fixer	✅	✅	✅	✅	✅	❌	Full
gsd-debugger	✅	❌	❌	✅	✅	✅	Read + Bash
gsd-verifier	✅	❌	❌	✅	✅	✅	Read + Bash
gsd-plan-checker	✅	❌	❌	❌	✅	❌	Read-Only
gsd-security-auditor	✅	❌	❌	❌	✅	✅	Read-Only
gsd-code-reviewer	✅	❌	❌	❌	✅	✅	Read-Only

4.3 运行时强制执行

工具权限不是「建议」，而是硬约束。GSD 的运行时（如 Claude Code 的 Task() API）在 spawn Agent 时会解析 frontmatter 中的 tools 字段，并据此配置 Agent 的工具可用性。任何超出白名单的工具调用都会被运行时拒绝。

这种设计与传统软件的 RBAC（基于角色的访问控制）异曲同工——Agent 的「角色」由它的定义文件决定，而「权限」由工具白名单精确控制。

---

五、模型配置：为不同任务匹配不同智力

GSD 的 33 个 Agent 并非都使用相同的 AI 模型。不同任务对模型的能力要求差异巨大：规划需要深度推理，执行需要精确遵循指令，审查需要批判性思维。

5.1 模型分层策略

层级	适用 Agent	能力要求	典型模型
Tier 1	gsd-planner、gsd-executor	最强推理 + 长上下文	Claude Sonnet 4.6、Opus 4.6
Tier 2	gsd-verifier、gsd-code-reviewer	强推理 + 批判性思维	Claude Sonnet 4.6、Gemini 2.5 Pro
Tier 3	gsd-research-synthesizer、gsd-doc-writer	良好的文本生成	Claude Haiku 3.5、GPT-4o-mini
Tier 4	gsd-intel-updater、gsd-assumptions-analyzer	快速处理、低成本	Claude Haiku 3.5

5.2 模型配置来源

Agent 的模型配置来自三个层级的合并：

1. Agent 自身 frontmatter：model 字段显式指定
2. model-profiles.md 参考文档：定义各模型的能力边界和推荐场景
3. 运行时默认值：当以上两者都未指定时，使用当前会话的默认模型

flowchart TD
    A[工作流 spawn Agent] --> B{Agent frontmatter
有 model 字段?}
    B -->|是| C[使用 Agent 指定模型]
    B -->|否| D{model-profiles.md
有推荐映射?}
    D -->|是| E[使用参考文档推荐]
    D -->|否| F[使用运行时默认模型]
    C --> G[执行 Agent 任务]
    E --> G
    F --> G

5.3 上下文窗口自适应

GSD 不仅适配不同模型，还适配同一模型的不同上下文窗口大小。context-budget.md 参考文档定义了标准的预算分配策略：

上下文窗口	Agent Prompt	代码库	参考文档	保留缓冲
200K	~20K	~120K	~40K	~20K
1M	~20K	~600K	~200K	~180K

对于 1M token 级模型（如 Claude Opus 4.6），GSD 会启用自适应上下文增强：在 Agent Prompt 中注入更多跨计划 awareness 信息，使 Agent 能够在执行当前任务时，参考其他相关计划的上下文。

---

六、Fresh Context Per Agent 的实现

Fresh Context Per Agent 是 GSD 五大核心设计原则之首（见第 03 篇）。它的工程含义是：每当工作流 spawn 一个子 Agent 时，这个 Agent 获得的是一个全新、干净、经过精心筛选的上下文窗口，而非从父对话继承的累积上下文。

6.1 为什么必须 Fresh？

在传统单体 Agent 模式中，用户与 AI 的会话上下文持续累积。经过数十轮交互后，上下文窗口被历史消息填满，导致：

• Context Rot（上下文腐烂）：早期关键信息被挤出窗口
• 注意力稀释：模型难以在冗长上下文中聚焦当前任务
• 错误累积：早期的错误推理可能持续影响后续输出

GSD 通过 spawn 新 Agent 彻底重置上下文，每次执行都在「干净 slate」上进行。

6.2 上下文注入协议

工作流在 spawn Agent 时，不是简单地把 Agent 定义文件丢给 AI，而是组装一个精心设计的上下文 Payload：

flowchart LR
    A[Agent 定义文件
agents/gsd-executor.md] --> E[上下文 Payload]
    B[当前任务上下文
Plan N + STATE.md] --> E
    C[参考文档
@context-budget.md] --> E
    D[运行时配置
model-profiles.md] --> E
    E --> F[全新上下文窗口]

Payload 组装流程：

1. Agent 定义：加载 agents/<name>.md 的完整内容（frontmatter + Prompt 主体）
2. 任务上下文：通过 gsd-sdk query init.<agent> 获取当前任务的精简上下文
3. 参考文档：按需 @-reference 相关参考文档（如 verification-patterns.md）
4. 运行时配置：注入模型配置、工具定义等运行时参数

6.3 开销与优化

Fresh Context 并非没有代价。每次 spawn 新 Agent 有约 14K token 的固定开销（系统提示 + 工具定义 + 初始化握手）。GSD 通过以下策略优化：

优化策略	实现	收益
内联阈值	inline_plan_threshold：2 个 task 以下不 spawn，直接内联执行	减少小任务的开销
上下文裁剪	超过预算时自动截断参考文档和示例	保证核心信息优先
Wave 内复用	同一 Wave 的多个 executor 共享相同的参考文档加载	减少重复 I/O
模型降级	简单任务使用 Haiku 级模型	降低成本

6.4 与 File-Based State 的协同

Fresh Context 能够成立的关键前提是 File-Based State（第 03 篇）。因为所有状态都以文件形式持久化在 .planning/ 中，新 spawn 的 Agent 可以通过读取这些文件快速重建项目上下文，而无需依赖父会话的记忆。

flowchart TB
    A[工作流 spawn 新 Agent] --> B[新 Agent 读取 STATE.md]
    B --> C[新 Agent 读取 PLAN.md]
    C --> D[新 Agent 读取相关参考文档]
    D --> E[重建完整项目上下文]
    E --> F[在全新窗口中执行任务]

核心洞察：Fresh Context 解决的是「上下文质量」问题，File-Based State 解决的是「状态连续性」问题。二者缺一不可。

---

七、Agent 定义的工程约束

为了保证 Agent 系统的可维护性，GSD 对 Agent 定义文件施加了若干工程约束。

7.1 大小约束

约束项	限制	说明
最大文件大小	50KB	某些运行时的 Subagent 内容限制
Frontmatter 行数	<20 行	保持元数据精简
Prompt 主体层级	≤3 级标题	避免过深的嵌套结构

gsd-planner.md（46KB）是 GSD 最大的 Agent 定义文件，已接近 50KB 上限。当 Agent 定义增长超出限制时，GSD 采用与 Workflow 类似的渐进式披露策略：将通用知识下沉到 references/agent-skills/*.md，Agent 定义中只保留角色特定的指令。

7.2 命名规范

所有 Agent 统一使用 gsd- 前缀，后续单词使用 kebab-case：

✅ gsd-project-researcher
✅ gsd-plan-checker
✅ gsd-code-reviewer
❌ gsd_project_researcher
❌ GsdPlanner
❌ planner

7.3 版本管理

Agent 定义文件与项目代码一同版本控制。当 Agent 的 Prompt 发生变更时：

1. Git diff 清晰展示 Prompt 的修改内容
2. 代码审查流程同样适用于 Agent 定义的变更
3. 回滚操作可以精确恢复到之前的 Agent 行为

这种「Prompt 即代码」的理念，是 GSD 能够持续迭代的关键。

---

八、小结

GSD 的 Agent 层是「专家工人」模型的工程化实现。通过 33 个专业 Agent 的精细分工，GSD 在有限的上下文窗口内实现了对复杂软件开发流程的全面覆盖。

设计要点	关键决策	收益
专家分工	33 个专业 Agent 而非 1 个通用 Agent	每个 Agent 的 Prompt 更精准，上下文利用率更高
Markdown 定义	Agent 是可读的结构化 Markdown	人类可审计，Git 可追溯
Frontmatter 规范	name + description + tools 标准化	运行时自动解析，权限强制执行
最小权限	工具白名单按 Agent 职能精确分配	审计类 Agent 无法修改代码，保证客观性
模型分层	不同 Agent 匹配不同模型能力	成本优化，任务与智力匹配
Fresh Context	每次 spawn 全新上下文窗口	消除 Context Rot，保证执行质量
File-Based State	状态持久化在文件系统	支持 Fresh Context 的前提，跨会话恢复

从架构视角看，Agent 层与工作流层形成了完美的互补：工作流负责「做正确的事」（决策路由、状态管理），Agent 负责「正确地做事」（代码生成、质量验证、安全审计）。二者通过清晰的编排-执行边界和文件系统状态协议解耦，共同支撑起 GSD 的核心能力。

---

下一篇预告：第 23 篇《Planner 与 Plan-Checker》将深入拆解 GSD 最核心的规划 Agent——gsd-planner.md（46KB）和 gsd-plan-checker.md。我们将逐行分析 Planner 的 Chunked Planning 策略、计划生成模板、偏差处理协议，以及 Plan-Checker 的审查清单和验证循环机制。这是理解 GSD 如何「把模糊想法变成可执行计划」的必修课，敬请期待！