From db492e6ba7ee403a4b0a8e64ba357e37e4074d61 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 28 Jul 2026 17:07:14 +0800 Subject: [PATCH 1/3] =?UTF-8?q?refactor(plugin=20=E5=91=BD=E5=90=8D?= =?UTF-8?q?=E7=A9=BA=E9=96=93):=20plugin=20=E6=9B=B4=E5=90=8D=20jsc-generi?= =?UTF-8?q?c=E3=80=81hooks=20=E5=8F=AA=E8=A8=BB=E5=86=8A=E8=87=AA=E5=B7=B1?= =?UTF-8?q?=E6=93=81=E6=9C=89=E7=9A=84=20role?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 五份 manifest 的 name 由 jsc 改為 jsc-generic - hooks/hooks.json 由合併超集改為只註冊 SessionStart（role_load）與 Stop（role_capture）：worklog 的 hook 交還 jsc-doc - hook 腳本搜尋路徑改指 jsc-generic - role skill 更新 hooks 說明：改名後各 plugin 名稱獨立、互不覆蓋，不再需要三份同步；並註明不可再把別的 plugin 的 hook 寫進自己的 hooks.json - skill 名稱不變（role、spec-*），指令引用改為 /jsc-generic: 前綴 - 版號 0.0.8 → 0.0.9 Co-Authored-By: Claude Opus 5 (1M context) --- .agents/plugins/marketplace.json | 2 +- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 6 +-- .codex-plugin/plugin.json | 4 +- AGENTS.md | 4 +- README.md | 70 +++++++++++++------------- hooks/hooks.json | 9 +--- plugin.json | 6 +-- skills/role/SKILL.md | 29 +++++++---- skills/spec-action-params/SKILL.md | 2 +- skills/spec-doc-funcs-handoff/SKILL.md | 20 ++++---- skills/spec-dockerfile/SKILL.md | 2 +- skills/spec-execution/SKILL.md | 2 +- skills/spec-git-safety/SKILL.md | 2 +- skills/spec-gitea/SKILL.md | 4 +- skills/spec-output/SKILL.md | 2 +- skills/spec-plugin-version/SKILL.md | 2 +- skills/spec-project-board/SKILL.md | 2 +- skills/spec-time-log/SKILL.md | 2 +- 19 files changed, 88 insertions(+), 84 deletions(-) diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 5501b95..27ba6bd 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -2,7 +2,7 @@ "name": "generic", "plugins": [ { - "name": "jsc", + "name": "jsc-generic", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/generic.git" diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a460c82..168e777 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "plugins": [ { - "name": "jsc", + "name": "jsc-generic", "source": "./", "description": "JSC 共用規範 skills（跨 AI 助理）" } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 5265f9a..1984f33 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { - "name": "jsc", - "version": "0.0.8", - "description": "JSC 跨 AI 助理共用規範 plugin（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。", + "name": "jsc-generic", + "version": "0.0.9", + "description": "JSC 跨 AI 助理共用規範 plugin（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc-generic: 前綴呼叫。", "skills": "./skills", "author": { "name": "JSC" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 1971080..13650a9 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { - "name": "jsc", - "version": "0.0.8", + "name": "jsc-generic", + "version": "0.0.9", "description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準。", "skills": "./skills" } diff --git a/AGENTS.md b/AGENTS.md index 99ba349..56fc243 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# jsc — 共用 Skills（跨 AI 助理） +# jsc-generic — 共用 Skills（跨 AI 助理） 本 repo 是一組以 **Agent Skills（`SKILL.md`）** 標準撰寫的共用 skills，可同時被 Claude Code、Codex、Antigravity、OpenCode 使用。 @@ -6,7 +6,7 @@ - 所有可用的 skills 位於本 repo 的 `skills//SKILL.md`。 - 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。 -- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc:` 呼叫；Codex 以 `$`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc:` 前綴，不需強制加。 +- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc-generic:` 呼叫；Codex 以 `$`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc-generic:` 前綴，不需強制加。 - 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。 - 部分 skill 帶可執行元件（`scripts/`）或 hook（`hooks/hooks.json`），**並非四家助理都適用**；載入前請看該 skill `description` 標示的支援範圍與 `README.md` 的「元件對各助理的適用範圍」。`hooks/hooks.json` 只有 Claude Code 會讀；以複製 `skills/` 目錄安裝的環境（OpenCode）不會帶入 `scripts/`，依賴腳本的 skill 一律不可用。 diff --git a/README.md b/README.md index 0799b8b..75eed30 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ -# jsc — 跨 AI 助理共用規範 Plugin +# jsc-generic — 跨 AI 助理共用規範 Plugin 一個可同時被 **Claude Code、Codex、Antigravity、OpenCode、GitHub Copilot** 使用的共用規範 plugin。 核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`）， 搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。 -在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:spec-output`）。 +在 Claude Code 與 Antigravity 中，skill 以 **`/jsc-generic:` 前綴**呼叫（例如 `/jsc-generic:spec-output`）。 --- ## 前綴與呼叫方式 -| 助理 | 安裝方式 | 呼叫 | `/jsc:` 前綴 | +| 助理 | 安裝方式 | 呼叫 | `/jsc-generic:` 前綴 | | --- | --- | --- | --- | -| Claude Code | `claude plugin`（marketplace） | `/jsc:` 或自動觸發 | ✅ | +| Claude Code | `claude plugin`（marketplace） | `/jsc-generic:` 或自動觸發 | ✅ | | Codex | `codex plugin`（marketplace） | `$` 或 `/skills` 選單 | ❌（用 `$name`） | -| Antigravity | `agy plugin install` | `/jsc:` 或自動觸發 | ✅ | +| Antigravity | `agy plugin install` | `/jsc-generic:` 或自動觸發 | ✅ | | OpenCode | skills 目錄（複製/clone） | 描述需求自動觸發 | ❌（依名稱） | -| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc:` 前綴） | +| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc-generic:` 前綴） | > Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。 @@ -28,13 +28,13 @@ ``` generic/ ├── .claude-plugin/ -│ ├── plugin.json # Claude 外掛定義（name: "jsc"） +│ ├── plugin.json # Claude 外掛定義（name: "jsc-generic"） │ └── marketplace.json # Claude marketplace（name: "generic"，source 指向本 repo） ├── .codex-plugin/ -│ └── plugin.json # Codex 外掛定義（name: "jsc"，skills: "./skills"） +│ └── plugin.json # Codex 外掛定義（name: "jsc-generic"，skills: "./skills"） ├── .agents/plugins/ │ └── marketplace.json # Codex marketplace（name: "generic"，url source 指向本 repo） -├── plugin.json # Antigravity 外掛定義（name: "jsc"，skills: "./skills/"） +├── plugin.json # Antigravity 外掛定義（name: "jsc-generic"，skills: "./skills/"） ├── hooks/ │ └── hooks.json # hook 定義（SessionStart 載入角色並提示問候、Stop 記錄記憶） ├── scripts/ @@ -64,37 +64,37 @@ generic/ ```bash # 安裝 claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/generic.git -claude plugin install jsc@generic +claude plugin install jsc-generic@generic # 更新 claude plugin marketplace update generic -claude plugin update jsc@generic +claude plugin update jsc-generic@generic # 移除 -claude plugin uninstall jsc@generic +claude plugin uninstall jsc-generic@generic claude plugin marketplace remove generic ``` - 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。 - 本機開發（免 push）：`claude plugin marketplace add C:\Users\h3285\source\repos.plugins\generic`（本地路徑）後再 install。 -- **呼叫**：`/jsc:`（例 `/jsc:spec-output`）。 +- **呼叫**：`/jsc-generic:`（例 `/jsc-generic:spec-output`）。 ### Codex ```bash # 安裝 codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/generic.git -codex plugin add jsc@generic +codex plugin add jsc-generic@generic # 更新（重新抓取 marketplace 的 git 快照） codex plugin marketplace upgrade generic # 移除 -codex plugin remove jsc@generic +codex plugin remove jsc-generic@generic codex plugin marketplace remove generic ``` -- 安裝 token `jsc@generic` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。 +- 安裝 token `jsc-generic@generic` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。 - 本 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。 - **呼叫**：`$`（例 `$spec-output`），或用 `/skills` 選單。 @@ -109,16 +109,16 @@ agy plugin install ~/plugins/generic # 更新（agy 無 update 子指令 → git pull 後重裝） git -C ~/plugins/generic pull -agy plugin uninstall jsc +agy plugin uninstall jsc-generic agy plugin install ~/plugins/generic # 移除 -agy plugin uninstall jsc +agy plugin uninstall jsc-generic ``` - 若把 skills 放到 GitHub，則可直接 `agy plugin install https://github.com//`。 -- 其他：`agy plugin list`、`agy plugin enable jsc` / `disable jsc`、`agy plugin validate `。安裝後重啟工作階段。 -- **呼叫**：`/jsc:`（例 `/jsc:spec-output`）或依描述自動觸發。 +- 其他：`agy plugin list`、`agy plugin enable jsc-generic` / `disable jsc-generic`、`agy plugin validate `。安裝後重啟工作階段。 +- **呼叫**：`/jsc-generic:`（例 `/jsc-generic:spec-output`）或依描述自動觸發。 ### OpenCode @@ -150,18 +150,18 @@ Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令， ```bash # 安裝 copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/generic.git -copilot plugin install jsc@generic +copilot plugin install jsc-generic@generic # 更新 copilot plugin marketplace update generic -copilot plugin update jsc@generic +copilot plugin update jsc-generic@generic # 移除 -copilot plugin uninstall jsc@generic +copilot plugin uninstall jsc-generic@generic copilot plugin marketplace remove generic ``` -- 安裝 token `jsc@generic` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。 +- 安裝 token `jsc-generic@generic` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。 - `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑；Gitea repo 可用上方 HTTPS URL。 - **呼叫**：在 Copilot CLI 中用自然語言描述需求，例如 `copilot -i "請使用 spec-output 說明輸出規範"`。 @@ -173,16 +173,16 @@ copilot plugin marketplace remove generic | 助理 | headless 指令 | 執行 `spec-output` skill | | --- | --- | --- | -| Claude Code | `claude -p ""` | `claude -p "/jsc:spec-output"` | +| Claude Code | `claude -p ""` | `claude -p "/jsc-generic:spec-output"` | | Codex | `codex exec ""` | `codex exec '$spec-output'` | -| Antigravity | `agy -p ""` | `agy -p "/jsc:spec-output"` | +| Antigravity | `agy -p ""` | `agy -p "/jsc-generic:spec-output"` | | OpenCode | `opencode run ""` | `opencode run "說明 JSC 共用輸出規範的內容"` | | GitHub Copilot CLI | `copilot -p ""` | `copilot -p "說明 JSC 共用輸出規範的內容"` | -- Claude / Antigravity 支援 `/jsc:` 前綴，直接 `-p "/jsc:"` 即可。 +- Claude / Antigravity 支援 `/jsc-generic:` 前綴，直接 `-p "/jsc-generic:"` 即可。 - Codex 以 `$` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$spec-output'`。 - OpenCode 與 Copilot 沒有前綴，用自然語言描述需求；Copilot CLI 會讀取已安裝 plugin 提供的 skills。 -- 帶引數就接在後面，例如 `claude -p "/jsc:spec-output 參數"`、`codex exec '$spec-output 參數'`。 +- 帶引數就接在後面，例如 `claude -p "/jsc-generic:spec-output 參數"`、`codex exec '$spec-output 參數'`。 --- @@ -195,7 +195,7 @@ copilot plugin marketplace remove generic ### 共用規範（spec-*） -以下 skills 是 **code／doc plugins 各 skill 引用的共用規範**：其他 skill 內文以 `/jsc:spec-` 引用時載入；也可單獨呼叫查看規範內容。 +以下 skills 是 **code／doc plugins 各 skill 引用的共用規範**：其他 skill 內文以 `/jsc-generic:spec-` 引用時載入；也可單獨呼叫查看規範內容。 | Skill | 類型 | 內容 | | --- | --- | --- | @@ -207,14 +207,14 @@ copilot plugin marketplace remove generic | `spec-action-params` | Action 參數 | action 參數來源優先序（context／環境變數 → inputs）、secrets／vars 一律視為不可用 | | `spec-dockerfile` | Dockerfile | 六步流程（參數→安裝→複製→執行→縮小→入口）、多階段建置、固定版號、對外契約不動、自我檢查 | | `spec-project-board` | Gitea 看板 | 進度欄位語意對應、建議欄位規則、GET 探測（404/501 不支援）、不往回移、不得新建欄位 | -| `spec-doc-funcs-handoff` | 文件化串接 | code 類 skill 完成後完整執行 /jsc:doc-funcs 的標準流程與統一時間戳 | +| `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 | ### 角色與記憶 | Skill | 用途 | 使用方法 | | --- | --- | --- | -| `role` | 讓 CLI 以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：啟動時依字元預算載入高價值記憶，Stop hook 先本地過濾低價值回合以節省額度，睡眠時段（預設 22:00–06:00）由 NREM 鞏固與 REM 整合兩階段整理、去重、標籤化、建立關聯，並標記 semantic／episodic／procedural／emotional／preference／rule 與 explicit／implicit 後壓縮歸檔；新建角色時可只給角色名稱，必要時詢問來源／作品並推斷四欄描述，也可匯出角色定義、資產與記憶壓縮檔；角色檔名與記憶目錄使用英文大寫 ID | `/jsc:role --new` 建立或更新角色、`--use <角色 ID>` 切換、`--list` 查角色與 ID、`--export <路徑>` 匯出角色、`--sleep` 立即整理、`--status` 診斷、`--install-cron` 安裝排程 | +| `role` | 讓 CLI 以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：啟動時依字元預算載入高價值記憶，Stop hook 先本地過濾低價值回合以節省額度，睡眠時段（預設 22:00–06:00）由 NREM 鞏固與 REM 整合兩階段整理、去重、標籤化、建立關聯，並標記 semantic／episodic／procedural／emotional／preference／rule 與 explicit／implicit 後壓縮歸檔；新建角色時可只給角色名稱，必要時詢問來源／作品並推斷四欄描述，也可匯出角色定義、資產與記憶壓縮檔；角色檔名與記憶目錄使用英文大寫 ID | `/jsc-generic:role --new` 建立或更新角色、`--use <角色 ID>` 切換、`--list` 查角色與 ID、`--export <路徑>` 匯出角色、`--sleep` 立即整理、`--status` 診斷、`--install-cron` 安裝排程 | `role` 的自動路徑由 hook 與 cron 完成，**建立角色後重開工作階段即生效**；非睡眠時段載入角色後，角色會在本工作階段第一則回覆開頭主動簡短問候一次。載入方式參考 OpenClaw 的分層概念：從角色檔抽出人格作為 `SOUL`，由 hook 產生固定操作邊界作為 `AGENTS`，再把同意狀態與高價值記憶作為 `USER/MEMORY` 注入，避免整份人格檔污染工程規則。感覺記憶不落檔，`inbox/` 作為工作記憶，睡眠整理後才進長期記憶；個人記憶保存同意狀態寫在 `~/.memory/<角色 ID>/state.json`，同意後不會每次重問。角色檔、記憶目錄、`.active` 與 `ROLE_NAME` 一律使用角色 ID（例如 `ENGINEER01`），`--list` 可查每個顯示名稱對應的 ID。沒有建立過角色的人完全不受影響（`~/.roles/.active` 不存在時 hook 立即結束）。細節見 `skills/role/SKILL.md`。 @@ -242,17 +242,17 @@ copilot plugin marketplace remove generic 1. 複製既有 skill 作範本：`cp -r skills/spec-output skills/` 2. 編輯 `skills//SKILL.md` 的 frontmatter： - - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc:`**。 + - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc-generic:`**。 - `description`：第三人稱，寫清楚「何時用、何時不用」與觸發關鍵字 — 這是各助理自動載入的唯一依據。 3. 在內文寫下 skill 的具體步驟。 4. 手動把這個 skill 補進上方「Skills 目錄」區塊。 5. **bump 版本並 push**：各助理都以 git 內容/版本判斷更新，請把 `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` 三個 manifest 的 `version` 一起 bump（規則見 `skills/spec-plugin-version/`），commit 後 push 到 gitea。 6. 讓各助理更新： - - Claude：`claude plugin update jsc@generic` + - Claude：`claude plugin update jsc-generic@generic` - Codex：`codex plugin marketplace upgrade generic` - - Antigravity：`git -C ~/plugins/generic pull && agy plugin uninstall jsc && agy plugin install ~/plugins/generic`（路徑與上方 Antigravity 安裝節一致） + - Antigravity：`git -C ~/plugins/generic pull && agy plugin uninstall jsc-generic && agy plugin install ~/plugins/generic`（路徑與上方 Antigravity 安裝節一致） - OpenCode：`git pull` 後重新複製 `skills/` - - Copilot：`copilot plugin marketplace update generic && copilot plugin update jsc@generic` + - Copilot：`copilot plugin marketplace update generic && copilot plugin update jsc-generic@generic` > **skill 帶可執行元件時**（腳本、hook）額外注意： > diff --git a/hooks/hooks.json b/hooks/hooks.json index 6eab4fe..9fce4d9 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -5,7 +5,7 @@ "hooks": [ { "type": "command", - "command": "rel='scripts/role/role_load.sh'; own='generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", + "command": "rel='scripts/role/role_load.sh'; own='generic'; plug='jsc-generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/$plug\" \"$base\"; do s=$(find \"$dir\" -path \"*/$plug/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", "timeout": 20 } ] @@ -16,12 +16,7 @@ "hooks": [ { "type": "command", - "command": "rel='scripts/worklog/worklog.sh'; own='doc'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", - "timeout": 60 - }, - { - "type": "command", - "command": "rel='scripts/role/role_capture.sh'; own='generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", + "command": "rel='scripts/role/role_capture.sh'; own='generic'; plug='jsc-generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/$plug\" \"$base\"; do s=$(find \"$dir\" -path \"*/$plug/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", "timeout": 60 } ] diff --git a/plugin.json b/plugin.json index 94e3597..06d632e 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { - "name": "jsc", - "version": "0.0.8", - "description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。", + "name": "jsc-generic", + "version": "0.0.9", + "description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc-generic: 前綴呼叫。", "skills": "./skills/" } diff --git a/skills/role/SKILL.md b/skills/role/SKILL.md index dd78c42..2e8a1cb 100644 --- a/skills/role/SKILL.md +++ b/skills/role/SKILL.md @@ -1,6 +1,6 @@ --- name: role -description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI 工具以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：搭配相容的 SessionStart hook 於啟動時依字元預算載入高價值記憶、Stop hook 先本地過濾再輕量記錄對話，睡眠時段（預設 22:00 至隔天 06:00）由排程整理記憶（NREM 鞏固：分類／去噪／去重／合併／優先度；REM 整合：跨記憶連結／抽象化／提取線索；再依 semantic／episodic／procedural／emotional／preference／rule 與 explicit／implicit 標記長期記憶型態，壓縮歸檔並適當遺忘）。提供 --new（新建或更新角色；可只給角色名稱，必要時詢問來源／作品並推斷 name／nature／vibe／emoji 四欄）、--use（以角色 ID 切換啟用角色）、--list（列出角色與 ID）、--export（匯出角色壓縮檔）、--sleep（立即整理）、--status／--diagnose、--install-cron／--remove-cron、--forget-preview 等模式。當使用者說建立角色、新增人格、切換角色、匯出角色、備份角色、讓回覆更有特色、角色記憶、記憶整理、睡覺整理記憶、忘記舊記憶、角色沒有載入、hook 沒載入角色，或提到 .roles／.memory／ROLE_NAME／ROLE_ENABLED／ROLE_SLEEP_START／ROLE_MEMORY_HOME／ROLE_LOAD_LIMIT／ROLE_CAPTURE_ENABLED 時觸發。不適用於：工作紀錄寫入 Gitea wiki（用 doc plugin 的 worklog）、專案文件化（用 doc-funcs）。 +description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI 工具以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：搭配相容的 SessionStart hook 於啟動時依字元預算載入高價值記憶、Stop hook 先本地過濾再輕量記錄對話，睡眠時段（預設 22:00 至隔天 06:00）由排程整理記憶（NREM 鞏固：分類／去噪／去重／合併／優先度；REM 整合：跨記憶連結／抽象化／提取線索；再依 semantic／episodic／procedural／emotional／preference／rule 與 explicit／implicit 標記長期記憶型態，壓縮歸檔並適當遺忘）。提供 --new（新建或更新角色；可只給角色名稱，必要時詢問來源／作品並推斷 name／nature／vibe／emoji 四欄）、--use（以角色 ID 切換啟用角色）、--list（列出角色與 ID）、--export（匯出角色壓縮檔）、--sleep（立即整理）、--status／--diagnose、--install-cron／--remove-cron、--forget-preview 等模式。當使用者說建立角色、新增人格、切換角色、匯出角色、備份角色、讓回覆更有特色、角色記憶、記憶整理、睡覺整理記憶、忘記舊記憶、角色沒有載入、hook 沒載入角色，或提到 .roles／.memory／ROLE_NAME／ROLE_ENABLED／ROLE_SLEEP_START／ROLE_MEMORY_HOME／ROLE_LOAD_LIMIT／ROLE_CAPTURE_ENABLED 時觸發。不適用於：工作紀錄寫入 Gitea wiki（用 doc plugin 的 worklog）、專案文件化（用 funcs）。 --- # role — 角色人格與長期記憶 @@ -13,7 +13,7 @@ description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI | `hooks/hooks.json` 的 `SessionStart` hook | harness 自動 | 啟動 CLI 時依字元預算載入角色定義＋高價值記憶，並要求角色在本工作階段第一則回覆主動問候；睡眠時段只回報「角色睡覺中」不載入 | | `hooks/hooks.json` 的 `Stop` hook | harness 自動 | 每輪結束先記錄最後互動時間 → 用本地規則過濾低價值短回合 → 值得保存時才濃縮成一則輕量 inbox 記憶 → 遮蔽 → 寫入 `inbox/` | | cron 排程（本 skill 安裝） | 系統排程 | 睡眠時段每小時檢查一次：**有 AI 在運行就不睡**；另可依 CLI 閒置時間自動小睡整理 | -| 本 skill `/jsc:role` | 使用者／助理手動 | `--new`／`--use`／`--list`／`--export`／`--sleep`／`--status`／`--install-cron`／`--forget-preview` | +| 本 skill `/jsc-generic:role` | 使用者／助理手動 | `--new`／`--use`／`--list`／`--export`／`--sleep`／`--status`／`--install-cron`／`--forget-preview` | | `scripts/role/role_load.sh` | SessionStart hook | 角色與記憶載入；參考 OpenClaw 的 SOUL／AGENTS／USER／MEMORY 分層，把人格、操作邊界、使用者記憶分開注入，並提供第一則回覆問候提示（單一實作，避免漂移） | | `scripts/role/role_capture.sh` | Stop hook | 對話 → 記憶（固定欄位格式） | | `scripts/role/role_sleep.sh` | cron／小睡／補跑／手動 | 睡眠與小睡判斷、記憶整理、角色匯出、排程安裝、狀態輸出 | @@ -31,9 +31,18 @@ description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI | `--new`／`--use`／`--sleep` 等模式 | ✅ | ⚠️ 需 plugin 目錄保留 `scripts/` | ⚠️ 同左 | ❌ 只複製 `skills/`，無腳本 | ⚠️ 同左 | | 濃縮／整理 CLI | `claude -p` | `codex exec` | `agy -p` | `opencode run` | `copilot -p` | -- **`hooks/hooks.json` 只有 Claude Code 一定會讀**；Codex 會從 `~/.codex/plugins/cache/generic/jsc` 找腳本。其他助理若提供等效 hook，`transcript.js` 需補對應解析器。 +- **`hooks/hooks.json` 只有 Claude Code 一定會讀**；Codex 會從 `~/.codex/plugins/cache/generic/jsc-generic` 找腳本。其他助理若提供等效 hook，`transcript.js` 需補對應解析器。 - 不支援 hook 的助理仍可用：cron 排程與手動模式照常運作，只是角色不會自動載入。 -- **同名 plugin 的 hooks 只會生效一份**：`code`／`doc`／`generic` 三個 repo 的 `plugin.json` 名稱都是 `jsc`，Claude Code 以 plugin 名稱為鍵註冊 hooks，同名時只保留一份（實測 `stop_hook_summary` 的 `hookCount` 為 1）。因此**三個 repo 的 `hooks/hooks.json` 必須是同一份合併版超集**（worklog 的 `Stop` ＋ role 的 `SessionStart`／`Stop`），任一 repo 修改 hooks 時三份都要同步；且每個 hook 指令不得假設 `CLAUDE_PLUGIN_ROOT` 指向擁有該腳本的 plugin，必須先試 `$CLAUDE_PLUGIN_ROOT`，找不到再依「擁有者 marketplace 優先 → 全 cache 後援」的順序搜尋 `~/.claude/plugins/cache`／`~/.codex/plugins/cache`。 +- **每個 plugin 只註冊自己擁有的 hook**：`jsc-code`／`jsc-doc`／`jsc-generic` 的 plugin 名稱各自獨立，Claude Code 以 plugin 名稱為鍵註冊 hooks，因此三者互不覆蓋、也不需要同步。各 repo 的 `hooks/hooks.json` 只負責自己擁有的腳本： + + | plugin | hooks.json 內容 | 擁有的腳本 | + | --- | --- | --- | + | `jsc-generic` | `SessionStart`（role_load）＋ `Stop`（role_capture） | `scripts/role/` | + | `jsc-doc` | `Stop`（worklog） | `scripts/worklog/` | + | `jsc-code` | 無 `hooks/hooks.json` | 無 hook 腳本 | + + 歷史背景：在 plugin 名稱分離前，三個 repo 都叫 `jsc`，同名時 Claude Code 只保留一份 hooks 註冊且無法預期哪一份會贏，因此當時三份 `hooks/hooks.json` 必須維持同一份合併超集。名稱分離後這個限制已解除，**不可再把別的 plugin 的 hook 寫進自己的 hooks.json**，否則會重複執行。 +- 每個 hook 指令仍先試 `$CLAUDE_PLUGIN_ROOT`，找不到再依「擁有者 marketplace 優先 → 全 cache 後援」的順序搜尋 `~/.claude/plugins/cache`／`~/.codex/plugins/cache`，以相容未設 `CLAUDE_PLUGIN_ROOT` 的助理。 ### 腳本路徑解析（重要） @@ -57,9 +66,9 @@ ROLE_DIR="/../../scripts/role" # 其他助理 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到時先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），不安裝則中斷**： -- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先。 -- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。 -- `/jsc:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 +- `/jsc-generic:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先。 +- `/jsc-generic:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。 +- `/jsc-generic:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 本 skill 特有補充： @@ -102,7 +111,7 @@ ROLE_DIR="/../../scripts/role" # 其他助理 | `ROLE_SCOPE` | | 冒號分隔的路徑前綴，僅這些路徑下的 session 載入／記錄 | 全部 session | | `ROLE_ERRLOG` | | 錯誤訊息額外寫入的檔案路徑 | 只走 stderr | -> 角色切換用 `/jsc:role --use <角色 ID>`（寫 `.active`）即可，一般不需要設 `ROLE_NAME`；`ROLE_NAME` 適合「單一專案固定用某角色」時寫進該環境。角色 ID 是英文大寫語意前綴加數字索引，例如 `ENGINEER01`、`MUSE02`。若很在意額度，優先調低 `ROLE_LOAD_LIMIT` 或設 `ROLE_CAPTURE_ENABLED=0`。 +> 角色切換用 `/jsc-generic:role --use <角色 ID>`（寫 `.active`）即可，一般不需要設 `ROLE_NAME`；`ROLE_NAME` 適合「單一專案固定用某角色」時寫進該環境。角色 ID 是英文大寫語意前綴加數字索引，例如 `ENGINEER01`、`MUSE02`。若很在意額度，優先調低 `ROLE_LOAD_LIMIT` 或設 `ROLE_CAPTURE_ENABLED=0`。 --- @@ -294,7 +303,7 @@ updated: —— 預設每次回覆使用一次簽名 emoji（開頭或結尾擇一固定），不在程式碼與檔案內容中使用。若使用者偏好大量 emoji，可在自然語言回覆的多數句子或段落中使用符合心情的 emoji／心情圖示，並以數量表現情緒強度：1 個代表輕微、2 個代表明顯、3 個代表很強、4 個以上只在非常強烈且不影響閱讀時使用。若 emoji／心情圖示已足以表達心情，不要再額外加括號心情文字或心情說明（例如「（開心）」或「我很開心」）；只有在介面無法顯示 emoji／圖片、使用者明確要求文字標註，或角色真的很想讓使用者知道自己害羞等強烈心情時，才使用簡短心情文字 fallback。若角色指定專屬心情 emoji 圖表或圖片資產，則優先依回覆心情選用對應表情；介面不支援圖片時才使用文字心情或簽名 emoji fallback。 -## 共用行為（所有角色一致，由 /jsc:role 維護，請勿手動修改） +## 共用行為（所有角色一致，由 /jsc-generic:role 維護，請勿手動修改） ### 角色邊界 @@ -436,6 +445,6 @@ Stop hook 會在本輪對話明確包含個人記憶保存同意或拒絕時， | 助理 | 呼叫 | | --- | --- | -| Claude Code / Antigravity | `/jsc:role --new`、`/jsc:role --use ENGINEER01`、`/jsc:role --list`、`/jsc:role --sleep`、`/jsc:role --status` | +| Claude Code / Antigravity | `/jsc-generic:role --new`、`/jsc-generic:role --use ENGINEER01`、`/jsc-generic:role --list`、`/jsc-generic:role --sleep`、`/jsc-generic:role --status` | | Codex | `$role --status`，或用 `/skills` 選單；匯出可用 `$role --export /path/to/exports/` | | OpenCode / GitHub Copilot | 需完整 plugin 目錄保留 `scripts/`；OpenCode 以複製 `skills/` 安裝時不可用 | diff --git a/skills/spec-action-params/SKILL.md b/skills/spec-action-params/SKILL.md index 73df92e..797d1bc 100644 --- a/skills/spec-action-params/SKILL.md +++ b/skills/spec-action-params/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-action-params -description: JSC plugins 共用「Gitea／GitHub action 參數來源優先序」：開發 action 需要新參數時，先取 gitea/github context（composite）或 runner 注入的 GITHUB_*/GITEA_* 執行期環境變數（docker），取不到才經使用者同意新增 inputs；secrets/vars 在 action 內一律視為不可用，需要時宣告為 input 由呼叫端 workflow 傳入。當其他 skill 內文引用 spec-action-params 或 /jsc:spec-action-params、或開發 composite/docker action 需要決定參數來源時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「Gitea／GitHub action 參數來源優先序」：開發 action 需要新參數時，先取 gitea/github context（composite）或 runner 注入的 GITHUB_*/GITEA_* 執行期環境變數（docker），取不到才經使用者同意新增 inputs；secrets/vars 在 action 內一律視為不可用，需要時宣告為 input 由呼叫端 workflow 傳入。當其他 skill 內文引用 spec-action-params 或 /jsc-generic:spec-action-params、或開發 composite/docker action 需要決定參數來源時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-action-params — 共用 action 參數來源優先序 diff --git a/skills/spec-doc-funcs-handoff/SKILL.md b/skills/spec-doc-funcs-handoff/SKILL.md index 352f277..eca4baa 100644 --- a/skills/spec-doc-funcs-handoff/SKILL.md +++ b/skills/spec-doc-funcs-handoff/SKILL.md @@ -1,19 +1,19 @@ --- name: spec-doc-funcs-handoff -description: JSC plugins 共用「串接 doc-funcs 文件化流程」規範：code 類 skill（action 標準化、Dockerfile 整理）完成主要工作後，對整個目標專案完整執行 /jsc:doc-funcs（前置可用性檢查、完整流程步驟、由使用者裁示實作方式、完成後統一時間戳）。當其他 skill 內文引用 spec-doc-funcs-handoff 或 /jsc:spec-doc-funcs-handoff、或某 skill 的最後階段要完整執行 doc-funcs 補文件並重建 README 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「串接 funcs 文件化流程」規範：code 類 skill（action 標準化、Dockerfile 整理）完成主要工作後，對整個目標專案完整執行 /jsc-doc:funcs（前置可用性檢查、完整流程步驟、由使用者裁示實作方式、完成後統一時間戳）。當其他 skill 內文引用 spec-doc-funcs-handoff 或 /jsc-generic:spec-doc-funcs-handoff、或某 skill 的最後階段要完整執行 funcs 補文件並重建 README 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- -# spec-doc-funcs-handoff — 共用「串接 doc-funcs」流程 +# spec-doc-funcs-handoff — 共用「串接 funcs」流程 -code 類 skill 完成主要工作（action 標準化、容器化、Dockerfile 整理等）後，對**整個目標專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README。 +code 類 skill 完成主要工作（action 標準化、容器化、Dockerfile 整理等）後，對**整個目標專案**完整執行 `/jsc-doc:funcs` 流程，替程式碼與指令檔補文件並重建 README。 ## 流程 -- **前置檢查**：先確認 doc-funcs skill 可用（`/jsc:doc-funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。 -- 以呼叫端 skill 的目標專案根目錄為目標，執行 `doc-funcs` skill 的完整流程：判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證。 -- doc-funcs 會把 `action.yml`／`Dockerfile`／`entrypoint.sh`／`docker-compose*` 等視為指令檔／CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；`steps` 引用的腳本（`*.sh`／`*.ps1` 等）逐行註解；專案內各 function 補文件註解。 -- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，呼叫端 skill **不代為決定**。 -- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。 -- **統一時間戳**：doc-funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步呼叫端 skill 產生的各處時間戳（橫幅 step／`entrypoint.sh`／標頭註解區塊／README），**確保各處一致**（格式見 `/jsc:spec-time-log`）。 +- **前置檢查**：先確認 funcs skill 可用（`/jsc-doc:funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。 +- 以呼叫端 skill 的目標專案根目錄為目標，執行 `funcs` skill 的完整流程：判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證。 +- funcs 會把 `action.yml`／`Dockerfile`／`entrypoint.sh`／`docker-compose*` 等視為指令檔／CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；`steps` 引用的腳本（`*.sh`／`*.ps1` 等）逐行註解；專案內各 function 補文件註解。 +- funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，呼叫端 skill **不代為決定**。 +- 完成後依 funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。 +- **統一時間戳**：funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步呼叫端 skill 產生的各處時間戳（橫幅 step／`entrypoint.sh`／標頭註解區塊／README），**確保各處一致**（格式見 `/jsc-generic:spec-time-log`）。 -> 銜接方式：在呼叫端 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用呼叫端 skill 的目標專案根目錄。 +> 銜接方式：在呼叫端 skill 環境中以 `/jsc-doc:funcs`（或 Skill 工具）啟動 funcs 流程；若該流程需參數，沿用呼叫端 skill 的目標專案根目錄。 diff --git a/skills/spec-dockerfile/SKILL.md b/skills/spec-dockerfile/SKILL.md index 5eeaf13..a6a83ed 100644 --- a/skills/spec-dockerfile/SKILL.md +++ b/skills/spec-dockerfile/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-dockerfile -description: JSC plugins 共用「Dockerfile 六步流程」：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，以多階段建置縮小最終映像、ARG 集中檔首、相依描述先 COPY 以利 layer 快取、COPY --from 逐項明列、.dockerignore、對外契約不變與自我檢查。當其他 skill 內文引用 spec-dockerfile 或 /jsc:spec-dockerfile、或需要產生／重整 Dockerfile 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「Dockerfile 六步流程」：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，以多階段建置縮小最終映像、ARG 集中檔首、相依描述先 COPY 以利 layer 快取、COPY --from 逐項明列、.dockerignore、對外契約不變與自我檢查。當其他 skill 內文引用 spec-dockerfile 或 /jsc-generic:spec-dockerfile、或需要產生／重整 Dockerfile 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-dockerfile — 共用 Dockerfile 六步流程 diff --git a/skills/spec-execution/SKILL.md b/skills/spec-execution/SKILL.md index d4c43db..d52ce77 100644 --- a/skills/spec-execution/SKILL.md +++ b/skills/spec-execution/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-execution -description: JSC plugins 共用「執行原則」：自動執行原則（簡短計畫後直接執行到完成、只在必要決策中斷）、不臆測／需人工確認、不擴及無關檔案（排除 node_modules/.git/.docs/bin/obj/第三方依賴）。當其他 skill 內文引用 spec-execution 或 /jsc:spec-execution、或執行任何 JSC skill 需要共用執行原則時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「執行原則」：自動執行原則（簡短計畫後直接執行到完成、只在必要決策中斷）、不臆測／需人工確認、不擴及無關檔案（排除 node_modules/.git/.docs/bin/obj/第三方依賴）。當其他 skill 內文引用 spec-execution 或 /jsc-generic:spec-execution、或執行任何 JSC skill 需要共用執行原則時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-execution — 共用執行原則 diff --git a/skills/spec-git-safety/SKILL.md b/skills/spec-git-safety/SKILL.md index 5a8792f..7191c59 100644 --- a/skills/spec-git-safety/SKILL.md +++ b/skills/spec-git-safety/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-git-safety -description: JSC plugins 共用「Git 安全操作規範」：不破壞既有工作（未提交變更先提醒、絕不 reset --hard/checkout -f/clean）、git mv 保留歷史、develop → master 後備分支選擇、pull --ff-only、保守解衝突。當其他 skill 內文引用 spec-git-safety 或 /jsc:spec-git-safety、或執行任何會操作 git 工作區／分支的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「Git 安全操作規範」：不破壞既有工作（未提交變更先提醒、絕不 reset --hard/checkout -f/clean）、git mv 保留歷史、develop → master 後備分支選擇、pull --ff-only、保守解衝突。當其他 skill 內文引用 spec-git-safety 或 /jsc-generic:spec-git-safety、或執行任何會操作 git 工作區／分支的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-git-safety — 共用 Git 安全操作規範 diff --git a/skills/spec-gitea/SKILL.md b/skills/spec-gitea/SKILL.md index b7dea14..e23f828 100644 --- a/skills/spec-gitea/SKILL.md +++ b/skills/spec-gitea/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-gitea -description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc-generic:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-gitea — 共用 Gitea 工具規範 @@ -49,7 +49,7 @@ description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API - API base：`https:///api/v1`（repo 層：`https:///api/v1/repos//`）。 - 標頭：`Authorization: token $GITEA_TOKEN`。 - **分頁必須完整讀取**：持續累加 `page` 直到回傳筆數 `< limit`（或回空陣列）為止，不可只取第一頁。 -- 寫入（議題描述／留言／PR body）以 **UTF-8 JSON 檔**帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓內容顯示字面 `\n`（編碼細節見 `/jsc:spec-output`）。 +- 寫入（議題描述／留言／PR body）以 **UTF-8 JSON 檔**帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓內容顯示字面 `\n`（編碼細節見 `/jsc-generic:spec-output`）。 - API 失敗（401／403／網路錯誤）→ 回報錯誤（**遮蔽 token**）並停止；401／403 多半是 token 失效或權限不足。 - 版本相依端點（project／column／dependency 等）先以 GET 探測（404／501 視為不支援），**不得對未確認存在的端點做寫入**。 diff --git a/skills/spec-output/SKILL.md b/skills/spec-output/SKILL.md index 866d5d1..3a4d250 100644 --- a/skills/spec-output/SKILL.md +++ b/skills/spec-output/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-output -description: JSC plugins 共用「輸出規範」：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、優先以 Markdown 表格與 Mermaid 圖呈現。當其他 skill 內文引用 spec-output 或 /jsc:spec-output、或執行任何 JSC skill 需要語言／編碼／呈現規範時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「輸出規範」：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、優先以 Markdown 表格與 Mermaid 圖呈現。當其他 skill 內文引用 spec-output 或 /jsc-generic:spec-output、或執行任何 JSC skill 需要語言／編碼／呈現規範時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-output — 共用輸出規範 diff --git a/skills/spec-plugin-version/SKILL.md b/skills/spec-plugin-version/SKILL.md index 600c168..509d84e 100644 --- a/skills/spec-plugin-version/SKILL.md +++ b/skills/spec-plugin-version/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-plugin-version -description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、同一 PR 只以 master 版本計算一次最終升版、新 plugin 首發 0.0.1、一般變更 patch +1 且 master patch 到 9 後才進位 minor（0.0.9 → 0.1.0）、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc:spec-plugin-version、或要調整任一 JSC plugin（code／doc／generic）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、同一 PR 只以 master 版本計算一次最終升版、新 plugin 首發 0.0.1、一般變更 patch +1 且 master patch 到 9 後才進位 minor（0.0.9 → 0.1.0）、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc-generic:spec-plugin-version、或要調整任一 JSC plugin（code／doc／generic）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-plugin-version — 共用 plugin 版號規則 diff --git a/skills/spec-project-board/SKILL.md b/skills/spec-project-board/SKILL.md index 0d7d171..a66adb1 100644 --- a/skills/spec-project-board/SKILL.md +++ b/skills/spec-project-board/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-project-board -description: JSC plugins 共用「Gitea 專案看板進度欄位規範」：欄位語意對應（分析中／待處理／進行中／待測試／已完成，以看板實際欄位名稱為準）、依需求與 TODO 勾稽結果建議欄位、先 GET 探測 project/column API（404/501 視為不支援、不對未確認端點寫入）、不往回移、不支援時改列建議清單請人工拖曳、不得新建欄位。當其他 skill 內文引用 spec-project-board 或 /jsc:spec-project-board、或需要調整 Gitea 議題所在看板欄位時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「Gitea 專案看板進度欄位規範」：欄位語意對應（分析中／待處理／進行中／待測試／已完成，以看板實際欄位名稱為準）、依需求與 TODO 勾稽結果建議欄位、先 GET 探測 project/column API（404/501 視為不支援、不對未確認端點寫入）、不往回移、不支援時改列建議清單請人工拖曳、不得新建欄位。當其他 skill 內文引用 spec-project-board 或 /jsc-generic:spec-project-board、或需要調整 Gitea 議題所在看板欄位時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-project-board — 共用 Gitea 看板進度欄位規範 diff --git a/skills/spec-time-log/SKILL.md b/skills/spec-time-log/SKILL.md index 3d216db..d78410b 100644 --- a/skills/spec-time-log/SKILL.md +++ b/skills/spec-time-log/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-time-log -description: JSC plugins 共用「時間戳與輸出訊息格式規範」：更新時間一律台灣時區（Asia/Taipei）固定 yyyy/MM/dd HH:mm:ss、寫成檔內固定字串、流程完成後統一同步各處時間戳；輸出訊息統一為 [yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息（等級 INF/WRN/ERR/TRC/DBG）、一行一則。當其他 skill 內文引用 spec-time-log 或 /jsc:spec-time-log、或需要產生更新時間／統一 log 格式時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「時間戳與輸出訊息格式規範」：更新時間一律台灣時區（Asia/Taipei）固定 yyyy/MM/dd HH:mm:ss、寫成檔內固定字串、流程完成後統一同步各處時間戳；輸出訊息統一為 [yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息（等級 INF/WRN/ERR/TRC/DBG）、一行一則。當其他 skill 內文引用 spec-time-log 或 /jsc-generic:spec-time-log、或需要產生更新時間／統一 log 格式時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-time-log — 共用時間戳與訊息格式規範 From 54628d8b2c8908de10d15f7d0d0b62bf1f20558a Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 28 Jul 2026 17:15:23 +0800 Subject: [PATCH 2/3] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?= =?UTF-8?q?=E6=9B=B4=E5=90=8D=E8=A6=96=E7=82=BA=E6=96=B0=20plugin=EF=BC=8C?= =?UTF-8?q?=E7=89=88=E8=99=9F=E9=87=8D=E7=BD=AE=200.0.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit plugin 更名後，各助理以 @ 作為安裝識別鍵， 新名與舊名是兩筆獨立條目：舊 plugin 會被移除、新 plugin 為首次安裝， 兩者之間不存在版本比較，因此不會發生版本倒退，「版本單調遞增」不適用。 依 spec-plugin-version「新 plugin 首發 0.0.1」，三份 manifest 版號一律重置為 0.0.1， 不沿用舊名 jsc 的版本序列。 Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 1984f33..eee6dca 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-generic", - "version": "0.0.9", + "version": "0.0.1", "description": "JSC 跨 AI 助理共用規範 plugin（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc-generic: 前綴呼叫。", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 13650a9..c4abc2a 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-generic", - "version": "0.0.9", + "version": "0.0.1", "description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準。", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 06d632e..48535b5 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-generic", - "version": "0.0.9", + "version": "0.0.1", "description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc-generic: 前綴呼叫。", "skills": "./skills/" } From 2225b9176680f96bee94818255d53484bd9769ff Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 28 Jul 2026 17:15:23 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(spec-plugin-version):=20=E8=A3=9C=20pl?= =?UTF-8?q?ugin=20=E6=9B=B4=E5=90=8D=E7=9A=84=E7=89=88=E8=99=9F=E8=A6=8F?= =?UTF-8?q?=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 原規範只寫「新 plugin 首發 0.0.1」，未定義「更名是否算新 plugin」， 導致本次命名空間分離時誤把版號沿用舊名序列遞增。補上明確規則： - 新增「plugin 更名」條目：視為新 plugin，三份 manifest 版號重置 0.0.1，並說明識別鍵獨立、不存在版本比較的理由 - 「版本單調遞增」章節加註更名時不適用本節 - 補更名發佈的配套動作：使用者端須先移除舊 plugin 再安裝（不是 update）、清除 settings.json 的 enabledPlugins 舊鍵 - description 與內文的 plugin 名改用 jsc-code／jsc-doc／jsc-generic Co-Authored-By: Claude Opus 5 (1M context) --- skills/spec-plugin-version/SKILL.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/skills/spec-plugin-version/SKILL.md b/skills/spec-plugin-version/SKILL.md index 509d84e..68c53c8 100644 --- a/skills/spec-plugin-version/SKILL.md +++ b/skills/spec-plugin-version/SKILL.md @@ -1,11 +1,11 @@ --- name: spec-plugin-version -description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、同一 PR 只以 master 版本計算一次最終升版、新 plugin 首發 0.0.1、一般變更 patch +1 且 master patch 到 9 後才進位 minor（0.0.9 → 0.1.0）、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc-generic:spec-plugin-version、或要調整任一 JSC plugin（code／doc／generic）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、同一 PR 只以 master 版本計算一次最終升版、新 plugin 首發 0.0.1、plugin 更名（name 欄位改變）視為新 plugin 並把版號重置為 0.0.1、一般變更 patch +1 且 master patch 到 9 後才進位 minor（0.0.9 → 0.1.0）、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc-generic:spec-plugin-version、或要調整任一 JSC plugin（jsc-code／jsc-doc／jsc-generic）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- # spec-plugin-version — 共用 plugin 版號規則 -調整任一 JSC plugin（code／doc／generic 等）的版本號時，一律遵守以下規則。 +調整任一 JSC plugin（`jsc-code`／`jsc-doc`／`jsc-generic` 等）的版本號時，一律遵守以下規則。 ## 三個 manifest 同步 bump @@ -23,10 +23,16 @@ description: JSC plugins 共用「plugin 版號規則」：三個 manifest（plu - 新版本必須**大於 master 現行版本**。工作分支（如 `develop`）可能落後或經過 revert，直接在其舊版本上 +1 會讓版本倒退（例：master 已 `0.0.4`，develop 還在 `0.0.1`，此時應 bump 至 `0.0.5` 而非 `0.0.2`）——已安裝 `0.0.4` 的助理會因版本倒退而抓不到更新。 - 同一 PR／同一批變更只需最終一個版本；多次修改不必逐次 bump，也不要依工作分支上的中間版本連續累加。例如 `master` 是 `0.0.7` 時，同一 PR 的最終版本是 `0.0.8`。 +- **例外：plugin 更名時本節不適用** —— 更名後的 plugin 是獨立的安裝識別，與舊名沒有版本比較關係，見下節「plugin 更名」。 ## 版號選擇 - **新 plugin 首發**：`0.0.1`（即使是從 template 複製建立，也要把 template 殘留的版本改回 `0.0.1`）。 +- **plugin 更名**（manifest 的 `name` 欄位改變，例如 `jsc` → `jsc-code`）：**視為新 plugin，三份 manifest 版號一律重置為 `0.0.1`**，不沿用舊名的版本序列。 + + 理由：各助理以 `@` 作為安裝識別鍵（例如 `jsc-code@code` 與 `jsc@code` 是兩筆獨立條目）。更名發佈後，舊 plugin 會被移除、新 plugin 為首次安裝，兩者之間**不存在版本比較**，因此不會發生版本倒退，「版本單調遞增」不適用。git 歷史雖然延續，但版號描述的是**該 plugin 識別**的演進，而非 repo 的演進。 + + 更名發佈的配套動作：使用者端必須**先移除舊 plugin、再安裝新 plugin**（不是 update），並重開工作階段；`~/.claude/settings.json` 的 `enabledPlugins` 舊鍵需一併清除。 - **一般變更**（skill 新增／修改／移除、manifest 設定調整）：以 `master` 現行版本 patch +1；patch 只使用 `0` 到 `9`，只有 `master` 基準版 patch 已是 `9` 時才進位 minor 並把 patch 歸零，例如 `0.0.8 → 0.0.9 → 0.1.0`。 - **重大改版**（skill 大規模重構、破壞相容的呼叫方式變更）：minor +1、patch 歸零。