Executor 与 Debugger

📑 目录

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


Executor 与 Debugger

在 GSD 的 Agent 生态中,33 个专业 Agent 各司其职。但如果要评选"最忙碌"和"最关键"的两个角色,非 gsd-executorgsd-debugger 莫属。前者是代码产出的引擎,后者是问题诊断的雷达。本文将分别深入解析这两个 Agent 的定义文件(gsd-executor.md 约 25KB,gsd-debugger.md 约 46KB),揭示它们的工作方式、协作协议和失败恢复机制。


一、gsd-executor 深度解析:计划执行者

gsd-executor.md 是 GSD 中定义计划执行 Agent 的核心文件。尽管只有 25KB(相比 execute-phase.md 的 69KB 更紧凑),但它承载了从"计划文本"到"可运行代码"的全部执行语义。

1.1 Agent 角色定义与工作方式

gsd-executor 的 Agent 定义遵循 GSD 的标准 YAML frontmatter 格式:

---
name: gsd-executor
description: |
  执行 GSD 计划的专用 Agent。负责读取 PLAN.md,按顺序完成任务,
  处理执行偏差,执行原子提交,并生成 SUMMARY.md。
  具备代码生成、测试运行、偏差修复和检查点暂停能力。
tools: Read, Write, Edit, Bash, Grep, Glob, Task
---

核心定位gsd-executor 不是通用编码助手,而是计划绑定的执行器。它的上下文被严格限制在单个 Plan 的范围内——只读取分配给它的 PLAN.md 和必要的项目上下文,不越权查看其他 Plan 或全局路线图。

工作方式的关键约束

约束维度具体规则设计意图
上下文边界仅读取当前 Plan + 依赖 Plan 的 SUMMARY.md防止 Context Rot,聚焦当前任务
工具权限git merge / git rebase 权限版本控制操作由 Orchestrator 负责
并行模式Wave 内并行,Wave 间隔离通过 worktree 实现物理隔离
输出产物SUMMARY.md + git commits可验证、可追溯的执行结果

1.2 任务执行策略:从 PLAN.md 到代码

gsd-executor 的核心执行流程可以概括为**"读取 → 分析 → 执行 → 验证 → 提交"**的五步循环:

flowchart TD
    subgraph A["① 加载上下文"]
        A1[读取 PLAN.md
frontmatter + tasks] --> A2[加载 init.execute-phase
项目配置与约束] --> A3[读取依赖 Plan 的
SUMMARY.md] end subgraph B["② 任务预处理"] B1[过滤已完成任务] --> B2[识别 checkpoint 任务
标记暂停点] --> B3[按 wave 排序] end subgraph C["③ 执行循环"] C1{还有任务?} -->|是| C2[读取当前 task 描述] C2 --> C3[分析所需文件
Read/Grep/Glob] C3 --> C4[执行代码变更
Write/Edit/Bash] C4 --> C5[运行验证
测试/Self-Check] C5 --> C6{验证通过?} C6 -->|是| C7[原子提交] C6 -->|否| C8[偏差处理
Rules 1-4] C8 --> C5 C7 --> C1 C1 -->|否| D1 end subgraph D["④ 收尾"] D1[生成 SUMMARY.md] --> D2[更新 STATE.md] --> D3[返回 Orchestrator] end A --> B --> C --> D

任务分类处理

PLAN.md 中的每个任务都有 type 字段,gsd-executor 对不同类型的任务采取不同的处理策略:

任务类型处理方式示例
auto自主执行,无需人工确认"实现 UserService 的 CRUD 方法"
checkpoint:human-verify执行到此处暂停,等待人工确认"完成后请确认 UI 效果"
checkpoint:human-input需要用户提供信息后才能继续"输入第三方 API Key"
checkpoint:external等待外部系统事件"等待 CI 通过"
gap-closure修复验证阶段发现的缺口"补充缺失的输入校验"

1.3 代码生成规范:质量内建

gsd-executor 不是"写完就跑"的代码生成器。它的提示词中内嵌了一套代码生成规范,确保产出代码的质量底线:

规范 1:防御性编程

  • 所有外部输入必须验证(null check、类型检查、范围检查)
  • 所有异步操作必须有错误处理
  • 所有资源操作必须有清理逻辑(try/finally 或等效模式)

规范 2:测试伴随

  • 每个 feat 任务必须伴随至少一个测试
  • 测试优先运行,确保 RED → GREEN → REFACTOR 的 TDD 节奏
  • 测试文件与源码文件保持同级目录结构

规范 3:文档同步

  • 修改公共 API 时必须同步更新注释/JSDoc
  • 修改配置项时必须同步更新 README 或相关文档
  • 复杂的业务逻辑必须添加行内注释说明"为什么"而非"做什么"

规范 4:最小变更原则

  • 每个任务只修改与目标直接相关的文件
  • 禁止"顺手重构"不相关代码——这属于新 Plan 的范畴
  • 如需重构支撑代码,记录为偏差并在 SUMMARY.md 中说明

1.4 原子提交机制:任务级事务

gsd-executor 的原子提交机制在 gsd-14 中已经详细介绍过,本文从 Agent 内部视角补充几个关键细节:

提交前检查清单(内置于 executor 提示词):

## 提交前自检

- [ ] 本次变更只包含当前任务相关文件
- [ ] 没有意外删除已追踪文件(`git status` 检查)
- [ ] 新生成的未追踪文件已处理(提交或加入 .gitignore)
- [ ] 测试通过(如适用)
- [ ] 提交信息遵循 `<type>(<plan-id>): <description>` 格式

提交信息模板

# 单文件变更
feat(03-01): implement password hashing with bcrypt

- Add bcrypt dependency to package.json
- Implement hashPassword() with salt rounds = 12
- Add timing-safe comparison for password verification

# 多文件跨模块变更
fix(04-02): resolve race condition in WebSocket connection

- Add mutex lock to connection handler
- Implement exponential backoff for reconnection
- Update connection test to cover concurrent access

关键约束gsd-executor显式禁止使用以下危险操作:

  • git add .git add -A —— 必须显式指定文件
  • git commit --amend —— 避免修改已发布历史
  • git rebase / git reset --hard —— 版本控制操作归 Orchestrator 管辖
  • git clean -fd —— 防止删除未追踪的 worktree 文件

1.5 与 execute-phase 工作流的关系

gsd-executorexecute-phase 的关系是**"被调用者"与"调用者"**的关系,但它们的协作协议远比简单的 RPC 复杂:

sequenceDiagram
    participant O as execute-phase
(Orchestrator) participant WT as Git Worktree participant E as gsd-executor participant P as PLAN.md participant S as SUMMARY.md O->>WT: git worktree add
branch: executor-{phase}-{plan} O->>E: Task(subagent_type="gsd-executor",
plan_id="03-01", phase_dir="...") E->>P: 读取 PLAN.md E->>E: 解析 frontmatter
提取 tasks / depends_on / files_modified loop 每个 auto 任务 E->>E: 执行代码变更 E->>WT: git add E->>WT: git commit -m "type(plan): description" E->>E: 运行 Self-Check end alt 遇到 checkpoint E->>S: 生成部分 SUMMARY.md E-->>O: 返回 checkpoint 状态
(含已完成 tasks 和暂停原因) else 全部完成 E->>S: 生成完整 SUMMARY.md E->>WT: git push / 准备合并 E-->>O: 返回成功状态 end O->>O: 验证 SUMMARY.md 存在 O->>O: 验证 commits 存在 O->>WT: git worktree merge → main

上下文注入协议

execute-phase 生成 executor Agent 时,它会注入以下上下文(按优先级排序):

  1. PLAN.md(必需):当前 Plan 的完整内容
  2. PROJECT.md(按需):项目全局约束和架构决策
  3. 依赖 SUMMARY.md(自动):depends_on 列出的前置 Plan 的执行结果
  4. CONTEXT.md(如有):阶段级上下文和灰色区域决策
  5. RESEARCH.md(如有):相关领域研究结果

这种"按需注入"策略确保 executor 拥有足够信息完成当前任务,同时不被无关上下文干扰。


二、gsd-debugger 深度解析:科学调试者

如果说 gsd-executor 是 GSD 的"右手"(负责创造),那么 gsd-debugger 就是 GSD 的"左手"(负责修复)。gsd-debugger.md 的体积达到 46KB,几乎是 executor 的两倍,这反映出调试比执行更复杂——调试需要科学方法、假设验证、证据收集和根因推断。

2.1 调试策略:科学方法的四步循环

gsd-debugger 的核心调试策略基于科学方法(Scientific Method),而非传统的"试错法"。它的提示词中明确嵌入了以下四步循环:

flowchart TD
    subgraph A["① 观察与假设"]
        A1[收集症状
错误信息/日志/行为描述] --> A2[形成初步假设
"可能的原因是..."] end subgraph B["② 预测与实验"] B1[基于假设做出预测
"如果假设成立,那么..."] --> B2[设计最小化实验
验证或证伪假设] end subgraph C["③ 验证与迭代"] C1[运行实验
观察实际结果] --> C2{结果与预测一致?} C2 -->|是| C3[假设得到支持
继续深入] C2 -->|否| C4[假设被证伪
记录排除原因] C3 --> C5{根因已定位?} C4 --> A2 C5 -->|是| D1 C5 -->|否| B1 end subgraph D["④ 修复与验证"] D1[制定修复方案] --> D2[实施最小化修复] --> D3[验证修复效果
回归测试] --> D4[记录根因与修复] end A --> B --> C --> D

与传统调试的区别

维度传统 AI 调试gsd-debugger 科学方法
假设管理无结构化跟踪显式记录当前假设和已排除假设
证据链凭直觉跳转每个结论必须有观察证据支撑
实验设计随机尝试修改最小化实验,每次只改一个变量
失败恢复容易陷入循环假设被证伪后必须切换方向
知识沉淀调试完就忘记录到会话文件,可复用

2.2 会话管理机制:三层 Agent 架构

gsd-debugger 不直接面向用户,而是通过 三层 Agent 架构 参与调试流程:

flowchart TD
    subgraph UserLayer["用户层"]
        U[用户输入
/gsd-debug <问题描述>] end subgraph OrchestratorLayer["编排层"] O[/gsd-debug 命令
主上下文] O -->|收集症状| O1[期望行为?]<-->O2[实际行为?]<-->O3[错误信息?]<-->O4[复现步骤?] O -->|创建会话| S[生成 slug
创建 .planning/debug/{slug}.md] end subgraph SessionManagerLayer["会话管理层"] SM[gsd-debug-session-manager
管理检查点/续接循环] SM -->|派生调查| SM1[第一轮调查] SM -->|检查点| SM2[保存会话状态] SM -->|续接| SM3[生成 continuation
Agent 继续调查] end subgraph InvestigatorLayer["调查层"] D[gsd-debugger
使用科学方法调查] D -->|返回结果| R{ROOT CAUSE FOUND?} R -->|否| SM R -->|是| RC[提取 specialist_hint
分派专家修复] end U --> O --> SM --> D --> R

各层职责详解

层级Agent职责上下文策略
调度层主上下文(Orchestrator)收集症状、创建会话文件、管理用户交互保留在主上下文
执行层gsd-debug-session-manager管理调试检查点/续接循环、决策何时继续调查独立 Agent, fresh context
调查层gsd-debugger使用科学方法执行具体调查任务独立 Agent, fresh context

这种分层设计的精妙之处在于:调试调查消耗大量上下文(阅读日志、追踪调用链、分析代码),如果放在主上下文中,会迅速挤占用户的对话空间。通过派生独立 Agent,每次调查都能获得全新的 200K+ tokens 上下文窗口。

2.3 持久化调试会话

gsd-debugger 的一个核心创新是会话持久化——调试过程被完整记录到文件系统,支持跨会话续接。

会话文件结构.planning/debug/{slug}.md):

---
status: investigating
slug: auth-race-condition-20260424
trigger: "用户登录时偶尔返回 500 错误,刷新后正常"
created: 2026-04-24T10:00:00Z
updated: 2026-04-24T10:30:00Z
session_count: 3
---

## Current Focus
- hypothesis: "JWT 令牌验证与时区处理存在 race condition"
- test: "在验证逻辑前后添加时间戳日志,观察 500 错误时的 token 状态"
- expecting: "错误发生时 token 的 exp 字段与服务器时间存在 >1s 偏差"
- next_action: "检查 auth.middleware.ts 第 45-60 行的时间比较逻辑"

## Evidence
- timestamp: 2026-04-24T10:05:00Z
  observation: "错误日志显示 TokenExpiredError,但 token 刚生成 2 分钟"
  source: server.log
  
- timestamp: 2026-04-24T10:15:00Z
  observation: "服务器使用 UTC,客户端使用本地时区,但转换逻辑缺失"
  source: auth.middleware.ts:52

## Eliminated
- hypothesis: "数据库连接池耗尽导致 500"
  reason: "错误发生时数据库连接数正常,且错误信息明确是 TokenExpiredError"
  eliminated_at: 2026-04-24T10:10:00Z

## Resolution
- root_cause: "待定位"
- fix: "待实施"
- verification: "待验证"

持久化的价值

  1. 跨会话续接:当上下文重置或对话中断后,新 Agent 可以读取会话文件,从断点继续调查
  2. 知识积累:已排除的假设不会重复验证,节省时间和 token
  3. 审计追踪:调试过程完整记录,便于事后复盘和学习
  4. 并行调查:多个调试会话可以同时进行(如调查不同 Bug)

2.4 子命令详解:list / status / continue / --diagnose

/gsd-debug 命令支持丰富的子命令,这些命令由 Orchestrator 层直接处理,不消耗 debugger Agent 的上下文:

# 列出所有活跃调试会话
/gsd-debug list

# 查看特定会话的完整状态
/gsd-debug status auth-race-condition-20260424

# 恢复指定会话的调试(生成 continuation Agent)
/gsd-debug continue auth-race-condition-20260424

# 仅诊断不修复(返回结构化根因报告)
/gsd-debug --diagnose "登录时偶尔 500 错误"

# 标准调试流程(诊断 + 修复)
/gsd-debug "登录时偶尔 500 错误,刷新后正常"

各子命令的实现逻辑

子命令处理层级是否生成 Agent作用
listOrchestrator扫描 .planning/debug/ 目录,输出会话摘要表
status <slug>Orchestrator读取指定会话文件,格式化输出当前状态
continue <slug>Orchestrator → Session Manager读取会话文件 → 生成 continuation Agent → 续接调查
--diagnoseOrchestrator → Session Manager → Debugger完整调查但不实施修复,输出结构化根因报告
无子命令(默认)Orchestrator → Session Manager → Debugger完整调查 + 实施修复

--diagnose 模式的特殊价值

--diagnose 模式只返回根因分析,不修改任何代码。这在以下场景特别有用:

  • 需要人工确认修复方案后再实施
  • 问题涉及架构变更(需走 Rule 4 流程)
  • 调试结果需要写入知识库或分享给团队
  • 对生产环境问题进行"只读调查"

2.5 专家分派机制

gsd-debugger 定位到根因后,它会返回一个 specialist_hint 字段,Orchestrator 据此分派对应的专家 Agent 执行修复:

flowchart LR
    D[gsd-debugger
返回 ROOT CAUSE] --> H{specialist_hint} H -->|typescript-expert| E1[TypeScript 专家] H -->|swift-concurrency| E2[Swift 并发专家] H -->|sql-optimization| E3[SQL 优化专家] H -->|react-performance| E4[React 性能专家] H -->|security| E5[安全专家] H -->|none| E6[gsd-executor
通用修复] E1 --> R[实施修复] E2 --> R E3 --> R E4 --> R E5 --> R E6 --> R

专家 Agent 的修复约束

  • 必须遵循 gsd-executor 的原子提交规范
  • 修复范围仅限于根因涉及的文件
  • 修复后必须运行相关测试验证
  • 修复结果记录到原调试会话的 Resolution 部分

三、Executor 与 Debugger 的协作关系

在 GSD 的执行管道中,gsd-executorgsd-debugger 并非孤立工作,它们通过 Orchestrator 协调,形成**"执行 → 失败 → 诊断 → 修复 → 重新执行"**的闭环:

flowchart TD
    subgraph Execute["执行阶段"]
        E1[execute-phase
Orchestrator] --> E2[spawn gsd-executor] E2 --> E3[执行任务队列] end subgraph Fail["失败检测"] E3 --> F1{任务成功?} F1 -->|测试失败| F2[记录失败信息] F1 -->|编译错误| F2 F1 -->|运行时异常| F2 F1 -->|检查点暂停| F3[checkpoint 处理] end subgraph Debug["调试阶段"] F2 --> D1[Orchestrator 决策] D1 -->|自动修复尝试| D2[gsd-executor
Rule 1-3 偏差处理] D1 -->|复杂问题| D3[spawn gsd-debugger] D3 --> D4[科学方法调查] D4 --> D5[ROOT CAUSE FOUND] end subgraph Fix["修复阶段"] D5 --> X1{修复类型} X1 -->|简单修复| X2[gsd-executor 实施] X1 -->|领域专家| X3[specialist Agent] X2 --> X4[原子提交] X3 --> X4 end subgraph Resume["恢复执行"] X4 --> R1[验证修复] R1 -->|通过| R2[恢复任务队列] R1 -->|失败| D3 R2 --> E3 end F3 --> E1

协作的关键协议点

  1. 失败信息传递:executor 的失败日志、错误堆栈、相关文件路径会被完整传递给 debugger
  2. 修复范围约定:debugger 定位根因,但不直接修改代码;修复由 executor 或 specialist Agent 执行,确保遵循原子提交规范
  3. 会话关联:如果调试是由某个 Plan 的执行失败触发的,调试会话文件会记录关联的 plan_idphase,修复后自动恢复该 Plan 的执行
  4. 状态同步:修复完成后,debugger 更新会话状态为 resolved,executor 更新 SUMMARY.md 记录偏差和修复过程

四、执行失败时的处理流程

gsd-executor 在执行过程中遇到失败时,GSD 建立了一套分层防御的失败处理机制:

4.1 第一层:Executor 自治修复(Rules 1-3)

在失败发生的瞬间,gsd-executor 首先尝试自治修复,无需外部介入:

规则失败类型修复策略尝试上限
Rule 1逻辑 Bug(代码不按预期工作)内联修复 → 补充测试 → 验证3 次
Rule 2缺失关键功能(安全性/正确性必需)补充实现 → 验证3 次
Rule 3阻塞问题(依赖缺失、导入错误等)修复环境/依赖 → 重试3 次

分析 paralysis 防护:如果 executor 在执行过程中连续进行了 5 次以上 Read/Grep/Glob 调用而没有任何 Edit/Write/Bash 操作,它会强制停止并自问自己:"为什么我还没开始写代码?" 这个机制防止了 AI Agent 陷入"永远在读、永远不动手"的无限分析循环。

4.2 第二层:调试 Agent 介入(Rule 4 或 3 次失败)

当自治修复达到尝试上限,或失败类型属于 Rule 4(需要架构变更)时,执行权转交给 gsd-debugger

flowchart LR
    A[gsd-executor
Rule 1-3 失败] --> B{失败次数 >= 3?} B -->|是| C[触发 gsd-debugger] B -->|否| D{Rule 4?} D -->|是| C D -->|否| E[继续重试] E --> B C --> F[科学方法调查] F --> G{根因类型} G -->|简单修复| H[gsd-executor 修复] G -->|领域问题| I[specialist Agent] G -->|架构问题| J[返回 checkpoint
等待用户决策]

触发 debugger 的典型场景

  • 同一个任务连续 3 次测试失败,且失败原因不同(暗示根因未定位)
  • 编译错误涉及多个文件的循环依赖
  • 运行时异常与计划描述的预期行为严重不符
  • 需要引入新的依赖或修改数据库 Schema

4.3 第三层:人工介入(Checkpoint 或 Rule 4)

当 debugger 判断问题需要架构级变更,或修复方案存在重大风险时,执行流程会暂停并创建 checkpoint:

## CHECKPOINT: DEBUG RESOLUTION REQUIRED

**Plan:** 03-02
**Task:** 实现 OAuth 2.0 登录
**Status:** blocked

### Problem Summary
调试发现:当前项目使用的 auth 库版本(v1.x)不支持 PKCE 扩展,
而需求明确要求支持移动端 OAuth。需要升级至 v2.x,但 v2.x 有 Breaking Changes。

### Root Cause
- gsd-debugger 调查结论:依赖版本约束导致功能无法实现
- specialist_hint: "dependency-migration"

### Options
1. **升级 auth 库至 v2.x**(推荐)—— 需要修改 5 个文件的 API 调用
2. **切换至其他 auth 库** —— 需要重新评估和测试
3. **降低需求** —— 与产品经理确认是否必须支持移动端

### Awaiting
用户决策:选择上述选项之一,或提供其他方案。

4.4 第四层:Wave 级失败处理

如果某个 Plan 的失败影响到整个 Wave 的执行(如 worktree 合并冲突、跨计划依赖断裂),execute-phase Orchestrator 会启动Wave 级恢复

  1. 隔离失败 Plan:将该 Plan 从当前 Wave 移除,标记为 failed
  2. 继续其他 Plan:不影响 Wave 内其他 Plan 的合并和验证
  3. 失败 Plan 重试:稍后单独 spawn executor 重试,或降级为顺序执行
  4. 必要时 spawn debugger:如果重试仍失败,启动调试流程
  5. 记录反模式:如果失败具有共性,写入 .continue-here.md 供后续阶段参考

五、关键设计洞察

通过深入分析 gsd-executor.mdgsd-debugger.md,可以提炼出几个贯穿 GSD Agent 设计的核心洞察:

5.1 "执行与调试分离"的架构价值

GSD 没有让一个 Agent 既写代码又修 Bug,而是将这两个职责分离。这种分离的价值:

  • 上下文隔离:调试调查不会污染执行上下文,反之亦然
  • 专业化:executor 专精"如何正确实现",debugger 专精"如何定位问题"
  • 并行化:多个 executor 并行执行时,debugger 可以独立调查失败 Plan
  • 可替换性:未来可以单独升级 debugger 的科学方法算法,不影响 executor

5.2 "文件即协议"的协作模式

Executor 和 Debugger 之间的协作不依赖内存状态或 RPC 调用,而是通过文件系统实现:

协议文件生产者消费者作用
PLAN.mdPlannerExecutor执行指令
SUMMARY.mdExecutorVerifier / Orchestrator执行结果
.planning/debug/*.mdDebuggerSession Manager / User调试状态
STATE.mdOrchestrator所有 Agent全局状态

这种设计使得 Agent 之间的协作人类可读、机器可解析、版本可追踪

5.3 "上下文预算"驱动的 Agent 粒度

gsd-debuggergsd-executor 大将近一倍(46KB vs 25KB),不是因为调试代码更多,而是因为调试需要更丰富的策略指导(科学方法步骤、假设管理、证据收集)。GSD 通过 Agent 粒度控制来管理上下文预算:

  • executor 精简:只保留执行必需规范,省略示例和边界情况(大模型通过 @reference 按需加载)
  • debugger 详尽:保留完整的科学方法流程和决策树,因为调试的容错空间更小

总结

gsd-executorgsd-debugger 是 GSD 执行管道的双核心。Executor 负责将计划转化为代码,通过原子提交、偏差处理和检查点协议确保执行质量;Debugger 负责用科学方法定位问题,通过会话持久化、三层架构和专家分派实现高效诊断。

它们的关系可以概括为三句话:

  1. Executor 创造,Debugger 修复——职责分离,各专其业
  2. 文件即协议,状态即持久化——通过文件系统实现跨 Agent 协作
  3. 自治优先,人工兜底——Rule 1-3 自动处理,Rule 4 和复杂问题人工决策

在下一篇文章中,我们将继续探索 GSD 的 Agent 系统,解析另外两位质量守护者——Verifier 与 Code-Reviewer,看看 GSD 如何在代码写完之后,确保它"写对了"且"写得够好"。

下一篇预告:第 25 篇《Verifier 与 Code-Reviewer》

Verifier 是 GSD 的"质检员"——它不写代码,只验证阶段目标是否真正达成。Code-Reviewer 是 GSD 的"审计员"——它用独立视角审查 AI 写的代码,发现人眼和自动化工具都容易遗漏的问题。我们将深入分析它们的验证策略、审查深度控制、与工作流的质量门禁衔接,以及 GSD 如何构建"AI 写、AI 审、AI 验"的完整质量闭环。敬请期待!