plugins/shared
2
0
Fork 0
Code Pull Requests Activity

feat(skills): 兩個 skill 都改成可一次處理多個 CLI，並修掉闇影劍找到的問題

Browse Source 
一次處理多個助理（使用者要求）：
- `--assistant` 從單一值改成清單，支援 `claude,codex,copilot` 與 `all`。
- 沒帶參數時偵測本機有哪些 CLI：只有一個就直接用，多個就讓使用者多選
  （安裝預設全選；移除是不可逆的，預設不全選）。
- 盤點與執行的迴圈改成「助理 × plugin」，回報表格加上「助理」欄。
- 正在執行本 skill 的那個助理排到最後處理——更新它要重啟工作階段，
  而移除它自己的 jsc-generic 之後，後面的助理就處理不到了。

闇影劍審 PR #30 找到的問題：
- Antigravity 與 OpenCode 的安裝分支無條件 `git clone`，clone 目錄已存在時
  會 fatal 中止（開發者自己就 clone 在預設的 ~/plugins）。改成先判斷
  `.git` 存在與否，已存在就 `pull --ff-only`。
- 新增「先確認 clone 在哪個分支」：預設路徑很可能是開發者的工作區，
  停在 develop 時裝進去的是未合併內容，要先告知使用者。
- OpenCode 的移除指令用 `{a,b,c}` brace expansion，有三種會靜默失效的情況
  （逗號後有空格、單一元素、dash/sh 不支援），全都是「什麼都沒刪但結束碼 0」。
  改成從本機 clone 的 skills/ 推導清單跑迴圈，退路是一行一個 rm。
- 硬編碼的 skill 目錄清單只是快照，plugin 新增 skill 後會殘留。改為優先從
  clone 推導，用表時要註明「清單可能不完整」。
- `cp -r` 不是覆蓋是合併，上游刪掉的檔案會留著。移除「覆蓋複製」這個
  不成立的說法。
- 階段 D 的版本欄只有 Antigravity 與 OpenCode 拿得到，其餘三家寫「未知」。

依 spec-plugin-version 升版 0.1.7（master 現行 0.1.6）。
This commit is contained in:
jiantw83
2026-07-31 08:48:50 +00:00
parent b75060bb3b
commit 93757b3036
2 changed files with 86 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/plugins-install/SKILL.md
+46 -20
View File
@@ -1,7 +1,7 @@
---
name: plugins-install
description: 一次把 JSC 的三個 plugin（jsc-code／jsc-doc／jsc-persona）安裝或更新到目前的 AI 助理，支援 Claude Code、Codex、GitHub Copilot CLI、Antigravity 四家原生 plugin CLI，OpenCode 則以複製 skills 目錄處理；每個 plugin 先判斷已安裝或未安裝，未安裝就安裝、已安裝就更新到最新，最後以表格回報每個 plugin 的結果與版本。當使用者說要安裝所有 jsc plugin、一次更新全部 skill 套件、把 code／doc／persona 都裝起來、換新機器要把 plugin 都補齊、或問怎麼一次更新所有 plugin 時觸發。不適用於：移除 plugin（用 /jsc-generic:plugins-uninstall）、只處理單一 plugin（直接照該 plugin README 的安裝章節）、安裝非 JSC 的第三方 plugin。
argument-hint: "[--assistant claude|codex|copilot|agy|opencode] [--plugins code,doc,persona] [--host <gitea 主機>] [--clone-dir <目錄>] [--yes]"
description: 一次把 JSC 的三個 plugin（jsc-code／jsc-doc／jsc-persona）安裝或更新到一個或多個 AI 助理，可同時處理 Claude Code、Codex、GitHub Copilot CLI、Antigravity 四家原生 plugin CLI 與 OpenCode（複製 skills 目錄）；沒指定時偵測本機裝了哪些 CLI 並讓使用者多選，每個 plugin 先判斷已安裝或未安裝，未安裝就安裝、已安裝就更新到最新，最後以「助理 × plugin」的表格回報結果與版本。當使用者說要安裝所有 jsc plugin、一次更新全部 skill 套件、把 code／doc／persona 都裝起來、要同時更新好幾個 CLI、換新機器要把 plugin 都補齊、或問怎麼一次更新所有 plugin 時觸發。不適用於：移除 plugin（用 /jsc-generic:plugins-uninstall）、只處理單一 plugin（直接照該 plugin README 的安裝章節）、安裝非 JSC 的第三方 plugin。
argument-hint: "[--assistant <助理清單，逗號分隔，或 all>] [--plugins code,doc,persona] [--host <gitea 主機>] [--clone-dir <目錄>] [--yes]"
---
# plugins-install — 一次安裝／更新所有 JSC plugin
@@ -10,7 +10,7 @@ argument-hint: "[--assistant claude|codex|copilot|agy|opencode] [--plugins code,
| 階段 | 動作 |
| --- | --- |
| A. 前置設定 | 決定要操作哪個助理（`--assistant`／偵測目前執行環境／詢問）→ 決定 gitea 主機 → 決定 plugin 清單（預設 code、doc、persona） |
| A. 前置設定 | 決定要操作哪些助理（`--assistant` 可帶多個或 all／偵測本機有哪些 CLI／多個就讓使用者多選）→ 決定 gitea 主機 → 決定 plugin 清單（預設 code、doc、persona） |
| B. 現況盤點 | 對每個 plugin 查詢 marketplace 與 plugin 是否已存在，決定「安裝」或「更新」 |
| C. 安裝／更新 | 依助理的原生指令逐一執行；Antigravity 與 OpenCode 走 clone／複製路徑 |
| D. 回報 | 以表格列出每個 plugin 的動作、結果與版本，並提醒重啟工作階段 |
@@ -35,7 +35,7 @@ argument-hint: "[--assistant claude|codex|copilot|agy|opencode] [--plugins code,
## 參數
- `--assistant claude|codex|copilot|agy|opencode`：指定要操作的助理。**省略時**依階段 A1 判斷。
- `--assistant <清單>`：要操作的助理，**可以多個**，以逗號分隔（`claude,codex,copilot,agy,opencode`），或用 `all` 代表本機找得到的全部。**省略時**依階段 A1 判斷（只有一個就直接用，多個就讓使用者多選）。
- `--plugins code,doc,persona`：要處理的 plugin（以逗號分隔，用 repo 短名）。**省略時預設三個全做**。
- `--host <gitea 主機>`：gitea 主機，省略時預設 `gitea.jsc.idv.tw`。
- `--clone-dir <目錄>`：Antigravity／OpenCode 的本機 clone 根目錄，**省略時預設 `~/plugins`**。
@@ -65,14 +65,20 @@ argument-hint: "[--assistant claude|codex|copilot|agy|opencode] [--plugins code,
## 階段 A：前置設定
### A1. 決定助理
### A1. 決定助理（可以一次多個）
`--assistant` 收的是**清單**，不是單一值：`--assistant claude,codex,copilot`、或 `--assistant all`。
最終得到的是一組助理，後面每個階段都對**這組的每一個**各跑一遍。
依序判斷，**第一個成立的就採用**：
1. 有帶 `--assistant` → 直接採用。
2. 目前正在執行本 skill 的助理可自我辨識（例如 Claude Code 的 `/plugin` 指令可用）→ 採用自己。
3. 逐一檢查哪些 CLI 存在（`command -v claude codex copilot agy opencode`）→ 只有一個就採用；**有多個就列出來問使用者**。
4. 一個都沒有 → 回報「找不到任何支援的助理 CLI」並停止。
1. 有帶 `--assistant` → 照它。`all` 代表「本機找得到的全部」（等同下面第 3 點的偵測結果）。
2. 沒帶 → 逐一檢查哪些 CLI 存在（`command -v claude codex copilot agy opencode`）：
- 找到 **1 個** → 直接用它。
- 找到 **多個** → 列出來讓使用者**多選**（預設全選）。帶 `--yes` 時不問，直接全做。
3. 一個都沒有 → 回報「找不到任何支援的助理 CLI」並停止。
> 目前正在執行本 skill 的那個助理，如果也在清單裡，**放到最後處理**——更新它自己會需要重啟工作階段。
### A2. 決定 gitea 主機與 clone 根目錄
@@ -95,9 +101,11 @@ argument-hint: "[--assistant claude|codex|copilot|agy|opencode] [--plugins code,
| Codex | `codex plugin marketplace list`、`codex plugin list` | 同上 |
| GitHub Copilot CLI | `copilot plugin marketplace list`、`copilot plugin list` | 同上 |
| Antigravity | `agy plugin list`，並看 `<clone-dir>/<repo>` 是否存在 | 目錄在且已安裝 → 更新；否則安裝 |
| OpenCode | 看 `~/.config/opencode/skills/` 底下是否已有該 plugin 的 skill 目錄 | 有 → 更新（覆蓋複製）；沒有 → 安裝 |
| OpenCode | 看 `~/.config/opencode/skills/` 底下是否已有該 plugin 的 skill 目錄 | 有 → 更新（重新複製；注意不是覆蓋，見階段 C）；沒有 → 安裝 |
指令不存在或子指令不被支援（舊版 CLI）時，**不要中斷整批**：記下該 plugin 為「跳過（CLI 不支援）」，繼續下一個，最後在階段 D 一起回報。
盤點的迴圈是**助理 × plugin**：階段 A1 選定的每個助理，都要對每個 plugin 各判定一次，結果分開記。
指令不存在或子指令不被支援（舊版 CLI）時，**不要中斷整批**：記下那一格為「跳過（CLI 不支援）」，繼續下一個，最後在階段 D 一起回報。同一個助理連續失敗（例如 CLI 存在但每個子指令都不支援）就整個助理標記為跳過，換下一個助理，不要卡住整批。
---
@@ -145,40 +153,58 @@ copilot plugin update <token>
> `agy plugin install <url>` 目前只支援 github.com；gitea 一律走「clone + 本地路徑」。`agy` 沒有 update 子指令，更新＝`git pull` 後重裝。
```bash
# 取得或更新本機 clone（目錄已存在就 pull，不要無條件 clone）
if [ -d "<clone-dir>/<repo>/.git" ]; then
git -C <clone-dir>/<repo> pull --ff-only
else
git clone <url> <clone-dir>/<repo>
fi
# 安裝
git clone <url> <clone-dir>/<repo>
agy plugin install <clone-dir>/<repo>
# 更新
git -C <clone-dir>/<repo> pull --ff-only
# 更新（agy 沒有 update 子指令，只能重裝）
agy plugin uninstall <plugin>
agy plugin install <clone-dir>/<repo>
```
- **不可無條件 `git clone`**：clone 目錄已經存在（很常見——開發者自己就 clone 在那裡）時，`git clone` 會以 `fatal: destination path already exists` 中止。階段 B 的判定只看「有沒有裝進 agy」，所以「目錄在、但 agy 沒裝」這個狀態會落進安裝分支，必須靠上面的 `if` 擋掉。
- `git pull --ff-only` 失敗（本機有未提交變更或分支分岔）→ **停在該 plugin**，回報現況讓使用者裁示，不得 `reset --hard`／`clean`，其餘 plugin 照常繼續。
- **先確認 clone 在哪個分支**：`git -C <clone-dir>/<repo> branch --show-current`。若不是發佈分支（`master`），代表要裝進去的是未合併的內容——先告訴使用者，由他決定要換分支還是照裝。預設的 `~/plugins` 很可能就是開發者自己的工作區。
### OpenCode
> OpenCode 的 plugin 是 npm 套件，不適用 skill 包；改用目錄安裝。**只會帶入 `skills/`，`scripts/` 與 `hooks/` 不會進去**——`jsc-persona` 依賴 `scripts/persona.mjs`，以此方式安裝等於只有說明書、沒有工具，安裝前要先告知使用者。
```bash
git clone <url> <clone-dir>/<repo> # 已存在則 git -C <clone-dir>/<repo> pull --ff-only
# 取得或更新本機 clone（同 Antigravity，不要無條件 clone）
if [ -d "<clone-dir>/<repo>/.git" ]; then
git -C <clone-dir>/<repo> pull --ff-only
else
git clone <url> <clone-dir>/<repo>
fi
mkdir -p ~/.config/opencode/skills
cp -r <clone-dir>/<repo>/skills/* ~/.config/opencode/skills/
```
> **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`~` → `$HOME`。
- **`cp -r` 不是覆蓋，是合併**：同名檔案會更新，但**上游已經刪掉的檔案會原地留著**。所以 skill 改名或移除之後，OpenCode 端會同時留著新舊兩份。要乾淨更新就先刪該 plugin 帶入的目錄再複製一次（刪法見 `/jsc-generic:plugins-uninstall` 的 OpenCode 段）。回報時不要講「已覆蓋」，講「已複製，舊檔可能殘留」。
---
## 階段 D：回報
以表格回報，一個 plugin 一列：
以表格回報，**一個「助理 × plugin」一列**：
| plugin | 動作 | 結果 | 版本 |
| --- | --- | --- | --- |
| `jsc-code` | 安裝／更新／跳過 | ✅ 成功／⚠ 需處理／❌ 失敗 | 例 `0.0.2` |
| 助理 | plugin | 動作 | 結果 | 版本 |
| --- | --- | --- | --- | --- |
| Claude Code | `jsc-code` | 安裝／更新／跳過 | ✅ 成功／⚠ 需處理／❌ 失敗 | 例 `0.0.2` |
| Codex | `jsc-code` | 更新 | ✅ 成功 | 未知 |
- 版本取自該 plugin 的 `plugin.json`；拿不到就寫「未知」。
只處理一個助理時可以省掉「助理」欄。**處理多個時一定要有**，否則使用者看不出哪一格出問題。
- 版本取自該 plugin 的 `plugin.json`。**只有 Antigravity 與 OpenCode 拿得到**（它們有本機 clone 可讀）；Claude／Codex／Copilot 把 plugin 放在各自 CLI 自管的快取目錄，除非該 CLI 的 `plugin list` 印得出版本，否則一律寫「未知」，不要去猜。
- 有任何一列不是 ✅ → 在表格下方逐項說明原因與建議動作。
- 最後固定提醒：**安裝或更新後要重啟工作階段**才會生效；`jsc-persona` 在 Claude Code 還要用 `/hooks` 確認六個 hook 都在。