工作流架构总览

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

在前 12 篇文章中，我们系统梳理了 GSD 的命令系统。但命令只是触发器——当用户输入 /gsd:execute-phase 或 /gsd:plan-phase 时，真正驱动整个流程的是位于 get-shit-done/workflows/*.md 的工作流文件。GSD 仓库中 shipped 的工作流多达 83 个，它们构成了整个框架的编排层核心。

如果说命令是「用户可见的按钮」，那么工作流就是「按钮背后的剧本」。本篇将从架构视角揭开这 83 个工作流的设计奥秘。

---

一、工作流的定位：Thin Orchestrator 设计哲学

GSD 对工作流有一个明确的角色定义：Thin Orchestrator（薄编排器）。

1.1 不执行，只编排

工作流文件从不执行真正的业务逻辑。它的职责被严格限制为四个动作：

1. Load context —— 通过 gsd-sdk query init.<workflow> 一次性加载项目上下文
2. Spawn agents —— 根据场景启动一个或多个专用 Subagent
3. Collect results —— 收集 Agent 产出，决定下一步路由
4. Update state —— 将进展写回 .planning/STATE.md

flowchart TD
    A[用户输入 /gsd:execute-phase] --> B[命令层 commands/gsd/*.md]
    B --> C[工作流层 workflows/*.md]
    C --> D1[加载上下文 gsd-sdk query init]
    C --> D2[解析参数与 flags]
    C --> D3[决策路由]
    D3 --> E1[Spawn Agent A]
    D3 --> E2[Spawn Agent B]
    D3 --> E3[Spawn Agent C]
    E1 --> F[收集结果]
    E2 --> F
    E3 --> F
    F --> G[更新 STATE.md]
    G --> H[进入下一步或结束]

这个设计与传统的工作流引擎（如 Airflow、Temporal）形成鲜明对比：后者的工作流节点通常包含重型业务逻辑，而 GSD 的工作流节点只包含编排指令。真正的"干活"被委托给 Agent，每个 Agent 获得一个全新的上下文窗口（最高 200K tokens），从根本上消除了 Context Rot。

1.2 为什么必须是 Thin 的？

Context Budget（上下文预算） 是 GSD 架构的核心约束。每个 /gsd:* 命令被调用时，对应的工作流文件会被完整地加载到 AI 的上下文中。如果工作流本身过于庞大，留给 Agent Prompt 和代码库的 token 就会被挤压。

因此，Thin Orchestrator 不是风格偏好，而是工程约束下的必然选择：

层级	职责	Context 占用
命令层（Command）	接收用户输入，启动工作流	~50-100 行 prompt
工作流层（Workflow）	编排逻辑，决策路由	目标 <1000 行
Agent 层	执行实际任务	完整上下文窗口
参考文档层（Reference）	共享知识，按需加载	仅在被 @-reference 时加载

设计原则：The complexity is in the system, not in your workflow.

---

二、工作流文件格式：Markdown + YAML Frontmatter

每个工作流文件都是一个标准的 Markdown 文件，包含 YAML frontmatter 和结构化的 Prompt 主体。

2.1 标准结构

---
# 工作流没有 frontmatter，但包含结构化的 XML/语义化区块
---

<purpose>
一句话描述工作流的核心目的。
</purpose>

<core_principle>
指导性的设计原则或核心哲学。
</core_principle>

<required_reading>
该工作流执行前必须先读取的参考文档列表：
@~/.claude/get-shit-done/references/agent-contracts.md
@~/.claude/get-shit-done/references/context-budget.md
</required_reading>

<available_agent_types>
该工作流有权 spawn 的 Agent 类型列表：
- gsd-executor — 执行计划任务
- gsd-verifier — 验证阶段完成度
- gsd-planner — 创建详细计划
</available_agent_types>

<process>
## 1. Initialize

步骤描述...

## 2. Parse Arguments

步骤描述...

## 3. Spawn Agents

```bash
INIT=$(gsd-sdk query init.execute-phase "${PHASE_ARG}")

### 2.2 与命令文件的关键区别

| 维度 | 命令文件（Command） | 工作流文件（Workflow） |
|------|-------------------|---------------------|
| 位置 | `commands/gsd/*.md` | `get-shit-done/workflows/*.md` |
| Frontmatter | 有（name, description, allowed-tools） | 无（纯结构化 Markdown） |
| 用户可见性 | 是（slash command） | 否（内部实现） |
| 职责 | 启动工作流 | 编排 Agent |
| 长度 | 通常 30-80 行 | 目标 200-1000 行 |
| 上下文加载 | 最小化 | 完整加载 |

---

## 三、工作流与命令的关系：触发 → 编排 → 执行

理解 GSD 的三层架构，是理解工作流设计的关键。

<pre class="mermaid">flowchart TB
    subgraph UserLayer["用户层"]
        U[用户]
    end

    subgraph CommandLayer["命令层"]
        C1[/gsd:new-project/]
        C2[/gsd:plan-phase/]
        C3[/gsd:execute-phase/]
        C4[/gsd:verify-work/]
    end

    subgraph WorkflowLayer["工作流层"]
        W1[new-project.md]
        W2[plan-phase.md]
        W3[execute-phase.md]
        W4[verify-phase.md]
    end

    subgraph AgentLayer["Agent 层"]
        A1[gsd-project-researcher]
        A2[gsd-planner]
        A3[gsd-executor]
        A4[gsd-verifier]
    end

    subgraph FileSystem["文件系统 .planning/"]
        F1[STATE.md]
        F2[ROADMAP.md]
        F3[PLAN.md]
        F4[SUMMARY.md]
    end

    U --> C1
    U --> C2
    U --> C3
    U --> C4

    C1 --> W1
    C2 --> W2
    C3 --> W3
    C4 --> W4

    W1 --> A1
    W2 --> A2
    W3 --> A3
    W4 --> A4

    W1 <---> F1
    W2 <---> F2
    W3 <---> F3
    W4 <---> F4

    A1 --> F1
    A2 --> F3
    A3 --> F4
    A4 --> F1</pre>

### 3.1 数据流解析

1. **用户触发**：用户在终端输入 `/gsd:execute-phase 3`
2. **命令层转发**：命令文件将参数原封不动地传递给工作流
3. **工作流编排**：`execute-phase.md` 解析参数 `3`，加载 ROADMAP.md 和 STATE.md，发现 Phase 3 有 5 个 Plan
4. **Agent 执行**：工作流 spawn 5 个 `gsd-executor` Agent（按 Wave 分组并行）
5. **状态更新**：每个 Plan 完成后，工作流调用 `gsd-sdk query state.advance-plan` 更新进度
6. **结果汇总**：所有 Wave 完成后，spawn `gsd-verifier` 进行阶段级验证

> **核心洞察**：命令是**门面模式**（Facade），工作流是**策略模式**（Strategy），Agent 是**模板方法模式**（Template Method）。三者解耦，各司其职。

---

## 四、工作流设计模式

83 个工作流看似庞大，但它们遵循着有限的设计模式组合。掌握这些模式，就能理解任意工作流的内部逻辑。

### 4.1 顺序编排（Sequential Orchestration）

最基本的设计模式：步骤 A → 步骤 B → 步骤 C，每一步依赖前一步的结果。

**典型代表**：`plan-phase.md`

<pre class="mermaid">flowchart LR
    A[1. Initialize] --> B[2. Parse Arguments]
    B --> C[3. Validate Phase]
    C --> D[4. Research?]
    D -->|yes| E[Spawn gsd-phase-researcher]
    D -->|no| F[5. Planning]
    E --> F
    F --> G[Spawn gsd-planner]
    G --> H[6. Verification Loop]
    H -->|fail| I[Spawn gsd-plan-checker]
    I -->|max 3 iter| G
    H -->|pass| J[7. Update STATE.md]</pre>

plan-phase 的编排逻辑体现了 GSD 的**防御纵深**原则：Planner 产出计划后，必须经 Plan-Checker 审查（最多 3 轮迭代），通过后才更新状态。这不是过度设计，而是对「计划质量决定执行质量」这一认知的工程化表达。

### 4.2 并行 Wave（Wave Execution Model）

GSD 最精妙的编排模式，体现在 `execute-phase.md` 中。

**核心思想**：将 Plan 按依赖关系分组，无依赖的 Plan 构成一个 Wave，同 Wave 内的 Plan 可以**并行执行**；Wave 之间**顺序执行**。

<pre class="mermaid">flowchart TB
    subgraph Wave1["Wave 1: 无依赖计划"]
        P1[Plan 1.1<br>基础设施搭建]
        P2[Plan 1.2<br>数据模型定义]
        P3[Plan 1.3<br>API 契约设计]
    end

    subgraph Wave2["Wave 2: 依赖 Wave 1"]
        P4[Plan 2.1<br>业务逻辑实现]
        P5[Plan 2.2<br>前端组件开发]
    end

    subgraph Wave3["Wave 3: 依赖 Wave 2"]
        P6[Plan 3.1<br>集成测试]
        P7[Plan 3.2<br>端到端验证]
    end

    Wave1 --> Wave2
    Wave2 --> Wave3

    P1 -.->|并行| P2
    P1 -.->|并行| P3
    P4 -.->|并行| P5
    P6 -.->|并行| P7</pre>

**Wave 执行的具体流程**：

1. **Discover**：扫描 phase 目录，列出所有 `*-PLAN.md`
2. **Analyze deps**：读取每个 Plan 的 frontmatter 中的 `depends_on` 字段
3. **Group waves**：拓扑排序，将 Plan 分配到不同 Wave
4. **Spawn per wave**：Wave 1 的所有 Plan 同时 spawn executor
5. **Checkpoint**：Wave 1 全部完成后，才启动 Wave 2
6. **Handle failures**：单个 Plan 失败可触发 `node-repair.md` 自动修复

**运行时适配**：Wave 并行依赖 Subagent spawn 能力。Claude Code 支持 `Task()` 阻塞调用，但 Copilot 的 Subagent 无法可靠返回完成信号。因此 `execute-phase.md` 包含显式的运行时兼容逻辑：

```markdown
**Subagent spawning is runtime-specific:**
- **Claude Code:** Uses `Task(subagent_type="gsd-executor", ...)` — blocks until complete
- **Copilot:** Default to sequential inline execution
- **Other runtimes:** If `Task`/`task` tool unavailable, fall back to sequential

这种运行时感知的设计，是 GSD 能在 10+ 个 AI 平台上运行的关键。

4.3 条件分支（Conditional Branching）

工作流通过前置条件检查实现灵活的路由。

典型模式：

## 2. Parse and Normalize Arguments

Extract from $ARGUMENTS: flags (`--research`, `--skip-research`, `--gaps`, ...)

**If `--reviews` AND `--gaps`:** Error — cannot combine. These are conflicting modes.

**If `planning_exists` is false:** Error — run `/gsd:new-project` first.

条件分支不仅处理用户输入，还处理状态驱动的路由。以 next.md 为例：

flowchart TD
    A[加载 STATE.md] --> B{当前阶段状态?}
    B -->|no planning| C[路由到 /gsd:new-project]
    B -->|discussed| D[路由到 /gsd:plan-phase]
    B -->|planned| E[路由到 /gsd:execute-phase]
    B -->|partial| F[路由到 /gsd:execute-phase --resume]
    B -->|complete| G[路由到 /gsd:verify-work]
    B -->|verified| H[路由到 /gsd:complete-milestone]

4.4 循环和重试（Loop & Retry）

GSD 在工作流层面实现了两种循环模式：

A. 验证循环（Verification Loop）

plan-phase 中的 Plan-Checker 循环：

Planner 产出 PLAN.md
    ↓
Plan-Checker 审查
    ↓
{ 不通过? } ──yes──> Planner 修订（循环，最多 3 次）
    ↓ no
保存最终 PLAN.md

B. 交互循环（Interactive Loop）

manager.md 的 dashboard 循环：

flowchart LR
    A[显示 Dashboard] --> B[用户选择操作]
    B --> C[执行操作]
    C --> D[刷新状态]
    D --> A

manager.md 每完成一个操作后，都会重新加载 init.manager 的 JSON 来刷新 dashboard，实现状态机驱动的交互式工作流。

C. 故障恢复循环（Recovery Loop）

execute-plan.md 中的 node-repair.md 调用：当单个 Plan 执行失败且达到最大重试次数后，spawn gsd-debugger 进行诊断修复，修复成功后重新加入当前 Wave继续执行。

---

五、状态更新机制：工作流如何更新 STATE.md

.planning/STATE.md 是 GSD 的活记忆（Living Memory）。工作流与 STATE.md 的交互是整个编排系统的核心。

5.1 STATE.md 的结构

STATE.md 是一个人类可读的 Markdown 文件，包含以下核心字段：

# Project State

**Current Phase:** 03-authentication
**Current Plan:** 2 of 5 in current phase
**Status:** executing

## Decisions
- 2026-04-20: 使用 JWT 而非 Session Cookie 进行身份认证

## Blockers
- 等待第三方 OAuth 提供商审核应用注册

## Metrics
- Total Plans: 23
- Completed Plans: 18
- Completion Rate: 78%

5.2 状态操作 CLI

gsd-tools.cjs（及 SDK）提供了一组原子化的状态操作命令：

命令	功能	工作流使用场景
state.update <field> <value>	更新单个字段	切换 Current Phase
state.patch <json>	批量更新多个字段	完成一组 Plan 后批量更新
state.advance-plan	推进当前 Plan 计数	Plan 执行完成后
state.update-progress	重新计算全局进度	里程碑检查点
state.add-decision	记录决策	讨论阶段产出的关键决定
state.add-blocker	记录阻塞项	执行中发现的外部依赖
state.resolve-blocker	解除阻塞	阻塞项被解决后
state.record-session	记录会话摘要	工作流结束时

5.3 并发安全：原子读写

当多个 Agent 并行执行时（如 Wave 执行），可能出现并发写入 STATE.md 的情况。GSD 通过文件锁机制解决：

// state.cjs 中的 readModifyWriteStateMd
const _heldStateLocks = new Set();
process.on('exit', () => {
  for (const lockPath of _heldStateLocks) {
    try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
  }
});

每个状态更新操作都是读-改-写的原子事务，确保即使在并行 Wave 执行场景下，STATE.md 也不会出现数据竞争。

5.4 工作流中的状态更新模式

以 execute-phase.md 为例，状态更新发生在三个关键节点：

sequenceDiagram
    participant W as execute-phase.md
    participant S as STATE.md
    participant A as gsd-executor

    W->>S: state.begin-phase (标记状态为 executing)
    loop 每个 Wave
        W->>A: Spawn executor for Plan N
        A->>A: 执行计划任务
        A->>A: 创建 SUMMARY.md
        W->>S: state.advance-plan (Plan N+1)
    end
    W->>S: state.update-progress (重新计算全局统计)
    W->>S: state.record-session (记录本次执行摘要)

---

六、渐进式披露（Progressive Disclosure）

83 个工作流中，有 3 个顶级编排器（execute-phase.md、plan-phase.md、new-project.md）的体量接近 XL 级别（1700 行）。如何让这些大工作流不吞噬上下文预算？GSD 的答案是渐进式披露。

6.1 核心思想

只在需要时加载，只加载需要的部分。

工作流文件被完整加载到上下文中，但如果工作流内部包含大量条件分支（如 --auto 模式 vs 交互模式），那些当前条件不会触发的分支代码也会被加载，浪费 token。

渐进式披露通过文件拆分解决这个问题：将条件分支体提取到子文件中，父文件变成薄分发器（Thin Dispatcher），只读取当前条件需要的子文件。

6.2 典范实现：discuss-phase

discuss-phase.md 是渐进式披露的最佳范例。原始文件曾是一个 2000+ 行的单体文件，经重构后变成：

workflows/
├── discuss-phase.md          # 薄分发器 (~300 行)
└── discuss-phase/
    ├── modes/
    │   ├── default.md        # 默认交互模式
    │   ├── power.md          # Power-user 模式
    │   ├── auto.md           # 自动模式
    │   ├── all.md            # 全量问题模式
    │   ├── chain.md          # 链式追问模式
    │   ├── text.md           # 纯文本模式
    │   ├── batch.md          # 批量处理模式
    │   ├── analyze.md        # 分析模式
    │   └── advisor.md        # 顾问模式
    └── templates/
        ├── CONTEXT.md        # 上下文模板
        ├── DISCUSSION-LOG.md # 讨论日志模板
        └── checkpoint.json   # 检查点 schema

父文件 discuss-phase.md 的逻辑简化为：

1. 解析 `--mode` 参数（默认 `default`）
2. Read `discuss-phase/modes/{mode}.md`
3. 按 mode 文件中的 process 执行

这样，当用户以默认模式调用 /gsd:discuss-phase 时，只有 default.md 被加载；其他 8 个 mode 文件对当前上下文完全不可见，节省了大量 token。

6.3 渐进式披露的通用模式

模式	适用场景	文件组织
Mode 拆分	同一工作流有多种互斥执行模式	workflows/<name>/modes/*.md
Template 外置	需要填充的大段模板文本	workflows/<name>/templates/*.md
Reference 下沉	共享知识被多个工作流引用	references/*.md（已存在）
Agent 技能外置	Agent 专用技能描述	references/agent-skills/*.md

---

七、大小预算控制

渐进式披露不是可选项，而是硬约束——GSD 通过自动化测试强制工作流遵守大小预算。

7.1 三级预算体系

tests/workflow-size-budget.test.cjs 定义了三个大小等级：

Tier	行数限制	适用工作流	代表文件
XL	1700 行	顶级编排器	execute-phase.md, plan-phase.md, new-project.md
LARGE	1500 行	多步骤规划器和大型特性工作流	manager.md, autonomous.md, ai-integration-phase.md
DEFAULT	1000 行	专注的单用途工作流（目标层级）	do.md, fast.md, help.md, note.md

此外，discuss-phase.md 有一个特殊约束：<500 行（issue #2551），强制其必须采用渐进式披露模式。

7.2 预算超限的处理策略

当工作流增长超出其 tier 限制时，GSD 采用以下拆分策略（按优先级排序）：

1. 提取 per-mode bodies → workflows/<workflow>/modes/<mode>.md
2. 提取 templates → workflows/<workflow>/templates/
3. 下沉共享知识 → get-shit-done/references/
4. 提取子工作流 → 独立的 workflows/<sub-workflow>.md

7.3 预算控制的工程意义

大小预算不仅仅是「代码整洁」的审美要求，它直接关联到 GSD 的运行成本：

• 每个工作流文件被调用时，其全部内容进入 AI 上下文
• 一个 2000 行的工作流可能占用 8K-15K tokens
• 如果这 8K tokens 中有 60% 是当前执行路径不会触发的代码，就是无效上下文
• 无效上下文 = 更贵的 API 调用 + 更低的输出质量（有效上下文被挤压）

因此，workflow-size-budget.test.cjs 是 GSD 质量保证体系的关键一环。

---

八、工作流分类概览

83 个工作流按职能可分为六大类：

8.1 初始化类（Initialization）

负责项目从无到有的创建和配置。

工作流	功能	触发命令
new-project.md	统一的新项目流程：提问 → 研究 → 需求 → 路线图	/gsd:new-project
new-milestone.md	新里程碑周期	/gsd:new-milestone
new-workspace.md	创建隔离工作区	/gsd:new-workspace
discovery-phase.md	存量项目发现	/gsd:new-project --discovery
map-codebase.md	代码库映射	/gsd:map-codebase
import.md	外部计划导入	/gsd:import
ingest-docs.md	混合规划文档扫描	/gsd:ingest-docs

8.2 规划类（Planning）

负责将需求转化为可执行计划。

工作流	功能	触发命令
plan-phase.md	创建可执行 PLAN.md	/gsd:plan-phase
discuss-phase.md	提取实现决策	/gsd:discuss-phase
research-phase.md	领域研究	/gsd:research-phase
plan-review-convergence.md	跨 AI 计划收敛	/gsd:plan-review-convergence
ai-integration-phase.md	AI 功能专项规划	/gsd:ai-integration-phase
analyze-dependencies.md	依赖分析	/gsd:analyze-dependencies

8.3 执行类（Execution）

负责实际的任务执行和代码产出。

工作流	功能	触发命令
execute-phase.md	Wave 并行执行阶段	/gsd:execute-phase
execute-plan.md	单计划执行	execute-phase 子调用
autonomous.md	自主驱动里程碑	/gsd:autonomous
quick.md	快速任务内联执行	/gsd:quick
fast.md	极简任务无开销执行	/gsd:fast
manager.md	交互式里程碑指挥中心	/gsd:manager
do.md	自由文本路由	/gsd:do
next.md	自动推进下一步	/gsd:next

8.4 验证类（Verification）

负责确保产出质量符合目标。

工作流	功能	触发命令
verify-phase.md	目标回溯验证	/gsd:verify-work
add-tests.md	测试生成	/gsd:add-tests
code-review.md	代码审查	/gsd:code-review
code-review-fix.md	审查问题自动修复	/gsd:code-review-fix

8.5 审计类（Audit）

负责长期质量保障和跨阶段检查。

工作流	功能	触发命令
audit-milestone.md	里程碑完成审计	/gsd:audit-milestone
audit-uat.md	UAT 跨阶段审计	/gsd:audit-uat
audit-fix.md	审计到修复的自动化流水线	/gsd:audit-fix
eval-review.md	AI 评估覆盖回溯	/gsd:eval-review
health.md	规划目录健康检查	/gsd:health

8.6 交互与辅助类（Interaction & Utility）

负责用户体验增强和开发辅助。

工作流	功能	触发命令
help.md	命令参考	/gsd:help
progress.md	进度展示	/gsd:progress
note.md	零摩擦想法记录	/gsd:note
add-todo.md	待办捕获	/gsd:add-todo
check-todos.md	待办列表	/gsd:check-todos
debug.md / diagnose-issues.md	调试与诊断	/gsd:debug
forensics.md	故障调查	/gsd:forensics
pause-work.md / resume-work.md	会话交接	/gsd:pause-work
extract_learnings.md	经验提取	/gsd:extract-learnings

---

九、小结

GSD 的工作流层是「命令是触发器，工作流是剧本，Agent 是演员」这一架构哲学的集中体现。

设计要点	关键决策	收益
Thin Orchestrator	工作流不执行业务逻辑，只编排 Agent	Context Budget 可控
Markdown 即代码	工作流是可读的结构化 Markdown	人类可审计，AI 可执行
Wave 并行	按依赖分组，同组并行，组间顺序	最大化并行度，保证依赖正确
文件状态	STATE.md 作为活记忆	跨会话持久化，人类可读
渐进式披露	大工作流拆分为 mode/template/reference	无效上下文最小化
大小预算	XL/LARGE/DEFAULT 三级硬约束	运行成本可控，质量可预期
运行时适配	工作流内置多平台兼容逻辑	10+ AI 平台一次编写，到处运行

这六大设计要点共同支撑起 GSD 工作流系统的核心能力：在有限的上下文窗口内，编排无限的复杂度。

---

下一篇预告：第 14 篇《execute-phase 工作流深度解析》将聚焦 GSD 最复杂的顶级编排器——execute-phase.md。我们将逐行拆解它的 Wave 分组算法、Subagent 上下文注入协议、运行时兼容性处理、Checkpoint 与 Drift Gate 机制，以及失败恢复与 Node Repair 的完整实现。这是理解 GSD 执行引擎的必修课，敬请期待！