这是「GSD 全景代码解析」专题的第 26 篇。在前 25 篇文章中，我们从命令系统到工作流编排，从 Planner 与 Executor 到 Verifier 与 Code-Reviewer，逐步揭开了 GSD 33 个专业 Agent 的设计面纱。但 Agent 系统的版图尚未完整——如果说 Planner 负责"想清楚"、Executor 负责"做出来"、Verifier 负责"验对没"，那么还有一类 Agent 负责"说明白"和"搞清楚"。
本文将聚焦 GSD 中知识生产层的核心角色——文档 Agent（gsd-doc-writer、gsd-doc-verifier）和研究 Agent（gsd-phase-researcher、gsd-ai-researcher、gsd-project-researcher、gsd-domain-researcher）。它们是连接"代码实现"与"知识沉淀"的桥梁，是 GSD 可持续演进的关键基础设施。

文档与研究 Agent

在 GSD 的多 Agent 编排体系中，有一类 Agent 不直接产出代码，却深刻影响着代码的质量和项目的可持续性——它们就是文档 Agent和研究 Agent。文档 Agent 确保"代码即文档"的承诺不沦为空谈；研究 Agent 确保每一个技术决策都有充分的依据，而非拍脑袋的猜测。

本文将深入解析这六个 Agent 的设计文件：gsd-doc-writer.md（38KB）、gsd-doc-verifier.md、gsd-phase-researcher.md（33KB）、gsd-ai-researcher.md、gsd-project-researcher.md 和 gsd-domain-researcher.md，揭示它们的工作方式、输出规范和协作协议。

一、gsd-doc-writer：代码的翻译官与知识的书写者

1.1 Agent 定位与核心职责

gsd-doc-writer 是 GSD 中专门负责技术文档撰写的 Agent，文件大小 38KB，是文档类 Agent 中最大的定义文件。它的核心职责可以概括为一句话：把代码和决策翻译成人类可读的知识。

具体而言，Doc-Writer 负责产出以下文档类型：

文档类型	典型场景	输出位置
API 文档	新增/修改接口后同步文档	`docs/api/` 或 `README.md`
README	项目初始化、功能迭代后更新	项目根目录
技术规范	架构决策、接口契约定义	`docs/specs/` 或 `CLAUDE.md`
CHANGELOG	版本发布前整理变更记录	`CHANGELOG.md`
部署文档	新增部署流程或环境配置	`docs/deployment/`
开发指南	新增开发规范或工具链	`CONTRIBUTING.md`

flowchart TD
    subgraph Input["输入上下文"]
        I1[git diff — 代码变更]
        I2[PLAN.md — 计划定义]
        I3[CLAUDE.md — 架构规范]
        I4[现有文档 — 需更新的文件]
    end

    subgraph DocWriter["gsd-doc-writer 执行"]
        D1[分析变更范围]
        D2[识别文档缺口]
        D3[生成/更新文档]
        D4[保持风格一致性]
    end

    subgraph Output["输出产物"]
        O1[更新的文档文件]
        O2[文档变更摘要]
    end

    I1 --> D1
    I2 --> D2
    I3 --> D3
    I4 --> D3
    D1 --> D2
    D2 --> D3
    D3 --> D4
    D4 --> O1
    D4 --> O2

1.2 文档生成策略：从代码到文档的双向同步

gsd-doc-writer.md（38KB）的核心设计挑战是如何确保文档与代码同步。在传统开发中，"文档过时"是普遍痛点——代码改了，文档没改。GSD 通过以下策略解决这个问题：

策略一：变更驱动（Change-Driven）

Doc-Writer 不"重写"文档，而是基于变更增量更新。它的输入核心是 git diff，而非完整的代码库。其工作流分为三步：加载变更上下文（git diff + PLAN.md 任务描述 + 待更新文档列表）、识别文档缺口（对比 diff 与现有文档，检查 API 覆盖、接口签名、环境变量、架构变更）、生成文档补丁（只修改与变更相关的部分）。

策略二：模板驱动（Template-Driven）

GSD 为常见文档类型预定义了模板，Doc-Writer 根据文档类型选择对应模板：

文档类型	模板文件	模板约束
API 文档	`templates/api-doc.md`	必须包含端点、参数、返回值、错误码
README	`templates/readme.md`	必须包含安装、使用、贡献、许可
技术规范	`templates/spec.md`	必须包含背景、方案、决策、影响
CHANGELOG	`templates/changelog.md`	遵循 Keep a Changelog 格式

策略三：风格一致性（Style Consistency）

Doc-Writer 在生成文档时，会 @-reference documentation-style-guide.md，确保术语统一、格式一致、人称一致、链接可维护。

1.3 多种文档类型的差异化处理

38KB 的 Agent 定义文件之所以庞大，很大程度上是因为需要覆盖多种文档类型的差异化逻辑。

API 文档生成：当检测到新增或修改 API 时，Doc-Writer 会解析代码中的接口定义，提取参数类型、返回值类型、错误码，生成对应的 OpenAPI / Swagger 片段，更新 docs/api/ 下的对应文件。

README 维护：README 的更新策略不同于 API 文档——它关注的是用户视角而非实现视角。新增功能时更新 Features，修改安装方式时更新 Installation，新增 CLI 命令时更新 Usage。

技术规范撰写：技术规范是 Doc-Writer 最具创造性的任务。当 Planner 做出架构决策后，Doc-Writer 需要将其转化为结构化的规范文档，包含背景、方案、备选方案、决策依据、影响范围和相关链接。

1.4 与代码同步机制：文档即契约

Doc-Writer 的核心价值不在于"会写文档"，而在于文档与代码的同步机制。GSD 通过以下设计确保二者的一致性：

sequenceDiagram
    participant E as gsd-executor
    participant DW as gsd-doc-writer
    participant DV as gsd-doc-verifier
    participant FS as 文件系统

    E->>FS: 编写代码 + SUMMARY.md
    E->>DW: 触发文档同步（execute-phase 内置）
    DW->>FS: 读取 git diff + 现有文档
    DW->>DW: 分析变更 → 识别缺口 → 生成补丁
    DW->>FS: 写入更新后的文档
    DW->>DV: 触发文档验证
    DV->>FS: 读取更新后的文档
    DV->>DV: 检查准确性 + 完整性 + 风格
    DV->>FS: 写入 DOC-VERIFICATION.md
    DV->>DW: 返回验证结果

关键设计：文档是执行阶段的必选项，而非可选项

在 GSD 的 execute-phase 中，每个 Wave 完成后会自动触发 Doc-Writer，将代码变更同步到文档。这与传统开发中"有空再写文档"的做法截然不同——文档是交付物的必要组成部分。

1.5 输出规范：DOC-UPDATE.md

Doc-Writer 的输出不仅包括更新后的文档文件，还包括一份 DOC-UPDATE.md 变更摘要，供工作流追踪：

# 文档变更摘要

## 变更范围
- 触发 Wave: Wave 3.2
- 关联 Plan: AUTH-02（用户认证模块）
- 代码变更: 5 个文件，+312/-89 行

## 文档更新

### 新增
- `docs/api/authentication.md` — 认证 API 完整文档

### 修改
- `README.md` — 更新 Features（新增 JWT 认证）
- `docs/deployment.md` — 新增环境变量 `JWT_SECRET`

### 删除
- 无

## 风格检查
- [x] 术语一致性
- [x] 格式规范
- [x] 链接有效性
- [x] 代码示例可运行

## 签名
- Doc-Writer Agent: gsd-doc-writer
- 文档风格版本: documentation-style-guide.md @ v1.2

二、gsd-phase-researcher：阶段级技术探勘

2.1 Agent 定位与核心职责

gsd-phase-researcher 是 GSD 中负责特定阶段技术研究的 Agent，文件大小 33KB。与 gsd-project-researcher（项目级宏观调研）不同，Phase-Researcher 聚焦于单个 Phase 或 Wave 执行前的技术可行性验证。

它的核心职责是回答："要实现这个功能，具体应该怎么做？"

研究维度	说明	典型输出
技术选型	库/框架的选择与对比	选型矩阵 + 推荐方案
实现路径	具体实现步骤和最佳实践	Step-by-step 指南
兼容性分析	与现有代码的兼容性评估	风险评估报告
性能基线	预期性能表现和优化建议	性能预估
参考实现	开源社区中的相似实现	参考链接 + 关键代码片段

flowchart TD
    subgraph Input["输入上下文"]
        I1[phases/{phase}.md — 阶段目标]
        I2[现有代码库结构]
        I3[技术栈约束]
        I4[性能/安全要求]
    end

    subgraph Researcher["gsd-phase-researcher 执行"]
        R1[解析阶段目标]
        R2[识别技术难点]
        R3[调研解决方案]
        R4[评估与推荐]
    end

    subgraph Output["输出产物"]
        O1[RESEARCH-{phase}.md]
    end

    I1 --> R1
    I2 --> R2
    I3 --> R3
    I4 --> R4
    R1 --> R2
    R2 --> R3
    R3 --> R4
    R4 --> O1

2.2 阶段研究策略：从模糊到具体

gsd-phase-researcher.md（33KB）定义了从"阶段目标"到"可执行方案"的完整研究流程：

阶段一：目标解构

Phase-Researcher 首先将阶段目标拆解为可研究的技术子问题。例如目标"实现 OAuth 2.0 登录"会被拆解为：选择哪个 OAuth 库、Token 存储策略、回调路由设计、用户数据如何与现有模型关联等子问题。

阶段二：并行调研

对于每个子问题，Phase-Researcher 会并行调研多个维度：

调研维度	方法	时间预算
官方文档	阅读核心 API 文档	~20%
社区实践	GitHub 高星项目参考	~30%
兼容性验证	与现有代码的集成推演	~25%
边界情况	错误处理、安全边界	~25%

阶段三：方案评估

调研完成后，Phase-Researcher 使用加权评分矩阵评估候选方案：

## 方案评估: OAuth 库选择

| 维度 | 权重 | Passport | Auth0 SDK | 自建 |
|------|:----:|:--------:|:---------:|:----:|
| 与现有 Express 集成难度 | 20% | 9 | 7 | 4 |
| 社区活跃度 | 15% | 9 | 8 | 3 |
| 文档完整性 | 15% | 8 | 9 | 5 |
| 安全更新频率 | 20% | 7 | 9 | 4 |
| 包体积 | 10% | 7 | 6 | 9 |
| 定制化能力 | 20% | 8 | 5 | 10 |
| **加权总分** | 100% | **8.1** | **7.4** | **5.8** |

**推荐**: Passport（加权总分最高，与现有技术栈集成度最佳）

2.3 研究成果的组织方式

Phase-Researcher 的输出是一份结构化的研究报告 RESEARCH-{phase}.md，它的设计目标是可直接被 Planner 引用、被 Executor 执行。

一份完整的研究报告包含：研究范围（阶段目标、技术栈约束、时间预算）、技术选型（推荐方案 + 备选方案 + 评估依据）、实现路径（Step-by-step 指南 + 代码结构 + 数据库迁移）、兼容性评估（与现有代码的兼容性检查表）、风险与缓解（可能性/影响/缓解措施矩阵）、性能预估（延迟、内存、吞吐量估算）、参考链接（官方文档、论文、社区资源），以及研究签名（Researcher 标识、日期、置信度）。

2.4 与 plan-phase 的协作

Phase-Researcher 不是独立运行的——它深度嵌入在 plan-phase 的执行流程中：

sequenceDiagram
    participant User as 用户
    participant PP as plan-phase 工作流
    participant PR as gsd-phase-researcher
    participant PL as gsd-planner
    participant FS as 文件系统

    User->>PP: 触发 plan-phase
    PP->>PL: Spawn Planner 生成初始计划
    PL->>PP: 返回初步 Phase 列表
    PP->>PP: 识别需要研究的 Phase
    PP->>PR: Spawn Phase-Researcher
    PR->>FS: 读取 phases/{phase}.md
    PR->>PR: 执行研究流程
    PR->>FS: 写入 RESEARCH-{phase}.md
    PR->>PP: 返回研究结论
    PP->>PL: 传递研究结论，要求细化计划
    PL->>PL: 基于研究结果调整任务分解
    PL->>FS: 更新 PLAN.md
    PL->>PP: 返回最终计划

关键设计：研究是规划的前置条件，而非可选增强

GSD 的 plan-phase 有一个内置的研究触发条件：Phase 涉及未使用过的技术栈、第三方集成、性能要求显著高于现有基线、安全敏感功能，或依赖关系复杂（大于 3 个外部依赖）。如果任一信号为真，则触发 gsd-phase-researcher。

这种设计确保了：复杂决策永远有研究支撑，简单决策不浪费研究预算。

三、gsd-ai-researcher：AI 领域的前沿侦察兵

3.1 Agent 定位与核心职责

gsd-ai-researcher 是 GSD 中专注于AI/ML 领域的专项研究 Agent。与通用的 gsd-phase-researcher 不同，AI-Researcher 的职责边界聚焦于：

模型选型: LLM、Embedding 模型、多模态模型的选择
Prompt 工程: 最佳实践、Anti-patterns、评估方法
RAG 架构: 检索策略、向量数据库、重排序
Agent 设计: ReAct、Plan-and-Execute、Multi-Agent 编排
评估指标: 准确性、延迟、成本、幻觉率

flowchart LR
    subgraph General["通用研究"]
        PR[gsd-phase-researcher]
    end

    subgraph AI["AI 专项研究"]
        AI1[模型选型]
        AI2[Prompt 工程]
        AI3[RAG 架构]
        AI4[Agent 设计]
        AI5[评估方法]
    end

    PR -->|不涉及 AI| PR_OK[通用技术调研]
    PR -->|涉及 AI| AIR[gsd-ai-researcher]
    AIR --> AI1
    AIR --> AI2
    AIR --> AI3
    AIR --> AI4
    AIR --> AI5

3.2 与 gsd-phase-researcher 的分工

AI-Researcher 和 Phase-Researcher 的关系是专项与通用的互补，而非替代：

维度	gsd-phase-researcher	gsd-ai-researcher
研究范围	通用技术栈（框架、库、工具）	AI/ML 专项技术
触发条件	任何需要技术调研的 Phase	Phase 涉及 AI/ML 组件
输出格式	RESEARCH-{phase}.md	AI-RESEARCH-{phase}.md
知识来源	官方文档、GitHub、博客	论文、ArXiv、HuggingFace、模型卡
评估维度	成熟度、社区、集成难度	准确性、延迟、成本、幻觉率
置信度标注	基于社区验证	基于基准测试数据

协作模式：嵌套调用

当一个 Phase 同时涉及通用技术和 AI 技术时（如"使用 FastAPI 搭建 LLM 服务"），plan-phase 会先 spawn gsd-phase-researcher 调研 FastAPI 部分，再 spawn gsd-ai-researcher 调研 LLM 推理优化部分。两份研究报告会被合并为统一的 RESEARCH-{phase}.md。

3.3 AI 研究的特殊挑战

AI-Researcher 的设计需要应对 AI 领域的几个特殊挑战：

挑战一：知识时效性

AI 领域的技术迭代极快，半年前的"最佳实践"可能已经过时。AI-Researcher 的 Prompt 中包含明确的时效性检查指令：2025 年后的来源为高可信度，2024 年的来源需交叉验证，2023 年及更早仅作为历史背景。

挑战二：基准测试数据解读

AI-Researcher 的核心输出之一是模型选型建议，这需要基于基准测试数据。例如 Embedding 模型选型会对比 text-embedding-3-large、BGE-M3、E5-mistral-7b 在 MTEB 平均分、延迟、许可证等维度的表现，给出加权推荐。

挑战三：幻觉检测

AI-Researcher 自身也可能产生幻觉（编造不存在的论文、模型或数据）。为此，它的输出规范要求：每个事实性陈述必须标注来源；无法验证的陈述标注为 [Unverified]；涉及数字的陈述提供计算过程或数据来源。

四、gsd-project-researcher 与 gsd-domain-researcher：宏观视角

4.1 gsd-project-researcher：项目级全景调研

gsd-project-researcher 是 GSD 中负责项目级宏观调研的 Agent。与 Phase-Researcher 的"微观深入"不同，Project-Researcher 关注的是"宏观全景"。

它的典型触发场景是 new-project 初始化阶段。在 new-project 工作流中，4 个 Project-Researcher 会从四个维度并行调研：

维度	研究内容	输出
技术栈	核心框架、语言、运行时选型	Stack-Research.md
依赖生态	第三方库成熟度、维护状态、许可证风险	Dependencies-Research.md
相似项目	开源社区中的参考实现、最佳实践	Reference-Projects.md
风险因素	已知陷阱、常见反模式、安全漏洞	Pitfalls-Research.md

flowchart TB
    subgraph NP["new-project 工作流"]
        N1[Dream Extraction]
        N2[需求结构化]
    end

    subgraph Parallel["并行研究（4× Project-Researcher）"]
        R1[技术栈调研]
        R2[依赖生态调研]
        R3[相似项目调研]
        R4[风险因素调研]
    end

    subgraph Synth["研究合成"]
        S1[gsd-research-synthesizer]
        S2[统一研究报告]
    end

    N2 --> R1
    N2 --> R2
    N2 --> R3
    N2 --> R4
    R1 --> S1
    R2 --> S1
    R3 --> S1
    R4 --> S1
    S1 --> S2

Project-Researcher 的输出会被 gsd-research-synthesizer 聚合成统一视图，供 Planner 在生成 ROADMAP.md 时引用。

4.2 gsd-domain-researcher：领域知识沉淀

gsd-domain-researcher 是 GSD 中负责领域知识研究的 Agent。它的关注点不是技术选型，而是业务领域的知识建模：

业务术语表：统一领域术语，消除歧义
业务规则：核心业务流程和约束条件
领域模型：实体、关系、状态机
合规要求：行业法规、数据保护、安全标准

Domain-Researcher 的输出通常存储在 .planning/research/domain.md，作为项目级参考文档，供所有后续 Agent 引用。

五、研究 Agent 的输出规范

5.1 研究报告的统一结构

无论哪种 Research Agent，其输出都遵循统一的结构规范，确保工作流可以可靠解析：

# Research Report: {研究主题}

## 元数据
- 研究类型: {phase | project | ai | domain}
- 触发源: {plan-phase | new-project | spike}
- 研究员: {agent-name}
- 日期: {YYYY-MM-DD}
- 置信度: {高 | 中 | 低}

## 研究范围
{清晰定义研究边界}

## 核心发现
{3-5 条最重要的发现}

## 详细分析
{分节展开}

## 推荐方案
{明确的推荐 + 理由}

## 风险与缓解
{风险评估矩阵}

## 参考来源
{带链接的引用列表}

## 附录
{原始数据、计算过程等}

5.2 置信度标注体系

GSD 要求所有研究报告标注置信度，这是防止"过度确信"的关键机制：

置信度	含义	使用场景
高	基于官方文档 + 社区实践验证	主流技术选型、成熟框架
中	基于官方文档，但缺乏实践验证	新发布的版本、小众方案
低	基于社区讨论，缺乏权威来源	前沿技术、实验性功能
推测	基于逻辑推理，无直接证据	未来趋势、长期影响评估

5.3 研究 Agent 的协作全景

flowchart TB
    subgraph Planning["规划阶段"]
        PP[plan-phase]
        NP[new-project]
    end

    subgraph Research["研究层"]
        PR[gsd-project-researcher
x4 并行]
        DR[gsd-domain-researcher]
        PHR[gsd-phase-researcher]
        AIR[gsd-ai-researcher]
        RS[gsd-research-synthesizer]
    end

    subgraph Consumption["消费层"]
        PL[gsd-planner]
        EX[gsd-executor]
        DW[gsd-doc-writer]
    end

    NP --> PR
    NP --> DR
    PP --> PHR
    PP --> AIR
    PR --> RS
    DR --> RS
    PHR --> PL
    AIR --> PL
    RS --> PL
    PL --> EX
    PL --> DW

数据流说明：

new-project 触发 Project-Researcher（4 维并行）和 Domain-Researcher
plan-phase 触发 Phase-Researcher 和 AI-Researcher（按需）
所有研究报告由 Synthesizer 聚合（Project 级）或直接传递给 Planner（Phase 级）
Planner 基于研究结论生成/调整计划
Executor 执行时可以引用研究报告作为参考
Doc-Writer 将研究结论沉淀为项目文档

六、小结

本文深入解析了 GSD 知识生产层的六个核心 Agent：

Agent	核心职责	关键设计
gsd-doc-writer	技术文档撰写与同步	变更驱动、模板驱动、风格一致性、双向同步
gsd-doc-verifier	文档准确性验证	与 Code-Reviewer 类似的审查清单
gsd-phase-researcher	阶段级技术探勘	目标解构、并行调研、加权评分矩阵
gsd-ai-researcher	AI/ML 专项研究	时效性检查、基准测试解读、幻觉检测
gsd-project-researcher	项目级全景调研	4 维并行、new-project 触发
gsd-domain-researcher	领域知识建模	业务术语、规则、模型、合规

设计哲学：

研究是规划的前置条件：复杂决策必须有研究支撑，研究不通过不进入规划
文档是交付的必要组成：代码变更必须同步文档，文档验证不通过不完成 Wave
专项与通用互补：Phase-Researcher 处理通用技术，AI-Researcher 处理专项领域，Project-Researcher 处理宏观视角
置信度驱动决策：所有研究结论标注置信度，低置信度结论需额外验证

这些 Agent 共同构成了 GSD 的知识飞轮：研究支撑规划 → 规划驱动执行 → 执行产生变更 → 变更沉淀为文档 → 文档指导后续研究。这个飞轮使得 GSD 项目不会因人员更替而丢失上下文，不会因时间流逝而遗忘决策依据。

下一篇预告：第 27 篇《代码修复与安全 Agent》
在解析了文档与研究 Agent 之后，我们将继续探索 GSD Agent 系统的另外两个关键角色——gsd-code-fixer 和 gsd-security-auditor。Code-Fixer 如何精准修复 Code-Reviewer 发现的问题？Security-Auditor 如何在 OWASP Top 10 框架下执行安全审计？它们如何与 Executor 和 Verifier 形成完整的质量保障闭环？敬请期待！