GSD 命令整合实战：从 `/gsd-research-phase` 到 `/gsd-plan-phase --research-phase <N>` 的 Research-Only 模式与过期引用清理

get-shit-done（GSD）在本仓库的最新变更中完成了一次典型的"孤儿命令整合"：长期未被注册、从未真正可用的 /gsd-research-phase 独立命令被删除，其研究能力被整合为 /gsd-plan-phase 上的 --research-phase <N> 标志，并配套新增 --view、--research 两个修饰符（见 变更记录）。本文以该变更为骨架，结合 plan-phase 命令文档、工作流实现 与智能体定义，完整说明 Research-Only 模式的三种运行分支、调用示例、底层执行逻辑与适用场景，并梳理同一变更中跨多语言文档集的 4 处过期斜杠命令引用清理。读完本文，你将掌握如何只做阶段研究、查看已生成的研究报告、强制刷新研究，而不触发完整的规划管线。

变更概览：一次"删除孤儿、收敛能力"的接口重构

该变更由两个 issue 驱动：#3042（孤儿研究命令的修复方向）与 #3044（过期命令引用清理），记录于 .changeset/research-flag-and-stale-refs.md。核心动作有两条：

动作	对象	结果
命令整合	/gsd-research-phase 独立命令	删除；能力收敛为 /gsd-plan-phase --research-phase <N>
新增修饰符	/gsd-plan-phase	--view、--research，配合无修饰符时的 update / view / skip 三选一提示
引用清理	/gsd-check-todos、/gsd-new-workspace、/gsd-status、残留的 /gsd-plan-milestone-gaps	从英文及 4 套本地化文档集中移除过期引用（#3044）

这里的思路值得注意：当独立命令的斜杠命令桩（slash-command stub）从未被注册时，与其去"复活孤儿"（restore the orphan），不如把研究能力放回到它真正所属的流程位置——/gsd-plan-phase 本来就负责"研究（如需）→ 规划 → 验证"的默认流水线，研究是规划的前置步骤，天然适合作为该命令的一个子模式。

背景：为什么删除而不是修复 /gsd-research-phase

GSD 的命令体系面向"阶段（phase）"驱动开发：为每个阶段生成可执行的规划提示（PLAN.md），完整链路通常是讨论（discuss-phase）→ 研究（research）→ 规划（planner）→ 校验（plan-checker）。其中 gsd-phase-researcher 智能体专职为某一阶段调研技术路线，产出 RESEARCH.md（见 agents/gsd-phase-researcher.md）。

问题在于：过去存在一个名为 /gsd-research-phase 的独立研究命令，但它从未被真正注册进运行时，属于"文档存在、命令不可用"的悬空 stub。#3042 没有选择把该 stub 补注册，而是做了一个更彻底的收敛——让研究只作为 /gsd-plan-phase 的可选入口存在。这样一来，用户永远不需要记住两条语义重叠的命令，命令面（command surface）缩小，文档与实现漂移的概率也随之下降。

从源码结构看，这个"功能属于规划流水线、而不该有独立入口"的判断与 plan-phase 工作流 中"步骤 5. Handle Research"的设计一致：研究步骤本就内嵌在规划流程中，将其暴露为 --research-phase <N> 只是给这个内部步骤开了一个"只做研究就退出"的对外窗口。

Research-Only 模式：三种运行分支

当命令携带 --research-phase <N> 时，GSD 会为阶段 <N> 生成研究报告后直接退出，规划器不再运行。此时对已存在 RESEARCH.md 的情况，有三种行为，由是否附加修饰符决定：

调用方式	行为	适用情形
/gsd-plan-phase --research-phase <N>	若 RESEARCH.md 已存在，提示用户三选一：update / view / skip	交互式会话中最稳妥的默认入口
/gsd-plan-phase --research-phase <N> --research	无条件强制刷新：无论如何重新 spawn 研究员并覆盖旧的 RESEARCH.md，不弹提示	已知研究已过时、需要确定性刷新
/gsd-plan-phase --research-phase <N> --view	仅查看：把已有 RESEARCH.md 原样打印到 stdout，绝不 spawn 研究员；若文件不存在则报错并提示去掉 --view	最廉价的只读回查，适合修正循环

这三种分支在 plan-phase 命令 Agent 定义 中有着明确的目标描述（见该文件 "Research-only mode" 小节），也反映在 COMMANDS 参考文档 的 Research-only mode 说明中。核心设计意图是：让"研究"这个动作可独立、可重复、可只读地执行，而不必每次都支付重启规划器的成本。

完整命令参考与调用示例

/gsd-plan-phase 的公开参数（节选与本次主题强相关的部分，完整清单见 docs/COMMANDS.md）：

标志	描述
N	阶段号（可选；缺省时自动探测下一个未规划阶段）
--research-phase <N>	Research-only 模式：为阶段 <N> spawn 研究员、写出 RESEARCH.md 后、在规划器运行前退出。取代已删除的 gsd-research-phase 独立命令（#3042）
--research	强制重新研究，即使 RESEARCH.md 已存在
--skip-research	跳过研究，直接进入规划
--view	Research-only 修饰符：配合 --research-phase 使用时，把已有 RESEARCH.md 打印到 stdout 后退出（不 spawn）
--auto	跳过交互确认（此时若研究开关关闭则静默跳过研究）

docs/COMMANDS.md 给出了如下可直接复制的示例组合：

/gsd-plan-phase --research-phase 4             # 只研究第 4 阶段（若 RESEARCH.md 已存在则提示三选一）
/gsd-plan-phase --research-phase 4 --view      # 打印已有 RESEARCH.md，不 spawn 研究员
/gsd-plan-phase --research-phase 4 --research  # 强制刷新研究，不弹提示

作为对照，完整的"研究 + 规划 + 校验"流水线仍然是：

/gsd-plan-phase 1                              # 研究 + 规划 + 校验第 1 阶段
/gsd-plan-phase 3 --skip-research              # 熟悉领域，跳过研究直接规划

研究步骤同样存在于更轻量的快速路径中：/gsd:quick 的 --research 标志会在规划前 spawn 一个聚焦研究员（见 commands/gsd/quick.md 中 "--research flag" 的说明），且 --discuss --research --validate 等价于 --full。

工作流内部的执行细节：RESEARCH_ONLY 与 VIEW_ONLY

Research-Only 模式并非文档层面的"口号"，而是 plan-phase 工作流 中实打实的执行分支。从该工作流源码可还原出关键实现：

1. 参数解析（步骤 2）：正则捕获 --research-phase <N>（支持整数或小数阶段号，如 2.1），命中即置 RESEARCH_ONLY=true，并用捕获的阶段号覆盖位置参数：

RESEARCH_ONLY=false
VIEW_ONLY=false
if [[ "$ARGUMENTS" =~ --research-phase[[:space:]]+([0-9]+(\.[0-9]+)?) ]]; then
  RESEARCH_ONLY=true
  PHASE="${BASH_REMATCH[1]}"
fi
if $RESEARCH_ONLY && [[ "$ARGUMENTS" =~ (^|[[:space:]])--view([[:space:]]|$) ]]; then
  VIEW_ONLY=true
fi

2. 分支裁决（步骤 5.0）：三选一菜单在 has_research=true 且无 --research、无 --view 时触发——update（重 spawn 并覆盖）、view（打印退出）、skip（干净退出），这一交互与已删除的独立命令的既有制品菜单保持行为对齐（#3042 parity）。--view 分支的守卫逻辑为：

if [[ "$VIEW_ONLY" == "true" ]]; then
  [[ -f "$research_path" ]] || { echo "Error: --view requires an existing RESEARCH.md (Phase ${PHASE}). Drop --view to spawn the researcher."; exit 1; }
  cat "$research_path"; exit 0
fi

3. 早期退出（步骤 5.1 之后）：一旦 RESEARCH_ONLY=true 且研究完成，流程会打印如下摘要并干净退出，规划器、规划检查器、验证循环、缺口回填（gaps、bounce）等所有后续块一律跳过：

✓ Research-only mode complete (#3042)

  Phase:       ${PHASE}
  RESEARCH.md: ${research_path}

Re-run /gsd-plan-phase ${PHASE} to plan the phase using this research,
or /gsd-plan-phase ${PHASE} --research to refresh research and plan.

值得留意的是工作流中一条注释（CR #3045 finding）：步骤 5.1 顶部守卫确保默认（非 research-only）分支绝不会落入 5.0 的 early-exit 逻辑，否则研究子模式可能泄漏到完整规划流程中。这说明该模式是严格互斥的旁路，而非对默认流程的弱化。

三个典型使用场景

从 plan-phase 命令文档 与 命令 Agent 定义 的阐述看，Research-Only 模式被明确设计用于三类场景：

1. 跨阶段研究（cross-phase research）：在决定某个规划方案前，提前调研尚未排到的阶段 <N> 的技术路线，为后续排期提供依据，而不必等待轮到这个阶段。
2. 投入规划前的文档审查（doc review）：先产生并审阅研究报告，确认方向后再提交到规划。
3. 修正而不重规划（correction-without-replanning loop）：当规划后的反馈暴露出"研究不足"而非"规划不当"时，单独迭代研究比整个重 spawn 规划器便宜得多——这正是 --view 存在的意义：在一次修正循环里，反复只读回查最新研究，成本趋近于零。

RESEARCH.md 产物：内容、落盘与衔接

研究结果统一落盘为阶段目录下的 {phase_num}-RESEARCH.md（在 .planning 工作区中，路径经 plan-phase 工作流 初始化的 research_path 字段暴露）。其结构模板见 get-shit-done/templates/research.md，覆盖用户约束与锁定决策、架构责任图、标准技术栈、候选方案与反模式（"Don't Hand-Roll"、Common Pitfalls）、可复用代码示例、技术现状、待决开放问题、以及分级资料来源（HIGH / MEDIUM / LOW 置信度）等板块。研究完成后的下一步衔接是明确的：直接运行 /gsd-plan-phase <N> 即可让规划器消费该研究报告，或用 --research 在规划前刷新。

此外，Research 步骤与验证策略联动：当 RESEARCH.md 含 ## Validation Architecture 小节时，工作流会据此生成对应阶段的 VALIDATION.md，为后续规划的质量门提供 Dimension 8（验证需求）依据（Nyquist 验证开关 workflow.nyquist_validation 控制该联动）。在较新版本中还叠加了包合法性门（Package Legitimacy Gate，v1.42.1 引入）：研究员推荐外部包时会对每个包运行 slopcheck install <pkg> --json，并在 RESEARCH.md 中写入 ## Package Legitimacy Audit 表，[SLOP] 包在研究写出前即被剔除、[SUS] 包触发人工确认检查点——这些净化逻辑都发生在 RESEARCH.md 真正落盘之前（参见 docs/COMMANDS.md 与 docs/ARCHITECTURE.md）。

配套变更：4 处过期斜杠命令引用的多语言清理

同一变更还处理了 #3044：全面清理 4 个已不存在/残留的斜杠命令引用，范围横跨英文文档及 4 套本地化文档集（对应本仓库 docs 下的 en、zh-CN、ja-JP、ko-KR、pt-BR 文档树）。被清理的对象包括：

• /gsd-check-todos —— 属于早前 REQ-CONSOLIDATE-03 已删除的微技能斜杠形式（在 docs/FEATURES.md 中可看到该类命令必须解析为 "Unknown command"、不得存在影子 stub 的约束）
• /gsd-new-workspace —— 同样属已收敛的微技能命令
• /gsd-status —— 过期命令引用
• 残留的 /gsd-plan-milestone-gaps —— 缺口规划能力早已被其他命令吸收（如 commands/gsd/ns-project.md 所示，该命令由 #2790 删除）

这次清理与 #3042 是同源的"命令面治理"：前者删除孤儿命令本体，后者清除其余文档中对已删除命令的过时指向。两者共同维护一条纪律——文档中出现的每个斜杠命令都必须是真实可调度的入口，否则用户会在复制示例时得到 "Unknown command"。

小结

/gsd-research-phase → /gsd-plan-phase --research-phase <N> 的整合，是一个把"研究"从独立入口收敛为规划命令子模式的典型案例：它消除了从未注册的孤儿 stub，用 --research-phase <N> + --research + --view 三个开关完整覆盖了"提示式、强制式、只读式"三种研究交互，并在工作流层面以 RESEARCH_ONLY / VIEW_ONLY 两个标志实现严格的早期退出旁路，配合跨英文与 4 套本地化文档的过期引用清理，让研究这一环节真正成为规划流水线中可独立、可廉价、可重复调用的能力。若你正在使用 GSD 的 phase 流程，--research-phase <N> --view 会是你在"要不要为规划方向再赌一把"时最省 token 的确认手段。