Merge pull request '更新版本號至 0.2.0 並補強 code-review-resolve 盤點規則' (#35) from develop into master

Reviewed-on: #35
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "JSC 程式碼審查 plugin（Claude Code / Codex / Antigravity / OpenCode），提供 RPG 攻防式 git diff review、裁決結果歸檔、Gitea AI review findings 修復/PR 流程，以及 C# / .NET NuGet 套件更新流程；於 Claude Code 以 /jsc: 前綴呼叫。",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "JSC 程式碼審查 plugin，提供 RPG 攻防式 git diff review、裁決結果歸檔、Gitea AI review findings 修復/PR 流程，以及 C# / .NET NuGet 套件更新流程。",
   "skills": "./skills"
 }

README.md

@@ -41,7 +41,11 @@ code-review/
 │   │   └── roles/           # 一角色一檔（bard/mage/rogue/assassin/paladin）
 │   ├── code-review-archive/ # 保存裁決：成立→已知問題、誤判→排除事項
 │   ├── code-review-resolve/ # 解決 findings.json + 分類提交 + push + 發 PR
-│   └── code-review-nuget/   # C# / .NET NuGet 套件更新 + build 驗證
+│   ├── code-review-nuget/   # C# / .NET NuGet 套件更新 + build 驗證
+│   ├── code-review-sync/    # 依擁有者批次 clone／更新 Gitea 專案
+│   ├── code-review-action-docker/    # action 容器化（Node 主程式）+ 串接 doc-funcs
+│   ├── code-review-action-composite/ # composite action 標準化 + 串接 doc-funcs
+│   └── code-review-image/            # Dockerfile 整理成六步流程 + 串接 doc-funcs
 ├── AGENTS.md                # 跨助理共用指引
 └── README.md
 ```
@@ -189,9 +193,9 @@ rm -rf ~/.config/opencode/skills/code-review
 
 ### `code-review-resolve`
 
-四階段：**(A 解決)** 讀工作目錄 `.gitea/ai-review/findings.json`（Gitea AI review 產出的問題清單），依嚴重等級 **🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低** 由高到低**逐條修復**程式碼問題（無法安全自動修復者標「待人工處理」不硬改），全部處理完把 `findings.json` 清空為空陣列 `[]`。**(B 提交)** 分析工作區**所有**變更，依異動內容歸類為 `feat`/`fix`/`docs`/`style`/`refactor`/`perf`/`test`/`chore`/`revert`，**每個 type 各自一個 commit**，訊息為「`type(範圍): 一句總結`」格式，**括號內的範圍須對應實際異動的功能／模組**（例 `feat(使用者登入): 新增帳密登入流程`、`perf(物件查詢): 改用批次查詢降低 DB 往返`，而非 `feat(新增功能)` 這類重述 type 的詞）。**(C 推送)** push 當前分支：先用**認證管理器**、失敗改用 **token**、再失敗**詢問使用者**。**(D 開 PR)** 用 token 透過 **Gitea API** 對目標分支發 PR（**目標分支不明必須詢問、不可猜測**），PR 描述可選**完整版**（重新分析 `git diff` 總結）／**簡單版**（逐條列 commit 訊息）／**使用者輸入**；完成後因內文可能含 gitea token，**提醒並清除 AI 助理對話內文**。修改程式碼／commit／push／開 PR 前先輸出計畫並取得同意（`--yes` 可略過）；token 一律由環境變數（如 `GITEA_TOKEN`）提供，全程不明文輸出。
+五階段：**(A Git 同步)** 先 `fetch`，務必檢查目前分支的線上分支是否存在；存在則留在目前分支更新到最新，不存在則依序切換到遠端 `develop`／`master` 並更新到最新，找不到後備分支則停止；pull 發生衝突時告知並嘗試安全解衝突；只有來源分支與 PR 目標分支相同時，才必須從該分支建立新的工作分支，後續修復、commit、push 與 PR `head` 都使用新分支。**(B 解決)** 讀工作目錄 `.gitea/ai-review/findings.json`（Gitea AI review 產出的問題清單），依嚴重等級 **🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低** 由高到低**逐條修復**程式碼問題或登記誤報（無法安全自動修復者標「待人工處理」不硬改），已解決或已登記誤報者才自 `findings.json` 移除。**(C 提交)** 分析工作區**所有**變更，依異動內容歸類為 `feat`/`fix`/`docs`/`style`/`refactor`/`perf`/`test`/`chore`/`revert`，**每個 type 各自一個 commit**，訊息為「`type(範圍): 一句總結`」格式，**括號內的範圍須對應實際異動的功能／模組**（例 `feat(使用者登入): 新增帳密登入流程`、`perf(物件查詢): 改用批次查詢降低 DB 往返`，而非 `feat(新增功能)` 這類重述 type 的詞）。**(D 推送)** push 當前分支：先用**認證管理器**、失敗改用 **token**、再失敗**詢問使用者**。**(E 開 PR)** 用 token 透過 **Gitea API** 對目標分支發 PR（**目標分支不明必須詢問、不可猜測**），PR 描述可選**完整版**（重新分析 `git diff` 總結）／**簡單版**（逐條列 commit 訊息）／**使用者輸入**；完成後因內文可能含 gitea token，**提醒並清除 AI 助理對話內文**。除非遇到必要決策，否則依自動執行原則直接處理；token 一律由環境變數（如 `GITEA_TOKEN`）提供，全程不明文輸出。
 
-參數：`[--findings <findings.json 路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]`（findings 省略時預設 `.gitea/ai-review/findings.json`；`--target` 省略時於開 PR 階段必問；`--no-commit` 只修復不提交；`--no-pr` 推送但不開 PR；`--yes` 略過確認）。
+參數：`[--findings <findings.json 路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]`（findings 省略時預設 `.gitea/ai-review/findings.json`；`--target` 省略且需要開 PR 時必問；`--no-commit` 只修復不提交；`--no-pr` 推送但不開 PR；`--yes` 略過確認）。
 
 - **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 simple --yes`，或用 `/skills` 選單
@@ -207,6 +211,46 @@ rm -rf ~/.config/opencode/skills/code-review
 - **Codex**：`$code-review-nuget`，或 `$code-review-nuget src/App/App.csproj --build "dotnet build App.sln -c Release"`，或用 `/skills` 選單
 - **OpenCode**：描述需求（如「把這個 .NET solution 的 NuGet 都更新到最新，先清掉 ProjectReference 已提供的重複套件，每更新一包就 build」）自動觸發
 
+### `code-review-sync`
+
+透過 `GITEA_TOKEN` 把使用者有讀取權限的 Gitea 專案批次 clone 到本機並依擁有者分類。流程會先確認 token、決定 gitea 主機與目標根目錄（預設家目錄），再以 token 分頁呼叫 `GET /api/v1/user/repos` 取回**所有有讀取權限**的專案、依 `owner` 分組（預設排除 fork）；接著列出所有擁有者讓使用者**多選**（帶 `--owner` 則跳過詢問），列出選定擁有者底下的專案後，於 `<根目錄>/<擁有者>/<專案名>` 逐一處理：**不存在則 clone**（HTTPS＋token，clone 後還原乾淨 origin；或 `--ssh`），**已存在則 `fetch` → 切到 develop（再退而 master）→ `pull --ff-only` 更新到最新**。全程唯讀（不 push、不改遠端），工作區有未提交變更的專案會略過而非強制覆蓋；token 一律由環境變數提供、不寫死也不印出。
+
+參數：`[--target-dir <根目錄>] [--owner <擁有者,以逗號分隔>] [--host <gitea 主機>] [--include-forks] [--ssh] [--yes]`（根目錄預設家目錄；`--owner` 預先指定擁有者並跳過多選；`--host` 指定 gitea 主機；`--include-forks` 納入 fork；`--ssh` 改用 SSH clone；`--yes` 略過一般確認但不略過擁有者多選）。
+
+- **Claude Code / Antigravity**：`/jsc:code-review-sync`，或 `/jsc:code-review-sync --owner plugins --target-dir ~/work`、`/jsc:code-review-sync --include-forks --ssh`
+- **Codex**：`$code-review-sync`，或 `$code-review-sync --owner plugins --target-dir ~/work`，或用 `/skills` 選單
+- **OpenCode**：描述需求（如「用 GITEA_TOKEN 取得我有讀取權限的所有 Gitea 專案，依擁有者分組讓我多選，把選定擁有者的專案 clone 到家目錄；已存在的切到 develop／master 更新到最新」）自動觸發
+
+### `code-review-action-docker`
+
+把 Gitea／GitHub「Docker 容器 action」專案標準化為 **Node 主程式＋容器化**，再串接文件化流程。五階段：(A) 找出 action 專案、讀 `action.yml`／`action.yaml` 的 `name`／`description`、判斷主程式語言；(B) 主程式**非 Node 則保守改寫為 Node**（高風險，先以 AskUserQuestion 確認，保留對外行為），並把所有 `.js` 集中到 **`src/`**、同步更新 `require`／`import` 路徑、`package.json` 與 `action.yml`；(C) 產生 `entrypoint.sh`，**啟動 node 前先輸出 action 名稱／用途／更新時間**（Asia/Taipei `yyyy/MM/dd HH:mm:ss`）再 `exec node`；(D) 依**六步流程**（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口）產生**使用最新 node 版本**的 `Dockerfile`，**每步內容依主程式（`src/`）實作量身決定**（先盤點相依／是否需 build／OS 層相依／入口檔再填對應步驟，用不到的不硬塞），預設 build 基底 `node:latest`、runtime `node:slim`、**多階段建置縮小映像**，`ENTRYPOINT` 指向 `entrypoint.sh`；(E) 對整個專案**完整執行 `/jsc:doc-funcs`**（function 文件、`entrypoint.sh`／`Dockerfile` 逐行註解、重建 README）。
+
+參數：`[--action-dir <action 根目錄>] [--node-version <node tag>] [--main <主程式檔>] [--yes]`（根目錄預設目前工作目錄；node 版本預設最新；主程式自動判斷；`--yes` 略過一般確認，但主程式改寫與 doc-funcs 的實作詢問仍會中斷）。
+
+- **Claude Code / Antigravity**：`/jsc:code-review-action-docker`，或 `/jsc:code-review-action-docker --action-dir ~/work/my-action --node-version 22`
+- **Codex**：`$code-review-action-docker`，或 `$code-review-action-docker --action-dir ~/work/my-action`，或用 `/skills` 選單
+- **OpenCode**：描述需求（如「把這個 action 主程式改成 node、所有 js 收進 src/，產生會先輸出 action 名稱／用途／更新時間再啟動 node 的 entrypoint.sh、用最新 node 版本的 Dockerfile，最後跑 doc-funcs 補文件並重建 README」）自動觸發
+
+### `code-review-action-composite`
+
+把 Gitea／GitHub「composite action」專案標準化，再串接文件化流程。四階段：(A) 找出 action 專案、讀 `action.yml`／`action.yaml` 的 `name`／`description`／`runs`、判斷是否為 composite；(B) **已是 composite 則保留既有 `steps`**，非 composite（JS／Docker）則**保守確認後對齊**為 composite（高風險先以 AskUserQuestion 確認，保留 `inputs`／`outputs` 契約；Docker 行為無法等價塞入時標「需人工確認」並建議改用 `code-review-action-docker`）；(C) 在 `runs.steps` **最前面注入啟動橫幅 step**，輸出 action **名稱／用途／更新時間**（Asia/Taipei `yyyy/MM/dd HH:mm:ss`，固定字串），並於 `action.yml` 開頭補用途／更新時間註解區塊（既有橫幅 step 則更新而非重插）；(D) 對整個專案**完整執行 `/jsc:doc-funcs`**（`action.yml` 與被引用腳本逐行註解、function 文件、重建 README）。
+
+參數：`[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>] [--yes]`（根目錄預設目前工作目錄；manifest 自動尋找 `action.yml`／`action.yaml`；`--yes` 略過一般確認，但「非 composite 需對齊」與 doc-funcs 的實作詢問仍會中斷）。
+
+- **Claude Code / Antigravity**：`/jsc:code-review-action-composite`，或 `/jsc:code-review-action-composite --action-dir ~/work/my-action`
+- **Codex**：`$code-review-action-composite`，或 `$code-review-action-composite --action-dir ~/work/my-action`，或用 `/skills` 選單
+- **OpenCode**：描述需求（如「把這個 composite action 標準化，在 steps 最前面加一個會輸出 action 名稱／用途／更新時間的 step，最後跑 doc-funcs 補文件並重建 README」）自動觸發
+
+### `code-review-image`
+
+把專案既有的 `Dockerfile` **整理成固定六步流程**，再串接文件化流程。三階段：(A) 找出專案根目錄、定位目標 `Dockerfile`（找不到則詢問、**不臆造**；要產生全新 action 容器請改用 `code-review-action-docker`），讀現有指令、判斷語言／生態與既有 base image／建置流程；(B) 在**保留建置行為**前提下，把指令重整／歸位為**六步流程**（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口）：可調參數集中於檔首 `ARG`、相依描述先 `COPY` 以利 layer 快取、**多階段建置**讓 runtime 改用較小基底（`*-slim`／`*-alpine`／`distroless` 等）只帶執行所需產物；`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV` 等對外契約不動，**無法保證等價的重整先以 AskUserQuestion 確認**（可選最小重排或只補註解）；(C) 對整個專案**完整執行 `/jsc:doc-funcs`**（`Dockerfile` 等指令檔逐行註解、function 文件、重建 README）。
+
+參數：`[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes]`（專案根目錄預設目前工作目錄；Dockerfile 自動定位、多個時詢問；`--yes` 略過一般確認，但「重整無法保證行為等價」與 doc-funcs 的實作詢問仍會中斷）。
+
+- **Claude Code / Antigravity**：`/jsc:code-review-image`，或 `/jsc:code-review-image --project-dir ~/work/my-app --dockerfile build/Dockerfile`
+- **Codex**：`$code-review-image`，或 `$code-review-image --dockerfile docker/Dockerfile`，或用 `/skills` 選單
+- **OpenCode**：描述需求（如「把這個專案的 Dockerfile 整理成參數處理→安裝套件→複製檔案→執行程序→縮小映像檔→設定入口六步、用多階段建置縮小映像，最後跑 doc-funcs 補文件並重建 README」）自動觸發
+
 <!-- JSC-SKILLS:END -->
 
 ---

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "JSC 程式碼審查 plugin，提供 RPG 攻防式 git diff review、裁決結果歸檔、Gitea AI review findings 修復/PR 流程，以及 C# / .NET NuGet 套件更新流程；於 Antigravity 以 /jsc: 前綴呼叫。",
   "skills": "./skills/"
 }

skills/code-review-action-composite/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: code-review-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-review-action-composite 時觸發。不適用於：Docker 容器 action（用 code-review-action-docker）、非 action 專案、或不需文件化的一般 repo。
+argument-hint: "[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>] [--yes]"
+---
+
+# code-review-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-review-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-review-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-review-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-review-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-review-action-composite`，或 `/jsc:code-review-action-composite --action-dir ~/work/my-action` |
+| Codex | `$code-review-action-composite`，或 `$code-review-action-composite --action-dir ~/work/my-action`，或用 `/skills` 選單 |
+| OpenCode | 描述需求（如「把這個 composite action 標準化，在 steps 最前面加一個會輸出 action 名稱／用途／更新時間的 step，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |

skills/code-review-action-docker/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: code-review-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-review-action-docker 時觸發。不適用於：非 action 專案、純前端打包、或不需容器化的一般 repo。
+argument-hint: "[--action-dir <action 根目錄>] [--node-version <node tag>] [--main <主程式檔>] [--yes]"
+---
+
+# code-review-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-review-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-review-action-docker`，或 `/jsc:code-review-action-docker --action-dir ~/work/my-action --node-version 22` |
+| Codex | `$code-review-action-docker`，或 `$code-review-action-docker --action-dir ~/work/my-action`，或用 `/skills` 選單 |
+| OpenCode | 描述需求（如「把這個 action 主程式改成 node、所有 js 收進 src/，產生會先輸出 action 名稱／用途／更新時間再啟動 node 的 entrypoint.sh、用最新 node 版本的 Dockerfile，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |

skills/code-review-image/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: code-review-image
+description: 把專案的 `Dockerfile` 整理成固定六步流程並串接文件化流程：(1) 找出專案根目錄與目標 `Dockerfile`、判斷語言／生態與既有建置方式；(2) 在保留建置行為的前提下，把 `Dockerfile` 重整為 **參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口** 六步流程（以多階段建置縮小最終映像，可調參數集中於檔首 `ARG`，相依描述先 `COPY` 以利 layer 快取）；(3) 最後完整執行 `/jsc:doc-funcs` 處理流程（function 文件、`Dockerfile` 等指令檔逐行註解、重建 README）。當使用者說整理／重構 Dockerfile、把 Dockerfile 排成參數處理→安裝→複製→執行→縮小→入口六步、優化映像檔分層／多階段建置、縮小 image，或提到 code-review-image 時觸發。不適用於：Gitea／GitHub action 容器化（用 code-review-action-docker）、composite action（用 code-review-action-composite）、或專案內沒有也不需要 Dockerfile 的情況。
+argument-hint: "[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes]"
+---
+
+# code-review-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-review-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-review-image`，或 `/jsc:code-review-image --project-dir ~/work/my-app --dockerfile build/Dockerfile` |
+| Codex | `$code-review-image`，或 `$code-review-image --dockerfile docker/Dockerfile`，或用 `/skills` 選單 |
+| OpenCode | 描述需求（如「把這個專案的 Dockerfile 整理成參數處理→安裝套件→複製檔案→執行程序→縮小映像檔→設定入口六步、用多階段建置縮小映像，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |

skills/code-review-resolve/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: code-review-resolve
-description: 解決 `.gitea/ai-review/findings.json` 的 AI review findings，先同步 git（fetch → pull，必要時嘗試解衝突），再依嚴重度逐條修復；可判斷為誤報者寫入 `.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。
+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`，必要時告知並嘗試解衝突），再**逐條處理** `.gitea/ai-review/findings.json` 裡的問題；成立問題修復後自 findings 移除，可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json` 後也可自 findings 移除，接著把工作區所有變更**依 conventional commit 類型分門別類 commit**，然後 **push 當前分支**，最後**透過 Gitea API 發 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` → `git pull` → 若有衝突則告知並嘗試解衝突 |
+| A. Git 同步 | `git fetch` → 當前分支不在遠端則切換 develop（再退而 master）→ `git pull`／必要時解衝突 → 只有來源分支與 PR 目標分支相同時才建立新工作分支 |
-| B. 解決問題 | 讀 `findings.json` / `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` 移除，誤報寫入 `exclusions.json` 後也可移除 |
+| B. 解決問題 | 讀 `findings.json` / `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` 移除，誤報寫入 `exclusions.json` 後也可移除；**無待處理問題則跳到階段 D** |
-| C. 分類提交 | 分析工作區所有變更 → 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
+| C. 分類提交 | 必須分析並涵蓋工作區所有變更（已修改／新增／刪除／改名，含已暫存與未暫存、未追蹤檔、findings/exclusions 更新）→ 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
-| D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者 |
+| D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者；**無 commit 可 push 則跳到階段 E** |
 | E. 發出 PR | 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文 |
 
 ---
@@ -68,17 +68,69 @@ git fetch --all --prune
 - fetch 失敗時回報錯誤並停止，不進入 findings 修復。
 - 若錯誤訊息可能含 credential / token，輸出前必須遮蔽。
 
-### A3. Pull 當前分支
+### 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 成功後進入階段 B。
+- pull 成功後進入 A5，必要時建立新的工作分支，再進入階段 B。
 - 若顯示需要指定 merge / rebase 策略，先回報原因；未帶 `--yes` 時詢問使用者要採用哪種策略，不可自行猜測。
-- 若 pull 產生衝突，立即告知使用者發生衝突，接著依階段 A4 嘗試解衝突。
+- 若 pull 產生衝突，立即告知使用者發生衝突，接著依階段 A6 嘗試解衝突。
 
-### A4. 必要時嘗試解衝突
+### 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` 後出現衝突：
 
@@ -86,7 +138,7 @@ git pull
 2. 讀取衝突檔脈絡，依專案現有行為與遠端變更做最小合理整合。
 3. 可安全解決的衝突：編輯檔案移除衝突標記，執行 `git add -- <檔案...>` 標記已解決。
 4. 無法安全判斷的衝突：停止處理，列出檔案、衝突原因與需要使用者決策的點；不要硬選任一邊。
-5. 全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 `git status --porcelain` 沒有未解衝突，再進入階段 B。
+5. 全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 `git status --porcelain` 沒有未解衝突，再回到 A5 判斷是否需要建立新工作分支。
 
 ---
 
@@ -132,7 +184,7 @@ git pull
 
   若既有 exclusions 使用 `suggestion`、`title`、`note` 等欄位，讀取時可容錯；寫回時仍要維持 top-level array，並盡量採用上述 canonical 欄位。
 
-- **檔案不存在、內容為 `[]` 或空白** → 視為「無問題待解決」，輸出告知並**直接跳到階段 C**（仍會把工作區既有變更分類提交，除非 `--no-commit`）。
+- **檔案不存在、內容為 `[]` 或空白** → 視為「無問題待解決」，輸出告知。`--no-commit` 時就此結束；否則**跳過階段 C 直接進入階段 D**（無待處理問題代表本 skill 未產生需要分類提交的修復變更）。
 - **JSON 解析失敗** → 回報錯誤與檔案路徑並停止，不臆測內容、不亂改檔。
 - `exclusions.json` 不存在時視為空陣列，必要時建立 `.gitea/ai-review/exclusions.json` 並寫入 `[]` 或新增後的排除項目。
 - 若 `exclusions.json` 是舊 wrapper 格式（例如 `{ "exclusions": [...] }` 或 `{ "excluded_findings": [...] }`），先正規化為 top-level array 再寫回。
@@ -185,16 +237,17 @@ canonical 等級為 `critical` / `warning` / `info`；其他寫法容錯對應
 ### C1. 盤點工作區變更
 
 ```bash
-git status --porcelain
+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 | 適用情境 |
 | --- | --- |
@@ -210,10 +263,11 @@ git diff --staged   # 已暫存變更
 
 - **同一檔案橫跨多型** → 以該檔**主要異動性質**歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
 - **階段 B 修復產生的變更**：依其性質歸類（修 bug→`fix`、補功能→`feat`、改文件→`docs`…）。`findings.json` / `exclusions.json` 的問題狀態更新歸 `chore`。
+- **未追蹤新檔**：必須照實際內容歸入對應 type，必要時在提交前明確 `git add -- <path>`，不可因為是新檔就略過。
 
 ### C3. 產出提交計畫
 
-把變更檔依 type 分組，**每個 type 一個 commit**，輸出提交計畫；除非使用者要求確認或分組有不可忽略的取捨，否則直接提交：
+把變更檔依 type 分組，**每個 type 一個 commit**，輸出提交計畫；**所有變更項目都必須被追蹤並納入計畫，不能遺漏任何 `??` 未追蹤檔**。除非使用者要求確認或分組有不可忽略的取捨，否則直接提交：
 
 | 順序 | type(範圍) | commit 訊息 | 納入檔案 |
 | --- | --- | --- | --- |
@@ -228,6 +282,7 @@ git diff --staged   # 已暫存變更
   - `一句總結`：把這個 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. 執行分類提交
 
@@ -240,23 +295,27 @@ git commit -m "type(範圍): 一句總結"   # 範圍＝實際異動的功能／
 
 - **逐組 add／commit**，確保每個 commit 只含該類異動；不要一次 `git add -A` 再混在一起。
 - 改名／刪除檔一併納入對應組的 `git add`（`git add -A -- <路徑>` 或明確列出）。
-- commit 完成後進入階段 D（push）；`--no-commit` 或無新 commit 時不進入後續階段。
+- **所有 `??` 未追蹤檔都必須納入提交**；若是新檔，必要時要明確執行 `git add -- <path>`，不可漏掉。
+- **不可只根據 `git diff` 判斷變更**；C1 盤點出的所有異動都必須反映到分類與提交，否則視為提交計畫不完整。
+- commit 完成後進入階段 D（push）。`--no-commit` 時不進入後續階段；若工作區無變更而沒有產生任何新 commit，仍進入階段 D，由 D 判斷無 commit 可 push 後跳到階段 E。
 
 ---
 
-## 階段 D：Push 當前分支（`--no-commit`／無新 commit 時略過）
+## 階段 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
 ```
 
-- 若來源分支沒有對應的 `origin/<source_branch>`，先記錄「無遠端基準」並繼續；後續若 source/base 同名，階段 E2 仍必須以 `origin/<target>` 作為帶入 commit 的比較基準。
+- **無 commit 可 push**（來源分支已存在於遠端，且相對 `origin/<source_branch>` 沒有領先 commit）→ **跳過本階段 push，直接進入階段 E**（仍可對既有遠端分支開 PR）；若帶 `--no-pr`，則就此結束。
-- 若後續會建立 PR（未帶 `--no-pr`）且尚未知道目標分支，先依階段 E1 的規則詢問目標分支，這屬於不可忽略的必要決策，避免把 commit 直接推進目標分支後才發現 source/base 相同。
+- 若來源分支沒有對應的 `origin/<source_branch>`，視為需要 push 的新分支，先記錄「無遠端基準」並繼續；這種情況不需要切回 develop／master，因為 A3 已在同步階段處理「當前分支不存在於遠端」的後備切換。
+- 若後續會建立 PR（未帶 `--no-pr`）且尚未知道目標分支，先依階段 E1 的規則詢問目標分支，這屬於不可忽略的必要決策。
 - 若來源分支名稱與目標分支相同，**不要 push 原來源分支**；記下來源分支與遠端基準，直接進入階段 E，由 E2 建立新的 PR 來源分支、帶入 commit 後再 push 新分支。
 
 1. **認證管理器（優先）**：直接用 git 既有的 credential helper（如 Windows 的 `manager-core`）：
@@ -383,10 +442,10 @@ curl -sS -X POST \
 
 各階段執行後輸出：
 
-- **階段 A**：git fetch / pull 是否成功、是否發生衝突、衝突是否已解決或仍需人工處理。
+- **階段 A**：git fetch / pull 是否成功、當前分支是否存在於遠端（不存在時切到 develop／master 的結果）、若來源分支與目標分支同名是否已建立新工作分支、是否發生衝突、衝突是否已解決或仍需人工處理。
-- **階段 B**：已解決 N 條（依等級分佈）、誤報寫入 exclusions M 條、待人工處理 K 條（列出原因）、`findings.json` 保留／移除筆數與 `exclusions.json` 新增筆數。
+- **階段 B**：已解決 N 條（依等級分佈）、誤報寫入 exclusions M 條、待人工處理 K 條（列出原因）、`findings.json` 保留／移除筆數與 `exclusions.json` 新增筆數；若無待處理問題，說明已跳過階段 C 直接進入階段 D。
 - **階段 C**：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（`--no-commit` / 無變更）。
-- **階段 D**：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名。
+- **階段 D**：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名；若無 commit 可 push，說明已跳過 push 直接進入階段 E。
 - **階段 E**：PR 連結／編號、目標分支、描述形式；並提醒已（或請使用者）清除對話內文以防 token 外洩。
 
 ---

skills/code-review-sync/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: code-review-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-review-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-review-sync`，或 `/jsc:code-review-sync --owner plugins --target-dir ~/work`、`/jsc:code-review-sync --include-forks --ssh` |
+| Codex | `$code-review-sync`，或 `$code-review-sync --owner plugins --target-dir ~/work`，或用 `/skills` 選單 |
+| OpenCode | 描述需求（如「用 GITEA_TOKEN 取得我有讀取權限的所有 Gitea 專案，依擁有者分組讓我多選，把選定擁有者的專案 clone 到家目錄；已存在的切到 develop／master 更新到最新」）自動觸發 |