get-shit-done 里程碑全流程自动驾驶：深入解读 gsd:autonomous 自主执行工作流

get-shit-done（GSD）是一套面向 Claude Code 等 Agent 运行时的 meta-prompting 与规格驱动开发（spec-driven development）系统。本文聚焦其核心命令 gsd:autonomous：一条让 Agent 从“discuss → plan → execute”逐阶段跑完整个里程碑，直至审计、完成、清理全部收尾的自动驾驶命令。读完本文，你将掌握 --from / --to / --only / --interactive 四种运行模式的使用时机、其背后的 phase 发现与阻塞处理机制、灰度决策（grey area）的批量化智能讨论策略，以及如何用配置文件收紧或放开自动执行边界。

命令概览：一条命令接管整个里程碑

gsd:autonomous 的命令定义位于 commands/gsd/autonomous.md，其 frontmatter 明确给出：

• description：Run all remaining phases autonomously — discuss→plan→execute per phase
• argument-hint：[--from N] [--to N] [--only N] [--interactive]
• requires：[cleanup, phase, progress] —— 意味着执行前必须已安装/可用这三条配套命令；
• allowed-tools：仅向该命令授权的工具集合，包括 Read、Write、Bash、Glob、Grep、AskUserQuestion、Agent，测试 tests/autonomous-allowed-tools.test.cjs 会对齐校验这一白名单。

一句话概括其职责：对里程碑中每一个未完成阶段依次执行 discuss → plan → execute，并且只在两类场景暂停向用户提问——需要用户拍板（灰度决策接受/覆盖、阻塞项、人工验证请求）。在阶段推进层面，它使用 Skill() 扁平调用各阶段命令，并在每个阶段结束后重新读取 ROADMAP.md，以捕获执行中途被动态插入的（小数字）阶段。

工作流的完整实现位于 get-shit-done/workflows/autonomous.md，而命令文档中的 execution_context 还引用了两份安装态材料：autonomous 工作流本体 与 UI 品牌规范（后者服务于前端阶段的 UI-SPEC 生成与 UI review）。

四种可选参数的含义与组合语义

参数	作用	边界行为
--from N	从第 N 个阶段（含小数阶段如 5.1）开始执行，而不是从第一个未完成阶段开始	使用数值比较过滤 number < N 的阶段
--to N	执行到第 N 个阶段完成后停止（halt，不再前进到下一阶段）	过滤掉 number > N 的阶段；未跑完整个里程碑则跳过 audit/complete/cleanup
--only N	只执行第 N 个阶段（单阶段模式）	内部同时把 --from N 设为该值；跳过整个生命周期（lifecycle）步骤
--interactive	discuss 内联执行并真正向用户提问，plan/execute 则以后台 Agent 方式派发	见下方“管道式并行”章节

五个执行阶段（Workflow Steps）解析

Step 1 初始化：解析参数并校验前置状态

工作流首先用 shell 从 $ARGUMENTS 中解析各 flag，例如：

FROM_PHASE=""
if echo "$ARGUMENTS" | grep -qE '\-\-from\s+[0-9]'; then
  FROM_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-from\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
fi

注意两个约定：设置 --only 时会顺带把 FROM_PHASE 指向同一数值以复用既有过滤逻辑；设置 --interactive 后，discuss 内联提问、plan/execute 派发为后台代理，主上下文只累积 discuss 会话，从而保持轻量。

随后通过里程碑级初始化查询引导（bootstrap）：

INIT=$(gsd-sdk query init.milestone-op)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

该查询由 sdk/src/query/init.ts 支撑，返回 milestone_version、milestone_name、phase_count、completed_phases、roadmap_exists、state_exists、commit_docs 等字段。若 roadmap_exists 或 state_exists 为 false，工作流会直接报错并提示“先运行 /gsd:new-milestone”。

启动横幅（banner）会展示里程碑版本与名称、总阶段数、已完成数；若存在各 flag，还会追加提示行，例如单阶段模式（Single phase mode: Phase ${ONLY_PHASE}）、--to 停止点、--interactive 的交互说明。

Step 2 阶段发现：ROADMAP 驱动的过滤与排序

工作流调用 gsd-sdk query roadmap.analyze 读取 ROADMAP，解析 phases 数组后执行统一过滤：

1. 仅保留未完成阶段：disk_status !== "complete" 或 roadmap_complete === false；
2. 应用 --from N：剔除 number < N；
3. 应用 --to N：剔除 number > N；
4. 应用 --only N：只保留 number == N；
5. 按 number 数值升序排序（对 5.1 这类小数阶段同样可用数值比较）。

对空结果也有优雅退出路径——--to N 目标已全部完成时输出 All phases through ${TO_PHASE} are already completed. Nothing to do.，--only N 阶段已完成时输出 Phase ${ONLY_PHASE} is already complete. Nothing to do.，全部完成后输出包含 🎉 的 COMPLETE 横幅。

随后工作流展示“阶段计划表”（含阶段号/名称/状态），并逐阶段调用 gsd-sdk query roadmap.get-phase ${PHASE_NUM} 抓取 phase_name、goal、success_criteria 备用。

Step 3 阶段执行：discuss → UI 契约 → plan → execute → review

进度横幅与数值约定

每个阶段开始前渲染进度条横幅：

 GSD ► AUTONOMOUS ▸ Phase {N}/{T}: {Name} [████░░░░] {P}%

其中 T 必须是里程碑总阶段数 phase_count，而不是剩余未完成数（避免“Phase 63/3”这类把“剩余 3”误读成“共 3”的歧义）；P 为已完成阶段占全里程碑的百分比，进度条宽 8 字符、用 █/░ 填充。若出现多里程碑全局编号导致 N > T，则退化为 Phase {N} ({position}/{T}) 格式。

3a. Smart Discuss（智能讨论）

工作流先调用 gsd-sdk query init.phase-op ${PHASE_NUM}，依据返回的 has_context 判断是否已有 CONTEXT.md：

• 已有上下文：跳过讨论，提示 Context exists — skipping discuss.；
• 配置 workflow.skip_discuss=true：彻底跳过讨论，把 ROADMAP 阶段描述当作规格，并自动写一份最小化 CONTEXT.md（含 <domain>/<decisions>/<code_context>/<specifics>/<deferred> 五段结构，decisions 中标注 Claude's Discretion），随后用 gsd-sdk query commit 提交：

  gsd-sdk query commit "docs(${PADDED_PHASE}): auto-generated context (discuss skipped)" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
  

• 默认（skip_discuss 未开启）：非交互模式下走 smart_discuss 步骤（见后文专题）；--interactive 模式则内联运行完整讨论技能 Skill(skill="gsd-discuss-phase", args="${PHASE_NUM}")，保留用户对设计决策的输入权。

一个关键约束是：autonomous 模式下 discuss 必须单趟完成（single-pass）。一旦 CONTEXT.md 写入，就不得再以“上下文有缺口”为由对同一阶段重复发起讨论，has_context 检查是唯一权威——这从机制上避免自馈式的无界循环。

3a.5 UI 设计契约（前端阶段）

当阶段包含前端特征（goal 中出现 UI 类关键词，通过仓库中的 Node.js 词法边界门禁检测，入口按 git rev-parse --show-toplevel 锚定仓库根目录）且尚未存在 *-UI-SPEC.md、且配置 workflow.ui_phase 不为 false 时，工作流自动触发 Skill(skill="gsd-ui-phase", args="${PHASE_NUM}") 生成 UI 设计契约。若 UI-SPEC 生成失败仅显示告警并继续（不阻塞），非前端阶段则静默跳过。

3b/3c. Plan 与 Execute

• 默认模式下以内联 Skill 调用完成：

  Skill(skill="gsd-plan-phase", args="${PHASE_NUM}")
  Skill(skill="gsd-execute-phase", args="${PHASE_NUM} --no-transition")
  

  注意 execute 总是带 --no-transition，因为阶段切换（transition）由 autonomous 自己接管。
• --interactive 模式下，二者改为 Agent(... run_in_background=true ...) 派发，并保存 task_id 等待其完成后进入结果路由。

Plan 完成后需复查 init phase-op 的 has_plans，为空则进入 handle_blocker。

3c.5 代码审查与修复链（自动）

与 execute-phase/quick 只“建议修复”不同，autonomous 会自动串联 review + fix：

CODE_REVIEW_ENABLED=$(gsd-sdk query config-get workflow.code_review 2>/dev/null || echo "true")

若配置为 false 则跳过；否则调用 Skill(skill="gsd-code-review", args="${PHASE_NUM}")，解析 REVIEW.md frontmatter 的状态：clean/skipped 直接前进，存在 findings 时自动升级为 Skill(skill="gsd-code-review", args="${PHASE_NUM} --fix --auto")。任一 Skill 失败都按非阻塞处理，容错后继续。

3d. 执行后路由：以 VERIFICATION 状态机驱动

从 *-VERIFICATION.md 的 status: 行读取结果并分派：

状态	行为
空（无验证文件）	进入 handle_blocker：阶段未产出验证结果
passed	✅ 直接进入下一阶段（无需用户打断）
human_needed	展示需人工测试项，经 AskUserQuestion 让用户在 “Validate now / Continue without validation” 中选择；选择了 “Validate now” 再询问验证结果
gaps_found	展示缺口分数，提供 “Run gap closure / Continue without fixing / Stop autonomous mode” 三选一

缺口闭合（gap closure）被限制为最多 1 次自动重试以防止死循环：调用 Skill(skill="gsd-plan-phase", args="${PHASE_NUM} --gaps") 生成缺口计划后重新执行 execute-phase，若仍 gaps_found 则再次询问用户 “Continue anyway / Stop autonomous mode”。这里的文本模式（workflow.text_mode 或 --text）会把所有 AskUserQuestion 换成纯文本编号列表，以兼容 Codex、Gemini CLI 等不支持 AskUserQuestion 的非 Claude 运行时。

3d.5 UI Review（前端阶段）

在成功执行路由结束后、进入下一阶段前，若阶段存在 UI-SPEC 且 workflow.ui_review 未禁用，则运行 Skill(skill="gsd-ui-review", args="${PHASE_NUM}") 并展示得分。UI review 是建议性的、非阻塞的——无论评分如何都继续推进阶段。

Smart Discuss：面向自动化的讨论优化（引用文件）

命令文档将完整细节抽取到 get-shit-done/references/autonomous-smart-discuss.md，这与测试 tests/autonomous-decomposition.test.cjs 所守护的约束相关：autonomous.md 曾因超过 Claude Code Read 工具 10K token 上限（约 11748 token）而被迫 150 行分段读取，因而把 smart_discuss 步骤拆入独立引用文件，并把主工作流控制在 38K 字符（约 9500 token）以下。

smart_discuss 的五个子步骤是：

1. 装载既有上下文：读取 .planning/PROJECT.md、REQUIREMENTS.md、STATE.md 以及此前所有 *-CONTEXT.md（仅取阶段号更小的），提炼 <decisions> 中的锁定偏好与 <specifics> 中的具体诉求，形成内存中的 prior_decisions——用于避免重复提问已拍板的问题；
2. 侦查代码库：优先复用 .planning/codebase/*.md 中的 CONVENTIONS/STRUCTURE/STACK 地图；无地图时对 src/ 等目录做定向 grep 并读取 3-5 个相关文件，形成可复用组件、既有模式、集成点三份清单（预算控制在上下文 5% 以内）；
3. 生成灰度提案：先做纯基础设施阶段检测——当 goal 命中 scaffolding/plumbing/setup/migration/refactor/rename 等关键词，且成功标准全部是“文件存在/测试通过/配置合法”类技术性断言、且无任何用户可见行为描述时，直接跳过讨论、写最小 CONTEXT.md。否则按领域类型（用户“看到/调用/运行/阅读/被组织”）生成 3-4 个灰度区、每区约 4 个问题，每题预选一个推荐答案并附 1-2 个备选，同时用“你在第 N 阶段决定了 X”“组件 Y 已有 Z 变体”等注释标注理由；
4. 逐区呈现：每个灰度区呈现一张表格，经 AskUserQuestion 提供 “Accept all / Change Q1..QN / Discuss deeper” 等动态选项（最多 6 个显式选项），支持逐题替换备选、深入讨论（每次额外 4 题）、自由文本 “Other” 以及范围蔓延处理——把超出本阶段域的诉求记为 deferred idea 而不当场实现；
5. 写 CONTEXT.md：按与 discuss-phase 完全一致的五段式结构落盘到 ${phase_dir}/${padded_phase}-CONTEXT.md 并 commit，最后展示 Decisions captured: {count} across {area_count} areas。

Step 4 迭代：阶段间的实时收敛

• --only N：不迭代，直接进入生命周期（并以单阶段模式干净退出）；
• --to N 且当前阶段号 ≥ N：到达目标，显示 --to N REACHED 横幅并提示恢复命令 /gsd:autonomous --from ${next_incomplete_phase}，跳过生命周期（因未全部完成）；
• 默认：每个阶段完成后重新执行 roadmap.analyze 以捕获中途插入的小数阶段，并 cat .planning/STATE.md 检查 Blockers/Concerns 段；发现阻塞则进入 handle_blocker。

--interactive 的管道式并行是迭代步骤的亮点：第 N 阶段 discuss 结束后，立即把 plan+execute 作为后台代理派发，然后马上开始第 N+1 阶段的 discuss——用户始终在回答轻量级讨论问题，而重活（规划、写代码）在后台推进；主上下文只累积讨论会话。在执行后路由之前，工作流会等待后台代理完成。

Step 5 生命周期：audit → complete → cleanup

全部阶段完成后，autonomous 自动触发里程碑生命周期（而非仅仅“建议”用户手动执行），步骤依次为：

1. Audit：Skill(skill="gsd-audit-milestone")，读取 .planning/v${milestone_version}-MILESTONE-AUDIT.md 的状态——passed 直接前进（不打断用户，符合项目 CTRL-01 控制法则）；gaps_found 询问 “Continue anyway / Stop”；tech_debt 询问 “Continue with tech debt / Stop”；审计文件缺失/格式错误进入 handle_blocker；
2. Complete：Skill(skill="gsd-complete-milestone", args="${milestone_version}")，并校验归档文件 .planning/milestones/v${milestone_version}-ROADMAP.md 是否产出；
3. Cleanup：Skill(skill="gsd-cleanup")——其内部 dry-run 与删除确认被认定为符合 CTRL-01 的可接受暂停；
4. 最终渲染 COMPLETE 🎉 横幅（含 Ship it!）。

若 --only N 生效则跳过整个生命周期，横幅明确提示“全部阶段完成后请运行不带 --only 的 autonomous 以触发 audit/complete/cleanup”。

Step 6 阻塞处理：三选项收敛

任一阶段操作失败或被检测到阻塞时，以 AskUserQuestion 呈现三选项：Fix and retry（重跑本阶段失败的 discuss/plan/execute，再次失败则重新呈现选项）、Skip this phase（记录 Phase {N} ⏭ {Name} — Skipped by user 后继续下一阶段）、Stop autonomous mode（展示已完成/已跳过/剩余清单与恢复命令后干净退出）。恢复命令会根据场景自动拼装：

 Resume with: /gsd:autonomous ${ONLY_PHASE ? "--only " + ONLY_PHASE : "--from " + next_phase}${TO_PHASE ? " --to " + TO_PHASE : ""}

配置开关一览：如何收紧/放开自动驾驶边界

autonomous 的各环节均可通过 gsd-sdk query config-get workflow.<key> 读取配置（底层 schema 定义于 sdk/src/config.ts，get/set 通道在 sdk/src/query/config-mutation.ts），运行期带默认值回退：

配置键	默认值	作用
workflow.skip_discuss	false	为 true 时跳过所有讨论，把 ROADMAP goal 直接当规格并自动写最小 CONTEXT.md
workflow.code_review	true	控制 3c.5 的自动代码审查+修复链是否开启
workflow.ui_phase	true	控制前端阶段是否自动生成 UI-SPEC 设计契约
workflow.ui_review	true	控制前端阶段执行后是否跑 UI review 审计（建议性、不阻塞）
workflow.text_mode	false	把 AskUserQuestion 替换为纯文本编号选择，适配不支持该工具的非 Claude 运行时
workflow.max_discuss_passes	3	讨论单趟上限，autonomous 模式下相关 pass-cap 防护同样生效

质量保障与回归测试

autonomous 的实现由多组测试守护：

• tests/autonomous-interactive.test.cjs（对应 issue #1413）：断言命令定义包含 --interactive 的 argument-hint、工作流存在显式 **If \INTERACTIVE` is set:**分支且该分支内必须调用连字符形式的Skill(skill="gsd-discuss-phase", ...)（冒号形式已按 bug-2543 约束退役）、plan/execute 以 run_in_background` 派发、并出现 “pipeline parallelism / Phase N+1” 语义以及对应 success criteria；
• tests/autonomous-decomposition.test.cjs（issue #2196）：守护 autonomous.md 小于 38K 字符、smart_discuss 已拆分至引用文件且引用文件包含灰色提案/CONTEXT.md 写入指令；
• tests/autonomous-to-flag.test.cjs、tests/autonomous-ui-steps.test.cjs、tests/autonomous-allowed-tools.test.cjs 则分别守护 --to 行为、UI-SPEC/UI-Review 步骤编排与工具白名单。

使用建议与适用边界

• 使用 gsd:autonomous 前需确认里程碑已初始化（存在 ROADMAP.md 与 STATE.md，通常由 /gsd:new-milestone 创建）；
• 想让 Agent 放开发挥、把 ROADMAP 描述当作唯一规格时，可组合 workflow.skip_discuss=true；
• 需要人工把关关键设计决策、又不想等串行执行时，用 --interactive 获得“讨论在前台、开发在后台”的管道式体验；
• 只处理单点风险阶段（如某阶段反复卡壳）用 --only N 即可，完成后自动跳过生命周期，避免误触发里程碑审计与归档；
• 请以当前仓库中的工作流与命令定义为准：不同版本的 get-shit-done 对 --from/--to/--only/--interactive 的组合语义、默认配置与 Skill 命名（连字符形式）可能有细微差异，升级后建议先阅读 get-shit-done/workflows/autonomous.md 再投入生产使用。