gsd-core 分级帮助系统（Tiered /gsd-help）实战指南：从一屏速览到完整参考的渐进式文档设计

导读

本文讲解 gsd-core 中 /gsd-help 命令的分级（tiered）帮助机制（changeset sturdy-moles-bark.md，PR #3039）。通过将单一的长篇命令参考拆分为“默认一屏速览、--brief 十行回顾、--full 完整参考、<topic> 定向跳转、--brief <topic> 紧凑定向查询”五级渐进披露形态，用户可以从一个命令入口按需获取不同粒度的帮助。读完本文，你将掌握 /gsd-help 的全部参数组合、底层模式文件路由规则、主题别名解析机制，以及它在安装、迁移和测试中的落地点，从而在 gsd-core 工作流中快速定位任意命令的用法。

一、背景：为什么帮助系统需要分级

gsd-core 是一个面向 Claude Code 等 agentic 开发场景的“计划驱动开发”框架，命令面非常广（规划、执行、快速任务、调试、里程碑、审计等）。在分级机制落地前，/gsd-help 只能输出一份完整的长篇参考；对新手而言信息过载，对老手而言每次都要翻过大量内容才能找到自己关心的命令。changeset .changeset/archived/sturdy-moles-bark.md 记录了这一改进：

/gsd-help is now tiered — default output fits one screen, --brief gives a 10-line refresher, --full keeps the complete reference, /gsd-help <topic> jumps straight to one section (e.g. /gsd-help debug), and /gsd-help --brief <topic> is a compact scoped lookup (signature + one-line summary). Every topic output starts with a resolved-routing preamble so the matched alias and scope are visible. Closes #3039.

其核心设计思想是渐进披露（progressive disclosure）：帮助内容按需加载，而不是一次性全部输出。这一点在命令入口文件 commands/gsd/help.md 中直接体现——它的 frontmatter 声明了 argument-hint: "[--brief | --full | <topic> | --brief <topic>]"，把五种形态暴露给用户与编辑器，同时 <objective> 明确要求“仅输出所选分级（tier）的参考内容”，禁止附加项目分析、Git 状态、下一步建议等任何多余信息。

二、五种帮助形态与参数速查

/gsd-help 的参数解析遵循“trim + 小写化”规则，支持长形式与短形式（详见 workflows/help.md 的 <progressive_disclosure> 部分）：

调用方式	别名	输出内容	对应模式文件
/gsd-help	—	默认一屏新手指南（默认 tour）	workflows/help/modes/default.md
/gsd-help --brief	-b	十行顶部命令回顾	workflows/help/modes/brief.md
/gsd-help --full	-f、--all	完整命令参考（所有命令、所有参数）	workflows/help/modes/full.md（或按 compact-content-gate 切换到 full.compact.md 变体）
/gsd-help <topic>	裸主题如 debug、--debug、capture	单一主题完整小节（full scope）	workflows/help/modes/topic.md（full scope）
/gsd-help --brief <topic>	-b <topic>	紧凑定向查询：签名行 + 一行摘要（compact scope）	workflows/help/modes/topic.md（compact scope）

几点解析细节需要特别注意：

• 裸 token 即主题：debug、--debug、capture、workflow、config 等都被视为主题，路由到 topic.md。
• 互斥规则：--brief 与 --full 互斥；若两者同时出现且没有主题，优先 --full。
• 带主题时：--brief <topic> 进入紧凑作用域；--full <topic> 与裸主题行为一致，进入完整作用域。向 topic.md 透传参数时需保留 --brief 标志，以便模式文件选择正确作用域。
• 主题大小写不敏感，且允许剥掉单个前导 --（如 --debug 等价于 debug）。

分级的意义在于“同一份参考，多种读取方式”：默认形态帮助新用户快速建立全局心智模型；--brief 是回归用户的快速刷新；--full 提供权威的完整参考；主题形态则让任何人在任意时刻只看到自己关心的那一节。

三、默认形态与 brief 形态的实际内容

3.1 默认一屏速览（default.md）

默认输出是一页面向新手的“GSD Core — Git. Ship. Done.”导览，落点在 gsd-core/workflows/help/modes/default.md。它由四块组成：

① 三条入门命令：

/gsd:new-project        # Greenfield: questioning → research → requirements → roadmap
/gsd:onboard            # Existing codebase: map → ingest docs → initialize planning
/gsd:plan-phase 1       # Create a detailed plan for phase 1
/gsd:execute-phase 1    # Execute all plans in the phase

② 常用命令速查表：

命令	用途
/gsd:progress	我在哪、下一步做什么——也支持 --do "..." 自由文本路由
/gsd:quick	带 GSD 保证的小型临时任务（planning 目录 + 原子提交）
/gsd:fast "<task>"	琐碎内联改动——不起子代理，≤3 个文件编辑
/gsd:discuss-phase <N>	规划前捕捉愿景与决策
/gsd:debug "<symptom>"	持久调试会话，/clear 后仍存活
/gsd:capture	保存想法、待办、笔记、种子或 backlog 条目
/gsd:verify-work <N>	已完成阶段的会话式 UAT
/gsd:ship <N>	从已完成阶段发起 PR
/gsd:help --full	完整参考（所有命令、所有参数）

③ “想要更多？”分级导航：

/gsd:help --brief         # 10-line refresher of top commands
/gsd:help --full          # complete reference
/gsd:help <topic>         # one section only — see topics below
/gsd:help --brief <topic> # compact scoped lookup — signature + one-line summary

同时列出全部可用主题：workflow · planning · execute · quick · debug · capture · ship · config · milestones · spike · sketch · review · audit · progress。

④ 更新入口：

npx @opengsd/gsd-core@latest

3.2 brief 十行回顾（brief.md）

--brief 输出落点在 gsd-core/workflows/help/modes/brief.md，专为回归用户设计，只保留“顶部命令”的十行清单：

/gsd:new-project           Initialize a project (greenfield)
/gsd:onboard               Onboard an existing codebase (brownfield)
/gsd:map-codebase          Refresh/map codebase intelligence
/gsd:plan-phase <N>        Create a phase plan
/gsd:execute-phase <N>     Execute a phase
/gsd:progress              Where am I, what's next
/gsd:quick                 Small ad-hoc task with GSD guarantees
/gsd:fast "<task>"         Trivial inline task — no subagents
/gsd:debug "<symptom>"     Persistent debug session (survives /clear)
/gsd:capture               Save an idea / todo / note
/gsd:ship <N>              Open a PR from a completed phase

末尾附一行“更多”导航：/gsd:help（默认 tour）· /gsd:help --full（全部内容）· /gsd:help <topic>（单个小节）。

两个模式文件都遵守 <purpose> 中的铁律：只输出 <reference> 块内容，不做任何添加，这是帮助命令保持“纯参考”语义的关键约束。

四、主题定向查询：topic.md 的解析机制

主题形态是分级系统中最精巧的部分，其逻辑全部落在 gsd-core/workflows/help/modes/topic.md。它充当“路由表 + 抽取器”：

1. 解析 $ARGUMENTS：检测 --brief/-b 决定紧凑作用域；剥离标志后，剩余 token（剥掉单个前导 --）即为主题别名。

2. 别名解析：将别名对照“主题解析表”映射到 full.md 中的具体小节标题。别名覆盖了大量同义词——例如 init/new-project/onboard/onboarding/brownfield 都指向 ### Project Initialization；debug/debugging 指向 ### Debugging；verify/verify-work/uat 指向 ### User Acceptance Testing 加 /gsd:audit-uat 块。

3. 未命中处理：输出一行错误提示，随后按行列出规范主题名（去重后的逗号分隔列表），并建议 /gsd-help --full，然后停止。

4. 命中处理：先输出一行“resolved-routing preamble”，让用户看到实际匹配结果与作用域：

   **Topic:** `<alias>` → `<heading>` *(scope: full | compact)*
   

   这正是 changeset 中“Every topic output starts with a resolved-routing preamble so the matched alias and scope are visible”的落地实现。

5. 按作用域抽取小节：

   • 完整作用域（full scope）：从命中小节标题开始，输出到下一个同级或更高层级标题为止；若是“plus 拼接”的多个小节则按文档顺序连续输出；若是“命令块”则从该命令的签名粗体行开始，到下一个签名粗体行或标题为止。
   • 紧凑作用域（compact scope）：输出标题 + 该小节内第一条“命令签名粗体行”（形如 `<command> [args]`）及其一行摘要。若小节内没有签名行，则输出标题和首段。

6. 摘要定位规则（Locating the summary）：紧凑作用域的“一行摘要”有两种来源，取决于安装的参考变体——若签名行在闭合 ** 后以 em-dash 接续散文，则该尾随散文本身就是摘要，只输出这一行；否则摘要就是签名行之后紧邻的非空行，两行一并输出。Usage: 行永远不算摘要。

7. 收尾行：小节内容后固定输出：

   More: /gsd:help --full · /gsd:help <topic> · /gsd:help --brief <topic>
   

主题解析表摘录（完整 35 行映射见 topic.md 的 <reference> 表）：

主题别名	在 full.md 中的目标
next, smart-entry	### Smart Entry
workflow, core, core-workflow	## Core Workflow（整节至 ### Quick Mode 结束）
plan, planning, plan-phase	### Phase Planning
execute, exec, execute-phase	### Execution
progress, route	### Progress Tracking 加 ### Smart Router
quick, quick-mode	### Quick Mode
phase, phases, roadmap	### Roadmap Management
milestone, milestones	### Milestone Management 加 ### Milestone Auditing
session, pause, resume	### Session Management
capture, notes, todos	### Capturing Ideas, Notes, and Todos
ship, pr	### Ship Work 加 /gsd:pr-branch 块
config, settings, configuration	### Configuration
files, structure, layout	## Files & Structure
modes, interactive, yolo	## Workflow Modes
help	## Getting Help

五、完整参考（full.md）的纵深内容

--full 形态直接读取 gsd-core/workflows/help/modes/full.md（约 846 行，是权威的完整命令参考），覆盖从 Quick Start、Core Workflow、Phase Planning、Execution、Smart Router、Quick Mode 到 Roadmap/Milestone/Session/Debugging/Spiking/Capturing/UAT/Ship/Audit/Configuration/Utility/Getting Help 的完整命令面。它也是主题形态抽取的“数据源”，因此其中的小节结构（##/### 标题、**``<command> [args]``** 签名行）就是主题路由的契约。

以规划命令为例，完整参考给出每个命令的签名、作用与全部参数：

/gsd:plan-phase <number> [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--skip-ui] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--bounce] [--skip-bounce] [--chunked] [--tdd] [--mvp] [--granularity <coarse|standard|fine>] [--no-tracer] [--no-reversibility-gates]

• --research-phase <N>：research-only 模式，为阶段 <N> 生成 RESEARCH.md 后即在规划器运行前退出（替代已删除的 gsd-research-phase 独立命令，#3042）；配合 --research 强制刷新、--view 仅打印不生成、两者皆无时自动复用已有 RESEARCH.md。
• --ingest <path-or-glob> / --ingest-format <auto|nygard|madr|narrative>：规划前预摄入外部 ADR/PRD/SPEC（PRD Express Path 的组成部分）。
• --bounce / --skip-bounce：可选的外部规划精炼 pass 开关，可通过 workflow.plan_bounce 配置默认启用。
• --chunked：将规划拆成短 outline pass + 每个 plan 各一次短 pass（约 3–5 分钟），逐个提交 plan 以增强崩溃韧性；重跑 --chunked 从最后一个已提交 plan 续跑。
• --tdd：以测试驱动顺序规划（先测试后代码）；--mvp：在默认 tracer-first 排序之上做 MVP 增强（user story + Walking Skeleton）。
• --granularity <coarse|standard|fine>：覆盖本次运行的规划粒度，优先级高于阶段级/顶层配置与项目默认。
• --no-tracer：退出默认的 tracer-first 切片，改为横向分层（旧默认）；--no-reversibility-gates：抑制 one-way 决策门本应获得的 checkpoint:decision（用于有意无人值守的运行，评分仍会记录）。

生成物路径与用法示例一并给出：

Result: Creates .planning/phases/01-foundation/01-01-PLAN.md
Usage: /gsd:plan-phase 1
Usage: /gsd:plan-phase --research-phase 2            # research only, auto-uses existing RESEARCH.md
Usage: /gsd:plan-phase --research-phase 2 --view     # print existing RESEARCH.md, no spawn
Usage: /gsd:plan-phase --research-phase 2 --research # force-refresh, no prompt

类似地，执行命令 **/gsd:execute-phase [--wave N] [--gaps-only] [--tdd]** 说明 wave 分组执行、--wave N 只跑第 N 波、--gaps-only 只重跑验证器标记的缺口 plan、执行后回写 REQUIREMENTS.md/ROADMAP.md/STATE.md；快速任务命令 **/gsd:quick [--full] [--validate] [--discuss] [--research]** 说明 --full 等价于 --discuss --research --validate 的组合、快速任务独立存放在 .planning/quick/ 且只更新 STATE.md 不更新 ROADMAP.md。

六、变体切换：full.compact.md 与 compact-content-gate

--full 并非固定读取单一文件——根据 workflows/help.md 的分级说明，当 workflow.compact_content 配置开启时，安装的参考将切换为 gsd-core/workflows/help/modes/full.compact.md 变体。两者差异点在于“命令的一行摘要落在哪里”（决定 topic.md 的 Locating the summary 规则走哪条分支），其余结构保持一致。这意味着主题查询的抽取行为会自动适配当前安装的变体，无需用户感知切换。

七、落地细节：命令入口、安装与迁移

分级帮助不只是一套模式文件，它在仓库中有完整的“命令入口 → 工作流 → 模式文件”三层落地：

• 命令入口 commands/gsd/help.md：frontmatter 声明 name: gsd:help、description: Show available GSD commands and usage guide、argument-hint，并通过 <execution_context> 指向 ~/.claude/gsd-core/workflows/help.md；<process> 指示“Follow help.md with $ARGUMENTS”。帮助命令允许的工具仅 Read——它本质上是一个纯文档读取命令。
• 安装层面：安装引擎会把 gsd-help 作为带前缀的技能目录安装（见 src/install-engine.cts 的注释“Each child of stagedDir is a prefixed skill directory: gsd-help/, etc.”），并在 src/install-profiles.cts 的分级安装配置中按 agent 完整 stem（如 gsd-planner）精确控制哪些技能随之安装（For tiered profiles, copies only agents whose full stem ...）。
• 跨宿主迁移：src/runtime-artifact-conversion.cts 记录了命令名映射规则——gsd-help.md → /gsd-help，Claude 特有的 name: gsd:<x> 会被转换为目标宿主（如 CodeBuddy、Codex）的命名空间。测试 tests/codebuddy-install.test.cjs 验证了 skills/gsd-help/SKILL.md 的生成与迁移后旧技能目录的清理；tests/codex-config-install.test.cjs 验证全局安装会创建 skills/gsd-help/SKILL.md 使 $gsd-help 可被发现；tests/codex-config-hooks.test.cjs 验证刷新后 SKILL.md frontmatter 必须声明 name: gsd-help 并清理遗留的旧版技能目录。
• 可发现性：测试 tests/audit-fix-command.test.cjs 专门断言 /gsd-help 的 frontmatter 必须包含 argument-hint，以保障编辑器与 Agent 的可发现性——这条测试正是分级参数形态的契约守护。

八、应用建议与最佳实践

综合上述机制，在实际使用中可形成如下习惯：

1. 新项目/新上手：直接 /gsd-help，先看一屏导览与入门三命令，建立全局心智模型。
2. 回归用户：/gsd-help --brief，十行回顾顶部命令，快速唤醒记忆。
3. 查找某个具体命令：/gsd-help <topic>，例如 /gsd-help debug、/gsd-help plan、/gsd-help config，直接进入该小节完整内容；不确定别名时，主题表的多同义词覆盖（如 init/new-project/onboard）让命中率很高。
4. 只需要签名和一行摘要：/gsd-help --brief <topic>，例如 /gsd-help --brief ship，拿到签名行与一行摘要即可继续工作。
5. 权威完整参考：/gsd-help --full，或把 full.md 当作离线手册阅读。

无论选择哪种形态，输出都以 resolved-routing preamble（**Topic:** <alias> → <heading> (scope: ...)）开头，让匹配结果与作用域一目了然——这正是 changeset #3039 带来的核心体验改进：帮助系统从“一刀切的长文”进化为“按需取用、始终可追溯”的分级文档体系。