一份脚本、两个身份：Superpowers 跨平台钩子 3 步跑通与避坑指南

一份脚本、两个身份Superpowers 跨平台钩子 3 步跑通与避坑指南【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers在新装 Windows 的机器上跑插件SessionStart 钩子毫无反应.sh 文件在 CMD 里被记事本打开$CLAUDE_PLUGIN_ROOT也毫无展开。Superpowers 的解法藏在hooks/目录里——一份一个脚本、两个身份的 polyglot多解释器脚本即同一段文本被不同解释器按各自语法解析调度器让同一套钩子逻辑在 Windows、macOS、Linux 上跑通。 原理先行同一份文件两个解释器各读一半这套方案能成立靠的不是兼容而是双方各自只看到自己想看的部分。核心就一行开头的把戏: CMDBLOCK # CMD 里以 : 开头的行是标签直接跳过bash 里 : 是空操作 启动 here-doc echo off # Windows 侧从这里接管按 3 个标准路径找 bash.exe找到就执行目标脚本 exit /b 0 # Windows 侧在此退出下面的内容永远不会被读 CMDBLOCK # bash 的 here-doc 终止符之前的批量命令全部被吞掉 exec bash ${SCRIPT_DIR}/${SCRIPT_NAME} $ # Unix 侧定位本脚本所在目录执行真正的钩子说白了CMD.exe 眼里第一行是个被忽略的标签随后执行批处理逻辑exit /b收场bash 眼里第一行是空命令 带引号的 here-docCMDBLOCK之前的所有批处理语法都只是要原样保留的文本一行都不会执行带引号的CMDBLOCK保证 here-doc 内容不做变量展开批处理里的%符号才不会干扰 bash。两侧行为对照读到的内容Windows 侧CMD.exeUnix 侧bash/sh第一行: CMDBLOCK冒号开头视为标签跳过:空操作启动 here-doc批处理段真正执行校验参数 → 找 bash → 跑目标脚本被 here-doc 吞掉不执行CMDBLOCK行已经exit /b到不了这里here-doc 终止Unix 段永远不可达exec bash执行实际钩子脚本还有两个不起眼的决策恰恰是踩坑踩出来的详见 hooks/run-hook.cmd 内的注释钩子脚本不带.sh扩展名Windows 上 Claude Code 见到路径里有.sh会自动前缀bash直接绕过调度器找不到 bash 就静默exit /b 0没装 Git for Windows 的用户插件照常工作只是跳过钩子而不是报错不用-l登录 shell、不用cygpath钩子脚本应自包含bash 直接接收 Windows 路径即可正确处理。 最小复现hooks/ 目录里的三个文件不用重写直接照着仓库走三步克隆仓库git clone https://gitcode.com/GitHub_Trending/su/superpowers打开hooks/目录看懂三个文件的分工hooks/hooks.json——声明钩子命令${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start并指定shell: bash强制走 Git Bash 通道hooks/run-hook.cmd——polyglot 调度器本体也就是上面拆解的那个两个身份文件hooks/session-start——真正的钩子逻辑一个无扩展名的 bash 脚本注意不是session-start.sh。完整原理与取舍在 docs/windows/polyglot-hooks.md 里写得很清楚文档还特别声明文档与代码不一致时以代码为准。改动调度器后跑一下 tests/hooks/test-session-start.sh 回归验证。⚠️ 踩坑速查表四个真实事故钩子静默不触发。现象是没有任何报错钩子就是不跑最容易误判为配置丢失。原因调度器依次探测C:\Program Files\Git、C:\Program Files (x86)\Git和 PATH 三个位置的 bash一个都没有时按设计静默退出 0。修法把 Git for Windows 装到默认路径或让bash进 PATH。脚本带了 .sh 后缀。现象是 macOS 上正常、Windows 上没反应。原因Claude Code 的 Windows 端看到命令里含.sh就自动前缀bash绕开了 CMD 调度器这条路。修法脚本一律无扩展名如session-starthooks.json里的命令同步改。matcher 对不上事件名。现象是钩子在任何事件下都不触发。原因不同宿主的事件名不同Claude Code 用startup|clear|compactCursor 用sessionStart。修法核对hooks.json的matcherCursor 场景看同目录的 hooks/hooks-cursor.json。依赖 login-shell 的 PATH。现象是终端里手跑没问题作为钩子就挂。原因调度器不带-l钩子脚本拿不到登录 shell 的 PATHsed、awk这类外部命令可能根本找不到。修法钩子逻辑尽量用纯 bash 内置命令实现所有变量展开写成$VAR形式。收益与延伸阅读收益一句话钩子逻辑只写一份 bash调度层用一份脚本、两个身份消化掉 CMD 与 bash 的语法鸿沟三个平台同一套行为不再为 Windows 单独维护脚本。深入建议直接读 hooks/run-hook.cmd 源码和 docs/windows/polyglot-hooks.md改完用 tests/hooks/test-session-start.sh 兜底。【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考