核心参考文档（下）

这是「GSD 全景代码解析」专题的第 33 篇。在本系列中，我们将逐层拆解 Get Shit Done (GSD) 这一 56K+ stars 的 Meta-Prompting 框架，从命令系统到工作流编排，从 Agent 设计到上下文工程，带你一览上下文驱动开发的工程全貌。

---

一、引言：参考文档层的底层支柱

在前一篇文章中，我们解析了 GSD 参考文档层的上半部分——包括 context-budget.md、research.md、execution.md 等面向流程的参考文档。这些文档回答了**"怎么做"**的问题。

本文将聚焦参考文档层的下半部分——四份面向能力与质量的参考文档：

参考文档	核心职责	解决的问题
model-profiles.md	定义模型能力矩阵	"用什么模型"
model-profile-resolution.md	解析模型选择策略	"如何选模型"
verification-overrides.md	配置验证覆盖规则	"验证什么、怎么验证"
common-bug-patterns.md	收录常见 Bug 模式	"可能犯什么错"

这四份文档构成了 GSD 的能力编排层和质量保障层。Agent 在执行任务时，不仅依赖工作流定义的流程，更依赖这些参考文档定义的能力边界和质量基准。

---

二、model-profiles.md：模型能力矩阵

2.1 设计意图

GSD 支持多种 LLM 运行时（Claude Code、Gemini CLI、Codex、Copilot 等），但不同模型在上下文长度、推理能力、代码质量、工具调用可靠性等方面存在显著差异。model-profiles.md 的核心目标是将这些差异显式化、可配置化，让系统能够根据任务特征自动选择最合适的模型。

2.2 模型配置结构

每个模型在 model-profiles.md 中以一个结构化的 Profile 定义：

profile:
  id: claude-3-5-sonnet-20241022
  name: Claude 3.5 Sonnet
  vendor: anthropic
  tier: standard        # fast / standard / reasoning
  
  capabilities:
    context_window: 200000
    output_limit: 8192
    tool_use: true
    vision: true
    reasoning: false
    
  performance:
    code_quality: 9
    reasoning_depth: 8
    instruction_following: 9
    creativity: 7
    
  constraints:
    max_concurrent_tools: 32
    supports_artifacts: true
    preferred_output_format: xml

2.3 模型能力对比

GSD 将模型划分为三个层级，对应不同的任务类型：

层级	代表模型	上下文窗口	核心优势	典型场景
Fast	Claude 3.5 Haiku, Gemini 1.5 Flash	128K-1M	低延迟、低成本	文件搜索、简单编辑、状态检查
Standard	Claude 3.5 Sonnet, GPT-4o	128K-200K	均衡能力	代码实现、文档生成、常规调试
Reasoning	Claude 3.7 Sonnet, o1, o3-mini	128K-200K	深度推理、复杂规划	架构设计、算法优化、安全审计

这种三层架构是 GSD 模型路由策略的基础。系统不会对所有任务使用最强的模型，而是根据任务复杂度进行智能降级或升级。

2.4 能力评分维度

model-profiles.md 中的 performance 字段采用 1-10 的评分制，涵盖五个维度：

• code_quality：生成代码的正确性、可读性和最佳实践遵循度
• reasoning_depth：处理复杂逻辑推理和多层依赖分析的能力
• instruction_following：对详细指令（尤其是负面约束）的遵循精度
• creativity：解决开放性问题的创新思维和方案多样性
• speed：端到端响应延迟（包括工具调用往返）

这些评分不是主观臆断，而是基于 GSD 团队对多个模型在相同基准测试集上的持续评估结果。评分会随模型版本更新而调整，确保路由决策的准确性。

2.5 模型选择策略

基于 model-profiles.md 的能力矩阵，GSD 实现了三种模型选择策略：

策略一：固定绑定

在 Agent 的 frontmatter 中直接指定模型：

model: claude-3-5-sonnet-20241022

这是最直接的策略，适用于对模型能力有明确要求的 Agent（如 gsd-security-auditor 需要推理能力强的模型）。

策略二：层级委托

Agent 不指定具体模型，只声明所需层级：

model_tier: standard   # 或 fast / reasoning

系统在运行时会从该层级中选择当前可用且性能最优的模型。这种策略提高了 Agent 的运行时可移植性——同一个 Agent 可以在不同环境中使用不同的具体模型，只要满足层级要求即可。

策略三：动态路由

最灵活的策略，根据任务上下文动态选择模型：

model_routing:
  default: standard
  rules:
    - condition: "task.complexity > 8"
      target: reasoning
    - condition: "task.scope == 'file_search'"
      target: fast
    - condition: "task.requires_vision == true"
      target: "vendor:anthropic,capabilities.vision:true"

动态路由策略让单个 Agent 能够根据具体任务的特征自动切换模型，实现**"该省则省，该花则花"**的成本和性能平衡。

---

三、model-profile-resolution.md：解析与覆盖机制

3.1 为什么需要解析机制

当 Agent 指定 model_tier: standard 时，系统需要回答两个问题：

1. "standard 层级当前有哪些可用模型？"
2. "如果有多个可用模型，选哪一个？"

model-profile-resolution.md 定义了这套解析规则，将抽象的层级声明转换为具体的模型实例。

3.2 解析流程

模型解析遵循一个四阶段流水线：

flowchart LR
    A[Agent 声明] --> B[层级解析]
    B --> C[环境过滤]
    C --> D[偏好排序]
    D --> E[最终选择]

阶段一：层级解析（Tier Resolution）

将 model_tier 或 model_routing 规则转换为候选模型集合。例如 standard 层级可能映射到：

• claude-3-5-sonnet-20241022
• gpt-4o-2024-08-06
• gemini-1.5-pro-002

阶段二：环境过滤（Environment Filtering）

根据当前运行时的环境变量和配置，过滤掉不可用的模型：

• 检查 API Key 是否配置
• 检查模型是否在当前区域可用
• 检查速率限制是否允许新请求
• 检查模型是否被用户显式禁用

阶段三：偏好排序（Preference Ranking）

对候选模型按优先级排序。排序因素包括：

1. 用户显式偏好（最高优先级）
2. 成本效率（tokens/美元比）
3. 历史成功率（该 Agent 使用该模型的历史成功率）
4. 当前负载（避免集中在单一模型上）

阶段四：最终选择（Final Selection）

选择排序后的第一个模型。如果所有候选模型都不可用，则触发降级策略（如从 standard 降级到 fast 并附加重试逻辑）。

3.3 层级覆盖策略

GSD 的模型配置支持多层覆盖，优先级从高到低依次为：

层级	配置位置	覆盖范围	典型用途
L1: 任务级	工作流中的 model 参数	单次任务	特定步骤需要特殊模型
L2: Agent 级	Agent frontmatter	该 Agent 的所有调用	Agent 的默认模型偏好
L3: 命令级	命令定义中的 default_model	该命令的所有工作流	命令的推荐模型配置
L4: 项目级	.planning/model-config.yaml	整个项目	团队统一的模型策略
L5: 全局级	GSD 安装目录下的 profiles.yaml	所有项目	用户个人偏好
L6: 默认级	model-profiles.md 中的系统默认值	全系统	兜底配置

这种六层覆盖机制确保了灵活性和一致性的平衡：

• 日常开发：使用 L5/L4 层配置，无需关心具体模型
• 特殊任务：在 L1/L2 层覆盖，满足特定需求
• 团队协作：L4 层确保项目内模型选择的一致性

3.4 覆盖冲突解决

当多个层级的配置发生冲突时，model-profile-resolution.md 定义了明确的解决规则：

resolution_rules:
  strict_override: true      # 高层严格覆盖低层
  merge_behavior: 
    scalar: override         # 标量值：高层覆盖低层
    list: append_unique      # 列表：去重合并
    object: deep_merge       # 对象：递归合并
  
  exceptions:
    - rule: "L1 不能降低 tier"
      description: "任务级不能选择比 Agent 级更低的能力层级"
    - rule: "L4 可以禁用模型"
      description: "项目级可以显式禁用某些模型（如合规要求）"

例如，如果一个 Agent 声明了 model_tier: reasoning，但项目级配置禁用了所有 reasoning 级模型，则系统会：

1. 触发合规冲突告警
2. 尝试使用 standard 层级的最强模型作为替代
3. 在日志中记录降级原因，供审计使用

---

四、verification-overrides.md：验证覆盖规则

4.1 验证体系概述

在 GSD 的架构中，验证不是可选项，而是内建的强制环节。每个工作流在执行完成后都必须经过验证（Verification）阶段。但不同任务类型、不同工件（Artifact）的验证需求各不相同。

verification-overrides.md 的核心职责是定义**"何时放宽验证"和"如何针对性验证"**的规则。

4.2 默认验证策略

GSD 的默认验证策略是**"全面验证"**：

验证类型	检查内容	执行者
语法验证	代码是否能通过编译器/解释器的语法检查	gsd-verifier
逻辑验证	代码是否符合需求规格的描述	gsd-verifier
风格验证	代码是否遵循项目的编码规范	gsd-code-reviewer
集成验证	变更是否破坏现有功能	gsd-integration-checker
安全验证	是否存在已知的安全漏洞	gsd-security-auditor

4.3 按工件类型的验证配置

verification-overrides.md 允许根据工件类型调整验证策略：

verification_rules:
  # 配置文件：语法验证即可
  - pattern: "*.config.*"
    override:
      logic_verification: skip
      style_verification: skip
      integration_verification: conditional
    reason: "配置文件变更通常不影响业务逻辑"

  # 测试文件：重点关注逻辑和集成验证
  - pattern: "*test*"
    override:
      style_verification: relaxed
      logic_verification: strict
      integration_verification: strict
    reason: "测试代码需要严格验证其覆盖的逻辑正确性"

  # 文档文件：仅做风格检查
  - pattern: "*.md"
    override:
      syntax_verification: skip
      logic_verification: skip
      integration_verification: skip
      style_verification: doc_style
    reason: "文档文件无需代码级验证"

  # 前端样式文件：跳过逻辑验证
  - pattern: "*.{css,scss,less}"
    override:
      logic_verification: skip
      style_verification: css_lint
    reason: "样式文件无业务逻辑"

4.4 验证覆盖规则

除了按文件类型的规则，verification-overrides.md 还支持以下覆盖场景：

场景一：紧急修复（Hotfix Override）

hotfix_override:
  enabled: true
  conditions:
    - branch_pattern: "hotfix/*"
    - label: "urgent"
  effects:
    integration_verification: reduced_scope
    security_verification: fast_track
  approval_required: true

当工作流检测到当前分支是 hotfix/* 或带有 urgent 标签时，自动应用紧急修复验证模式：缩小集成验证范围、加速安全验证，但需要额外的人工审批。

场景二：已知风险接受（Accepted Risk Override）

accepted_risks:
  - id: RISK-001
    description: "临时降级 TypeScript 严格模式"
    scope: "src/legacy/**/*"
    override:
      syntax_verification: allow_warnings
    expires: "2026-06-01"

对于技术债务或迁移期的代码，可以显式声明已知风险，在风险到期前允许特定的验证放宽。

场景三：增量验证（Incremental Override）

incremental_override:
  enabled: true
  trigger: "change_size < 50 lines"
  effects:
    integration_verification: affected_only
    scope_calculation: dependency_graph

当变更很小（如少于 50 行）时，系统可以只验证受影响的模块，而非全量集成验证。这种优化基于 GSD 的依赖图分析能力，确保小变更的验证既快速又安全。

4.5 验证覆盖的审计追踪

所有验证覆盖操作都会被记录到 VERIFICATION-LOG.md：

## 2026-04-24 14:35:00
- 任务：gsd-executor / TASK-3342
- 覆盖规则：incremental_override
- 触发条件：change_size = 23 lines
- 原始验证：full_integration
- 实际验证：affected_only (modules: auth, session)
- 验证结果：PASSED

这种审计追踪确保了**"放宽验证不等于放弃质量"**——每一次覆盖都有明确的理由、范围和结果记录。

---

五、common-bug-patterns.md：常见 Bug 模式库

5.1 设计意图

AI Agent 在生成代码时，会犯一些系统性错误——即特定模型在特定场景下反复出现的同类错误。common-bug-patterns.md 是一个组织级知识库，收录了这些已知模式，帮助 Agent 在执行和验证阶段主动规避。

5.2 Bug 模式结构

每个 Bug 模式包含以下字段：

pattern:
  id: BP-017
  name: "异步资源泄漏"
  severity: high
  affected_models:
    - claude-3-5-sonnet
    - gpt-4o
  affected_languages:
    - javascript
    - typescript
    - python
  
  description: |
    在异步函数中创建资源（如 EventEmitter、Stream、Timer）时，
    Agent 经常忘记在函数退出或错误时清理这些资源。
  
  symptoms:
    - "内存使用量随请求数持续增长"
    - "进程退出时触发 MaxListenersExceededWarning"
    - "测试用例在多次运行后随机失败"
  
  root_cause: |
    模型的训练数据倾向于展示"正确路径"的代码，
    对错误处理和资源清理的重视不足。
  
  prevention: |
    1. 使用 `try/finally` 或 `using` 语法确保资源释放
    2. 对异步函数强制要求 cleanup 代码块
    3. 在代码审查阶段重点检查资源创建点
  
  detection: |
    检查所有 `new EventEmitter()`、`setInterval()`、
    `createReadStream()` 等调用是否对应有清理逻辑。

5.3 Bug 模式分类

common-bug-patterns.md 按错误类型将 Bug 模式分为六大类：

分类	典型模式	影响范围
资源管理	异步泄漏、文件句柄未关闭、数据库连接池耗尽	运行时稳定性
并发控制	竞态条件、死锁、原子性缺失	多线程/多进程场景
类型安全	any 滥用、泛型推断失败、类型收窄遗漏	TypeScript 项目
边界处理	空值检查遗漏、索引越界、整数溢出	所有语言
API 误用	弃用 API 使用、参数顺序错误、返回值忽略	特定框架/库
安全漏洞	SQL 注入、XSS、路径遍历、敏感信息泄露	安全合规

5.4 与 gsd-debugger 的协作

common-bug-patterns.md 与 gsd-debugger Agent 之间有紧密的协作关系：

flowchart TB
    subgraph "执行阶段"
        E1[gsd-executor 生成代码]
        E2[对照 common-bug-patterns 自检]
        E3[标记潜在风险点]
    end
    
    subgraph "调试阶段"
        D1[gsd-debugger 接收调试任务]
        D2[查询匹配的 Bug 模式]
        D3[生成针对性修复方案]
    end
    
    E1 --> E2 --> E3
    E3 -.->|风险标记传递| D1
    D1 --> D2 --> D3

协作机制一：预防性注入

在 gsd-executor 的 Prompt 中，系统会根据当前任务的语言和模型，动态注入相关的 Bug 模式：

## 已知风险提醒
基于当前使用的模型和语言，请特别注意以下常见错误：

- BP-017: 异步资源泄漏（JavaScript/TypeScript）
- BP-023: Promise 链错误处理遗漏
- BP-031: 闭包捕获循环变量

请在生成代码时主动规避这些模式。

协作机制二：诊断加速

当 gsd-debugger 接到调试任务时，会首先查询 common-bug-patterns.md：

1. 症状匹配：将错误日志/现象与模式库中的 symptoms 字段匹配
2. 根因定位：如果匹配成功，直接采用已知根因，减少盲目排查
3. 修复建议：基于 prevention 字段生成修复方案

这种协作让 gsd-debugger 不再是"从零开始排查"，而是**"站在已知经验上诊断"**。

协作机制三：模式进化

common-bug-patterns.md 是一个活文档。当 gsd-debugger 发现并修复了一个新的系统性错误时，如果这个错误具有可复现性和通用性，就会触发模式提取流程：

flowchart LR
    A[gsd-debugger 发现新 Bug] --> B{是否系统性错误?}
    B -->|是| C[提取模式模板]
    C --> D[提交到 common-bug-patterns]
    D --> E[更新 gsd-executor 的 Prompt]
    B -->|否| F[记录为一次性问题]

这种闭环进化机制确保了 GSD 的 Bug 模式库随时间不断成长，让整个系统越用越聪明。

5.5 模式库的版本管理

common-bug-patterns.md 采用语义化版本管理：

common-bug-patterns.md
├── v1.0.0  # 初始版本，30 个基础模式
├── v1.1.0  # 增加 TypeScript 专用模式
├── v1.2.0  # 增加安全漏洞模式
└── v2.0.0  # 重构分类体系，模式数达 100+

项目可以通过 .planning/gsd-config.yaml 锁定使用的模式库版本：

reference_docs:
  bug_patterns:
    version: "1.2.0"
    auto_update: minor   # 允许自动更新到最新 minor 版本

---

六、小结

本文深入解析了 GSD 参考文档层的四份核心能力文档：

1. model-profiles.md：通过结构化的能力矩阵，将不同模型的差异显式化，为智能路由提供数据基础
2. model-profile-resolution.md：定义了六层覆盖的解析机制和冲突解决规则，实现灵活而一致的模型选择
3. verification-overrides.md：在"全面验证"的默认策略之上，提供按工件类型、场景和紧急程度的验证覆盖规则
4. common-bug-patterns.md：组织级 Bug 模式知识库，与 gsd-debugger 形成预防-诊断-进化的闭环

这四份文档与前文解析的流程参考文档一起，构成了 GSD 上下文工程的完整拼图：

• 流程参考文档告诉你**"怎么做"**
• 能力参考文档告诉你**"用什么做"**
• 质量参考文档告诉你**"做到什么程度"**
• 知识参考文档告诉你**"别犯什么错"**

在下一篇文章中，我们将进入 GSD 参考文档层的最后一块拼图——思考模型与策略参考，解析 GSD 如何通过 thinking-models.md 和 strategy-references.md 引导 Agent 进行更高质量的推理和决策。

---

下一篇预告： 第 34 篇《思考模型与策略参考》——解析 GSD 的推理增强层：思考模型（Thinking Models）与策略参考（Strategy References）如何引导 Agent 进行结构化思考与高质量决策。