get-shit-done 项目统计gsd:stats工作流数据采集、字段语义与 MVP 模式摘要的实现解析【免费下载链接】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本篇技术指南围绕 get-shit-doneGSD中负责“项目统计展示”的 stats 工作流 展开它由/gsd:stats命令触发用于一次性汇总当前项目的阶段phases、计划plans、需求requirements、Git 提交记录与项目时间线。读完本文你将掌握 stats 工作流的完整执行步骤、stats.json中每个统计字段的来源与计算口径以及如何通过gsd-sdk query在终端中直接复现同样的统计结果并理解 MVP 模式阶段摘要行的判定逻辑。一、工作流定位与命令入口stats 工作流属于 get-shit-done 的只读查询类工作流其职责在文档purpose中定义得非常明确Display comprehensive project statistics including phases, plans, requirements, git metrics, and timeline.它并不修改任何项目文件只负责读取项目状态并格式化输出。对应的命令定义为 commands/gsd/stats.md命令名gsd:stats描述Display project statistics — phases, plans, requirements, git metrics, and timeline声明依赖requires: [phase, progress]即依赖阶段与进度相关的状态文件执行上下文通过execution_context引用 get-shit-done/workflows/stats.md也就是说/gsd:stats是一个端到端执行Execute end-to-end的命令用户只需输入命令Agent 便会加载 stats 工作流并按其中的步骤完成统计与展示。二、第一步通过gsd-sdk query stats.json采集统计数据工作流的第一步gather_stats使用 SDK 查询接口获取原始统计 JSONSTATS$(gsd-sdk query stats.json) if [[ $STATS file:* ]]; then STATS$(cat ${STATS#file:}); fi这里有两个值得注意的实现细节查询命令是stats.json在 SDK 的查询注册表中stats与stats.json、stats json均被映射到同一个处理器statsJson见 command-static-catalog-domain.ts 与 command-manifest.non-family.ts别名统一由 command-aliases.generated.ts 维护且均为只读mutation: false。file:前缀协议当查询结果较大时SDK 可能将结果写入临时文件并以file:路径的形式返回工作流随后用cat读取文件内容保证超长输出的稳定性。statsJson处理器的完整实现位于 sdk/src/query/progress.ts它是旧版commands.cjs中cmdStats对应行 816–971的 TypeScript 移植版。它从.planning目录下的四类文件聚合数据数据来源路径由planningPaths解析用途阶段目录.planning/phases/扫描各阶段子目录统计 PLAN/SUMMARY路线图.planning/roadmap.md解析阶段编号、名称需求.planning/requirements.md统计需求完成数量状态.planning/state.md读取last_activity三、stats.json字段语义与源码级口径工作流要求从返回的 JSON 中提取以下字段其计算口径可以直接在 progress.ts 的结果对象中找到一一对应关系字段类型计算方式源码依据milestone_versionstring当前里程碑版本号来自getMilestoneInfomilestone_namestring当前里程碑名称phasesarray每个阶段对象{ number, name, plans, summaries, status }phases_completednumberstatus Complete的阶段数量progress.tsphases_totalnumber阶段总数phases.lengthtotal_plansnumber所有阶段目录中*-PLAN.md/PLAN.md文件数量之和progress.tstotal_summariesnumber所有阶段目录中*-SUMMARY.md/SUMMARY.md文件数量之和progress.tspercentnumberphases_completed / phases_total四舍五入后上限 100progress.tsplan_percentnumbertotal_summaries / total_plans同样四舍五入且上限 100progress.tsrequirements_totalnumber需求清单中- [x] **与- [ ] **条目之和progress.tsrequirements_completenumber仅- [x] **已勾选条目数量git_commitsnumbergit rev-list --count HEAD的输出progress.tsgit_first_commit_datestring/null首个提交日期git rev-list --max-parents0 HEAD找到根提交再用git show -s --format%as取日期progress.tslast_activitystring/null从state.md中按多种格式匹配last_activity:、**Last Activity:**、Last Activity:、Last activity:progress.ts几个值得展开的口径细节阶段解析分两路合并先通过正则/#{2,4}\s*Phase\s(\d[A-Z]?(?:\.\d)*)\s*:\s*([^\n])/gi从 roadmap.md 提取阶段骨架编号 名称状态初始为Not Started再扫描.planning/phases/下的子目录把磁盘上实际的 PLAN/SUMMARY 文件数量合并回对应阶段progress.ts。该正则支持1、1A、1.1等编号形式这正是十进制阶段编号能够被正确统计的原因相关回归见 bug-3150-stats-json-decimal-phase-gaps.test.cjs。阶段状态判定由determinePhaseStatus(plans, summaries, dir, Not Started)决定Plan 与 Summary 文件的有无组合决定了Not Started / In Progress / Complete等状态。需求统计只认**加粗列表项正则严格限定^- \[x\] \*\*与^- \[ \] \*\*避免把普通 checkbox 误计入需求指标。两个百分比均做了上限 100 的钳制Math.min(100, ...)防止历史数据异常时出现超过 100% 的展示。四、第二步向用户呈现统计结果工作流第二步present_stats定义了一套固定的 Markdown 展示模板采集到字段后按如下版式输出# 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 进度条源码使用 10 格宽的 Unicode 条filled round(percent / 100 * 10)实心块为█U2588、空档为░U2591见 progress.ts 的 table 分支实现。Phases 表格每一行对应一个阶段列依次为编号、名称、Plan 数、Summary 数、状态。Git 区仅当git_commits 0时展示提交数与起始日期progress.ts。Timeline由 Git 起始日期与最后活动推算项目年龄。值得说明的是SDK 侧已将这套模板固化为两种可复用格式statsJson默认返回 JSON 对象而当第一个参数为table即gsd-sdk query stats.table或stats table时返回渲染好的 Markdown 文本{ data: { rendered } }statsTable 正是对这一table分支的薄封装。工作流文档选择“取 JSON 自行排版”的方式是为了在展示前可以插入 MVP 摘要等附加信息。边界情况项目尚未初始化工作流明确规定如果项目根目录下不存在.planning/目录则不要强行统计而是提示用户先运行/gsd:new-project初始化项目。对应地源码中所有读取阶段目录、roadmap、requirements、state 的代码段都用try/catch包裹并静默降级catch { /* intentionally empty */ }因此在未初始化目录下查询会得到零值字段而非崩溃例如phases_total: 0、percent: 0。五、第三步MVP 模式阶段摘要行stats 工作流特有的mvp_summary步骤用于回答“这个项目里有多少个阶段属于 MVP 垂直切片”。它借助roadmap.analyze查询每个阶段的mode字段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)拿到计数后在统计输出中追加一行Phases: ${TOTAL_COUNT} total | ${MVP_COUNT} MVP | $((TOTAL_COUNT - MVP_COUNT)) standard判定规则为当MVP_COUNT 0时说明项目没有任何 MVP 模式阶段则整行省略避免给非 MVP 项目带来噪音。从源码看roadmap.analyze处理器为 roadmapAnalyze它对ROADMAP.md的每个阶段区块解析**Mode:** value标记并将值trim().toLowerCase()归一化roadmap.ts最终在阶段对象上暴露mode字段roadmap.ts。因此select(.mode mvp)只有在阶段显式标注**Mode:** mvp时才会命中而workflow.mvp_mode配置与--mvpCLI 标志则是另一条独立的激活链路见 mvp.ts 的优先级解析。这段 MVP 摘要的契约行为有专门测试守护tests/stats-mvp-display.test.cjs 断言工作流文档必须包含MVP字样、引用mode字段且必须通过roadmap.analyze来获取每阶段模式——也就是说任何未来对 stats 工作流的重构都不能绕过这些约定。六、与相邻查询命令的分工stats 并非项目唯一的只读统计入口理解它与相邻命令的边界有助于选对工具命令侧重依据gsd-sdk query stats.json里程碑级全景统计阶段 计划 需求 Git 时间线progress.tsgsd-sdk query progress/stats.table进度的紧凑渲染 / 统计的表格渲染progress.tsgsd-sdk query roadmap.analyze路线图全量结构分析含每阶段mode字段roadmap.tsgsd-sdk query phase.mvp-mode phase单阶段 MVP 模式的优先级解析mvp.tsSDK 查询命令的分发逻辑位于 query-command-resolution-strategy.ts当命令是progress或stats且带子参数如stats table时会被归一化为stats.table形式再路由保证了 CLI 与声明式调用的行为一致。七、小结stats 工作流是 get-shit-done 中最典型的“查询即聚合”型工作流命令入口定义在 commands/gsd/stats.md执行骨架在 get-shit-done/workflows/stats.md数据聚合实现在 sdk/src/query/progress.ts阶段模式信息来自 sdk/src/query/roadmap.ts行为契约由 tests/stats-mvp-display.test.cjs 守护。它不写入任何项目状态只读地汇总.planning/目录与 Git 历史输出一份含阶段、计划、需求、Git、时间线五大板块的统计快照并可附加 MVP 模式阶段摘要。若你的项目尚未执行/gsd:new-project无.planning/目录stats 会提示先初始化其余情况下/gsd:stats或gsd-sdk query stats.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），仅供参考