get-shit-done 修复 3599 深度解析：roadmap get-phase 如何正确命中 project-code 前缀阶段 ID-二趣网

get-shit-done 修复 #3599 深度解析：roadmap get-phase 如何正确命中 project-code 前缀阶段 ID

【免费下载链接】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

本文基于仓库中的变更记录 .changeset/3599-roadmap-get-phase-project-code-prefix.md，讲清 get-shit-done（GSD 元提示与规格驱动开发系统）中roadmap get-phase子命令的一个正则匹配缺陷及其修复方案：当阶段 ID 带有项目代号前缀（如PROJ-42）时，命令曾查不到 ROADMAP.md 中真实的### Phase PROJ-42:标题。读完本文，你能理解该命令背后的“两遍查找（two-pass）”设计、phaseMarkdownRegexSourceExact()新辅助函数的职责边界，以及它与历史修复 #3537、#2391 之间如何互相保约而不互相破坏。

背景：GSD 的阶段 ID 体系与 ROADMAP 散文解析

get-shit-done 以.planning/ROADMAP.md作为项目规划的单一事实来源，阶段以 Markdown 标题形式书写，形如### Phase 2.7: 功能名。解析阶段标题的入口是 get-shit-done/bin/lib/roadmap.cjs 中的cmdRoadmapGetPhase，它把「调用方传入的阶段 ID」转换成一段正则片段，再拼进#{2,4}\s*Phase\s+<片段>:\s*([^\n]+)这样的标题匹配模式中。

问题在于，阶段 ID 存在多种合法形态。从核心库的normalizePhaseName()可以看出系统支持的输入：

标准数字阶段：1、01、12A、12.1（整数部分可补零、可带字母后缀、可带小數位）；
带 project-code 前缀的目录名形态：CK-01-name（project_code配置会出现在阶段目录名中）；
自定义阶段 ID：PROJ-42、AUTH-101（normalizePhaseName对这类非数字 ID 原样返回）。

其中两类形态之间天然存在「错位」：

补零错位（#3537 / #2391）：skill 或 CLI 解析后传入补零形态02.7，而人类手写的 ROADMAP 惯用未补零的### Phase 2.7:。为此，core.cjs 提供了phaseMarkdownRegexSource()：先剥掉 project-code 前缀，再把整数部分的 leading zero 去掉、重新以0*前缀输出，使片段同时匹配2.7与02.7。其源码注释明确记录了动机：

function phaseMarkdownRegexSource(phaseNum) { const stripped = String(phaseNum).replace(/^[A-Z]{1,6}-(?=\d)/i, ''); const match = stripped.match(/^0*(\d+)([A-Z])?((?:\.\d+)*)$/i); if (!match) return escapeRegex(phaseNum); const integer = match[1].replace(/^0+/, '') || '0'; const letter = match[2] ? escapeRegex(match[2]) : ''; const decimal = match[3] ? escapeRegex(match[3]) : ''; return `0*${escapeRegex(integer)}${letter}${decimal}`; }

前缀错位（本次 #3599）：PROJ-42这类 ID 本身就是一个自定义阶段 ID，ROADMAP 里真实写的是### Phase PROJ-42:。但上面的phaseMarkdownRegexSource()会先剥掉PROJ-前缀再生成0*42——于是roadmap get-phase PROJ-42实际生成的正则是0*42。

缺陷机理：剥前缀后的正则丢失了「精确身份」

用0*42这段片段去匹配 ROADMAP 时会出现两种坏结果（回归测试文件 tests/bug-3599-roadmap-get-phase-project-code-prefix.test.cjs 头部注释对此有完整描述）：

若 ROADMAP 里只有### Phase PROJ-42:而没有### Phase 42:，0*42匹配不到任何标题，命令返回found: false——变更记录里描述的行为就是「roadmap get-phase PROJ-42now matches### Phase PROJ-42:instead of returningfound: false」；
若 ROADMAP 里恰好还有一个同尾数的裸数字标题### Phase 42:，0*42会交叉命中它，把属于42的阶段内容错配给PROJ-42查询。

还有一个微妙的实现陷阱：phaseMarkdownRegexSource()的 docstring 承诺「对非数字 ID 回退到escapeRegex(phaseNum)」，但剥前缀之后PROJ-42变成了纯数字42，if (!match)这个回退分支对项目代号前缀 + 数字的 ID 而言永远不可达——承诺的 fallback 恰好覆盖不到最需要它的输入。

修复方案：新增精确形态辅助函数 + 调用点两遍查找

修复分两层，且刻意把「选哪种正则」的决策放在调用点而非正则内部。

第一层：`phaseMarkdownRegexSourceExact()`——只回答「有没有前缀」

新辅助函数位于 core.cjs，实现极短：

function phaseMarkdownRegexSourceExact(phaseNum) { const raw = String(phaseNum); if (!/^[A-Z]{1,6}-(?=\d)/i.test(raw)) return null; return escapeRegex(raw); }

语义：

输入形如PROJ-42（1~6 位大写字母 + 连字符 + 至少一位数字开头）时，返回整体转义后的精确片段PROJ\-42，用于匹配### Phase PROJ-42:这一保留前缀的标题；
输入不带前缀（如42、02.7、12A.1）时返回null，表示调用方只需要既有的phaseMarkdownRegexSource()数值形态即可。

这样把「是否需要精确前缀匹配」的判定与「数值补零容忍」的片段构造解耦，phaseMarkdownRegexSource()的 #3537 契约保持原样，所有既有调用方零改动。

第二层：`cmdRoadmapGetPhase`的两遍查找

修复后的命令实现见 roadmap.cjs。查找顺序是：

精确前缀遍：若phaseMarkdownRegexSourceExact(phaseNum)非 null，先用精确片段搜索「当前里程碑切片」（extractCurrentMilestone产出的内容），未命中再搜索剥离已交付里程碑后的全量 ROADMAP（stripShippedMilestones）；
补零容忍遍（#3537）：只有精确遍落空，才用phaseMarkdownRegexSource(phaseNum)生成0*42形态片段，按同样的「当前里程碑优先、全量兜底」策略搜索。

源码中的注释解释了为什么不在正则内部用「PROJ\-42|0*42」这样的选择式一步完成：

Doing this at the call site (instead of inside phaseMarkdownRegexSource) avoids the alternation-order ambiguity where a bare### Phase 42:heading in the same document would intercept the match for aPROJ-42query.

即选择式正则的匹配顺序会让同文档中的裸### Phase 42:标题拦截掉PROJ-42查询；两遍查找则保证「先精确、后宽松」的优先级在逻辑上成立，同时不破坏CK-01目录名形态映射到### Phase 1:散文的既有契约。

命中之后的输出结构

无论哪一遍命中，最终都交给 searchPhaseInContent() 解析出结构化结果：匹配##～####级标题并截取到下一个阶段标题之间的区块，提取**Goal:**、**Mode:**（统一小写后规范化）与**Success Criteria**编号列表，返回：

{ found: true, phase_number: phaseNum, // 标题中「如所写」的规范 token phase_name, // 标题冒号后的名称 goal, mode, success_criteria, // 字符串数组 section, // 完整章节原文 }

另有两条兜底路径：标题缺失但概要清单里存在- [ ] **Phase X:** ...时，返回error: 'malformed_roadmap'提示 ROADMAP 需要「清单 + 详情节」双格式；ROADMAP.md 不存在时返回{ found: false, error: 'ROADMAP.md not found' }。加--json参数即输出上述 JSON payload，这正是回归测试断言的字段（found、phase_name、goal）。

SDK 侧的镜像实现

该仓库同时维护一套 TypeScript 的 SDK 查询层，roadmap.get-phase在 sdk/src/query/roadmap.ts 中作为roadmapGetPhase处理器存在，是cmdRoadmapGetPhase的移植版本（源码注释标注 "Port of cmdRoadmapGetPhase from roadmap.cjs lines 75-113"）。#3599 的修复在 SDK 侧保持了逐行对等（parity）：

phaseMarkdownRegexSourceExact() 与 core.cjs 版本逐语句一致，注释直接写明「parity with core.cjs phaseMarkdownRegexSourceExact, lines 691-708」；
roadmapGetPhase内部同样先计算exactEscaped（精确前缀片段）与numericEscaped（phaseMarkdownRegexSource片段），先试精确片段、落空再走补零容忍片段，且都遵循「当前里程碑切片 → 全量内容」的两级搜索。

另外，CLI 侧的子命令路由在 roadmap-command-router.cjs 中把get-phase转发到 SDK 处理器roadmap.get-phase——也就是说路由层与底层解析层的两条实现在同一个语义下工作，修复对两条链路同时生效。

回归测试：四个用例钉死四种行为

tests/bug-3599-roadmap-get-phase-project-code-prefix.test.cjs 基于node:test，通过runGsdTools()在临时项目中真实执行roadmap get-phase ... --json，四个用例分别覆盖：

正向命中：ROADMAP 只含### Phase PROJ-42: Custom phase，查询PROJ-42必须found: true，且phase_name/goal与该标题一致；
反向不交叉：查询裸42时，绝不能命中### Phase PROJ-42:（防止修成「双向交叉匹配」）；
#3537 契约保持：查询CK-01（project-code 前缀 + 补零）时，仍须解析到未补零的### Phase 1:散文——证明新修复没有弄丢旧契约；
双形态共存消歧：同一 ROADMAP 同时存在### Phase 42:与### Phase PROJ-42:时，两个查询各自命中自己那条。

这四个用例合起来构成一个完整的「不回归、不交叉、能消歧」矩阵，在本地可用node --test tests/bug-3599-roadmap-get-phase-project-code-prefix.test.cjs直接复验。

修复的定位与适用前提

契约关系：#3599 是在 #3537（phaseMarkdownRegexSource()补齐到全部 8 个正则构建点，见变更记录）的基础上，把「前缀保留」这一维度从正则内部剥离到调用点，两条契约（前缀 ID 精确匹配 / 目录补零形态映射数字散文）各自独立可验证；
适用前提：该修复在仓库中以待发布的 changeset 形式存在（type: Fixed, issue: 3599），适用对象是配置了project_code、ROADMAP 中使用### Phase PROJ-42:这类带前缀标题的项目；对纯数字阶段与无 project-code 的项目行为不变（phaseMarkdownRegexSourceExact()对无输入返回 null，直接走原路径）；
相关变更：同批 changeset 中的 3600-milestone-phase-filter-project-code.md 处理的是 milestone 阶段过滤侧的同类前缀问题，与本篇的get-phase查找侧互为补充。

小结

#3599 修复看似只涉及一个正则片段，实际示范了一套处理「多形态 ID 命名空间」的可复用模式：用一个廉价的判别函数（phaseMarkdownRegexSourceExact()，仅判断前缀存在性）把「精确形态」与「宽松形态」的正则构造拆开，再由调用点按「先精确、后宽松」的顺序做两遍查找，从而同时满足新契约（PROJ-42→### Phase PROJ-42:）、旧契约（CK-01→### Phase 1:）和消歧要求（42与PROJ-42互不串扰），并在 CLI 与 SDK 两套实现中保持逐行对等。对于同样以 Markdown 散文承载结构化状态（ROADMAP、STATE 等）的规格驱动工具链，这种「判别 + 两遍查找 + 双向回归用例」的做法值得直接借鉴。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析