【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载导读本文围绕 gsd-core 仓库中一张Fixed类型的 changeset.changeset/sturdy-ravens-hum.mdPR #4719展开深入讲解verify references命令如何校验文档中的文件引文citation以及本次修复如何解决带行号后缀如src/foo.ts:42、src/foo.ts:1-20的引文被静默丢弃或误报缺失的问题。读完本文你将掌握verify references的完整用法、两种引文语法的匹配规则、行号后缀剥离的实现原理以及对应的回归测试矩阵可直接用于排查和验证自己仓库中的引用完整性。一、变更速览一张 changeset 卡片讲了什么gsd-core 使用 changeset 管理变更记录。本次变更的原始卡片内容如下--- type: Fixed pr: 4719 --- **verify references no longer mishandles :LINE citations** — backtick citations with a line suffix (e.g. src/foo.ts:42) are now checked instead of silently dropped, and -citations with a line suffix resolve against the underlying file instead of being reported missing (#4678)。要点拆解类型Fixed属于缺陷修复类变更PR4719对应 issue #4678两个修复面反引号引文backtick citation带行号后缀如src/foo.ts:42时此前会被静默丢弃、不参与校验修复后会被正常检查引文-citation带行号后缀时此前会因把:42当成路径的一部分而误报文件缺失修复后先剥离行号后缀再针对底层文件做存在性解析。修复的核心效果是引文输出中保留原始文本含行号后缀但存在性判定基于剥离后缀后的真实路径。二、命令定位verify references是干什么的在 gsd-core 的 CLI 工具集中verify references属于Verification Commands验证命令一族官方文档docs/CLI-TOOLS.md给出的用法是# Check -refs paths resolve node gsd-tools.cjs verify references file与它同族的验证命令还包括node gsd-tools.cjs verify-summary path [--check-count N] # 校验 SUMMARY.md node gsd-tools.cjs verify plan-structure file # 校验 PLAN.md 结构与任务 node gsd-tools.cjs verify phase-completeness phase # 校验各计划均有摘要 node gsd-tools.cjs verify references file # 校验 -引用与路径可解析 node gsd-tools.cjs verify commits hash1 [hash2] ... # 批量校验 commit 哈希 node gsd-tools.cjs verify artifacts plan-file # 校验 must_haves.artifacts node gsd-tools.cjs verify key-links plan-file # 校验 must_haves.key_links该命令的典型使用场景是在.planning/规划文档、SUMMARY 或任意 Markdown 文档中检查其中引用的仓库文件路径是否真实存在——防止计划文档引用了一个不存在的文件这类漂移问题。在命令路由与别名层src/command-aliases.cts中verify references同样被登记属于 gsd-tools 稳定命令面的一部分。命令接收一个file参数路径可以是绝对路径也可以是相对当前工作目录的相对路径源码中通过path.isAbsolute(filePath)分支处理见下文。三、两种引文语法ref与pathverify references从文档内容中提取两类引文分别使用不同的正则1.引文-citationconst atRefs content.match(/([^\s\n,)]\/[^\s\n,)])/g) || [];匹配以开头、包含/、且不含空白/换行/逗号/右括号的连续片段典型的写法是src/app.js或src/app.js:42对引文其解析支持~/前缀——fsRef.startsWith(~/)时拼接到process.env[HOME]下否则拼接到当前工作目录cwd。2. 反引号引文backtick citationconst backtickRefs content.match(/([^]\/[^]\.[a-zA-Z]{1,10}(?::\d(?:-\d)?)?)/g) || [];匹配反引号包裹、含/、且带文件扩展名\.[a-zA-Z]{1,10}的路径末尾允许可选的行号后缀(?::\d(?:-\d)?)?即支持:42单行形式与:1-20行区间形式仅凭反引号但无扩展名/无目录分隔符的普通单词如helper不会被识别为引文对提取出的每条反引号引文还会做三重过滤cleanRef.startsWith(http)→ 跳过网络 URL 不查磁盘cleanRef.includes(${)→ 跳过模板表达式如${variable}/path/file.jscleanRef.includes({{)→ 跳过模板占位符已出现在found/missing中的即与引文重复→ 跳过去重。之所以要跳过模板表达式是因为这类反引号内容只是代码片段而非真实路径测试用例 tests/verify.test.cjs 中专门验证了${variable}/path/file.js应被整体跳过输出total为 0。四、修复核心stripLineSuffix的实现原理本次修复的关键在于一行辅助函数位于 src/verify.cts// #4678: citations may carry a trailing line suffix (:42, :1-20) that // describes a location inside the file, not part of the path itself. function stripLineSuffix(ref: string): string { return ref.replace(/:\d(?:-\d)?$/, ); }该函数用正则:\d(?:-\d)?$只剥离末尾的:数字或:数字-数字后缀src/foo.ts:42→src/foo.tssrc/foo.ts:1-20→src/foo.tssrc/foo.ts无后缀→ 原样返回注意它与$锚定的配合只有后缀出现在行尾时才剥离因此正常路径中如果恰好包含冒号数字例如不含扩展名段落的边缘情况不会被误伤——因为反引文正则本就要求扩展名在前。修复前后行为对比输入引文修复前行为修复后行为src/utils/helper.js:7文件存在静默丢弃不参与统计剥离后缀 → 解析src/utils/helper.js→ 计入foundsrc/gone.ts:99文件不存在静默丢弃漏报剥离后缀 → 解析失败 → 计入missing且保留原文src/gone.ts:99src/app.js:42文件存在把:42当路径一部分 → 误报 missing剥离后缀 → 解析src/app.js→ 计入foundsrc/gone.ts:1文件不存在误报src/gone.ts:1缺失巧合正确剥离后缀 → 解析src/gone.ts→ 计入missing保留原文核心差异在于修复前反引号引文一旦带行号后缀就不匹配正则、直接不查引文则把行号后缀误当作路径导致解析错位。修复后两类引文统一先剥离后缀再做磁盘存在性检查。五、完整实现cmdVerifyReferences逐段解读整个校验流程位于 src/verify.cts 的cmdVerifyReferences逻辑如下function cmdVerifyReferences(cwd: string, filePath: string, raw: boolean): void { if (!filePath) { error(file path required); } const fullPath path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath); const content safeReadFile(fullPath); if (!content) { output({ error: File not found, path: filePath }, raw); return; } const found: string[] []; const missing: string[] []; // 1) -citations const atRefs content.match(/([^\s\n,)]\/[^\s\n,)])/g) || []; for (const ref of atRefs) { const cleanRef ref.slice(1); const fsRef stripLineSuffix(cleanRef); const resolved fsRef.startsWith(~/) ? path.join(process.env[HOME] || , fsRef.slice(2)) : path.join(cwd, fsRef); if (fs.existsSync(resolved)) { found.push(cleanRef); } else { missing.push(cleanRef); } } // 2) backtick citations const backtickRefs content.match(/([^]\/[^]\.[a-zA-Z]{1,10}(?::\d(?:-\d)?)?)/g) || []; for (const ref of backtickRefs) { const cleanRef ref.slice(1, -1); if (cleanRef.startsWith(http) || cleanRef.includes(${) || cleanRef.includes({{)) continue; if (found.includes(cleanRef) || missing.includes(cleanRef)) continue; const resolved path.join(cwd, stripLineSuffix(cleanRef)); if (fs.existsSync(resolved)) { found.push(cleanRef); } else { missing.push(cleanRef); } } output( { valid: missing.length 0, found: found.length, missing, total: found.length missing.length, }, raw, missing.length 0 ? valid : invalid, ); }执行流程可概括为四步读文件目标文件不存在时直接输出{ error: File not found, path }扫引文逐条剥离行号后缀、解析路径支持~/主目录展开、查磁盘扫反引号引文过滤 URL / 模板表达式 / 重复项再剥离行号后缀并查磁盘汇总输出valid、found、missing、total四项字段文本判定为valid或invalid。值得注意的一个细节found/missing数组中保存的是剥离前的原始引文文本如src/gone.ts:99而非src/gone.ts这样输出报告能精确指向用户在文档中写下的那行引文便于定位修复位置——测试断言中专门校验了这一点。六、回归测试矩阵#4678 用例逐条拆解本次修复配套的回归测试位于 tests/verify.test.cjs 的verify references commanddescribe 块中核心用例为#4678: line-numbered citations are checked, not dropped or misreported。测试构造的文档内容如下- src/gone.ts:99 - src/utils/helper.js:7 - src/app.js:42 - src/gone.ts:1 - src/utils/helper.js - src/gone.ts - src/app.js其中src/app.js与src/utils/helper.js已创建src/gone.ts不存在。测试断言output.total 7——所有 7 条引文含带行号后缀与不带后缀的都必须进入统计不允许任何一条被静默丢弃output.found 4——src/utils/helper.js:7、src/utils/helper.js、src/app.js:42、src/app.js均解析成功missing同时包含src/gone.ts:99、src/gone.ts:1、src/gone.ts三条——保留原始引文文本valid false——存在缺失引文时文档判定为 invalid。配套的第二个用例#4678: an all-missing line-numbered document is not reported valid构造了src/gone.ts:99与src/also-gone.ts:1-20两条全部缺失的引文断言total 2、missing.length 2、valid false——防止行号区间后缀导致正则不匹配、从而整篇误报通过的回归。再结合同模块的其他既有用例可得到完整的测试矩阵测试用例输入期望reports valid when all referenced files existsrc/app.js文件存在validtrue、found1reports missing for nonexistent referenced filessrc/missing.jsvalidfalse、missing含src/missing.jsdetects backtick file pathssrc/utils/helper.jsfound 1skips backtick template expressions${variable}/path/file.jstotal0#4678 行号引文不丢不漏7 条混合引文total7、found4、缺失项保留原文#4678 全缺失文档不得误报 valid两条带行号/行区间后缀的缺失引文total2、missing2、validfalsereturns error for nonexistent file传入不存在的文档路径输出error字段这套矩阵既锁定了反引号 行号与 行号两种修复路径也防止了模板表达式跳过、缺失误报 valid 等相邻回归。七、输出契约与集成方式命令支持rawJSON输出模式无论文本模式还是 JSON 模式核心字段保持一致{ valid: false, found: 4, missing: [src/gone.ts:99, src/gone.ts:1, src/gone.ts], total: 7 }validmissing.length 0时为true否则falsefound/missing已解析成功 / 未找到的引文计数与明细totalfound missing代表实际纳入统计的引文总数——修复后的一个关键语义是 total 必须等于文档中所有可识别引文的数量这是不静默丢弃的直接体现。文本模式下命令以valid/invalid作为终态词便于在 shell 脚本或 CI 流程中做grep判定。由于 gsd-tools 是单文件 CLIgsd-tools.cjs该命令天然适合接入 pre-commit 钩子或计划文档评审流水线。八、使用建议与边界说明引文写法规范推荐统一使用path:line或path:line的行号后缀形式它既能表达指向文件的第几行又能被verify references正确解析行区间使用:1-20形式同样受支持。路径解析基准命令以当前工作目录cwd为基准拼接相对路径引文额外支持~/前缀展开到主目录。涉及目录穿越的绝对路径或../越界引用不属于本命令的校验范畴同族命令verify key-links专门负责from:/to:的项目目录约束。过滤规则反引号引文中以http开头、含${或{{的内容会被跳过避免把网络 URL 与模板表达式误当成本地文件。边界与前提本文所述行为以当前仓库源码src/verify.cts与测试tests/verify.test.cjs为准命令入口为node gsd-tools.cjs verify references filedocs/CLI-TOOLS.md。若你在自己的仓库中使用建议先运行verify references检查一个已知含缺失引文的文档观察missing明细是否保留了带行号后缀的原文以确认修复版本已生效。总而言之#4678 的修复让verify references从对行号引文睁一只眼闭一只眼变成了每条引文都给出明确结论带:LINE后缀的引文不再漏检、不再误报报告中的每一条missing都能精确对应到文档里的原始书写为规划文档的引用完整性提供了一道可靠的自动化闸门。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐Gemini CLI MCP 资源工具详解list_mcp_resources 与 read_mcp_resource 的发现与读取机制Gemini CLI MCP 资源工具详解list_mcp_resources 与 read_mcp_resource 的发现与读取机制 Gemini CLIgsd-core 中 verify artifacts 命令的目录路径容错修复从 EISDIR 崩溃到逐项独立校验gsd core 中 verify artifacts 命令的目录路径容错修复从 EISDIR 崩溃到逐项独立校验 导读 verify artifacts 是gsd-core 修复解读3381 修复 —— /gsd-verify-work --ws 通过 SDK 解析工作流阶段gsd core 修复解读 3381 修复 —— /gsd verify work ws 通过 SDK 解析工作流阶段 本篇文章基于 .changeset/a上一篇Tomcat JSP页面缓存失效主动与被动触发的完整指南下一篇告别繁琐特征工程Ludwig自动特征处理框架AutoFE实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考