【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本文围绕仓库中归档的变更片段 fair-hawks-play.mdPR #3444关闭 #3440展开GSDGet Shit Done安装器将 Codex 托管 hook 命令统一投影到共享的 shell-command seam并在config.tomlhook 块构建与 Codex 重装重写两条路径上复用同一套运行时感知的命令渲染策略。读完本文你将理解托管 hook 命令文本由谁生成、如何针对 Windows/PowerShell 等运行时做差异渲染、如何保证config.toml、hooks.json、settings.json多表面之间的格式一致并可直接顺着给出的源码与测试路径继续深挖。一、变更片段解读一条归档 changeset 背后的 seam 决策.changeset/archived/目录存放的是已归档的 changeset 片段release note 碎片归档目录 README 说明这些片段仅用于溯源保留retained for provenance only且 changeset 工具只递归枚举.changeset/顶层文件归档子目录永远不会被render消费避免与已发布的 CHANGELOG 重复。本次关联文档的全文如下--- type: Added pr: 3444 --- **Codex managed hook commands now project through the shared shell-command seam** — the installer reuses the same runtime-aware command rendering policy for config.toml hook blocks and Codex reinstall rewrites, reducing shell-format drift between runtime surfaces. Closes #3440.这段片段虽然简短但包含三个可验证的技术信息点构成本文的骨架共享 seamCodex 托管 hook 命令的渲染统一收敛到单一模块shell-command-projection两处复用同一策略config.tomlhook 块的生成构建与 Codex 重装时的重写reinstall rewrites共用同一渲染入口目标减少运行时表面runtime surfaces之间的 shell 格式漂移shell-format drift。下文将从当前仓库源码逐一验证这三条主张的实际落地形态。二、共享 seam 是什么只渲染、不执行共享 seam 的实体是 shell-command-projection.cts编译产物为bin/lib/shell-command-projection.cjs。模块头注释明确定义了它的边界L1-L12Tracer-bullet seam for runtime-aware projection of serialized command text that GSD writes into runtime config or prints for copy/paste. This module doesNOTexecute commands; it only renders command text for external shells and runtimes.即该模块不执行任何命令只负责把命令文本渲染成目标 shell / 运行时可消费的字符串——这决定了它天然适合被安装器写入 config与重装重写已有配置两条路径共用因为两条路径的产出物都是序列化文本而非进程调用。此外注释还记录了 ADR-457 build-at-publish该 seam 曾以手写bin/lib/shell-command-projection.cjs存在后折叠为 TypeScript 单一事实源行为逐字节保持仅增加类型。seam 的核心渲染原语函数作用位置projectShellCommandText把 runnerToken argTokens 拼成单条命令文本并按 hookShell 决定是否加L176-L192projectManagedHookCommand托管 hook 命令主入口win32 下先posixNormalize脚本路径再 JSON 引号化再交给projectShellCommandTextL194-L210projectCodexHookTomlCommandCodex 专用出口调用projectManagedHookCommandruntime 固定为codex后追加 TOML 基本字符串转义L434-L446formatHookCommandForRuntime根据hookShell powershell决定是否在命令前加 PowerShell 调用运算符L97-L99escapeTomlDoubleQuotedString按 TOML v1.0.0 基本字符串语法转义\、与控制字符#3118 修复过只转义反斜杠和引号导致生成非法 config.toml 的问题L423-L432posixNormalize无条件把所有反斜杠归一为前斜杠用于把路径投影进 POSIX/bash 目标L55-L57isManagedHookCommand判定一段命令文本是否属于 GSD 托管 hook按 surface 的 basename 白名单 可选 args 形态匹配L309-L341projectCodexHookTomlCommand是理解本次变更的钥匙其实现非常短export function projectCodexHookTomlCommand({ absoluteRunner, scriptPath, platform process.platform }: { absoluteRunner?: string | null; scriptPath?: string | null; platform?: string; }): string | null { const command projectManagedHookCommand({ absoluteRunner, scriptPath, runtime: codex, platform, }); return command null ? null : escapeTomlDoubleQuotedString(command); }两条规则值得注意runner 或脚本缺失时返回null调用方跳过注册而非写坏配置呼应 #3393 的宁可跳过不可写坏原则非 null 时统一走escapeTomlDoubleQuotedString保证写进 TOML 的命令字符串在任何字符组合下都可解析。三、运行时感知渲染策略的关键维度运行时感知runtime-aware是本次变更的核心卖点。从 shell-command-projection.cts 的源码可以看到同一渲染函数族接受platform、runtime、hookShell三个维度并据此差异输出1. hookShellGit Bash 与 PowerShell 的分歧#2236hookCommandNeedsPowerShellCallOperator 的注释说明了背景同一个运行时Claude Code在 Windows 上可能托管 Git Bash 或 PowerShell而没有任何一条静态命令字符串能同时兼容两者——Git Bashnode.exe hook.js可用 node.exe …是语法错误PowerShell node.exe hook.js可用裸node.exe …报Unexpected token。因此的决定键是生效的 hook 执行 shellopts.hookShell而非 runtime 本身。默认falseGit Bash 形态向后兼容hookShell: powershell时formatHookCommandForRuntime返回 ${command}。2. platformwin32 的路径归一与引号化Windows 下托管 hook 脚本路径统一posixNormalize成前斜杠并JSON.stringify加引号使同一条路径在 JSON/TOML/config 多个表面间一致存活projectManagedHookCommand。测试 shell-command-projection-dispatch.test.cjs 中 L1672-L1703 锁定hookShellpowershell对任何 runtime 都返回 true 并输出前缀而默认Git Bash / 旧形态绝不输出。3. runtimeClaude/Windows 的 bash 包装省略#166/#580/#3393shellHookOmitsBashRunner 规定win32 runtime claude isShellHook时.sh托管 hook 只输出锚定的脚本路径本身去掉显式 bash 包装——否则 Claude Code 在 Windows 的 Git Bash 中执行时会出现bash.exe: cannot execute binary file。而codex运行时不在省略之列测试 L2235-L2236 明确断言 win32 codex 为 false这正是按 runtime 分化渲染的一个具体例证。四、config.toml hook 块buildCodexHookBlockconfig.toml hook 块的构建实现位于 runtime-hooks-surface.cts 的buildCodexHookBlockfunction buildCodexHookBlock(targetDir: string, opts?: BuildCodexHookBlockOpts): string | null { const absoluteRunner opts opts.absoluteRunner; if (!absoluteRunner) return null; const eol (opts opts.eol) || \n; const platform (opts opts.platform) || process.platform; const updateCheckScript path.resolve(targetDir, hooks, gsd-check-update.js); const commandValue projectCodexHookTomlCommand({ absoluteRunner, scriptPath: updateCheckScript, platform, }); return ${eol}# GSD Hooks${eol} [[hooks.SessionStart]]${eol} ${eol} [[hooks.SessionStart.hooks]]${eol} type command${eol} command ${commandValue}${eol}; }关键点hook 命令文本完全交给 seam 生成projectCodexHookTomlCommand构建器自身不拼装任何命令细节。生成的 TOML 采用 Codex 0.124.0 要求的两层嵌套 schema——[[hooks.SessionStart]][[hooks.SessionStart.hooks]]type command测试 codex-config-hooks.test.cjs 的注释与断言记录了这一点扁平[[hooks]] event表单与缺少.hooks的单块表单都不被接受。落盘形态示意# GSD Hooks [[hooks.SessionStart]] [[hooks.SessionStart.hooks]] type command command \/usr/local/bin/node\ \/Users/me/.codex/hooks/gsd-check-update.js\command值中的\是 TOML 基本字符串的合法转义由escapeTomlDoubleQuotedString统一产出runner 与路径按实际安装环境变化。五、重装重写复用同一策略rewriteLegacyCodexHookBlock本次变更的第二个复用点位于同一文件的rewriteLegacyCodexHookBlockL894-L923。它在重装/修复场景下扫描既有 config.toml 中的旧式命令行const updated content.replace( /^(command\s*\s*)node\s((?:\\[^]\\|\S))(\s*)$/gm, (full: string, prefix: string, scriptToken: string, suffix: string) { // ...解析 scriptPath解析失败按原样返回 if (!isManagedHookBasename(scriptPath, { surface: codex-toml })) return full; const desiredCommand projectCodexHookTomlCommand({ absoluteRunner, scriptPath, platform }); // 当前命令与期望命令不一致时才改写 if (currentCommand desiredCommand) return full; changed true; return ${prefix}${desiredCommand}${suffix}; }, );这条路径体现了 changeset 所述reinstall rewrites的完整语义只动 GSD 托管的 hook通过isManagedHookBasename(scriptPath, { surface: codex-toml })过滤用户自写 hook 一律不动幂等当前命令与重投影结果一致时保持原文避免无意义改写同策略目标命令仍由projectCodexHookTomlCommand生成与buildCodexHookBlock走的是同一个渲染入口。正因构建与重写两条路径共享同一函数任何针对 runner 解析、路径归一、TOML 转义、PowerShell前缀的策略调整都会同时生效于两个表面——这就是减少 shell-format drift的实现机理可以从源码结构直接验证。六、hooks.json 协调与遗留注册迁移除了 config.tomlCodex 安装还维护hooks.json表面相关协调逻辑集中在 runtime-hooks-surface.cts 的reconcileCodexHooksJsonEventL960 起与reconcileCodexHooksJsonSessionStartL1112-L1114读取解析hooks.json时会先做符号链接守卫拒绝不信任的 symlink 布局除非显式GSD_ALLOW_SYMLINKED_DEST1见 L973-L1000写入前把所有顶层事件数组规范提升到嵌套{ hooks: { Event: [...] } }形态#1348避免 Codexdeny_unknown_fields拒绝对每个 hook 条目用isManagedHookCommand(cmd, { surface: codex-hooks-json, includeLegacyAliases: true, configDir })判定是否属于 GSD 托管命令托管条目被过滤移除并记录removedLegacy用户条目保留。配套的安装迁移 002-codex-legacy-hooks-json.cts2026-05-11-codex-legacy-hooks-jsonruntimes: [codex]destructive递归剪除 hooks.json 中的托管注册剪空即删除文件。这解释了 seam 中按 surface 分列的托管 basename 白名单L238-L278surface托管 basenamecodex-tomlgsd-check-update.jscodex-hooks-jsongsd-check-update.js、gsd-check-update.cmd、gsd-context-monitor.js、gsd-context-monitor.cmd遗留别名legacy aliasgsd-update-check.js其中.cmd条目对应 Windows 下的 shim 方案#3426buildCodexHookWindowsShimIR 生成ECHO OFF/SETLOCAL前缀的.cmd包装reconcileCodexHooksJsonSessionStart在重装时可用.cmdshim 命令替换陈旧的 node-runner 命令跨平台迁移时反向替换。七、测试验证与进一步阅读以下测试为本文所述行为提供了可运行断言shell-command-projection-dispatch.test.cjsL1672-L1703 验证hookShellpowershell时前缀的生成与默认省略L1859-L1875 验证codex-toml/codex-hooks-json表面的isManagedHookCommand识别与遗留别名gsd-update-check.js的匹配L2235-L2236 断言codex不落入 Claude/Windows 的 bash-runner 省略分支。codex-config-hooks.test.cjsL331-L347 验证全新安装只把托管 SessionStart 命令写入hooks.json恰一条gsd-check-update而config.toml不携带 GSD 托管 SessionStart 块后续用例验证保留用户自有[[hooks.SessionStart]]条目并追加 GSD 托管处理。augment-upgrades.test.cjs 等跨运行时用例可对照同一 seam 服务多运行时的横向一致性。想查看实际落盘产物安装后检查$CODEX_HOME默认~/.codex下的config.toml与hooks.jsonGSD 托管条目集中在gsd-check-update.jsSessionStart 更新检查与gsd-context-monitor.js上下文监控SubagentStart/Stop/PostToolUse等钩子上。修改托管 hook 命令后重新运行安装器即可观察到重写路径按同一渲染策略把命令收敛回规范形态。八、小结fair-hawks-play.md 片段记录的是 gsd-core 安装链路中一次典型的seam 收敛Codex 托管 hook 命令的文本渲染不再由各调用点自行拼装而是统一投影到 shell-command-projection.cts 这一只渲染、不执行的共享 seam并被config.toml块构建buildCodexHookBlock与重装重写rewriteLegacyCodexHookBlock两处共同复用。从源码结构看platform/runtime/hookShell三个维度在 seam 内完成差异决策配合isManagedHookCommand的 surface 白名单与 002 号迁移最终在config.toml、hooks.json与跨平台.cmdshim 之间维持了稳定的命令格式契约——这正是减少 shell 格式漂移的落地形态。后续阅读可从 归档 changeset 目录 出发横向对比其他运行时Claude、Antigravity 等的同类 seam 决策。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐GSD Core 修复 Codex SessionStart Hook 裸 node 命令从 exit 127 到绝对路径 runnerGSD Core 修复 Codex SessionStart Hook 裸 node 命令从 exit 127 到绝对路径 runner 导读 本篇文章聚焦gsd-core 状态命令路由重构state 子命令如何通过 SDK 运行时桥executeForCjs统一派发gsd core 状态命令路由重构state 子命令如何通过 SDK 运行时桥executeForCjs统一派发 本文基于 gsd core 仓库中已归档gsd-core 命令参数投影单次索引优化parseNamedArgs 从 O(flags×argv) 到 O(argvflags) 的演进实录gsd core 命令参数投影单次索引优化parseNamedArgs 从 O flags×argv 到 O argvflags 的演进实录 导读 本文以上一篇OptiScaler革命性游戏超采样技术桥接器 - 智能GPU兼容解决方案下一篇突破90%覆盖率React-Toastify核心组件测试实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考