jiantw83
ab5494a128
What：工具表補上還原閘門腳本一列與 `--detect` 用法，新增「還原的破壞性前提」一節，改寫結束碼總表與技能摘要。 Why：新腳本沒進工具表，讀 README 的人找不到它，也不知道還原多了一個必要旗標。原本寫「五支工具都靠 python3」也不對——新的閘門腳本只用 git，安裝那支根本不碰 python3，照著讀會誤判環境需求。還原策略已經改成先釘回舊版再重試，摘要卻還停在舊寫法。 How：工具表逐支列出真正需要的指令。新增一節寫清楚 `git clean -fd` 的風險與那五道前提，並說明判定從嚴、動手從窄。結束碼總表改成「一個數字一個類別」，同一個碼在各工具指的對象寫在該列裡。技能摘要改成先把嫌疑套件釘回舊版重試一次，真失敗才還原。 Who：pkg domain 的說明文件。
jsc-pkg — 套件批次更新
jsc 技能組的 pkg domain：把專案所有外部套件更新到最新穩定版本，完成後執行建置與測試。過不了先把嫌疑套件釘回舊版重試一次，真的裝不起來或建置測試仍過不了才還原變更。支援 nodejs / python / dotnet。
安裝、更新、移除
Marketplace 統一為 jsc（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 jsc-pkg@jsc。每個指令一行：
| CLI | 安裝 | 更新 | 移除 |
|---|---|---|---|
| claude | claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-pkg@jsc |
claude plugin marketplace update jsc && claude plugin update jsc-pkg@jsc |
claude plugin uninstall jsc-pkg@jsc |
| codex | codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-pkg@jsc |
codex plugin marketplace upgrade jsc |
codex plugin remove jsc-pkg@jsc |
| copilot | copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-pkg@jsc |
copilot plugin marketplace update jsc && copilot plugin update jsc-pkg@jsc |
copilot plugin uninstall jsc-pkg@jsc |
| antigravity | git clone https://gitea.jsc.idv.tw/plugins/pkg.git ~/plugins/pkg && agy plugin install ~/plugins/pkg |
git -C ~/plugins/pkg pull && agy plugin uninstall jsc-pkg && agy plugin install ~/plugins/pkg |
agy plugin uninstall jsc-pkg |
| kiro | kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-pkg@jsc |
kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-pkg@jsc |
kiro-cli plugin uninstall jsc-pkg@jsc |
antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用
/jsc-cli:deploy。
舊入口
plugins/jsc已移除，marketplace 正本移到plugins/meta。marketplace 名稱仍是jsc（取自 marketplace.json 的name欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行claude plugin marketplace remove jsc，再依上表重新 add。
工具
list-packages.sh、latest-version.sh、apply-version.sh、build-test.sh 靠 python3 解析或改寫檔案。少了 python3，這幾支都回報「需要的指令不存在」，不會裝成查無套件。install-deps.sh 不碰 python3，它把安裝交給各生態系自己的安裝器；git-guard.sh 只用 git。每支工具實際需要哪些指令，看下表最右欄。
| 工具 | 用途 | 需要的指令 |
|---|---|---|
tools/git-guard.sh |
git-guard.sh check <project dir> 確認是 git 工作樹且工作區乾淨；git-guard.sh revert <project dir> --confirm-destructive 還原工作區 |
git |
tools/list-packages.sh |
list-packages.sh [專案目錄] 偵測專案類型並列出所有外部套件與目前版本（TSV：ecosystem / name / current） |
python3 |
tools/latest-version.sh |
latest-version.sh <ecosystem> <name> 查最新穩定版（npm / pypi / nuget） |
curl、python3 |
tools/apply-version.sh |
apply-version.sh <ecosystem> <project dir> <name> <version> 改寫版本來源檔案，把套件釘選到指定版本 |
python3 |
tools/install-deps.sh |
install-deps.sh <ecosystem> <project dir> 重新解析並安裝相依套件（npm install、pip install、dotnet restore） |
npm、pip、dotnet |
tools/build-test.sh |
build-test.sh [--detect] <ecosystem> <project dir> 偵測並執行建置與測試；--detect 只偵測不執行，用來在動任何檔案之前先問出推不出指令的情況 |
npm、python3、pytest、dotnet |
還原的破壞性前提
git-guard.sh revert 會執行 git clean -fd，未追蹤檔案刪掉沒有 reflog 可救。所以前提判定寫在腳本裡，不寫在技能內文：目錄存在、git 指令存在、確實是 git 工作樹（不是裸存取庫）、呼叫端明確傳入 --confirm-destructive、目標不是檔案系統根目錄，五條全過才會跑第一個破壞性指令。任何一條不過就回 1、4、5 或 6，工作區一個位元組都不動。
check 的乾淨判定看整個存取庫，revert 的還原只作用在專案目錄以下：判定從嚴，動手從窄。
結束碼總表
一個數字一個類別，六支工具共用；同一個類別在各工具指的對象可以不同，差別寫在該列裡。新增工具請沿用這張表，不要自己編號。
| 碼 | 意思 | 呼叫方的動作 |
|---|---|---|
| 0 | 成功 | 繼續 |
| 1 | 參數個數不對 | 停手 |
| 2 | 不認識的輸入：多數工具是 ecosystem 不認識，git-guard.sh 是子指令不認識 |
停手 |
| 3 | 該 ecosystem 沒有來源檔案 | 跳過這個 ecosystem 或套件 |
| 4 | 依工具而定：list-packages.sh、build-test.sh、install-deps.sh 是指令不存在（停手）；latest-version.sh、apply-version.sh 是查不到該套件（跳過） |
見左欄 |
| 5 | 依工具而定：latest-version.sh、apply-version.sh 是指令不存在（停手）；build-test.sh 是推不出建置或測試指令（改問使用者）；git-guard.sh 是前提不成立，指不是 git 工作樹、工作區不乾淨、還原後仍不乾淨（停手） |
見左欄 |
| 6 | 找不到專案目錄 | 停手 |
| 其他 | 底層指令的結束碼 | 只有 install-deps.sh、build-test.sh 會走還原 |
6 不與 3 合併：找不到專案目錄是輸入壞了，併進 3 會被當成跳過藏起來。latest-version.sh 不收專案目錄，所以沒有 6。
4 與 5 在各工具間意思不同，是為了保住既有的跳過路由；新增工具請優先用 4 表示指令不存在。
回 1、回 2、回 6 與回「指令不存在」時，技能只回報並停手，不還原工作樹——工具鏈壞了不是套件壞了，還原只會白白刪掉檔案。停手不等於沒動過檔案：更新步驟跑到一半才停手時，已改寫的版本來源檔案留在原地，技能要一併報出改了哪些檔案與哪些套件。
Skills 目錄
呼叫方式：Claude / Antigravity /jsc-pkg:{name}；Codex ${name}；Copilot / Kiro 描述需求自動觸發。
pkg-update
套件批次更新：先驗 git 工作區乾淨當硬閘門，過了才列套件並問出建置與測試指令 → 各 ecosystem 以 sub agent 並行更新 → 建置與測試，失敗先把兇手釘回舊版重試一次 → 仍失敗才還原全部變更。
更新途中要在版本來源檔案或程式碼留註解時，只寫繞道或釘回舊版的原因；第三方套件的 issue 連結可以寫，用來說明成因與解除條件。禁止清單的正本只有一份，在 jsc-review 的 references/comment-scope.md，由 jsc-hooks 的 hooks/comment-scope.sh 在程式層強制。