diff --git a/README.md b/README.md index 43b58c7..4ea358e 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # code — 跨 AI 助理 Plugin 一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的 plugin,提供一組以 **程式碼工作流** 為核心的 skills: -**RPG 攻防對決式 `git diff` review**、**裁決結果歸檔**、**Gitea AI review findings 修復、分類提交、push 與 PR 建立流程**、**Gitea 議題 TODO 彙整與逐項實作流程**、**C# / .NET NuGet 套件更新流程**、**Gitea 專案批次同步**,以及 **action / Dockerfile 標準化流程**。 +**Gitea AI review findings 修復、分類提交、push 與 PR 建立流程**、**Gitea 議題 TODO 彙整與逐項實作流程**、**C# / .NET NuGet 套件更新流程**、**Gitea 專案批次同步**,以及 **action / Dockerfile 標準化流程**。 核心是以 [Agent Skills(`SKILL.md`)](https://agentskills.io) 標準撰寫的共用 skills(唯一真實來源放在 `skills/`), 搭配各助理各自的 plugin manifest,讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。 -plugin 名為 `jsc`,在 Claude Code 與 Antigravity 中 skill 以 **`/jsc:` 前綴**呼叫(例如 `/jsc:code-review`)。 +plugin 名為 `jsc`,在 Claude Code 與 Antigravity 中 skill 以 **`/jsc:` 前綴**呼叫(例如 `/jsc:code-issues`)。 --- @@ -36,18 +36,13 @@ code/ │ └── marketplace.json # Codex marketplace(name: "code",url source 指向本 repo) ├── plugin.json # Antigravity 外掛定義(name: "jsc",skills: "./skills/") ├── skills/ # ★ 唯一真實來源:所有 skills -│ ├── code-review/ -│ │ ├── SKILL.md # 主 skill:取 diff → 選角 → 攻擊 → 裁決 → 總結 -│ │ └── roles/ # 一角色一檔(bard/mage/rogue/assassin/paladin) -│ ├── code-review-archive/ # 保存裁決:成立→已知問題、誤判→排除事項 │ ├── code-review-resolve/ # 解決 findings.json + 分類提交 + push + 發 PR │ ├── code-issues/ # 彙整議題 TODO(影響範圍小→大)+ 逐項實作 + 留言進度 │ ├── code-nuget/ # C# / .NET NuGet 套件更新 + build 驗證 │ ├── code-sync/ # 依擁有者批次 clone/更新 Gitea 專案 │ ├── code-action-docker/ # action 容器化(Node 主程式)+ 串接 doc-funcs │ ├── code-action-composite/ # composite action 標準化 + 串接 doc-funcs -│ ├── code-image/ # Dockerfile 整理成六步流程 + 串接 doc-funcs -│ └── hello/ # 範例 skill:驗證安裝、新增 skill 的範本 +│ └── code-image/ # Dockerfile 整理成六步流程 + 串接 doc-funcs ├── AGENTS.md # 跨助理共用指引 └── README.md ``` @@ -80,7 +75,7 @@ claude plugin marketplace remove code - 工作階段內 slash 版(等價):把 `claude plugin` 換成 `/plugin`。 - 本機開發(免 push):`claude plugin marketplace add C:\Users\h3285\source\repos.plugins\code`(本地路徑)後再 install。 -- **呼叫**:`/jsc:`(例 `/jsc:code-review`)。 +- **呼叫**:`/jsc:`(例 `/jsc:code-issues`)。 ### Codex @@ -99,7 +94,7 @@ codex plugin marketplace remove code - 安裝 token `jsc@code` = plugin 名(`.codex-plugin/plugin.json` 的 `name`)@ marketplace 名(`.agents/plugins/marketplace.json` 的 `name`)。 - 本 repo 的 Codex marketplace 以 `url` 來源指向自己,故 Codex **一律從 gitea 安裝**(需先 push);安裝後重啟 Codex。 -- **呼叫**:`$`(例 `$code-review`),或用 `/skills` 選單。 +- **呼叫**:`$`(例 `$code-issues`),或用 `/skills` 選單。 ### Antigravity(`agy`) @@ -121,7 +116,7 @@ agy plugin uninstall jsc - 若把 skills 放到 GitHub,則可直接 `agy plugin install https://github.com//`。 - 其他:`agy plugin list`、`agy plugin enable jsc` / `disable jsc`、`agy plugin validate `。安裝後重啟工作階段。 -- **呼叫**:`/jsc:`(例 `/jsc:code-review`)或依描述自動觸發。 +- **呼叫**:`/jsc:`(例 `/jsc:code-issues`)或依描述自動觸發。 ### OpenCode @@ -139,7 +134,7 @@ git -C ~/jsc-plugin pull cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/ # 移除 -rm -rf ~/.config/opencode/skills/{code-review,code-review-archive,code-review-resolve,code-issues,code-nuget,code-sync,code-action-docker,code-action-composite,code-image,hello} +rm -rf ~/.config/opencode/skills/{code-review-resolve,code-issues,code-nuget,code-sync,code-action-docker,code-action-composite,code-image} ``` > **Windows PowerShell**:`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。 @@ -152,17 +147,17 @@ rm -rf ~/.config/opencode/skills/{code-review,code-review-archive,code-review-re 安裝好之後,不必進互動介面,一行指令就能叫某個 skill 跑完並印出結果: -| 助理 | headless 指令 | 執行 `code-review` skill | +| 助理 | headless 指令 | 執行 `code-issues` skill | | --- | --- | --- | -| Claude Code | `claude -p ""` | `claude -p "/jsc:code-review main feature/login all --exclusions exclusions.md --known-issues known-issues.md"` | -| Codex | `codex exec ""` | `codex exec '$code-review main feature/login all --exclusions exclusions.md --known-issues known-issues.md'` | -| Antigravity | `agy -p ""` | `agy -p "/jsc:code-review main feature/login all --exclusions exclusions.md --known-issues known-issues.md"` | -| OpenCode | `opencode run ""` | `opencode run "用攻防角色 review main 與 feature/login 的差異"` | +| Claude Code | `claude -p ""` | `claude -p "/jsc:code-issues --tool api --repo plugins/code --issues 12,15 --yes"` | +| Codex | `codex exec ""` | `codex exec '$code-issues --tool api --repo plugins/code --issues 12,15 --yes'` | +| Antigravity | `agy -p ""` | `agy -p "/jsc:code-issues --tool api --repo plugins/code --issues 12,15 --yes"` | +| OpenCode | `opencode run ""` | `opencode run "讀 plugins/code 的 12、15 號議題,整理 TODO 並逐項實作、留言進度"` | - Claude / Antigravity 支援 `/jsc:` 前綴,直接 `-p "/jsc:"` 即可。 -- Codex 以 `$` 觸發;在 shell 請用**單引號**避免 `$` 被展開:`codex exec '$code-review …'`。 +- Codex 以 `$` 觸發;在 shell 請用**單引號**避免 `$` 被展開:`codex exec '$code-issues …'`。 - OpenCode 沒有前綴,用自然語言描述需求,模型會自動透過 skill 工具呼叫。 -- 帶引數就接在後面,例如 `claude -p "/jsc:code-review main feature/login mage"`、`codex exec '$code-review main feature/login mage'`。 +- 帶引數就接在後面,例如 `claude -p "/jsc:code-issues --issues 12"`、`codex exec '$code-issues --issues 12'`。 --- @@ -173,26 +168,6 @@ rm -rf ~/.config/opencode/skills/{code-review,code-review-archive,code-review-re -### `code-review` - -以 RPG 攻防對決方式審查 `git diff` 的程式碼審查 skill。審查範圍是兩個分支的差異,**來源分支與目標分支缺一不可**(缺漏會反問補齊)。角色分**攻擊方**(吟遊詩人=風格 🎼/法師=邏輯 🔮/盜賊=效率 ⚡/刺客=安全性 🗡️)與**防守方**(聖騎士=裁決 🛡️),每個角色定義在 `skills/code-review/roles/.md`(含英文名稱/專案/個性/徽章/代表色)。攻擊方分析 diff 找出問題(問題/等級/描述/建議/檔案位置/所在行數,審查前自動排除 `.` 開頭資料夾內的內容、以及排除事項檔與前次審查紀錄檔本身);防守方依專案根目錄排除事項設定檔、**前次審查紀錄(已知問題=前次發現但未解決的問題)**與原始碼脈絡裁決每條問題(🚫 略過/🔁 已知問題/❌ 誤判/✅ 成立)。使用者可選擇單一角色、整個攻擊方、整個防守方或全部;複選時以 sub agent 並行執行。 - -參數格式:` [角色...] [--exclusions <排除事項檔案路徑>] [--known-issues <前次審查紀錄路徑>]`(目標在前、來源在後;角色可省略,會詢問;`--exclusions`、`--known-issues` 指定對應檔案路徑,省略時若選到防守方會反問)。 - -- **Claude Code / Antigravity**:`/jsc:code-review`(反問分支與角色),或帶參數 `/jsc:code-review main feature/login mage`、`/jsc:code-review main feature/login all --exclusions exclusions.md --known-issues known-issues.md` -- **Codex**:`$code-review main feature/login attack`,或 `$code-review main feature/login all --exclusions docs/review-rules.md --known-issues docs/known-issues.md`,或用 `/skills` 選單 -- **OpenCode**:描述需求(如「用攻防角色 review main 與 feature/login 的差異,排除事項看 docs/review-rules.md、已知問題看 docs/known-issues.md」)自動觸發 - -### `code-review-archive` - -將 `/jsc:code-review` 已裁決的問題保存到專案:**✅ 成立** 附加到前次審查紀錄(已知問題)檔、**❌ 誤判** 附加到排除事項檔,讓防守方下次自動標 🔁 已知問題 / 🚫 略過;🔁/🚫 已存在者僅計數不重複寫入。只吃既有裁決結果(合併攻擊方問題表+防守方裁決表),不自己跑 review、不改程式碼,且寫檔前先取得同意。檔案格式依副檔名(`.md` / `.json`)決定。 - -參數:`--known-issues <前次審查紀錄路徑> --exclusions <排除事項檔案路徑>`(與 code-review 同名旗標,沿用同一組路徑;缺漏會反問)。 - -- **Claude Code / Antigravity**:`/jsc:code-review-archive --known-issues known-issues.md --exclusions exclusions.md` -- **Codex**:`$code-review-archive --known-issues docs/known-issues.md --exclusions docs/review-rules.md`,或用 `/skills` 選單 -- **OpenCode**:描述需求(如「把剛剛 code-review 成立的問題存到 known-issues.md、誤判存到 exclusions.md」)自動觸發 - ### `code-review-resolve` 五階段:**(A Git 同步)** 先 `fetch`,務必檢查目前分支的線上分支是否存在;存在則留在目前分支更新到最新,不存在則依序切換到遠端 `develop`/`master` 並更新到最新,找不到後備分支則停止;pull 發生衝突時告知並嘗試安全解衝突;只有來源分支與 PR 目標分支相同時,才必須從該分支建立新的工作分支,後續修復、commit、push 與 PR `head` 都使用新分支。**(B 解決)** 讀工作目錄 `.gitea/ai-review/findings.json`(Gitea AI review 產出的問題清單),依嚴重等級 **🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低** 由高到低**逐條修復**程式碼問題或登記誤報(無法安全自動修復者標「待人工處理」不硬改),已解決或已登記誤報者才自 `findings.json` 移除。**(C 提交)** 分析工作區**所有**變更,依異動內容歸類為 `feat`/`fix`/`docs`/`style`/`refactor`/`perf`/`test`/`chore`/`revert`,**每個 type 各自一個 commit**,訊息為「`type(範圍): 一句總結`」格式,**括號內的範圍須對應實際異動的功能/模組**(例 `feat(使用者登入): 新增帳密登入流程`、`perf(物件查詢): 改用批次查詢降低 DB 往返`,而非 `feat(新增功能)` 這類重述 type 的詞)。**(D 推送)** push 當前分支:先用**認證管理器**、失敗改用 **token**、再失敗**詢問使用者**。**(E 開 PR)** 用 token 透過 **Gitea API** 對目標分支發 PR(**目標分支不明必須詢問、不可猜測**),PR 描述可選**完整版**(重新分析 `git diff` 總結)/**簡單版**(逐條列 commit 訊息)/**使用者輸入**;完成後因內文可能含 gitea token,**提醒並清除 AI 助理對話內文**。除非遇到必要決策,否則依自動執行原則直接處理;token 一律由環境變數(如 `GITEA_TOKEN`)提供,全程不明文輸出。 @@ -263,21 +238,13 @@ rm -rf ~/.config/opencode/skills/{code-review,code-review-archive,code-review-re - **Codex**:`$code-image`,或 `$code-image --dockerfile docker/Dockerfile`,或用 `/skills` 選單 - **OpenCode**:描述需求(如「把這個專案的 Dockerfile 整理成參數處理→安裝套件→複製檔案→執行程序→縮小映像檔→設定入口六步、用多階段建置縮小映像,最後跑 doc-funcs 補文件並重建 README」)自動觸發 -### `hello` - -範例 skill,用來驗證 `jsc` plugin 是否安裝成功,也是新增 skill 的範本。觸發時回覆問候並簡述 plugin 用途。 - -- **Claude Code / Antigravity**:`/jsc:hello` -- **Codex**:`$hello`,或用 `/skills` 選單 -- **OpenCode**:描述需求(如「hello、測試 plugin 有沒有裝好」)自動觸發 - --- ## 新增一個 skill -1. 複製既有 skill 作範本:`cp -r skills/code-review skills/` +1. 複製既有 skill 作範本:`cp -r skills/code-issues skills/` 2. 編輯 `skills//SKILL.md` 的 frontmatter: - `name`:小寫、數字、連字號(`-`),最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc:`**。 - `description`:第三人稱,寫清楚「何時用、何時不用」與觸發關鍵字 — 這是各助理自動載入的唯一依據。