工作流设计模式总结

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

---

一、工作流层的核心设计哲学

在前 8 篇文章中（第 13-20 篇），我们深入解析了 GSD 的各个工作流。现在，让我们从更高的视角审视这些工作流背后的设计模式和架构原则。

GSD 的工作流层遵循一个核心原则：Thin Orchestrators——工作流只做编排，不做重活。这一原则看似简单，但其背后的设计决策深刻影响了整个系统的可维护性、可扩展性和可靠性。

flowchart TB
    subgraph "传统模式"
        A1[单体工作流] --> A2[包含全部逻辑]
        A2 --> A3[臃肿、难维护]
    end
    subgraph "GSD 模式"
        B1[Thin Orchestrator] --> B2[只做编排]
        B2 --> B3[委托给 Agents]
        B3 --> B4[轻量、可组合]
    end

---

二、Thin Orchestrator 模式

2.1 什么是 Thin Orchestrator

在 GSD 中，工作流文件（workflows/*.md）的"胖"主要体现在体积（最大 69KB），而非逻辑复杂度。这些体积主要来自于：

• 详细的上下文说明：告诉 Agent 当前阶段的目标和约束
• 渐进式披露：分步骤加载信息，避免一次性淹没 Agent
• 状态更新指令：精确指导如何更新 .planning/ 目录中的状态文件
• 错误处理指南：各种异常场景的处理策略

而实际的业务逻辑（代码生成、测试编写、文档撰写等）全部委托给专门的 Agents。

2.2 Orchestrator 与 Agent 的职责边界

职责	Orchestrator (工作流)	Agent
流程控制	✅ 决定执行顺序和分支	❌
状态管理	✅ 更新 STATE.md / ROADMAP.md	❌
上下文组装	✅ 加载参考文档和模板	❌
代码生成	❌	✅ 实际编写代码
测试编写	❌	✅ 实际编写测试
调试诊断	❌	✅ 实际分析问题
质量验证	❌	✅ 实际执行检查

sequenceDiagram
    participant W as Workflow (Orchestrator)
    participant E as gsd-executor
    participant D as gsd-debugger
    participant V as gsd-verifier

    W->>W: 1. 加载上下文和参考文档
    W->>E: 2. 委托：执行 Task A
    E->>E: 3. 编写代码 + 测试
    E->>W: 4. 返回结果
    W->>W: 5. 更新 STATE.md
    W->>V: 6. 委托：验证工作
    V->>V: 7. 执行验证检查
    V->>W: 8. 返回验证报告
    alt 验证失败
        W->>D: 9. 委托：调试修复
        D->>D: 10. 诊断问题
        D->>W: 11. 返回修复方案
    end

2.3 为什么工作流可以"大"但仍然是 Thin

一个常见疑问是：如果工作流文件达到 69KB，它怎么还能被称为"Thin"？

答案是：Thin 指的是逻辑复杂度，而非文件大小。GSD 工作流的大量内容实际上是：

1. 文档化的编排逻辑：用文字描述"做什么"而非"怎么做"
2. 上下文工程：精心设计的上下文加载策略
3. 防御性指令：各种边界情况的处理指南

这些内容都是声明式的，而非命令式的。它们告诉 Agent"应该达成什么目标"，而非"如何达成目标"。

---

三、状态机设计模式

3.1 工作流作为状态机

每个 GSD 工作流本质上是一个有限状态机（Finite State Machine）：

stateDiagram-v2
    [*] --> 初始化
    初始化 --> 执行中
    执行中 --> 验证中
    验证中 --> 完成
    验证中 --> 修复中
    修复中 --> 验证中
    修复中 --> 失败
    完成 --> [*]
    失败 --> [*]

状态转换由以下因素驱动：

• 前置条件：当前状态是否满足进入下一状态的条件
• 事件：Agent 的执行结果、用户输入、外部信号
• 守卫条件：gates.md 中定义的检查点

3.2 状态持久化

GSD 的状态机不是内存中的对象，而是文件系统中的文档：

.planning/
├── STATE.md          # 当前状态
├── ROADMAP.md        # 目标状态
└── phases/
    ├── phase-01.md   # 阶段状态
    └── phase-02.md   # 阶段状态

这种设计带来了独特的优势：

1. 可恢复性：任何时候都可以从 STATE.md 恢复执行
2. 可观察性：人类可以直接阅读状态文件了解项目进展
3. 可审计性：状态历史可以通过 Git 追溯
4. 跨会话：Agent 可以"离线"后重新加载状态继续工作

3.3 状态传播机制

状态在工作流和 Agent 之间传播：

flowchart LR
    A[Workflow 读取 STATE.md] --> B[组装上下文]
    B --> C[调用 Agent]
    C --> D[Agent 执行任务]
    D --> E[Agent 返回结果]
    E --> F[Workflow 更新 STATE.md]

---

四、Agent 委托策略

4.1 委托模式分类

GSD 工作流使用三种 Agent 委托模式：

模式	说明	示例
直接委托	工作流直接调用单个 Agent	execute-phase → gsd-executor
链式委托	Agent A 完成后调用 Agent B	planner → plan-checker
并行委托	多个 Agent 同时执行（Wave）	多个 gsd-verifier 并行验证

4.2 Wave 执行模型

Wave 是 GSD 最核心的并行执行模式：

flowchart TB
    subgraph Wave1["Wave 1"]
        A1[Task 1.1] 
        A2[Task 1.2]
        A3[Task 1.3]
    end
    subgraph Wave2["Wave 2 (依赖 Wave 1)"]
        B1[Task 2.1]
        B2[Task 2.2]
    end
    subgraph Wave3["Wave 3 (依赖 Wave 2)"]
        C1[Task 3.1]
    end
    Wave1 --> Wave2
    Wave2 --> Wave3

Wave 的设计原则：

• 同 Wave 内无依赖：同一 Wave 的任务可以并行执行
• 跨 Wave 有依赖：后续 Wave 依赖前面 Wave 的完成
• 失败隔离：单个 Wave 的失败不影响其他 Wave
• 增量状态更新：每个 Wave 完成后更新 STATE.md

4.3 Agent 选择的上下文感知

工作流不是硬编码调用哪个 Agent，而是根据当前上下文动态选择：

flowchart TD
    A[需要执行代码] --> B{代码类型?}
    B -->|前端| C[gsd-executor]
    B -->|后端| C
    B -->|基础设施| D[gsd-executor + gsd-verifier]
    E[需要验证] --> F{验证类型?}
    F -->|功能测试| G[gsd-verifier]
    F -->|安全审查| H[gsd-security-auditor]
    F -->|UI 检查| I[gsd-ui-auditor]

---

五、工作流组合模式

5.1 组合而非继承

GSD 的工作流采用组合而非继承的复用策略。一个工作流可以调用其他工作流作为子流程：

flowchart TD
    A[new-project 工作流] --> B[plan-phase 工作流]
    B --> C[research-phase 工作流]
    C --> B
    B --> D[execute-phase 工作流]
    D --> E[verify-phase 工作流]
    E -->|失败| D
    E -->|通过| F[audit-milestone 工作流]

5.2 工作流模板

对于常见的子流程，GSD 提供了工作流模板：

模板	用途	使用场景
验证模板	标准化的验证流程	verify-phase、audit-fix
研究模板	深度研究的标准流程	research-phase、spike
审查模板	代码审查的标准流程	code-review、audit-milestone

模板存放在 get-shit-done/templates/ 目录中，工作流通过引用机制复用。

5.3 条件分支与动态路由

工作流支持条件分支，根据状态动态选择执行路径：

flowchart TD
    A[开始执行] --> B{是否有计划?}
    B -->|是| C[按计划执行]
    B -->|否| D[调用 plan-phase]
    C --> E{验证通过?}
    D --> E
    E -->|是| F[提交代码]
    E -->|否| G{可修复?}
    G -->|是| H[调用 debug]
    G -->|否| I[标记失败]
    H --> E

---

六、渐进式披露机制

6.1 什么是渐进式披露

渐进式披露（Progressive Disclosure）是 GSD 工作流的核心设计技巧：只在需要的时候提供必要的信息。

对于一个 69KB 的工作流文件，如果一次性全部加载到 Agent 的上下文中，会迅速耗尽 token 预算。GSD 通过以下策略解决：

1. 分层加载：先加载高层概述，需要时再加载细节
2. 条件加载：根据当前状态决定加载哪些参考文档
3. 引用机制：使用 @reference 引用外部文档而非内联

6.2 上下文预算分配

GSD 为每个阶段分配上下文预算：

阶段	预算比例	用途
系统指令	20%	工作流的核心逻辑
参考文档	30%	加载的 references/*.md
状态信息	20%	STATE.md、ROADMAP.md
任务上下文	20%	当前任务的具体信息
保留缓冲	10%	应对意外情况

6.3 大小预算控制

GSD 对工作流文件本身也有大小限制：

级别	行数限制	适用场景
Default	1,000 行	标准工作流
Large	1,500 行	复杂工作流
XL	1,700 行	核心工作流（execute-phase、plan-phase）

超过限制的 workflow 需要拆分为多个文件或使用引用机制。

---

七、错误处理与恢复模式

7.1 工作流级别的错误处理

GSD 工作流定义了标准的错误处理模式：

错误类型	处理策略	示例
Agent 失败	重试 → 降级 → 上报	执行失败时重试 3 次
验证失败	修复循环	verify-phase 失败时调用 debug
上下文溢出	截断 → 分块	加载超大文件时自动截断
依赖缺失	阻塞 → 跳过	前置任务未完成时等待
状态不一致	检测 → 修复	STATE.md 与实际情况不符时重建

7.2 恢复模式

当工作流执行中断时，GSD 支持多种恢复模式：

flowchart TD
    A[执行中断] --> B{中断原因?}
    B -->|上下文溢出| C[从 STATE.md 恢复]
    B -->|Agent 失败| D[重试或换 Agent]
    B -->|用户中断| E[保存状态等待恢复]
    B -->|系统错误| F[回滚到上一个检查点]
    C --> G[继续执行]
    D --> G
    E --> H[用户恢复]
    H --> G
    F --> G

---

八、工作流设计最佳实践

基于对 GSD 60+ 工作流的分析，总结出以下设计最佳实践：

8.1 DO（推荐）

1. 保持 Orchestrator 逻辑清晰：工作流只做决策和编排
2. 使用明确的阶段标记：每个阶段有清晰的开始和结束
3. 状态更新原子化：每个阶段完成后立即更新 STATE.md
4. 防御性设计：考虑各种边界情况和失败场景
5. 上下文最小化：只加载当前阶段需要的参考文档
6. 验证内置化：每个关键节点都有验证步骤

8.2 DON’T（避免）

1. 不要在工作流中嵌入业务逻辑：让 Agent 处理具体实现
2. 不要假设 Agent 会记住状态：明确的状态更新指令
3. 不要忽略错误处理：每个委托调用都需要错误处理
4. 不要过度设计：简单场景用简单工作流（quick/fast）
5. 不要忽视上下文预算：大工作流需要分块或引用

---

九、小结

GSD 的工作流层是整个框架的"中枢神经系统"。通过 Thin Orchestrator 模式，它将复杂的软件开发流程分解为可管理、可验证、可恢复的阶段。

核心设计模式回顾：

1. Thin Orchestrator：工作流只做编排，业务逻辑委托给 Agents
2. 状态机设计：文件系统作为状态存储，支持跨会话恢复
3. Agent 委托：直接委托、链式委托、并行 Wave 三种模式
4. 工作流组合：通过调用其他工作流实现复用
5. 渐进式披露：分层加载信息，优化上下文预算使用

这些模式不仅适用于 GSD，也可以借鉴到其他 AI Agent 系统的设计中。

---

下一篇预告： 第 22 篇《Agent 架构总览》——解析 GSD 33 个专业 Agent 的设计架构，包括 Agent 定义格式、frontmatter 规范、工具权限和模型配置。