gsd-core 斜杠命令命名空间治理：从 bug 2543 到“目录级矩阵”双层不变量（PR 164）

【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本文以归档变更集 .changeset/archived/nimble-seals-munch.mdPR #164type: Fixed为主线讲清 gsd-core 是如何把/gsd:cmd冒号与/gsd-cmd连字符两套斜杠命令书写形式划分成“源码层”与“运行时发射层”的双层契约并借助一条经过范围限定的回归扫描scoped invariant、一份目录级矩阵文档和一个双向文本规范化器把散落在 workflow/reference 文档中的失效命令 token 系统性纠正掉的。读完本篇你可以复现该不变量的扫描逻辑、理解排除 runtime-emitter 上下文的动机并知道在修改任何/gsd-//gsd:token 前应该遵循哪些规则。1. 变更集原文PR #164 做了三件事归档变更集的完整正文只有一行但它概括了一次典型的“多表面契约修复”Re-activate bug-2543 scan as scoped invariant (excludes runtime-emitter contexts), rewrite CONTEXT.md slash-command guidance as directory-level matrix, replace dead /gsd-* tokens in workflow and reference docs with live registry forms.对应三项交付重新激活 bug-2543 扫描但改为“带范围的不变量”——扫描只覆盖 Claude 面向的源码目录并显式排除 runtime-emitter 上下文把 CONTEXT.md 中的斜杠命令书写指引重写为“目录级矩阵”directory-level matrix——按目录维度规定每个目录应使用冒号还是连字符形式把 workflow 与 reference 文档中的失效/gsd-*token 替换为“活注册表”live registry形式——即只重写commands/gsd/*.md中真实注册过的命令名而非任何看起来像命令的字符串。2. 背景为什么存在两套书写形式从 tests/slash-command-namespace.test.cjs 折叠进来的 bug-2543 测试头注释可以看到该仓库命名空间演进的完整脉络源码仓库面向 Claude 命令注册命令文件位于commands/gsd/cmd.md早期 Claude Code 会把子目录布局解析为命名空间斜杠命令/gsd:cmd冒号形式。issue #3443 之后仓库在 Claude 面向的源码文本中重新确立/gsd:cmd为规范形式非 Claude 运行时在安装期做转换安装器把/gsd:cmd转写成/gsd-cmd连字符形式再落盘这是 bug #3584 定义的“runtime-emitter 契约”扁平命令布局#1367安装到 Claude Code 本地时命令写成扁平的.claude/commands/gsd-cmd.md而非commands/gsd/cmd.md子目录避免再次产生冒号命名空间这一布局由集成测试 tests/slash-command-namespace.test.cjs 的 E 套件锁定。于是形成了测试头注释中描述的双层模型two-tier model层目录/文件规范形式依据Claude 面向的源码文本commands/、agents/、gsd-core/workflows/、gsd-core/references/、gsd-core/templates/、hooks/、.clinerules/gsd:cmd冒号#3443runtime-emitter 上下文gsd-core/bin/lib/runtime-slash.cjs、*.generated.cjs等/gsd-cmd连字符bug #3584这套“目录级矩阵”在 CONTEXT.md 中登记为故障排查条目当tests/slash-command-namespace.test.cjs由原bug-2543-gsd-slash-namespace折叠而来consolidation epic #1969失败时修复指引是“先查 Slash-command form 一节再动手——agents//commands/用冒号runtime emitter 用连字符”见 CONTEXT.md 的 “Slash command two-tier confusion” 条目。3. PR #164 的第一项修复把 bug-2543 扫描重激活为“带范围”的不变量3.1 为什么需要“重激活 加范围”测试头注释记录了一次真实事故PR #154 的第一轮处理中Agent 应用了一条过时的全局不变量“任何地方都不允许出现/gsd-cmd”把 runtime-emitter 模块里本来正确的连字符形式改回了冒号形式直接破坏了 bug-3584 契约下 tests/init-manager.test.cjs 所辖的测试。PR #164 的 Codex 对抗性评审正是发现了“旧不变量仍然在裸奔”的风险才要求以显式排除清单重激活这条扫描——这正是变更集里 “scoped invariant (excludes runtime-emitter contexts)” 的来历。3.2 扫描范围与排除逻辑当前 tests/slash-command-namespace.test.cjs 的实现要点扫描目录SEARCH_DIRSgsd-core/workflows、gsd-core/references、gsd-core/templates、commands/gsd、agents、hooks顶层文件为.clinerules有意排除gsd-core/bin/lib注释明确说明runtime-slash.cjs与*.generated.cjs位于该目录按 bug-3584 契约使用连字符形式“整个 bin/lib 树都是 runtime-emitter 领地扫描它会产生误报”与生产脚本保持同步SKIP_DIRSnode_modules、dist、.turbo直接从 scripts/fix-slash-commands.cjs 引入保证测试目录遍历器与修复脚本的遍历器始终一致扩展名集合.md/.cjs/.js则按 no-source-grep 标准有意与修复脚本额外覆盖.ts/.tsx保持“合法分叉”。3.3 “活注册表”驱动的失效 token 判定测试不硬编码命令清单而是从真实注册表现读const cmdNames fs.readdirSync(COMMANDS_DIR) // commands/gsd/*.md .filter(f f.endsWith(.md)) .map(f f.replace(/\.md$/, )) .sort((a, b) b.length - a.length); // 最长优先避免部分匹配 const retiredPattern new RegExp(/gsd-(${cmdNames.join(|)})(?[^a-zA-Z0-9_-]|$));核心不变量测试断言在所有 Claude 面向源码文件中该retiredPattern的命中数必须为 0失败信息会列出前 10 条文件:行号: 内容并提示 “use /gsd:cmd instead”见 tests/slash-command-namespace.test.cjs。这就是变更集第三项 “replace dead /gsd-* tokens … with live registry forms” 的机械化体现只有活注册表中真实存在的命令名才会被判定/被重写/gsd-sdk、/gsd-tools这类 CLI 二进制标识符永远不被触碰。测试还锁定了配套行为命令文件名必须使用连字符 slug下划线会污染生成的 skill/自动补全名以及修改排除清单的纪律——“不要在不更新 bug-3584 测试和 CONTEXT.md 目录级矩阵的情况下扩展 RUNTIME_EMITTER_EXCLUDES”。4. 双向规范化器scripts/fix-slash-commands.cjs 的源码剖析支撑上述不变量的工具是 scripts/fix-slash-commands.cjs它同时是一个一次性修复脚本和一个可复用库提供两个方向的纯函数转换导出函数方向用途transformContent(src, cmdNames)连字符 → 冒号/gsd-cmd→/gsd:cmd保持 monorepo 源码/文档/workflow 处于激活的冒号形式仓库内修复transformContentToHyphen(src, cmdNames)冒号 → 连字符gsd:cmd//gsd:cmd→gsd-cmd安装期为使用 #2808 连字符规范形式的运行时做 skill 安装转换几个工程细节值得注意空注册表短路buildPattern在cmdNames为空时返回null。注释解释了原因——空输入会编译出/gsd-()(?…)/g这类正则仍会在任何/gsd-token 后匹配把文本改写出孤立的/gsd:短路后调用方对缺失/空注册表安全地 no-op而不是执行一次范围失控的批量改写最长优先 词边界两个方向都按命令名长度降序排序并用前瞻/后顾右侧(?[^a-zA-Z0-9_-]|$)冒号方向左侧(?![a-zA-Z0-9_-])保证只命中完整 token——/gsd-plan-phase-extra不会被误判为plan-phase幂等性已是规范形式的输入原样返回重装重放转换不会把文本改坏。对应测试直接调用transformContent验证/gsd-plan-phase被重写为/gsd:plan-phase且连字符形式不残留一次重写多处出现对已是冒号形式的输入是 no-op/gsd-sdk、/gsd-tools保持不动词边界防止部分匹配见 tests/slash-command-namespace.test.cjs。5. 周边不变量同一命名空间问题的三个表面PR #164 的矩阵治理并非孤立工作它与后续针对“安装后表面”的回归测试共同覆盖了同一契约的三个表面同在一个折叠测试文件中可对照阅读agent 主体表面#3677Claude/Qwen/Hermes 注册连字符name:但逐字拷贝 agent 主体导致冒号引用泄漏到安装产物修复是bin/install.js导出纯谓词shouldNormalizeHyphenNamespaceInAgentBody(runtime) 助手normalizeAgentBodyForRuntime在运行时特定转换之后、写盘之前条件性地应用transformContentToHyphencommand 主体表面#3683copyWithPathReplacement曾按原样拷贝commands/gsd/*.md静态散文如 plan-phase.md 引用/gsd:execute-phase被模型逐字回显workflow/reference 表面#3683 续gsd-core/目录曾因if (isCommand)守卫而跳过归一化用户实测/gsd-discuss-phase输出以不可路由的/gsd:nextcommand结尾同时 R 套件对▶前缀的“路由块”行做正向断言——不仅要求连字符形式存在还要求它没被省略。这些测试都遵循同一设计哲学文件头部的 allow-test-rule 注释workflow/agent/command 的.md文本本身就是运行时加载的部署契约断言其内容是对安装变换的行为测试而非源码 grep 表演。6. 如何验证与遵循该治理在仓库中可以直接运行相关测试来验证双层不变量当前成立node --test tests/slash-command-namespace.test.cjs它覆盖折叠进来的三个回归套件bug-2543、bug-3677、bug-3683其中后两个包含真实安装集成测试会执行node bin/install.js --claude --local --no-sdk到临时目录并检查产物。对维护者CONTEXT.md 给出的操作规程是触碰任何/gsd-或/gsd:token 前先查 CONTEXT.md 的 Slash-command form 指引Claude 面向目录agents/、commands/等矩阵左列一律冒号runtime emitter 一律连字符若需新增 runtime-emitter 排除项必须同步更新 bug-3584 测试与 CONTEXT.md 矩阵——三者测试、脚本、文档构成一个必须协同变更的闭环。7. 小结PR #164nimble-seals-munch展示了一条可复用的治理路径当同一“命令名”在不同部署层使用不同语法时用目录级矩阵明确所有权、用范围限定的扫描测试活注册表 显式排除替代容易过火的全局断言、用双向纯函数规范化器让“仓库内修复”与“安装期转换”共用同一套最长优先、词边界安全的重写逻辑并把事故教训PR #154 的旧不变量回改写进测试头注释与 CONTEXT.md 排障条目。对 gsd-core 这类“文本即产品”的仓库来说源码文本、安装产物与回归测试三者对齐正是斜杠命令可路由性的根本保证。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐GSD 斜杠命令命名空间防漂移实战从 /gsd: 残留泄漏到安装期规范化get-shit-doneGSD 斜杠命令命名空间防漂移实战从 /gsd: 残留泄漏到安装期规范化get shit done GSDget shit done是一套为 Clau人工智能AI 应用提示工程开发工具工作流自动化AI Agentgsd-core 运行时斜杠命令输出机制从 PR 3584 看 /gsd-cmd 与 $gsd-cmd 的单一格式化器gsd core 运行时斜杠命令输出机制从 PR 3584 看 /gsd cmd 与 $gsd cmd 的单一格式化器 导读 gsd core 会在多处运tchMaterial-parser把智慧教育平台的电子课本解析成本地 PDFtchMaterial parser把智慧教育平台的电子课本解析成本地 PDF 在平台上翻一本电子课本觉得有用想存成 PDF 带回家结果页面上找不到下载网页爬虫教育上一篇如何零基础搞定明日方舟公开招募自动化MAA 自动公招实操教程下一篇taskt面向 Windows 办公场景的免费开源 RPA 自动化工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考