,零改動:Superpowers 的 Polyglot 跨平臺 Hook 是怎么做到的)
一個文件,三臺系統(tǒng),零改動:Superpowers 的 Polyglot 跨平臺 Hook 是怎么做到的【免費下載鏈接】superpowersAn agentic skills framework software development methodology that works.項目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 的 hooks 目錄里藏著一個很實用的跨平臺技巧:借助 polyglot(多語言)腳本,讓同一條 SessionStart hook 在 Windows、macOS 和 Linux 上都能跑,不用為不同系統(tǒng)維護兩套命令。如果你是那種經(jīng)常在三臺設備之間切來切去、又給 Claude Code 插件寫過鉤子腳本的人,這套寫法值得花十分鐘拆開看看。先從一個真實的翻車現(xiàn)場說起你剛給插件寫了一個 SessionStart hook,在 Mac 上測試一切正常:會話啟動時注入技能說明,省得每次手動貼。然后你換到一臺 Windows 機器上開工。事情開始不對勁:.sh文件被當成普通文本,雙擊直接彈開記事本;鉤子命令里帶引號的路徑被 CMD 的引號規(guī)則剝掉一層,解析報錯;更坑的是手動在終端里跑腳本沒問題,作為 hook 就靜悄悄不執(zhí)行——這種沒有報錯的失敗,排查起來最耗時。問題不在你的腳本邏輯,而在 Windows 上根本不存在直接跑.sh這件事:CMD 不認識$VAR,路徑是反斜杠,而就算裝了 Git Bash,bash也未必在 PATH 里。Superpowers 的解法不是給每個系統(tǒng)寫一份腳本,而是用一個文件同時喂飽 CMD 和 bash。一句話定位Superpowers 是一個 agentic 技能框架 開發(fā)方法論,它的 hook 子系統(tǒng)用了一個多語言派發(fā)器加無擴展名鉤子腳本的組合,把Windows 上跑 bash 鉤子這件臟活全包了:插件照常工作,鉤子在三個系統(tǒng)上都生效,找得到 bash 就執(zhí)行,找不到就安靜跳過,不會把整個插件帶崩。原理拆解:一扇門,兩條暗道先看派發(fā)器hooks/run-hook.cmd的開頭幾行:: CMDBLOCK echo off set HOOK_DIR%~dp0 ... exit /b 0 CMDBLOCK SCRIPT_DIR$(cd $(dirname $0) pwd) exec bash ${SCRIPT_DIR}/${SCRIPT_NAME} $可以把它想象成一扇門,門牌上貼著兩種語言寫的告示:bash 走這條道。對 Unix shell 來說,:是一個什么都不做的空命令,而 CMDBLOCK啟動了一個 here 文檔。于是從echo off到exit /b 0的整塊 CMD 內(nèi)容,全被當成 here 文檔的數(shù)據(jù)吞掉,一個字都不會執(zhí)行。文檔結(jié)束標記CMDBLOCK出現(xiàn)后,shell 繼續(xù)往下走,執(zhí)行底部真正的 Unix 邏輯。CMD 走那條道。CMD 把第一行: CMDBLOCK看成一個無害的標簽,然后開始逐行執(zhí)行后面的批處理命令:確定腳本目錄、查找 bash、調(diào)用鉤子。最后exit /b直接退出批處理,后面的 Unix 代碼它永遠看不到。同一份字節(jié),兩種解釋器,各走各的暗道,互不干擾。這就是 polyglot 包裝器的核心。Windows 那一半還做了兩件事值得注意:按順序找 bash:先試C:\Program Files\Git\bin\bash.exe,再試C:\Program Files (x86)下的,最后where bash找 PATH(覆蓋 MSYS2、Cygwin 等安裝方式);找不到就exit /b 0:不報錯、不中斷,插件繼續(xù)正常工作,只是跳過這次上下文注入。寧可靜默降級,也不讓鉤子把宿主應用搞壞。一個容易被忽略的細節(jié):腳本為什么沒有 .sh 后綴倉庫里的鉤子腳本叫session-start,不是session-start.sh。這不是命名潔癖,而是防一個具體行為:Claude Code 在 Windows 上會給任何命令里含.sh的條目自動前置bash,等于繞過你的派發(fā)器自己跑,結(jié)果就是鉤子看起來不生效。所以這套方案是成對生效的:派發(fā)器統(tǒng)一入口:hooks/run-hook.cmd鉤子腳本無擴展名:session-start配置文件指向派發(fā)器并傳腳本名hooks/hooks.json里的對應配置長這樣(路徑加了引號,因為${CLAUDE_PLUGIN_ROOT}可能含空格):{ type: command, command: \${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\ session-start, shell: bash }其中shell: bash也值得說一句:它強制走 Git Bash 路線。如果機器上沒裝 Git Bash,你會收到一個請安裝 Git for Windows的可執(zhí)行提示,而不是一條莫名其妙的 shell 解析錯誤。快速上手:三步跑起來第一步,克隆倉庫(Windows 上同樣適用):git clone https://gitcode.com/GitHub_Trending/su/superpowers第二步,打開三個文件,把入口—派發(fā)—邏輯的關(guān)系對上號:hooks/hooks.json— 聲明鉤子事件和派發(fā)命令hooks/run-hook.cmd— polyglot 派發(fā)器,跨平臺入口hooks/session-start— 真正的鉤子邏輯,純 bash第三步,驗證行為。倉庫自帶測試腳本tests/hooks/test-session-start.sh,改完派發(fā)器或鉤子后跑一遍,確認三個平臺的輸出格式(JSON 注入內(nèi)容)沒被破壞。如果你的插件要加新鉤子,不用復制派發(fā)器——把run-hook.cmd的邏輯抄進自己的插件,新鉤子只需要一個無擴展名腳本,命令里多傳一個參數(shù)就行。進階模式:把派發(fā)器當可復用組件用run-hook.cmd的用法是run-hook.cmd 腳本名 [參數(shù)...],腳本名取自第一個參數(shù)。這意味著一個插件有 N 個鉤子,也只需要這一個派發(fā)文件,每個鉤子各自維護一段 bash 邏輯。hooks-cursor.json里就是這么復用的:同一個派發(fā)命令,Cursor 側(cè)只換了事件名的寫法。寫這些無擴展名 bash 腳本時,項目里有幾條經(jīng)驗可以直接抄:優(yōu)先用 bash 內(nèi)建命令。鉤子不以登錄 shell(-l)方式運行,PATH 里有什么全看宿主環(huán)境。session-start里做 JSON 轉(zhuǎn)義就沒碰sed/awk,而是用純參數(shù)替換:s${s//\\/\\\\} s${s//\/\\\} s${s//$\n/\\n}逐類字符替換、只靠內(nèi)建語法,哪個系統(tǒng)上都成立。所有變量展開都加引號:$VAR;命令替換用$(...)而不是反引號;輸出用printf。別依賴登錄 shell 的環(huán)境。鉤子環(huán)境和你手動開終端的環(huán)境不是一回事,這正是終端里能跑、當鉤子就不行的常見根源。改動派發(fā)器之后,以hooks/run-hook.cmd的代碼為準去對照文檔,再跑一次測試,這是項目里寫明的維護約定。避坑排查:三個看起來沒壞的假象現(xiàn)象一:Windows 上鉤子靜默不執(zhí)行,連個報錯都沒有。原因:派發(fā)器三個位置都沒找到 bash,按設計exit /b 0退出了。這是靜默降級的正常行為,不是你的 bug。 解法:把 Git for Windows 裝到標準路徑,或確保bash在 PATH 里(比如你裝了 MSYS2/Cygwin)。現(xiàn)象二:Linux 上正常,Windows 上什么都不做。八成是腳本文件名帶了.sh擴展名,觸發(fā)了 Windows 側(cè)的自動前置邏輯,派發(fā)路徑被繞開了。 解法:鉤子腳本一律去掉擴展名,hooks.json里的命令參數(shù)同步改成無擴展名?，F(xiàn)象三:任何系統(tǒng)上鉤子都不觸發(fā)。這通常是事件名對不上:Claude Code 的 matcher 是startup|clear|compact,Cursor 用的是sessionStart。 解法:核對hooks.json里的 matcher 和你所用宿主實際發(fā)出的事件名,兩個平臺的差異在hooks/hooks.json與hooks/hooks-cursor.json里可以直接對照。還有一個通用技巧:懷疑是環(huán)境問題時,別猜。模擬鉤子的執(zhí)行環(huán)境手動跑一遍派發(fā)命令,再跑tests/hooks/test-session-start.sh,大多數(shù)時好時壞的問題會在復現(xiàn)的瞬間露出馬腳?；氐介_頭那臺 Windows 機器再回到開頭那個場景:同一條 SessionStart hook,現(xiàn)在在你同事的 Windows 機器上也會準時注入上下文了——沒有雙份腳本,沒有平臺判斷,沒有這臺機器再試一次。Superpowers 這套 polyglot 派發(fā)器加無擴展名腳本的寫法,核心收益就一句話:鉤子邏輯只寫一遍,bash 找不到就優(yōu)雅退出,找得到就在任何系統(tǒng)上準時執(zhí)行。如果你也在做多平臺 Claude Code 插件,hooks/目錄下的這三個文件值得逐行讀一遍,比任何跨平臺教程都短,而且全是能直接抄的生產(chǎn)實現(xiàn)?！久赓M下載鏈接】superpowersAn agentic skills framework software development methodology that works.項目地址: https://gitcode.com/GitHub_Trending/su/superpowers創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 一個文件,三臺系統(tǒng),零改動:Superpowers 的 Polyglot 跨平臺 Hook 是怎么做到的
一個文件,三臺系統(tǒng),零改動:Superpowers 的 Polyglot 跨平臺 Hook 是怎么做到的【免費下載鏈接】superpowersAn agentic skills framework software development methodology that works.項目地址: https://gitcode.com/GitHub_Trending/su/superpowersSuperpowers 的 hooks 目錄里藏著一個很實用的跨平臺技巧:借助 polyglot(多語言)腳本,讓同一條 SessionStart hook 在 Windows、macOS 和 Linux 上都能跑,不用為不同系統(tǒng)維護兩套命令。如果你是那種經(jīng)常在三臺設備之間切來切去、又給 Claude Code 插件寫過鉤子腳本的人,這套寫法值得花十分鐘拆開看看。先從一個真實的翻車現(xiàn)場說起你剛給插件寫了一個 SessionStart hook,在 Mac 上測試一切正常:會話啟動時注入技能說明,省得每次手動貼。然后你換到一臺 Windows 機器上開工。事情開始不對勁:.sh文件被當成普通文本,雙擊直接彈開記事本;鉤子命令里帶引號的路徑被 CMD 的引號規(guī)則剝掉一層,解析報錯;更坑的是手動在終端里跑腳本沒問題,作為 hook 就靜悄悄不執(zhí)行——這種沒有報錯的失敗,排查起來最耗時。問題不在你的腳本邏輯,而在 Windows 上根本不存在直接跑.sh這件事:CMD 不認識$VAR,路徑是反斜杠,而就算裝了 Git Bash,bash也未必在 PATH 里。Superpowers 的解法不是給每個系統(tǒng)寫一份腳本,而是用一個文件同時喂飽 CMD 和 bash。一句話定位Superpowers 是一個 agentic 技能框架 開發(fā)方法論,它的 hook 子系統(tǒng)用了一個多語言派發(fā)器加無擴展名鉤子腳本的組合,把Windows 上跑 bash 鉤子這件臟活全包了:插件照常工作,鉤子在三個系統(tǒng)上都生效,找得到 bash 就執(zhí)行,找不到就安靜跳過,不會把整個插件帶崩。原理拆解:一扇門,兩條暗道先看派發(fā)器hooks/run-hook.cmd的開頭幾行:: CMDBLOCK echo off set HOOK_DIR%~dp0 ... exit /b 0 CMDBLOCK SCRIPT_DIR$(cd $(dirname $0) pwd) exec bash ${SCRIPT_DIR}/${SCRIPT_NAME} $可以把它想象成一扇門,門牌上貼著兩種語言寫的告示:bash 走這條道。對 Unix shell 來說,:是一個什么都不做的空命令,而 CMDBLOCK啟動了一個 here 文檔。于是從echo off到exit /b 0的整塊 CMD 內(nèi)容,全被當成 here 文檔的數(shù)據(jù)吞掉,一個字都不會執(zhí)行。文檔結(jié)束標記CMDBLOCK出現(xiàn)后,shell 繼續(xù)往下走,執(zhí)行底部真正的 Unix 邏輯。CMD 走那條道。CMD 把第一行: CMDBLOCK看成一個無害的標簽,然后開始逐行執(zhí)行后面的批處理命令:確定腳本目錄、查找 bash、調(diào)用鉤子。最后exit /b直接退出批處理,后面的 Unix 代碼它永遠看不到。同一份字節(jié),兩種解釋器,各走各的暗道,互不干擾。這就是 polyglot 包裝器的核心。Windows 那一半還做了兩件事值得注意:按順序找 bash:先試C:\Program Files\Git\bin\bash.exe,再試C:\Program Files (x86)下的,最后where bash找 PATH(覆蓋 MSYS2、Cygwin 等安裝方式);找不到就exit /b 0:不報錯、不中斷,插件繼續(xù)正常工作,只是跳過這次上下文注入。寧可靜默降級,也不讓鉤子把宿主應用搞壞。一個容易被忽略的細節(jié):腳本為什么沒有 .sh 后綴倉庫里的鉤子腳本叫session-start,不是session-start.sh。這不是命名潔癖,而是防一個具體行為:Claude Code 在 Windows 上會給任何命令里含.sh的條目自動前置bash,等于繞過你的派發(fā)器自己跑,結(jié)果就是鉤子看起來不生效。所以這套方案是成對生效的:派發(fā)器統(tǒng)一入口:hooks/run-hook.cmd鉤子腳本無擴展名:session-start配置文件指向派發(fā)器并傳腳本名hooks/hooks.json里的對應配置長這樣(路徑加了引號,因為${CLAUDE_PLUGIN_ROOT}可能含空格):{ type: command, command: \${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\ session-start, shell: bash }其中shell: bash也值得說一句:它強制走 Git Bash 路線。如果機器上沒裝 Git Bash,你會收到一個請安裝 Git for Windows的可執(zhí)行提示,而不是一條莫名其妙的 shell 解析錯誤。快速上手:三步跑起來第一步,克隆倉庫(Windows 上同樣適用):git clone https://gitcode.com/GitHub_Trending/su/superpowers第二步,打開三個文件,把入口—派發(fā)—邏輯的關(guān)系對上號:hooks/hooks.json— 聲明鉤子事件和派發(fā)命令hooks/run-hook.cmd— polyglot 派發(fā)器,跨平臺入口hooks/session-start— 真正的鉤子邏輯,純 bash第三步,驗證行為。倉庫自帶測試腳本tests/hooks/test-session-start.sh,改完派發(fā)器或鉤子后跑一遍,確認三個平臺的輸出格式(JSON 注入內(nèi)容)沒被破壞。如果你的插件要加新鉤子,不用復制派發(fā)器——把run-hook.cmd的邏輯抄進自己的插件,新鉤子只需要一個無擴展名腳本,命令里多傳一個參數(shù)就行。進階模式:把派發(fā)器當可復用組件用run-hook.cmd的用法是run-hook.cmd 腳本名 [參數(shù)...],腳本名取自第一個參數(shù)。這意味著一個插件有 N 個鉤子,也只需要這一個派發(fā)文件,每個鉤子各自維護一段 bash 邏輯。hooks-cursor.json里就是這么復用的:同一個派發(fā)命令,Cursor 側(cè)只換了事件名的寫法。寫這些無擴展名 bash 腳本時,項目里有幾條經(jīng)驗可以直接抄:優(yōu)先用 bash 內(nèi)建命令。鉤子不以登錄 shell(-l)方式運行,PATH 里有什么全看宿主環(huán)境。session-start里做 JSON 轉(zhuǎn)義就沒碰sed/awk,而是用純參數(shù)替換:s${s//\\/\\\\} s${s//\/\\\} s${s//$\n/\\n}逐類字符替換、只靠內(nèi)建語法,哪個系統(tǒng)上都成立。所有變量展開都加引號:$VAR;命令替換用$(...)而不是反引號;輸出用printf。別依賴登錄 shell 的環(huán)境。鉤子環(huán)境和你手動開終端的環(huán)境不是一回事,這正是終端里能跑、當鉤子就不行的常見根源。改動派發(fā)器之后,以hooks/run-hook.cmd的代碼為準去對照文檔,再跑一次測試,這是項目里寫明的維護約定。避坑排查:三個看起來沒壞的假象現(xiàn)象一:Windows 上鉤子靜默不執(zhí)行,連個報錯都沒有。原因:派發(fā)器三個位置都沒找到 bash,按設計exit /b 0退出了。這是靜默降級的正常行為,不是你的 bug。 解法:把 Git for Windows 裝到標準路徑,或確保bash在 PATH 里(比如你裝了 MSYS2/Cygwin)。現(xiàn)象二:Linux 上正常,Windows 上什么都不做。八成是腳本文件名帶了.sh擴展名,觸發(fā)了 Windows 側(cè)的自動前置邏輯,派發(fā)路徑被繞開了。 解法:鉤子腳本一律去掉擴展名,hooks.json里的命令參數(shù)同步改成無擴展名?，F(xiàn)象三:任何系統(tǒng)上鉤子都不觸發(fā)。這通常是事件名對不上:Claude Code 的 matcher 是startup|clear|compact,Cursor 用的是sessionStart。 解法:核對hooks.json里的 matcher 和你所用宿主實際發(fā)出的事件名,兩個平臺的差異在hooks/hooks.json與hooks/hooks-cursor.json里可以直接對照。還有一個通用技巧:懷疑是環(huán)境問題時,別猜。模擬鉤子的執(zhí)行環(huán)境手動跑一遍派發(fā)命令,再跑tests/hooks/test-session-start.sh,大多數(shù)時好時壞的問題會在復現(xiàn)的瞬間露出馬腳?；氐介_頭那臺 Windows 機器再回到開頭那個場景:同一條 SessionStart hook,現(xiàn)在在你同事的 Windows 機器上也會準時注入上下文了——沒有雙份腳本,沒有平臺判斷,沒有這臺機器再試一次。Superpowers 這套 polyglot 派發(fā)器加無擴展名腳本的寫法,核心收益就一句話:鉤子邏輯只寫一遍,bash 找不到就優(yōu)雅退出,找得到就在任何系統(tǒng)上準時執(zhí)行。如果你也在做多平臺 Claude Code 插件,hooks/目錄下的這三個文件值得逐行讀一遍,比任何跨平臺教程都短,而且全是能直接抄的生產(chǎn)實現(xiàn)?！久赓M下載鏈接】superpowersAn agentic skills framework software development methodology that works.項目地址: https://gitcode.com/GitHub_Trending/su/superpowers創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考