get-shit-done 健康检查工作流 `/gsd:health`：`.planning/` 目录完整性校验、自动修复与上下文利用率诊断指南

本篇技术指南围绕 get-shit-done（GSD）的 health 工作流展开，讲解如何对 .planning/ 规划目录做系统性健康体检（缺失文件、非法配置、状态不一致、孤立计划），如何使用 --repair、--backfill、--context 三个标志位完成自动修复与上下文利用率诊断，并从 SDK 查询层实现 与 测试用例 出发剖析底层判定逻辑。读完本文，你将能熟练使用 /gsd:health 排查规划目录故障、安全地自动修复可恢复问题，并在会话进入上下文“断裂点”之前及时止损。

一、工作流定位：两种互相正交的诊断模式

health 工作流由 workflows/health.md 定义，其 purpose 明确为：校验 .planning/ 目录的完整性并报告可执行的问题，覆盖缺失文件、非法配置、不一致状态与孤立计划四类问题，且可选自动修复可修复项。

工作流同时提供第二种与规划目录健康完全无关的诊断模式——上下文利用率检查。原文档特别强调“两种模式互相正交”：--context 模式只关心当前会话的 token 使用量与模型上下文窗口的比值，与 .planning/ 目录健康没有任何关系。因此两种模式的输出绝不混排，独立诊断、独立呈现。

在命令层，commands/gsd/health.md 将其注册为 slash 命令 /gsd:health（COMMANDS.md 中亦写作 /gsd-health，两者等价），支持三个参数：

Flag	说明
--repair	自动修复可恢复的问题（创建/重置 config.json、重建 STATE.md、补充 nyquist 键、清理陈旧任务目录）
--backfill	回填里程碑归档快照中缺失的 MILESTONES.md 条目（仅叠加、不删除，安全性最高）
--context	切换为上下文利用率诊断模式，跳过全部完整性校验

二、参数解析：入口的第一步

工作流第一步 parse_args 扫描命令参数，识别三个标志位并写入环境变量，供后续步骤分发：

REPAIR_FLAG=""
BACKFILL_FLAG=""
CONTEXT_MODE=""
if arguments contain "--repair"; then
  REPAIR_FLAG="--repair"
fi
if arguments contain "--backfill"; then
  BACKFILL_FLAG="--backfill"
fi
if arguments contain "--context"; then
  CONTEXT_MODE="true"
fi

一旦 CONTEXT_MODE 置位，工作流直接跳转到 context_check 步骤，跳过全部完整性校验步骤。这是理解整个工作流分发的关键：health 与 context 是同一命令入口下的两条独立执行路径。

三、--context 模式：上下文利用率三分法诊断

3.1 数据来源：模型自报

上下文模式要求运行该工作流的模型自报两个数字：当前会话的近似 tokensUsed 与活动模型的 contextWindow。取值来源为运行时可见信息（Claude Code 的 /context 斜杠命令输出，或模型自身会话遥测）。若运行时两者都不暴露，则通过 AskUserQuestion 向用户询问一次。

TEXT_MODE 回退：当 text_mode 为 true（配置文件或 --text 标志触发）时，运行时不支持 AskUserQuestion（如 Codex、Gemini 等非 Claude 运行时），改为纯文本两问序列——“Approximate tokens used? Context window size?”，并从用户回复中按纯文本读取答案。

3.2 判定阈值与建议

拿到两个数字后，工作流调用 SDK 查询层：

gsd-sdk query validate.context \
  --tokens-used "$TOKENS_USED" \
  --context-window "$CONTEXT_WINDOW"

validate.ts 的 validateContext 处理器 在底层执行纯数学判定：ratio = tokensUsed / contextWindow，percent = round(ratio * 100)，并按三分法归类：

利用率	状态	建议动作（命令层文档）
< 60%	healthy	无需动作，上下文充裕
60% – 70%	warning	建议 /gsd:thread 开启新会话
≥ 70%	critical	推理质量可能在“断裂点”（fracture point）之后下降

原工作流文档要求：查询输出一行状态（Context utilization: NN% (state)）加一条针对 warning / critical 状态的建议行；SDK 输出原样打印后立即结束工作流，不得混入 .planning/ 健康输出。

实现层面值得注意的细节（源码）：

• parseFlagInt 严格校验：--tokens-used 必须是非负整数、--context-window 必须是正整数，缺失或非法会抛出 GSDError（Validation 分类）而不是静默吞掉；
• 建议文案由 handler 统一持有（CONTEXT_RECOMMENDATIONS），其中 warning 提示“接近断裂区，建议 /gsd:thread 在新窗口继续”，critical 提示“超过 70% 利用率后推理质量可能下降，立即运行 /gsd:thread 保持输出质量”；
• 结果以 JSON 返回 { percent, state, recommendation }，渲染层负责输出。

四、主流程：validate.health 查询与 JSON 输出契约

4.1 执行方式

非 --context 模式下，工作流执行：

gsd-sdk query validate.health $REPAIR_FLAG $BACKFILL_FLAG

该查询注册于 command-manifest.validate.ts，canonical 名为 validate.health，别名 validate health，mutation: false、outputMode: json，并由 command-family-handlers.ts 绑定到 validateHealth 处理器。

4.2 JSON 输出字段

工作流解析查询返回的 JSON，字段契约如下：

字段	含义
status	"healthy" | "degraded" | "broken"
errors[]	关键问题（含 code、message、fix、repairable）
warnings[]	非关键问题
info[]	信息性提示
repairable_count	可自动修复的问题数量
repairs_performed[]	使用 --repair 时实际执行的动作

从源码看，status 的判定规则是（validate.ts）：存在 error 即 broken；否则存在 warning 即 degraded；否则 healthy。repairable_count 为 error 与 warning 中 repairable=true 条目数之和。

五、错误码与警告码全表（16 项）

原工作流文档给出的完整码表必须逐条掌握，它是解读诊断输出的字典：

Code	Severity	Description	Repairable
E001	error	.planning/ 目录不存在	No
E002	error	PROJECT.md 不存在	No
E003	error	ROADMAP.md 不存在	No
E004	error	STATE.md 不存在	Yes
E005	error	config.json 解析错误	Yes
W001	warning	PROJECT.md 缺少必需章节	No
W002	warning	STATE.md 引用了无效阶段	No
W003	warning	config.json 不存在	Yes
W004	warning	config.json 字段值非法	No
W005	warning	阶段目录命名不符合 NN-name 格式	No
W006	warning	阶段在 ROADMAP 中但磁盘无目录	No
W007	warning	磁盘有阶段目录但不在 ROADMAP 中	No
W008	warning	config.json 缺少 workflow.nyquist_validation（默认启用但 agent 可能跳过）	Yes
W009	warning	阶段在 RESEARCH.md 中有 Validation Architecture 但无 VALIDATION.md	No
W018	warning	归档里程碑快照在 MILESTONES.md 中缺失条目	Yes（--backfill）
W019	warning	.planning/ 根目录存在无法识别的文件——非 GSD 规范产物	No
I001	info	计划缺少 SUMMARY（可能进行中）	No

源码侧扩充：从 validateHealth 实现 看，实际检查不止表格中的条目，还包含若干较新的校验项，理解它们有助于定位真实项目故障：

• Check 1（E001）：.planning/ 目录不存在直接返回 broken，且跳过其余检查（源码）；
• Check 2（E002/W001）：PROJECT.md 必须包含 ## What This Is、## Core Value、## Requirements 三个必需章节，缺一即报 W001（源码）；
• Check 4（E004/W002）：STATE.md 阶段引用以 ROADMAP.md 为权威进行比对（bug #2633 修复），同时把 milestones/vX.Y-phases/ 归档目录中的历史阶段也视为有效引用（bug #3652 修复），避免完整里程碑切换后产生误报（源码）；
• Check 5b（W008）：检测 config.json.workflow.nyquist_validation 键是否存在，缺失时提示“默认启用但 agent 可能跳过”并标记可修复（源码）；
• Check 6（W005）：阶段目录必须匹配 /^\d{2,}(?:\.\d+)*-[\w-]+$/（如 01-setup），不满足即报 W005（源码）；
• Check 7（I001）：按 canonicalPlanStem 规范化计划名（如 68-01-scaffolding → 68-01）后比对 PLAN 与 SUMMARY 配对（源码）；
• Check 7b（W009）：RESEARCH.md 内含 ## Validation Architecture 却缺 VALIDATION.md 时报警，提示用 /gsd:plan-phase --research 重新生成（源码）；
• Check 8（W006/W007）：ROADMAP 与磁盘阶段同步比对，支持阶段号变体归一（去前导零、补零、带字母后缀等），未开始的阶段（- [ ] 复选框）豁免 W006（源码）；
• Check 9（W011）：STATE.md 的 Current Phase 与 ROADMAP 中 [x] 已勾选完成阶段交叉验证，状态非 complete/done 时报“状态文件可能失步”，建议 /gsd-progress 重新推导（源码）；
• Check 10（W012–W015）：配置字段专项校验——branching_strategy 合法值仅 none|phase|milestone；context_window 必须是正整数；phase_branch_template 必须含 {phase} 占位符；milestone_branch_template 必须含 {milestone} 占位符（源码）；
• E010（首页守卫）：若当前工作目录就是用户主目录，直接拒绝检查并返回 E010——因为此时会读到错误的 .planning/ 目录，提示先 cd 到项目根目录（源码）。

六、输出格式与终端呈现

format_output 步骤定义了统一的终端输出模板。头部横幅：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD Health Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Status: HEALTHY | DEGRADED | BROKEN
Errors: N | Warnings: N | Info: N

各分节按需渲染。执行过修复时：

## Repairs Performed

- ✓ config.json: Created with defaults
- ✓ STATE.md: Regenerated from roadmap

存在错误时：

## Errors

- [E001] config.json: JSON parse error at line 5
  Fix: Run /gsd:health --repair to reset to defaults

- [E002] PROJECT.md not found
  Fix: Run /gsd:new-project to create

存在警告时：

## Warnings

- [W002] STATE.md references phase 5, but only phases 1-3 exist
  Fix: Review STATE.md manually before changing it; repair will not overwrite an existing STATE.md

- [W005] Phase directory "1-setup" doesn't follow NN-name format
  Fix: Rename to match pattern (e.g., 01-setup)

存在信息时：

## Info

- [I001] 02-implementation/02-01-PLAN.md has no SUMMARY.md
  Note: May be in progress

若存在可修复问题但未使用 --repair，输出底部追加：

---
N issues can be auto-repaired. Run: /gsd:health --repair

七、自动修复机制：安全边界与风险分级

7.1 五种修复动作

Action	效果	风险
createConfig	以默认值创建 config.json	无
resetConfig	删除并重建 config.json	丢失自定义设置
regenerateState	缺失时根据 ROADMAP 结构重建 STATE.md	丢失会话历史
addNyquistKey	向 config.json 追加 workflow.nyquist_validation: true	无——与现有默认一致
backfillMilestones	从 .planning/milestones/vX.Y-ROADMAP.md 快照合成缺失的 MILESTONES.md 条目	无——仅叠加；由 --backfill 标志触发

明确不可修复（风险过高）：PROJECT.md / ROADMAP.md 内容、阶段目录重命名、孤立计划清理。这些项必须人工介入。

7.2 修复动作的源码实现细节

从 validateHealth 的 repair 分支 可看到修复的具体行为：

• createConfig / resetConfig 只写入“已知安全默认值”（源码注释 T-12-11）：model_profile: 'balanced'、commit_docs: false、search_gitignored: false、branching_strategy: 'none'、phase_branch_template: 'feat/phase-{phase}'、milestone_branch_template: 'feat/{milestone}'、quick_branch_template: 'fix/{slug}'，workflow 下 research/plan_check/verifier/nyquist_validation 均启用，parallelization: 1、brave_search: false。注意该动作覆盖整个文件，自定义设置确实会丢失——与文档风险标注一致；
• regenerateState 从 ROADMAP.md 中正则提取 ## Milestone: <version> - <name> 生成最小 STATE.md（含 ## Project Reference、## Position、## Session Log 三节，当前阶段标为 (determining...)，状态 Resuming，并记录重建日期）；
• addNyquistKey 仅在键缺失时增量写入 workflow.nyquist_validation = true，不会改动其他配置。

7.3 修复后的闭环验证

工作流在 verify_repairs 步骤要求：执行过修复后，不带 --repair 重跑一次健康检查以确认问题已解决，并报告最终状态。这正是“诊断 → 修复 → 复诊”的闭环，建议在 CI 或交付前脚本中复用同样的模式。

八、--backfill：里程碑归档回填

W018 与 backfillMilestones 动作服务一个特定场景：执行完整里程碑归档（如 /gsd:cleanup）后，归档到 .planning/milestones/vX.Y-ROADMAP.md 的快照在 MILESTONES.md 中没有对应条目。此时运行：

/gsd:health --repair --backfill

会从归档快照合成缺失的条目。该动作被明确标注为“仅叠加（additive only）”，不会修改或删除既有条目，因此是全部修复动作中侵入性最低的一类，可以在归档流程后放心执行。

九、Windows 专属：陈旧子代理任务目录清理

stale_task_cleanup 步骤针对 Windows 平台的一个已知问题：Claude Code 的子代理被强制杀死（崩溃/冻结）后，会在 ~/.claude/tasks/ 留下陈旧任务目录，持续占用磁盘空间。

当 --repair 激活时，工作流检测并清理：

# Check for stale task directories (older than 24 hours)
TASKS_DIR="$HOME/.claude/tasks"
if [ -d "$TASKS_DIR" ]; then
  STALE_COUNT=$( (find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null || true) | wc -l )
  if [ "$STALE_COUNT" -gt 0 ]; then
    echo "⚠️  Found $STALE_COUNT stale task directories in ~/.claude/tasks/"
    echo "   These are leftover from crashed subagent sessions."
    echo "   Run: rm -rf ~/.claude/tasks/*  (safe — only affects dead sessions)"
  fi
fi

检测阈值是超过 24 小时的目录（-mtime +1），判定为死会话残留后作为 info 级诊断 I002 | info | Stale subagent task directories found | Yes (--repair removes them) 报告。其安全前提是：只清理已死会话的残留，不影响活动会话。

十、底层原理：从工作流到 SDK 查询层的调用链

10.1 注册与路由

health 工作流并非直接执行文件系统检查，而是委托给 GSD SDK 的查询层：

1. 工作流定义 workflows/health.md 接收命令层传入的标志位；
2. 命令定义 commands/gsd/health.md 通过 execution_context 引用 @~/.claude/get-shit-done/workflows/health.md，并声明 allowed-tools: Read, Bash, Write, AskUserQuestion 与 requires: [thread]；
3. 查询通过 gsd-sdk query validate.health / gsd-sdk query validate.context 路由到 command-family-handlers.ts，由 validate.ts 中的 validateHealth、validateContext（以及同族的 validateConsistency、validateAgents）处理器执行；
4. 查询注册表 QUERY-HANDLERS.md 将 validate 家族列为已注册状态。

10.2 双实现的对齐约束

validate.ts 头部注释 说明这些处理器是从旧版 get-shit-done/bin/lib/verify.cjs 移植而来，并在多处保留“Mirrors … in verify.cjs”的注释，例如 listMilestoneArchiveDirs、collectPhaseRoots、validateContext（镜像 context-utilization.cjs）。这意味着 CJS 命令行工具与 TS SDK 查询层必须保持行为一致，golden 集成测试 正是用来守护这种双实现对齐的。

10.3 若干健壮性设计

• 路径安全：resolvePathUnderProject 约束文件读写不逃逸项目根目录；verifyKeyLinks 对包含空字节（\0）的路径直接抛 Validation 错误；
• 正则 DoS 防护：key_links 模式长度超过 512 字符或含嵌套量词时回退为字面量匹配（源码）；
• 阶段号归一化：W002/W006/W007 的比对都支持阶段号变体（03↔3、3.1↔03.1，字母后缀如 3A 必须精确匹配），避免历史格式引发误报；
• 首页守卫 E010：防止在用户主目录误读错误的 .planning/ 目录，属于防御性编程的典型范例。

十一、测试验证：行为契约的证据链

仓库对健康检查功能有专门的测试覆盖，可作为行为契约的证据：

• health-validation.test.cjs：覆盖 W011（STATE/ROADMAP 阶段发散检测）、W012–W015（config 字段与模板占位符校验）以及边界条件，测试用 createTempProject 构造最小 ROADMAP/STATE/PROJECT/config 夹具；
• validate-context.test.cjs：验证 validate.context 的阈值判定与参数校验；
• context-utilization.test.cjs：覆盖上下文利用率三分法逻辑；
• golden.integration.test.ts：守护 CJS 工具与 SDK 查询层的输出一致性。

这意味着 /gsd:health 的每次行为变更都受回归测试约束，生产环境中可以放心依赖其输出契约。

十二、日常使用建议

1. 例行体检：每周或每个里程碑边界运行一次 /gsd:health，重点观察 W006/W007（ROADMAP 与磁盘失步）与 W002（状态文件过期引用）；
2. 安全自愈：对 E004/E005/W003/W008 这类可修复项，先运行无 --repair 的检查确认数量，再执行 /gsd:health --repair，最后复诊确认归零；
3. 里程碑归档后：执行完归档类操作后追加 --backfill，补全 MILESTONES.md 记录；
4. 长会话防断裂：会话中段运行 /gsd:health --context，当利用率进入 60%–70% 区间即考虑 /gsd:thread 开新会话，避免越过 70% 断裂点后推理质量滑坡；
5. 手动修复前先读修复建议：W002 这类不可修复项，工作流会给出“Review STATE.md manually”的指引，切勿用 --repair 覆盖既有 STATE.md（重建动作会丢失会话历史，源码实现中 regenerateState 只处理“缺失”场景，不会覆盖已存在文件）。

/gsd:health 的价值在于把“规划目录状态机”的隐性规则显性化：文件存在性、命名规范、跨文件引用、配置 schema、会话上下文水位全部收敛为一张可执行、可修复、可复诊的检查清单。理解其错误码体系与修复动作的安全边界，就能在 GSD 驱动的迭代开发中第一时间定位规划层故障，把精力留给真正需要人工判断的问题。