# 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。

## 工具

五支工具都靠 python3 解析或改寫檔案。少了 python3，每一支都回報「需要的指令不存在」，不會裝成查無套件。

| 工具 | 用途 | 需要的指令 |
| --- | --- | --- |
| `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 <ecosystem> <project dir>` 偵測並執行建置與測試 | npm、python3、pytest、dotnet |

### 結束碼總表

一個數字只有一個意思，五支工具共用。新增工具請沿用這張表，不要自己編號。

| 碼 | 意思 | 呼叫方的動作 |
| --- | --- | --- |
| 0 | 成功 | 繼續 |
| 1 | 參數個數不對 | 停手 |
| 2 | ecosystem 不認識 | 停手 |
| 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` 是推不出建置或測試指令（改問使用者） | 見左欄 |
| 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 描述需求自動觸發。

<!-- JSC-SKILLS:START -->

### `pkg-update`

套件批次更新：列套件 → 查最新穩定版 → 逐 ecosystem 以 sub agent 更新 → 建置與測試（指令不明時決策樹詢問）→ 失敗還原全部變更。

更新途中要在版本來源檔案或程式碼留註解時，只寫鎖版本或繞道的原因，不寫內部議題編號、工作包編號、人名與 @ 提及、產生來源署名；第三方套件的 issue 連結可以寫，用來說明繞道成因與解除條件。完整清單與白名單見 [`jsc-review`](https://gitea.jsc.idv.tw/plugins/review) 的 `references/comment-scope.md`。

<!-- JSC-SKILLS:END -->

## 相關 domain

- [`jsc-ask`](https://gitea.jsc.idv.tw/plugins/ask)：建置與測試指令不明時的決策樹詢問
- [`jsc-sdlc`](https://gitea.jsc.idv.tw/plugins/sdlc)：維護階段的建議維護方法之一