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

---

execute-phase 工作流深度解析

在前面的文章中，我们已经了解了 GSD 的阶段规划（phase 的划分）和计划生成（plan-phase 如何将阶段目标拆解为可执行的 PLAN.md）。本文将深入解析 GSD 中体积最大、逻辑最复杂的工作流文件——execute-phase.md（约 69KB），揭开从"计划"到"代码"的执行黑箱。

---

一、execute-phase 概览：69KB 的编排巨兽

execute-phase.md 是 GSD 框架中最大的工作流文件。它不负责写任何一行业务代码，而是作为**编排器（Orchestrator）**存在，其核心设计哲学可以用一句话概括：

Orchestrator coordinates, not executes.
（编排器负责协调，不负责执行。）

这意味着 execute-phase 的定位非常清晰：

• 发现计划 → 扫描阶段目录下的所有 PLAN.md
• 分析依赖 → 提取 depends_on 和 files_modified 信息
• 分组 Wave → 按依赖关系将计划分批
• 派发 Agent → 为每个计划生成 gsd-executor 子 Agent
• 处理检查点 → 处理需要人工介入的中断点
• 收集结果 → 汇总 SUMMARY.md，更新 STATE.md

所有的实际编码工作都委派给了 gsd-executor Agent。这种"分层解耦"的设计让编排器保持精简（~10-15% 的上下文窗口占用），而将大量上下文留给执行器去消耗。

---

二、执行阶段的完整流程

execute-phase 的执行流程包含超过 15 个步骤，可分为六个主要阶段：

flowchart TD
    subgraph A["① 前置准备"]
        A1[parse_args
解析参数] --> A2[initialize
加载上下文] --> A3[check_blocking_antipatterns
检查阻塞反模式] --> A4[check_interactive_mode
交互模式检测]
    end

    subgraph B["② 阶段初始化"]
        B1[handle_branching
分支策略] --> B2[validate_phase
验证阶段] --> B3[discover_and_group_plans
发现并分组计划]
    end

    subgraph C["③ 执行引擎"]
        C1[cross_ai_delegation
Cross-AI 委托] --> C2[execute_waves
Wave 执行]
        C2 --> C3[checkpoint_handling
检查点处理]
    end

    subgraph D["④ 结果聚合"]
        D1[aggregate_results
聚合结果] --> D2[tdd_review_checkpoint
TDD 审查]
    end

    subgraph E["⑤ 质量门禁"]
        E1[code_review_gate
代码审查] --> E2[regression_gate
回归测试] --> E3[schema_drift_gate
Schema Drift] --> E4[codebase_drift_gate
代码库漂移]
    end

    subgraph F["⑥ 收尾与衔接"]
        F1[verify_phase_goal
目标验证] --> F2[update_roadmap
更新路线图] --> F3[offer_next
下一阶段]
    end

    A --> B --> C --> D --> E --> F

2.1 参数解析：灵活控制执行粒度

execute-phase 支持丰富的命令行参数，让用户可以精确控制执行范围：

参数	作用
--wave N	只执行第 N 个 Wave
--gaps-only	只执行 gap_closure 类型的计划
--cross-ai	强制所有计划通过 Cross-AI 执行
--no-cross-ai	禁用 Cross-AI 执行
--interactive	交互模式（内联执行，不派生子 Agent）
--auto	自动模式（自动推进到下一阶段）

2.2 运行时兼容性：不同 AI 平台的适配策略

GSD 被设计为跨平台运行，execute-phase 对运行时的差异做了显式处理：

• Claude Code：使用 Task(subagent_type="gsd-executor", ...) 同步派生子 Agent，阻塞等待完成
• Copilot：子 Agent 完成信号不可靠，默认回退到顺序内联执行
• 其他运行时：运行时检测 Task/task 工具的可用性，不可用则回退到顺序执行

这种"检测而非假设"的策略确保了 GSD 在不同 AI 平台间的可移植性。

2.3 阻塞反模式检查：防止历史问题重演

在正式开始任何工作之前，execute-phase 会检查当前阶段目录下是否存在 .continue-here.md 文件。如果存在且包含 severity: blocking 的反模式，执行将暂停，直到 Agent 能够回答三个问题：

1. 这是什么反模式？（用自己的话描述）
2. 它是如何表现的？（导致记录的具体失败）
3. 什么结构性机制（不是口头承诺）能防止它再次发生？

这是一个非常精巧的"学习型组织"机制——GSD 不会盲目重复已知会导致问题的路径。

---

三、任务分解策略：从计划到可执行单元

3.1 依赖分析

当 discover_and_group_plans 步骤运行时，它会通过 GSD SDK 一次性加载完整的计划清单：

PLAN_INDEX=$(gsd-sdk query phase-plan-index "${PHASE_NUMBER}")

返回的 JSON 包含每个计划的：

• id：计划标识
• wave：所属 Wave 编号
• autonomous：是否可自主执行（false 表示含检查点）
• objective：计划目标摘要
• files_modified：预期修改的文件列表
• task_count：任务数量
• has_summary：是否已完成（有 SUMMARY.md）

关键安全检查：如果指定了 --wave N，但仍有更低的 Wave 中存在未完成的计划，执行会立即停止并提示用户先完成前置 Wave。

3.2 Wave 分组与优先级排序

计划的 Wave 分组在 plan-phase 阶段就已经确定（通过 wave 字段），execute-phase 只是读取并验证这些分组。Wave 编号本质上就是拓扑排序后的执行层级：

• Wave 1：无外部依赖的基础计划
• Wave 2：依赖 Wave 1 输出的计划
• Wave 3+：以此类推

3.3 并行度控制：文件重叠检测

在每个 Wave 内部，如果 parallelization 配置为 true，计划会尝试并行执行。但在生成并行 Agent 之前，编排器会进行一项关键检查——文件修改重叠检测：

seen_files = {}
for each plan in wave:
    for each file in plan.files_modified:
        if file in seen_files:
            # 发现重叠！这两个计划不能并行执行
            mark_as_sequential_dependency(plan, seen_files[file])
        else:
            seen_files[file] = plan

如果两个计划共享任何一个 files_modified 中的文件，它们就被判定为存在隐式依赖，必须串行执行。这是防止并行执行导致代码冲突的第一道防线。

---

四、Wave 执行模型：分批、隔离、合并

4.1 Wave 的概念与作用

Wave 是 execute-phase 最核心的调度单位。它的设计灵感来源于 GPU 的 Wavefront 执行模型，但应用于软件工程的依赖调度：

flowchart LR
    subgraph W1["Wave 1: 基础设施"]
        P1["01-01: 项目脚手架"]
        P2["01-02: 数据库迁移"]
    end

    subgraph W2["Wave 2: 核心功能"]
        P3["01-03: 用户认证"]
        P4["01-04: API 路由"]
    end

    subgraph W3["Wave 3: 集成层"]
        P5["01-05: 前端对接"]
    end

    W1 --> W2 --> W3

Wave 的核心规则：

• Wave 内部：无依赖冲突的计划可并行执行
• Wave 之间：严格顺序执行，前一 Wave 完全完成后才能开始下一 Wave
• 跨 Wave 依赖：Wave N+1 的计划可以依赖 Wave N 的产出

4.2 执行模式：Worktree 隔离 vs 顺序执行

Wave 内的并行执行有两种模式，由 workflow.use_worktrees 配置控制：

模式 A：Worktree 隔离（默认启用）

每个并行执行的 gsd-executor Agent 在独立的 git worktree 中运行：

flowchart TD
    subgraph Main["主工作树"]
        MB["main branch"]
    end

    subgraph WT1["Worktree 1"]
        B1["branch: executor-01-01"]
        E1["gsd-executor
执行 01-01"]
    end

    subgraph WT2["Worktree 2"]
        B2["branch: executor-01-02"]
        E2["gsd-executor
执行 01-02"]
    end

    MB -->|checkout| B1
    MB -->|checkout| B2
    E1 -->|commits| B1
    E2 -->|commits| B2
    B1 -->|merge| MB
    B2 -->|merge| MB

Worktree 隔离的优势：

• 真正的并行：多个 Agent 同时修改文件不会互相干扰
• 安全回滚：某个 Agent 失败不会影响其他 Agent 的工作
• 干净合并：worktree 分支合并回 main 时，冲突在合并阶段统一处理

模式 B：顺序执行（Worktree 禁用或子模块项目）

当 USE_WORKTREES=false 时（或项目使用 git submodules），所有计划串行执行，即使 parallelization=true 也无效。此时每个 executor Agent 直接在主工作树上运行，逐个完成计划。

4.3 Worktree 合并：五道安全关卡

Worktree 合并是 execute-phase 中最复杂的操作之一，它包含五道安全关卡：

关卡	目的	失败处理
1. 预合并删除检查	防止 worktree 分支意外删除已追踪文件	阻止合并，要求人工审查
2. Orchestrator 文件保护	STATE.md / ROADMAP.md 始终以主分支为准	合并前快照备份，合并后恢复
3. 合并后批量删除审计	检测合并提交是否删除了 >5 个非 .planning/ 文件	默认阻止（ALLOW_BULK_DELETE=1 可绕过）
4. 文件复活检测	防止已删除文件被 worktree 重新引入	检测并移除复活文件
5. 未提交 SUMMARY 救援	防止 executor 漏提交 SUMMARY.md	自动补提交并重新合并

4.4 Post-Wave 测试门：跨计划冲突的最后防线

每个 worktree 内的 executor Agent 都会运行自测（Self-Check），但 Anthropic 的 Harness Engineering 研究发现一个盲区：Agent 会可靠地报告 Self-Check: PASSED，即使合并后的代码实际上存在冲突。

因此 execute-phase 在每个 Wave 合并后强制运行项目测试套件：

# 检测测试运行器并执行快速冒烟测试（超时 5 分钟）
timeout 300 bash -c "$TEST_CMD"

测试命令的解析优先级：

1. workflow.test_command 配置
2. Makefile 中的 test: 目标
3. Justfile / justfile
4. package.json → npm test
5. Cargo.toml → cargo test
6. go.mod → go test ./...
7. pyproject.toml / requirements.txt → pytest

如果测试失败，累计的 WAVE_FAILURE_COUNT 会递增，后续 Wave 会显示警告："⚠ Note: N prior wave(s) had test failures"。当失败超过 1 个 Wave 时，系统强烈建议"立即修复"，因为跨 Wave 的复合失败诊断难度呈指数级增长。

---

五、原子提交机制：每个任务都是一次独立事务

5.1 为什么需要原子提交

GSD 采用任务级原子提交策略——每个任务完成后立即提交，而不是等到整个计划完成后再统一提交。这种设计的价值在于：

1. 可追溯性：每个任务对应一个独立的 git commit，历史记录清晰
2. 可回滚：如果某个任务失败，只需回滚该任务的提交，不影响已完成的工作
3. 审计友好：代码审查可以精确到单个任务的变更范围
4. 并行安全：在 worktree 模式下，每个任务的提交都在独立分支上，合并时冲突粒度可控

5.2 提交粒度控制

gsd-executor Agent 的 <task_commit_protocol> 定义了精确的提交规范：

提交类型映射：

类型	场景
feat	新功能、端点、组件
fix	Bug 修复、错误纠正
test	仅测试变更（TDD RED 阶段）
refactor	代码清理，无行为变更
perf	性能优化，无行为变更
docs	仅文档变更
style	格式化、空格，无逻辑变更
chore	配置、工具、依赖

提交格式：

# 单仓库
git commit -m "feat(03-01): implement JWT authentication

- Add login endpoint with password validation
- Integrate jose library for token signing
- Add refresh token rotation mechanism
"

# 多仓库（monorepo）
gsd-sdk query commit-to-subrepo "feat(03-01): implement JWT authentication" \
  --files backend/src/auth.ts frontend/src/api.ts

关键约束：

• 绝不使用 git add . 或 git add -A——只 staging 与当前任务相关的文件
• 提交后删除检查：验证提交没有意外删除已追踪文件
• 未追踪文件检查：运行工具后检查新生成的未追踪文件，该提交的提交，该忽略的加 .gitignore

5.3 回滚策略

execute-phase 内置了多层回滚保护：

第一层：Worktree 级别的隔离

• 每个并行 Agent 在独立 worktree 中运行
• 某个 Agent 失败只会丢弃该 worktree 分支，不影响主分支

第二层：合并前的预检查

• 检测文件删除、批量变更等危险操作
• Orchestrator 文件（STATE.md / ROADMAP.md）始终以主分支为准

第三层：Destructive Git 禁令

• 在 worktree 中绝对禁止运行 git clean、git rm（未显式创建的文件）、git checkout -- .、git reset --hard
• 这些命令在 worktree 中会将 feature branch 上的已提交文件视为"未追踪"，导致数据丢失

第四层：恢复机制

• 如果执行过程中断，重新运行 /gsd:execute-phase {phase} 会自动跳过已有 SUMMARY.md 的计划，从第一个未完成的计划恢复
• STATE.md 跟踪最后完成的计划和当前 Wave 状态

---

六、与 gsd-executor Agent 的协作

execute-phase 作为编排器，与 gsd-executor Agent 的分工非常明确：

sequenceDiagram
    participant O as execute-phase
（编排器）
    participant SDK as GSD SDK
    participant E1 as gsd-executor #1
    participant E2 as gsd-executor #2
    participant Git as Git 仓库

    O->>SDK: gsd-sdk query init.execute-phase
    SDK-->>O: 阶段上下文、计划列表

    O->>O: 分析依赖、分组 Wave

    O->>Git: git worktree add wt1 branch-01
    O->>Git: git worktree add wt2 branch-02

    par Wave 1 并行执行
        O->>E1: Task(subagent_type="gsd-executor",
plan="01-01", isolation="worktree")
        E1->>E1: 读取 PLAN.md
        E1->>E1: 执行 Task 1 → commit
        E1->>E1: 执行 Task 2 → commit
        E1->>E1: 创建 SUMMARY.md
        E1->>Git: commits on branch-01
        E1-->>O: 完成（或检查点）
    and
        O->>E2: Task(subagent_type="gsd-executor",
plan="01-02", isolation="worktree")
        E2->>E2: 读取 PLAN.md
        E2->>E2: 执行 Task 1 → commit
        E2->>E2: 创建 SUMMARY.md
        E2->>Git: commits on branch-02
        E2-->>O: 完成（或检查点）
    end

    O->>O: 等待所有 Agent 完成
    O->>O: Post-wave 测试门
    O->>Git: merge branch-01 → main
    O->>Git: merge branch-02 → main
    O->>Git: 清理 worktree
    O->>SDK: 更新 STATE.md / ROADMAP.md

6.1 gsd-executor 的核心职责

gsd-executor 被定位为"GSD 计划执行者"，它的职责包括：

1. 加载执行上下文：通过 gsd-sdk query init.execute-phase 获取阶段配置
2. 读取 PLAN.md：解析 frontmatter、目标、任务列表、验证标准
3. 执行所有任务：按顺序处理 type="auto" 任务
4. 处理偏差：自动修复 bug、补充缺失功能、处理阻塞问题（Rules 1-3）
5. 暂停检查点：遇到 type="checkpoint:*" 时停止并返回结构化状态
6. 原子提交：每个任务完成后立即提交
7. 创建 SUMMARY.md：记录完成的工作、偏差、决策和指标
8. 更新 STATE.md：汇报进度、记录决策、更新会话信息

6.2 偏差处理：四大规则

executor 在执行过程中必然会发现计划中未预见的问题。GSD 用四条规则规范了偏差处理行为：

Rule 1：自动修复 Bug

• 触发条件：代码不按预期工作（逻辑错误、类型错误、空指针等）
• 处理：内联修复 → 补充测试 → 验证 → 继续任务 → 记录为偏差

Rule 2：自动补充缺失的关键功能

• 触发条件：缺少正确性、安全性或基本运行所必需的功能
• 示例：缺少输入验证、没有认证保护的路由、缺少数据库索引
• 关键功能 ≠ 新特性——它们是正确性要求

Rule 3：自动修复阻塞问题

• 触发条件：当前任务无法继续推进
• 示例：缺少依赖、错误类型、损坏的导入、环境变量缺失

Rule 4：询问架构变更

• 触发条件：修复需要重大的结构性修改
• 示例：新增数据库表（非列）、切换框架、重大 API 变更
• 处理：停止执行 → 返回检查点 → 等待用户决策

规则优先级：Rule 4 > Rules 1-3 > 不确定时按 Rule 4 处理

修复尝试上限：单个任务最多 3 次自动修复尝试，之后记录为"Deferred Issues"并继续下一个任务。

6.3 分析 paralysis 防护

这是一个非常人性化的设计——如果 executor 在执行过程中连续进行了 5 次以上 Read/Grep/Glob 调用而没有任何 Edit/Write/Bash 操作，它会强制停止并问自己：

"为什么我还没开始写代码？"然后要么立即写，要么明确报告"被什么信息阻塞"。

这个机制防止了 AI Agent 陷入"永远在读、永远不动手"的无限分析循环。

---

七、与 verify-phase 的衔接

execute-phase 的终点不是"代码写完了"，而是"阶段目标被验证通过了"。它与 verify-phase 的衔接通过多个"质量门禁"实现：

7.1 执行后、验证前的六道门禁

在 verify_phase_goal 步骤调用 gsd-verifier Agent 之前，execute-phase 会依次通过以下门禁：

flowchart LR
    A[execute_waves
Wave 执行完成] --> B[aggregate_results
结果聚合]
    B --> C[code_review_gate
代码审查]
    C --> D[close_parent_artifacts
关闭父阶段工件]
    D --> E[regression_gate
回归测试]
    E --> F[schema_drift_gate
Schema 漂移检测]
    F --> G[codebase_drift_gate
代码库漂移检测]
    G --> H[verify_phase_goal
目标验证]

门禁	类型	说明
Code Review Gate	建议性	自动触发代码审查 Skill，不阻塞流程
Close Parent Artifacts	条件性	仅对小数阶段（如 4.1）执行，更新父阶段 UAT 状态
Regression Gate	建议性	运行前期阶段的测试套件，检测跨阶段回归
Schema Drift Gate	可绕过	检测 Schema 文件变更后是否缺少数据库 push，防止假阳性验证
Codebase Drift Gate	非阻塞	检测执行后的结构漂移，内部错误必须穿透到 verify_phase_goal
Verify Phase Goal	强制性	验证阶段是否真正达成了 GOAL，而非仅仅完成了任务

7.2 验证结果的三种状态

gsd-verifier Agent 执行后会生成 VERIFICATION.md，其 status 字段有三种可能：

状态	含义	后续动作
passed	所有 must-haves 已验证通过	更新 ROADMAP，标记阶段完成
human_needed	自动化检查通过，但需要人工验证	创建 HUMAN-UAT.md，等待用户确认
gaps_found	发现缺口	提供 gap-closure 路径：/gsd:plan-phase {X} --gaps

7.3 自动推进链（Auto-Advance Chain）

当使用 --auto 参数或 workflow.auto_advance 配置为 true 时，execute-phase 在验证通过后会自动执行 transition 工作流，无缝衔接到下一阶段：

╔══════════════════════════════════════════╗
║  AUTO-ADVANCING → TRANSITION             ║
║  Phase X verified, continuing chain      ║
╚══════════════════════════════════════════╝

这种设计让 GSD 可以在无人值守的情况下连续执行多个阶段——从规划到执行到验证，全自动流转。

---

八、交互模式与检查点机制

8.1 交互模式：低 Token 消耗的精准控制

当用户传入 --interactive 参数时，execute-phase 切换到交互模式：

• 不派生子 Agent——所有计划由编排器内联顺序执行
• 计划级控制：每个计划开始前询问用户：执行 / 先审阅 / 跳过 / 停止
• 任务级暂停：每个任务完成后暂停，用户可随时介入

这种模式的优势：

• Token 消耗大幅降低（无子 Agent 开销）
• 用户可以在早期发现错误，节省昂贵的验证周期
• 适合小规模阶段、Bug 修复、验证缺口修复、学习 GSD

8.2 检查点协议：人机协作的精确中断

对于 autonomous: false 的计划（含 checkpoint:* 任务），gsd-executor 会在检查点处停止并返回结构化消息：

## CHECKPOINT REACHED

**Type:** human-verify
**Plan:** 03-03
**Progress:** 2/3 tasks complete

### Completed Tasks
| Task | Name | Commit | Files |
| ---- | ---- | ------ | ----- |
| 1 | 搭建布局框架 | a1b2c3d | src/layout/... |

### Current Task
**Task 3:** Dashboard 组件集成
**Status:** awaiting verification
**Blocked by:** 需要用户确认视觉效果

### Checkpoint Details
[已构建内容、验证步骤、预期行为]

### Awaiting
[用户需要提供/执行的操作]

编排器收到检查点后呈现给用户，用户回复后重新生成一个 continuation agent（而非 resume），因为 resume 依赖内部序列化，在并行工具调用场景下不可靠。新 Agent 会验证之前的提交存在，然后从断点继续执行。

---

九、Cross-AI 委托：跨 AI 平台的任务分发

execute-phase 支持将特定计划委托给外部 AI 运行时执行，这是 GSD 的"跨 AI 协作"能力的体现：

激活条件：

• 计划 frontmatter 中 cross_ai: true + 配置 workflow.cross_ai_execution: true
• 或 --cross-ai 强制全部计划走外部 AI
• 或 --no-cross-ai 完全禁用

执行流程：

1. 从 PLAN.md 提取 <objective> 和 <tasks> 部分
2. 附加 PROJECT.md 上下文
3. 通过 stdin 将任务提示写入外部命令：

   echo "$TASK_PROMPT" | timeout "${CROSS_AI_TIMEOUT}s" ${CROSS_AI_CMD}

4. 验证返回的 SUMMARY.md 结构有效性
5. 成功则更新 STATE.md，失败则提供 retry / skip / abort 选项

这种机制让 GSD 可以整合多个 AI 系统的优势——例如用 Claude 做规划，用其他模型做特定类型的实现任务。

---

十、关键设计洞察

通过深入分析 execute-phase.md 的 69KB 代码，可以提炼出几个关键的设计洞察：

10.1 "防御性编排"哲学

execute-phase 几乎在每一个关键操作后都有安全检查：

• worktree 合并前检查文件删除
• 合并后检查批量删除
• 提交后检查意外删除
• 测试失败后暂停跟踪更新
• Schema 变更后检查数据库同步

这不是过度工程，而是生产级系统对"AI Agent 会犯错"这一现实的务实回应。

10.2 "信号 vs 事实"的区分

execute-phase 明确区分了"Agent 报告完成"（信号）和"实际工作产物存在"（事实）：

# 完成信号可能丢失（特别是 Copilot 运行时），所以用文件系统验证
SUMMARY_EXISTS=$(test -f "{phase_dir}/{plan}-SUMMARY.md" && echo "true" || echo "false")
COMMITS_FOUND=$(git log --oneline --all --grep="{phase}-{plan}" --since="1 hour ago" | head -1)

如果 SUMMARY.md 存在且提交记录找到，即使 Agent 报告失败（比如 classifyHandoffIfNeeded 运行时错误），也视为成功。这种"以事实为准"的设计避免了因信号丢失导致的不必要重试。

10.3 上下文预算意识

execute-phase 对上下文窗口大小做了自适应处理：

• < 200K 模型：executor 提示中省略冗长的示例和边界情况列表，按需通过 @reference 加载
• >= 500K 模型：传递更丰富的上下文（前期 Wave 的 SUMMARY、CONTEXT.md、RESEARCH.md），实现跨阶段感知

这种"上下文感知"的提示工程让 GSD 能在不同能力等级的模型上都能有效运行。

---

总结

execute-phase.md 是 GSD 框架的"发动机"——它不写代码，但决定了代码如何被写出来。通过 Wave 调度、Worktree 隔离、原子提交、六道质量门禁和检查点协议，它构建了一个可靠的 AI 软件工程执行管道。

其核心设计可以概括为三句话：

1. 编排器协调，执行器实现——分工明确，各尽其责
2. Wave 顺序执行，Wave 内并行加速——在依赖安全和执行效率间取得平衡
3. 信号不可靠，事实才可信——用文件系统和 git 状态验证代替 Agent 的自报告

---

下一篇预告： 第 15 篇《plan-phase 工作流深度解析》

plan-phase 是 GSD 的’大脑’——它负责将阶段目标拆解为具体的 PLAN.md 文件，定义任务、依赖、验证标准和检查点。 敬请期待。