GSD 分层帮助系统解析：get-shit-done 中 /gsd:help 的渐进式信息揭露与模式路由设计

导读

本文深入剖析 get-shit-done（GSD）这一面向 Claude Code 的规约驱动开发系统中 help.md 工作流的设计：它如何通过一条 /gsd:help 命令，把庞大的命令参考库组织成 --brief、--full、<topic>、--brief <topic> 四档可分级揭露的信息层级，避免在单次上下文窗口中一次性灌入全部内容。读完本文，你将掌握 GSD 帮助系统"按参数路由 → 惰性加载模式文件 → 原样输出 reference 正文"的实现机制、完整的参数解析规则与话题别名解析表，并能据此理解该仓库中其他工作流文件（如 progress.md、capture.md）共用的 <purpose> / <progressive_disclosure> / <reference> 三段式模板约定。

一、定位：help.md 在整个 GSD 系统中的角色

GSD（Get Shit Done）是"面向 Claude Code 单人 Agent 化开发的轻量元提示与规约驱动系统"。它把「模糊想法 → 层级化计划 → 分阶段执行」的全流程拆成 60+ 个可独立调用的 /gsd-* 斜杠命令，覆盖项目初始化、代码库测绘、阶段规划、执行、调试、验收、发布等环节。命令一多，如何在不耗尽模型上下文的前提下快速给出「正确粒度的帮助」就成了一个工程问题。

help.md 正是这套系统的帮助分发中枢。它本身不承载命令正文，而是充当一张"路由表 + 参数解析器"：

• 决定用户请求对应读取哪个模式文件（brief.md、default.md、full.md、topic.md）；
• 要求模型"只输出所选模式的 reference 正文，不添加任何项目分析、git 状态或下一步建议"。

从仓库结构看，它被命令层显式引用：命令定义文件 commands/gsd/help.md 通过 execution_context 指向 ~/.claude/get-shit-done/workflows/help.md，并规定"按 $ARGUMENTS 遵循该工作流"。也就是说，仓库内 get-shit-done/workflows/ 下的工作流文件是安装到用户 ~/.claude/get-shit-done/ 后的内容来源，commands/gsd/*.md 则是斜杠命令的入口壳。

二、渐进式信息揭露：为什么帮助要分四档

help.md 的 <progressive_disclosure>（渐进式信息揭露）节说明了设计动机：模式文件是惰性加载的（Mode files are lazy-loaded）——每次只读取与 $ARGUMENTS 匹配的那一个模式文件，然后逐字输出其 <reference> 正文。

四档信息粒度构成一条「由浅入深」的阶梯：

档位	触发参数	加载文件	内容粒度
简要回顾	--brief / -b	brief.md	约 10 行顶层命令速查（适合回归用户）
默认导览	空参数	default.md	一页式新手导览（3 个起步命令 + 常用命令表）
完整参考	--full / -f / --all	full.md	全部命令、全部标志、目录结构、配置项、常用工作流
主题切片	裸话题或 --brief <topic>	topic.md	从 full.md 提取单个章节（紧凑版仅签名 + 一行摘要）

这套设计把「信息密度」与「上下文成本」解耦：新用户看默认导览即可上手，老用户用 --brief 秒刷记忆，需要穷尽能力时再 --full，而单点查询用 <topic> 精准命中。仓库测试 feat-3039-help-tiered.test.cjs 的存在也印证了"分层帮助"（tiered help）是一个被显式测试保障的特性。

三、参数解析规则：$ARGUMENTS 是如何被消解的

help.md 定义了严格的参数消解流程，模型必须按序执行：

1. 预处理：对 $ARGUMENTS 做 trim 并转为小写。
2. 识别别名：--brief（含 -b）、--full（含 -f、--all）为互斥的长/短形式。
3. 话题判定：裸 token（如 debug）、带 -- 前缀的 token（如 --debug）、以及 capture、workflow、config 等一律视为话题，路由到 topic.md。
4. 互斥规则：--brief 与 --full 同时出现且不带话题时，优先 --full。
5. 组合规则：--brief <topic> 进入 topic.md 的紧凑作用域；--full <topic> 进入全量作用域（即默认话题行为）；向 topic.md 透传参数时必须保留 --brief 标志，以便该模式自行选择作用域。

由此得到完整路由表：

$ARGUMENTS 取值	读取文件
--brief（或 -b）单独出现	workflows/help/modes/brief.md
--full（或 -f、--all）单独出现	workflows/help/modes/full.md
空 / 未设置	workflows/help/modes/default.md
--brief <topic>（或 -b <topic>）	workflows/help/modes/topic.md（紧凑作用域：签名 + 匹配章节一行摘要）
其他任意形式（裸话题、--full <topic>、带 -- 前缀的话题）	workflows/help/modes/topic.md（全量作用域：输出匹配章节全部内容）

加载完成后，模型必须直接输出所选模式 <reference> 块的内容，不加任何修饰、项目上下文或建议——这条纪律在 commands/gsd/help.md 的 <objective> 中被再次强调（"Output ONLY the reference content of the chosen tier"）。

四、四个模式文件的职责与内容全景

4.1 brief.md：10 行顶层命令速查

面向回归用户的一行式刷新（One-liner refresher），正文是一个 text 代码块，列出 GSD 最常用的 8 条命令：

/gsd:new-project           Initialize a project (greenfield)
/gsd:map-codebase          Map an existing codebase (brownfield)
/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（默认导览）· /gsd:help --full（全部）· /gsd:help <topic>（单章节）。注意 --brief 不会重复解释命令的完整语义，它的定位是"最小记忆成本"。

4.2 default.md：一页式新手导览

无参数时的默认输出，面向第一次接触 GSD 的用户。其结构是典型的三段式引导：

• 起步三步（Start here）：

  /gsd:new-project        # Greenfield: questioning → research → requirements → roadmap
  /gsd:plan-phase 1       # Create a detailed plan for phase 1
  /gsd:execute-phase 1    # Execute all plans in the phase
  

  并提示存量代码库应先用 /gsd:map-codebase 让 GSD 落地到实际代码。
• 常用命令表：以表格列出 progress、quick、fast、discuss-phase、debug、capture、verify-work、ship、help --full 各自用途，覆盖"从定位到发布"的关键链路。
• 进阶路径：给出 --brief / --full / <topic> / --brief <topic> 四种用法示例，并列出可查询的话题全集：workflow · planning · execute · quick · debug · capture · ship · config · milestones · spike · sketch · review · audit · progress。
• 更新方式：npx get-shit-done-cc@latest。

4.3 full.md：完整命令参考（信息量最大的模式）

这是全系统命令知识的"单一事实来源"，也是 <topic> 模式的内容母版。其内容覆盖：

• 快速开始与核心工作流：/gsd:new-project → /gsd:plan-phase → /gsd:execute-phase → repeat，以及 /gsd:map-codebase、/gsd:discuss-phase、/gsd:plan-phase 的完整标志集（如 --research-phase <N>、--ingest-format <auto|nygard|madr|narrative>、--tdd、--mvp 与 PRD Express Path --prd）。
• 执行与路由：/gsd:execute-phase [--wave N] [--gaps-only] [--tdd] 的按波执行语义，以及 /gsd:progress --do "<description>" 的智能路由（dispatcher 只做分发、从不亲自执行）。
• 快模式：/gsd:quick [--full|--validate|--discuss|--research] 与内联执行的 /gsd:fast（无子代理、≤3 个文件改动、原子提交）。
• 路线图与里程碑：/gsd:phase [--insert <after>|--remove <number>|--edit <number>]（含小数阶段 7.1 插入与重编号）、/gsd:new-milestone、/gsd:complete-milestone。
• 调试、Spike、Sketch、捕获、验收、发布：从 /gsd:debug（可穿越 /clear 持久化）到 /gsd:verify-work、/gsd:ship、/gsd:review、/gsd:pr-branch、/gsd:capture --note|--list|--seed|--backlog。
• 配置与工具：/gsd:settings、/gsd:config [--profile|--advanced|--integrations]（四个模型画像 quality/balanced/budget/inherit）、/gsd:surface、/gsd:cleanup、/gsd:update。
• 附加命令清单：按「发现与规约」「规划与执行」「质量与评审」「诊断与维护」「知识上下文」「工作流编排」「仓库集成」分组罗列其余全部命令。
• 命名空间路由器：/gsd-context、/gsd-ideate、/gsd-manage、/gsd-project、/gsd-quality、/gsd-workflow 六个面向模型的两级分层路由元技能。
• 目录结构与规划配置：完整的 .planning/ 文件树、interactive / yolo 两种工作流模式、planning.commit_docs 与 planning.search_gitignored 两个配置项及 JSON 示例。
• 常用工作流剧本：新项目启动、中断后恢复、紧急插单、里程碑收尾、工作中捕获、问题调试六个可复制片段。

4.4 topic.md：话题别名解析与作用域控制

topic.md 是全系统最"程序化"的一个模式文件，它定义了一张话题别名解析表，将用户输入的话题别名映射到 full.md 中的具体章节：

话题别名（不区分大小写，忽略单个前导 --）	对应 full.md 章节
workflow / core / core-workflow	## Core Workflow（整节至 ### Quick Mode 结束）
init / new-project	### Project Initialization
map / map-codebase	### Project Initialization 下的 map-codebase 块
plan / planning / plan-phase	### Phase Planning
execute / exec / execute-phase	### Execution
progress / route	### Progress Tracking + ### Smart Router
debug / debugging	### Debugging
spike / sketch / spike-sketch / experiments	### Spiking & Sketching（或对应子块）
capture / notes / todos	### Capturing Ideas, Notes, and Todos
ship / pr	### Ship Work + pr-branch 块
config / settings / configuration	### Configuration
files / structure / layout	## Files & Structure
modes / interactive / yolo	## Workflow Modes
help	## Getting Help
…（完整表见下文链接）	…

topic.md 的输出规则同样严格：

1. 解析 $ARGUMENTS，检测 --brief（或 -b）选定紧凑作用域，否则为全量作用域；去除标志后，剩余 token（剥掉单个前导 --）即话题别名。
2. 用别名查表；若未命中，输出一行错误 + 去重后的规范话题名列表，并提示 /gsd:help --full，然后停止。
3. 命中后先输出一行解析路由前导（preamble）：**Topic:** \` → `` (scope: full | compact)`，让用户看到自己到底命中了哪一节。
4. 读取 full.md，按匹配单元格的提取规则与作用域输出正文：全量作用域输出从该标题到下一个同级/更高级标题为止的全部内容；紧凑作用域只输出标题 + 节内首个 **\/gsd:...`**` 签名行及其后一行摘要；多节拼接（"plus"）则按文档顺序依次输出；子块（"the /gsd:X block under …"）则在该章节内从每个签名行开始，到下一个签名行或标题为止。
5. 结尾固定输出一行：More: /gsd:help --full · /gsd:help <topic> · /gsd:help --brief <topic>，且不允许附加任何项目评论或追问。

该模式的落位逻辑与 full.md 中"Every topic output starts with a preamble so resolved routing is visible"的说明相互印证。

五、从源码与测试看实现约束

从仓库证据看，这套帮助系统不是一个"演示性质"的文档，而是有明确实现约束与回归保护的正式模块：

• 命令入口壳：commands/gsd/help.md 的 frontmatter 声明了 name: gsd:help、argument-hint: "[--brief | --full | <topic> | --brief <topic>]"，并把 allowed-tools 收敛到 Read——即帮助命令原则上只读文件、不改动任何项目状态，这与"只输出 reference 正文"的纪律一致。
• 分发依赖工作流：该命令的 execution_context 引用安装后的 ~/.claude/get-shit-done/workflows/help.md，说明命令与工作流是"壳 + 逻辑"的分离式架构，help.md 承担全部路由逻辑。
• 测试保障：仓库中 feat-3039-help-tiered.test.cjs 直接针对分层帮助特性编写；bug-2954-help-md-slash-command-stubs.test.cjs 验证帮助文档与斜杠命令存根的一致性；bug-3019-help-passthrough.test.cjs 则覆盖 help 参数透传的正确性。这些用例共同把"四档路由、参数解析、话题别名"固化为可回归的行为契约。

可以推断，任何新增命令或话题别名，都需要同时更新 full.md 的命令清单与 topic.md 的别名表，并接受上述测试的校验——这也是该仓库"文档即契约"工程风格在帮助系统上的体现。

六、实战速查：日常如何使用四档帮助

场景	命令	效果
刚装好 GSD，想快速上手	/gsd:help	一页新手导览，含 3 个起步命令
用了几天，想回忆顶层命令	/gsd:help --brief	约 10 行速查
想穷尽某个领域（如调试）	/gsd:help debug	输出 ### Debugging 整节
只想看某命令的签名与一行摘要	/gsd:help --brief ship	紧凑作用域，省上下文
想了解全部能力边界	/gsd:help --full	完整命令参考 + 目录结构 + 配置
话题记不清、拼写不确定	/gsd:help <不存在的词>	返回规范话题列表，辅助纠正
更新 GSD 后	npx get-shit-done-cc@latest 或 /gsd:update	保持帮助内容与命令同步

七、小结

GSD 的 help.md 用"一张路由表 + 四个模式文件 + 严格输出纪律"实现了可量化的分层帮助：--brief 保证最小上下文开销，--full 保证知识完整性，<topic> 保证单点可达，--brief <topic> 则在两者之间取折中。这种渐进式信息揭露模式不仅服务于 /gsd:help 本身，也示范了规约驱动系统中"把文档组织成可被模型按需消费的结构化模块"的通用方法论——同样的 <purpose> / <progressive_disclosure> / <reference> 三段式骨架，在 get-shit-done/workflows 目录下数十个工作流文件中被反复使用，构成了整个 GSD 运行时行为的最小单元。