这是「GSD 全景代码解析」专题的第 19 篇。在前面几篇文章中，我们深入解析了 execute-phase、plan-phase、new-project 等核心工作流的编排机制。如果说执行是 GSD 的"肌肉"，规划是它的"大脑"，那么验证与审计就是它的"免疫系统"——确保每一行交付的代码都经过严格检查，每一个里程碑都达到可发布的质量标准。

本文将聚焦 GSD 工作流编排层的质量保障机制，逐一拆解 verify-phase、audit-milestone、audit-uat 和 audit-fix 四个验证与审计工作流的设计哲学和实现细节。

---

验证与审计工作流

在 GSD 框架中，"写代码"只是交付流程的一半，另一半是验证代码是否正确、审计过程是否合规。GSD 通过四个专门的工作流来完成这一使命：

工作流	职责	触发时机
verify-phase	阶段级验证	每个 phase 执行完成后
audit-milestone	里程碑审计	Milestone 标记为完成时
audit-uat	用户验收测试审计	UAT 阶段完成后
audit-fix	修复审计	修复任务完成后

这四个工作流共同构成了 GSD 的质量门控体系（Quality Gate System），与 gates.md 中定义的质量标准深度集成。

---

一、verify-phase 工作流：阶段级质量把关

1.1 工作流定位

verify-phase.md 是 GSD 中最基础的验证工作流，其核心职责是：在一个 phase 的所有 Wave 执行完成后，系统性地验证该阶段的目标是否达成。

与 execute-phase 中的"过程验证"不同，verify-phase 做的是"结果验证"——它不关心代码是怎么写出来的，只关心代码是否满足阶段目标。

1.2 验证流程与检查点

verify-phase 的完整流程包含 6 个主要步骤：

flowchart TD
    subgraph Prep["① 前置准备"]
        P1[加载 STATE.md
获取阶段目标] --> P2[加载 gates.md
获取质量标准]
    end

    subgraph Check["② 检查点执行"]
        C1[Goal Verification
目标达成检查] --> C2[Test Suite Check
测试套件检查]
        C2 --> C3[Schema Consistency
Schema 一致性检查]
        C3 --> C4[Documentation Check
文档完整性检查]
    end

    subgraph Gate["③ 质量门控"]
        G1{所有检查通过?}
    end

    subgraph Result["④ 结果处理"]
        G1 -->|是| R1[生成 VERIFY.md
标记阶段完成]
        G1 -->|否| R2[生成 ISSUE.md
进入修复流程]
        R2 --> R3[触发 audit-fix
修复审计]
    end

    Prep --> Check --> Gate --> Result

各检查点的具体职责：

检查点	验证内容	失败处理
Goal Verification	阶段目标中定义的每个 deliverable 是否完成	标记未完成项，生成修复任务
Test Suite Check	单元测试、集成测试通过率是否达标	列出失败测试，分析失败原因
Schema Consistency	数据库 schema、API 契约是否与计划一致	检测 drift，生成迁移任务
Documentation Check	代码注释、API 文档、CHANGELOG 是否同步	标记缺失文档，生成补充任务

1.3 与 gates.md 的集成

verify-phase 并非独立运行，而是深度依赖 gates.md 中定义的质量标准：

sequenceDiagram
    participant VP as verify-phase
    participant G as gates.md
    participant TS as Test Suite
    participant DB as Schema Registry
    participant Out as VERIFY.md

    VP->>G: 读取阶段质量标准
    G-->>VP: 返回阈值（测试覆盖率 ≥80%、API 兼容性等）

    VP->>TS: 执行测试套件
    TS-->>VP: 返回测试报告

    VP->>DB: 检查 schema 一致性
    DB-->>VP: 返回 drift 报告

    VP->>VP: 综合评估所有指标

    alt 全部达标
        VP->>Out: 生成 VERIFY.md（PASSED）
    else 部分未达标
        VP->>Out: 生成 VERIFY.md（FAILED + issues）
    end

gates.md 中定义的质量门控是可配置的，不同项目、不同阶段可以有不同的阈值：

# gates.md 示例片段
phase_verification:
  test_coverage_threshold: 80
  api_compatibility: strict
  documentation_required: true
  schema_drift_tolerance: none

milestone_audit:
  security_scan: required
  performance_benchmark: required
  code_review_coverage: 100

1.4 验证失败的处理

当 verify-phase 检测到质量问题时，不会直接修改代码，而是遵循**"记录问题 → 生成修复任务 → 审计修复"**的闭环流程：

1. 记录问题：在 VERIFY.md 中详细记录每个失败的检查点、失败原因、影响范围
2. 生成修复任务：根据问题类型，自动生成对应的修复任务（如 fix-test-coverage、fix-schema-drift）
3. 进入修复流程：将修复任务交给 audit-fix 工作流处理
4. 重新验证：修复完成后，重新触发 verify-phase

这种设计确保了问题不会被掩盖，修复不会被遗漏。

---

二、audit-milestone：里程碑审计

2.1 里程碑完成标准

在 GSD 中，Milestone 是比 Phase 更高层次的聚合单位。一个 Milestone 通常包含多个 Phase，代表一个可独立交付的功能模块或版本节点。

audit-milestone 的审计标准比 verify-phase 更严格：

flowchart LR
    subgraph PhaseLevel["Phase 级别"]
        P1[verify-phase]
        P2[测试通过]
        P3[文档完整]
    end

    subgraph MilestoneLevel["Milestone 级别"]
        M1[audit-milestone]
        M2[所有 Phase 通过]
        M3[跨 Phase 集成测试]
        M4[性能基准测试]
        M5[安全扫描通过]
        M6[代码审查 100%]
    end

    PhaseLevel --> MilestoneLevel

Milestone 的完成标准包括：

标准	说明	自动化程度
所有子 Phase 的 VERIFY.md 为 PASSED	前置条件	全自动
跨 Phase 集成测试通过	验证模块间协作	全自动
性能基准达标	响应时间、吞吐量等	半自动（需基线对比）
安全扫描无高危漏洞	SAST/DAST 扫描	全自动
代码审查覆盖率 100%	所有变更经过 review	全自动（记录检查）
用户文档已更新	面向用户的指南同步	半自动（AI 辅助检查）

2.2 审计流程

audit-milestone 的审计流程采用**"分层递进"**策略：

flowchart TD
    A[开始 Milestone 审计] --> B{所有子 Phase
已通过验证?}
    B -->|否| C[终止审计
返回 Phase 修复]
    B -->|是| D[执行集成测试套件]
    D --> E{集成测试通过?}
    E -->|否| F[生成集成问题报告]
    E -->|是| G[执行性能基准测试]
    G --> H{性能达标?}
    H -->|否| I[生成性能优化任务]
    H -->|是| J[执行安全扫描]
    J --> K{无高危漏洞?}
    K -->|否| L[生成安全修复任务]
    K -->|是| M[检查代码审查记录]
    M --> N{覆盖率 100%?}
    N -->|否| O[标记未审查变更]
    N -->|是| P[生成 AUDIT.md]
    P --> Q{全部通过?}
    Q -->|是| R[标记 Milestone 完成]
    Q -->|否| S[进入修复审计流程]

关键设计点：

• 前置检查：如果子 Phase 未全部通过，直接终止审计，避免浪费资源
• 渐进式执行：每个检查点失败后即生成报告，不继续后续检查（除非配置为"全量模式"）
• 审计独立性：audit-milestone 由独立的 gsd-auditor Agent 执行，避免"自己审自己"

2.3 审计报告

audit-milestone 的输出是一份结构化的 AUDIT.md 文件：

# Milestone Audit Report

## 基本信息
- Milestone: v1.0-user-authentication
- 审计日期: 2026-04-24
- 审计 Agent: gsd-auditor
- 结果: PASSED_WITH_NOTES

## 检查结果

| 检查项 | 状态 | 详情 |
|--------|------|------|
| Phase 验证 | ✅ PASSED | 3/3 Phases 通过 |
| 集成测试 | ✅ PASSED | 42/42 通过 |
| 性能基准 | ⚠️ NOTE | 响应时间 120ms（阈值 100ms），建议优化 |
| 安全扫描 | ✅ PASSED | 无高危/严重漏洞 |
| 代码审查 | ✅ PASSED | 100% 覆盖率 |

## 建议
- 登录接口响应时间接近阈值，建议在下一 Milestone 中优化

## 签名
- 审计 Agent: gsd-auditor
- 人类确认: [待确认]

---

三、audit-uat：用户验收测试审计

3.1 UAT 流程

UAT（User Acceptance Testing，用户验收测试）是 GSD 交付流程中最接近真实用户的验证环节。audit-uat 工作流负责审计 UAT 过程的完整性和结果的可信度。

flowchart LR
    subgraph UATFlow["UAT 流程"]
        U1[准备 UAT 环境] --> U2[执行验收用例]
        U2 --> U3[记录用户反馈]
        U3 --> U4[分类问题优先级]
    end

    subgraph Audit["审计节点"]
        A1[audit-uat]
    end

    UATFlow --> Audit

audit-uat 的审计重点不是"功能是否正确"（这是 verify-phase 的职责），而是：

1. UAT 环境是否与生产环境一致
2. 验收用例是否覆盖了需求文档中的全部场景
3. 用户反馈是否被正确分类和追踪
4. 阻塞性问题是否已解决或已接受风险

3.2 验收标准检查

audit-uat 对验收标准的检查采用**"需求追溯（Requirements Traceability）"**方法：

flowchart TD
    A[加载 REQUIREMENTS.md] --> B[提取所有 acceptance criteria]
    B --> C[加载 UAT 测试记录]
    C --> D[匹配 criteria 与测试用例]
    D --> E{每个 criteria
都有对应测试?}
    E -->|否| F[标记遗漏的验收标准]
    E -->|是| G[检查测试结果]
    G --> H{所有 criteria 通过?}
    H -->|否| I[分类失败：阻塞/严重/轻微]
    H -->|是| J[生成 UAT-AUDIT.md]

验收标准的三级分类：

级别	定义	处理策略
阻塞（Blocker）	核心功能不可用，影响发布	必须修复，重新 UAT
严重（Critical）	重要功能有缺陷，有 workaround	建议修复，可接受风险则记录
轻微（Minor）	体验问题，不影响功能	记录为已知问题，后续版本处理

audit-uat 的独特之处在于它会审计 UAT 过程本身——确保测试不是走过场，反馈不是被忽视。

---

四、audit-fix：修复审计

4.1 修复验证流程

当 verify-phase、audit-milestone 或 audit-uat 发现问题后，会进入修复流程。修复完成后，audit-fix 工作流负责验证修复本身是否正确、是否引入了新的问题。

flowchart TD
    A[接收修复任务] --> B[加载原始问题报告]
    B --> C[审查修复方案]
    C --> D{修复方案合理?}
    D -->|否| E[要求重新设计修复]
    D -->|是| F[执行回归测试]
    F --> G{回归测试通过?}
    G -->|否| H[标记回归失败]
    G -->|是| I[检查修复范围]
    I --> J{是否过度修复?}
    J -->|是| K[建议精简修复范围]
    J -->|否| L[生成 FIX-AUDIT.md]

audit-fix 的三重检查：

1. 方案审查：修复是否针对根因，而非症状
2. 回归测试：修复是否破坏了原有功能
3. 范围审查：修复是否引入了不必要的变更（过度修复）

4.2 回归测试

回归测试是 audit-fix 的核心环节。GSD 的回归测试策略分为两个层次：

flowchart LR
    subgraph L1["第一层：受影响范围"]
        A1[识别修改的文件] --> A2[运行相关单元测试]
    end

    subgraph L2["第二层：全量保护"]
        B1[运行完整测试套件] --> B2[性能基准对比]
    end

    L1 --> L2

• 第一层（快速反馈）：仅运行与修改文件相关的测试，快速验证修复本身
• 第二层（全面保护）：运行完整测试套件，确保没有引入回归问题

audit-fix 会根据修复的风险等级决定执行哪一层：

风险等级	判断依据	回归测试范围
低	单行注释修改、文档更新	第一层即可
中	局部逻辑修改、配置变更	第一层 + 相关集成测试
高	核心模块修改、接口变更	第一层 + 第二层全量

---

五、质量门控在工作流中的位置

5.1 门控的嵌入点

质量门控（Quality Gates）不是独立的工作流，而是嵌入在各个工作流中的检查点。在 GSD 的工作流体系中，门控分布在以下位置：

flowchart TD
    subgraph NewProject["new-project"]
        N1[项目初始化] --> N2[门控: 项目结构合规]
    end

    subgraph PlanPhase["plan-phase"]
        P1[计划生成] --> P2[门控: 计划可执行性]
    end

    subgraph ExecutePhase["execute-phase"]
        E1[Wave 执行] --> E2[门控: 原子提交检查]
        E2 --> E3[门控: 代码审查]
        E3 --> E4[门控: 回归测试]
    end

    subgraph VerifyPhase["verify-phase"]
        V1[阶段验证] --> V2[门控: 目标达成]
        V2 --> V3[门控: 测试覆盖率]
    end

    subgraph MilestoneAudit["audit-milestone"]
        M1[里程碑审计] --> M2[门控: 集成测试]
        M2 --> M3[门控: 安全扫描]
    end

    subgraph UATAudit["audit-uat"]
        U1[UAT 审计] --> U2[门控: 验收标准]
    end

    subgraph FixAudit["audit-fix"]
        F1[修复审计] --> F2[门控: 回归测试]
    end

    NewProject --> PlanPhase --> ExecutePhase --> VerifyPhase --> MilestoneAudit --> UATAudit
    ExecutePhase -.-> FixAudit
    VerifyPhase -.-> FixAudit
    MilestoneAudit -.-> FixAudit

5.2 门控的层次结构

GSD 的质量门控具有清晰的层次关系：

层次	门控名称	所属工作流	检查频率
L0	项目结构门控	new-project	一次性
L1	计划可执行性门控	plan-phase	每阶段一次
L2	代码审查门控	execute-phase	每 Wave 一次
L2	回归测试门控	execute-phase	每 Wave 一次
L3	阶段目标门控	verify-phase	每 Phase 一次
L3	测试覆盖率门控	verify-phase	每 Phase 一次
L4	集成测试门控	audit-milestone	每 Milestone 一次
L4	安全扫描门控	audit-milestone	每 Milestone 一次
L5	验收标准门控	audit-uat	每版本一次
L6	修复回归门控	audit-fix	每次修复后

这种分层门控设计的优势在于：

• 问题早发现：低级门控（如代码审查）在每次提交时运行，问题在引入时即被发现
• 资源合理分配：高级门控（如安全扫描）运行频率低但覆盖全面
• 反馈延迟递减：越靠近开发的门控，反馈越快；越靠近交付的门控，检查越全面

---

六、验证与审计的自动化策略

6.1 自动化程度分级

GSD 将验证与审计任务按可自动化程度分为四类：

flowchart LR
    subgraph Auto["全自动"]
        A1[单元测试执行]
        A2[代码覆盖率统计]
        A3[Schema 一致性检查]
        A4[安全扫描]
    end

    subgraph Semi["半自动"]
        S1[测试用例生成]
        S2[代码审查辅助]
        S3[文档完整性检查]
        S4[性能基线对比]
    end

    subgraph Human["人工决策"]
        H1[UAT 验收结论]
        H2[风险接受判断]
        H3[发布审批]
    end

    subgraph Hybrid["人机协作"]
        M1[审计报告生成]
        M2[问题优先级排序]
        M3[修复方案建议]
    end

    Auto --> Semi --> Hybrid --> Human

类别	示例	实施策略
全自动	测试执行、覆盖率统计、安全扫描	CI/CD 流水线集成，零人工干预
半自动	用例生成、审查辅助、文档检查	AI 生成 + 人工确认
人机协作	报告生成、优先级排序	AI 分析 + 人工决策
人工决策	验收结论、发布审批	AI 提供信息，人类做最终决定

6.2 自动化执行策略

在实际项目中，GSD 推荐以下自动化执行策略：

策略一：提交时触发（Pre-commit / CI）

# 每次代码提交时自动执行
- 代码格式检查（lint）
- 单元测试（受影响范围）
- 静态类型检查

策略二：Wave 完成时触发（execute-phase 内置）

# 每个 Wave 执行完成后自动执行
- 代码审查门控
- 回归测试门控
- Schema Drift 检查

策略三：Phase 完成时触发（verify-phase）

# 每个 Phase 结束后自动执行
- 目标达成验证
- 测试覆盖率检查
- 文档完整性检查

策略四：Milestone 完成时触发（audit-milestone）

# 每个 Milestone 结束后自动执行
- 集成测试
- 性能基准测试
- 安全扫描

策略五：修复完成后触发（audit-fix）

# 每次修复任务完成后自动执行
- 修复验证
- 回归测试
- 修复范围审查

6.3 检查点协议（Checkpoint Protocol）

对于无法全自动化的检查点，GSD 使用**检查点协议（Checkpoint Protocol）**来管理人工介入：

sequenceDiagram
    participant WF as 工作流
    participant CP as 检查点
    participant Human as 人类用户
    participant Resume as 恢复执行

    WF->>CP: 到达检查点
    CP->>Human: 展示当前状态 + 决策选项
    Human->>CP: 做出决策（通过/拒绝/修订）
    CP->>Resume: 记录决策 + 上下文
    Resume->>WF: 恢复工作流执行

检查点协议的核心设计原则：

1. 状态持久化：检查点的所有上下文信息写入文件，工作流可以随时中断和恢复
2. 决策可追溯：每个检查点的决策都被记录，便于后续审计
3. 默认安全：如果检查点超时未响应，默认行为是"暂停"而非"继续"

---

七、验证与审计工作流的协作关系

四个验证与审计工作流并非孤立运行，它们通过文件系统和工作流触发器形成一个有机的质量保障网络：

flowchart TD
    E[execute-phase
执行阶段] --> V[verify-phase
阶段验证]
    V -->|通过| M[audit-milestone
里程碑审计]
    V -->|失败| F1[audit-fix
修复审计]
    M -->|通过| U[audit-uat
UAT 审计]
    M -->|失败| F2[audit-fix
修复审计]
    U -->|通过| D[发布]
    U -->|失败| F3[audit-fix
修复审计]
    F1 --> V
    F2 --> M
    F3 --> U

    style E fill:#e1f5fe
    style V fill:#fff3e0
    style M fill:#fff3e0
    style U fill:#fff3e0
    style F1 fill:#ffebee
    style F2 fill:#ffebee
    style F3 fill:#ffebee
    style D fill:#e8f5e9

这个网络的运作逻辑非常清晰：

• 执行驱动验证：每次 execute-phase 完成后自动触发 verify-phase
• 失败驱动修复：任何验证失败都进入 audit-fix 流程
• 修复驱动重验：修复完成后自动重新触发上层验证
• 层级递进：只有下层验证全部通过，才能进入上层审计

---

总结

验证与审计工作流是 GSD 框架中不可或缺的质量保障基础设施。它们的设计理念可以概括为三句话：

1. 验证分层，问题早现——从代码提交到版本发布，多层门控确保问题在引入的最早阶段被发现
2. 审计独立，标准统一——由独立 Agent 执行审计，避免"自己审自己"的利益冲突
3. 失败闭环，修复可追溯——任何验证失败都进入标准化的修复审计流程，确保问题得到彻底解决

verify-phase、audit-milestone、audit-uat 和 audit-fix 四个工作流，配合 gates.md 中定义的质量标准，共同构成了 GSD 的免疫系统——它不直接产生价值，但确保产生的价值是可靠、可用、可维护的。

下一篇预告： 第 20 篇《代码审查与修复工作流》

我们将聚焦 GSD 的代码审查机制（code-review）和修复工作流（fix-phase），探讨 AI 驱动的代码审查策略和修复任务的分派逻辑。 敬请期待。