feat(skills): 新增 code-review 攻防審查等 9 個程式碼工作流 skills
This commit is contained in:
Jeffery
@@ -0,0 +1,174 @@
|
|||||||
|
---
|
||||||
|
name: code-action-composite
|
||||||
|
description: 將 Gitea／GitHub「composite action」專案標準化並串接文件化流程：(1) 確認 action 為 composite（`runs.using: composite`），非 composite 則保守確認後對齊；(2) 在 `runs.steps` 最前面注入啟動橫幅 step，輸出 action 名稱／用途／更新時間（Asia/Taipei `yyyy/MM/dd HH:mm:ss`），並於 `action.yml` 開頭補用途／更新時間註解區塊；(3) 最後完整執行 `/jsc:doc-funcs` 處理流程（function 文件、指令檔逐行註解、重建 README）。當使用者說整理 composite action、把 action 標準化為 composite、讓 composite action 啟動時印名稱／用途／更新時間、對 composite action 補文件，或提到 code-action-composite 時觸發。不適用於：Docker 容器 action（用 code-action-docker）、非 action 專案、或不需文件化的一般 repo。
|
||||||
|
argument-hint: "[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>] [--yes]"
|
||||||
|
---
|
||||||
|
|
||||||
|
# code-action-composite — composite action 標準化＋文件化
|
||||||
|
|
||||||
|
四階段 skill：先做**前置設定與偵測**（找出 action 專案、讀取名稱／用途、判斷是否為 composite），再**確認／對齊為 composite action**，接著在 `runs.steps` 最前面**注入會輸出 action 名稱／用途／更新時間的啟動橫幅 step**，最後**完整執行 `/jsc:doc-funcs` 處理流程**替整個專案補文件並重建 README。
|
||||||
|
|
||||||
|
| 階段 | 動作 |
|
||||||
|
| --- | --- |
|
||||||
|
| A. 前置設定與偵測 | 決定 action 根目錄 → 讀 `action.yml`／`action.yaml` 的 `name`／`description`／`runs` → 判斷是否為 composite |
|
||||||
|
| B. 對齊為 composite | 已是 composite 則保留既有 `steps`；非 composite 則**保守確認後對齊**（高風險，先確認），整理被引用的腳本路徑 |
|
||||||
|
| C. 注入啟動橫幅 step | 在 `runs.steps` 最前面插入一個 shell step，輸出 action **名稱／用途／更新時間**；並於 `action.yml` 開頭補用途／更新時間註解區塊 |
|
||||||
|
| D. 串接 doc-funcs | 對整個 action 專案完整執行 `/jsc:doc-funcs` 流程（function 文件、指令檔逐行註解、重建 README） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 輸出規範（務必遵守）
|
||||||
|
|
||||||
|
- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、git 指令、API 路徑、YAML 鍵名、程式碼等技術標識保留原文，**不可**使用簡體字。
|
||||||
|
- **編碼無亂碼**：凡輸出含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框或錯碼。產生／覆寫的 `action.yml`／`action.yaml`、被引用腳本、`README.md` 同樣需 UTF-8（不含 BOM）。
|
||||||
|
- **自動執行原則**：除非使用者明確要求先確認，或遇到不可忽略的必要決策，否則各階段只需輸出簡短計畫／進度後直接執行到完成。**一定會中斷詢問的點**：階段 B 主 action「非 composite 需對齊」時（破壞性，須先確認），以及階段 D 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
|
||||||
|
- **不破壞既有工作**：改寫 `action.yml`／搬移或改寫被引用腳本前，若工作區有未提交變更，先提醒使用者建議先 commit／備份；**絕不** `reset --hard`／`checkout -f`／`clean`，也不刪除使用者既有原始碼。移動檔案優先用 `git mv` 以保留歷史。
|
||||||
|
- **保留行為**：對齊 composite 與注入橫幅 step 只「補強」既有流程，不得擅自改變既有 `steps` 的執行順序、輸入（`inputs`）／輸出（`outputs`）契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。
|
||||||
|
- **不擴及無關檔案**：本 skill 只動 action 專案根目錄內的：`action.yml`／`action.yaml`、其 `steps` 直接引用的內嵌腳本（如 `*.sh`／`*.ps1`），以及階段 D 由 doc-funcs 流程處理的目標；排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 參數
|
||||||
|
|
||||||
|
格式：`[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>] [--yes]`
|
||||||
|
|
||||||
|
- `--action-dir <action 根目錄>`：action 專案根目錄。**省略時預設目前工作目錄**（須含 `action.yml`／`action.yaml`，否則依 A1 詢問）。
|
||||||
|
- `--manifest <action.yml 路徑>`：指定 action manifest 檔（相對 action 根目錄）。省略時依 A1 自動尋找 `action.yml`／`action.yaml`。
|
||||||
|
- `--yes`：盡量不中斷。即使帶此參數，「非 composite 需對齊」與 doc-funcs 的「如何實作」仍會詢問。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 A：前置設定與偵測
|
||||||
|
|
||||||
|
### A1. 決定 action 根目錄與 manifest
|
||||||
|
|
||||||
|
- 帶 `--action-dir` → 採用（展開 `~`）；省略 → 用目前工作目錄。
|
||||||
|
- manifest：帶 `--manifest` → 採用；否則於根目錄找 `action.yml`，再退而 `action.yaml`。
|
||||||
|
- **找不到** action manifest → 回報「此目錄不是 action 專案（缺 action.yml／action.yaml）」並詢問正確路徑，**不臆測**、不在非 action 專案上動工。
|
||||||
|
|
||||||
|
### A2. 讀取 action 名稱與用途
|
||||||
|
|
||||||
|
從 action manifest 讀取：
|
||||||
|
|
||||||
|
- `name`：action 名稱（供啟動橫幅與 README 使用）。
|
||||||
|
- `description`：action 用途。
|
||||||
|
- `runs`：目前的執行設定（`using`、`steps`、`main`、`image`、`entrypoint` 等）。
|
||||||
|
- `inputs`／`outputs`：對外契約（後續不得破壞）。
|
||||||
|
|
||||||
|
若 `name`／`description` 缺漏，回報並請使用者補；無法取得時於後續輸出以「（未提供）」保守標示，**不編造**。
|
||||||
|
|
||||||
|
### A3. 判斷是否為 composite
|
||||||
|
|
||||||
|
依 `runs.using` 判定：
|
||||||
|
|
||||||
|
- `composite` → 即為目標型態，記下既有 `runs.steps`，直接進入階段 B 的「已是 composite」分支。
|
||||||
|
- `node*`（JS action）／`docker`（Docker 容器 action）／其他 → 視為**非 composite**。
|
||||||
|
|
||||||
|
輸出偵測結果（action 名稱、用途、`runs.using`、是否為 composite、既有 step 數量），再進入階段 B。
|
||||||
|
|
||||||
|
> 若偵測為 **Docker 容器 action**，且使用者本意是容器化而非 composite，提醒可改用 `/jsc:code-action-docker`，再依使用者裁示決定是否續行。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 B：確認／對齊為 composite action
|
||||||
|
|
||||||
|
### B1. 已是 composite
|
||||||
|
|
||||||
|
- 確認 `runs.using: composite` 與既有 `runs.steps`，**不更動既有 steps 的順序與邏輯**，直接進入階段 C。
|
||||||
|
- 順手檢查 step 的必要欄位（`run` step 須有 `shell`；`uses` step 的引用是否存在），有疑慮以回報標註，不擅改。
|
||||||
|
|
||||||
|
### B2. 非 composite（需對齊）
|
||||||
|
|
||||||
|
這是**破壞性高風險決策**：先以 `AskUserQuestion` 向使用者確認，選項至少含「對齊為 composite」「維持原樣只做文件化（略過對齊）」「改用 code-action-docker」「其他」。經確認「對齊為 composite」後才改寫：
|
||||||
|
|
||||||
|
- 將 `runs` 保守對齊為 composite，把原執行入口轉為 composite step：
|
||||||
|
- 原 JS action（`runs.using: node*`，`runs.main: <x>.js`）→ 轉為一個 `run` step，於 step 內以 `node <x>.js` 執行（`shell: bash`），保留 `inputs`／`outputs` 與環境變數（`INPUT_*`）契約。
|
||||||
|
- 原 Docker action（`runs.using: docker`）→ Docker 行為通常無法可靠等價地塞進 composite；**不臆測改寫**，以回報＋`# 需人工確認` 標註，並建議改用 `/jsc:code-action-docker`。
|
||||||
|
- 任何無法可靠等價對齊處，**不臆測**：以 `# 需人工確認：...` 標註並回報，保留原檔行為。
|
||||||
|
|
||||||
|
對齊後的 `runs` 形如：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
runs:
|
||||||
|
using: composite
|
||||||
|
steps:
|
||||||
|
# （階段 C 會在此處最前面插入啟動橫幅 step）
|
||||||
|
- name: <原執行入口轉成的 step>
|
||||||
|
shell: bash
|
||||||
|
run: node ./index.js
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 C：注入啟動橫幅 step（輸出名稱／用途／更新時間）
|
||||||
|
|
||||||
|
在 `runs.steps` **最前面**插入（或更新）一個輸出橫幅的 step，讓 composite action 一啟動就**輸出 action 名稱、用途、更新時間**；並於 `action.yml` 開頭補用途／更新時間註解區塊。
|
||||||
|
|
||||||
|
- **更新時間**為產生此檔當下的時間戳，使用台灣時區（Asia/Taipei）並固定為 `yyyy/MM/dd HH:mm:ss`（可用 `TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'` 取得），**寫成檔內固定字串**（非執行期動態時間）。
|
||||||
|
- 名稱／用途取自階段 A2 的 `action.yml`（缺漏時以「（未提供）」標示）。
|
||||||
|
- 橫幅 step 須有可辨識的 `name`（如 `顯示 action 資訊`）與 `shell: bash`；其後緊接既有／對齊後的 steps，**不更動既有 steps**。
|
||||||
|
- 若已存在本 skill 先前插入的橫幅 step（依 `name` 辨識），則**更新**其內容與更新時間，不重複插入。
|
||||||
|
|
||||||
|
範例（既有 steps 接在橫幅 step 之後）：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: <action name>
|
||||||
|
description: <action description>
|
||||||
|
|
||||||
|
runs:
|
||||||
|
using: composite
|
||||||
|
steps:
|
||||||
|
# 啟動橫幅：輸出名稱／用途／更新時間（此 step 由 code-action-composite 產生）
|
||||||
|
- name: 顯示 action 資訊
|
||||||
|
shell: bash
|
||||||
|
run: |
|
||||||
|
echo "================================================"
|
||||||
|
echo "Action : <action name>"
|
||||||
|
echo "用途 : <action description>"
|
||||||
|
echo "更新時間: 2026/06/30 18:30:05"
|
||||||
|
echo "================================================"
|
||||||
|
# === 以下為既有／對齊後的 steps（保持原順序與邏輯）===
|
||||||
|
- name: <既有 step>
|
||||||
|
shell: bash
|
||||||
|
run: node ./index.js
|
||||||
|
```
|
||||||
|
|
||||||
|
- `action.yml` 開頭的「用途／更新時間」註解區塊與每行註解，最終會在階段 D 由 `/jsc:doc-funcs` 的指令檔流程統一補齊／覆寫為標準格式（用途與更新日期同一註解區塊、逐行註解）；本階段先確保**執行期橫幅輸出**正確即可。
|
||||||
|
- 自我檢查：插入橫幅 step 後 YAML 仍可解析（縮排、`steps` 為 list、每個 `run` step 都有 `shell`），且 `inputs`／`outputs` 未被更動。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 D：完整執行 /jsc:doc-funcs 處理流程
|
||||||
|
|
||||||
|
標準化完成後，對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README：
|
||||||
|
|
||||||
|
- 以階段 A1 的 action 根目錄為目標，執行 `doc-funcs` skill 的完整流程（判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證）。
|
||||||
|
- doc-funcs 會把 `action.yml`／`action.yaml` 視為 CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；`steps` 內引用的腳本（`*.sh`／`*.ps1` 等）逐行註解；專案內各 function 補文件註解。
|
||||||
|
- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，本 skill 不代為決定。
|
||||||
|
- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
|
||||||
|
|
||||||
|
> 銜接方式：在本 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用本 skill 的 action 根目錄為目標專案。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 總結
|
||||||
|
|
||||||
|
各階段執行後輸出：
|
||||||
|
|
||||||
|
- **階段 A**：action 根目錄、manifest 路徑、action 名稱／用途、`runs.using`、是否為 composite、既有 step 數量。
|
||||||
|
- **階段 B**：是否對齊為 composite（及對齊摘要與「需人工確認」清單），或維持原樣的理由。
|
||||||
|
- **階段 C**：橫幅 step 的輸出內容（名稱／用途／更新時間）與插入位置，並確認既有 steps、`inputs`／`outputs` 未被破壞。
|
||||||
|
- **階段 D**：doc-funcs 流程的處理結果（文件化的 function 與指令檔、重建的 README）。
|
||||||
|
- 列出本次新增／變更的檔案與其相對路徑，並提醒使用者於提交前確認 `action.yml` 可正常解析、composite action 能正確啟動並輸出橫幅。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 呼叫方式
|
||||||
|
|
||||||
|
格式：`[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>] [--yes]` — 全部可省略（根目錄預設目前工作目錄；manifest 自動尋找）。
|
||||||
|
|
||||||
|
| 助理 | 呼叫 |
|
||||||
|
| --- | --- |
|
||||||
|
| Claude Code / Antigravity | `/jsc:code-action-composite`，或 `/jsc:code-action-composite --action-dir ~/work/my-action` |
|
||||||
|
| Codex | `$code-action-composite`，或 `$code-action-composite --action-dir ~/work/my-action`，或用 `/skills` 選單 |
|
||||||
|
| OpenCode | 描述需求（如「把這個 composite action 標準化，在 steps 最前面加一個會輸出 action 名稱／用途／更新時間的 step，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |
|
||||||
@@ -0,0 +1,241 @@
|
|||||||
|
---
|
||||||
|
name: code-action-docker
|
||||||
|
description: 將 Gitea／GitHub「Docker 容器 action」專案標準化為 Node 主程式＋容器化，並串接文件化流程：(1) 檢查 action 主程式是否為 Node，否則保守改寫為 Node，且所有 `.js` 檔一律集中到 `src/` 資料夾；(2) 產生 `entrypoint.sh`，啟動前先輸出 action 名稱／用途／更新時間，再執行 node 主程式；(3) 產生使用最新 node 版本的 `Dockerfile`；(4) 最後完整執行 `/jsc:doc-funcs` 處理流程（function 文件、指令檔逐行註解、重建 README）。當使用者說把 action 改成 docker／node、容器化 action、action 主程式 node 化、把 js 收進 src、產 entrypoint.sh／Dockerfile 給 action，或提到 code-action-docker 時觸發。不適用於：非 action 專案、純前端打包、或不需容器化的一般 repo。
|
||||||
|
argument-hint: "[--action-dir <action 根目錄>] [--node-version <node tag>] [--main <主程式檔>] [--yes]"
|
||||||
|
---
|
||||||
|
|
||||||
|
# code-action-docker — action 容器化（Node 主程式）＋文件化
|
||||||
|
|
||||||
|
五階段 skill：先做**前置設定與偵測**（找出 action 專案、讀取名稱／用途、判斷主程式語言），再把**主程式 Node 化並將所有 `.js` 收進 `src/`**，接著產生**啟動前先輸出 action 名稱／用途／更新時間的 `entrypoint.sh`**，然後產生**使用最新 node 版本的 `Dockerfile`**（並對齊 `action.yml` 的 docker 設定），最後**完整執行 `/jsc:doc-funcs` 處理流程**替整個專案補文件並重建 README。
|
||||||
|
|
||||||
|
| 階段 | 動作 |
|
||||||
|
| --- | --- |
|
||||||
|
| A. 前置設定與偵測 | 決定 action 根目錄 → 讀 `action.yml`／`action.yaml` 的 `name`／`description` → 判斷目前主程式與語言 |
|
||||||
|
| B. 主程式 Node 化 | 主程式非 Node 則**保守改寫**為 Node（高風險，先確認）→ 所有 `.js` 集中到 `src/`，更新所有引用、`package.json`、`action.yml` |
|
||||||
|
| C. entrypoint.sh | 產生 `entrypoint.sh`：先輸出 action **名稱／用途／更新時間**，再 `exec` node 主程式 |
|
||||||
|
| D. Dockerfile | 依六步流程（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口）產生使用**最新 node 版本**的 `Dockerfile`，多階段建置縮小映像、`ENTRYPOINT` 指向 `entrypoint.sh` |
|
||||||
|
| E. 串接 doc-funcs | 對整個 action 專案完整執行 `/jsc:doc-funcs` 流程（function 文件、指令檔逐行註解、重建 README） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 輸出規範（務必遵守）
|
||||||
|
|
||||||
|
- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、git／docker 指令、API 路徑、程式碼等技術標識保留原文，**不可**使用簡體字。
|
||||||
|
- **編碼無亂碼**：凡輸出含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框或錯碼。產生／覆寫的 `entrypoint.sh`、`Dockerfile`、`action.yml`、`README.md` 同樣需 UTF-8（不含 BOM）。
|
||||||
|
- **自動執行原則**：除非使用者明確要求先確認，或遇到不可忽略的必要決策，否則各階段只需輸出簡短計畫／進度後直接執行到完成。**一定會中斷詢問的點**：階段 B 主程式「非 Node 需改寫」時（破壞性，須先確認），以及階段 E 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
|
||||||
|
- **不破壞既有工作**：移動 `.js`、改寫主程式、覆寫 `entrypoint.sh`／`Dockerfile`／`action.yml` 前，若工作區有未提交變更，先提醒使用者建議先 commit／備份；**絕不** `reset --hard`／`checkout -f`／`clean`，也不刪除使用者既有原始碼。移動檔案優先用 `git mv` 以保留歷史。
|
||||||
|
- **保留行為**：Node 化只「翻譯」既有邏輯，不得擅自改變對外行為、輸入輸出契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。
|
||||||
|
- **不擴及無關檔案**：本 skill 只動 action 專案根目錄內的：主程式、`.js`（搬移到 `src/`）、`package.json`、`action.yml`／`action.yaml`、`entrypoint.sh`、`Dockerfile`，以及階段 E 由 doc-funcs 流程處理的目標；排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 參數
|
||||||
|
|
||||||
|
格式：`[--action-dir <action 根目錄>] [--node-version <node tag>] [--main <主程式檔>] [--yes]`
|
||||||
|
|
||||||
|
- `--action-dir <action 根目錄>`：action 專案根目錄。**省略時預設目前工作目錄**（須含 `action.yml`／`action.yaml`，否則依 A1 詢問）。
|
||||||
|
- `--node-version <node tag>`：`Dockerfile` 的 node base image tag（如 `22`、`22-alpine`、`lts`）。**省略時預設使用最新 node 版本**（`node:latest`，見階段 D）。
|
||||||
|
- `--main <主程式檔>`：指定主程式入口檔（相對 action 根目錄）。省略時依 A3 自動判斷。
|
||||||
|
- `--yes`：盡量不中斷。即使帶此參數，「主程式非 Node 需改寫」與 doc-funcs 的「如何實作」仍會詢問。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 A：前置設定與偵測
|
||||||
|
|
||||||
|
### A1. 決定 action 根目錄
|
||||||
|
|
||||||
|
- 帶 `--action-dir` → 採用（展開 `~`）。
|
||||||
|
- 省略 → 用目前工作目錄。
|
||||||
|
- 根目錄須存在 `action.yml` 或 `action.yaml`（action manifest）。**找不到** action manifest → 回報「此目錄不是 action 專案（缺 action.yml／action.yaml）」並詢問正確路徑，**不臆測**、不在非 action 專案上動工。
|
||||||
|
|
||||||
|
### A2. 讀取 action 名稱與用途
|
||||||
|
|
||||||
|
從 action manifest 讀取：
|
||||||
|
|
||||||
|
- `name`：action 名稱（供 `entrypoint.sh` 輸出與 README 使用）。
|
||||||
|
- `description`：action 用途。
|
||||||
|
- `runs`：目前的執行設定（`using`、`main`、`image`、`entrypoint` 等）。
|
||||||
|
|
||||||
|
若 `name`／`description` 缺漏，回報並請使用者補；無法取得時於後續輸出以「（未提供）」保守標示，**不編造**。
|
||||||
|
|
||||||
|
### A3. 判斷目前主程式與語言
|
||||||
|
|
||||||
|
依序判斷主程式入口（取第一個成立者）：
|
||||||
|
|
||||||
|
1. 帶 `--main <主程式檔>` → 直接採用。
|
||||||
|
2. `action.yml` 為 JS action（`runs.using: node*`）→ 取 `runs.main`。
|
||||||
|
3. `action.yml` 為 docker action（`runs.using: docker`）→ 看 `runs.entrypoint`／`Dockerfile` 的 `ENTRYPOINT`／`CMD` 推主程式。
|
||||||
|
4. 以上皆無 → 依專案檔與副檔名分布推斷（`package.json` 的 `main`／`bin`、`index.js`、`*.sh`、`*.py` 等）。
|
||||||
|
|
||||||
|
判定**主程式是否為 Node**：入口為 `.js`／`.mjs`／`.cjs` 且由 `node` 執行即視為 Node；入口為 shell／python／其他則視為非 Node。輸出偵測結果（action 名稱、用途、主程式檔、判定語言、是否為 Node），再進入階段 B。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 B：主程式 Node 化，並將所有 `.js` 收進 `src/`
|
||||||
|
|
||||||
|
### B1. 主程式 Node 化
|
||||||
|
|
||||||
|
- **已是 Node** → 確認入口檔，不改寫邏輯，直接進 B2。
|
||||||
|
- **非 Node（shell／python／其他）** → 這是**破壞性高風險決策**：先以 `AskUserQuestion` 向使用者確認是否改寫為 Node，選項至少含「改寫為 Node」「維持原樣只做容器化（略過改寫）」「其他」。經確認後才改寫：
|
||||||
|
- 逐段把原主程式邏輯**保守翻譯**為 Node（建議 `index.js`）；保留對外行為、輸入（環境變數／`INPUT_*`／args）與輸出（stdout／exit code／檔案副作用）契約。
|
||||||
|
- 外部指令呼叫以 `child_process`（`execFileSync`／`spawnSync`）對應；檔案操作以 `fs`；環境變數以 `process.env`。
|
||||||
|
- 任何無法可靠等價翻譯處，**不臆測**：以 `// 需人工確認：...` 標註並回報。
|
||||||
|
- 改寫完成後，原非 Node 主程式於 B2 一併處理（移除或保留由使用者裁示；預設保留並在 README／回報標註已由 Node 取代）。
|
||||||
|
|
||||||
|
### B2. 所有 `.js` 集中到 `src/`
|
||||||
|
|
||||||
|
- 在 action 根目錄建立 `src/`（若不存在）。
|
||||||
|
- 將專案內所有 `.js`／`.mjs`／`.cjs`（排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴）**移入 `src/`**，優先 `git mv` 保留歷史。主程式入口統一為 `src/index.js`（或 `src/<main>.js`）。
|
||||||
|
- **移動後必須更新所有引用**，確保不破壞：
|
||||||
|
- 模組間的 `require`／`import` 相對路徑。
|
||||||
|
- `package.json` 的 `main`／`bin`／`scripts`／`exports`（指向 `src/...`）。
|
||||||
|
- `action.yml`／`Dockerfile`／`entrypoint.sh` 內對主程式路徑的引用。
|
||||||
|
- 若 `src/` 下無 `package.json` 而專案需要相依，於 `src/` 建立或移入 `package.json`，`main` 指向入口檔；不擅自新增與功能無關的相依。
|
||||||
|
|
||||||
|
### B3. action.yml 對齊 docker
|
||||||
|
|
||||||
|
將 manifest 的 `runs` 對齊為 docker 容器 action（保留既有 `inputs`／`outputs`／`name`／`description`）：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
runs:
|
||||||
|
using: docker
|
||||||
|
image: Dockerfile
|
||||||
|
entrypoint: entrypoint.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
若原本是 JS action（`using: node*`），改為上述 docker 設定；若已是 docker action，確認 `image` 指向 `Dockerfile`、`entrypoint` 指向 `entrypoint.sh`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 C：產生 entrypoint.sh（先輸出名稱／用途／更新時間，再啟動 node 主程式）
|
||||||
|
|
||||||
|
在 action 根目錄產生（或覆寫）`entrypoint.sh`：**啟動 node 主程式前，先輸出 action 名稱、用途、更新時間**。
|
||||||
|
|
||||||
|
- **更新時間**為產生此檔當下的時間戳，使用台灣時區（Asia/Taipei）並固定為 `yyyy/MM/dd HH:mm:ss`（可用 `TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'` 取得），**寫成檔內固定字串**（非執行期動態時間）。
|
||||||
|
- 名稱／用途取自階段 A2 的 `action.yml`。
|
||||||
|
- 最後以 `exec node <主程式>`（如 `exec node /action/src/index.js "$@"`）啟動，讓 node 取代 shell 行程，正確傳遞訊號與 exit code；路徑須與階段 D 的 `Dockerfile` 落點一致。
|
||||||
|
|
||||||
|
範例（實際路徑依階段 B 入口而定）：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
#!/bin/sh
|
||||||
|
set -e
|
||||||
|
|
||||||
|
# action 啟動橫幅：輸出名稱／用途／更新時間（此檔由 code-action-docker 產生）
|
||||||
|
echo "================================================"
|
||||||
|
echo "Action : <action name>"
|
||||||
|
echo "用途 : <action description>"
|
||||||
|
echo "更新時間: 2026/06/30 18:30:05"
|
||||||
|
echo "================================================"
|
||||||
|
|
||||||
|
# 啟動 node 主程式（以 exec 取代 shell，正確處理訊號與 exit code）
|
||||||
|
exec node /action/src/index.js "$@"
|
||||||
|
```
|
||||||
|
|
||||||
|
- 賦予可執行權限：`chmod +x entrypoint.sh`（並於 git 標記為可執行）。
|
||||||
|
- 此檔開頭的「用途／更新時間」與每行註解，最終會在階段 E 由 `/jsc:doc-funcs` 的指令檔流程統一補齊／覆寫為標準格式（用途與更新日期同一註解區塊、逐行註解）；本階段先確保**執行期輸出**正確即可。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 D：產生 Dockerfile（使用最新 node 版本，六步流程依主程式實作量身產生）
|
||||||
|
|
||||||
|
在 action 根目錄產生（或覆寫）`Dockerfile`，**base image 使用最新 node 版本**，採**多階段建置**以縮小最終映像檔。六步流程是**骨架**，但**每一步的實際內容必須依階段 B 的主程式（`src/`）實作決定**——不要套用與主程式無關的固定樣板，也不要硬塞主程式用不到的安裝或建置指令。
|
||||||
|
|
||||||
|
### D0. 先盤點主程式實作需求
|
||||||
|
|
||||||
|
產生 Dockerfile 前，先檢視 `src/` 主程式與 `package.json`，判斷各步該放什麼：
|
||||||
|
|
||||||
|
- **相依套件**：`src/package.json` 的 `dependencies`／`devDependencies`、是否有 lockfile（`package-lock.json`／`npm-shrinkwrap.json`）。決定第 2 步用 `npm ci` 還是 `npm install`、是否需要 dev 相依來 build。
|
||||||
|
- **是否需要 build／transpile**：有無 `scripts.build`、是否為 TypeScript／打包（產物落在 `dist/`／`build/` 等）。決定第 4 步是否要跑建置、第 5 步 runtime 該帶入哪個產物目錄。
|
||||||
|
- **OS 層相依**：主程式是否以 `child_process` 呼叫外部執行檔（如 `git`、`bash`、`openssl`、`python3`、`ffmpeg`、`imagemagick`），或使用需編譯的原生模組（node-gyp／native addon）。決定第 2 步是否要 `apt-get install` 對應套件，以及第 5 步 runtime 基底是否需保留這些執行檔。
|
||||||
|
- **執行期需求**：主程式讀取的環境變數、需存取的檔案路徑、是否寫入暫存目錄。決定 `WORKDIR`、需 `COPY` 的檔案範圍與必要的 `ENV`。
|
||||||
|
- **入口檔**：階段 B 決定的主程式入口（如 `src/index.js`），決定第 6 步與 `entrypoint.sh` 內 `node` 路徑。
|
||||||
|
|
||||||
|
### D1～D6：依盤點結果填入六步
|
||||||
|
|
||||||
|
1. **參數處理**：以 `ARG` 注入 node 版本（預設最新）與主程式需要的 build-time 參數；可調參數集中在檔案開頭。
|
||||||
|
2. **安裝套件**：依 D0 的相依結果安裝——有 lockfile 用 `npm ci`、否則 `npm install`；不需 build 時加 `--omit=dev`，需 build 時先裝完整相依（含 dev）供第 4 步使用。**只在主程式真的會用到時**才 `apt-get install` OS 套件，並於同一 `RUN` 清掉 apt 快取。先 `COPY` 相依描述（`package*.json`）再安裝，以利 layer 快取。
|
||||||
|
3. **複製檔案**：`COPY` 主程式實際需要的檔案（`src/`、`entrypoint.sh`，及主程式會讀取的資源）；不需要的檔案不必帶入。
|
||||||
|
4. **執行程序**：賦予 `entrypoint.sh` 執行權限；**僅當 D0 判定需要 build／transpile 時**才執行（如 `npm run build`），否則此步只做權限設定，不要硬加建置指令。
|
||||||
|
5. **縮小映像檔**：多階段建置，runtime 改用 slim 基底，只 `COPY --from=build` 帶入主程式執行**真正需要**的產物——有 build 產物時帶入 `dist/` 與 production `node_modules`（`npm prune --omit=dev` 或重裝 production 相依），純 JS 無 build 時帶入 `src/` 與 production `node_modules`；若 D0 判定 runtime 需要某些 OS 執行檔，於 runtime 階段一併安裝（slim 基底可能不含）。不要把 build 階段的 dev 相依與快取帶進最終映像。
|
||||||
|
6. **設定入口**：`ENTRYPOINT` 指向 `entrypoint.sh`，其內 `node` 路徑為 D0 的入口檔。
|
||||||
|
|
||||||
|
base image 版本：預設 build 基底 `node:latest`、runtime 基底 `node:slim`（皆為最新版，slim 用於縮小）；帶 `--node-version <tag>`（如 `22`、`lts`）時改用 `node:<tag>` 與 `node:<tag>-slim`。若需確認當前最新穩定版號，可查詢 Docker Hub（`https://hub.docker.com/_/node`）後於 `FROM` 註記實際版本，但**預設行為是使用最新版**。
|
||||||
|
|
||||||
|
下列為**最簡基準骨架**（純 JS、無 build、無 OS 相依的情況）；實際內容須依 D0 盤點調整，第 4 步建置、第 2／5 步 OS 套件等視主程式需要增刪：
|
||||||
|
|
||||||
|
```Dockerfile
|
||||||
|
# syntax=docker/dockerfile:1
|
||||||
|
|
||||||
|
# 1. 參數處理：node 版本以 ARG 注入（預設最新版；--node-version 可覆寫）
|
||||||
|
ARG NODE_VERSION=latest
|
||||||
|
ARG NODE_RUNTIME=slim
|
||||||
|
|
||||||
|
# ---- build 階段：安裝相依、準備產物 ----
|
||||||
|
FROM node:${NODE_VERSION} AS build
|
||||||
|
WORKDIR /action
|
||||||
|
|
||||||
|
# 2. 安裝套件：先帶相依描述以利 layer 快取，再裝 src/ 相依
|
||||||
|
# （需 build 時改裝完整相依；需 OS 套件時於此 apt-get install 並清快取）
|
||||||
|
COPY src/package*.json /action/src/
|
||||||
|
RUN if [ -f /action/src/package.json ]; then \
|
||||||
|
cd /action/src && (npm ci --omit=dev || npm install --omit=dev); \
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 3. 複製檔案：複製主程式實際需要的檔案
|
||||||
|
COPY . /action
|
||||||
|
|
||||||
|
# 4. 執行程序：賦予 entrypoint 執行權限（D0 判定需要 build 時於此 npm run build）
|
||||||
|
RUN chmod +x /action/entrypoint.sh
|
||||||
|
|
||||||
|
# 5. 縮小映像檔：多階段建置，runtime 改用 slim 基底、只帶必要產物
|
||||||
|
# （有 build 產物時改帶 dist/ 與 production node_modules；runtime 需要的 OS 執行檔於此安裝）
|
||||||
|
FROM node:${NODE_RUNTIME} AS runtime
|
||||||
|
WORKDIR /action
|
||||||
|
COPY --from=build /action /action
|
||||||
|
|
||||||
|
# 6. 設定入口：以 entrypoint.sh 啟動（其內 node 指向 D0 的入口檔）
|
||||||
|
ENTRYPOINT ["/action/entrypoint.sh"]
|
||||||
|
```
|
||||||
|
|
||||||
|
- **依主程式實作**：上面只是基準骨架。若主程式是 TypeScript／需打包，第 4 步要加 `npm run build`、第 5 步只帶 `dist/` 與 production 相依；若主程式會 spawn 外部執行檔或用原生模組，第 2／5 步要補對應 OS 套件；用不到的步驟內容不要硬塞。
|
||||||
|
- **版號對齊**：runtime 的 slim 基底版號需與 build 基底一致。預設 `node:latest` ↔ `node:slim`；帶 `--node-version 22` 時設 `NODE_VERSION=22`、`NODE_RUNTIME=22-slim`。注意**沒有 `node:latest-slim` 這個 tag**，最新版 slim 一律用 `node:slim`，故以獨立的 `NODE_RUNTIME` 參數帶入、不要用 `${NODE_VERSION}-slim` 組裝。
|
||||||
|
- **自我檢查**：`entrypoint.sh` 的 `node <主程式>` 路徑（如 `/action/src/index.js`）需與 `Dockerfile` 的 `WORKDIR`／`COPY` 落點一致，避免容器啟動時找不到主程式。
|
||||||
|
- 此檔的用途／更新日期註解與逐行註解，同樣於階段 E 由 doc-funcs 指令檔流程統一補齊。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 E：完整執行 /jsc:doc-funcs 處理流程
|
||||||
|
|
||||||
|
容器化與 Node 化完成後，對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README：
|
||||||
|
|
||||||
|
- 以階段 A1 的 action 根目錄為目標，執行 `doc-funcs` skill 的完整流程（判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證）。
|
||||||
|
- doc-funcs 會涵蓋本次新增／變更的指令檔：`entrypoint.sh`（補齊「用途＋更新日期同一註解區塊」與逐行註解）、`Dockerfile`（逐行註解）；以及 `src/` 內 Node 主程式與各 function 的文件註解。
|
||||||
|
- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，本 skill 不代為決定。
|
||||||
|
- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
|
||||||
|
|
||||||
|
> 銜接方式：在本 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用本 skill 的 action 根目錄為目標專案。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 總結
|
||||||
|
|
||||||
|
各階段執行後輸出：
|
||||||
|
|
||||||
|
- **階段 A**：action 根目錄、action 名稱／用途、原主程式檔與語言、是否為 Node。
|
||||||
|
- **階段 B**：是否改寫主程式（及改寫摘要與「需人工確認」清單）、搬入 `src/` 的 `.js` 清單、已更新的引用（`package.json`／`action.yml`／路徑）。
|
||||||
|
- **階段 C／D**：`entrypoint.sh` 的輸出內容（名稱／用途／更新時間）與啟動的 node 主程式、`Dockerfile` 採用的 node 版本與 `ENTRYPOINT`。
|
||||||
|
- **階段 E**：doc-funcs 流程的處理結果（文件化的 function 與指令檔、重建的 README）。
|
||||||
|
- 列出本次新增／變更的檔案與其相對路徑，並提醒使用者於提交前確認 `entrypoint.sh` 有可執行權限、容器能正確啟動。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 呼叫方式
|
||||||
|
|
||||||
|
格式：`[--action-dir <action 根目錄>] [--node-version <node tag>] [--main <主程式檔>] [--yes]` — 全部可省略（根目錄預設目前工作目錄；node 版本預設最新；主程式自動判斷）。
|
||||||
|
|
||||||
|
| 助理 | 呼叫 |
|
||||||
|
| --- | --- |
|
||||||
|
| Claude Code / Antigravity | `/jsc:code-action-docker`，或 `/jsc:code-action-docker --action-dir ~/work/my-action --node-version 22` |
|
||||||
|
| Codex | `$code-action-docker`，或 `$code-action-docker --action-dir ~/work/my-action`，或用 `/skills` 選單 |
|
||||||
|
| OpenCode | 描述需求（如「把這個 action 主程式改成 node、所有 js 收進 src/，產生會先輸出 action 名稱／用途／更新時間再啟動 node 的 entrypoint.sh、用最新 node 版本的 Dockerfile，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |
|
||||||
@@ -0,0 +1,161 @@
|
|||||||
|
---
|
||||||
|
name: code-image
|
||||||
|
description: 把專案的 `Dockerfile` 整理成固定六步流程並串接文件化流程：(1) 找出專案根目錄與目標 `Dockerfile`、判斷語言／生態與既有建置方式；(2) 在保留建置行為的前提下，把 `Dockerfile` 重整為 **參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口** 六步流程（以多階段建置縮小最終映像，可調參數集中於檔首 `ARG`，相依描述先 `COPY` 以利 layer 快取）；(3) 最後完整執行 `/jsc:doc-funcs` 處理流程（function 文件、`Dockerfile` 等指令檔逐行註解、重建 README）。當使用者說整理／重構 Dockerfile、把 Dockerfile 排成參數處理→安裝→複製→執行→縮小→入口六步、優化映像檔分層／多階段建置、縮小 image，或提到 code-image 時觸發。不適用於：Gitea／GitHub action 容器化（用 code-action-docker）、composite action（用 code-action-composite）、或專案內沒有也不需要 Dockerfile 的情況。
|
||||||
|
argument-hint: "[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes]"
|
||||||
|
---
|
||||||
|
|
||||||
|
# code-image — Dockerfile 六步流程整理＋文件化
|
||||||
|
|
||||||
|
三階段 skill：先做**前置設定與偵測**（找出專案根目錄、定位目標 `Dockerfile`、判斷語言／生態與既有建置方式），再把 `Dockerfile` **重整為固定六步流程**（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，並以多階段建置縮小最終映像），最後**完整執行 `/jsc:doc-funcs` 處理流程**替整個專案補文件並重建 README。
|
||||||
|
|
||||||
|
| 階段 | 動作 |
|
||||||
|
| --- | --- |
|
||||||
|
| A. 前置設定與偵測 | 決定專案根目錄 → 定位目標 `Dockerfile`（找不到則詢問，不臆造）→ 讀現有指令、判斷語言／生態、既有 base image 與建置流程 |
|
||||||
|
| B. 整理 Dockerfile 為六步流程 | 在**保留建置行為**前提下，把指令重整／歸位為六步：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口；多階段建置縮小映像；行為不等價處標「需人工確認」並先確認 |
|
||||||
|
| C. 串接 doc-funcs | 對整個專案完整執行 `/jsc:doc-funcs` 流程（function 文件、`Dockerfile` 等指令檔逐行註解、重建 README） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 輸出規範（務必遵守）
|
||||||
|
|
||||||
|
- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、git／docker 指令、API 路徑、程式碼等技術標識保留原文，**不可**使用簡體字。
|
||||||
|
- **編碼無亂碼**：凡輸出含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框或錯碼。產生／覆寫的 `Dockerfile`、`README.md` 同樣需 UTF-8（不含 BOM）。
|
||||||
|
- **自動執行原則**：除非使用者明確要求先確認，或遇到不可忽略的必要決策，否則各階段只需輸出簡短計畫／進度後直接執行到完成。**一定會中斷詢問的點**：階段 B「重整無法可靠保證建置行為等價」時（破壞性，須先確認），以及階段 C 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
|
||||||
|
- **不破壞既有工作**：覆寫 `Dockerfile` 前，若工作區有未提交變更，先提醒使用者建議先 commit／備份；**絕不** `reset --hard`／`checkout -f`／`clean`，也不刪除使用者既有原始碼。
|
||||||
|
- **保留建置行為**：重整只「重新組織與分層」既有指令，不得擅自改變最終映像的內容、檔案落點、相依版本、暴露的 port、`ENV`、`ENTRYPOINT`／`CMD` 對外契約或建置副作用；任何無法可靠等價推論的調整一律不做，並以註解或回報標註「需人工確認」。多階段建置縮小映像時，runtime 階段必須帶齊執行所需的所有產物（執行檔、相依、靜態資源、`ENV`、暴露 port），不得遺漏導致容器無法啟動。
|
||||||
|
- **不擴及無關檔案**：本 skill 階段 A／B 只動目標 `Dockerfile`（及與其直接相關、為保留行為而必須同步的 `.dockerignore`）；其餘檔案僅在階段 C 由 doc-funcs 流程依其規範處理。排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 參數
|
||||||
|
|
||||||
|
格式：`[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes]`
|
||||||
|
|
||||||
|
- `--project-dir <專案根目錄>`：專案根目錄。**省略時預設目前工作目錄**。
|
||||||
|
- `--dockerfile <Dockerfile 路徑>`：指定要整理的 `Dockerfile`（相對專案根目錄）。省略時依 A2 自動定位；找到多個時詢問。
|
||||||
|
- `--yes`：盡量不中斷。即使帶此參數，「重整無法保證建置行為等價」與 doc-funcs 的「如何實作」仍會詢問。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 A：前置設定與偵測
|
||||||
|
|
||||||
|
### A1. 決定專案根目錄
|
||||||
|
|
||||||
|
- 帶 `--project-dir` → 採用（展開 `~`）。
|
||||||
|
- 省略 → 用目前工作目錄。
|
||||||
|
|
||||||
|
### A2. 定位目標 Dockerfile
|
||||||
|
|
||||||
|
- 帶 `--dockerfile` → 採用（相對專案根目錄；展開後須存在）。
|
||||||
|
- 省略 → 於專案根目錄與常見位置尋找 `Dockerfile`（含 `Dockerfile.*`、`*/Dockerfile`，排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴）。
|
||||||
|
- 恰好一個 → 直接採用。
|
||||||
|
- 多個 → 以 `AskUserQuestion` 列出讓使用者選擇要整理哪一個（或逐一整理）。
|
||||||
|
- **找不到** → 回報「專案內找不到 `Dockerfile`」並詢問正確路徑；**不臆造** Dockerfile、不在沒有 Dockerfile 的專案上憑空生成（本 skill 的職責是「整理既有 Dockerfile」，產生全新 action 容器請改用 `/jsc:code-action-docker`）。
|
||||||
|
|
||||||
|
### A3. 讀現有指令並判斷語言／生態與既有建置流程
|
||||||
|
|
||||||
|
讀取目標 `Dockerfile` 全文，盤點並記錄（作為階段 B 重整與 C doc-funcs 的依據）：
|
||||||
|
|
||||||
|
- **base image 與階段**：所有 `FROM`（含多階段 `AS <name>`）、目前是單階段或多階段。
|
||||||
|
- **可調參數**：既有 `ARG`／`ENV`（版本、路徑、build flag 等）。
|
||||||
|
- **安裝步驟**：OS 套件（`apt`／`apk`／`yum` 等）、語言相依（`npm ci`／`pip install`／`go mod download`／`dotnet restore`／`mvn`／`gradle` 等）、相依描述檔（`package*.json`／`requirements.txt`／`go.mod`／`*.csproj`／`pom.xml` 等）。
|
||||||
|
- **複製與建置**：`COPY`／`ADD` 來源與落點、`RUN` 建置／編譯／transpile（`npm run build`／`go build`／`dotnet publish`／`mvn package` 等）、`WORKDIR`、`USER`、檔案權限（`chmod`）。
|
||||||
|
- **執行設定**：`EXPOSE`、`ENV`、`VOLUME`、`HEALTHCHECK`、`ENTRYPOINT`／`CMD`（這些是對外契約，重整時不得改變語意）。
|
||||||
|
- **語言／生態**：依 base image 與安裝指令、專案檔分布推斷主要語言（供階段 C doc-funcs 第 0 步沿用，也決定縮小映像時的 runtime 基底選擇）。
|
||||||
|
|
||||||
|
輸出偵測結果（目標 Dockerfile 路徑、單／多階段、base image、推斷語言、既有 `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`），再進入階段 B。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 B：整理 Dockerfile 為六步流程
|
||||||
|
|
||||||
|
在**保留建置行為**的前提下，把目標 `Dockerfile` 的指令重整／歸位為**固定六步流程**，並採**多階段建置**縮小最終映像。各步驟對應如下：
|
||||||
|
|
||||||
|
1. **參數處理**：把可調參數集中到檔案開頭，以 `ARG` 注入（base image 版本、build flag、路徑等）；`# syntax` 指示與全域 `ARG` 置於最前。
|
||||||
|
2. **安裝套件**：先 `COPY` 相依描述檔（如 `package*.json`／`requirements.txt`／`go.mod go.sum`／`*.csproj`）再安裝，以利 layer 快取；OS 套件與語言相依在此安裝，安裝後清理快取（如 `apt-get clean`／`rm -rf /var/lib/apt/lists/*`、`--no-cache`）以縮小該層。
|
||||||
|
3. **複製檔案**：`COPY` 其餘原始碼到映像（搭配 `.dockerignore` 排除無關檔案）。
|
||||||
|
4. **執行程序**：build／compile／transpile（如 `npm run build`／`go build`／`dotnet publish`）與必要的權限設定（`chmod`）於此執行。
|
||||||
|
5. **縮小映像檔**：多階段建置，runtime 階段改用較小的基底（如 `*-slim`／`*-alpine`／`distroless`／`scratch`，依語言與既有 base 對應），只 `COPY --from=<build>` 帶入**執行所必需**的產物（執行檔／發佈輸出／必要相依／靜態資源），避免把 build 階段的快取、原始碼與 dev 工具帶進最終映像；同步搬移 runtime 階段需要的 `ENV`／`WORKDIR`／`EXPOSE`／`USER`。
|
||||||
|
6. **設定入口**：`ENTRYPOINT`／`CMD` 置於最後，語意與原檔一致。
|
||||||
|
|
||||||
|
**重整原則（關鍵）**
|
||||||
|
|
||||||
|
- **語意等價優先**：重排指令前，先確認該調整不改變最終映像內容與建置結果。某些重排會改變行為（例如 `ARG` 的作用範圍跨 `FROM` 會失效、`COPY` 順序影響快取與覆蓋、`RUN` 之間有狀態相依、單階段改多階段時 runtime 缺少 build 期才有的檔案）。**凡無法可靠保證等價的重整，先以 `AskUserQuestion` 向使用者確認**（選項至少含「依建議重整（多階段＋六步）」「只在不改變行為前提下做最小重排」「維持原結構只補註解（略過重整，交給階段 C）」「其他」），確認後才覆寫。
|
||||||
|
- **已是多階段** → 將既有各階段對應到六步（build 階段涵蓋 1–4、runtime 階段涵蓋 5–6），補齊缺漏的快取最佳化與清理，不破壞既有 `--from` 依賴。
|
||||||
|
- **單階段改多階段** → 僅在能可靠判斷 runtime 真正需要哪些產物時才做；無法可靠判斷時，**不臆測**，標 `# 需人工確認：runtime 需要的產物清單` 並回報，退回「最小重排＋補註解」。
|
||||||
|
- **多階段不適用** → 若該映像本質上無法受益於多階段（例如純資料映像、最終就是要完整建置環境），保留單階段，於步驟 5 以註解說明「此映像不適用多階段縮小」，其餘步驟仍依序歸位。
|
||||||
|
- **對外契約不動**：`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`／`VOLUME`／`HEALTHCHECK`／`USER` 的語意保持與原檔一致；只可調整位置與分層，不可改變值或刪除。
|
||||||
|
- **`.dockerignore`**：若為了「複製檔案」步驟的正確性需要排除建置產物／`node_modules`／`.git`，可建立或補強 `.dockerignore`（僅新增排除項，不刪既有），並回報。
|
||||||
|
|
||||||
|
重整骨架（實際指令、base image、語言依階段 A 偵測結果填入；非 Node 專案請換成對應語言的安裝／建置指令與 runtime 基底）：
|
||||||
|
|
||||||
|
```Dockerfile
|
||||||
|
# syntax=docker/dockerfile:1
|
||||||
|
|
||||||
|
# 1. 參數處理：可調參數集中於檔首，以 ARG 注入
|
||||||
|
ARG BUILD_IMAGE=<build-base>
|
||||||
|
ARG RUNTIME_IMAGE=<runtime-base-slim>
|
||||||
|
|
||||||
|
# ---- build 階段：安裝相依、複製原始碼、建置產物 ----
|
||||||
|
FROM ${BUILD_IMAGE} AS build
|
||||||
|
WORKDIR /app
|
||||||
|
|
||||||
|
# 2. 安裝套件：先帶相依描述以利 layer 快取，再安裝（並清理快取縮小該層）
|
||||||
|
COPY <dependency-manifests> ./
|
||||||
|
RUN <install-deps>
|
||||||
|
|
||||||
|
# 3. 複製檔案：複製其餘原始碼（搭配 .dockerignore）
|
||||||
|
COPY . .
|
||||||
|
|
||||||
|
# 4. 執行程序：build / compile / transpile、必要權限設定
|
||||||
|
RUN <build-command>
|
||||||
|
|
||||||
|
# ---- 5. 縮小映像檔：runtime 改用較小基底，只帶執行所需產物 ----
|
||||||
|
FROM ${RUNTIME_IMAGE} AS runtime
|
||||||
|
WORKDIR /app
|
||||||
|
COPY --from=build /app/<artifacts> ./<artifacts>
|
||||||
|
# （搬移 runtime 需要的 ENV / EXPOSE / USER，語意與原檔一致）
|
||||||
|
|
||||||
|
# 6. 設定入口：ENTRYPOINT / CMD 置於最後，語意同原檔
|
||||||
|
ENTRYPOINT [<entrypoint>]
|
||||||
|
```
|
||||||
|
|
||||||
|
- **自我檢查**：重整後確認 (1) `ARG` 在使用它的 `FROM` 之後有重新宣告（跨階段 `ARG` 規則）；(2) runtime 階段 `COPY --from` 帶齊執行所需全部產物；(3) `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV` 與原檔語意一致；(4) 路徑（`WORKDIR`／`COPY` 落點）一致、容器能找到入口。
|
||||||
|
- 此檔的「用途／更新日期」開頭註解區塊與逐行註解，於階段 C 由 `/jsc:doc-funcs` 的指令檔流程統一補齊／覆寫為標準格式；本階段先確保**建置行為**正確、六步結構清楚即可。
|
||||||
|
- **建置驗證**：若環境可執行 `docker build`，重整後做一次建置驗證（或至少 `docker build --check`／語法檢查）確認可建置；無法執行時明確說明原因並標註風險（階段 C doc-funcs 第 11 步亦會做語法驗證）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 C：完整執行 /jsc:doc-funcs 處理流程
|
||||||
|
|
||||||
|
Dockerfile 六步整理完成後，對**整個專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README：
|
||||||
|
|
||||||
|
- 以階段 A1 的專案根目錄為目標，執行 `doc-funcs` skill 的完整流程（判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證）。
|
||||||
|
- doc-funcs 會把本次整理的 `Dockerfile` 視為部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解（每行有效指令上方或行尾說明其作用、為何需要、重要參數或副作用）；專案內各 function 補文件註解；其他指令檔（腳本／CI／`docker-compose*` 等）一併處理。
|
||||||
|
- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，本 skill 不代為決定。
|
||||||
|
- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
|
||||||
|
|
||||||
|
> 銜接方式：在本 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用本 skill 的專案根目錄為目標專案。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 總結
|
||||||
|
|
||||||
|
各階段執行後輸出：
|
||||||
|
|
||||||
|
- **階段 A**：專案根目錄、目標 `Dockerfile` 路徑、單／多階段、base image、推斷語言、既有 `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`。
|
||||||
|
- **階段 B**：重整摘要（六步歸位結果、是否改為多階段、縮小映像採用的 runtime 基底）、「需人工確認」清單、是否做過建置／語法驗證；並確認對外契約（`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV` 等）未被破壞。
|
||||||
|
- **階段 C**：doc-funcs 流程的處理結果（文件化的 function 與指令檔、重建的 README）。
|
||||||
|
- 列出本次新增／變更的檔案與其相對路徑，並提醒使用者於提交前確認 `Dockerfile` 可正確建置、容器能正常啟動。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 呼叫方式
|
||||||
|
|
||||||
|
格式：`[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes]` — 全部可省略（專案根目錄預設目前工作目錄；Dockerfile 自動定位，多個時詢問）。
|
||||||
|
|
||||||
|
| 助理 | 呼叫 |
|
||||||
|
| --- | --- |
|
||||||
|
| Claude Code / Antigravity | `/jsc:code-image`，或 `/jsc:code-image --project-dir ~/work/my-app --dockerfile build/Dockerfile` |
|
||||||
|
| Codex | `$code-image`，或 `$code-image --dockerfile docker/Dockerfile`，或用 `/skills` 選單 |
|
||||||
|
| OpenCode | 描述需求（如「把這個專案的 Dockerfile 整理成參數處理→安裝套件→複製檔案→執行程序→縮小映像檔→設定入口六步、用多階段建置縮小映像，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |
|
||||||
@@ -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 依影響範圍小到大排序、缺的補進議題描述，然後逐項實作、每完成一項留言進度」）自動觸發 |
|
||||||
@@ -0,0 +1,156 @@
|
|||||||
|
---
|
||||||
|
name: code-nuget
|
||||||
|
description: 將 C# / .NET 專案的 NuGet 套件更新到最新可用版本。當使用者要求更新 NuGet、升級 PackageReference、清理重複套件參考、檢查專案參考中的重複 NuGet、或逐包更新並確認 build 時觸發。流程會依專案分組列出套件，檢查 ProjectReference 上層專案是否已引用相同套件並移除可安全移除的重複參考，接著逐一更新套件版本；每更新或移除一個套件都必須 restore/build 驗證。若更新到最新版本後編譯失敗，改由目前版本之後的最小可用版本逐版升級，直到遇到第一個編譯失敗版本，保留最後一個可編譯版本。不適用於：非 .NET 專案、只想查詢套件清單不更新、或只要人工建議不修改檔案。
|
||||||
|
argument-hint: "[<solution-or-project>] [--include-prerelease] [--no-dedupe] [--build <command>] [--yes]"
|
||||||
|
---
|
||||||
|
|
||||||
|
# code-nuget — 更新 C# 專案 NuGet 套件
|
||||||
|
|
||||||
|
把 C# / .NET repo 內的 NuGet 套件依專案盤點、清理可安全移除的重複參考，然後逐一更新到最新可用版本。每個套件異動後都要驗證專案可以正常編譯；若最新版本失敗，改從目前版本之後的最小可用版本逐版升級，直到第一個編譯失敗版本為止，保留最後一個可編譯版本並記錄失敗點。
|
||||||
|
|
||||||
|
## 輸出規範
|
||||||
|
|
||||||
|
- 所有面向使用者的輸出一律使用繁體中文（台灣用語）；套件 id、檔名、指令、版本號保留原文。
|
||||||
|
- 修改前先輸出簡短執行計畫；除非使用者要求確認、遇到多個 solution 無法判斷、或編譯失敗需要取捨，否則依計畫執行。
|
||||||
|
- 每個套件都要留下結果：已更新 / 已降階到可編譯版本 / 已略過 / 已回復 / 已移除重複參考，以及對應版本與驗證指令。
|
||||||
|
- 不主動 commit、push 或開 PR；使用者明確要求時才做。
|
||||||
|
- **遇到 `JSC` 開頭的套件（套件 id 前綴為 `JSC`）時，必須先通知使用者並詢問是否要繼續處理該套件，取得明確同意後才可動作（更新版本或移除重複參考）。此確認為強制項，不得被 `--yes` 略過。使用者若拒絕，將該套件記為「已略過（JSC 套件，使用者未同意）」並繼續處理其他套件。**
|
||||||
|
|
||||||
|
## 參數
|
||||||
|
|
||||||
|
`[<solution-or-project>] [--include-prerelease] [--no-dedupe] [--build <command>] [--yes]`
|
||||||
|
|
||||||
|
- `<solution-or-project>`：`.sln`、`.slnx` 或 `.csproj` 路徑。省略時自動搜尋；若找到多個 solution 且無法判斷主專案，必須詢問。
|
||||||
|
- `--include-prerelease`：更新時允許 prerelease 版本；未指定時只更新 stable 版本。
|
||||||
|
- `--no-dedupe`：略過 ProjectReference 重複 PackageReference 清理，只更新版本。
|
||||||
|
- `--build <command>`：覆寫驗證指令，例如 `dotnet build My.sln -c Release`。未指定時用 `dotnet build <solution-or-project> --no-restore`。
|
||||||
|
- `--yes`：可略過一般確認，但仍不可忽略多 solution 選擇、無法安全清理重複參考、編譯失敗的必要決策、或 `JSC` 開頭套件的繼續確認。
|
||||||
|
|
||||||
|
## 執行流程
|
||||||
|
|
||||||
|
### 1. 探測專案與工具
|
||||||
|
|
||||||
|
1. 確認目前在 repo 根目錄或可找到 git root。
|
||||||
|
2. 檢查工具：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet --info
|
||||||
|
dotnet --list-sdks
|
||||||
|
```
|
||||||
|
|
||||||
|
3. 找出目標：
|
||||||
|
- 參數有指定 `.sln` / `.slnx` / `.csproj` → 使用該路徑。
|
||||||
|
- 未指定 → 依序搜尋 `.slnx`、`.sln`、`.csproj`。
|
||||||
|
- 多個 solution 且無明顯唯一主檔 → 詢問使用者選擇，不可猜測。
|
||||||
|
4. 先執行 baseline 驗證：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet restore <目標>
|
||||||
|
dotnet build <目標> --no-restore
|
||||||
|
```
|
||||||
|
|
||||||
|
baseline build 失敗時停止，回報現況；不要在不可編譯的基準上升級套件。
|
||||||
|
|
||||||
|
### 2. 依專案分組列出 NuGet 套件
|
||||||
|
|
||||||
|
1. 找出目標涵蓋的所有 `.csproj`：
|
||||||
|
- solution：可用 `dotnet sln <solution> list`，必要時解析輸出中的 `.csproj`。
|
||||||
|
- 單一 project：只處理該 project 與其 ProjectReference 圖。
|
||||||
|
2. 對每個專案列出 direct 套件：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet list <project.csproj> package --outdated
|
||||||
|
dotnet list <project.csproj> package --include-transitive
|
||||||
|
```
|
||||||
|
|
||||||
|
3. 讀取 `.csproj`、`Directory.Packages.props`、`Directory.Build.props`，判斷是否使用 Central Package Management（`ManagePackageVersionsCentrally` / `PackageVersion`）。
|
||||||
|
4. 產出「依專案分組」清單：
|
||||||
|
|
||||||
|
| 專案 | 套件 | 目前版本 | 最新版本 | 參考來源 | 備註 |
|
||||||
|
| --- | --- | --- | --- | --- | --- |
|
||||||
|
|
||||||
|
`參考來源` 標註 `PackageReference`、`Directory.Packages.props`、`transitive` 或 `ProjectReference`。
|
||||||
|
|
||||||
|
### 3. 檢查 ProjectReference 重複套件
|
||||||
|
|
||||||
|
> 這裡的「上層專案」指目前專案透過 `ProjectReference` 直接或間接參考到的專案；若該被參考專案已 direct reference 同一個 NuGet 套件，且該套件會透過專案參考傳遞，當前專案通常不需要重複 direct reference。
|
||||||
|
|
||||||
|
1. 建立 ProjectReference graph：
|
||||||
|
- 讀每個 `.csproj` 的 `<ProjectReference Include="...">`。
|
||||||
|
- 正規化路徑，建立「目前專案 → 被參考專案」的 direct / transitive 關係。
|
||||||
|
2. 比對 direct PackageReference：
|
||||||
|
- 若目前專案與其 direct/transitive ProjectReference 上層專案有相同套件 id，列為重複候選。
|
||||||
|
- 若目前專案的套件參考含 `PrivateAssets="all"`、`IncludeAssets` / `ExcludeAssets` 特殊設定、analyzers/build/source generators、或版本刻意高於上層專案，先列為「需人工確認」，不要自動移除。
|
||||||
|
- 若上層專案的參考含 `PrivateAssets="all"` 或不會傳遞必要 assets，不可視為可替代。
|
||||||
|
3. 對可安全移除的重複 direct reference 逐一處理：
|
||||||
|
- **若該套件 id 為 `JSC` 開頭，先通知使用者並詢問是否繼續移除，取得同意才處理；未同意則記為「已略過（JSC 套件，使用者未同意）」。此確認不得被 `--yes` 略過。**
|
||||||
|
- 先記錄目前檔案狀態與套件版本。
|
||||||
|
- 移除當前專案的重複 `PackageReference`；若使用 Central Package Management，只有在沒有任何專案仍需要該 `PackageVersion` 時才移除中央版本項。
|
||||||
|
- 執行：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet restore <目標>
|
||||||
|
dotnet build <目標> --no-restore
|
||||||
|
```
|
||||||
|
|
||||||
|
- build 成功 → 保留移除。
|
||||||
|
- build 失敗 → 回復該移除，重新 restore/build 確認回復後可編譯，並記錄失敗原因。
|
||||||
|
|
||||||
|
### 4. 逐一更新套件版本
|
||||||
|
|
||||||
|
1. 排除不應更新的項目：
|
||||||
|
- transitive-only 套件不直接更新；更新提供它的 direct 套件。
|
||||||
|
- 明確 pin 住版本且註解或 props 顯示有相容性原因者，先列入「需人工確認」。
|
||||||
|
- `PrivateAssets="all"` 的 analyzer / generator / build tooling 可更新，但要特別注意 build 驗證結果。
|
||||||
|
- **`JSC` 開頭的套件：在更新版本前，必須先通知使用者「即將處理 JSC 套件 `<PackageId>`」並詢問是否繼續，取得同意才更新；未同意則記為「已略過（JSC 套件，使用者未同意）」。此確認不得被 `--yes` 略過。**
|
||||||
|
2. 逐一更新 direct 套件：
|
||||||
|
- 一次只更新一個套件 id。
|
||||||
|
- 若多個專案引用同一套件，先判斷是否使用 Central Package Management：
|
||||||
|
- CPM：更新對應 `Directory.Packages.props` 的單一 `PackageVersion`。
|
||||||
|
- 非 CPM：依專案逐一更新該套件。
|
||||||
|
- 優先使用 `dotnet add <project> package <PackageId>` 讓 NuGet 選擇最新相容 stable 版本；若 `dotnet list package --outdated` 已提供最新版本，也可用 `--version <latest>` 明確更新。
|
||||||
|
- 指定 `--include-prerelease` 時，查詢與更新都允許 prerelease；未指定時不得升到 prerelease。
|
||||||
|
3. 每更新一個套件後立即驗證：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet restore <目標>
|
||||||
|
dotnet build <目標> --no-restore
|
||||||
|
```
|
||||||
|
|
||||||
|
若使用者提供 `--build <command>`，以該命令取代 build 步驟，但 restore 仍需執行。
|
||||||
|
4. 驗證結果：
|
||||||
|
- 成功：記錄 `PackageId oldVersion -> newVersion`，保留變更。
|
||||||
|
- 最新版本失敗：先回復最新版本異動與 lock file 變更，確認回到可編譯狀態；接著查詢該套件「目前版本之後、最新版本之前或等於最新版本」的所有可用版本，由最低版本開始逐一升級並每版 restore/build。遇到成功就暫時保留並繼續下一版；遇到第一個失敗版本就停止此套件升級、回復到上一個成功版本，記錄為「已降階到可編譯版本」。如果第一個候選版本就失敗，回復到原版本並記錄為「已回復」。
|
||||||
|
- 查詢可用版本時優先使用目前專案既有 feed 設定（`nuget.config`）；可用 `dotnet package search`、`nuget list`、NuGet v3 API 或專案環境可用的等價工具。不得改用未設定的公開 feed 造成私有套件版本判斷錯誤。
|
||||||
|
- 因相依套件版本衝突導致失敗：可嘗試更新同一 dependency chain 中的必要 direct 套件，但仍必須一次一包、每包驗證。
|
||||||
|
|
||||||
|
### 5. 特殊檔案與版本管理
|
||||||
|
|
||||||
|
- `packages.lock.json` 存在時，更新套件後允許 lock file 跟著變更；回復失敗更新時也要回復 lock file。
|
||||||
|
- `nuget.config` 有私有 feed 時，不輸出 credential；錯誤訊息若含 token / password 必須遮蔽。
|
||||||
|
- `packages.config` 專案不套用 `dotnet add package` 流程；先回報這是舊格式，使用 `nuget.exe update` 或請使用者確認遷移策略。
|
||||||
|
- 多 target framework 專案以完整目標 build 為準，不只 build 單一 framework。
|
||||||
|
|
||||||
|
### 6. 最終總結
|
||||||
|
|
||||||
|
完成後輸出：
|
||||||
|
|
||||||
|
| 類別 | 套件 / 專案 | 結果 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
|
||||||
|
至少包含：
|
||||||
|
|
||||||
|
- 重複 PackageReference：移除幾筆、回復幾筆、需人工確認幾筆。
|
||||||
|
- NuGet 更新：成功幾筆、已是最新幾筆、降階到可編譯版本幾筆、回復幾筆、略過幾筆。
|
||||||
|
- 最後一次成功驗證的指令。
|
||||||
|
- 尚待人工處理的套件與原因。
|
||||||
|
|
||||||
|
若所有變更後最終 build 成功，明確寫「最終編譯驗證成功」。若有套件因最新版本失敗而降階或回復，說明目前工作區保留的是已通過 build 的變更集合，並列出失敗版本與最後成功版本。
|
||||||
|
|
||||||
|
## 呼叫方式
|
||||||
|
|
||||||
|
| 助理 | 呼叫 |
|
||||||
|
| --- | --- |
|
||||||
|
| Claude Code / Antigravity | `/jsc:code-nuget`，或 `/jsc:code-nuget MySolution.sln --include-prerelease` |
|
||||||
|
| Codex | `$code-nuget`，或 `$code-nuget src/App/App.csproj --build "dotnet build App.sln -c Release"` |
|
||||||
|
| OpenCode | 描述需求（如「把這個 .NET solution 的 NuGet 都更新到最新，先清掉 ProjectReference 已提供的重複套件，每更新一包就 build」）自動觸發 |
|
||||||
@@ -0,0 +1,176 @@
|
|||||||
|
---
|
||||||
|
name: code-review-archive
|
||||||
|
description: 將 /jsc:code-review 已裁決的問題保存到目標專案 —【✅ 成立】附加到「前次審查紀錄（已知問題）」檔、【❌ 誤判】附加到「排除事項」檔，讓 code-review 防守方下次自動標為 🔁 已知問題 / 🚫 略過。當使用者說保存／歸檔 code review 結果、把成立問題寫進已知問題、把誤判寫進排除事項、把 review 裁決落地到專案時觸發。只處理「已裁決」的列表（合併防守方裁決表與攻擊方問題表），不自己跑 review、不修改程式碼。缺裁決表時，請先用 /jsc:code-review 的防守方（paladin）產生裁決。
|
||||||
|
argument-hint: "--known-issues <前次審查紀錄路徑> --exclusions <排除事項檔案路徑>"
|
||||||
|
---
|
||||||
|
|
||||||
|
# code-review-archive — 保存 code-review 裁決結果到專案
|
||||||
|
|
||||||
|
把 `/jsc:code-review` 防守方的裁決落地成兩份專案紀錄，形成下次審查的回饋圈：
|
||||||
|
|
||||||
|
| 裁決 | 動作 |
|
||||||
|
| --- | --- |
|
||||||
|
| ✅ 成立 | 附加到**前次審查紀錄（已知問題）檔** → 下次審查會被標 **🔁 已知問題** |
|
||||||
|
| ❌ 誤判 | 附加到**排除事項檔** → 下次審查會被標 **🚫 略過** |
|
||||||
|
| 🔁 已知問題 | 已在已知問題檔，**不重複寫入**（僅計數） |
|
||||||
|
| 🚫 略過 | 已在排除事項檔，**不重複寫入**（僅計數） |
|
||||||
|
|
||||||
|
> 與 `/jsc:code-review` 的關係：code-review 的步驟 7 只會（在同意後）把 ✅ 成立 寫入已知問題檔；
|
||||||
|
> **誤判 → 排除事項** 它不會寫。本 skill 一次補齊兩個方向，且**只吃既有裁決結果**：不跑 review、不改程式碼。
|
||||||
|
|
||||||
|
## 輸出規範（務必遵守）
|
||||||
|
|
||||||
|
- **語言**：所有面向使用者的輸出與**寫入檔案的內容**一律使用**繁體中文（台灣用語）**；
|
||||||
|
僅檔名、程式碼識別字、`key`／JSON 欄位名等技術標識保留原文，不可使用簡體字。
|
||||||
|
- **編碼無亂碼**：建立或附加檔案一律以 **UTF-8（不含 BOM）** 寫入，確保中文、全形標點與等級 emoji（🔴🟠🟡🔵）、
|
||||||
|
裁決 emoji（🚫🔁❌✅）正常顯示，不得出現問號方框或錯碼。
|
||||||
|
|
||||||
|
## 參數（與 code-review 同名旗標，方便沿用同一組路徑）
|
||||||
|
|
||||||
|
`--known-issues <前次審查紀錄路徑>` `--exclusions <排除事項檔案路徑>` — **兩者皆必填，一定要指定**。
|
||||||
|
|
||||||
|
- **未提供任一路徑 → 必須先向使用者取得，不可自行採用預設或臆測**（與 code-review 一致：預設檔名僅作詢問時的建議選項）。
|
||||||
|
建議預設：已知問題 `known-issues.md`、排除事項 `exclusions.md`（與 code-review 防守方讀的同一檔）。
|
||||||
|
- **檔案本身允許不存在或為空內容**：若目標檔不存在、或內容為空（含只有空白）→ skill 先**依模板建立該檔**（見下方「模板」），再附加條目；既有非空檔則直接附加。
|
||||||
|
- 寫入屬於**更動專案檔案**的行為 → **未獲使用者同意前不可寫入**；拒絕則只輸出將寫入的預覽。
|
||||||
|
- **格式依副檔名自動決定**：`.md` → Markdown（用下方模板）；`.json` → top-level JSON array（空／不存在時初始化為 `[]`）。
|
||||||
|
|
||||||
|
## 執行流程
|
||||||
|
|
||||||
|
### 1. 取得問題表與裁決表（只吃既有結果）
|
||||||
|
|
||||||
|
來源優先序：本次對話中上一個 `/jsc:code-review` 的輸出；若無，請使用者貼上。
|
||||||
|
|
||||||
|
- **問題表**（攻擊方）：`問題 | 等級 | 描述 | 建議 | 檔案位置 | 所在行數`。
|
||||||
|
- **裁決表**（防守方）：`來源角色 | 原問題 | 裁決 | 理由 | 最終建議`，裁決 ∈ `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立`。
|
||||||
|
- **沒有裁決表** → 無法分類，**請先跑防守方**（`/jsc:code-review <target> <source> paladin`）或請使用者提供裁決表。
|
||||||
|
**只處理已裁決的列表**，不自行臆測成立或誤判。
|
||||||
|
|
||||||
|
### 2. 合併兩表
|
||||||
|
|
||||||
|
以 **`原問題` ↔ `問題`** 為鍵配對；同名問題以 **`來源角色` + `檔案位置`** 區分。
|
||||||
|
合併後每筆 = 等級／描述／建議／檔案位置／所在行數（問題表）＋ 裁決／理由／最終建議（裁決表）。
|
||||||
|
|
||||||
|
- **對不上的列**（裁決表有但問題表查無，或反之）→ 列出請使用者確認，**不臆測**、不寫入。
|
||||||
|
|
||||||
|
### 3. 補齊欄位
|
||||||
|
|
||||||
|
- **日期**：`YYYY-MM-DD`（可用 `date +%F`，或取來源分支最後 commit 日期）。
|
||||||
|
- **範圍／來源**：`<target>...<source>`（沿用本次 review 的分支；不確定就問或留白）。
|
||||||
|
|
||||||
|
### 4. 取得同意 → 去重 → 附加
|
||||||
|
|
||||||
|
1. 先輸出「將寫入」的預覽（各檔幾筆、條目摘要），**請使用者確認**後才動檔。
|
||||||
|
2. **去重鍵**：`<檔案位置>|<問題標題>`。寫入前先讀目標檔，**已存在相同鍵的條目 → 略過不重複附加**。
|
||||||
|
3. **目標檔不存在或為空（含只有空白）→ 先依「模板」建立**（`.md` 用下方模板；`.json` 初始化為 `[]`），再附加。
|
||||||
|
4. 分流：
|
||||||
|
- **✅ 成立** → 附加到**已知問題檔**（`--known-issues`）。
|
||||||
|
- **❌ 誤判** → 附加到**排除事項檔**（`--exclusions`）。
|
||||||
|
- **🔁 已知問題 / 🚫 略過** → 不處理（已存在），僅計數。
|
||||||
|
|
||||||
|
### 5. 回報摘要
|
||||||
|
|
||||||
|
列出：新增成立 N 筆、新增誤判 M 筆、已知問題（略過）K 筆、排除（略過）L 筆、重複而跳過 J 筆，以及實際寫入的檔案路徑。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 檔案格式
|
||||||
|
|
||||||
|
### Markdown（`.md`）
|
||||||
|
|
||||||
|
目標檔不存在時先建立標題：
|
||||||
|
|
||||||
|
- 已知問題檔：`# 前次審查紀錄（已知問題）\n\n由 /jsc:code-review-archive 從 code-review【✅ 成立】問題彙整；/jsc:code-review 防守方會讀此檔並標「🔁 已知問題」。`
|
||||||
|
- 排除事項檔（`exclusions.md`）：`# Code Review 排除事項\n\n已知技術債／團隊慣例／刻意取捨／已確認的誤判；/jsc:code-review 防守方會讀此檔並標「🚫 略過」。`
|
||||||
|
|
||||||
|
**已知問題** 每筆：
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
### [<等級>] <問題標題>
|
||||||
|
<!-- key: <檔案位置>|<問題標題> -->
|
||||||
|
- 檔案：`<檔案位置>:<所在行數>`
|
||||||
|
- 描述：<描述>
|
||||||
|
- 建議：<最終建議>
|
||||||
|
- 裁決：✅ 成立（<理由>）— 由 <來源角色> 提出
|
||||||
|
- 範圍：`<target>...<source>`，<日期>
|
||||||
|
```
|
||||||
|
|
||||||
|
**排除事項** 每筆：
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
### <問題標題>
|
||||||
|
<!-- key: <檔案位置>|<問題標題> -->
|
||||||
|
- 檔案：`<檔案位置>`
|
||||||
|
- 排除原因（❌ 誤判）：<裁決理由>
|
||||||
|
- 範圍：`<target>...<source>`，<日期>
|
||||||
|
```
|
||||||
|
|
||||||
|
### JSON（`.json`）
|
||||||
|
|
||||||
|
維持 **top-level array**（不要包在物件裡）；每筆一個物件，以 `key` 去重：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"key": "<檔案位置>|<問題標題>",
|
||||||
|
"title": "<問題標題>",
|
||||||
|
"severity": "🔴 嚴重 | 🟠 高 | 🟡 中 | 🔵 低",
|
||||||
|
"file": "<檔案位置>",
|
||||||
|
"line": "<所在行數>",
|
||||||
|
"description": "<描述>",
|
||||||
|
"suggestion": "<最終建議>",
|
||||||
|
"verdict": "成立 | 誤判",
|
||||||
|
"reason": "<理由>",
|
||||||
|
"source": "<target>...<source>",
|
||||||
|
"date": "YYYY-MM-DD"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 模板（空檔／新檔的初始內容）
|
||||||
|
|
||||||
|
目標檔不存在或為空時，先寫入下列模板（同一份也隨附於本 skill 的 `templates/`），再於對應標題下附加條目。
|
||||||
|
|
||||||
|
### 已知問題檔（`--known-issues`，`.md`）
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# 前次審查紀錄（已知問題 / Known Issues）
|
||||||
|
|
||||||
|
> 本檔由 `/jsc:code-review-archive` 自動維護，記錄 `/jsc:code-review` 防守方裁定 **✅ 成立** 但尚未解決的問題。
|
||||||
|
> `/jsc:code-review` 防守方在步驟 3(b) 會讀此檔：若新發現與此處條目相符，標為 **🔁 已知問題（前次未解決）**，不重複裁決。
|
||||||
|
> 問題修復後請刪除對應條目。每筆以 `<!-- key: 檔案位置|問題標題 -->` 去重。
|
||||||
|
|
||||||
|
## 待解決問題
|
||||||
|
|
||||||
|
<!-- code-review-archive 由此往下追加條目；條目格式見 /jsc:code-review-archive 說明。 -->
|
||||||
|
```
|
||||||
|
|
||||||
|
### 排除事項檔（`--exclusions`，`.md`）
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Code Review 排除事項（Exclusions）
|
||||||
|
|
||||||
|
> 本檔由 `/jsc:code-review-archive` 維護（也可手動編輯），列出已知技術債／團隊慣例／刻意取捨／已確認的誤判。
|
||||||
|
> `/jsc:code-review` 防守方在步驟 3(a) 會讀此檔：若新發現命中此處條目，標為 **🚫 略過（排除事項）**，不再裁決。
|
||||||
|
> 不再適用時請手動移除。每筆以 `<!-- key: 檔案位置|問題標題 -->` 去重。
|
||||||
|
|
||||||
|
## 排除項目
|
||||||
|
|
||||||
|
<!-- code-review-archive 由此往下追加條目；條目格式見 /jsc:code-review-archive 說明。 -->
|
||||||
|
```
|
||||||
|
|
||||||
|
### JSON（`.json`）
|
||||||
|
|
||||||
|
空／不存在時初始化為空陣列，再 append 物件：`[]`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 呼叫方式
|
||||||
|
|
||||||
|
格式：`--known-issues <路徑> --exclusions <路徑>` — **兩者必填**；未提供會反問取得。需先有 `/jsc: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」）自動觸發 |
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
# Code Review 排除事項（Exclusions）
|
||||||
|
|
||||||
|
> 本檔由 `/jsc:code-review-archive` 維護（也可手動編輯），列出已知技術債／團隊慣例／刻意取捨／已確認的誤判。
|
||||||
|
> `/jsc:code-review` 防守方在步驟 3(a) 會讀此檔：若新發現命中此處條目，標為 **🚫 略過（排除事項）**，不再裁決。
|
||||||
|
> 不再適用時請手動移除。每筆以 `<!-- key: 檔案位置|問題標題 -->` 去重。
|
||||||
|
|
||||||
|
## 排除項目
|
||||||
|
|
||||||
|
<!-- code-review-archive 由此往下追加條目；條目格式見 /jsc:code-review-archive 說明。 -->
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
# 前次審查紀錄（已知問題 / Known Issues）
|
||||||
|
|
||||||
|
> 本檔由 `/jsc:code-review-archive` 自動維護，記錄 `/jsc:code-review` 防守方裁定 **✅ 成立** 但尚未解決的問題。
|
||||||
|
> `/jsc:code-review` 防守方在步驟 3(b) 會讀此檔：若新發現與此處條目相符，標為 **🔁 已知問題（前次未解決）**，不重複裁決。
|
||||||
|
> 問題修復後請刪除對應條目。每筆以 `<!-- key: 檔案位置|問題標題 -->` 去重。
|
||||||
|
|
||||||
|
## 待解決問題
|
||||||
|
|
||||||
|
<!-- code-review-archive 由此往下追加條目；條目格式見 /jsc:code-review-archive 說明。 -->
|
||||||
@@ -0,0 +1,462 @@
|
|||||||
|
---
|
||||||
|
name: code-review-resolve
|
||||||
|
description: 解決 `.gitea/ai-review/findings.json` 的 AI review findings，先同步 git（fetch → 檢查目前分支的遠端分支是否存在；存在則留在目前分支 pull 更新，不存在則切換到 develop／master 後 pull 更新；只有來源分支與 PR 目標分支相同時才建立新的工作分支；必要時嘗試解衝突），再依嚴重度逐條修復；可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json`，已解決或已登記為誤報的 finding 可自 findings 移除；接著可將工作區變更依 conventional commit 類型分類提交、push 當前分支，並透過 Gitea API 對指定目標分支開 PR。當使用者說解決 findings、處理 AI review 問題、修掉 `.gitea/ai-review` 問題、依嚴重度修復後分類提交，或要分類 commit 並 push/開 PR 時觸發。不適用於：產生 findings、單純 code review 不修改、只保存裁決紀錄，或只要不分類的單一 commit。
|
||||||
|
argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]"
|
||||||
|
---
|
||||||
|
|
||||||
|
# code-review-resolve — 解決 AI review findings、分類提交、push 並開 PR
|
||||||
|
|
||||||
|
五階段 skill：先執行 **git 同步**（`git fetch` → 確認目前分支的遠端分支是否存在；存在則留在目前分支 `git pull` 更新，不存在則切換到 `develop`，再退而 `master` 後 `git pull` 更新；只有來源分支與 PR 目標分支相同時才建立新的工作分支；必要時告知並嘗試解衝突），再**逐條處理** `.gitea/ai-review/findings.json` 裡的問題；成立問題修復後自 findings 移除，可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json` 後也可自 findings 移除，接著**必須盤點並處理工作區的所有變更**，再依 conventional commit 類型分門別類 commit，然後 **push 當前分支**，最後**透過 Gitea API 發 PR**。
|
||||||
|
|
||||||
|
| 階段 | 動作 |
|
||||||
|
| --- | --- |
|
||||||
|
| A. Git 同步 | `git fetch` → 當前分支不在遠端則切換 develop（再退而 master）→ `git pull`／必要時解衝突 → 只有來源分支與 PR 目標分支相同時才建立新工作分支 |
|
||||||
|
| B. 解決問題 | 讀 `findings.json` / `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` 移除，誤報寫入 `exclusions.json` 後也可移除；**無待處理問題則跳到階段 D** |
|
||||||
|
| C. 分類提交 | 必須分析並涵蓋工作區所有變更（已修改／新增／刪除／改名，含已暫存與未暫存、未追蹤檔、findings/exclusions 更新）→ 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
|
||||||
|
| D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者；**無 commit 可 push 則跳到階段 E** |
|
||||||
|
| E. 發出 PR | 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 輸出規範（務必遵守）
|
||||||
|
|
||||||
|
- **語言**：所有面向使用者的輸出（修復清單、提交計畫、總結、反問）與 **commit 訊息** 一律使用**繁體中文（台灣用語）**；
|
||||||
|
僅程式碼識別字、檔名、git 指令、conventional commit 的 `type`（`feat`/`fix`…）等技術標識保留原文，**不可**使用簡體字。
|
||||||
|
- **編碼無亂碼（含繁中、全形標點、emoji）**：凡輸出或寫入只要含繁體中文，一律 **UTF-8（不含 BOM）**，不得出現問號方框（）或錯碼。涵蓋：更新後的 `findings.json` / `exclusions.json`、**commit 訊息**、**PR 標題／描述**、終端訊息，與等級 emoji 🔴🟠🟡🔵。實作要點：
|
||||||
|
- **寫檔**：優先用助理的檔案寫入工具（預設 UTF-8 無 BOM）。若改用 shell 寫檔，**避免 PowerShell 的 `>`／`Out-File`**（預設可能寫成 UTF-16 或加 BOM）；需要時用 `Set-Content -Encoding utf8NoBOM`，或在 bash 用 `printf`／heredoc。
|
||||||
|
- **commit 訊息**：用 `git commit -m` 直接帶字串，或寫進 UTF-8 無 BOM 的檔案再 `git commit -F <file>`；確保 `git config i18n.commitEncoding utf-8`。
|
||||||
|
- **PR body**：以 UTF-8 JSON 經 API 送出（如 `--data @body.json`，該檔為 UTF-8 無 BOM）。
|
||||||
|
- **送出前自我檢查**：產生含繁中的檔案／訊息後，回頭確認沒有亂碼或 BOM 再提交／送出。
|
||||||
|
- **自動執行原則**：除非使用者明確要求先確認，或遇到不可忽略的必要決策（例如目標分支缺失、pull 策略不明、無法安全解衝突、需人工判斷的設計取捨、push 憑證皆失敗），否則各階段只需輸出簡短計畫／進度後直接執行到完成；不要為一般修復、寫檔、分類 commit、push 或開 PR 反覆詢問。
|
||||||
|
- **Token 機密保護（極重要）**：gitea token 一律**從環境變數讀取**（如 `$GITEA_TOKEN`），**絕不**寫死在 skill、commit、PR 內文或任何輸出；**不可** echo 含 token 的指令或 URL、不可寫進 log。所有顯示給使用者的指令／錯誤訊息都要**遮蔽 token**（如以 `***` 取代）。階段 E 完成後依規範清除對話內文（見 E6）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 參數
|
||||||
|
|
||||||
|
格式：`[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]`
|
||||||
|
|
||||||
|
- `--findings <路徑>`：findings 檔路徑。**省略時預設 `.gitea/ai-review/findings.json`**（相對於工作目錄根）。
|
||||||
|
- `--target <目標分支>`：PR 的目標分支。**省略時必須詢問使用者，不可猜測**；若需要避免把同名來源分支誤推到目標分支，可能會在階段 D 先詢問並於階段 E 沿用。
|
||||||
|
- `--pr-desc <full|simple|自訂文字>`：PR 描述形式。`full`＝完整版（重新分析 diff 總結）、`simple`＝簡單版（逐條列 commit 訊息）、或直接給自訂文字；省略時預設 `full`，不要為描述形式中斷詢問。
|
||||||
|
- `--no-commit`：只做階段 A/B（git 同步 + 修復 + 更新 findings/exclusions），**不**執行階段 C/D/E（不提交、不推送、不開 PR）。
|
||||||
|
- `--no-pr`：執行到階段 D（push）為止，**不**開 PR（階段 E 略過）。
|
||||||
|
- `--yes`：明確要求全自動執行（修復、更新 findings/exclusions、commit、push、開 PR 一氣呵成）；即使未帶此參數，也依「自動執行原則」盡量不中斷，只有必要決策才詢問。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 A：Git 同步
|
||||||
|
|
||||||
|
### A1. 檢查同步前狀態
|
||||||
|
|
||||||
|
執行同步前先盤點目前分支與工作區狀態：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git rev-parse --abbrev-ref HEAD
|
||||||
|
git status --porcelain
|
||||||
|
```
|
||||||
|
|
||||||
|
- **若工作區已有未提交變更**：先告知使用者同步可能需要 merge / rebase 並可能與本地變更衝突；除非使用者要求先確認或目前狀態明顯容易覆蓋未提交工作，否則繼續同步。
|
||||||
|
- **若目前不在一般分支上**（例如 detached HEAD）：回報狀態並停止，請使用者切到要處理的分支後再執行。
|
||||||
|
|
||||||
|
### A2. Fetch 遠端更新
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git fetch --all --prune
|
||||||
|
```
|
||||||
|
|
||||||
|
- fetch 失敗時回報錯誤並停止，不進入 findings 修復。
|
||||||
|
- 若錯誤訊息可能含 credential / token，輸出前必須遮蔽。
|
||||||
|
|
||||||
|
### A3. 確認當前分支存在於遠端，必要時切換（develop → master）
|
||||||
|
|
||||||
|
fetch 後，確認當前分支在遠端是否有對應分支：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
current_branch="$(git rev-parse --abbrev-ref HEAD)"
|
||||||
|
git rev-parse --verify --quiet "origin/${current_branch}"
|
||||||
|
```
|
||||||
|
|
||||||
|
- **`origin/<current_branch>` 存在** → 維持當前分支，直接進入 A4 更新到最新；不要只因目前分支有遠端同名分支就建立新工作分支，後續只有來源分支與 PR 目標分支相同時才需要開新分支。
|
||||||
|
- **`origin/<current_branch>` 不存在**（當前分支為本地獨有，遠端無對應）→ 依序嘗試切換到後備分支：
|
||||||
|
1. 切換前先確認工作區可安全切換（承接 A1 結果）。若有未提交變更導致切換失敗，停止並回報，請使用者先處理未提交變更；不可強制丟棄。
|
||||||
|
2. 若 `origin/develop` 存在 → 切換到 `develop`：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git switch develop 2>/dev/null || git switch -c develop --track origin/develop
|
||||||
|
```
|
||||||
|
|
||||||
|
3. 否則若 `origin/master` 存在 → 切換到 `master`：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git switch master 2>/dev/null || git switch -c master --track origin/master
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **`develop` 與 `master` 在遠端都不存在** → 回報「當前分支不在遠端，且找不到 develop／master 後備分支」並停止，不臆測其他分支。
|
||||||
|
- 切換完成後，A4 先更新該後備分支到最新；是否建立新的工作分支交由 A5 依來源分支與 PR 目標分支是否相同判斷。切換到後備分支屬不可忽略的狀態變更，需在輸出中明確告知使用者已從原分支切換到哪一個分支。
|
||||||
|
|
||||||
|
### A4. Pull（更新到最新）
|
||||||
|
|
||||||
|
對當前分支（可能已於 A3 切換為 develop／master）拉取最新：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git pull
|
||||||
|
```
|
||||||
|
|
||||||
|
- pull 成功後進入 A5，必要時建立新的工作分支，再進入階段 B。
|
||||||
|
- 若顯示需要指定 merge / rebase 策略，先回報原因；未帶 `--yes` 時詢問使用者要採用哪種策略，不可自行猜測。
|
||||||
|
- 若 pull 產生衝突，立即告知使用者發生衝突，接著依階段 A6 嘗試解衝突。
|
||||||
|
|
||||||
|
### A5. 只有來源分支與 PR 目標分支相同時，建立新的工作分支
|
||||||
|
|
||||||
|
A4 更新完成後，取得目前來源分支與 PR 目標分支：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source_branch="$(git rev-parse --abbrev-ref HEAD)"
|
||||||
|
# target 來自 --target；若未提供且後續會建立 PR（未帶 --no-pr），需先依 E1 詢問目標分支。
|
||||||
|
```
|
||||||
|
|
||||||
|
- **若後續會建立 PR（未帶 `--no-pr`）且尚未知道目標分支** → 先依階段 E1 的規則詢問目標分支，避免後續修復 commit 落在與 PR 目標同名的來源分支上才發現 source/base 相同。若帶 `--no-pr`，此階段不因缺少目標分支而詢問。
|
||||||
|
- **若來源分支名稱與目標分支相同** → 不在該分支上直接修復／commit，也不可後續直接建立 head=base 的 PR。從目前已更新到最新的目標分支建立新的工作分支，後續階段（修復、commit、push、PR 的 `head`）都以新分支為準。
|
||||||
|
- **若來源分支名稱與目標分支不同** → 維持目前分支，不另開分支；即使目前分支存在 `origin/<source_branch>`，也照常在目前分支處理。
|
||||||
|
- 新分支名稱需可讀且避免覆蓋既有分支；預設格式：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
work_branch="ai-review-resolve/${source_branch}-$(date +%Y%m%d-%H%M%S)"
|
||||||
|
git switch -c "${work_branch}"
|
||||||
|
```
|
||||||
|
|
||||||
|
- 建立前若本地或遠端已存在同名分支，換一個時間戳或短 hash，不可覆蓋既有分支。
|
||||||
|
- 若因未提交變更導致建立／切換新分支失敗，停止並回報，請使用者先處理未提交變更；不可強制丟棄。
|
||||||
|
- 建立新分支屬不可忽略的狀態變更，需在輸出中明確告知使用者「因來源分支與目標分支同名，已從 `<source_branch>` 建立並切換到 `<work_branch>`」。
|
||||||
|
|
||||||
|
### A6. 必要時嘗試解衝突
|
||||||
|
|
||||||
|
當 `git pull` 後出現衝突：
|
||||||
|
|
||||||
|
1. 用 `git status --porcelain` 與衝突標記定位衝突檔。
|
||||||
|
2. 讀取衝突檔脈絡，依專案現有行為與遠端變更做最小合理整合。
|
||||||
|
3. 可安全解決的衝突：編輯檔案移除衝突標記，執行 `git add -- <檔案...>` 標記已解決。
|
||||||
|
4. 無法安全判斷的衝突：停止處理，列出檔案、衝突原因與需要使用者決策的點；不要硬選任一邊。
|
||||||
|
5. 全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 `git status --porcelain` 沒有未解衝突，再回到 A5 判斷是否需要建立新工作分支。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 B：依嚴重等級逐條解決問題或登記誤報
|
||||||
|
|
||||||
|
### B1. 讀取 findings 與 exclusions
|
||||||
|
|
||||||
|
讀 `--findings` 指定（或預設 `.gitea/ai-review/findings.json`）的檔案，內容為 **top-level JSON 陣列**，每筆是一個問題物件。常見欄位（不同產生器命名略有差異，需容錯對應）：
|
||||||
|
|
||||||
|
| 語義 | 可能欄位名 |
|
||||||
|
| --- | --- |
|
||||||
|
| 嚴重等級 | `severity` / `level` / `等級` |
|
||||||
|
| 檔案位置 | `file` / `path` / `檔案位置` |
|
||||||
|
| 所在行數 | `line` / `lines` / `所在行數` |
|
||||||
|
| 問題標題 | `title` / `message` / `問題` |
|
||||||
|
| 問題描述 | `description` / `detail` / `描述` |
|
||||||
|
| 修正建議 | `suggestion` / `fix` / `建議` |
|
||||||
|
|
||||||
|
`findings.json` 與 `.gitea/ai-review/exclusions.json` 的 canonical 格式須對齊 `https://gitea.jsc.idv.tw/actions/code-review`：
|
||||||
|
|
||||||
|
- 兩者都使用 **top-level JSON array**，不得包在 `{ "findings": [...] }`、`{ "exclusions": [...] }` 或 `{ "excluded_findings": [...] }`。
|
||||||
|
- `findings.json` 每筆至少保留 action 使用的必要欄位：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"level": "critical|warning|info",
|
||||||
|
"role": "審查角色名稱",
|
||||||
|
"location": "檔案路徑:行號 或 檔案路徑",
|
||||||
|
"suggestion": "繁體中文（台灣用語）的具體修改建議"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `exclusions.json` 每筆以最小且穩定的排除條目為主，優先保留原始問題文字、語言與語意；建議欄位：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"location": "檔案路徑:行號 或 檔案路徑",
|
||||||
|
"role": "審查角色名稱",
|
||||||
|
"original_finding": "原 finding 的 suggestion 或完整問題文字",
|
||||||
|
"reason": "判斷為誤報或不適用的原因"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
若既有 exclusions 使用 `suggestion`、`title`、`note` 等欄位，讀取時可容錯；寫回時仍要維持 top-level array，並盡量採用上述 canonical 欄位。
|
||||||
|
|
||||||
|
- **檔案不存在、內容為 `[]` 或空白** → 視為「無問題待解決」，輸出告知。`--no-commit` 時就此結束；否則**跳過階段 C 直接進入階段 D**（無待處理問題代表本 skill 未產生需要分類提交的修復變更）。
|
||||||
|
- **JSON 解析失敗** → 回報錯誤與檔案路徑並停止，不臆測內容、不亂改檔。
|
||||||
|
- `exclusions.json` 不存在時視為空陣列，必要時建立 `.gitea/ai-review/exclusions.json` 並寫入 `[]` 或新增後的排除項目。
|
||||||
|
- 若 `exclusions.json` 是舊 wrapper 格式（例如 `{ "exclusions": [...] }` 或 `{ "excluded_findings": [...] }`），先正規化為 top-level array 再寫回。
|
||||||
|
|
||||||
|
### B2. 依嚴重等級排序
|
||||||
|
|
||||||
|
把所有 finding 依等級由高到低排序：**🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低**。
|
||||||
|
canonical 等級為 `critical` / `warning` / `info`；其他寫法容錯對應：`critical`/`blocker`→🔴、`high`/`major`/`warning`→🟠、`medium`/`moderate`→🟡、`low`/`minor`/`info`→🔵；無法辨識的等級**排在最後**並標註「等級未知」。寫回 `findings.json` 時盡量保留原欄位值，除非需要修正成 canonical 格式。
|
||||||
|
|
||||||
|
### B3. 逐條處理（高等級先）
|
||||||
|
|
||||||
|
輸出一張「處理計畫」表，除非使用者要求確認或遇到必要決策，否則**依排序由上而下逐條**處理：
|
||||||
|
|
||||||
|
| # | 等級 | 問題 | 檔案位置 | 行數 | 處理方式 |
|
||||||
|
| --- | --- | --- | --- | --- | --- |
|
||||||
|
|
||||||
|
對每一條 finding：
|
||||||
|
|
||||||
|
1. 讀取對應檔案與其脈絡（依 `file` / `line`）。
|
||||||
|
2. 先判斷是否為誤報或不適用：例如程式碼脈絡證明指控不成立、已有等價防護、問題來自 action 已知排除規則、CI/CD 必要權限、或 finding 對非本次變更做不合理要求。
|
||||||
|
3. **可判斷為誤報** → 不改程式碼；將排除條目 append 到 `.gitea/ai-review/exclusions.json`，保留原始 finding 的語言與語意，避免過度改寫；若已有等價 exclusion（同檔案路徑、角色、原始文字或 suggestion 高度相似）則不要重複新增。
|
||||||
|
4. **確認為真問題且可安全修復** → 依 `suggestion`／`description` 在程式碼中實作最小合理修正；建議含糊或與現況不符時，依原始碼脈絡做最小且合理的修正。
|
||||||
|
5. **無法安全自動修復或無法確認真偽**（例如需求不明、牽涉設計取捨、檔案不存在）→ **不硬改**，標記為「待人工處理」並記錄原因，繼續下一條。
|
||||||
|
6. 逐條完成後，記錄該條結果（✅ 已解決 / 🚫 誤報已寫入 exclusions / ⏭️ 待人工處理 + 原因）。
|
||||||
|
|
||||||
|
> 一次只處理一條、修完再處理下一條，避免互相干擾；同檔多條問題可合併讀取但仍逐條套用修正。
|
||||||
|
|
||||||
|
### B4. 更新 findings.json 與 exclusions.json
|
||||||
|
|
||||||
|
**所有條目處理完畢後**，依結果更新 `findings.json` 與 `exclusions.json`：
|
||||||
|
|
||||||
|
- **只有確認已解決，或已確認為誤報並成功寫入 `exclusions.json` 的 finding，才可從 `findings.json` 移除**。
|
||||||
|
- 誤報移出 `findings.json` 前，必須先確認 `exclusions.json` 已存在、格式合法、且該排除條目已寫入或已有等價條目；若 exclusions 寫入失敗，該 finding 必須保留。
|
||||||
|
- 待人工處理、無法確認真偽、或修復未驗證成功的 finding 必須保留在 `findings.json`。
|
||||||
|
- 寫回 `findings.json` 時只保留尚未解決且尚未登記為誤報的 finding；已解決或已登記為誤報的 finding 逐項移除，不需要等待其他問題也處理完。
|
||||||
|
- 如果移除後沒有任何 finding 需要保留，將 `findings.json` 寫成空陣列：
|
||||||
|
|
||||||
|
```json
|
||||||
|
[]
|
||||||
|
```
|
||||||
|
|
||||||
|
- 寫回 `findings.json` 時保留未解決 finding 的 canonical 欄位（`level`、`role`、`location`、`suggestion`）與有用原欄位；依嚴重度排序。
|
||||||
|
- 寫回 `exclusions.json` 時使用 top-level JSON array；新增項目 append 後依既有順序保留並去重。
|
||||||
|
- 兩個檔案都以 UTF-8（不含 BOM）寫入，結尾保留一個換行。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 C：分析變更並分類提交（`--no-commit` 時略過）
|
||||||
|
|
||||||
|
### C1. 盤點工作區變更
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git status --porcelain=v1 -uall
|
||||||
|
git diff # 已追蹤檔的未暫存變更
|
||||||
|
git diff --staged # 已暫存變更
|
||||||
|
git ls-files --others --exclude-standard # 未追蹤檔
|
||||||
|
```
|
||||||
|
|
||||||
|
盤點時必須以 `git status --porcelain=v1 -uall` 為主，不可只看 `git diff`，因為那會漏掉未追蹤檔。盤點範圍必須包含**所有**變更：已修改檔、新增檔（`??` 未追蹤檔）、刪除檔、改名檔，以及已暫存與未暫存變更。`git diff`、`git diff --staged`、`git ls-files --others --exclude-standard` 只作為輔助核對。**無任何變更** → 回報「工作區無變更可提交」，跳過提交直接進入階段 D（D 會因無 commit 可 push 而跳到階段 E）。
|
||||||
|
|
||||||
|
### C2. 依異動內容歸類 conventional commit 類型
|
||||||
|
|
||||||
|
逐一檢視每個變更檔的**實際異動內容**（不只看路徑），歸入下列其一；**所有 `??` 未追蹤檔都必須納入分類**，不能因為它們不在 `git diff` 裡就漏掉：
|
||||||
|
|
||||||
|
| type | 適用情境 |
|
||||||
|
| --- | --- |
|
||||||
|
| `feat` | 新增功能／新行為／新 API／新 skill |
|
||||||
|
| `fix` | 修正錯誤、修掉 bug（**階段 B 的 bug 修復多半歸此**） |
|
||||||
|
| `docs` | 只改文件（README、註解、`*.md`、說明） |
|
||||||
|
| `style` | 不影響邏輯的格式調整（排版、空白、分號、命名一致化） |
|
||||||
|
| `refactor` | 重構：不改外部行為的內部結構調整 |
|
||||||
|
| `perf` | 效能優化 |
|
||||||
|
| `test` | 新增或修改測試 |
|
||||||
|
| `chore` | 雜項：建置、設定、相依套件、版本號 bump、忽略檔等 |
|
||||||
|
| `revert` | 還原先前的提交 |
|
||||||
|
|
||||||
|
- **同一檔案橫跨多型** → 以該檔**主要異動性質**歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
|
||||||
|
- **階段 B 修復產生的變更**：依其性質歸類（修 bug→`fix`、補功能→`feat`、改文件→`docs`…）。`findings.json` / `exclusions.json` 的問題狀態更新歸 `chore`。
|
||||||
|
- **未追蹤新檔**：必須照實際內容歸入對應 type，必要時在提交前明確 `git add -- <path>`，不可因為是新檔就略過。
|
||||||
|
|
||||||
|
### C3. 產出提交計畫
|
||||||
|
|
||||||
|
把變更檔依 type 分組，**每個 type 一個 commit**，輸出提交計畫；**所有變更項目都必須被追蹤並納入計畫，不能遺漏任何 `??` 未追蹤檔**。除非使用者要求確認或分組有不可忽略的取捨，否則直接提交：
|
||||||
|
|
||||||
|
| 順序 | type(範圍) | commit 訊息 | 納入檔案 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
|
||||||
|
- **commit 訊息格式**：`type(範圍): 一句總結` —
|
||||||
|
- `type`：上表英文類型。
|
||||||
|
- `範圍`（括號內）：**必須是這組異動實際牽涉的功能／模組／元件名稱**，而**不是**重述 type 的類別詞。
|
||||||
|
取名規則：優先沿用程式碼／專案中既有的識別名（檔名、模組名、skill 名、功能名，可中可英、保持與原碼一致），讓人一眼看出「改到哪個東西」。
|
||||||
|
- ✅ 對：`feat(使用者登入)`、`fix(結帳流程)`、`perf(物件查詢)`、`docs(README)`、`refactor(訂單服務)`、`chore(plugin 版本)`、`feat(code-review-resolve)`。
|
||||||
|
- ❌ 錯（只是重述 type，禁止）：`feat(新增功能)`、`fix(修正錯誤)`、`perf(優化效能)`、`docs(文件)`、`chore(雜項)`。
|
||||||
|
- 一組異動橫跨多個功能而無單一主體時，才退而取最貼近的上層範圍（例如多個 manifest → `plugin 設定`）。
|
||||||
|
- `一句總結`：把這個 commit 內所有異動**總結成一句**繁體中文（簡短、聚焦做了什麼）。
|
||||||
|
- 範例：`feat(使用者登入): 新增帳密登入與 token 簽發`、`fix(結帳流程): 修正空購物車導致的結帳例外`、`perf(物件查詢): 改用批次查詢降低 DB 往返`、`docs(README): 補上安裝與呼叫方式說明`、`chore(ai-review 狀態): 更新 findings.json 與 exclusions.json`。
|
||||||
|
- **提交順序建議**：`fix`/`feat` 等核心異動在前，`docs`/`style`/`chore` 在後（純屬建議，可依相依性調整）。
|
||||||
|
- **盤點要求**：提交計畫必須完整對應 C1 盤點出的所有變更項目，若有新檔或未追蹤檔，必須明確列入對應 commit，不能只根據 `git diff` 下結論。
|
||||||
|
|
||||||
|
### C4. 執行分類提交
|
||||||
|
|
||||||
|
對每組依序：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add -- <該組檔案...> # 僅暫存該組檔案，逐組精準 add
|
||||||
|
git commit -m "type(範圍): 一句總結" # 範圍＝實際異動的功能／模組名
|
||||||
|
```
|
||||||
|
|
||||||
|
- **逐組 add／commit**，確保每個 commit 只含該類異動；不要一次 `git add -A` 再混在一起。
|
||||||
|
- 改名／刪除檔一併納入對應組的 `git add`（`git add -A -- <路徑>` 或明確列出）。
|
||||||
|
- **所有 `??` 未追蹤檔都必須納入提交**；若是新檔，必要時要明確執行 `git add -- <path>`，不可漏掉。
|
||||||
|
- **不可只根據 `git diff` 判斷變更**；C1 盤點出的所有異動都必須反映到分類與提交，否則視為提交計畫不完整。
|
||||||
|
- commit 完成後進入階段 D（push）。`--no-commit` 時不進入後續階段；若工作區無變更而沒有產生任何新 commit，仍進入階段 D，由 D 判斷無 commit 可 push 後跳到階段 E。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 D：Push 當前分支（`--no-commit` 時略過；無 commit 可 push 時跳到階段 E）
|
||||||
|
|
||||||
|
commit 完成後推送**當前分支**，依序嘗試三種方式，前者失敗才退到下一個：
|
||||||
|
|
||||||
|
推送前先記錄目前來源分支與其遠端基準，並確認是否有 commit 需要 push：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source_branch="$(git rev-parse --abbrev-ref HEAD)"
|
||||||
|
git rev-parse --verify "origin/${source_branch}"
|
||||||
|
git log --oneline "origin/${source_branch}..${source_branch}" # 領先遠端的 commit
|
||||||
|
```
|
||||||
|
|
||||||
|
- **無 commit 可 push**（來源分支已存在於遠端，且相對 `origin/<source_branch>` 沒有領先 commit）→ **跳過本階段 push，直接進入階段 E**（仍可對既有遠端分支開 PR）；若帶 `--no-pr`，則就此結束。
|
||||||
|
- 若來源分支沒有對應的 `origin/<source_branch>`，視為需要 push 的新分支，先記錄「無遠端基準」並繼續；這種情況不需要切回 develop／master，因為 A3 已在同步階段處理「當前分支不存在於遠端」的後備切換。
|
||||||
|
- 若後續會建立 PR（未帶 `--no-pr`）且尚未知道目標分支，先依階段 E1 的規則詢問目標分支，這屬於不可忽略的必要決策。
|
||||||
|
- 若來源分支名稱與目標分支相同，**不要 push 原來源分支**；記下來源分支與遠端基準，直接進入階段 E，由 E2 建立新的 PR 來源分支、帶入 commit 後再 push 新分支。
|
||||||
|
|
||||||
|
1. **認證管理器（優先）**：直接用 git 既有的 credential helper（如 Windows 的 `manager-core`）：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git push -u origin "$(git rev-parse --abbrev-ref HEAD)"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **失敗 → 改用 token push**：從環境變數讀 token，組帶 token 的遠端 URL 推送。**整個過程不可把含 token 的指令／URL 印出來**（用變數帶入、輸出時遮蔽）：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# GITEA_TOKEN 來自環境變數；解析 origin 的 host/owner/repo
|
||||||
|
git push "https://oauth2:${GITEA_TOKEN}@<host>/<owner>/<repo>.git" \
|
||||||
|
"$(git rev-parse --abbrev-ref HEAD)"
|
||||||
|
```
|
||||||
|
|
||||||
|
（token 用完即棄，不寫進 git remote 設定、不落地。）
|
||||||
|
|
||||||
|
3. **再失敗 → 詢問使用者要如何 push**：列出失敗原因（遮蔽 token），請使用者指示推送方式，**不可自行猜測**其他憑證或來源。
|
||||||
|
|
||||||
|
push 成功後記下遠端分支名，進入階段 E。若因來源分支與目標分支相同而延後 push，記下原因並進入階段 E2 建立新分支。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 E：透過 Gitea API 發出 PR（`--no-pr`／`--no-commit` 時略過）
|
||||||
|
|
||||||
|
### E1. 確定目標分支（不可猜想）
|
||||||
|
|
||||||
|
- 帶 `--target <分支>` → 直接採用。
|
||||||
|
- 若階段 D 已為了避免 source/base 相同而詢問過目標分支，沿用該目標分支。
|
||||||
|
- **否則必須詢問使用者目標分支**（可用 `git branch -r` 列出輔助選擇），**嚴禁臆測或預設**（不可自行假設 develop／main／master）。
|
||||||
|
|
||||||
|
### E2. 若來源分支與目標分支相同，改建 PR 來源分支
|
||||||
|
|
||||||
|
先取得目前 PR 來源分支：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git rev-parse --abbrev-ref HEAD
|
||||||
|
```
|
||||||
|
|
||||||
|
若來源分支名稱與 `--target` 指定（或使用者選定）的目標分支相同，**不可直接建立 head=base 的 PR，也不可先把原來源分支 push 到目標分支**。改用下列流程建立新的 PR 來源分支，並把原來源分支的 commit 帶入後再開 PR：
|
||||||
|
|
||||||
|
1. 先記錄原來源分支名稱與要帶入的 commit 清單：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source_branch="$(git rev-parse --abbrev-ref HEAD)"
|
||||||
|
git log --oneline "origin/${target}..${source_branch}"
|
||||||
|
```
|
||||||
|
|
||||||
|
- 若 `origin/<target>` 不存在，先回報並停止，不猜測替代 base。
|
||||||
|
- 若沒有任何 commit 可帶入，回報「來源分支沒有領先目標分支的 commit」，停止開 PR。
|
||||||
|
- 若階段 D 已記錄來源分支的遠端基準，使用該基準判斷要帶入的 commit，避免把原來源分支直接推進目標分支。
|
||||||
|
|
||||||
|
2. 從目標分支的遠端基準建立新分支。新分支名稱需可讀且避免覆蓋既有分支，例如：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git switch -c "ai-review-resolve/<短時間戳>" "origin/${target}"
|
||||||
|
```
|
||||||
|
|
||||||
|
3. 將原來源分支領先目標分支的 commit 依序帶入新分支：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git cherry-pick "origin/${target}..${source_branch}"
|
||||||
|
```
|
||||||
|
|
||||||
|
- cherry-pick 發生衝突時，先告知使用者，再依專案脈絡嘗試最小合理解衝突。
|
||||||
|
- 可安全解決的衝突：移除衝突標記、`git add -- <檔案...>`，再繼續 `git cherry-pick --continue`。
|
||||||
|
- 無法安全判斷的衝突：停止處理，列出衝突檔案與需要使用者決策的點；不要硬選任一邊。
|
||||||
|
|
||||||
|
4. 將新分支 push 到遠端，使用階段 D 的同一套 push 憑證策略，並把後續 PR 的 `head` 改為這個新分支。
|
||||||
|
|
||||||
|
若來源分支與目標分支不同，直接以目前分支作為 PR 的 `head`。
|
||||||
|
|
||||||
|
### E3. 解析 repo 座標
|
||||||
|
|
||||||
|
從 `git remote get-url origin` 解析出 **host／owner／repo**（例：`https://gitea.jsc.idv.tw/plugins/code-review.git` → host=`gitea.jsc.idv.tw`、owner=`plugins`、repo=`code-review`）。
|
||||||
|
|
||||||
|
### E4. 決定 PR 描述形式（完整版／簡單版／使用者輸入）
|
||||||
|
|
||||||
|
依 `--pr-desc` 三選一；若未提供則預設使用 `full`，不要為描述形式中斷詢問：
|
||||||
|
|
||||||
|
- **完整版（`full`）**：**重新分析並總結** `git diff <target>...<PR 來源分支>`（比對 source 自分岔點以來的變更），整理成結構化繁體中文說明 —— 變更摘要、影響範圍、重點檔案／模組、風險或注意事項。不是貼原始 diff，而是「人讀得懂的總結」。
|
||||||
|
- **簡單版（`simple`）**：直接把本分支領先 target 的 commit 訊息**逐條列出**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git log --oneline "<target>..<PR 來源分支>"
|
||||||
|
```
|
||||||
|
|
||||||
|
以條列呈現每行 commit 訊息。
|
||||||
|
- **使用者輸入**：採用使用者提供的描述文字。
|
||||||
|
|
||||||
|
PR **標題**預設取一句總結（可用首個 feat/fix commit 或分支用途）；使用者另有指定則從之。
|
||||||
|
|
||||||
|
產生 PR body 時必須使用實際換行與 Markdown 內容，不可把跳脫字串當作正文送出。若用 shell / `jq` 組 JSON，應以 UTF-8 暫存檔、heredoc、`printf` 或 `jq --rawfile` 帶入內容；避免讓 PR 顯示成 `## Commit\n\n- ...` 這類字面 `\n`。
|
||||||
|
|
||||||
|
### E5. 呼叫 Gitea API 建立 PR（使用 token）
|
||||||
|
|
||||||
|
token 從環境變數讀取，呼叫 Gitea 建立 PR：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 不可 echo 含 token 的指令；body 以 UTF-8 JSON 檔帶入，輸出時遮蔽 token
|
||||||
|
# PR 描述內的換行必須是實際換行，不可使用字面 \n
|
||||||
|
curl -sS -X POST \
|
||||||
|
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
"https://<host>/api/v1/repos/<owner>/<repo>/pulls" \
|
||||||
|
--data @body.json
|
||||||
|
```
|
||||||
|
|
||||||
|
- **成功**：取回應中的 PR 連結／編號回報使用者。
|
||||||
|
- **失敗**：顯示 API 回應的錯誤訊息供排查（**先遮蔽 token**）。常見錯誤：目標分支不存在、已有相同 head→base 的 PR、token 權限不足。
|
||||||
|
|
||||||
|
### E6. 完成通知 + 清除對話內文（重要：可能含 token）
|
||||||
|
|
||||||
|
1. **通知使用者**：push 結果、PR 連結／編號、PR 描述採用哪種形式。
|
||||||
|
2. **清除 AI 助理對話內文**：因為 push／API 過程可能使對話內文殘留 gitea token，**完成後務必清除對話內文／上下文**以免外洩：
|
||||||
|
- Claude Code：提示使用者執行 `/clear`（或依當前助理對等指令清空對話）。
|
||||||
|
- 其他助理：執行各自清除對話／上下文的方式。
|
||||||
|
- 在清除前，請再次確認輸出與 log 中沒有任何明文 token。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 總結
|
||||||
|
|
||||||
|
各階段執行後輸出：
|
||||||
|
|
||||||
|
- **階段 A**：git fetch / pull 是否成功、當前分支是否存在於遠端（不存在時切到 develop／master 的結果）、若來源分支與目標分支同名是否已建立新工作分支、是否發生衝突、衝突是否已解決或仍需人工處理。
|
||||||
|
- **階段 B**：已解決 N 條（依等級分佈）、誤報寫入 exclusions M 條、待人工處理 K 條（列出原因）、`findings.json` 保留／移除筆數與 `exclusions.json` 新增筆數；若無待處理問題，說明已跳過階段 C 直接進入階段 D。
|
||||||
|
- **階段 C**：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（`--no-commit` / 無變更）。
|
||||||
|
- **階段 D**：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名；若無 commit 可 push，說明已跳過 push 直接進入階段 E。
|
||||||
|
- **階段 E**：PR 連結／編號、目標分支、描述形式；並提醒已（或請使用者）清除對話內文以防 token 外洩。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 呼叫方式
|
||||||
|
|
||||||
|
格式：`[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]` —
|
||||||
|
全部可省略（findings 預設 `.gitea/ai-review/findings.json`；目標分支省略時必問、不猜測）。token 一律由環境變數（如 `GITEA_TOKEN`）提供。
|
||||||
|
|
||||||
|
| 助理 | 呼叫 |
|
||||||
|
| --- | --- |
|
||||||
|
| Claude Code / Antigravity | `/jsc:code-review-resolve`，或 `/jsc:code-review-resolve --target develop --pr-desc full --yes`、`/jsc:code-review-resolve --no-pr`、`/jsc:code-review-resolve --no-commit` |
|
||||||
|
| Codex | `$code-review-resolve`，或 `$code-review-resolve --target develop --pr-desc full --yes`，或用 `/skills` 選單 |
|
||||||
|
| OpenCode | 描述需求（如「讀 .gitea/ai-review/findings.json 依嚴重度逐條處理，更新 findings/exclusions，把工作區變更依 conventional commit 分類提交，push 後對 develop 發 PR（完整版描述）」）自動觸發 |
|
||||||
@@ -0,0 +1,165 @@
|
|||||||
|
---
|
||||||
|
name: code-review
|
||||||
|
description: 以 RPG 攻防對決方式審查 git diff 的程式碼審查 skill。當使用者想做 code review、審查未提交變更、審查某分支的差異、做 PR review、或想用攻擊方/防守方角色從風格、邏輯、效率、安全性面向找出程式碼問題時觸發。使用者可選擇要派哪些角色（單一角色、整個攻擊方、整個防守方、或全部）。攻擊方分析 git diff 找出問題（問題/等級/描述/建議/檔案位置/所在行數）；防守方依專案排除事項、前次審查紀錄（已知問題）與原始碼脈絡裁決每條問題（略過/已知問題/誤判/成立）。不適用於：非 diff 的整體架構評估、非程式碼的文件審查、或單純解釋程式碼。
|
||||||
|
---
|
||||||
|
|
||||||
|
# 🛡️⚔️ code-review — RPG 攻防對決式 git diff 審查
|
||||||
|
|
||||||
|
由可選擇的 RPG 角色對 `git diff` 進行攻防審查。**攻擊方**找問題，**防守方**裁決。
|
||||||
|
角色定義在 `roles/` 資料夾（一角色一個 `.md`），各自有英文名稱、專案、個性、徽章與代表色。
|
||||||
|
|
||||||
|
## 角色一覽
|
||||||
|
|
||||||
|
| 角色 | 陣營 | 面向 | 徽章 | 檔案 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| Bard（吟遊詩人） | 攻擊方 | 風格 | 🎼 | `roles/bard.md` |
|
||||||
|
| Mage（法師） | 攻擊方 | 邏輯 | 🔮 | `roles/mage.md` |
|
||||||
|
| Rogue（盜賊） | 攻擊方 | 效率 | ⚡ | `roles/rogue.md` |
|
||||||
|
| Assassin（刺客） | 攻擊方 | 安全性 | 🗡️ | `roles/assassin.md` |
|
||||||
|
| Paladin（聖騎士） | 防守方 | 裁決 | 🛡️ | `roles/paladin.md` |
|
||||||
|
|
||||||
|
每次執行前，先讀取被選到角色的 `roles/<role>.md`，套用其 frontmatter（徽章、代表色、個性）與 body（審查重點/裁決準則）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 輸出規範（所有角色共用，務必遵守）
|
||||||
|
|
||||||
|
- **語言**：所有面向使用者的輸出（findings 表、裁決表、總結、附註、反問）一律使用**繁體中文（台灣用語）**。
|
||||||
|
僅程式碼識別字、檔名、git 指令、既有技術術語保留原文，**不可**使用簡體字或英文敘述句。
|
||||||
|
- **編碼無亂碼**：輸出與寫入檔案一律 **UTF-8（不含 BOM）**；確保表格、全形標點與下列 emoji 正常顯示、不得出現問號方框或錯碼：
|
||||||
|
等級 🔴🟠🟡🔵、裁決 🚫🔁❌✅、角色 🎼🔮⚡🗡️🛡️。
|
||||||
|
- **派發 subagent 時**：須把本規範一併寫入每個 subagent 的提示，確保各角色回傳的內容同樣是繁體中文、無亂碼。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 執行流程
|
||||||
|
|
||||||
|
### 1. 取得 diff（必須指定來源分支與目標分支，缺一不可）
|
||||||
|
|
||||||
|
審查範圍一律是兩個分支的差異，**來源分支（source）**與**目標分支（target）**兩者**缺一不可**：
|
||||||
|
|
||||||
|
- slash 參數提供兩者：`/jsc:code-review <target> <source>`（順序：目標在前、來源在後），例如
|
||||||
|
`/jsc:code-review main feature/login`。指令為 `git diff <target>...<source>`（比對 source 自分岔點以來的變更）。
|
||||||
|
- **若來源或目標分支任一缺漏 → 必須詢問使用者補齊**，兩個都拿到才繼續；
|
||||||
|
可用 `git branch` 列出可選分支輔助使用者選擇。不可自行臆測或預設某一分支。
|
||||||
|
- 取得兩個分支後執行 `git diff <target>...<source>`，並**排除下列不納入審查的路徑**：
|
||||||
|
- **任何以 `.` 開頭的資料夾內的所有內容**（如 `.git/`、`.github/`、`.claude-plugin/`、`.codex-plugin/`、`.agents/` 等）。
|
||||||
|
- **排除事項檔**與**前次審查紀錄檔**本身（`--exclusions` / `--known-issues` 指定的路徑；未指定時連同預設檔名 `exclusions.md`、`known-issues.md` 一併排除）。
|
||||||
|
- 用 git pathspec 一次完成，例如：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff <target>...<source> -- . \
|
||||||
|
':(exclude,glob)**/.*/**' \
|
||||||
|
':(exclude)<排除事項檔路徑>' \
|
||||||
|
':(exclude)<前次審查紀錄檔路徑>'
|
||||||
|
```
|
||||||
|
|
||||||
|
（`**/.*/**` 排除任意層級的 `.` 開頭資料夾內容；`.` 開頭的**檔案**不在此列，只有上述兩個設定檔被指名排除。）
|
||||||
|
- **過濾後 diff 為空** → 回報「無變更可審查」並結束。
|
||||||
|
|
||||||
|
### 2. 選擇角色
|
||||||
|
|
||||||
|
slash 參數格式：`/jsc:code-review <target> <source> [角色...] [--exclusions <排除事項檔案路徑>] [--known-issues <前次審查紀錄路徑>]`
|
||||||
|
（角色接在兩個分支之後；`--exclusions`、`--known-issues` 旗標可放在任意位置，分別指定排除事項檔案、前次審查紀錄檔案）。
|
||||||
|
|
||||||
|
- **若已指定角色** → 直接採用。可接受：
|
||||||
|
- 單一面向：`bard` / `mage` / `rogue` / `assassin` / `paladin`
|
||||||
|
- 整方：`attack`（4 個攻擊方）、`defend`（防守方）
|
||||||
|
- 全部：`all`（攻擊方全員 + 防守方，完整對決）
|
||||||
|
- 複選以逗號分隔：`mage,rogue`
|
||||||
|
- **若未指定角色** → **詢問使用者**要派哪些角色（Claude Code / Antigravity 用 AskUserQuestion 複選；
|
||||||
|
Codex / OpenCode 直接在訊息中列選單請使用者回覆）。選項涵蓋：單一角色 / 攻擊方全員 / 防守方全員 / 全部。
|
||||||
|
|
||||||
|
### 3. 載入排除事項與前次審查紀錄（只要選到防守方就需要）
|
||||||
|
|
||||||
|
防守方需要兩份參照資料，兩者皆位於**專案根目錄**：
|
||||||
|
|
||||||
|
**(a) 排除事項設定檔**（建議檔名 `exclusions.md`，列出已知技術債／團隊慣例／刻意取捨）：
|
||||||
|
|
||||||
|
- **若 slash 參數帶了 `--exclusions <路徑>`** → 即為使用者明確指定，直接採用該路徑，**不需再問**。
|
||||||
|
- **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `exclusions.md` 僅作為詢問時的**建議選項**，
|
||||||
|
**不可**在未取得使用者明確指定前自行假設或直接採用該預設路徑。
|
||||||
|
- **檔案允許不存在或為空** → 視為「無排除事項」，**不**因缺檔而中斷。
|
||||||
|
|
||||||
|
**(b) 前次審查紀錄檔**（已知問題＝前次審查成立但未解決的問題；建議檔名 `known-issues.md`）：
|
||||||
|
|
||||||
|
- **若 slash 參數帶了 `--known-issues <路徑>`** → 即為使用者明確指定，直接採用該路徑，**不需再問**。
|
||||||
|
- **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**（規則同上，預設檔名僅為建議選項，不可自行假設）。
|
||||||
|
- **檔案允許不存在或為空** → 視為「無已知問題」（例如首次審查），**不**因缺檔而中斷。
|
||||||
|
|
||||||
|
### 4. 攻擊方審查
|
||||||
|
|
||||||
|
被選到的每個攻擊方角色，依其 `focus` 與個性掃描 diff，**各自輸出一張 findings 表**
|
||||||
|
（表前加上該角色的徽章＋名稱，並標註代表色）：
|
||||||
|
|
||||||
|
> ## 🔮 Mage（法師）· 邏輯 `#3B82F6`
|
||||||
|
>
|
||||||
|
> | 問題 | 等級 | 描述 | 建議 | 檔案位置 | 所在行數 |
|
||||||
|
> | --- | --- | --- | --- | --- | --- |
|
||||||
|
|
||||||
|
- **等級**：🔴 嚴重 / 🟠 高 / 🟡 中 / 🔵 低。
|
||||||
|
- **檔案位置 / 所在行數**：取自 diff 新檔（`+` 側）的路徑與行號。
|
||||||
|
- 只針對本次 diff 的變更，不對無關舊碼開砲。
|
||||||
|
- 攻擊方審查的是**步驟 1 過濾後**的 diff（已排除 `.` 開頭資料夾內容、排除事項檔與前次審查紀錄檔），不得把這些被排除的路徑列入問題。
|
||||||
|
|
||||||
|
### 5. 防守方裁決（若選到防守方）
|
||||||
|
|
||||||
|
**先把攻擊方的 findings 彙整去重並排序，再逐條裁決：**
|
||||||
|
|
||||||
|
- **(0) 去重 + 排序**：合併所有攻擊方的 findings，依「同檔案位置 ＋ 同問題本質」**去除重複**
|
||||||
|
（多個角色重複提出的同一問題只保留一條，並註明由哪些角色共同提出），再依嚴重等級
|
||||||
|
**🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低** 排序。
|
||||||
|
|
||||||
|
對排序後的**每一條** finding 依序：
|
||||||
|
|
||||||
|
- **(a) 先比對排除事項**：命中 → **🚫 略過（排除事項）**，引用對應排除條目，不再回答此條。
|
||||||
|
- **(b) 再比對前次審查紀錄（已知問題）**：若與前次發現但未解決的問題相符 → **🔁 已知問題（前次未解決）**，引用對應紀錄條目，不重複裁決。
|
||||||
|
- **(c) 否則讀原始碼判斷**：標 **❌ 誤判（false positive）**（附理由）或 **✅ 成立**（附理由與修正建議）。
|
||||||
|
|
||||||
|
輸出一張裁決表（聖騎士徽章 🛡️ `#EAB308`）：
|
||||||
|
|
||||||
|
| 來源角色 | 原問題 | 裁決 | 理由 | 最終建議 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
|
||||||
|
裁決欄只能是 `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立`。
|
||||||
|
|
||||||
|
> **若只選了防守方、尚無攻擊方 findings** → 先自動跑攻擊方全員產生指控，再裁決（並告知使用者已自動補跑）。
|
||||||
|
|
||||||
|
### 6. 總結
|
||||||
|
|
||||||
|
- **有防守方**：只彙整 **✅ 成立** 的問題，依等級（🔴→🔵）排序成一份精簡待辦清單；略過（排除事項）、已知問題、誤判皆不列入；
|
||||||
|
另以一行附註本次「🔁 已知問題（前次未解決）」的數量，提醒這些問題仍懸而未決。
|
||||||
|
- **無防守方**：直接呈現攻擊方各自的 findings 表。
|
||||||
|
|
||||||
|
### 7. 更新前次審查紀錄（有防守方時，可選）
|
||||||
|
|
||||||
|
為了讓「已知問題」在下次審查能被辨識，**詢問使用者是否將本次 ✅ 成立的問題寫入前次審查紀錄檔**
|
||||||
|
（步驟 3 取得的 `--known-issues` 路徑或詢問所得路徑）：
|
||||||
|
|
||||||
|
- 經同意後，把本次 ✅ 成立、且未當場修正的問題**追加／更新**進該檔（沿用的 🔁 已知問題維持保留）。
|
||||||
|
- 寫入屬於更動專案檔案的行為，**未獲同意前不可自行寫入**；使用者拒絕則僅輸出總結、不改檔。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 執行方式：單選 vs 複選
|
||||||
|
|
||||||
|
- **單一角色** → 模型直接扮演該角色執行，不需 subagent。
|
||||||
|
- **複選（多個角色 / 整方 / 全部）** → 以 **sub agent** 方式執行：
|
||||||
|
- **Claude Code / Antigravity**：用 Agent/Task 工具，**每個被選到的攻擊方角色派一個 subagent 並行執行**
|
||||||
|
（subagent 帶該角色 `roles/<role>.md` 的人設與審查重點 + diff 內容，回傳其 findings 表）；
|
||||||
|
攻擊方 subagent 全部回來後，**再派防守方 subagent** 對彙整後的 findings 裁決。
|
||||||
|
- **Codex / OpenCode（無對等 subagent 機制）**：退化為模型**依序扮演**各角色，行為等價、僅非並行。
|
||||||
|
|
||||||
|
無論哪種路徑，最終輸出格式（findings 表、裁決表、總結）一致。
|
||||||
|
|
||||||
|
## 呼叫方式
|
||||||
|
|
||||||
|
格式：`<target> <source> [角色...] [--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」）自動觸發 |
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
---
|
||||||
|
name: Assassin
|
||||||
|
project: code-review
|
||||||
|
side: attack
|
||||||
|
focus: security
|
||||||
|
badge: "🗡️"
|
||||||
|
color: "#DC2626"
|
||||||
|
personality: 多疑偏執、以攻擊者視角看世界，假設每筆輸入都是惡意的，每個信任都會被濫用
|
||||||
|
---
|
||||||
|
|
||||||
|
# 🗡️ Assassin（刺客）· 安全性面向
|
||||||
|
|
||||||
|
> 攻擊方。代表色 `#DC2626`（暗紅）。
|
||||||
|
|
||||||
|
## 個性
|
||||||
|
|
||||||
|
刺客習慣站在敵人的位置思考：哪裡能潛入、哪裡能越權、哪裡能讓秘密外洩。
|
||||||
|
他多疑而偏執，不相信任何「使用者不會這樣傳」的善意假設，
|
||||||
|
把每筆外部輸入都當作淬了毒的匕首來對待。
|
||||||
|
|
||||||
|
## 審查重點（只看 git diff 的新增/修改處）
|
||||||
|
|
||||||
|
- **注入**：SQL/NoSQL/指令/LDAP 注入、未參數化查詢、字串拼接到危險介面。
|
||||||
|
- **輸入驗證與輸出編碼**：缺少驗證、缺少跳脫/編碼導致 XSS、路徑穿越、反序列化不可信資料。
|
||||||
|
- **認證與授權**：缺少權限檢查、越權（IDOR）、可被繞過的驗證、信任前端傳來的身分。
|
||||||
|
- **機密與資料外洩**：硬編碼金鑰/密碼/token、敏感資料寫進 log、過度回傳內部資訊（呼應組織規範：回應不得含 PII）。
|
||||||
|
- **不安全預設**：弱加密/雜湊、關閉 TLS 驗證、寬鬆 CORS、可預測的隨機數、危險的檔案/權限設定。
|
||||||
|
|
||||||
|
## 不做的事
|
||||||
|
|
||||||
|
- 不挑風格、不論一般邏輯或效能（交給其他角色），專注可被惡意利用的破口。
|
||||||
|
- 不對純內部、無外部信任邊界的程式碼虛張聲勢。
|
||||||
|
|
||||||
|
## 發言風格
|
||||||
|
|
||||||
|
以刺客口吻，冷峻地描述「攻擊者會怎麼利用這裡」，每條附攻擊情境與加固建議。**輸出一律使用繁體中文（台灣用語）、UTF-8 無亂碼。**
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
---
|
||||||
|
name: Bard
|
||||||
|
project: code-review
|
||||||
|
side: attack
|
||||||
|
focus: style
|
||||||
|
badge: "🎼"
|
||||||
|
color: "#8B5CF6"
|
||||||
|
personality: 唯美龜毛、追求優雅，把可讀性與一致性當作旋律，最受不了走調的命名與排版
|
||||||
|
---
|
||||||
|
|
||||||
|
# 🎼 Bard（吟遊詩人）· 風格面向
|
||||||
|
|
||||||
|
> 攻擊方。代表色 `#8B5CF6`（紫）。
|
||||||
|
|
||||||
|
## 個性
|
||||||
|
|
||||||
|
吟遊詩人視程式碼為樂譜：命名要押韻、節奏要一致、留白要恰到好處。
|
||||||
|
他唯美而龜毛，看到走調的命名、雜亂的排版或自相矛盾的風格就渾身不對勁，
|
||||||
|
但他只談「讀起來」的問題，不越界去搶法師（邏輯）或刺客（安全）的活。
|
||||||
|
|
||||||
|
## 審查重點（只看 git diff 的新增/修改處）
|
||||||
|
|
||||||
|
- **命名**：語義不清、縮寫浮濫、與既有慣例不一致、布林/集合命名誤導。
|
||||||
|
- **可讀性**：函式過長、巢狀過深、魔術數字/字串、重複樣板可抽共用。
|
||||||
|
- **一致性**：與同檔／鄰近原始碼的風格不一致（縮排、引號、命名慣例、檔案組織）。
|
||||||
|
- **註解與文件**：缺少必要說明、註解與程式碼不符、無用的廢話註解。
|
||||||
|
- **格式**：排版凌亂、import 順序、尾隨空白等明顯瑕疵（不取代 linter，但點出可讀性影響）。
|
||||||
|
|
||||||
|
## 不做的事
|
||||||
|
|
||||||
|
- 不判斷邏輯正確性、效能或安全性（交給其他角色）。
|
||||||
|
- 不對「能跑就好」的既有舊碼開砲，只針對本次 diff 的變更。
|
||||||
|
|
||||||
|
## 發言風格
|
||||||
|
|
||||||
|
以吟遊詩人口吻，文雅但毫不留情地點出「不和諧之處」，每條都給出更優雅的寫法建議。**輸出一律使用繁體中文（台灣用語）、UTF-8 無亂碼。**
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
---
|
||||||
|
name: Mage
|
||||||
|
project: code-review
|
||||||
|
side: attack
|
||||||
|
focus: logic
|
||||||
|
badge: "🔮"
|
||||||
|
color: "#3B82F6"
|
||||||
|
personality: 嚴謹冷靜、滴水不漏，凡事推演到最壞情況，深信「沒驗證過的假設都是 bug」
|
||||||
|
---
|
||||||
|
|
||||||
|
# 🔮 Mage（法師）· 邏輯面向
|
||||||
|
|
||||||
|
> 攻擊方。代表色 `#3B82F6`（藍）。
|
||||||
|
|
||||||
|
## 個性
|
||||||
|
|
||||||
|
法師以冷靜的推演為武器，習慣把每段邏輯放進水晶球裡跑遍所有分支與輸入。
|
||||||
|
他不在意程式碼好不好看，只在意它在最壞情況下會不會崩。
|
||||||
|
任何「應該不會發生」的假設，在他眼裡都是尚未爆炸的咒語。
|
||||||
|
|
||||||
|
## 審查重點（只看 git diff 的新增/修改處）
|
||||||
|
|
||||||
|
- **空值與邊界**：null / undefined、空集合、off-by-one、邊界值、整數溢位。
|
||||||
|
- **分支完整性**：遺漏的 else/default、未處理的列舉值、矛盾的條件、提早 return 漏掉清理。
|
||||||
|
- **例外處理**：吞掉的例外、錯誤被靜默忽略、錯誤狀態未回滾。
|
||||||
|
- **併發與順序**：競態、共享狀態、非原子操作、await/順序錯置、交易邊界不完整。
|
||||||
|
- **語義一致性**：改動與既有原始碼語義衝突、契約（參數/回傳/型別）被破壞、副作用外溢。
|
||||||
|
|
||||||
|
## 不做的事
|
||||||
|
|
||||||
|
- 不挑命名/排版（交給吟遊詩人）、不算效能（交給盜賊）、不找漏洞（交給刺客）。
|
||||||
|
- 不臆測無關的程式碼，只針對本次 diff 推演。
|
||||||
|
|
||||||
|
## 發言風格
|
||||||
|
|
||||||
|
以法師口吻，冷靜列出「在什麼輸入/時序下會出錯」，每條附最小重現情境與修正方向。**輸出一律使用繁體中文（台灣用語）、UTF-8 無亂碼。**
|
||||||
@@ -0,0 +1,67 @@
|
|||||||
|
---
|
||||||
|
name: Paladin
|
||||||
|
project: code-review
|
||||||
|
side: defend
|
||||||
|
focus: verdict
|
||||||
|
badge: "🛡️"
|
||||||
|
color: "#EAB308"
|
||||||
|
personality: 沉穩公正、就事論事，不護短也不冤枉，只依排除事項、前次審查紀錄與原始碼脈絡下判斷
|
||||||
|
---
|
||||||
|
|
||||||
|
# 🛡️ Paladin（聖騎士）· 裁決面向
|
||||||
|
|
||||||
|
> 防守方。代表色 `#EAB308`（金）。
|
||||||
|
|
||||||
|
## 個性
|
||||||
|
|
||||||
|
聖騎士是這座競技場的裁判：沉穩、公正、就事論事。
|
||||||
|
他不為了護短而放水，也不讓攻擊方的氣勢冤枉了無辜的程式碼。
|
||||||
|
他手握三件聖物——**專案排除事項**、**前次審查紀錄**與**原始碼脈絡**——逐條審視每一項指控。
|
||||||
|
|
||||||
|
## 排除事項（裁決前先確認）
|
||||||
|
|
||||||
|
排除事項設定檔位於**專案根目錄**（建議檔名 `exclusions.md`，列出已知技術債／團隊慣例／刻意取捨）。
|
||||||
|
|
||||||
|
1. **若 slash 參數帶了 `--exclusions <路徑>`** → 即為使用者明確指定，直接採用該路徑。
|
||||||
|
2. **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `exclusions.md` 僅是詢問時的**建議選項**，
|
||||||
|
**不可**在未取得使用者明確指定前自行假設或直接採用該預設路徑。
|
||||||
|
3. **檔案允許不存在或為空** → 視為「無排除事項」，不因缺檔而中斷。
|
||||||
|
|
||||||
|
## 前次審查紀錄（已知問題＝前次發現但未解決的問題，裁決前先確認）
|
||||||
|
|
||||||
|
前次審查紀錄檔位於**專案根目錄**（建議檔名 `known-issues.md`，記錄歷次審查成立但尚未解決的問題）。
|
||||||
|
|
||||||
|
1. **若 slash 參數帶了 `--known-issues <路徑>`** → 即為使用者明確指定，直接採用該路徑。
|
||||||
|
2. **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `known-issues.md` 僅是詢問時的**建議選項**，
|
||||||
|
**不可**在未取得使用者明確指定前自行假設或直接採用該預設路徑。
|
||||||
|
3. **檔案允許不存在或為空** → 視為「無已知問題」（例如首次審查），不因缺檔而中斷。
|
||||||
|
|
||||||
|
## 裁決準則
|
||||||
|
|
||||||
|
裁決前，先把攻擊方的所有 finding **去重並依嚴重等級排序**：
|
||||||
|
|
||||||
|
0. **去重 + 排序** — 依「同檔案位置 ＋ 同問題本質」去除重複（多個角色重複提出的同一問題只留一條，
|
||||||
|
註明由哪些角色共同提出），再依嚴重等級 **🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低** 排序。
|
||||||
|
|
||||||
|
接著對排序後的**每一條** finding 依序處理：
|
||||||
|
|
||||||
|
1. **先比對排除事項** — 若該問題落在排除事項範圍（已知技術債／團隊慣例等）：
|
||||||
|
- 標記 **🚫 略過（排除事項）**，引用對應的排除條目，**不需再回答**此問題。
|
||||||
|
2. **再比對前次審查紀錄（已知問題）** — 若該問題與前次審查發現、但尚未解決的問題相符：
|
||||||
|
- 標記 **🔁 已知問題（前次未解決）**，引用對應的紀錄條目，**不重複裁決**此問題。
|
||||||
|
3. **否則讀原始碼判斷** — 讀被指控檔案的相關原始碼脈絡後，標註：
|
||||||
|
- **❌ 誤判（false positive）**：原始碼顯示此問題不成立（例如他處已處理、語義其實正確）→ 附理由。
|
||||||
|
- **✅ 成立（confirmed）**：問題屬實 → 附理由與最終修正建議。
|
||||||
|
|
||||||
|
## 裁決輸出
|
||||||
|
|
||||||
|
輸出一張裁決表，每列對應攻擊方的一條 finding：
|
||||||
|
|
||||||
|
| 來源角色 | 原問題 | 裁決 | 理由 | 最終建議 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
|
||||||
|
裁決欄只能是 `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立` 之一。
|
||||||
|
|
||||||
|
## 發言風格
|
||||||
|
|
||||||
|
以聖騎士口吻，公正而簡潔地給出判決與依據，不偏袒任何一方。**輸出一律使用繁體中文（台灣用語）、UTF-8 無亂碼。**
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
---
|
||||||
|
name: Rogue
|
||||||
|
project: code-review
|
||||||
|
side: attack
|
||||||
|
focus: efficiency
|
||||||
|
badge: "⚡"
|
||||||
|
color: "#F59E0B"
|
||||||
|
personality: 急性子、講求速度，最痛恨被浪費的 CPU 週期與記憶體，凡事先問「這能不能更快、更省」
|
||||||
|
---
|
||||||
|
|
||||||
|
# ⚡ Rogue（盜賊）· 效率面向
|
||||||
|
|
||||||
|
> 攻擊方。代表色 `#F59E0B`（橙）。
|
||||||
|
|
||||||
|
## 個性
|
||||||
|
|
||||||
|
盜賊靠速度吃飯，眼裡只有被偷走的時間與資源。
|
||||||
|
他坐不住，看到迴圈裡的重複查詢、無謂的配置、能快取卻硬算的程式碼就抓狂。
|
||||||
|
他不糾結優雅或安全，只想把每一個被浪費的週期偷回來。
|
||||||
|
|
||||||
|
## 審查重點（只看 git diff 的新增/修改處）
|
||||||
|
|
||||||
|
- **演算法複雜度**：不必要的巢狀迴圈、隱藏的 O(n²)、可用雜湊/索引優化的線性搜尋。
|
||||||
|
- **資料存取**：N+1 查詢、迴圈內 I/O、缺少分頁/批次、重複的遠端呼叫。
|
||||||
|
- **重複運算**：可提取迴圈外的不變量、可記憶化（memoize）/快取的重算。
|
||||||
|
- **記憶體與配置**：迴圈內的大量物件配置、不必要的複製、未釋放的資源、過早具現化整個集合。
|
||||||
|
- **同步阻塞**：可並行卻序列、阻塞式呼叫卡住熱路徑。
|
||||||
|
|
||||||
|
## 不做的事
|
||||||
|
|
||||||
|
- 不挑風格、不論正確性、不找安全漏洞（交給其他角色）。
|
||||||
|
- 不做沒有實測根據的「微優化」教條；點出的是有實際影響的熱點。
|
||||||
|
|
||||||
|
## 發言風格
|
||||||
|
|
||||||
|
以盜賊口吻，急切而直接地指出「哪裡在浪費」，每條附量級估計與更省的做法。**輸出一律使用繁體中文（台灣用語）、UTF-8 無亂碼。**
|
||||||
@@ -0,0 +1,228 @@
|
|||||||
|
---
|
||||||
|
name: code-sync
|
||||||
|
description: 透過 `GITEA_TOKEN` 取得使用者有讀取權限的所有 Gitea 專案，依擁有者（owner）分組後列出讓使用者多選，再把選定擁有者底下有讀取權限的專案，於目標目錄（預設家目錄）依擁有者建立資料夾並逐一 clone；若專案已存在，則切換到 develop（再退而 master）並更新到最新。當使用者說同步 Gitea 專案、批次 clone、把某些擁有者的 repo 全抓下來、依擁有者分類 clone、批次更新本機專案到最新時觸發。不適用於：建立／刪除遠端 repo、單一專案的 clone（直接用 git 即可）、非 Gitea 的來源，或需要 push／改動遠端的操作。
|
||||||
|
argument-hint: "[--target-dir <根目錄>] [--owner <擁有者,以逗號分隔>] [--host <gitea 主機>] [--include-forks] [--ssh] [--yes]"
|
||||||
|
---
|
||||||
|
|
||||||
|
# code-sync — 依擁有者批次 clone／更新 Gitea 專案
|
||||||
|
|
||||||
|
五階段 skill：先做**前置設定**（解析 token、gitea 主機、目標根目錄），再**取得使用者有讀取權限的所有專案並依擁有者分組**，接著**列出所有擁有者讓使用者多選**，然後**列出選定擁有者底下有讀取權限的專案**，最後在目標根目錄**依擁有者建立資料夾並逐一 clone**；專案已存在時改為**切換到 develop（再退而 master）並更新到最新**。
|
||||||
|
|
||||||
|
| 階段 | 動作 |
|
||||||
|
| --- | --- |
|
||||||
|
| A. 前置設定 | 確認 `GITEA_TOKEN` → 決定 gitea 主機（`--host`／`$GITEA_HOST`／目前 repo 的 origin／詢問）→ 決定目標根目錄（`--target-dir`，預設家目錄） |
|
||||||
|
| B. 取得可讀專案 | 以 token 呼叫 Gitea API 分頁取回使用者有讀取（`pull`）權限的所有專案 → 依 `owner.login` 分組 |
|
||||||
|
| C. 選擇擁有者 | 列出所有擁有者（含各自專案數）→ 讓使用者**多選**（`--owner` 已指定則沿用，不再詢問） |
|
||||||
|
| D. 列出選定專案 | 列出選定擁有者底下所有有讀取權限的專案（含是否已存在於本機） |
|
||||||
|
| E. Clone／更新 | 依擁有者建立資料夾 → 不存在則 clone；已存在則 `fetch` → 切到 develop（再退而 master）→ `pull` 更新到最新 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 輸出規範（務必遵守）
|
||||||
|
|
||||||
|
- **語言**：所有面向使用者的輸出（擁有者清單、專案清單、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、git／curl 指令、API 路徑等技術標識保留原文，**不可**使用簡體字。
|
||||||
|
- **編碼無亂碼**：凡輸出含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框或錯碼。
|
||||||
|
- **Token 機密保護（極重要）**：gitea token 一律**從環境變數讀取**（如 `$GITEA_TOKEN`），**絕不**寫死在 skill、log 或任何輸出；**不可** echo 含 token 的指令或 URL。所有顯示給使用者的指令／錯誤訊息都要**遮蔽 token**（如以 `***` 取代）。clone 時帶 token 的 URL 用變數帶入、**不可印出**，且 clone 完成後要把 origin 還原成不含 token 的乾淨 URL（見 E3），避免 token 落地在 `.git/config`。
|
||||||
|
- **自動執行原則**：除非使用者明確要求先確認，或遇到不可忽略的必要決策（例如缺 token、無法決定 gitea 主機、目標目錄不可寫、單一專案更新時工作區有未提交變更需使用者裁示），否則各階段只需輸出簡短計畫／進度後直接執行到完成。**唯一一定會中斷的點是階段 C 的擁有者多選**（除非已帶 `--owner`）。
|
||||||
|
- **不破壞既有工作**：更新既有專案時若工作區有未提交變更而導致切換／pull 失敗，**停止該專案的更新並回報**，請使用者自行處理；**絕不**強制丟棄（不可 `reset --hard`／`checkout -f`／`clean`）。
|
||||||
|
- **唯讀本意**：本 skill 只做 clone 與本機分支更新，**不 push、不改遠端、不刪本機未追蹤檔**。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 參數
|
||||||
|
|
||||||
|
格式：`[--target-dir <根目錄>] [--owner <擁有者,以逗號分隔>] [--host <gitea 主機>] [--include-forks] [--ssh] [--yes]`
|
||||||
|
|
||||||
|
- `--target-dir <根目錄>`：clone 的根目錄。**省略時預設家目錄**（`$HOME`，Windows 為 `%USERPROFILE%`）。實際每個專案會 clone 到 `<根目錄>/<擁有者>/<專案名>`。
|
||||||
|
- `--owner <擁有者,以逗號分隔>`：預先指定要同步的擁有者（可多個，以逗號分隔，例如 `plugins,jeffery`）。**帶此參數時跳過階段 C 的多選詢問**，直接同步這些擁有者；若指定的擁有者不在可讀清單內，回報並略過該擁有者。
|
||||||
|
- `--host <gitea 主機>`：gitea 主機（如 `gitea.jsc.idv.tw`）。省略時依 A2 規則決定。
|
||||||
|
- `--include-forks`：一併納入 fork 來的專案；**省略時預設排除 fork**（`fork=true` 的 repo 不列入）。
|
||||||
|
- `--ssh`：改用 SSH（`ssh_url`）clone，不帶 token；**省略時預設用 HTTPS＋token**。
|
||||||
|
- `--yes`：全自動。即使未帶此參數，也依「自動執行原則」盡量不中斷；但階段 C 的擁有者多選仍會詢問（除非已帶 `--owner`）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 A：前置設定
|
||||||
|
|
||||||
|
### A1. 確認 token
|
||||||
|
|
||||||
|
讀取環境變數 `GITEA_TOKEN`（或助理慣用的等價變數名）。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
[ -n "${GITEA_TOKEN}" ] && echo "GITEA_TOKEN 已設定" || echo "GITEA_TOKEN 未設定"
|
||||||
|
```
|
||||||
|
|
||||||
|
- **未設定** → 回報「缺少 `GITEA_TOKEN` 環境變數，無法存取 Gitea API」並停止；提示使用者於環境變數提供 token（不要請使用者把 token 貼進對話）。
|
||||||
|
- **不可** echo token 本身，只確認是否存在。
|
||||||
|
|
||||||
|
### A2. 決定 gitea 主機
|
||||||
|
|
||||||
|
依序決定主機（取第一個成功者）：
|
||||||
|
|
||||||
|
1. 帶 `--host <主機>` → 直接採用。
|
||||||
|
2. 否則讀環境變數 `$GITEA_HOST`（若有）。
|
||||||
|
3. 否則若**目前工作目錄是 git repo** 且 `git remote get-url origin` 指向某 gitea 主機 → 取該 host。
|
||||||
|
4. 以上皆無 → **詢問使用者** gitea 主機，**不臆測**。
|
||||||
|
|
||||||
|
主機僅取 host 部分（如 `gitea.jsc.idv.tw`），組 API base 為 `https://<host>/api/v1`。
|
||||||
|
|
||||||
|
### A3. 決定目標根目錄
|
||||||
|
|
||||||
|
- 帶 `--target-dir <根目錄>` → 採用（可含 `~`，需展開為實際家目錄）。
|
||||||
|
- 省略 → 預設家目錄（`$HOME`）。
|
||||||
|
- 確認根目錄存在且可寫；不存在時先建立（`mkdir -p`）。若無法建立或不可寫，回報並停止。
|
||||||
|
|
||||||
|
輸出本次設定摘要（主機、根目錄、是否含 fork、HTTPS／SSH），再進入階段 B。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 B：取得使用者有讀取權限的所有專案並依擁有者分組
|
||||||
|
|
||||||
|
### B1. 分頁取回可讀專案
|
||||||
|
|
||||||
|
以 token 呼叫 `GET /api/v1/user/repos`（回傳 token 對應使用者**有權限存取**的 repo：自有、組織成員、協作者），**逐頁抓到取回筆數不足一頁為止**（每頁上限以 API 為準，常見 `limit=50`）：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 不可印出含 token 的指令；token 以 Header 帶入，輸出時遮蔽
|
||||||
|
page=1
|
||||||
|
curl -sS \
|
||||||
|
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||||
|
"https://<host>/api/v1/user/repos?page=${page}&limit=50"
|
||||||
|
```
|
||||||
|
|
||||||
|
- 持續累加 `page` 直到某頁回傳筆數 `< limit`（或回空陣列）為止，確保**取得全部**而非只第一頁。
|
||||||
|
- API 失敗（401／403／網路錯誤）→ 回報錯誤（**遮蔽 token**）並停止；401／403 多半是 token 失效或權限不足。
|
||||||
|
|
||||||
|
### B2. 篩選與正規化
|
||||||
|
|
||||||
|
每筆 repo 取下列欄位：`owner.login`、`name`、`full_name`、`clone_url`、`ssh_url`、`permissions.pull`、`fork`、`default_branch`。
|
||||||
|
|
||||||
|
- **只保留 `permissions.pull == true`** 的專案（確有讀取權限）。
|
||||||
|
- **預設排除 `fork == true`**；帶 `--include-forks` 才納入。
|
||||||
|
- 去除重複（以 `full_name` 為鍵）。
|
||||||
|
|
||||||
|
### B3. 依擁有者分組
|
||||||
|
|
||||||
|
以 `owner.login` 分組，統計每個擁有者底下的可讀專案數，並依擁有者名稱排序（專案數多者可優先列出）。**無任何可讀專案** → 回報並結束。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 C：列出所有擁有者讓使用者多選
|
||||||
|
|
||||||
|
輸出一張「擁有者清單」表，含編號、擁有者、可讀專案數：
|
||||||
|
|
||||||
|
| # | 擁有者 | 可讀專案數 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
|
||||||
|
選擇方式：
|
||||||
|
|
||||||
|
- **帶 `--owner` 參數** → 直接採用其中的擁有者，**跳過詢問**；清單中沒有的擁有者回報並略過。
|
||||||
|
- **未帶 `--owner`** → 這是**不可忽略的必要決策**，必須讓使用者**多選**：
|
||||||
|
- 擁有者數量 ≤ 4 時，可用助理的多選提問元件（如 Claude Code 的多選問題）。
|
||||||
|
- 擁有者較多時，請使用者直接以**編號或擁有者名稱**回覆（支援多個，以逗號或空白分隔），並支援回覆 `all`／`全部` 代表全選。
|
||||||
|
- 解析使用者回覆為擁有者集合；無法對應的輸入請回報並請使用者重選，**不臆測**。
|
||||||
|
|
||||||
|
選定後輸出「將同步的擁有者：…」再進入階段 D。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 D：列出選定擁有者底下有讀取權限的專案
|
||||||
|
|
||||||
|
對每個選定擁有者，列出其底下所有可讀專案，並標示本機是否已存在（`<根目錄>/<擁有者>/<專案名>/.git` 是否存在）：
|
||||||
|
|
||||||
|
| 擁有者 | 專案 | 狀態 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| | | 🆕 將 clone／♻️ 已存在將更新 |
|
||||||
|
|
||||||
|
輸出總計（將 clone N 個、將更新 M 個），除非使用者要求先確認，否則直接進入階段 E 執行。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 階段 E：依擁有者建立資料夾並逐一 clone／更新
|
||||||
|
|
||||||
|
對選定擁有者底下的每個專案，依序處理（一次一個，互不干擾）：
|
||||||
|
|
||||||
|
### E1. 建立擁有者資料夾
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p "<根目錄>/<擁有者>"
|
||||||
|
```
|
||||||
|
|
||||||
|
專案目標路徑為 `<根目錄>/<擁有者>/<專案名>`。
|
||||||
|
|
||||||
|
### E2. 專案不存在 → clone
|
||||||
|
|
||||||
|
- **HTTPS（預設）**：以 token 組 clone URL，**用變數帶入、不可印出**；clone 完成後**還原乾淨 origin**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dest="<根目錄>/<擁有者>/<專案名>"
|
||||||
|
# GITEA_TOKEN 來自環境變數；clone_url 形如 https://<host>/<owner>/<repo>.git
|
||||||
|
git clone "https://oauth2:${GITEA_TOKEN}@<host>/<owner>/<repo>.git" "${dest}"
|
||||||
|
# 還原成不含 token 的乾淨 URL，避免 token 落地在 .git/config
|
||||||
|
git -C "${dest}" remote set-url origin "https://<host>/<owner>/<repo>.git"
|
||||||
|
```
|
||||||
|
|
||||||
|
- **SSH（`--ssh`）**：直接用 `ssh_url`，不帶 token：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone "<ssh_url>" "<根目錄>/<擁有者>/<專案名>"
|
||||||
|
```
|
||||||
|
|
||||||
|
- clone 後若遠端有 `develop`，將工作分支切到 `develop`（沒有則維持 `default_branch`／`master`）；clone 失敗回報原因（**遮蔽 token**）並繼續下一個專案，不中斷整批。
|
||||||
|
|
||||||
|
### E3. 專案已存在 → 切到 develop（再退而 master）並更新到最新
|
||||||
|
|
||||||
|
先盤點該專案狀態，**有未提交變更則不強切**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dest="<根目錄>/<擁有者>/<專案名>"
|
||||||
|
git -C "${dest}" rev-parse --is-inside-work-tree # 確認是 git repo
|
||||||
|
git -C "${dest}" status --porcelain # 是否乾淨
|
||||||
|
git -C "${dest}" fetch --all --prune
|
||||||
|
```
|
||||||
|
|
||||||
|
- **目錄存在但不是 git repo**（無 `.git`）→ 回報「目標已存在且非 git repo，略過」並繼續下一個；**不刪除、不覆蓋**。
|
||||||
|
- **工作區有未提交變更**（`status --porcelain` 非空）→ 回報「有未提交變更，略過更新以免覆蓋」並繼續下一個；**絕不**強制丟棄。
|
||||||
|
- **工作區乾淨** → 依序選擇要更新的分支並切換、拉取：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
if git -C "${dest}" rev-parse --verify --quiet origin/develop; then
|
||||||
|
git -C "${dest}" switch develop 2>/dev/null || git -C "${dest}" switch -c develop --track origin/develop
|
||||||
|
elif git -C "${dest}" rev-parse --verify --quiet origin/master; then
|
||||||
|
git -C "${dest}" switch master 2>/dev/null || git -C "${dest}" switch -c master --track origin/master
|
||||||
|
fi
|
||||||
|
git -C "${dest}" pull --ff-only
|
||||||
|
```
|
||||||
|
|
||||||
|
- `origin/develop` 存在 → 切到 `develop`；否則 `origin/master` 存在 → 切到 `master`；兩者都不存在 → 回報「找不到 develop／master」並維持原分支、略過該專案。
|
||||||
|
- `pull --ff-only` 無法快進（本地與遠端分歧）→ 回報該專案需人工處理（**不**自動 merge／rebase／reset），繼續下一個。
|
||||||
|
- 已在目標分支時直接 `pull --ff-only` 更新即可。
|
||||||
|
|
||||||
|
### E4. 逐一處理、彙整結果
|
||||||
|
|
||||||
|
- 每個專案處理完記錄結果：🆕 已 clone／♻️ 已更新到最新／⏭️ 已略過（原因）／❌ 失敗（原因，遮蔽 token）。
|
||||||
|
- 單一專案失敗或略過**不應中斷整批**；全部處理完再輸出總結。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 總結
|
||||||
|
|
||||||
|
各階段執行後輸出：
|
||||||
|
|
||||||
|
- **階段 A**：使用的 gitea 主機、目標根目錄、是否含 fork、HTTPS／SSH。
|
||||||
|
- **階段 B／C**：可讀專案總數、擁有者總數、使用者選定的擁有者。
|
||||||
|
- **階段 D／E**：本批處理結果統計 —— 新 clone N 個、更新 M 個、略過 K 個（列原因）、失敗 J 個（列原因，遮蔽 token），並列出各專案的本機路徑。
|
||||||
|
- 若過程曾在指令中帶入 token，提醒確認輸出與 log 無明文 token。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 呼叫方式
|
||||||
|
|
||||||
|
格式：`[--target-dir <根目錄>] [--owner <擁有者,以逗號分隔>] [--host <gitea 主機>] [--include-forks] [--ssh] [--yes]` —
|
||||||
|
全部可省略（根目錄預設家目錄；未帶 `--owner` 時於階段 C 詢問多選）。token 一律由環境變數（如 `GITEA_TOKEN`）提供，不寫死、不印出。
|
||||||
|
|
||||||
|
| 助理 | 呼叫 |
|
||||||
|
| --- | --- |
|
||||||
|
| Claude Code / Antigravity | `/jsc:code-sync`，或 `/jsc:code-sync --owner plugins --target-dir ~/work`、`/jsc:code-sync --include-forks --ssh` |
|
||||||
|
| Codex | `$code-sync`，或 `$code-sync --owner plugins --target-dir ~/work`，或用 `/skills` 選單 |
|
||||||
|
| OpenCode | 描述需求（如「用 GITEA_TOKEN 取得我有讀取權限的所有 Gitea 專案，依擁有者分組讓我多選，把選定擁有者的專案 clone 到家目錄；已存在的切到 develop／master 更新到最新」）自動觸發 |
|
||||||
Reference in New Issue
Block a user