get-shit-done 技能安装中的命名空间归一化拆解 SKILL.md 内/gsd:cmd残留引用修复#3583【免费下载链接】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一个面向 Claude Code 的轻量级 meta-prompting / 上下文工程 / 规范驱动开发系统的一则 bugfix changeset.changeset/graceful-tigers-fly.md展开当仓库把 Claude 命令command安装成 Claude / Qwen / Hermes 的 SKILL.md 技能时命令正文中遗留的旧式/gsd:cmd冒号引用如何被统一改写为规范化的gsd-cmd连字符形式。读完本文你将理解 GSD 命令命名空间“存储方言”与“运行时方言”的差异、共享转换器fix-slash-commands.cjs的正则安全设计、安装器convertClaudeCommandToClaudeSkill的调用链以及对应回归测试的防护策略可直接迁移到任何需要跨运行时做“文本规范化”的 Agent 工具安装管线中。一个 changeset 背后的问题正文里的旧引用graceful-tigers-fly.md以极简的 frontmattertype: Fixed、pr: 3583记录了一次行为修复核心陈述如下Claude skill installconvertClaudeCommandToClaudeSkillcopyCommandsAsClaudeSkills现在会使用共享转换器fix-slash-commands.cjs中新增的transformContentToHyphen把 SKILL.md 正文中退役的/gsd:cmd引用归一化为规范的gsd-cmd连字符形式。这看起来只是一行改动但它实际串联起了 GSD 系统内三个层面的问题历史命名迁移、安装期内容转换、运行时命名空间一致性。下面分别从仓库源码逐层拆解。问题根源仓库里存在两种“命令引用方言”方言一冒号形式/gsd:cmd仓库存储的规范形态GSD 的每个命令本体位于 commands/gsd/如plan-phase.md、review.md。阅读 scripts/fix-slash-commands.cjs 的头部注释可以发现仓库内部源码、文档与 workflow 的正文统一使用冒号形式/gsd:cmd作为书写规范默认方向的transformContent把退役的/gsd-cmd→/gsd:cmd目的是“keep monorepo sources, docs, and workflows in the active colon form”维持 monorepo 的活跃冒号形态仅当把内容安装到特定运行时时才走反向的transformContentToHyphen。也就是说命令正文里如果提到兄弟命令例如“运行/gsd:plan-phase后再执行/gsd:review”写的是冒号形式。方言二连字符形式gsd-cmd运行时注册的规范形态Claude Code以及 Qwen、Hermes 的对应实现以目录名 / frontmattername:注册技能。根据 tests/bug-2808-skill-hyphen-name.test.cjs 头部注释记录的完整历史#2643 时代bin/install.js中的skillFrontmatterName()曾把连字符目录名gsd-add-phase转回冒号gsd:add-phase因为当时 workflow 里用Skill(skillgsd:cmd)冒号形式调用#2808 之后所有 workflow 改为连字符形式调用skillFrontmatterName()也改为直接返回连字符形式见 bin/install.js 及其注释 “hyphen form as-is (gsd- ) — canonical since #2808”#3583 的漏网点frontmatter 的name:虽然在 #2808 已修正但SKILL.md 的正文仍然原样照搬命令源文件的冒号式引用导致安装出的技能在“以连字符注册技能”的运行时中出现失效链接——这正是 changeset 所说的 “body leakage is now eliminated”正文泄漏被消除。一个值得注意的例外是 Codex代码注释明确说明 “Codex must NOT use this helper”因为 Codex 适配器以$gsd-cmdshell 变量语法调用技能连字符形式天然正确。核心修复共享转换器 fix-slash-commands.cjs修复的落点是 scripts/fix-slash-commands.cjs。它同时是一个“一键批处理脚本”和“可被安装器、测试复用的纯函数库”实现双向的 GSD 斜杠命令命名空间归一化。反向转换transformContentToHyphen安装期调用的是反向方向fix-slash-commands.cjsfunction transformContentToHyphen(src, cmdNames) { const pattern buildColonPattern(cmdNames); if (!pattern) return src; return src.replace(pattern, (_, cmd) gsd-${cmd}); }它把/gsd:cmd与不带斜杠的gsd:cmd一律改写为gsd-cmd。正则的安全设计最长优先 双向词边界buildColonPatternfix-slash-commands.cjs体现了这个转换器最值得借鉴的部分function buildColonPattern(cmdNames) { if (!Array.isArray(cmdNames) || cmdNames.length 0) return null; const sorted [...cmdNames].sort((a, b) b.length - a.length); return new RegExp((?![a-zA-Z0-9_-])gsd:(${sorted.join(|)})(?[^a-zA-Z0-9_-]|$), g); }最长优先排序先匹配较长的命令名避免plan-phase尚未匹配、plan先命中的“部分匹配”误伤左侧负向后顾(?![a-zA-Z0-9_-])防止mygsd:plan-phase、prefix-gsd:review这类“嵌在大 token 内部”的伪引用被改写右侧前瞻(?[^a-zA-Z0-9_-]|$)防止把gsd:plan-phase-extra这类带后缀的词误截断空列表短路当命令注册表为空时直接返回null调用方整体 no-op绝不执行一次“宽泛的意外重写”。回归测试 bug-2808-skill-hyphen-name.test.cjs 中专门有三条用例覆盖这些边界gsd:plan-phase-extra不得被改写、mygsd:plan-phase不得被改写、混合输入中仅冒号形式被转换。命令白名单与“非命令豁免”命令名集合并非硬编码而是运行时从 commands/gsd/ 目录实时读取readCmdNames()扫描*.md并去掉后缀。两个方向都只改写已知命令非命令标识符如gsd-sdk、gsd-tools被刻意保留不动这是前向转换器就已确立的安全契约见 fix-slash-commands.cjs 注释。安装器调用链convertClaudeCommandToClaudeSkill 里发生了什么转换器真正的消费方在安装器 bin/install.js 中。一次性预计算命令名bin/install.js在模块顶层require转换器bin/install.js并在注释中说明原因每个技能都去fs.readdirSync加编译正则太浪费模块加载时计算一次即可传给所有技能转换——这是对大规模技能安装的典型性能优化。技能转换主函数convertClaudeCommandToClaudeSkillbin/install.js的核心流程为用extractFrontmatterAndBody拆分源命令的 frontmatter 与正文无 frontmatter 则原样返回取命令名列表调用方未传cmdNames时回退到readGsdCommandNames()对正文执行transformContentToHyphen(body, names)得到normalizedBody重建技能 frontmattername: gsd-cmd连字符规范形态、description用yamlQuote引号包裹防止[BETA]…这类 YAML flow 指示符破坏解析#2876 教训、保留argument-hint与agent、allowed-tools保持 YAML 多行列表对 Hermes 额外写入version其 SKILL.md 规范要求必填用于skill_view()报告稳定标识。代码中#3583的注释点明了设计意图让“安装出的 SKILL.md 正文”与“#2808 之后按连字符注册的name:”保持一致即正文引用的命令也必须是同一命名空间下的连字符形式。哪些运行时适用显式白名单而非黑名单bin/install.js定义了一个针对 Agent 正文处理的运行时集合bin/install.jsconst HYPHEN_NAME_AGENT_RUNTIMES new Set([claude, qwen, hermes]); function shouldNormalizeHyphenNamespaceInAgentBody(runtime) { if (typeof runtime ! string || runtime ) return false; return HYPHEN_NAME_AGENT_RUNTIMES.has(runtime); } function normalizeAgentBodyForRuntime(content, runtime, cmdNames) { if (!shouldNormalizeHyphenNamespaceInAgentBody(runtime)) return content; return transformContentToHyphen(content, cmdNames); }设计者选择显式允许列表而非拒绝列表注释给出的理由值得记录“better to leak than to mangle a runtime whose namespace behavior we havent verified”——对于未知或未来的运行时宁可保留原样也不要在未经证实其命名空间行为的情况下贸然改写。这也解释了为什么 changeset 只声称覆盖 Claude、Qwen、Hermes 三个运行时。对应的迁移验证可参考 tests/claude-skills-migration.test.cjs、tests/qwen-skills-migration.test.cjs 与 tests/hermes-skills-migration.test.cjs。回归护栏bug-2808 测试如何守住这条不变量changeset 明确提到 “Added regression guard in bug-2808 test”。tests/bug-2808-skill-hyphen-name.test.cjs 在原有的“#2808 技能名必须是连字符”断言之外新增了正文层面的检查生成产物断言调用convertClaudeCommandToClaudeSkill得到 SKILL.md 后扫描其正文中形如\bgsd:[a-z][a-z0-9-]*\b的残留并显式放行gsd:sdk、gsd:tools它们本就不是斜杠命令其余任何冒号命令引用都会让测试失败源文件断言扫描 get-shit-done/workflows 全部.md确保不存在Skill(skillgsd:cmd)冒号形式调用——正则Skill\(\s*skill\s*\s*\\?[]gsd:([^\s)])\\?[]甚至覆盖了空格与转义引号的变体转换器单元测试直接对transformContentToHyphen验证正向改写、右侧边界gsd:plan-phase-extra不误伤、左侧边界mygsd:plan-phase不误伤与混合输入行为。这套“生成产物 源内容 纯函数”三层测试恰好分别守护了安装产物、仓库存储方言与转换器自身的正确性。边界与适用前提最后明确这次归一化的生效范围避免误用仅作用于已识别命令白名单来自 commands/gsd/ 下的*.md文件名不在列表中的标识符一律不改安装期生效、存储期不变monorepo 内命令源文件与文档仍保留冒号方言由前向transformContent维护只有安装到 Claude / Qwen / Hermes 的产物被改写为连字符——从源码结构可以推断这是一套“存储规范与运行时规范解耦”的双方言策略测试文件豁免批处理模式会跳过*.test.*文件因为其中的夹具字符串本就是测试语义的一部分改写会破坏断言未验证运行时默认不动HYPHEN_NAME_AGENT_RUNTIMES之外的运行时不触发正文归一化。小结graceful-tigers-fly.md记录的并非一次孤立的字符串替换而是一整套可复用的工程实践为“同一内容在不同运行时拥有不同规范形态”的问题提供双向纯函数转换器用最长优先匹配与双向词边界保证重写安全用显式运行时白名单控制影响面再用三级回归测试守住产物与源码的双向一致。对于任何需要把 Markdown 类“命令/技能”产物安装进多种 AI 运行时Claude Code、Qwen、Hermes、Codex 等的工程这套“共享转换器 安装期接入 边界测试”的模式都可以直接套用。【免费下载链接】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），仅供参考