jiantw83
e2b08f04a3
異常回報依 wiki 讀取的結束碼分流，只有頁面確定不存在才套範本建新頁。 版本閘門與重啟閘門的豁免清單各補上 hook 修復技能。 階段閘門把計畫階段移出擋人名單，改成只注入提醒。 錯誤掃描的自家 hook 判定補齊九支腳本，並加一條路徑判定。 修復技能與接線技能的內文改成真的走得到的路徑與真的存在的關卡數。 原本 wiki 讀取失敗會一路落到套範本那一步，金鑰失效或 API 出狀況時， 就拿一份空白範本蓋掉整份異常目錄，而寫入不做合併也不留備份，蓋掉就救不回來。 兩道閘門把唯一的 hook 修復路徑一起擋住，hook 一壞就沒有任何方法修回來， 閘門等於鎖掉解除自己的路徑。工作包閘門擋下計畫階段是誤擋： 計畫是純邏輯階段、不碰程式碼，而閘門只知道有 PR 未合併，判不出跟新計畫有沒有關聯。 自家 hook 判定只認得早期那五支，後來加的四支出錯會被當成第三方的，只回報不修正。 修復技能裡三個指向流程的路徑指到不存在的位置，照著走一定撲空； 接線流程寫四道關卡，實際上有五道，兩段中文說明也混在英文內文裡。 異常目錄改成先讀回舊頁、把新列附在文末、再整頁寫回；讀不回來就放棄寫目錄頁並回報， 寧可少一列索引，也不覆蓋別人的紀錄。兩份豁免清單各補一項，理由逐項寫在腳本檔頭。 計畫階段改印提醒後放行，放棄的在製品上限與代價一併寫在檔頭。 自家 hook 判定逐支列出腳本名，再加一條安裝路徑判定，日後新增 hook 忘了補清單也還認得出來。 三個路徑改指到擁有它的技能組，關卡數改成五道並逐關寫明結束碼，兩段中文說明改回英文。 版本閘門在同一次改動另補唯讀的建議子命令，把版本比對表收斂成一行結論， 部署技能不必自己再解一次那張表。
330 lines
16 KiB
Bash
Executable File
330 lines
16 KiB
Bash
Executable File
#!/usr/bin/env sh
|
||
# version-guard.sh — 技能使用前的版本前置檢查（PreToolUse，matcher: Skill）。
|
||
#
|
||
# 本機版本落後遠端發佈版本時擋下該次技能呼叫，並提示更新指令。
|
||
#
|
||
# 結束碼（hook 模式）：0=放行 2=擋下該次技能呼叫，訊息走 stderr。
|
||
# 安靜放行（exit 0）的情況要記清楚，這道閘門絕大多數時候走的是這幾條：逃生門
|
||
# JSC_VERSION_GUARD=off、工具名取得到但不是 Skill、取不到技能名、技能名不是
|
||
# jsc-{domain}:{name}、拆不出 domain、命中下方豁免清單那 7 支、讀不到本機實際載入版本、
|
||
# 推導不出遠端站台、查不到遠端版本、本機版本等於或超前遠端。
|
||
# 只有「本機落後遠端」這一條會 exit 2。
|
||
# 結束碼（report、recommend）：0=永遠成功，只讀不擋。結論看 stdout，不看結束碼。
|
||
# 註：本檔以 `. "$HERE/lib.sh"` 載入共用函式，沒有接 `|| true`。lib.sh 讀不到時 sh 會就地
|
||
# 結束並回 2，接在 PreToolUse 上就是無聲擋下每一次技能呼叫，上面那些放行路徑一條都跑不到
|
||
# （write-guard.sh 踩過這個坑）。部署時要確認 hooks/lib.sh 跟這支腳本一起裝上。
|
||
#
|
||
# 輸入：stdin JSON（Claude 格式）或環境變數，兩者都收。
|
||
# 工具名 JSC_TOOL_NAME、TOOL_NAME、stdin 的 tool_name
|
||
# 技能名 JSC_SKILL、SKILL、stdin 的 skill
|
||
# 兩邊都拿不到就安靜降級 exit 0。
|
||
#
|
||
# 判準與取值：
|
||
# - 比對對象是「遠端發佈版本」與「本機**實際載入**的版本」。
|
||
# 實際載入版本只認 installed_plugins.json 的 installPath 底下那份 plugin.json，
|
||
# 不看註冊在 installed_plugins.json 的版本欄位——那兩者可能不同，註冊值比較新時
|
||
# 會放過真正被載入的舊版。讀不到那份檔案就當查不到，安靜放行。
|
||
# - 只擋落後。本機版本等於或超前遠端一律放行：開發技能組時本機本來就會
|
||
# 超前預設分支，擋下去會讓維護者自己動不了。
|
||
# - **只有「本機落後遠端」會擋**。查不到資料一律放行（exit 0）：本機版本、
|
||
# Gitea 站台、遠端版本全部來自 Claude 的 plugin 檔案與 Gitea API，沒裝
|
||
# Claude 或離線的機器一筆都讀不到。那種情況擋下去，等於在沒有任何版本
|
||
# 證據時停掉每一次技能呼叫，護欄變成故障點。
|
||
#
|
||
# 豁免（這些技能永遠放行）：
|
||
# jsc-cli:deploy 更新整組技能的入口，擋了就沒有任何方法更新，會死鎖
|
||
# jsc-hooks:hooks-install 更新後要重新接線，擋了會讓更新做一半卡住
|
||
# jsc-cli:models SDLC 閘門依賴它產生 model-tags.tsv
|
||
# jsc-meta:* 開發技能組本身的工具，擋了就修不了技能組
|
||
# jsc-ask:ask deploy 問「install/update/uninstall」一定會呼叫它；
|
||
# 它本身落後版本被擋下，訊息又指回 /jsc-cli:deploy，
|
||
# deploy 卡在問不出模式那一步，跟直接擋 deploy 是同一種死鎖
|
||
# jsc-gitea:wiki jsc-ask:ask 問完一定寫回 wiki 才算完成，理由同上一條，
|
||
# 擋在這一步一樣是 deploy 做不完
|
||
# jsc-hooks:repair hook 壞掉時唯一的修復路徑。修 hook 的技能被 hook 擋下，
|
||
# 就沒有任何方法把 hook 修回來，跟直接擋 deploy 是同一種死鎖
|
||
#
|
||
# 逃生門：JSC_VERSION_GUARD=off 完全略過檢查（離線工作時用）。
|
||
#
|
||
# 快取：$JSC_HOME/version-cache/{CLI 代號}/{domain}，單行「{版本} {epoch}」，
|
||
# 預設 600 秒內不重查（JSC_VERSION_TTL 可調）。hook 與 report 在同一支 CLI 內共用。
|
||
# 舊路徑 $JSC_HOME/version-cache/{domain} 會在第一次讀取時複製到當前 CLI 的新路徑。
|
||
#
|
||
# 另有兩個非 hook 的子指令：
|
||
# version-guard.sh report 把每個已安裝 jsc-* plugin 的版本比對印成 TSV，每行
|
||
# 「{domain}<TAB>{本機}<TAB>{遠端}<TAB>{落後|最新|超前|查詢失敗}」，
|
||
# 最後一行「behind<TAB>{落後個數}」。供 jsc-cli:deploy 判斷要不要
|
||
# 把「更新」設成推薦選項。report 只讀不擋，永遠 exit 0。
|
||
# 本機沒有 Claude 的 plugin 註冊檔時改印「noregistry<TAB>{路徑}」
|
||
# 再接 behind 0：那代表這台機器無法做版本檢查，跟「全部最新」是兩件事。
|
||
#
|
||
# version-guard.sh recommend
|
||
# 把 report 那張表收斂成一個結論，只印一行、只有這一種格式：
|
||
# recommend<TAB>update|none|unverifiable
|
||
# 判定規則（呼叫端不必自己再判一次）：
|
||
# update 任何一個 plugin 落後就是 update，一個就夠，不等多數
|
||
# unverifiable 查不到註冊資訊（noregistry），或一列 domain 都沒有，
|
||
# 或每一列都是查詢失敗——沒有任何一項查得到的證據
|
||
# none 至少有一列查得到結果，而且沒有任何一項落後
|
||
# 查詢失敗的那幾列不計入：查不到不等於最新，也不等於落後，只是沒有證據。
|
||
# 輸出格式必須穩定，別的 domain 的技能直接讀第二欄；證據表要另外看的話
|
||
# 再呼叫一次 report，這裡刻意不混印，免得 cut 取值被表格內容打亂。
|
||
# recommend 只讀不擋，永遠 exit 0：判定結果只看那一行的第二欄。
|
||
HERE=$(dirname "$0"); . "$HERE/lib.sh"
|
||
|
||
REG="$HOME/.claude/plugins/installed_plugins.json"
|
||
MK="$HOME/.claude/plugins/known_marketplaces.json"
|
||
|
||
# 從檔案取 JSON 字串欄位。與 lib.sh 的 json_str 同一種 naive 解析，只是來源是檔案：
|
||
# 先把換行換成空白、再以逗號斷行，這樣每行最多一個欄位，取值不會被貪婪比對吃掉。
|
||
file_json_str() { # $1=檔案 $2=欄位名
|
||
[ -f "$1" ] || return 0
|
||
tr '\n' ' ' < "$1" | tr ',' '\n' \
|
||
| sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n1
|
||
}
|
||
|
||
# 本機實際載入版本：先取該 plugin 的 installPath，再讀那個目錄下的 plugin.json。
|
||
# 只認 installPath 底下那份檔案。註冊在 installed_plugins.json 的 version 欄位不當備援：
|
||
# 註冊值可能比實際載入的版本新，拿它來比對會放過真正被載入的舊版，護欄形同虛設。
|
||
# 讀不到那份檔案就當「查不到本機載入版本」，由呼叫端安靜放行。
|
||
local_version() { # $1=domain
|
||
[ -f "$REG" ] && [ -r "$REG" ] || return 0
|
||
_seg=$(tr -d '\n' < "$REG" \
|
||
| sed -n "s/.*\"jsc-$1@jsc\"[[:space:]]*:[[:space:]]*\[\([^]]*\)\].*/\1/p")
|
||
[ -n "$_seg" ] || return 0
|
||
_path=$(printf '%s' "$_seg" | tr ',' '\n' \
|
||
| sed -n 's/.*"installPath"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
|
||
[ -n "$_path" ] || return 0
|
||
file_json_str "$_path/plugin.json" version
|
||
}
|
||
|
||
# 遠端站台與 owner：從已註冊的 jsc marketplace 來源推導，其次 GITEA_HOST。
|
||
# 印出「{host} {owner}」；推導不出來時 host 為空字串。
|
||
remote_host_owner() {
|
||
_url=""
|
||
if [ -f "$MK" ]; then
|
||
_url=$(tr -d '\n' < "$MK" | sed -n 's/.*"jsc"[[:space:]]*:[[:space:]]*{//p' \
|
||
| tr ',' '\n' \
|
||
| sed -n 's/.*"url"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
|
||
fi
|
||
_h=$(printf '%s' "$_url" | sed -n 's#^\(https\{0,1\}://[^/]*\)/.*#\1#p')
|
||
_o=$(printf '%s' "$_url" | sed -n 's#^https\{0,1\}://[^/]*/\([^/]*\)/.*#\1#p')
|
||
if [ -z "$_h" ] || [ -z "$_o" ]; then
|
||
_h="${GITEA_HOST:-}"; _o="${JSC_GITEA_OWNER:-plugins}"
|
||
fi
|
||
printf '%s %s' "$_h" "$_o"
|
||
}
|
||
|
||
# 遠端發佈版本：一律經由 jsc-gitea 的 gitea.sh（技能準則），它會帶 GITEA_TOKEN，
|
||
# 並在缺 token 或 401／403 時退回 tea 的登入金鑰，私有存取庫才讀得到。
|
||
# 不指定 ref：Gitea 的 raw 端點預設就取該存取庫的預設分支，比在這裡寫死分支名準。
|
||
# 查不到就回傳空字串，由呼叫端放行。
|
||
remote_version() { # $1=domain $2=host $3=owner
|
||
_gsh=$(jsc_gitea_sh) || return 0
|
||
_v=""
|
||
for _try in 1 2; do # 暫時性網路失敗不該誤判成版本問題，失敗重試一次
|
||
_body=$(GITEA_HOST="$2" sh "$_gsh" api GET "/repos/$3/$1/raw/plugin.json" 2>/dev/null) \
|
||
&& _v=$(printf '%s' "$_body" | tr '\n' ' ' | tr ',' '\n' \
|
||
| sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
|
||
[ -n "$_v" ] && break
|
||
sleep 1
|
||
done
|
||
printf '%s' "$_v"
|
||
}
|
||
|
||
TTL="${JSC_VERSION_TTL:-600}"
|
||
cache_root="$JSC_HOME/version-cache"
|
||
|
||
cache_cli() {
|
||
_cli=$(cli_name | sed 's/[^A-Za-z0-9._-]/_/g')
|
||
[ -n "$_cli" ] || _cli=unknown
|
||
printf '%s' "$_cli"
|
||
}
|
||
|
||
cache_file() { # $1=domain
|
||
printf '%s/%s/%s' "$cache_root" "$(cache_cli)" "$1"
|
||
}
|
||
|
||
legacy_cache_file() { # $1=domain
|
||
printf '%s/%s' "$cache_root" "$1"
|
||
}
|
||
|
||
# 帶快取的遠端版本查詢。hook 與 report 共用同一份快取與同一個 TTL：
|
||
# report 每個 domain 各打一次網路（還帶重試），/jsc-cli:deploy 一跑就是全部 domain，
|
||
# 不共用快取等於每次部署都付一輪網路成本。同主機的不同 CLI 不共用快取，避免其中一支
|
||
# 讀到另一支留下的檢查紀錄。
|
||
cached_remote_version() { # $1=domain $2=host $3=owner
|
||
_cache=$(cache_file "$1")
|
||
_legacy=$(legacy_cache_file "$1")
|
||
if [ ! -f "$_cache" ] && [ -f "$_legacy" ]; then
|
||
mkdir -p "${_cache%/*}" 2>/dev/null || true
|
||
cat "$_legacy" > "$_cache" 2>/dev/null || true
|
||
fi
|
||
_now=$(now_epoch)
|
||
if [ -f "$_cache" ]; then
|
||
_cv=$(cut -d' ' -f1 "$_cache" 2>/dev/null)
|
||
_ca=$(cut -d' ' -f2 "$_cache" 2>/dev/null)
|
||
if [ -n "$_cv" ] && [ -n "$_ca" ] && [ $((_now - _ca)) -lt "$TTL" ]; then
|
||
printf '%s' "$_cv"; return 0
|
||
fi
|
||
fi
|
||
_rv=$(remote_version "$1" "$2" "$3")
|
||
if [ -n "$_rv" ]; then
|
||
mkdir -p "${_cache%/*}" 2>/dev/null || true
|
||
printf '%s %s\n' "$_rv" "$_now" > "$_cache" 2>/dev/null || true
|
||
fi
|
||
printf '%s' "$_rv"
|
||
}
|
||
|
||
# 語意化比較：印出 -1（$1 落後）、0（相等）、1（$1 超前）
|
||
ver_cmp() { # $1=版本 A $2=版本 B
|
||
awk -v a="$1" -v b="$2" '
|
||
BEGIN {
|
||
n = split(a, x, "."); m = split(b, y, ".")
|
||
for (i = 1; i <= 3; i++) {
|
||
xi = (i <= n ? x[i] + 0 : 0); yi = (i <= m ? y[i] + 0 : 0)
|
||
if (xi < yi) { print -1; exit }
|
||
if (xi > yi) { print 1; exit }
|
||
}
|
||
print 0
|
||
}'
|
||
}
|
||
|
||
# ── report：一次比對所有已安裝的 jsc plugin（非 hook 模式，不讀 stdin）
|
||
# 抽成函式是為了讓 recommend 讀同一份輸出。判定規則只寫在這一支腳本裡，recommend 直接解析
|
||
# 這裡印出來的表；兩邊各實作一次比對邏輯就會漂移，結論與證據對不起來。
|
||
do_report() {
|
||
# 註冊檔不存在或讀不到就明講。這裡不能只印 behind 0：呼叫端會把它讀成「都是最新」，
|
||
# 於是把「這台機器無法做版本檢查」誤報成「不用更新」。
|
||
# 舊版用 `tr -d '\n' < "$REG" 2>/dev/null`，那個 2>/dev/null 只蓋住 tr 的 stderr，
|
||
# 蓋不住 shell 開檔失敗的訊息，所以沒裝 Claude 的機器會先漏一行 cannot open。
|
||
if [ ! -f "$REG" ] || [ ! -r "$REG" ]; then
|
||
printf 'noregistry\t%s\n' "$REG"
|
||
printf 'behind\t0\n'
|
||
return 0
|
||
fi
|
||
ho=$(remote_host_owner)
|
||
r_host=$(printf '%s' "$ho" | cut -d' ' -f1)
|
||
r_owner=$(printf '%s' "$ho" | cut -d' ' -f2)
|
||
behind=0
|
||
domains=$(tr -d '\n' < "$REG" | tr ',' '\n' \
|
||
| sed -n 's/.*"jsc-\([a-z0-9][a-z0-9-]*\)@[^"]*"[[:space:]]*:.*/\1/p' | sort -u)
|
||
for d in $domains; do
|
||
lv=$(local_version "$d")
|
||
rv=""
|
||
[ -n "$r_host" ] && rv=$(cached_remote_version "$d" "$r_host" "$r_owner")
|
||
if [ -z "$rv" ]; then
|
||
st="查詢失敗"
|
||
else
|
||
case "$(ver_cmp "$lv" "$rv")" in
|
||
-1) st="落後"; behind=$((behind + 1)) ;;
|
||
1) st="超前" ;;
|
||
*) st="最新" ;;
|
||
esac
|
||
fi
|
||
printf '%s\t%s\t%s\t%s\n' "$d" "${lv:-?}" "${rv:-?}" "$st"
|
||
done
|
||
printf 'behind\t%s\n' "$behind"
|
||
return 0
|
||
}
|
||
|
||
if [ "${1:-}" = "report" ]; then
|
||
do_report
|
||
exit 0
|
||
fi
|
||
|
||
# ── recommend：把 report 那張表收斂成一個結論（非 hook 模式，不讀 stdin）
|
||
# 規則的唯一來源就是這一段，jsc-cli:deploy 只讀第二欄，不再自己解那張表。
|
||
if [ "${1:-}" = "recommend" ]; then
|
||
rep=$(do_report)
|
||
verdict=none
|
||
if printf '%s\n' "$rep" | grep -q '^noregistry '; then
|
||
# 沒有本機註冊檔，一項都比不了。這跟「全部最新」是兩件事，不能推薦 none。
|
||
verdict=unverifiable
|
||
else
|
||
behind_n=$(printf '%s\n' "$rep" | sed -n 's/^behind //p' | head -n1)
|
||
# 查得到結果的列：狀態欄是落後、最新或超前三種之一。查詢失敗那幾列不算證據。
|
||
known=$(printf '%s\n' "$rep" | awk -F'\t' '$1 != "behind" && $1 != "noregistry" && ($4 == "落後" || $4 == "最新" || $4 == "超前")' | wc -l | tr -d ' ')
|
||
if [ -n "$behind_n" ] && [ "$behind_n" -gt 0 ] 2>/dev/null; then
|
||
verdict=update
|
||
elif [ "${known:-0}" -gt 0 ] 2>/dev/null; then
|
||
verdict=none
|
||
else
|
||
# 一列 domain 都沒有，或每一列都查詢失敗：兩種都是「沒有任何查得到的證據」。
|
||
verdict=unverifiable
|
||
fi
|
||
fi
|
||
printf 'recommend\t%s\n' "$verdict"
|
||
exit 0
|
||
fi
|
||
|
||
read_stdin
|
||
|
||
[ "${JSC_VERSION_GUARD:-}" = "off" ] && exit 0
|
||
|
||
# 輸入相容：stdin JSON（Claude 格式）與環境變數（其他四支 CLI 接線時設定）都要收。
|
||
# 只讀 stdin 的話，用環境變數餵資料的 CLI 一律拿到空值，檢查會整支靜靜放行。
|
||
# 兩者都缺才是真的沒資料，那時照舊安靜降級 exit 0。
|
||
tool="${JSC_TOOL_NAME:-${TOOL_NAME:-$(json_str tool_name)}}"
|
||
[ -z "$tool" ] || [ "$tool" = "Skill" ] || exit 0
|
||
|
||
skill="${JSC_SKILL:-${SKILL:-$(json_str skill)}}"
|
||
[ -n "$skill" ] || exit 0
|
||
|
||
# 只管本技能組（jsc-{domain}:{name}）
|
||
case "$skill" in
|
||
jsc-*:*) ;;
|
||
*) exit 0 ;;
|
||
esac
|
||
|
||
domain=${skill#jsc-}
|
||
domain=${domain%%:*}
|
||
[ -n "$domain" ] || exit 0
|
||
|
||
# 豁免清單
|
||
case "$skill" in
|
||
jsc-cli:deploy|jsc-hooks:hooks-install|jsc-hooks:repair|jsc-cli:models|jsc-meta:*|jsc-ask:ask|jsc-gitea:wiki) exit 0 ;;
|
||
esac
|
||
|
||
# 更新指令依實際 CLI 給。印別的 CLI 的指令等於沒給指令，使用者照著打只會失敗。
|
||
update_cmd() { # $1=domain
|
||
case "$(cli_name)" in
|
||
claude)
|
||
printf 'claude plugin marketplace update jsc && claude plugin update jsc-%s@jsc' "$1" ;;
|
||
codex)
|
||
printf 'codex plugin marketplace upgrade jsc' ;;
|
||
copilot)
|
||
printf 'copilot plugin marketplace update jsc && copilot plugin update jsc-%s@jsc' "$1" ;;
|
||
antigravity)
|
||
printf 'git -C ~/plugins/%s pull && agy plugin uninstall jsc-%s && agy plugin install ~/plugins/%s' "$1" "$1" "$1" ;;
|
||
kiro)
|
||
printf 'kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-%s@jsc' "$1" ;;
|
||
*)
|
||
printf '用你的 CLI 的 plugin 更新指令更新 jsc-%s@jsc' "$1" ;;
|
||
esac
|
||
}
|
||
|
||
deny() { # $1=訊息
|
||
printf '[jsc][版本檢查][ERR]：%s\n' "$1" >&2
|
||
printf '更新指令：%s\n' "$(update_cmd "$domain")" >&2
|
||
printf '更新整組：/jsc-cli:deploy ｜ 確定要略過檢查：JSC_VERSION_GUARD=off\n' >&2
|
||
exit 2
|
||
}
|
||
|
||
# 讀不到本機實際載入版本就放行：沒有版本證據時擋下等於停掉每一次技能呼叫
|
||
local_ver=$(local_version "$domain")
|
||
[ -n "$local_ver" ] || exit 0
|
||
|
||
ho=$(remote_host_owner)
|
||
host=$(printf '%s' "$ho" | cut -d' ' -f1)
|
||
owner=$(printf '%s' "$ho" | cut -d' ' -f2)
|
||
[ -n "$host" ] || exit 0
|
||
|
||
# 遠端版本（走 hook 與 report 共用的快取與 TTL）
|
||
remote_ver=$(cached_remote_version "$domain" "$host" "$owner")
|
||
[ -n "$remote_ver" ] || exit 0
|
||
|
||
# 只擋「本機 < 遠端」這一種情況
|
||
[ "$(ver_cmp "$local_ver" "$remote_ver")" = "-1" ] || exit 0
|
||
deny "jsc-$domain 本機版本 $local_ver 落後遠端發佈版本 $remote_ver，本次技能呼叫已擋下"
|