jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
154 lines
9.7 KiB
Markdown
154 lines
9.7 KiB
Markdown
---
|
||
name: spec-plugin-cli
|
||
description: JSC plugins 共用「五種助理 plugin 安裝／更新／移除指令」規範：Claude Code、Codex、Antigravity（agy）、OpenCode、GitHub Copilot CLI 各自的 marketplace add／plugin install／plugin update／plugin uninstall 完整指令語法，以 <host>/<name>/<plugin>/<marketplace>/<token>/<url> 佔位符套用到任一 JSC plugin repo（code／doc／persona／shared），本機開發（免 push）的本地路徑一律用 %USERPROFILE%\...／$HOME/... 佔位符示範，不得寫死真實使用者帳號路徑。當其他 skill 或 README 內文引用 spec-plugin-cli 或 /jsc-shared:spec-plugin-cli、或需要說明／產生某個 plugin 的安裝、更新、移除指令時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-plugin-cli — 共用 Plugin 安裝／更新／移除指令規範
|
||
|
||
四個 JSC plugin repo（`code`／`doc`／`persona`／`shared`）各自的 README 都有一節「安裝 / 更新 / 移除（各助理）」，內容除了 plugin 名稱之外幾乎完全重複；`shared/skills/plugins-install/SKILL.md`、`shared/skills/plugins-uninstall/SKILL.md` 又各自重述一次同一組指令。本規範是這組指令的**唯一權威版本**：其他 skill 內文或 README 需要說明某個助理的 plugin 安裝／更新／移除指令時，一律引用本節並只代換下方佔位符，不得另行複述完整指令區塊。
|
||
|
||
## 佔位符（唯一權威定義）
|
||
|
||
| 佔位符 | 意義 | 以 `jsc-shared` 為例 |
|
||
| --- | --- | --- |
|
||
| `<host>` | gitea 主機；決定順序見 `/jsc-shared:spec-gitea` 的「gitea 主機決定順序」一節，本規範不重複定義 | `gitea.jsc.idv.tw` |
|
||
| `<name>` | plugin repo 短名 | `shared`（其餘為 `doc`／`code`／`persona`） |
|
||
| `<url>` | repo 網址 = `https://<host>/plugins/<name>.git` | `https://gitea.jsc.idv.tw/plugins/shared.git` |
|
||
| `<plugin>` | plugin 名（各助理 manifest 的 `name` 欄位，例如 `.claude-plugin/plugin.json`） | `jsc-shared` |
|
||
| `<marketplace>` | marketplace 名（Claude／Codex／Copilot marketplace 登錄名） | `shared` |
|
||
| `<token>` | 安裝／更新／移除用的 install token，固定等於 `<plugin>@<marketplace>` | `jsc-shared@shared` |
|
||
|
||
> **`persona` 沒有例外**：現行 marketplace 名就是 repo 名 `persona`（即 `<token>` = `jsc-persona@persona`），跟其他三個 repo 規則一致。`jsc-plugins` 是**已停用的舊名**，只會出現在早期安裝過的本機殘留鍵裡；遇到使用者本機還留著 `jsc-persona@jsc-plugins`，要提醒先移除舊鍵再用 `jsc-persona@persona` 重裝，不要把舊名當成現行規則的例外套用。
|
||
|
||
## 通用前提
|
||
|
||
- **Claude / Codex 從 git URL 安裝會 clone 遠端**，安裝前請先把該 repo `push` 到 gitea。
|
||
- **Antigravity 的 `agy plugin install <url>` 目前只支援 github.com**；gitea 等自架 git 不支援 URL 安裝，一律走「clone 到本機固定目錄 + 本地路徑安裝」，且**該 clone 目錄持久保留、更新用 `git pull` 而非每次重新 clone**（與 `plugins-install`／`plugins-uninstall` 的階段 C 實作一致）。
|
||
- **OpenCode 沒有原生 plugin 匯入指令，但可使用 skill**：改用「clone 到本機固定目錄 → 複製 `skills/` 到工具的 skills 目錄」的目錄安裝法，同樣採持久 clone + `git pull`。
|
||
- **GitHub Copilot CLI** 具備與 Claude Code 相同形態的 `marketplace` / `plugin` 原生指令。
|
||
- 下方每個助理小節的指令都以「安裝 → 更新 → 移除」固定順序給出。
|
||
|
||
---
|
||
|
||
## Claude Code
|
||
|
||
```bash
|
||
# 安裝
|
||
claude plugin marketplace add <url>
|
||
claude plugin install <token>
|
||
|
||
# 更新
|
||
claude plugin marketplace update <marketplace>
|
||
claude plugin update <token>
|
||
|
||
# 移除
|
||
claude plugin uninstall <token>
|
||
claude plugin marketplace remove <marketplace>
|
||
```
|
||
|
||
- 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。
|
||
- **本機開發（免 push）**：改用本地路徑安裝，例如 Windows `claude plugin marketplace add %USERPROFILE%\<你的工作區路徑>\<name>`、Linux／macOS／WSL `claude plugin marketplace add $HOME/<你的工作區路徑>/<name>`，安裝後同樣接 `claude plugin install <token>`。**路徑僅示範結構，實際位置依開發者本機安排；引用端產生文件時不得把真實使用者帳號名稱寫死進路徑**，一律用 `%USERPROFILE%\...`／`$HOME/...` 這類佔位符。正式安裝仍以 Gitea 遠端＋上方指令為準。
|
||
- 呼叫：Claude Code / Antigravity 用 `/jsc-<name>:<skill>`（例 `/jsc-shared:spec-output`）。
|
||
|
||
## Codex
|
||
|
||
```bash
|
||
# 安裝
|
||
codex plugin marketplace add <url>
|
||
codex plugin add <token>
|
||
|
||
# 更新（重新抓取 marketplace 的 git 快照）
|
||
codex plugin marketplace upgrade <marketplace>
|
||
|
||
# 移除
|
||
codex plugin remove <token>
|
||
codex plugin marketplace remove <marketplace>
|
||
```
|
||
|
||
- 安裝 token `<token>` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。
|
||
- 該 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。
|
||
- 呼叫：`$<skill>`（例 `$spec-output`），或用 `/skills` 選單。
|
||
|
||
## Antigravity（`agy`）
|
||
|
||
> `agy plugin install <url>` 目前**只支援 github.com**；gitea 等自架 git 不支援 URL 安裝，一律走「clone 到本機固定目錄，再用本地路徑安裝」；`agy` 沒有 `update` 子指令，更新＝`git pull` 後重裝。
|
||
|
||
```bash
|
||
# 安裝（本機尚無 clone）
|
||
git clone <url> <clone-dir>/<name>
|
||
agy plugin install <clone-dir>/<name>
|
||
|
||
# 更新（已有 clone → git pull 後重裝，不重新 clone）
|
||
git -C <clone-dir>/<name> pull
|
||
agy plugin uninstall <plugin>
|
||
agy plugin install <clone-dir>/<name>
|
||
|
||
# 移除
|
||
agy plugin uninstall <plugin>
|
||
```
|
||
|
||
- `<clone-dir>` 沒有跨助理強制的唯一值：Windows 佔位符範例 `%USERPROFILE%\plugins`，Linux／macOS／WSL 佔位符範例 `$HOME/plugins`；引用端（README、`plugins-install` 等）可自訂自己的預設 clone 根目錄，但**一律用佔位符表示，不得寫死真實使用者帳號路徑**。
|
||
- 若把 skills 放到 GitHub，可直接 `agy plugin install https://github.com/<owner>/<repo>`，不需 clone。
|
||
- 其他常用子指令：`agy plugin list`、`agy plugin enable <plugin>` / `disable <plugin>`、`agy plugin validate <path>`。安裝或更新後需重啟工作階段。
|
||
- 呼叫：`/jsc-<name>:<skill>` 或依描述自動觸發。
|
||
|
||
## OpenCode
|
||
|
||
> OpenCode 沒有原生 plugin 匯入／移除指令，但可使用 skill：改用「clone 到本機固定目錄 → 複製 `skills/` 到工具 skills 目錄」的目錄安裝法。OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、`~/.agents/skills/`）。
|
||
|
||
```bash
|
||
# 安裝
|
||
git clone <url> <clone-dir>/<name>
|
||
mkdir -p ~/.config/opencode/skills
|
||
cp -r <clone-dir>/<name>/skills/* ~/.config/opencode/skills/
|
||
|
||
# 更新（git pull 後重新複製，不重新 clone）
|
||
git -C <clone-dir>/<name> pull
|
||
cp -r <clone-dir>/<name>/skills/* ~/.config/opencode/skills/
|
||
|
||
# 移除：從 clone 目錄的 skills/ 即時推導清單逐一刪除，不要手抄寫死的 skill 名單（plugin 新增 skill 後手抄清單會漏）
|
||
for s in <clone-dir>/<name>/skills/*/; do rm -rf "$HOME/.config/opencode/skills/$(basename "$s")"; done
|
||
```
|
||
|
||
- `cp -r` 是合併不是覆蓋：上游已刪除的 skill 目錄會在本機殘留，要乾淨更新請先用上面的移除迴圈清掉舊目錄再複製一次。
|
||
- **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`、`<clone-dir>` 佔位符範例 `%USERPROFILE%\plugins`。
|
||
- 呼叫：直接描述需求，模型會依 skill 描述自動透過 skill 工具呼叫。
|
||
|
||
## GitHub Copilot CLI
|
||
|
||
```bash
|
||
# 安裝
|
||
copilot plugin marketplace add <url>
|
||
copilot plugin install <token>
|
||
|
||
# 更新
|
||
copilot plugin marketplace update <marketplace>
|
||
copilot plugin update <token>
|
||
|
||
# 移除
|
||
copilot plugin uninstall <token>
|
||
copilot plugin marketplace remove <marketplace>
|
||
```
|
||
|
||
- 安裝 token `<token>` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。
|
||
- `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑；Gitea repo 用上方 HTTPS URL。
|
||
- 呼叫：自然語言或 plugin skills，例如 `copilot -i "請使用 <skill> 說明其內容"`。
|
||
|
||
---
|
||
|
||
## 各助理速查
|
||
|
||
| 助理 | 安裝 | 更新 | 移除 |
|
||
| --- | --- | --- | --- |
|
||
| Claude Code | `marketplace add` + `install` | `marketplace update` + `update` | `uninstall` + `marketplace remove` |
|
||
| Codex | `marketplace add` + `add` | `marketplace upgrade` | `remove` + `marketplace remove` |
|
||
| Antigravity | `git clone` + `install` | `git pull` + `uninstall`→`install` | `uninstall` |
|
||
| OpenCode | `git clone` + `cp -r skills/*` | `git pull` + `cp -r skills/*` | 依 clone 的 `skills/` 逐一 `rm -rf` |
|
||
| GitHub Copilot CLI | `marketplace add` + `install` | `marketplace update` + `update` | `uninstall` + `marketplace remove` |
|
||
|
||
## 給樣板產生器的備註
|
||
|
||
- 四份 README 的「安裝 / 更新 / 移除（各助理）」章節，之後應改為引用本規範並只代換 `<host>`／`<name>`／`<plugin>`／`<marketplace>`／`<token>`／`<url>`，不再各自重複完整指令區塊；`shared/skills/plugins-install/SKILL.md`、`plugins-uninstall/SKILL.md` 亦同。
|
||
- `plugins-install`／`plugins-uninstall` 的階段 C 已採用與本規範一致的「持久 clone + `git pull`」寫法，可視為本規範的既有實作範例；`shared/README.md` 目前的 Antigravity／OpenCode 段落改用「每次重新 clone 到暫存目錄」的寫法，與本規範及 `doc`／`code` README 不一致，樣板產生時請一併改為本規範版本。
|
||
- 本機開發本地路徑一律使用 `%USERPROFILE%\...`／`$HOME/...` 佔位符，不得出現真實使用者帳號名稱路徑。
|