plugins/shared
2
0
Fork 0
Code Pull Requests Activity

feat(shared): 新增14個共用spec、models/todo工具與樣板產生器，收斂跨repo重複規範

Browse Source 
依 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>
This commit is contained in:
jiantw83
2026-08-11 06:02:30 +00:00
co-authored by Claude Sonnet 5
parent d49ae1085d
commit 1030f9d403
38 changed files with 2329 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+37 -117
View File
@@ -50,123 +50,18 @@ shared/
## 安裝 / 更新 / 移除（各助理）
> 指令中的 repo 網址換成你的：`https://gitea.jsc.idv.tw/plugins/shared.git`
> 本 repo 的安裝／更新／移除流程一律以 Gitea 遠端檔案為準，不依賴既有本機存取庫。
>
> **Claude / Codex 從 git URL 安裝（會 clone 遠端），請先把本 repo `push` 到 gitea。**
> **Antigravity 的 `agy plugin install <url>` 目前只支援 github.com**；gitea 請依本節改用「從遠端重新抓取到暫存目錄，再用本地路徑安裝」。
> 本 repo 的安裝／更新／移除流程一律以 Gitea 遠端檔案與下方 README 章節為準，不依賴既有本機存取庫。
### Claude Code
```bash
# 安裝
claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/shared.git
claude plugin install jsc-shared@shared
# 更新
claude plugin marketplace update shared
claude plugin update jsc-shared@shared
# 移除
claude plugin uninstall jsc-shared@shared
claude plugin marketplace remove shared
```
- 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。
- 本機開發（免 push）仍可用本地路徑，但正式安裝請以 Gitea 遠端 README 為準。
- **呼叫**：`/jsc-shared:<name>`（例 `/jsc-shared:spec-output`）。
### Codex
```bash
# 安裝
codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/shared.git
codex plugin add jsc-shared@shared
# 更新（重新抓取 marketplace 的 git 快照）
codex plugin marketplace upgrade shared
# 移除
codex plugin remove jsc-shared@shared
codex plugin marketplace remove shared
```
- 安裝 token `jsc-shared@shared` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。
- 本 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。
- **呼叫**：`$<name>`（例 `$spec-output`），或用 `/skills` 選單。
### Antigravity（`agy`）
> `agy plugin install <url>` 目前**只支援 github.com**；gitea 等自架 git 不支援 URL 安裝，請先從遠端抓到暫存目錄，再用**本地路徑**安裝。
```bash
# 安裝：先從遠端抓到暫存目錄，再用本地路徑
git clone --depth 1 https://gitea.jsc.idv.tw/plugins/shared.git /tmp/jsc-shared
agy plugin install /tmp/jsc-shared
# 更新（重新抓取遠端後重裝）
git clone --depth 1 https://gitea.jsc.idv.tw/plugins/shared.git /tmp/jsc-shared
agy plugin uninstall jsc-shared
agy plugin install /tmp/jsc-shared
# 移除
agy plugin uninstall jsc-shared
```
- 若把 skills 放到 GitHub，則可直接 `agy plugin install https://github.com/<owner>/<repo>`。
- 不讀取既有本機 repo；若需要對照 README，只用遠端 checkout 的暫存工作區。
- 其他：`agy plugin list`、`agy plugin enable jsc-shared` / `disable jsc-shared`、`agy plugin validate <path>`。安裝後重啟工作階段。
- **呼叫**：`/jsc-shared:<name>`（例 `/jsc-shared:spec-output`）或依描述自動觸發。
### 無 plugin 指令但可使用 skill 的助理
以 OpenCode 為例，這類工具不走原生 plugin install / uninstall，而是：
1. 先把整組 skill clone 到工具的專屬資料夾。
2. 再依技能組自己的 `README.md`，把技能匯入到 README 指定的位置。
3. 移除時則反向刪除 README 指定的那些 skill 目錄。
OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、`~/.agents/skills/`），因此可把技能匯入這些位置。
```bash
# 安裝
git clone --depth 1 https://gitea.jsc.idv.tw/plugins/shared.git /tmp/jsc-shared
mkdir -p ~/.config/opencode/skills
cp -r /tmp/jsc-shared/skills/* ~/.config/opencode/skills/
# 更新
git clone --depth 1 https://gitea.jsc.idv.tw/plugins/shared.git /tmp/jsc-shared
cp -r /tmp/jsc-shared/skills/* ~/.config/opencode/skills/
# 移除（逐一移除本 plugin 帶入的 skill 目錄；勿只清 spec-*，否則其他 skill 會殘留）
for s in /tmp/jsc-shared/skills/*/; do rm -rf "$HOME/.config/opencode/skills/$(basename "$s")"; done
```
> **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
- **呼叫**：直接描述需求，模型會依 skill 描述自動透過 skill 工具呼叫。
### GitHub Copilot CLI
Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令，可直接從 marketplace 安裝、更新與移除本 plugin。
```bash
# 安裝
copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/shared.git
copilot plugin install jsc-shared@shared
# 更新
copilot plugin marketplace update shared
copilot plugin update jsc-shared@shared
# 移除
copilot plugin uninstall jsc-shared@shared
copilot plugin marketplace remove shared
```
- 安裝 token `jsc-shared@shared` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。
- `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑；Gitea repo 可用上方 HTTPS URL。
- **呼叫**：在 Copilot CLI 中用自然語言描述需求，例如 `copilot -i "請使用 spec-output 說明輸出規範"`。
> 完整的安裝／更新／移除指令（Claude Code、Codex、Antigravity、OpenCode、GitHub Copilot CLI 五種助理），一律以 [`/jsc-shared:spec-plugin-cli`](https://gitea.jsc.idv.tw/plugins/shared/src/branch/master/skills/spec-plugin-cli/SKILL.md) 為唯一權威版本，套用時代入下列佔位符：
>
> | 佔位符 | 值 |
> | --- | --- |
> | `<host>` | `gitea.jsc.idv.tw` |
> | `<name>` | `shared` |
> | `<plugin>` | `jsc-shared` |
> | `<marketplace>` | `shared` |
> | `<token>`（= `<plugin>@<marketplace>`） | `jsc-shared@shared` |
> | `<url>` | `https://gitea.jsc.idv.tw/plugins/shared.git` |
---
@@ -198,7 +93,7 @@ copilot plugin marketplace remove shared
### 共用規範（spec-*）
以下 skills 是 **code／doc plugins 各 skill 引用的共用規範**：其他 skill 內文以 `/jsc-shared:spec-<name>` 引用時載入；也可單獨呼叫查看規範內容。
以下 skills 是 **code／doc／persona plugins 各 skill 引用的共用規範**：其他 skill 內文以 `/jsc-shared:spec-<name>` 引用時載入；也可單獨呼叫查看規範內容。
| Skill | 類型 | 內容 |
| --- | --- | --- |
@@ -212,6 +107,30 @@ copilot plugin marketplace remove shared
| `spec-project-board` | Gitea 看板 | 進度欄位語意對應、建議欄位規則、GET 探測（404/501 不支援）、不往回移、不得新建欄位 |
| `spec-doc-funcs-handoff` | 文件化串接 | code 類 skill 完成後完整執行 /jsc-doc:funcs 的標準流程與統一時間戳 |
| `spec-plugin-version` | 版號規則 | 三 manifest 同步 bump、以 master 為基準計算同一 PR 的最終版本、新 plugin 首發 0.0.1、patch 到 9 後進位 minor、chore(plugin 版本) commit |
| `spec-preflight` | 前置載入 | 每個 skill 執行前先載入本規範自身再依序載入其他 spec、任一載入不到即詢問是否安裝 shared、拒絕就中斷、絕不憑摘要繼續 |
| `spec-conventional-commit` | Commit 分類 | `git status --porcelain=v1 -uall` 完整盤點、9 種 commit 類型對照、`type(範圍)：一句總結` 格式、逐組精準 `git add` 分類提交 |
| `spec-pull-request` | PR 建立 | 目標分支不得臆測、解析 origin 座標決定 owner/repo、full／simple 兩種描述模式、body 以 UTF-8 檔帶入、已有相同 head→base 開啟中 PR 就沿用 |
| `spec-git-push` | Push 憑證 | credential helper → token（遮蔽、用完即棄）→ 詢問使用者三段式，與 `spec-gitea` 的 token 解析優先序用途不同、不可互相取代 |
| `spec-issue-read` | 議題讀取 | 必須含描述、所有留言與所有附件、分頁完整讀取、彙整需求不得臆測缺漏部分，須詢問使用者或標記「未提及」 |
| `spec-todo-list` | TODO 清單 | Markdown checklist 格式、每項具體可驗收、依影響範圍由小到大排序、對應 `path:line` 或議題描述、完成一項就勾選並回報 |
| `spec-ask-user` | 詢問使用者 | 單選／多選時機判斷、選項上限 4（超過改列文字）、每組含「其他」自訂輸入、已知答案跳過詢問、絕不要求貼 token／密碼 |
| `spec-subagent` | Subagent 派工 | 一個明確目標派一個 subagent、subagent 只讀不寫、回傳結構化結果、派工提示帶入 `spec-output`、不得改動原始碼或直接寫外部系統 |
| `spec-no-scratch-files` | 不落地 | 全程不建立任何草稿檔／暫存檔、中間成果留在對話或議題內容，唯一例外是議題附件唯讀暫存下載、讀完即刪 |
| `spec-skill-invocation` | 呼叫方式 | 各助理呼叫一個 skill 的統一表格：Claude Code／Antigravity 斜線指令、Codex `$name`、OpenCode 依 description 自動觸發 |
| `spec-script-path` | 腳本路徑 | plugin 內腳本絕不可用相對路徑：Claude Code 用 `${CLAUDE_PLUGIN_ROOT}`、其他助理由載入時的 base directory 往上兩層推導 |
| `spec-action-scaffold` | Action 骨架 | 目錄無 action manifest 時判斷 action 根目錄並觸發問答式從零建立，固定三題骨架（名稱／用途、輸入輸出、執行目標） |
| `spec-node-src-layout` | Node src 收攏 | 主程式入口及其依賴鏈的 `.js`／`.mjs`／`.cjs` 收進 `src/`、排除設定檔與 test 目錄、搬移後同步更新所有引用路徑 |
| `spec-plugin-cli` | Plugin CLI 指令 | 五種助理（Claude Code／Codex／Antigravity／OpenCode／Copilot CLI）的 install／update／uninstall 完整指令語法與佔位符，唯一權威版本 |
| `spec-model` | 模型標籤與檢查 | 固定標籤體系（能力等級／成本／延遲／上下文／用途／可用性）、任務→必要標籤對映表、取得模型清單的權威來源優先序、`~/.claude/jsc/models.json` 快取設計（30 天過期）、強制切換規則、讀到帶 `model:` frontmatter 清單檔時的模型檢查義務 |
### 規範相關工具
以下 skills 不是 `spec-*` 規範本身，而是**依規範實際做事的可執行工具**：
| Skill | 用途 | 使用方法 |
| --- | --- | --- |
| `models` | 查詢目前可用哪些模型並依 `spec-model` 的標籤體系標註，維護 `~/.claude/jsc/models.json` 快取，依任務類型推薦模型或檢查當前模型是否符合指定模型。是 `spec-model` 的唯一可執行入口——其他 skill 需要模型清單或推薦時一律呼叫本 skill，不自行重寫探測或推薦邏輯 | `/jsc-shared:models`；可帶 `--refresh`（重跑探測與 smoke test）、`--task <analysis\|implement\|review\|summary\|persona>`（依對映表推薦模型）、`--check <model>`（比對指定模型與當前模型）、`--json` |
| `todo` | 把「需求 → 分析 → 產生 `todo.md` → 交給指定模型實作」固定成可重複執行的流程：先依 `spec-model` 的「需求分析」任務挑分析模型（不符就先停下要求切換）、讀取來源（需求描述、本機檔案或 Gitea 議題）釐清需求、再挑一個實作模型，最後產生帶 `model`／`model_alias`／`model_reason` 等 frontmatter 的 `todo.md`，供另開一個以該模型執行的 session 落地實作 | `/jsc-shared:todo`；可帶 `--source <需求描述\|檔案路徑\|議題編號>`、`--file <path>`、`--impl-model <id\|alias>`、`--append\|--overwrite`、`--yes` |
### 整組 plugin 安裝管理
@@ -259,3 +178,4 @@ copilot plugin marketplace remove shared
- Copilot：`copilot plugin marketplace update shared && copilot plugin update jsc-shared@shared`
> 本 repo 只放純 `SKILL.md` 內容，不含可執行腳本或 hook。