plugins/shared
2
0
Fork 0
Code Pull Requests Activity

docs(plugins 安裝管理): 統一無 plugin 匯入指令工具流程

Browse Source
This commit is contained in:
jiantw83
2026-08-03 06:17:11 +00:00
parent 3dccddf055
commit 0d3bd72de3
4 changed files with 27 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+1 -1
View File
@@ -8,7 +8,7 @@
- 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。
- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc-shared:<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc-shared:` 前綴，不需強制加。
- 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。
- 本 repo 只保留純 `skills/` 內容；載入前請看各 skill `description` 標示的支援範圍與 `README.md` 的「Skills 目錄」。OpenCode 以複製 `skills/` 目錄安裝。
- 本 repo 只保留純 `skills/` 內容；載入前請看各 skill `description` 標示的支援範圍與 `README.md` 的「Skills 目錄」。沒有 plugin 匯入指令、但可使用 skill 的助理，統一先 clone 技能組到工具專屬資料夾，再依 `README.md` 的指定位置匯入。
## 慣例
README.md
+11 -6
View File
@@ -14,7 +14,7 @@
| Claude Code | `claude plugin`（marketplace） | `/jsc-shared:<name>` 或自動觸發 | ✅ |
| Codex | `codex plugin`（marketplace） | `$<name>` 或 `/skills` 選單 | ❌（用 `$name`） |
| Antigravity | `agy plugin install` | `/jsc-shared:<name>` 或自動觸發 | ✅ |
| OpenCode | skills 目錄（複製/clone） | 描述需求自動觸發 | ❌（依名稱） |
| OpenCode | skills 目錄（先 clone 到工具專屬資料夾，再依 README 匯入） | 描述需求自動觸發 | ❌（依名稱） |
| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc-shared:` 前綴） |
> Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。
@@ -118,10 +118,15 @@ agy plugin uninstall jsc-shared
- 其他：`agy plugin list`、`agy plugin enable jsc-shared` / `disable jsc-shared`、`agy plugin validate <path>`。安裝後重啟工作階段。
- **呼叫**：`/jsc-shared:<name>`（例 `/jsc-shared:spec-output`）或依描述自動觸發。
### OpenCode
### 無 plugin 指令但可使用 skill 的助理
OpenCode 的「plugin」是 TypeScript/npm 套件，不適用於 skill 包；skills 改用**目錄安裝**。
OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、`~/.agents/skills/`）。
以 OpenCode 為例，這類工具不走原生 plugin install / uninstall，而是：
1. 先把整組 skill clone 到工具的專屬資料夾。
2. 再依技能組自己的 `README.md`，把技能匯入到 README 指定的位置。
3. 移除時則反向刪除 README 指定的那些 skill 目錄。
OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、`~/.agents/skills/`），因此可把技能匯入這些位置。
```bash
# 安裝
@@ -214,8 +219,8 @@ copilot plugin marketplace remove shared
| Skill | 用途 | 使用方法 |
| --- | --- | --- |
| `plugins-install` | 一次**安裝或更新** `jsc-code`、`jsc-doc`、`jsc-persona`、`jsc-shared`：先盤點每個 plugin 已安裝或未安裝，未安裝就安裝、已安裝就更新到最新，最後以表格回報動作、位置、結果與版本。`agy` 走 clone＋本地路徑安裝；`opencode` 這類**沒有 plugin 指令**的助理先讀該工具設定找出 skills 實際掛載路徑（可能是某個專案下的 `.opencode/skills`），**已安裝就在該路徑就地更新、未安裝才放進工具的全域資料夾** | `/jsc-shared:plugins-install`；可帶 `--assistant claude\|codex\|copilot\|agy\|opencode`、`--plugins code,doc,persona,shared`、`--host <gitea 主機>`、`--clone-dir <目錄>`、`--yes` |
| `plugins-uninstall` | 一次**移除** `jsc-code`、`jsc-doc`、`jsc-persona`、`jsc-shared`：動手前先列出將被移除的項目與不會被碰的資料請使用者確認，移除順序固定把 `jsc-shared` 放最後（本 skill 就住在裡面）。人格倉庫與記憶目錄一律不刪 | `/jsc-shared:plugins-uninstall`；可帶 `--assistant …`、`--plugins code,doc,persona,shared`、`--keep-marketplace`、`--yes` |
| `plugins-install` | 一次**安裝或更新** `jsc-code`、`jsc-doc`、`jsc-persona`、`jsc-shared`：先盤點每個 plugin 已安裝或未安裝，未安裝就安裝、已安裝就更新到最新，最後以表格回報動作、位置、結果與版本。`agy` 走 clone＋本地路徑安裝；OpenCode 這類**沒有 plugin 匯入指令、但可使用 skill** 的助理先把技能組 clone 到工具專屬資料夾，再依技能組 `README.md` 匯入到指定位置，**已安裝就在該路徑就地更新、未安裝才放進工具的全域資料夾** | `/jsc-shared:plugins-install`；可帶 `--assistant claude\|codex\|copilot\|agy\|opencode`、`--plugins code,doc,persona,shared`、`--host <gitea 主機>`、`--clone-dir <目錄>`、`--yes` |
| `plugins-uninstall` | 一次**移除** `jsc-code`、`jsc-doc`、`jsc-persona`、`jsc-shared`：動手前先列出將被移除的項目與不會被碰的資料請使用者確認，移除順序固定把 `jsc-shared` 放最後（本 skill 就住在裡面）。人格倉庫與記憶目錄一律不刪；OpenCode 這類**沒有 plugin 匯入指令、但可使用 skill** 的助理則依技能組 `README.md` 反向刪除匯入位置 | `/jsc-shared:plugins-uninstall`；可帶 `--assistant …`、`--plugins code,doc,persona,shared`、`--keep-marketplace`、`--yes` |
> `plugins-install` 與 `plugins-uninstall` 都會處理 `jsc-shared`；移除時一定放最後一步。
skills/plugins-install/SKILL.md
+11 -11
View File
@@ -1,6 +1,6 @@
---
name: plugins-install
description: 一次把 JSC 的四個 plugin（jsc-code／jsc-doc／jsc-persona／jsc-shared）安裝或更新到一個或多個 AI 助理，可同時處理 Claude Code、Codex、GitHub Copilot CLI、Antigravity 四家原生 plugin CLI 與 OpenCode 這類沒有 plugin 指令、靠複製 skills 目錄的助理；沒指定時偵測本機裝了哪些 CLI 並讓使用者多選，每個 plugin 先判斷已安裝或未安裝，未安裝就安裝、已安裝就更新到最新。非指令助理另走「先讀該工具設定找出 skills 實際掛載路徑」的判定：已安裝就在設定指到的那個路徑（可能是某個專案目錄）就地更新，未安裝才把 skills 放進該工具的預設資料夾，最後以「助理 × plugin」的表格回報動作、位置、結果與版本。當使用者說要安裝所有 jsc plugin、一次更新全部 skill 套件、把 code／doc／persona／shared 都裝起來、要同時更新好幾個 CLI、換新機器要把 plugin 都補齊、OpenCode 的 skill 更新到錯的地方、要更新專案自己那份 skills、或問怎麼一次更新所有 plugin 時觸發。不適用於：移除 plugin（用 /jsc-shared:plugins-uninstall）、只處理單一 plugin（直接照該 plugin README 的安裝章節）、安裝非 JSC 的第三方 plugin。
description: 一次把 JSC 的四個 plugin（jsc-code／jsc-doc／jsc-persona／jsc-shared）安裝或更新到一個或多個 AI 助理，可同時處理 Claude Code、Codex、GitHub Copilot CLI、Antigravity 四家原生 plugin CLI 與沒有 plugin 匯入指令、但可使用 skill 的助理；沒指定時偵測本機裝了哪些 CLI 並讓使用者多選，每個 plugin 先判斷已安裝或未安裝，未安裝就安裝、已安裝就更新到最新。非指令助理先把技能組 clone 到工具專屬資料夾，再依技能組 README.md 將技能匯入到指定位置：已安裝就在 README 指到的路徑就地更新，未安裝才放進工具的預設資料夾，最後以「助理 × plugin」的表格回報動作、位置、結果與版本。當使用者說要安裝所有 jsc plugin、一次更新全部 skill 套件、把 code／doc／persona／shared 都裝起來、要同時更新好幾個 CLI、換新機器要把 plugin 都補齊、技能匯入到錯的地方、要更新專案自己那份 skills、或問怎麼一次更新所有 plugin 時觸發。不適用於：移除 plugin（用 /jsc-shared:plugins-uninstall）、只處理單一 plugin（直接照該 plugin README 的安裝章節）、安裝非 JSC 的第三方 plugin。
argument-hint: "[--assistant <助理清單，逗號分隔，或 all>] [--plugins code,doc,persona,shared] [--host <gitea 主機>] [--clone-dir <目錄>] [--yes]"
---
@@ -12,7 +12,7 @@ argument-hint: "[--assistant <助理清單，逗號分隔，或 all>] [--plugins
| --- | --- |
| A. 前置設定 | 決定要操作哪些助理（`--assistant` 可帶多個或 all／偵測本機有哪些 CLI／多個就讓使用者多選）→ 決定 gitea 主機 → 決定 plugin 清單（預設 code、doc、persona、shared） |
| B. 現況盤點 | 對每個 plugin 查詢 marketplace 與 plugin 是否已存在，決定「安裝」或「更新」 |
| C. 安裝／更新 | 依助理的原生指令逐一執行；Antigravity 走 clone＋本地路徑，OpenCode 這類**非指令助理**走「讀設定 → 就地更新／放進工具資料夾」 |
| C. 安裝／更新 | 依助理的原生指令逐一執行；Antigravity 走 clone＋本地路徑，沒有 plugin 匯入指令但可使用 skill 的助理則先 clone 技能組到工具專屬資料夾，再依 README.md 匯入到指定位置 |
| D. 回報 | 以表格列出每個 plugin 的動作、結果與版本，並提醒重啟工作階段 |
---
@@ -23,7 +23,7 @@ argument-hint: "[--assistant <助理清單，逗號分隔，或 all>] [--plugins
- `/jsc-shared:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、表格呈現。
- `/jsc-shared:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認。
- `/jsc-shared:spec-git-safety`：Antigravity／OpenCode 路徑會動到本機 clone，**工作區有未提交變更時不得強制更新**。
- `/jsc-shared:spec-git-safety`：Antigravity／其他會動到本機 clone 的工具路徑有未提交變更時不得強制更新。
本 skill 特有補充：
@@ -38,7 +38,7 @@ argument-hint: "[--assistant <助理清單，逗號分隔，或 all>] [--plugins
- `--assistant <清單>`：要操作的助理，**可以多個**，以逗號分隔（`claude,codex,copilot,agy,opencode`），或用 `all` 代表本機找得到的全部。**省略時**依階段 A1 判斷（只有一個就直接用，多個就讓使用者多選）。
- `--plugins code,doc,persona,shared`：要處理的 plugin（以逗號分隔，用 repo 短名）。**省略時預設四個全做**。
- `--host <gitea 主機>`：gitea 主機，省略時預設 `gitea.jsc.idv.tw`。
- `--clone-dir <目錄>`：Antigravity／OpenCode 的本機 clone 根目錄，**省略時預設 `~/plugins`**。
- `--clone-dir <目錄>`：Antigravity／其他會用到本機 clone 的工具的根目錄，**省略時預設 `~/plugins`**。
- `--yes`：全自動，不做確認式詢問（必要決策仍會中斷）。
---
@@ -103,7 +103,7 @@ argument-hint: "[--assistant <助理清單，逗號分隔，或 all>] [--plugins
| 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（非指令助理） | 先依「非指令助理的安裝位置判定」找出**所有**候選 skills 目錄，再看哪個底下已有該 plugin 的 skill 目錄 | 有 → **更新該位置**（重新複製；注意不是覆蓋，見階段 C）；都沒有 → 安裝到工具預設資料夾 |
| 無 plugin 匯入指令但可使用 skill 的助理 | 先依工具設定或 README.md 找出**所有**候選匯入位置，再看哪個底下已有該 plugin 的 skill 目錄 | 有 → **更新該位置**（重新複製；注意不是覆蓋，見階段 C）；都沒有 → 安裝到工具預設資料夾 |
盤點的迴圈是**助理 × plugin**：階段 A1 選定的每個助理，都要對每個 plugin 各判定一次，結果分開記。
@@ -174,10 +174,10 @@ agy plugin install <clone-dir>/<repo>
- `git pull --ff-only` 失敗（本機有未提交變更或分支分岔）→ **停在該 plugin**，回報現況讓使用者裁示，不得 `reset --hard`／`clean`，其餘 plugin 照常繼續。
- **先確認 clone 在哪個分支**：`git -C <clone-dir>/<repo> branch --show-current`。若不是發佈分支（`master`），代表要裝進去的是未合併的內容——先告訴使用者，由他決定要換分支還是照裝。預設的 `~/plugins` 很可能就是開發者自己的工作區。
### OpenCode（非指令助理）
### 無 plugin 匯入指令但可使用 skill 的助理
> OpenCode 的 plugin 是 npm 套件，不適用 skill 包；改用**目錄安裝**。OpenCode 只會帶入 `skills/`，安裝前要先告知使用者。
> 這類助理**沒有 plugin CLI 可查安裝清單**，所以不能像四家原生 CLI 那樣「問 CLI 裝了沒」，也**不可預設就往全域目錄倒**——先讀設定找出它實際掛在哪，再決定要更新誰。
> 這類助理沒有可用的 plugin 匯入指令，但可以使用 skill，因此改用**目錄安裝**。先把技能組 clone 到工具專屬資料夾，再依技能組 `README.md` 的匯入說明，把技能放到指定位置。
> 這類助理**沒有 plugin CLI 可查安裝清單**，所以不能像四家原生 CLI 那樣「問 CLI 裝了沒」，也**不可預設就往全域目錄倒**——先讀設定或 README.md 找出它實際掛在哪，再決定要更新誰。
#### C-1. 先判定安裝位置（讀設定，不要臆測）
@@ -221,13 +221,13 @@ else
git clone <url> <clone-dir>/<repo>
fi
# <target> = C-1 判定出「已經有這個 plugin」的那個目錄（可能是某個專案下的 .opencode/skills）
# <target> = C-1 / README.md 判定出「已經有這個 plugin」的那個目錄（可能是某個專案下的 skills 目錄）
cp -r <clone-dir>/<repo>/skills/* "<target>/"
```
- **就地更新，不要另外補一份到全域目錄**：設定指到專案路徑就更新專案路徑；多倒一份到 `~/.config/opencode/skills/` 會造成同名 skill 兩份、之後每次更新都要記得更兩邊。
- **就地更新，不要另外補一份到全域目錄**：設定或 README.md 指到專案路徑就更新專案路徑；多倒一份到其他位置會造成同名 skill 兩份、之後每次更新都要記得更兩邊。
- **多個候選位置都已安裝** → 全部更新，並在階段 D **逐列列出各自的位置**，同時提醒使用者這個 plugin 被重複安裝了，建議留一份。
- **目標在某個 git 專案內**（例如 `.opencode/skills` 被該專案追蹤）→ 複製後會產生未提交變更。依 `/jsc-shared:spec-git-safety`：只回報「該專案有新增／異動檔案待處理」，**不代為 commit、不動既有變更**。
- **目標在某個 git 專案內** → 複製後會產生未提交變更。依 `/jsc-shared:spec-git-safety`：只回報「該專案有新增／異動檔案待處理」，**不代為 commit、不動既有變更**。
#### C-3. 未安裝 → 放進工具的資料夾
skills/plugins-uninstall/SKILL.md
+4 -4
View File
@@ -1,6 +1,6 @@
---
name: plugins-uninstall
description: 一次把 JSC 的四個 plugin（jsc-code／jsc-doc／jsc-persona／jsc-shared）從一個或多個 AI 助理移除，可同時處理 Claude Code、Codex、GitHub Copilot CLI、Antigravity 四家原生 plugin CLI 與 OpenCode（刪除先前複製進去的 skill 目錄）；沒指定時偵測本機裝了哪些 CLI 並讓使用者多選；移除順序固定把 jsc-shared 放到最後（本 skill 就住在裡面，移除後即失效），並在動手前列出將被移除的項目與會受影響的本機資料讓使用者確認。當使用者說要移除所有 jsc plugin、把 skill 套件整組解除安裝、清掉 code／doc／persona／shared、重灌前先卸載、要同時從好幾個 CLI 移除、或問怎麼一次移除全部 plugin 時觸發。不適用於：安裝或更新（用 /jsc-shared:plugins-install）、只移除單一 plugin（直接照該 plugin README 的移除章節）、刪除人格資料或 Gitea 上的存取庫。
description: 一次把 JSC 的四個 plugin（jsc-code／jsc-doc／jsc-persona／jsc-shared）從一個或多個 AI 助理移除，可同時處理 Claude Code、Codex、GitHub Copilot CLI、Antigravity 四家原生 plugin CLI 與沒有 plugin 匯入指令、但可使用 skill 的助理；沒指定時偵測本機裝了哪些 CLI 並讓使用者多選；移除順序固定把 jsc-shared 放到最後（本 skill 就住在裡面，移除後即失效），並在動手前列出將被移除的項目與會受影響的本機資料讓使用者確認。當使用者說要移除所有 jsc plugin、把 skill 套件整組解除安裝、清掉 code／doc／persona／shared、重灌前先卸載、要同時從好幾個 CLI 移除、或問怎麼一次移除全部 plugin 時觸發。不適用於：安裝或更新（用 /jsc-shared:plugins-install）、只移除單一 plugin（直接照該 plugin README 的移除章節）、刪除人格資料或 Gitea 上的存取庫。
argument-hint: "[--assistant <助理清單，逗號分隔，或 all>] [--plugins code,doc,persona,shared] [--keep-marketplace] [--keep-clone] [--yes]"
---
@@ -141,12 +141,12 @@ agy plugin uninstall <plugin>
- 本機 clone（`~/plugins/<repo>` 之類）**預設保留**；使用者在階段 B 明確同意才刪，且該目錄有未提交變更時一律保留並回報。
### OpenCode
### 無 plugin 匯入指令但可使用 skill 的助理
逐一刪除該 plugin 帶入的 skill 目錄。**最可靠的做法是從本機 clone 推導清單**，而不是照抄上表——上表是快照，plugin 新增 skill 之後就會漏：
逐一刪除該 plugin 帶入的 skill 目錄。**最可靠的做法是從本機 clone 與 README.md 推導清單**，而不是照抄上表——上表是快照，plugin 新增 skill 之後就會漏：
```bash
# clone 還在：從來源目錄推導要刪哪些（唯一不會漏的做法）
# clone 還在：從來源目錄與 README.md 推導要刪哪些（唯一不會漏的做法）
for s in <clone-dir>/<repo>/skills/*/; do
rm -rf "$HOME/.config/opencode/skills/$(basename "$s")"
done