get-shit-done 项目统计指南用 gsd:stats 透视阶段、计划、需求与 Git 进度【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done导读gsd:stats是 get-shit-done 体系内一个只读的一体化统计命令负责把里程碑进度、计划执行率、需求完成度、Git 提交历史与项目时间线汇总成一份可读报告也提供可供程序消费的 JSON。本文从命令入口出发依次讲解其实际执行的统计工作流并结合 SDK 查询层的 statsJson 实现逐字段拆解统计口径、MVP 阶段摘要与底层原理最终让你既能熟练使用该命令也能理解每项指标是怎么算出来的。一条命令的完整链路gsd:stats是一个典型的“薄命令文档 厚工作流”设计。它的命令定义文件非常精简name: gsd:stats description: Display project statistics — phases, plans, requirements, git metrics, and timeline allowed-tools: - Read - Bash requires: [phase, progress]三个要点值得注意只读工具集该命令仅允许Read与Bash不会修改任何项目文件可以放心在任何阶段执行。前置依赖frontmatter 声明了requires: [phase, progress]即相关能力基于 phase阶段与 progress进度两条既有链路构建二者在 SDK 查询层也确实共享同一套扫描与判定逻辑。执行上下文委托文档通过execution_context指向~/.claude/get-shit-done/workflows/stats.md并声明“Execute end-to-end”。在仓库中该工作流对应的实体文件是 get-shit-done/workflows/stats.md真正的统计逻辑都在这份文件与底层 SDK 处理器中。当没有.planning/目录时工作流会明确提示先运行/gsd:new-project创建项目规划骨架避免对空目录做无意义的统计。数据采集gsd-sdk query stats.json工作流的第一步是调用 SDK 查询层获取统计 JSONSTATS$(gsd-sdk query stats.json) if [[ $STATS file:* ]]; then STATS$(cat ${STATS#file:}); fifile:前缀的处理表明gsd-sdk在结果过大时会落盘并返回文件引用脚本需要解引用后读取。随后从中抽取以下字段字段含义milestone_version/milestone_name当前里程碑的版本号与名称phases阶段明细数组含编号、名称、计划数、完成数、状态phases_completed/phases_total已完成阶段数 / 阶段总数total_plans/total_summariesPLAN.md 总数 / SUMMARY.md 总数percent阶段完成百分比按阶段数计算plan_percent计划执行百分比按 PLAN/SUMMARY 计数计算requirements_total/requirements_complete需求总数 / 已完成需求数git_commits/git_first_commit_date提交总数 / 首个提交日期last_activity最近一次活动时间除了stats.json查询层还注册了多个同义别名stats、stats json、stats.table、stats table全部声明为mutation: false的只读查询见 command-manifest.non-family.ts 与 command-static-catalog-domain.ts。其中stats.table会返回一段渲染好的 Markdown 表格字符串而stats.json返回结构化对象。呈现格式从 JSON 到人类可读报告工作流规定了统一的展示模板。采集到 JSON 后智能体按下述骨架输出报告# Project Statistics — {milestone_version} {milestone_name} ## Progress [████████░░] X/Y phases (Z%) ## Plans X/Y plans complete (Z%) ## Phases | Phase | Name | Plans | Completed | Status | |-------|------|-------|-----------|--------| | ... | ... | ... | ... | ... | ## Requirements ✅ X/Y requirements complete ## Git - **Commits:** N - **Started:** YYYY-MM-DD - **Last activity:** YYYY-MM-DD ## Timeline - **Project age:** N days模板的设计语言非常清晰Progress 段用█U2588与░U2591绘制 10 格或 20 格进度条X/Y 表示已完成阶段数与阶段总数Z% 对应percentPlans 段单独统计计划执行率X/Y 为 SUMMARY/PLAN 计数比对应plan_percent——因为一个阶段内可能含多份 PLAN计划级进度与阶段级进度经常不同步Phases 表逐阶段列出 Plans / Completed / Status直接透传phases数组中的plans、summaries、status字段Requirements / Git / Timeline 段补齐需求、提交量与项目年龄其中项目年龄由git_first_commit_date与当前时间推算。这套表格渲染逻辑在 SDK 中有完整对应实现。statsTable处理器直接委托给statsJson([table], ...)progress.ts表头即| Phase | Name | Plans | Completed | Status |进度条宽度固定为 10 格与上方模板一一对应。底层实现statsJson 的统计口径理解 gsd:stats 输出精度的关键在于 sdk/src/query/progress.ts 中的statsJson处理器。它依次完成五个数据源聚合1. 阶段清单ROADMAP 与磁盘双源合并处理器先解析 ROADMAP.md 中### Phase 编号: 名称形式的标题为每个阶段初始化plans/summaries 0、状态Not Started随后扫描.planning/phases/下的目录用comparePhaseNum排序把每个目录中的PLAN.md/-PLAN.md与SUMMARY.md/-SUMMARY.md文件分别计数再按规范化后的阶段号与 ROADMAP 侧记录合并见 progress.ts。这意味着即使磁盘上没有物理目录ROADMAP 中声明的阶段仍会计入phases_total。2. 阶段状态机determinePhaseStatus每个阶段的状态由determinePhaseStatus判定progress.ts规则如下条件状态PLAN 数为 0Pendingstats 上下文中为Not Started有 SUMMARY 但少于 PLANIn Progress无 SUMMARYPlannedSUMMARY ≥ PLAN 且存在 VERIFICATION 文件其内status: passedCompleteVERIFICATION 标记status: human_neededNeeds ReviewVERIFICATION 标记status: gaps_foundExecuted有 VERIFICATION 但状态无法识别Executed无 VERIFICATION 文件已执行未验证Executed也就是说一个阶段只有在“SUMMARY 数量不低于 PLAN 且验证文件判定 passed”时才算Complete据此统计phases_completed。3. 两个百分比的区别statsJson同时产出两个百分比progress.tsconst planPercent totalPlans 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0; const percent phases.length 0 ? Math.min(100, Math.round((completedPhases / phases.length) * 100)) : 0;plan_percenttotal_summaries / total_plans衡量“写了多少计划已执行”percentphases_completed / phases_total衡量“有多少阶段整体通过验证”。两者都做了Math.min(100, ...)上界钳制防止小数舍入越界。4. 需求、Git 与活动时间需求统计读取 requirements 文件用正则^- \[x\] \*\*与^- \[ \] \*\*分别匹配已勾选/未勾选的需求条目累加出requirements_total与requirements_completeprogress.tsGit 指标通过git rev-list --count HEAD取提交总数用git rev-list --max-parents0 HEAD定位根提交后再git show -s --format%as取其首个提交日期progress.ts所有这些调用都经过execGit封装并对退出码做了容错非 Git 仓库或空仓库时相应字段保持为 0 / null最近活动从 STATE.md 中按多种写法frontmatterlast_activity:、**Last Activity:**、Last Activity:、Last activity:兜底匹配last_activity字段progress.ts。MVP 阶段摘要一张表之外的维度对使用 MVP 模式垂直切片规划的项目普通统计表只反映“完成度”无法体现阶段的类型构成。为此工作流新增了mvp_summary步骤ANALYZE$(gsd-sdk query roadmap.analyze) if [[ $ANALYZE file:* ]]; then ANALYZE$(cat ${ANALYZE#file:}); fi MVP_COUNT$(echo $ANALYZE | jq [.phases[] | select(.mode mvp)] | length) TOTAL_COUNT$(echo $ANALYZE | jq .phases | length)roadmap.analyze的每个阶段对象会暴露一个mode字段对应 ROADMAP.md 中**Mode:** mvp的解析结果解析器位于get-shit-done/bin/lib/roadmap.cjs的searchPhaseInContent/cmdRoadmapAnalyze。随后在统计输出中追加一行汇总Phases: ${TOTAL_COUNT} total | ${MVP_COUNT} MVP | $((TOTAL_COUNT - MVP_COUNT)) standardPhase 1的cmdRoadmapAnalyze是 mode 字段的权威来源工作流只消费其输出而从不自行二次解析这与仓库内“Workflows compare against the parser output, never re-parse”的约定一致。值得注意的降噪规则若MVP_COUNT 0即项目没有任何 MVP-mode 阶段则整行省略。这样非 MVP 项目不会被统计噪音干扰也让该功能保持向后兼容。表格输出与测试保障stats.table 的渲染细节当你显式请求表格格式gsd-sdk query stats.table或智能体在报告中以 Markdown 呈现时输出包含标题、进度条、Plans/Phases/Requirements 小节与逐阶段表格progress.ts。其细节规则包括标题形如# {milestone_version} {milestone_name} — Statistics仅当total_plans 0时才打印 Plans 行仅当requirements_total 0时才打印 Requirements 行Git 信息同样条件化输出并在有git_first_commit_date时附加(since YYYY-MM-DD)。契约测试MVP 摘要行为有专门的契约测试保护tests/stats-mvp-display.test.cjs 读取工作流原文断言其必须提及MVP与mode字段、且必须引用roadmap.analyze——任何后续重构若删掉了这条能力会立刻被测试拦住。十进制阶段编号的完整性也有回归测试tests/bug-3150-stats-json-decimal-phase-gaps.test.cjs 复现了“当存在 06.10 时stats.json 曾漏掉 06.7/06.8/06.9”的缺陷如今断言输出的phases[].number必须精确为[06.6, 06.7, 06.8, 06.9, 06.10]且phases_total、total_plans、total_summaries均为 5。这说明阶段排序与计数必须使用数值化十进制比较comparePhaseNum而非字符串排序否则06.10会被错误地排在06.7之前并吞并中间阶段。适用前提与建议先建项目再统计没有.planning/时命令无法产出有意义的数据请先运行gsd:new-project依赖 Git提交数与起始日期依赖当前目录处于 Git 仓库中且存在HEAD可解析状态的可信度Complete依赖 VERIFICATION 文件中的status: passed因此“统计好看”不等于“代码可靠”——它只反映规范层面已完成验证无图渲染依赖报告为纯文本/表格便于在任何终端与日志系统中流转也便于被 Agent 直接解析或继续汇总。综上gsd:stats的价值在于把分散在 ROADMAP.md、.planning/phases/、requirements、STATE.md 与 Git 历史中的信息统一投影成一张“项目健康全景图”。通过本命令文档指向的工作流与 SDK 查询层实现你可以精确掌握每个百分比的来源、每条状态的判定规则并在自己的自动化流程中复用stats.json的稳定 JSON 结构做里程碑汇报或进度看板。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 get-shit-done 项目统计指南：用 gsd:stats 透视阶段、计划、需求与 Git 进度
get-shit-done 项目统计指南用 gsd:stats 透视阶段、计划、需求与 Git 进度【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done导读gsd:stats是 get-shit-done 体系内一个只读的一体化统计命令负责把里程碑进度、计划执行率、需求完成度、Git 提交历史与项目时间线汇总成一份可读报告也提供可供程序消费的 JSON。本文从命令入口出发依次讲解其实际执行的统计工作流并结合 SDK 查询层的 statsJson 实现逐字段拆解统计口径、MVP 阶段摘要与底层原理最终让你既能熟练使用该命令也能理解每项指标是怎么算出来的。一条命令的完整链路gsd:stats是一个典型的“薄命令文档 厚工作流”设计。它的命令定义文件非常精简name: gsd:stats description: Display project statistics — phases, plans, requirements, git metrics, and timeline allowed-tools: - Read - Bash requires: [phase, progress]三个要点值得注意只读工具集该命令仅允许Read与Bash不会修改任何项目文件可以放心在任何阶段执行。前置依赖frontmatter 声明了requires: [phase, progress]即相关能力基于 phase阶段与 progress进度两条既有链路构建二者在 SDK 查询层也确实共享同一套扫描与判定逻辑。执行上下文委托文档通过execution_context指向~/.claude/get-shit-done/workflows/stats.md并声明“Execute end-to-end”。在仓库中该工作流对应的实体文件是 get-shit-done/workflows/stats.md真正的统计逻辑都在这份文件与底层 SDK 处理器中。当没有.planning/目录时工作流会明确提示先运行/gsd:new-project创建项目规划骨架避免对空目录做无意义的统计。数据采集gsd-sdk query stats.json工作流的第一步是调用 SDK 查询层获取统计 JSONSTATS$(gsd-sdk query stats.json) if [[ $STATS file:* ]]; then STATS$(cat ${STATS#file:}); fifile:前缀的处理表明gsd-sdk在结果过大时会落盘并返回文件引用脚本需要解引用后读取。随后从中抽取以下字段字段含义milestone_version/milestone_name当前里程碑的版本号与名称phases阶段明细数组含编号、名称、计划数、完成数、状态phases_completed/phases_total已完成阶段数 / 阶段总数total_plans/total_summariesPLAN.md 总数 / SUMMARY.md 总数percent阶段完成百分比按阶段数计算plan_percent计划执行百分比按 PLAN/SUMMARY 计数计算requirements_total/requirements_complete需求总数 / 已完成需求数git_commits/git_first_commit_date提交总数 / 首个提交日期last_activity最近一次活动时间除了stats.json查询层还注册了多个同义别名stats、stats json、stats.table、stats table全部声明为mutation: false的只读查询见 command-manifest.non-family.ts 与 command-static-catalog-domain.ts。其中stats.table会返回一段渲染好的 Markdown 表格字符串而stats.json返回结构化对象。呈现格式从 JSON 到人类可读报告工作流规定了统一的展示模板。采集到 JSON 后智能体按下述骨架输出报告# Project Statistics — {milestone_version} {milestone_name} ## Progress [████████░░] X/Y phases (Z%) ## Plans X/Y plans complete (Z%) ## Phases | Phase | Name | Plans | Completed | Status | |-------|------|-------|-----------|--------| | ... | ... | ... | ... | ... | ## Requirements ✅ X/Y requirements complete ## Git - **Commits:** N - **Started:** YYYY-MM-DD - **Last activity:** YYYY-MM-DD ## Timeline - **Project age:** N days模板的设计语言非常清晰Progress 段用█U2588与░U2591绘制 10 格或 20 格进度条X/Y 表示已完成阶段数与阶段总数Z% 对应percentPlans 段单独统计计划执行率X/Y 为 SUMMARY/PLAN 计数比对应plan_percent——因为一个阶段内可能含多份 PLAN计划级进度与阶段级进度经常不同步Phases 表逐阶段列出 Plans / Completed / Status直接透传phases数组中的plans、summaries、status字段Requirements / Git / Timeline 段补齐需求、提交量与项目年龄其中项目年龄由git_first_commit_date与当前时间推算。这套表格渲染逻辑在 SDK 中有完整对应实现。statsTable处理器直接委托给statsJson([table], ...)progress.ts表头即| Phase | Name | Plans | Completed | Status |进度条宽度固定为 10 格与上方模板一一对应。底层实现statsJson 的统计口径理解 gsd:stats 输出精度的关键在于 sdk/src/query/progress.ts 中的statsJson处理器。它依次完成五个数据源聚合1. 阶段清单ROADMAP 与磁盘双源合并处理器先解析 ROADMAP.md 中### Phase 编号: 名称形式的标题为每个阶段初始化plans/summaries 0、状态Not Started随后扫描.planning/phases/下的目录用comparePhaseNum排序把每个目录中的PLAN.md/-PLAN.md与SUMMARY.md/-SUMMARY.md文件分别计数再按规范化后的阶段号与 ROADMAP 侧记录合并见 progress.ts。这意味着即使磁盘上没有物理目录ROADMAP 中声明的阶段仍会计入phases_total。2. 阶段状态机determinePhaseStatus每个阶段的状态由determinePhaseStatus判定progress.ts规则如下条件状态PLAN 数为 0Pendingstats 上下文中为Not Started有 SUMMARY 但少于 PLANIn Progress无 SUMMARYPlannedSUMMARY ≥ PLAN 且存在 VERIFICATION 文件其内status: passedCompleteVERIFICATION 标记status: human_neededNeeds ReviewVERIFICATION 标记status: gaps_foundExecuted有 VERIFICATION 但状态无法识别Executed无 VERIFICATION 文件已执行未验证Executed也就是说一个阶段只有在“SUMMARY 数量不低于 PLAN 且验证文件判定 passed”时才算Complete据此统计phases_completed。3. 两个百分比的区别statsJson同时产出两个百分比progress.tsconst planPercent totalPlans 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0; const percent phases.length 0 ? Math.min(100, Math.round((completedPhases / phases.length) * 100)) : 0;plan_percenttotal_summaries / total_plans衡量“写了多少计划已执行”percentphases_completed / phases_total衡量“有多少阶段整体通过验证”。两者都做了Math.min(100, ...)上界钳制防止小数舍入越界。4. 需求、Git 与活动时间需求统计读取 requirements 文件用正则^- \[x\] \*\*与^- \[ \] \*\*分别匹配已勾选/未勾选的需求条目累加出requirements_total与requirements_completeprogress.tsGit 指标通过git rev-list --count HEAD取提交总数用git rev-list --max-parents0 HEAD定位根提交后再git show -s --format%as取其首个提交日期progress.ts所有这些调用都经过execGit封装并对退出码做了容错非 Git 仓库或空仓库时相应字段保持为 0 / null最近活动从 STATE.md 中按多种写法frontmatterlast_activity:、**Last Activity:**、Last Activity:、Last activity:兜底匹配last_activity字段progress.ts。MVP 阶段摘要一张表之外的维度对使用 MVP 模式垂直切片规划的项目普通统计表只反映“完成度”无法体现阶段的类型构成。为此工作流新增了mvp_summary步骤ANALYZE$(gsd-sdk query roadmap.analyze) if [[ $ANALYZE file:* ]]; then ANALYZE$(cat ${ANALYZE#file:}); fi MVP_COUNT$(echo $ANALYZE | jq [.phases[] | select(.mode mvp)] | length) TOTAL_COUNT$(echo $ANALYZE | jq .phases | length)roadmap.analyze的每个阶段对象会暴露一个mode字段对应 ROADMAP.md 中**Mode:** mvp的解析结果解析器位于get-shit-done/bin/lib/roadmap.cjs的searchPhaseInContent/cmdRoadmapAnalyze。随后在统计输出中追加一行汇总Phases: ${TOTAL_COUNT} total | ${MVP_COUNT} MVP | $((TOTAL_COUNT - MVP_COUNT)) standardPhase 1的cmdRoadmapAnalyze是 mode 字段的权威来源工作流只消费其输出而从不自行二次解析这与仓库内“Workflows compare against the parser output, never re-parse”的约定一致。值得注意的降噪规则若MVP_COUNT 0即项目没有任何 MVP-mode 阶段则整行省略。这样非 MVP 项目不会被统计噪音干扰也让该功能保持向后兼容。表格输出与测试保障stats.table 的渲染细节当你显式请求表格格式gsd-sdk query stats.table或智能体在报告中以 Markdown 呈现时输出包含标题、进度条、Plans/Phases/Requirements 小节与逐阶段表格progress.ts。其细节规则包括标题形如# {milestone_version} {milestone_name} — Statistics仅当total_plans 0时才打印 Plans 行仅当requirements_total 0时才打印 Requirements 行Git 信息同样条件化输出并在有git_first_commit_date时附加(since YYYY-MM-DD)。契约测试MVP 摘要行为有专门的契约测试保护tests/stats-mvp-display.test.cjs 读取工作流原文断言其必须提及MVP与mode字段、且必须引用roadmap.analyze——任何后续重构若删掉了这条能力会立刻被测试拦住。十进制阶段编号的完整性也有回归测试tests/bug-3150-stats-json-decimal-phase-gaps.test.cjs 复现了“当存在 06.10 时stats.json 曾漏掉 06.7/06.8/06.9”的缺陷如今断言输出的phases[].number必须精确为[06.6, 06.7, 06.8, 06.9, 06.10]且phases_total、total_plans、total_summaries均为 5。这说明阶段排序与计数必须使用数值化十进制比较comparePhaseNum而非字符串排序否则06.10会被错误地排在06.7之前并吞并中间阶段。适用前提与建议先建项目再统计没有.planning/时命令无法产出有意义的数据请先运行gsd:new-project依赖 Git提交数与起始日期依赖当前目录处于 Git 仓库中且存在HEAD可解析状态的可信度Complete依赖 VERIFICATION 文件中的status: passed因此“统计好看”不等于“代码可靠”——它只反映规范层面已完成验证无图渲染依赖报告为纯文本/表格便于在任何终端与日志系统中流转也便于被 Agent 直接解析或继续汇总。综上gsd:stats的价值在于把分散在 ROADMAP.md、.planning/phases/、requirements、STATE.md 与 Git 历史中的信息统一投影成一张“项目健康全景图”。通过本命令文档指向的工作流与 SDK 查询层实现你可以精确掌握每个百分比的来源、每条状态的判定规则并在自己的自动化流程中复用stats.json的稳定 JSON 结构做里程碑汇报或进度看板。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考