feat(skills): 新增 code-review 攻防審查等 9 個程式碼工作流 skills
This commit is contained in:
Jeffery
@@ -0,0 +1,166 @@
|
||||
---
|
||||
name: code-issues
|
||||
description: 處理一或多個 Gitea 議題的實作流程：先選擇使用 `tea` 或 Gitea REST API + `GITEA_TOKEN`（已選定則跳過），再確認議題所在專案（已知則跳過）與要處理的議題編號（一或多個）；接著讀取議題描述與留言、彙整需求，整理 TODO 列表並依影響範圍由小到大排序，既有 TODO 不足以達成議題需求時補上新 TODO 並附加到議題描述；最後逐項實作 TODO，每完成一項就把進度留言到議題。全程不建立任何草稿檔，中間成果一律用議題描述或留言保存，並盡量以表格與 Mermaid 圖呈現。當使用者說處理議題、實作議題、依議題 TODO 開工、把議題需求整理成 TODO 並逐項完成、議題進度留言，或提到 code-issues、issue 實作、Gitea 議題處理時觸發。不適用於：把需求拆分成多個新議題（用 doc-issues-analyze）、只同步議題狀態不實作（用 doc-issues-sync）、或與 Gitea 無關的本機 TODO 管理。
|
||||
argument-hint: "[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes]"
|
||||
---
|
||||
|
||||
# code-issues — 彙整議題 TODO 並逐項實作、留言進度
|
||||
|
||||
五階段 skill：先做**工具選擇**（`tea` 或 Gitea REST API + `GITEA_TOKEN`），再**確認議題所在專案**與**要處理的議題編號**，接著**讀取議題並彙整 TODO 列表**（依影響範圍小→大排序，缺漏的 TODO 附加到議題描述），最後**逐項實作 TODO**，每完成一項就把進度**留言到議題**。
|
||||
|
||||
| 階段 | 動作 | 可跳過條件 |
|
||||
| --- | --- | --- |
|
||||
| A. 工具選擇 | 檢查 `tea` / `GITEA_TOKEN` → 詢問使用者要用 `tea` 或 `api` | 使用者已明確選定（`--tool` 或對話中已選）|
|
||||
| B. 確認專案 | 詢問議題所在專案（owner/repo），可用目前 repo 的 origin 當預設選項 | 已知專案（`--repo`、對話已提供、或使用者確認採用 origin）|
|
||||
| C. 選擇議題 | 詢問要處理的議題編號，**一個或多個** | 已提供（`--issues` 或對話中已列出）|
|
||||
| D. 彙整 TODO | 讀議題描述＋留言 → 彙整需求 → TODO 依**影響範圍小→大**排序 → 不足以達成需求的缺漏 TODO **附加到議題描述** | — |
|
||||
| E. 逐項實作 | 依排序實作每項 TODO → 每完成一項：勾選議題描述 checkbox ＋ **留言進度到議題** | — |
|
||||
|
||||
---
|
||||
|
||||
## 絕對準則（不可違反）
|
||||
|
||||
- **不建立任何草稿檔**：不寫 `.docs/`、不寫暫存檔、不用本機檔案傳遞中間結果。需求彙整、TODO 排序、實作進度、驗證結果等所有中間成果，一律留在**對話內容**，並透過 `tea` 或 Gitea API **保存到議題描述或議題留言**。唯一例外是階段 E 在議題範圍內對**目標 repo 原始碼**的正常程式修改。
|
||||
- **盡量使用表格或圖形**：面向使用者的輸出與寫入議題的內容（需求彙整、TODO 列表、進度回報），優先以 **Markdown 表格**與 **Mermaid 圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）呈現，讓使用者一眼看懂意圖；圖表必須忠實反映議題內容，不得杜撰。
|
||||
|
||||
## 輸出規範（務必遵守）
|
||||
|
||||
- **語言**：所有面向使用者的輸出與寫入議題的描述／留言，一律使用**繁體中文（台灣用語）**；僅程式碼識別字、檔名、指令、API 路徑等技術標識保留原文，**不可**使用簡體字。
|
||||
- **編碼無亂碼**：凡輸出或寫入含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框或錯碼。用 API 送出議題描述／留言時，以 UTF-8 JSON 檔帶入（如 `--data @body.json`），換行必須是實際換行，不可讓議題顯示字面 `\n`。
|
||||
- **Token 機密保護（極重要）**：gitea token 一律**從環境變數讀取**（`$GITEA_TOKEN`），**絕不**寫死、不 echo、不寫進議題或 log；顯示給使用者的指令／錯誤訊息一律**遮蔽 token**（以 `***` 取代）。檢查時只輸出「已設定／未設定」。
|
||||
- **不依賴 `jq`**（環境未必安裝）：解析 JSON 用 `tea` 的結構化輸出（`--output csv` / `--fields`），或把原始 JSON 直接交給助理解析，不要 pipe 到 `jq`。
|
||||
- **自動執行原則**：除非遇到不可忽略的必要決策（工具皆不可用、專案不明、議題編號缺失、TODO 與需求衝突需人工裁示、實作失敗需使用者決策），否則各階段輸出簡短計畫／進度後直接執行到完成；帶 `--yes` 時更不應為一般寫入／留言反覆詢問。階段 A／B／C 的詢問在「可跳過條件」成立時**必須跳過**，不要重複確認已知資訊。
|
||||
|
||||
---
|
||||
|
||||
## 參數
|
||||
|
||||
格式：`[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes]`
|
||||
|
||||
- `--tool <tea|api>`：指定工具，**帶此參數時跳過階段 A 的詢問**（仍需驗證該工具可用）。
|
||||
- `--repo <owner/repo>`：議題所在專案，**帶此參數時跳過階段 B 的詢問**。
|
||||
- `--issues <編號,以逗號分隔>`：要處理的議題編號，可一個或多個（例 `--issues 12` 或 `--issues 12,15,18`），**帶此參數時跳過階段 C 的詢問**。
|
||||
- `--host <gitea 主機>`：gitea 主機（如 `gitea.jsc.idv.tw`）；省略時依 `--repo` 的 URL、目前 repo 的 origin 或 `tea login` 對應 host 決定，無法決定時詢問。
|
||||
- `--yes`：全自動；即使未帶此參數，也依「自動執行原則」盡量不中斷。
|
||||
|
||||
---
|
||||
|
||||
## 階段 A：工具選擇（已選定則跳過）
|
||||
|
||||
**若使用者已透過 `--tool` 或對話明確選定工具，跳過詢問**，只做該工具的可用性驗證。
|
||||
|
||||
1. 檢查 `tea` 是否存在：`command -v tea`；存在則執行 `tea login list` 記錄可用 login 與 host（失敗記錄原因，不中止）。
|
||||
2. 檢查 `GITEA_TOKEN` 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容：
|
||||
|
||||
```bash
|
||||
[ -n "${GITEA_TOKEN}" ] && echo "GITEA_TOKEN 已設定" || echo "GITEA_TOKEN 未設定"
|
||||
```
|
||||
|
||||
3. 以表格呈現檢查結果後詢問使用者要用哪一種：
|
||||
|
||||
| 選項 | 可選條件 | 後續使用方式 |
|
||||
| --- | --- | --- |
|
||||
| `tea` | `tea` 可執行且目標 host 有對應 login | 命令一律帶 `--login <name> --repo <owner>/<repo>` |
|
||||
| `api` | `GITEA_TOKEN` 已設定 | Gitea REST API + `curl`，標頭 `Authorization: token $GITEA_TOKEN` |
|
||||
|
||||
4. 兩種方式都不可用 → 回報缺少 `tea login` 或 `GITEA_TOKEN` 並停止；不要請使用者把 token 貼進對話。
|
||||
|
||||
## 階段 B：確認議題所在專案（已知則跳過）
|
||||
|
||||
**若已透過 `--repo`、對話內容或先前階段確知專案，跳過詢問。**
|
||||
|
||||
1. 若目前工作目錄是 git repo，解析 `git remote get-url origin` 取得 host／owner／repo 作為**預設選項**提供給使用者。
|
||||
2. 詢問使用者議題所在專案（owner/repo 或 repo URL）；使用者只給名稱時，確認 host／owner 補齊完整座標。
|
||||
3. 驗證專案可讀：
|
||||
- `tea`：`tea repos <owner>/<repo>` 或 `tea issues list --repo <owner>/<repo> --limit 1`
|
||||
- `api`：`GET https://<host>/api/v1/repos/<owner>/<repo>`
|
||||
4. 確認本機是否已 clone 該 repo（實作階段需要）；找不到本機 repo 時詢問路徑或是否需要 clone，不臆測位置。
|
||||
|
||||
## 階段 C：選擇要處理的議題編號（一個或多個）
|
||||
|
||||
**若已透過 `--issues` 或對話提供編號，跳過詢問。**
|
||||
|
||||
1. 先列出該專案開啟中的議題供使用者參考（編號、標題、標籤、里程碑），以表格呈現：
|
||||
- `tea`：`tea issues list --repo <owner>/<repo> --state open --output csv --fields index,title,labels,milestone`
|
||||
- `api`：`GET {base}/issues?state=open&type=issues`（有分頁必須完整分頁讀取）
|
||||
2. 詢問使用者要處理哪些議題編號，**接受一個或多個**。
|
||||
3. 逐一驗證每個編號存在且為 issue（非 pull request）；不存在或已關閉的編號回報並請使用者確認是否仍要處理。
|
||||
|
||||
## 階段 D：彙整需求與 TODO 列表（依影響範圍小→大排序）
|
||||
|
||||
對每一個選定議題執行：
|
||||
|
||||
### D1. 讀取議題完整內容
|
||||
|
||||
- 讀取 `title`、`body`、`state`、`labels`、`milestone`、`assignees` 與**所有留言**：
|
||||
- `tea`：`tea issues <index> --repo <owner>/<repo> --comments`
|
||||
- `api`：`GET {base}/issues/{index}` 與 `GET {base}/issues/{index}/comments`
|
||||
- 留言中若有需求補充、變更或取消，必須納入需求彙整，並以最新留言為準。
|
||||
|
||||
### D2. 彙整需求並盤點既有 TODO
|
||||
|
||||
- 把議題描述與留言整理成**需求彙整**：目標、驗收條件、限制條件；只做歸納，不編造議題未提及的需求，不確定處標註「需人工確認」。
|
||||
- 盤點議題描述中既有的 Markdown checklist（`- [ ]` / `- [x]`）作為既有 TODO；已勾選項目視為已完成，不重做。
|
||||
|
||||
### D3. 產生排序後的 TODO 列表
|
||||
|
||||
- 每項 TODO 必須**可執行、可驗收**，並評估其**影響範圍**（預計修改的檔案／模組數與波及面）：
|
||||
|
||||
| 影響範圍 | 定義（參考） |
|
||||
| --- | --- |
|
||||
| XS | 單一檔案內的局部修改（文案、設定值、小修正） |
|
||||
| S | 單一檔案或單一函式的邏輯調整 |
|
||||
| M | 同一模組內跨多檔案的修改 |
|
||||
| L | 跨模組修改或介面／契約變更 |
|
||||
| XL | 跨專案、資料結構或流程性的大改動 |
|
||||
|
||||
- **依影響範圍由小到大排序**（XS → XL）；範圍相同時，前置依賴在前。
|
||||
- **勾稽需求覆蓋度**：逐條比對需求彙整與 TODO 列表；若既有 TODO **不足以達成議題描述與需求**，補上缺漏的 TODO（標註「新增」）。
|
||||
- 有助理解時，在留言或描述中加入 Mermaid 流程圖呈現 TODO 之間的依賴與執行順序。
|
||||
|
||||
### D4. 缺漏 TODO 附加到議題描述
|
||||
|
||||
- 若 D3 有新增 TODO，用 `tea` 或 API **更新議題描述**：保留原描述內容，於既有 `## TODO` 區塊補上新項目；沒有該區塊時在描述最後加上 `## TODO`：
|
||||
- `tea`：`tea issues edit <index> --repo <owner>/<repo> --description <更新後全文>`（tea 版本不支援時改用 API）
|
||||
- `api`：`PATCH {base}/issues/{index}`，body 以 UTF-8 JSON 檔帶入 `{"body": "..."}`
|
||||
- 更新前先向使用者以表格摘要「新增了哪些 TODO、為什麼需要」；帶 `--yes` 時直接執行並回報。
|
||||
- 沒有新增 TODO 時不改動議題描述。
|
||||
|
||||
## 階段 E：逐項實作 TODO，每完成一項留言到議題
|
||||
|
||||
依 D3 排序（多議題時先完成一個議題的所有 TODO，再進入下一個議題；有跨議題依賴時先處理被依賴者）逐項執行：
|
||||
|
||||
1. **實作**：在本機 repo 依 TODO 內容實作，只修改該 TODO 必要範圍；發現需要擴大範圍或牽動其他 TODO 時，先停止並詢問使用者。
|
||||
2. **驗證**：執行適合專案的建置／測試／驗證；失敗時修正到通過，無法通過則記錄原因並在留言中標註「待人工處理」。
|
||||
3. **更新議題描述**：把該 TODO 的 checkbox 由 `- [ ]` 勾成 `- [x]`（同 D4 的更新方式）。
|
||||
4. **留言進度到議題**（每完成一項就留言，不可累積到最後一次補）：
|
||||
- `tea`：`tea comment <index> --repo <owner>/<repo> <內容>`
|
||||
- `api`：`POST {base}/issues/{index}/comments`，body 以 UTF-8 JSON 檔帶入
|
||||
- 留言內容以表格呈現：本項 TODO、影響範圍、主要變更（檔案／模組）、驗證方式與結果、整體進度（`已完成 n/總數 m`）；有助理解時附 Mermaid 圖。
|
||||
5. 全部 TODO 完成後，對每個議題留下**總結留言**：TODO 完成統計表、變更檔案清單、驗證總結、待人工處理項目（若有）。
|
||||
|
||||
> 本 skill 範圍到「實作＋留言」為止；是否 commit、push、開 PR 或關閉議題**不在本 skill 自動範圍**，由使用者另行指示（可搭配 `code-review-resolve` 的分類提交與 PR 流程）。
|
||||
|
||||
---
|
||||
|
||||
## 總結
|
||||
|
||||
各階段執行後輸出：
|
||||
|
||||
- **階段 A**：選定工具（`tea` 或 `api`）、可用性檢查結果（token 只顯示已設定／未設定）、是否因已選定而跳過詢問。
|
||||
- **階段 B**：議題所在專案（host／owner／repo）、本機 repo 位置、是否因已知而跳過詢問。
|
||||
- **階段 C**：處理的議題編號清單（含標題），是否因已提供而跳過詢問。
|
||||
- **階段 D**：每個議題的需求彙整重點、TODO 列表（含影響範圍排序）、新增了幾項 TODO 並是否已附加到議題描述。
|
||||
- **階段 E**：每項 TODO 的完成狀態與留言連結（或編號）、驗證結果、待人工處理項目；提醒後續可自行決定 commit／PR／關閉議題。
|
||||
|
||||
---
|
||||
|
||||
## 呼叫方式
|
||||
|
||||
格式：`[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes]` — 全部可省略；省略時依階段 A／B／C 詢問（已知資訊一律跳過詢問）。token 一律由環境變數 `GITEA_TOKEN` 提供。
|
||||
|
||||
| 助理 | 呼叫 |
|
||||
| --- | --- |
|
||||
| Claude Code / Antigravity | `/jsc:code-issues`，或 `/jsc:code-issues --tool api --repo plugins/code --issues 12,15 --yes` |
|
||||
| Codex | `$code-issues`，或 `$code-issues --tool tea --repo plugins/code --issues 12`，或用 `/skills` 選單 |
|
||||
| OpenCode | 描述需求（如「用 GITEA_TOKEN 讀 plugins/code 的 12、15 號議題，整理需求成 TODO 依影響範圍小到大排序、缺的補進議題描述，然後逐項實作、每完成一項留言進度」）自動觸發 |
|
||||
Reference in New Issue
Block a user