深入解析 get-shit-doneGSDCodex 全局安装的$gsd-*Skill Surface 修复从 Issue #3562 看多 Agent CLI 的技能发现契约【免费下载链接】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/3562-codex-install-skill-surface.md 所记录的缺陷修复展开剖析一个核心工程问题为什么使用npx get-shit-done-cclatest --codex --global全局安装 get-shit-doneGSD后Codex CLI 在重启后依然看不到任何$gsd-*命令文章将完整还原该 Bug 的现象、根因、修复方式并结合 bin/install.js 安装器实现与 tests/bug-3562-codex-install-skill-surface.test.cjs 回归测试说明 GSD 是如何为不同 AI 编码助手统一生成可被 Skill 发现机制读取的命令表面skill surface以及读者在全局安装后应当如何自检验证。一、Bug 背景Codex CLI 需要skills/name/SKILL.md才能暴露命令get-shit-done 本身是一个元提示meta-prompting与上下文工程系统其对外暴露能力的方式是让 AI 编码助手看到一批以$gsd-*开头的斜杠命令slash command。这些命令的源文件来自仓库中的 get-shit-done/commands/gsd/ 目录每个命令一个 Markdown 文件例如help.md以及 agents/ 目录下的gsd-*.mdAgent 定义。问题在于不同的 AI 编码助手其命令发现机制并不一致。变更记录明确指出Codex CLI 0.130.0Issue 报告中的版本并不会从get-shit-done/workflows/*.md或agents/*.md自动发现命令它只把skills/name/SKILL.md这样的技能文件注册为可调用命令。这是本 Bug 的认知前提也是理解整个修复的关键。依据回归测试文件头注释原文即写明 Codex CLI 0.130.0 ... does NOT auto-discover commands fromget-shit-done/workflows/*.mdoragents/*.md. It only registers commands fromskills/name/SKILL.md见 tests/bug-3562-codex-install-skill-surface.test.cjs。二、问题现象与根因Issue #3562变更记录描述的现象如下用户执行全局安装命令npx get-shit-done-cclatest --codex --global安装完成后磁盘上确实存在工作流文件get-shit-done/workflows/*.md与 Agent 定义agents/gsd-*但没有生成~/.codex/skills/gsd-*/SKILL.md。因此在 Codex CLI 0.130.0 中重启后零个$gsd-*命令被静默暴露——命令文件在磁盘上但 Codex 根本发现不了它们。根因是安装器中一条过时假设旧逻辑认为Codex 会自动从 workflow/agent 文件发现官方技能于是在 Codex 安装路径上跳过了技能skill生成。然而这一假设并不符合当前 Codex CLI 的真实行为于是造成了文件都装了、命令却一个都看不见的割裂状态。需要强调的是这类假设性跳过很容易被静态检查漏过安装过程本身没有报错产物也基本齐全唯独缺少了决定能不能被命令系统看见的那一层SKILL.md。这也是为什么该 Bug 必须用专门的回归测试来钉死详见第五节。三、修复方案把copyCommandsAsCodexSkills()重新接回 Codex 安装路径变更记录对应 PR #3568frontmatter 声明type: Fixed给出的修复非常聚焦复用已有的copyCommandsAsCodexSkills()辅助函数把它重新接入 Codex 的安装分发dispatch路径。其核心效果是让 Codex 安装产出与其他助手完全一致的技能形状skill-shape对命令源目录中每一个 commands/gsd/*.md 生成一个 ~/.codex/skills/gsd-命令名/SKILL.md即遵循oneskills/gsd-name/SKILL.mdpercommands/gsd/*.md的一对一映射规则。变更记录中明确列出这一形状此前已经被 Claude / Copilot / Antigravity / Cursor / Windsurf / Augment / Trae 等安装路径采用本次只是让 Codex 补齐到同一标准避免同源命令、异构出口的漂移。从 bin/install.js 的代码可以佐证该设计的普遍性在安装清单manifest登记逻辑中Codex 与 Copilot / Antigravity / Cursor / Windsurf / Trae 等目标共享同一条技能目录登记分支当目标属于这些助手代码中isCodex || isCopilot || ...且技能目录存在时安装器会遍历skills/下的技能目录以listCodexSkillNames枚举把每个技能内的文件按相对路径写入安装清单并计算哈希Codex 侧使用skills/前缀Hermes 场景使用skills/gsd/前缀见 bin/install.js 中codexSkillsManifestPrefix相关实现。这说明技能表面不是可选项而是安装产物中需要被显式登记追踪的一等公民。在 Codex 安装的回滚rollback逻辑中安装器专门对skills/gsd-*目录做先清空、按快照还原的两阶段处理注释明确写到copyCommandsAsCodexSkills removes pre-existing gsd-* dirs before re-writing即copyCommandsAsCodexSkills在重写前会先移除已存在的gsd-*目录见 bin/install.js 中restoreCodexSnapshot的实现。这意味着技能生成是幂等可重入的重复安装不会叠加脏数据失败时也能按安装前快照精确还原。四、修复附带的行为保证不碰用户自有技能变更记录特别强调了一句容易被忽略的约束已存在的、非gsd-*前缀的用户自有技能目录会被保留Pre-existing user-owned non-gsd-*skill directories are preserved。这是一条重要的安全边界安装器只对自己拥有命名空间的产物gsd-*负责可以删除、重建、回滚但对用户自建的skills/custom-*等目录安装器不得越界修改。也就是说--codex --global是全量接管 GSD 自身表面 对用户空间零侵入的组合这也是它敢于在回滚逻辑中对gsd-*目录执行递归删除再还原的前提——被删除的只可能是安装器此前自己写入或快照过的内容。五、回归测试如何证明$gsd-*真正可被发现修复的验收标准不是文件被生成而是文件以 Codex 能发现的形状生成。仓库为此新增了专门的回归测试 tests/bug-3562-codex-install-skill-surface.test.cjs测试通过设置CODEX_HOME指向临时目录、调用安装器的install(true, codex)第一个参数为 global 标志第二个参数为目标助手来模拟全局安装。它从四个角度验证了修复质量最小可发现单元存在全局安装后必须存在skills/gsd-help/SKILL.md否则$gsd-help不会被 Codex CLI 暴露。frontmatter 契约正确生成的SKILL.md中 frontmatter 必须声明name: gsd-help因为 Codex 的技能发现依赖该名称字段来解析出$gsd-help命令。不是只生成一两个样品安装后skills/下以gsd-开头的技能目录数量必须不少于 10 个。测试注释说明这是一个保守下限——commands/gsd/目录保存着数十个命令文件这个断言专门用来拦截什么都没生成或只碰巧生成了一个的回归。不破坏用户自有技能测试先预置一个skills/custom-user-skill/SKILL.md再执行安装最后断言该文件仍然存在验证了非gsd-*用户技能目录被保留的行为保证。从仓库现状看commands/gsd/ 目录下确实保存着大量命令文件help.md、phase.md、ship.md等因此十余个乃至数十个gsd-*技能目录的描述与源码结构一致。六、实战自检全局安装 Codex 后如何确认技能表面就位基于本次修复的定义与测试断言任何使用--codex --global的用户都可以用以下清单做技能表面体检而无需等待 CLI 启动后才被动发现命令缺失确认安装命令正确使用npx get-shit-done-cclatest --codex --global确认SKILL.md存在检查~/.codex/skills/gsd-help/SKILL.md以及一批其他gsd-*子目录是否生成。确认 frontmatter 契约打开任意生成的SKILL.md验证 frontmatter 中name:字段等于目录名例如目录gsd-help对应name: gsd-help这是 Codex 把技能解析为$gsd-help命令的关键。确认数量规模ls ~/.codex/skills/ | grep -c ^gsd-应返回与 commands/gsd/ 目录命令数量匹配的结果至少十余个级别绝不可能是零或一。确认用户空间未被破坏若此前在~/.codex/skills/下自建过非gsd-前缀的技能目录升级/重装后它们应原样保留。重启 Codex CLI 验证Codex 的技能注册发生在启动时变更记录与测试均以重启后after restart作为观察窗口因此判断是否生效必须重启会话后键入$gsd-前缀观察补全。七、从本案例提炼的工程启示技能发现是一种隐性契约对以斜杠命令驱动的 AI 编码工具命令源文件落盘不等于命令可用中间隔着该 CLI 是否把某类文件识别为命令这一层发现协议。任何对自动发现能力的假设都应当用最小可运行样例验证而不是写进安装器的跳过逻辑。异构目标的统一形状降低心智负担GSD 安装器通过copyCommandsAs*Skills()一族辅助函数Cursor、Copilot、Antigravity、Windsurf、Augment、Claude、Codex 各自一份转换逻辑bin/install.js 中可见它们彼此镜像、仅转换器不同把源命令目录 → 目标 CLI 技能目录的映射收敛到同一套约定便于审计与补课——本次修复正是把 Codex 拉回同一张形状表。回归测试要断言能被发现而非文件存在本次测试特意同时校验目录存在、frontmatter 名称、数量下限与用户目录保留四点避免了生成了一些东西但仍是坏表面的假阳性。简言之Issue #3562 是一次典型的安装产物齐全、但能力入口静默丢失的缺陷修复与配套测试共同确立了 Codex 安装路径上的硬性契约——~/.codex/skills/gsd-*/SKILL.md缺一不可、命名必须匹配、数量必须达标、用户空间必须免扰。【免费下载链接】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），仅供参考