企业官网建设流程全解析

/gsd:progress --next --auto是 gsd-core 中实现「无人值守逐步推进」的关键机制：它允许一个命令在完成当前步骤后自动重新调用自身，形成 discuss → plan → execute → verify → complete 的连续链条。本文以归档变更片段 .changeset/archived/14-progress-auto-flag.md（PR #148）为核心，结合 commands/gsd/progress.md、gsd-core/workflows/next.md 与相关测试，完整讲解--auto标志的历史由来、运行时语义、终止条件与实战用法。

一、变更背景：PR #148 修复了什么

归档片段原文（.changeset/archived/14-progress-auto-flag.md）：

--- type: Fixed pr: 148 --- The `--auto` flag is now wired through the `/gsd:progress` → `/gsd:next` handoff so that chaining these commands works without requiring the flag to be re-supplied manually.

这条变更记录包含三个核心信息：

1. 变更类型为Fixed：--auto不是新功能，而是对已有自动链（auto-chain）机制的缺陷修复；
2. 缺陷位置在/gsd:progress→/gsd:next交接处：当/gsd:progress --next --auto决定前进时，会把控制权移交给 next 工作流，而此前这一交接会丢失--auto标志；
3. 修复目标是"无需手动重新补充标志"：修复后，--auto在整个链式调用过程中持续生效，用户不必在每一步都重新输入。

该片段已被归档（.changeset/archived/子目录），根据 .changeset/archived/README.md，它描述的是gsd-core ≤ 1.3.1时代已发布的能力，归档仅用于溯源（provenance），其用户可见内容已手工整理进 CHANGELOG.md 的对应版本章节。

二、--auto的运行时语义：从 next 工作流看实现

修复后的交接逻辑完整地体现在 gsd-core/workflows/next.md 的show_and_execute步骤中。理解--auto需要先理解/gsd:progress --next本身的执行流程。

2.1/gsd:progress --next的推进管线

根据 commands/gsd/progress.md，/gsd:progress是「统一情境命令」，有三种模式：

• 默认模式：输出进度报告 + 智能路由到下一个动作（执行或规划）；
• --next模式：自动推进到下一个逻辑步骤，读取STATE.md、ROADMAP.md与阶段目录，支持--force绕过安全门；
• --do "任务描述"模式：分析自由文本意图，分发到最合适的 GSD 命令。

--next模式经 process 段落把参数剥离后，将剩余参数（--force、--auto等）原样传给 gsd-core/workflows/next.md 执行——这正是 PR #148 修复的交接链的第一环。

next工作流的推进管线按顺序包含：

1. detect_state：读取项目状态快照（gsd_run query state.json）、.planning/STATE.md与.planning/ROADMAP.md，提取current_phase、plans_total、progress、status等字段；
2. safety_gates：三道硬停止检查——未解决检查点（.planning/.continue-here.md存在）、错误状态（status: error/failed）、未处理验证失败（VERIFICATION.md 中无 override 的 FAIL 项）。任一命中即退出，除非传了--force；
3. resume_incomplete_phase（Route 0）：硬性不变量——任何「有计划但无对应 SUMMARY.md」的阶段必须先完成，才能向前路由（--no-resume可跳过，--force直接跳过全部）；
4. prior_phase_completeness：扫描当前阶段之前的阶段是否存在三类未完成工作（有计划无总结、未覆盖的验证失败、有 CONTEXT 无计划），支持 [C] 继续并延期到 backlog / [S] 停止 / [F] 强制推进；
5. determine_next_action：按 Route 1～8 判定下一步动作；
6. show_and_execute：展示判定结果后立即调用目标命令，不征求用户确认——这正是"零摩擦推进"的体现。

2.2 链式核心：--auto的递归语义

--auto的语义在 gsd-core/workflows/next.md 的show_and_execute步骤末尾有精确定义：

If--autowas passed:after the determined command completes, automatically re-invoke/gsd:progress --next --auto(forwarding--converge/--cross-aiand any reviewer flags if they were originally passed) to continue chaining to the next step.

即--auto不是"一次性"的：每完成一个步骤后，系统自动重新调用/gsd:progress --next --auto，形成链式推进，直到满足终止条件。注意交接时还会转发--converge/--cross-ai及评审者标志（--codex、--claude等），保证整条链的规划策略一致。

PR #148 修复的正是这个递归调用点：在修复前，/gsd:progress把--next --auto传给 next 工作流后，next 完成当前步骤并尝试链式续调时，重建的/gsd:progress调用丢失了--auto，导致链条中断。修复后--auto被正确贯穿/gsd:progress→/gsd:next的交接，链式推进无需手动重复补充标志。

2.3 终止条件

--auto链不会无限循环，根据 next 工作流的定义，链条在以下三种情况停止：

停止时输出提示：

⛔ Auto-chain stopped: [reason — e.g. safety gate, blocking decision required] Resume with: `/gsd:progress --next --auto` once resolved.

这保证了解除阻塞后，用户可以用同一条命令无缝续跑整条链。

三、--auto与--chain：两套自动推进机制的协同

gsd-core 中除了--auto，还存在--chain标志，两者共享同一套自动推进基础设施，这一点从测试中可以清楚看到。

3.1 共享的双标志守卫

plan-phase.md 与 discuss-phase 的链式模式 gsd-core/workflows/discuss-phase/modes/chain.md 使用完全相同的守卫模式清除自动链活动标记：

if [[ ! "$ARGUMENTS" =~ --auto ]] && [[ ! "$ARGUMENTS" =~ --chain ]]; then

即：只有--auto与--chain都缺席时，才清除workflow._auto_chain_active配置。这意味着无论用户从哪条命令、用哪个标志进入自动链，链状态都能被正确识别与延续。

3.2 测试对交接契约的锁定

chain-flag-plan-phase.test.cjs（#1620）用一组文本契约断言锁定了这一行为：

• plan-phase 的同步标志守卫必须同时检查--auto与--chain；
• 自动推进前必须持久化链标志：config-set workflow._auto_chain_active true；
• 自动推进触发条件必须同时提及--auto与--chain；
• plan-phase 步骤 15 必须解析这两个标志。

这组测试确认了--auto链不仅存在于/gsd:progress --next路径，还与plan-phase/discuss-phase的--chain自动推进共享同一状态机制（workflow._auto_chain_active），保证了跨命令切换时链条不断。

四、与--converge的配合：带评审收敛的自动链

--auto最常用的组合是--converge（别名--cross-ai），即「每步都走规划评审收敛循环」的自动链。相关契约由 adr-15-progress-converge.test.cjs（#1190）锁定。

4.1 工作流中的参数解析

next 工作流通过以下逻辑区分规划策略（gsd-core/workflows/next.md 的show_and_execute）：

PLAN_STRATEGY="local" if echo "$ARGUMENTS" | grep -qE '(^|[[:space:]])\-\-(converge|cross-ai)([[:space:]]|$)'; then PLAN_STRATEGY="converge" fi

随后为收敛模式构建透传参数：

CONVERGENCE_ARGS="" # 评审者通道标志来自运行时花名册（review-lane flags），--all 与 --text 是收敛控制项 for REVIEW_FLAG in $(gsd_run review-lane flags) --all --text; do if echo "$ARGUMENTS" | grep -qE "(^|[[:space:]])${REVIEW_FLAG}([[:space:]]|$)"; then CONVERGENCE_ARGS="${CONVERGENCE_ARGS} ${REVIEW_FLAG}" fi done MAX_CYCLES_ARG="" if echo "$ARGUMENTS" | grep -qE '\-\-max-cycles\s+[0-9]+'; then MAX_CYCLES_ARG=$(echo "$ARGUMENTS" | grep -oE '\-\-max-cycles\s+[0-9]+' | awk '{print $2}') CONVERGENCE_ARGS="${CONVERGENCE_ARGS} --max-cycles ${MAX_CYCLES_ARG}" fi

当路由判定为 Route 3（需要规划）且PLAN_STRATEGY=converge时，改用/gsd:plan-review-convergence <current-phase> ${CONVERGENCE_ARGS}而非标准的/gsd:plan-phase。

4.2 特性门控：fail-fast

收敛模式受配置项workflow.plan_review_convergence门控。若在未启用时请求--converge，next 工作流直接失败并输出启用指引：

/gsd:progress --next --converge is disabled (workflow.plan_review_convergence=false). Enable plan convergence with: gsd config-set workflow.plan_review_convergence true Then re-run with --converge.

测试 adr-15-progress-converge.test.cjs 对以下契约做了断言：progress 命令必须在argument-hint中同时声明--auto与--converge、文档须提及--cross-ai别名与门控配置、next 工作流默认PLAN_STRATEGY="local"、Route 3 的收敛调用必须带上${CONVERGENCE_ARGS}变量（不能只写命令名）。注意该测试把命令与工作流的 markdown 文本视为"运行时加载的契约"（source-text-is-the-product），因此对文本内容的断言即是对线上行为的断言。

五、实战用法

5.1 逐步自动链

在已初始化的项目（存在.planning/ROADMAP.md与.planning/STATE.md）中，从当前位置自动推进：

/gsd:progress --next --auto

系统会自动完成当前步骤，然后持续链式推进，直到里程碑完成、遇到阻塞性决策或出现错误/暂停状态。

5.2 带评审收敛的自动链

/gsd:progress --next --auto --converge /gsd:progress --next --auto --converge --codex --max-cycles 4

第二条命令把--auto（链式推进）、--converge（规划走收敛循环）、--codex（评审者通道）与--max-cycles 4（收敛轮次上限）组合使用。前提是先用gsd config-set workflow.plan_review_convergence true启用门控（--converge未启用时会 fail-fast，参考 4.2 节）。

5.3 强制跳过安全门

/gsd:progress --next --auto --force

--force会跳过全部三道安全门、Route 0 与 prior-phase 完整性提示，直接进入determine_next_action（gsd-core/workflows/next.md 的safety_gates步骤）。输出一行警告⚠ --force: skipping safety gates后立即推进。仅在明确知晓项目状态时使用。

5.4 与/gsd:autonomous的对比

如果你希望一次性跑完所有剩余阶段（而非逐步链式推进），可以使用 gsd-autonomous 技能对应的/gsd:autonomous命令。两者都支持--converge，但定位不同：

• /gsd:progress --next --auto：按当前状态逐步推进，每步之间有机会响应阻塞决策；
• /gsd:autonomous：读取 ROADMAP.md 一次性驱动所有未完成阶段，结束后自动执行里程碑生命周期（audit → complete → cleanup），并支持--from/--to/--only范围控制与--interactive交互模式。

实战细节可参考 docs/how-to/run-phases-autonomously.md，其中给出了带收敛的完整示例：

# Via progress --next --auto (step-chaining with convergence): /gsd-progress --next --auto --converge /gsd-progress --next --auto --converge --codex --max-cycles 4

六、验证与契约保障

--auto交接链的可靠性由两类测试锁定：

1. adr-15-progress-converge.test.cjs：验证 progress 命令声明--auto/--converge/--cross-ai、next 工作流解析收敛别名、门控 fail-fast、Route 3 收敛透传${CONVERGENCE_ARGS}；
2. chain-flag-plan-phase.test.cjs：验证 plan-phase 与 discuss-phase 的双标志守卫（--auto与--chain）、链标志持久化（config-set workflow._auto_chain_active true）与自动推进触发条件。

这两组测试共同把「--auto从/gsd:progress贯穿到/gsd:next乃至 plan-phase / discuss-phase」的契约固化下来，防止回归——这正是 PR #148 修复内容的延续与守护。

七、小结

从 .changeset/archived/14-progress-auto-flag.md 这一条简短变更记录出发，可以看到 gsd-core 中--auto标志的完整技术图景：

• 它由 PR #148 修复，使--auto能贯穿/gsd:progress→/gsd:next交接，链式推进无需手动重复补参；
• 它在 gsd-core/workflows/next.md 中被定义为"步骤完成后递归重调/gsd:progress --next --auto"，并在里程碑完成、阻塞决策、错误/暂停三种条件下终止；
• 它与--chain共享workflow._auto_chain_active状态机制，与--converge组合时可实现带规划评审收敛的自动链；
• 它的契约由 adr-15-progress-converge.test.cjs 与 chain-flag-plan-phase.test.cjs 持续守护。

一句话总结：--auto是让 gsd-core「自己接着干活」的开关——一次指定，整条链生效，直到项目状态明确要求人类介入为止。