feat(action skills): composite／docker action 標準化流程強化（參數優先序、從零建立、Dockerfile 修正） #6
@@ -17,32 +17,28 @@ argument-hint: "[--action-dir <action 根目錄>] [--manifest <action.yml 路徑
|
||||
|
||||
---
|
||||
|
||||
## 輸出規範（務必遵守）
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
|
||||
- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、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`）契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依「參數來源優先序」經使用者同意後為之。
|
||||
- **不擴及無關檔案**：本 skill 只動 action 專案根目錄內的：`action.yml`／`action.yaml`、其 `steps` 直接引用的內嵌腳本（如 `*.sh`／`*.ps1`），以及階段 D 由 doc-funcs 流程處理的目標；排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴。
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼。
|
||||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認、不擴及無關檔案。
|
||||
- `/jsc:spec-git-safety`：不破壞既有工作（絕不 `reset --hard`／`clean`）、`git mv` 保留歷史。
|
||||
- `/jsc:spec-action-params`：action 參數來源優先序（context → 經同意新增 `inputs`）、`secrets`／`vars` 一律視為不可用。
|
||||
- `/jsc:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、完成後統一同步時間戳。
|
||||
- `/jsc:spec-doc-funcs-handoff`：最終階段完整執行 `/jsc:doc-funcs` 的標準流程。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- **一定會中斷詢問的點**：階段 B 主 action「非 composite 需對齊」時（破壞性，須先確認），以及階段 D 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
|
||||
- **保留行為**：對齊 composite 與注入橫幅 step 只「補強」既有流程，不得擅自改變既有 `steps` 的執行順序、輸入（`inputs`）／輸出（`outputs`）契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依 `/jsc:spec-action-params` 經使用者同意後為之。
|
||||
- **本 skill 只動**：action 專案根目錄內的 `action.yml`／`action.yaml`、其 `steps` 直接引用的內嵌腳本（如 `*.sh`／`*.ps1`），以及階段 D 由 doc-funcs 流程處理的目標。
|
||||
|
||||
---
|
||||
|
||||
## 參數來源優先序（開發中需要新參數時）
|
||||
|
||||
從零建立（A1a）、對齊 composite（階段 B）、注入橫幅 step（階段 C）或補強被引用腳本的過程中，若需要新的參數值，依下列順序處理，**前一項可取得就不往下**：
|
||||
|
||||
1. **`${{ gitea.* }}`／`${{ github.* }}` context**：在 Gitea composite action 的 `runs.steps` 內**可直接使用**（Gitea 中 `gitea` 與 `github` context 互為別名）。常用如 `github.repository`、`github.ref_name`、`github.server_url`、`github.token`、`github.event.*`。為同時相容 GitHub Actions，composite action 內建議寫 `github.*`（Gitea 亦支援）；確定只跑 Gitea 的專案可用 `gitea.*`。`run` 腳本內可改讀同源的執行期環境變數（`$GITHUB_REPOSITORY`、`$GITHUB_SERVER_URL`、`$GITHUB_REF_NAME` 等）。
|
||||
2. **context 無法取得 → 詢問使用者新增 `inputs`**：以 `AskUserQuestion` 詢問使用者是否新增對應 `input`（名稱／description／`required`／`default`），經同意後於 `inputs` 宣告並在 step 內以 `${{ inputs.<name> }}` 取用；未經同意**不得**擅自更動 `inputs`／`outputs` 契約。
|
||||
|
||||
**secrets／vars 一律視為不可用，不列入優先序**：`${{ secrets.* }}`／`${{ vars.* }}` context 在 composite action 的 `action.yml` 內於 GitHub 為**官方明文不可用**（composite action 取不到 `secrets`／`vars` context，`inputs` 的 `default` 也不能引用）；Gitea act_runner 未嚴格檢查 context 可用性、行為無保證。為求兩邊相容，本 skill 一律視為不可用——參數值本質上屬 secrets／vars 者，直接依第 2 項宣告為 `input`，回報時附上呼叫端 workflow 的傳入寫法：
|
||||
|
||||
```yaml
|
||||
- uses: <owner>/<action>@<ref>
|
||||
with:
|
||||
token: ${{ secrets.MY_TOKEN }} # secrets 由呼叫端 workflow 傳入
|
||||
registry: ${{ vars.MY_REGISTRY }} # vars 亦同
|
||||
```
|
||||
從零建立（A1a）、對齊 composite（階段 B）、注入橫幅 step（階段 C）或補強被引用腳本的過程中，若需要新的參數值，一律依 `/jsc:spec-action-params` 的優先序處理：composite 的 `runs.steps` 內優先取 `${{ gitea.* }}`／`${{ github.* }}` context（建議寫 `github.*` 以相容兩邊；`run` 腳本內可改讀 `$GITHUB_*` 環境變數），取不到才以 `AskUserQuestion` 經使用者同意新增 `inputs`；`secrets`／`vars` 一律視為不可用，需要時宣告為 `input` 由呼叫端 workflow 傳入（範例見該 spec）。
|
||||
|
||||
---
|
||||
|
||||
@@ -146,7 +142,7 @@ runs:
|
||||
|
||||
在 `runs.steps` **最前面**插入（或更新）一個輸出橫幅的 step，讓 composite action 一啟動就**輸出 action 名稱、用途、更新時間**；並於 `action.yml` 開頭補用途／更新時間註解區塊。
|
||||
|
||||
- **更新時間**語意為「本檔最後由本 skill 產生／更新的時間」，使用台灣時區（Asia/Taipei）並固定為 `yyyy/MM/dd HH:mm:ss`（可用 `TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'` 取得），**寫成檔內固定字串**（非執行期動態時間）。本階段先寫入暫定時間戳，**階段 D 完成後會統一同步各處時間戳**（見階段 D）。
|
||||
- **更新時間**依 `/jsc:spec-time-log`（Asia/Taipei、固定 `yyyy/MM/dd HH:mm:ss`、寫成檔內固定字串）。本階段先寫入暫定時間戳，**階段 D 完成後會統一同步各處時間戳**（見階段 D）。
|
||||
- 名稱／用途取自階段 A2 的 `action.yml`（缺漏時以「（未提供）」標示）。
|
||||
- 橫幅 step 須有可辨識的 `name`（如 `顯示 action 資訊`）與 `shell: bash`；其後緊接既有／對齊後的 steps，**不更動既有 steps**。
|
||||
- 若已存在本 skill 先前插入的橫幅 step（依 `name` 辨識），則**更新**其內容與更新時間，不重複插入。
|
||||
@@ -182,16 +178,7 @@ runs:
|
||||
|
||||
## 階段 D：完整執行 /jsc:doc-funcs 處理流程
|
||||
|
||||
標準化完成後，對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README：
|
||||
|
||||
- **前置檢查**：先確認 doc-funcs skill 可用（`/jsc:doc-funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。
|
||||
- 以階段 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`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
|
||||
- **統一時間戳**：doc-funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步橫幅 step 內文、`action.yml` 開頭註解區塊與 README 的更新時間，**確保各處時間戳一致**。
|
||||
|
||||
> 銜接方式：在本 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用本 skill 的 action 根目錄為目標專案。
|
||||
標準化完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README）。完成後依該 spec **統一時間戳**：回頭同步橫幅 step 內文、`action.yml` 開頭註解區塊與 README 的更新時間，確保各處一致。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -18,32 +18,29 @@ argument-hint: "[--action-dir <action 根目錄>] [--node-version <node tag>] [-
|
||||
|
||||
---
|
||||
|
||||
## 輸出規範（務必遵守）
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
|
||||
- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、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 化只「翻譯」既有邏輯，不得擅自改變對外行為、輸入輸出契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依「參數來源優先序」經使用者同意後為之。
|
||||
- **不擴及無關檔案**：本 skill 只動 action 專案根目錄內的：主程式、主程式依賴鏈的 `.js`（搬移到 `src/`）、`package.json`、`action.yml`／`action.yaml`、`entrypoint.sh`、`Dockerfile`、`.dockerignore`，以及階段 E 由 doc-funcs 流程處理的目標；排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／第三方依賴。
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼。
|
||||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認、不擴及無關檔案。
|
||||
- `/jsc:spec-git-safety`：不破壞既有工作（絕不 `reset --hard`／`clean`）、`git mv` 保留歷史。
|
||||
- `/jsc:spec-action-params`：action 參數來源優先序（環境變數 → 經同意新增 `inputs`）、`secrets`／`vars` 一律視為不可用。
|
||||
- `/jsc:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、完成後統一同步時間戳。
|
||||
- `/jsc:spec-dockerfile`：Dockerfile 六步流程、多階段建置、固定版號、自我檢查。
|
||||
- `/jsc:spec-doc-funcs-handoff`：最終階段完整執行 `/jsc:doc-funcs` 的標準流程。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- **一定會中斷詢問的點**：階段 B 主程式「非 Node 需改寫」時（破壞性，須先確認），以及階段 E 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
|
||||
- **保留行為**：Node 化只「翻譯」既有邏輯，不得擅自改變對外行為、輸入輸出契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依 `/jsc:spec-action-params` 經使用者同意後為之。
|
||||
- **本 skill 只動**：action 專案根目錄內的主程式、主程式依賴鏈的 `.js`（搬移到 `src/`）、`package.json`、`action.yml`／`action.yaml`、`entrypoint.sh`、`Dockerfile`、`.dockerignore`，以及階段 E 由 doc-funcs 流程處理的目標。
|
||||
|
||||
---
|
||||
|
||||
## 參數來源優先序（開發中需要新參數時）
|
||||
|
||||
從零建立（A1a）、主程式 Node 化（階段 B）、產生 `entrypoint.sh`（階段 C）或產生 `Dockerfile`（階段 D）的過程中，若需要新的參數值，依下列順序處理，**前一項可取得就不往下**：
|
||||
|
||||
1. **runner 注入的執行期環境變數（`gitea.*`／`github.*` context 的同源資訊）**：Docker 容器 action 的 `action.yml` 內 expression 幾乎只有 `inputs`／`env` context 可用，但 runner 會把 `gitea.*`／`github.*` 的同源資訊以**執行期環境變數注入容器**——Node 主程式以 `process.env.GITHUB_*` 讀取（如 `GITHUB_REPOSITORY`、`GITHUB_SERVER_URL`、`GITHUB_REF_NAME`、`GITHUB_EVENT_PATH`；Gitea 亦提供 `GITEA_*` 同義變數），`entrypoint.sh` 內以 `$GITHUB_*` 讀取。為同時相容 GitHub Actions，程式內建議讀 `GITHUB_*`。
|
||||
2. **環境變數無法取得 → 詢問使用者新增 `inputs`**：以 `AskUserQuestion` 詢問使用者是否新增對應 `input`（名稱／description／`required`／`default`），經同意後於 `inputs` 宣告，容器內以 `INPUT_<大寫名稱>` 環境變數取用（Node 主程式讀 `process.env.INPUT_<NAME>`）；未經同意**不得**擅自更動 `inputs`／`outputs` 契約。
|
||||
|
||||
**secrets／vars 一律視為不可用，不列入優先序**：`${{ secrets.* }}`／`${{ vars.* }}` context 在 Docker 容器 action 的 `action.yml`（`runs.args`／`runs.env`）內於 GitHub 為不可用（官方文件僅記載 `inputs` context 可用；runner 也不會把呼叫端的 secrets 自動注入容器）；Gitea act_runner 未嚴格檢查 context 可用性、行為無保證。為求兩邊相容，本 skill 一律視為不可用——參數值本質上屬 secrets／vars 者，直接依第 2 項宣告為 `input`，回報時附上呼叫端 workflow 的傳入寫法：
|
||||
|
||||
```yaml
|
||||
- uses: <owner>/<action>@<ref>
|
||||
with:
|
||||
token: ${{ secrets.MY_TOKEN }} # secrets 由呼叫端 workflow 傳入
|
||||
registry: ${{ vars.MY_REGISTRY }} # vars 亦同
|
||||
```
|
||||
從零建立（A1a）、主程式 Node 化（階段 B）、產生 `entrypoint.sh`（階段 C）或產生 `Dockerfile`（階段 D）的過程中，若需要新的參數值，一律依 `/jsc:spec-action-params` 的優先序處理：Docker 容器 action 優先取 runner 注入的執行期環境變數（Node 主程式讀 `process.env.GITHUB_*`、`entrypoint.sh` 讀 `$GITHUB_*`；Gitea 亦提供 `GITEA_*` 同義變數，建議讀 `GITHUB_*` 以相容兩邊），取不到才以 `AskUserQuestion` 經使用者同意新增 `inputs`（容器內以 `INPUT_<大寫名稱>` 取用）；`secrets`／`vars` 一律視為不可用，需要時宣告為 `input` 由呼叫端 workflow 傳入（範例見該 spec）。
|
||||
|
||||
---
|
||||
|
||||
@@ -142,7 +139,7 @@ runs:
|
||||
|
||||
在 action 根目錄產生（或覆寫）`entrypoint.sh`：**啟動 node 主程式前，先輸出 action 名稱、用途、更新時間**。
|
||||
|
||||
- **更新時間**語意為「本檔最後由本 skill 產生／更新的時間」，使用台灣時區（Asia/Taipei）並固定為 `yyyy/MM/dd HH:mm:ss`（可用 `TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'` 取得），**寫成檔內固定字串**（非執行期動態時間）。本階段先寫入暫定時間戳，**階段 E 完成後會統一同步各處時間戳**（見階段 E）。
|
||||
- **更新時間**依 `/jsc:spec-time-log`（Asia/Taipei、固定 `yyyy/MM/dd HH:mm:ss`、寫成檔內固定字串）。本階段先寫入暫定時間戳，**階段 E 完成後會統一同步各處時間戳**（見階段 E）。
|
||||
- 名稱／用途取自階段 A2 的 `action.yml`。
|
||||
- 最後以 `exec node <主程式>`（如 `exec node /action/src/index.js "$@"`）啟動，讓 node 取代 shell 行程，正確傳遞訊號與 exit code；路徑須與階段 D 的 `Dockerfile` 落點一致。
|
||||
- **若階段 B 裁示「維持非 Node」**：橫幅照常輸出，最後改以 `exec <原直譯器> <主程式>` 啟動（如 `exec python3 /action/src/main.py "$@"`、`exec sh /action/src/main.sh "$@"`）。
|
||||
@@ -193,7 +190,7 @@ exec node /action/src/index.js "$@"
|
||||
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 相依與快取帶進最終映像；**`COPY --from=build` 必須逐項明列路徑，不得整包 `COPY --from=build /action /action`**（整包搬等於沒有縮小）。
|
||||
6. **設定入口**：`ENTRYPOINT` 指向 `entrypoint.sh`，其內 `node` 路徑為 D0 的入口檔。
|
||||
|
||||
base image 版本：**預設使用產生當下的最新 LTS major 固定 tag**（如 build 基底 `node:22`、runtime 基底 `node:22-slim`）——docker action 每次執行都由 runner 現場 build，用 `latest` 會隨 base 無預警跳版而行為漂移、跨 runner 不一致、無法重現除錯；可查詢 Docker Hub（`https://hub.docker.com/_/node`）確認當前 LTS 版號。帶 `--node-version <tag>` 時改用 `node:<tag>` 與 `node:<tag>-slim`；`latest` 僅在**使用者明確要求**時使用（此時 runtime 用 `node:slim`，因為沒有 `node:latest-slim` 這個 tag）。
|
||||
base image 版本依 `/jsc:spec-dockerfile`（固定 major tag、不用 `latest`）：**預設使用產生當下的最新 LTS major 固定 tag**（如 build 基底 `node:22`、runtime 基底 `node:22-slim`），可查詢 Docker Hub（`https://hub.docker.com/_/node`）確認當前 LTS 版號；帶 `--node-version <tag>` 時改用 `node:<tag>` 與 `node:<tag>-slim`。
|
||||
|
||||
下列為**最簡基準骨架**（純 JS、無 build、無 OS 相依的情況）；實際內容須依 D0 盤點調整，第 4 步建置、第 2／5 步 OS 套件等視主程式需要增刪：
|
||||
|
||||
@@ -234,7 +231,7 @@ ENTRYPOINT ["/action/entrypoint.sh"]
|
||||
|
||||
- **依主程式實作**：上面只是基準骨架。若主程式是 TypeScript／需打包，第 4 步要加 `npm run build`、第 5 步只帶 `dist/` 與 production 相依；若主程式會 spawn 外部執行檔或用原生模組，第 2／5 步要補對應 OS 套件；用不到的步驟內容不要硬塞。
|
||||
- **若階段 B 裁示「維持非 Node」**：base image 改用對應語言官方映像（如 `python:3-slim`），第 2 步改安裝該生態相依（如 `pip install -r requirements.txt`），其餘六步結構不變；`ENTRYPOINT` 仍指向 `entrypoint.sh`（其內 `exec` 原直譯器，見階段 C）。
|
||||
- **版號對齊**：runtime 基底版號需與 build 基底一致。預設 LTS 固定 tag（如 `NODE_VERSION=22`、`NODE_RUNTIME=22-slim`）；帶 `--node-version` 時同理對應。tag 已是 `-alpine`／`-slim` 變體（如 `22-alpine`）時，build 與 runtime **直接沿用同一 tag**、不再另組 `-slim`（沒有 `node:22-alpine-slim` 這種 tag）。使用者明確要求 `latest` 時 runtime 用 `node:slim`（**沒有 `node:latest-slim`**）。故一律以獨立的 `NODE_RUNTIME` 參數帶入、不要用 `${NODE_VERSION}-slim` 組裝。
|
||||
- **版號對齊**：依 `/jsc:spec-dockerfile`（runtime 與 build 版號一致、以獨立 runtime ARG 帶入不用 `${VERSION}-slim` 組裝、`-alpine`／`-slim` 變體沿用同一 tag、使用者要求 `latest` 時 runtime 用 `node:slim`）。
|
||||
- **自我檢查**：`entrypoint.sh` 的 `node <主程式>` 路徑（如 `/action/src/index.js`）需與 `Dockerfile` 的 `WORKDIR`／`COPY` 落點一致，避免容器啟動時找不到主程式；`action.yml` 的 `runs.entrypoint` 若存在，必須是**絕對路徑**且與 `Dockerfile` 落點一致（預設不設，讓 Dockerfile 的 `ENTRYPOINT` 生效）。
|
||||
- 此檔的用途／更新日期註解與逐行註解，同樣於階段 E 由 doc-funcs 指令檔流程統一補齊。
|
||||
|
||||
@@ -242,16 +239,7 @@ ENTRYPOINT ["/action/entrypoint.sh"]
|
||||
|
||||
## 階段 E：完整執行 /jsc:doc-funcs 處理流程
|
||||
|
||||
容器化與 Node 化完成後，對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README：
|
||||
|
||||
- **前置檢查**：先確認 doc-funcs skill 可用（`/jsc:doc-funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。
|
||||
- 以階段 A1 的 action 根目錄為目標，執行 `doc-funcs` skill 的完整流程（判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證）。
|
||||
- doc-funcs 會涵蓋本次新增／變更的指令檔：`entrypoint.sh`（補齊「用途＋更新日期同一註解區塊」與逐行註解）、`Dockerfile`（逐行註解）；以及 `src/` 內 Node 主程式與各 function 的文件註解。
|
||||
- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，本 skill 不代為決定。
|
||||
- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。
|
||||
- **統一時間戳**：doc-funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步 `entrypoint.sh` 橫幅輸出與註解區塊、`Dockerfile` 註解區塊與 README 的更新時間，**確保各處時間戳一致**。
|
||||
|
||||
> 銜接方式：在本 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用本 skill 的 action 根目錄為目標專案。
|
||||
容器化與 Node 化完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README；本次新增／變更的 `entrypoint.sh`、`Dockerfile` 與 `src/` 內 Node 主程式都會被涵蓋）。完成後依該 spec **統一時間戳**：回頭同步 `entrypoint.sh` 橫幅輸出與註解區塊、`Dockerfile` 註解區塊與 README 的更新時間，確保各處一致。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+18
-25
@@ -16,14 +16,21 @@ argument-hint: "[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路
|
||||
|
||||
---
|
||||
|
||||
## 輸出規範（務必遵守）
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
|
||||
- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、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`／第三方依賴。
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼。
|
||||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認、不擴及無關檔案。
|
||||
- `/jsc:spec-git-safety`：不破壞既有工作（絕不 `reset --hard`／`clean`）。
|
||||
- `/jsc:spec-dockerfile`：Dockerfile 六步流程、多階段建置、對外契約不動、自我檢查。
|
||||
- `/jsc:spec-doc-funcs-handoff`：最終階段完整執行 `/jsc:doc-funcs` 的標準流程。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- **一定會中斷詢問的點**：階段 B「重整無法可靠保證建置行為等價」時（破壞性，須先確認），以及階段 C 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
|
||||
- **保留建置行為**：重整只「重新組織與分層」既有指令，不得擅自改變最終映像的內容、檔案落點、相依版本、暴露的 port、`ENV`、`ENTRYPOINT`／`CMD` 對外契約或建置副作用；多階段建置縮小映像時，runtime 階段必須帶齊執行所需的所有產物，不得遺漏導致容器無法啟動。
|
||||
- **本 skill 只動**：階段 A／B 只動目標 `Dockerfile`（及與其直接相關、為保留行為而必須同步的 `.dockerignore`）；其餘檔案僅在階段 C 由 doc-funcs 流程依其規範處理。
|
||||
|
||||
---
|
||||
|
||||
@@ -69,14 +76,7 @@ argument-hint: "[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路
|
||||
|
||||
## 階段 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` 置於最後，語意與原檔一致。
|
||||
在**保留建置行為**的前提下，把目標 `Dockerfile` 的指令重整／歸位為 `/jsc:spec-dockerfile` 定義的**固定六步流程**（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口），並採**多階段建置**縮小最終映像；各步要點（ARG 集中檔首、相依描述先 `COPY`、同層清理快取、`COPY --from` 逐項明列、搬移 runtime 需要的 `ENV`／`WORKDIR`／`EXPOSE`／`USER`）依該 spec。
|
||||
|
||||
**重整原則（關鍵）**
|
||||
|
||||
@@ -84,7 +84,7 @@ argument-hint: "[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路
|
||||
- **已是多階段** → 將既有各階段對應到六步（build 階段涵蓋 1–4、runtime 階段涵蓋 5–6），補齊缺漏的快取最佳化與清理，不破壞既有 `--from` 依賴。
|
||||
- **單階段改多階段** → 僅在能可靠判斷 runtime 真正需要哪些產物時才做；無法可靠判斷時，**不臆測**，標 `# 需人工確認：runtime 需要的產物清單` 並回報，退回「最小重排＋補註解」。
|
||||
- **多階段不適用** → 若該映像本質上無法受益於多階段（例如純資料映像、最終就是要完整建置環境），保留單階段，於步驟 5 以註解說明「此映像不適用多階段縮小」，其餘步驟仍依序歸位。
|
||||
- **對外契約不動**：`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`／`VOLUME`／`HEALTHCHECK`／`USER` 的語意保持與原檔一致；只可調整位置與分層，不可改變值或刪除。
|
||||
- **對外契約不動**：依 `/jsc:spec-dockerfile`（`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`／`VOLUME`／`HEALTHCHECK`／`USER` 語意與原檔一致，只可調整位置與分層）。
|
||||
- **`.dockerignore`**：若為了「複製檔案」步驟的正確性需要排除建置產物／`node_modules`／`.git`，可建立或補強 `.dockerignore`（僅新增排除項，不刪既有），並回報。
|
||||
|
||||
重整骨架（實際指令、base image、語言依階段 A 偵測結果填入；非 Node 專案請換成對應語言的安裝／建置指令與 runtime 基底）：
|
||||
@@ -120,7 +120,7 @@ COPY --from=build /app/<artifacts> ./<artifacts>
|
||||
ENTRYPOINT [<entrypoint>]
|
||||
```
|
||||
|
||||
- **自我檢查**：重整後確認 (1) `ARG` 在使用它的 `FROM` 之後有重新宣告（跨階段 `ARG` 規則）；(2) runtime 階段 `COPY --from` 帶齊執行所需全部產物；(3) `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV` 與原檔語意一致；(4) 路徑（`WORKDIR`／`COPY` 落點）一致、容器能找到入口。
|
||||
- **自我檢查**：依 `/jsc:spec-dockerfile` 的自我檢查清單（跨階段 `ARG` 重新宣告、runtime 帶齊產物、對外契約一致、路徑一致）。
|
||||
- 此檔的「用途／更新日期」開頭註解區塊與逐行註解，於階段 C 由 `/jsc:doc-funcs` 的指令檔流程統一補齊／覆寫為標準格式；本階段先確保**建置行為**正確、六步結構清楚即可。
|
||||
- **建置驗證**：若環境可執行 `docker build`，重整後做一次建置驗證（或至少 `docker build --check`／語法檢查）確認可建置；無法執行時明確說明原因並標註風險（階段 C doc-funcs 第 11 步亦會做語法驗證）。
|
||||
|
||||
@@ -128,14 +128,7 @@ ENTRYPOINT [<entrypoint>]
|
||||
|
||||
## 階段 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 的專案根目錄為目標專案。
|
||||
Dockerfile 六步整理完成後，以階段 A1 的專案根目錄為目標，依 `/jsc:spec-doc-funcs-handoff` 對**整個專案**完整執行 `/jsc:doc-funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README；本次整理的 `Dockerfile` 會被視為部署設定檔補齊標頭與逐行註解）。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+13
-22
@@ -21,15 +21,20 @@ argument-hint: "[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以
|
||||
## 絕對準則（不可違反）
|
||||
|
||||
- **不建立任何草稿檔**：不寫 `.docs/`、不寫暫存檔、不用本機檔案傳遞中間結果。需求彙整、TODO 排序、實作進度、驗證結果等所有中間成果，一律留在**對話內容**，並透過 `tea` 或 Gitea API **保存到議題描述或議題留言**。唯一例外是階段 E 在議題範圍內對**目標 repo 原始碼**的正常程式修改。
|
||||
- **盡量使用表格或圖形**：面向使用者的輸出與寫入議題的內容（需求彙整、TODO 列表、進度回報），優先以 **Markdown 表格**與 **Mermaid 圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）呈現，讓使用者一眼看懂意圖；圖表必須忠實反映議題內容，不得杜撰。
|
||||
- **盡量使用表格或圖形**：依 `/jsc:spec-output` — 面向使用者的輸出與寫入議題的內容（需求彙整、TODO 列表、進度回報），優先以 Markdown 表格與 Mermaid 圖呈現，忠實反映議題內容、不得杜撰。
|
||||
|
||||
## 輸出規範（務必遵守）
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
|
||||
- **語言**：所有面向使用者的輸出與寫入議題的描述／留言，一律使用**繁體中文（台灣用語）**；僅程式碼識別字、檔名、指令、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 的詢問在「可跳過條件」成立時**必須跳過**，不要重複確認已知資訊。
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、API body 以 UTF-8 JSON 檔帶入且換行為實際換行。
|
||||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認、已知資訊跳過詢問。
|
||||
- `/jsc:spec-gitea`：tea／API 工具選擇與檢查、`GITEA_TOKEN` 機密保護（不 echo、遮蔽）、不依賴 `jq`、API 分頁完整讀取。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- **必要決策**（會中斷詢問）：工具皆不可用、專案不明、議題編號缺失、TODO 與需求衝突需人工裁示、實作失敗需使用者決策。
|
||||
- 階段 A／B／C 的詢問在「可跳過條件」成立時**必須跳過**，不要重複確認已知資訊。
|
||||
|
||||
---
|
||||
|
||||
@@ -49,21 +54,7 @@ argument-hint: "[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以
|
||||
|
||||
**若使用者已透過 `--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 貼進對話。
|
||||
依 `/jsc:spec-gitea` 的工具選擇流程執行：檢查 `tea`（`command -v tea`、`tea login list`）與 `GITEA_TOKEN`（只輸出「已設定／未設定」）→ 以表格呈現檢查結果後詢問使用者要用 `tea` 或 `api` → 兩種方式都不可用則回報並停止（不要請使用者把 token 貼進對話）。
|
||||
|
||||
## 階段 B：確認議題所在專案（已知則跳過）
|
||||
|
||||
|
||||
@@ -8,9 +8,15 @@ argument-hint: "[<solution-or-project>] [--include-prerelease] [--no-dedupe] [--
|
||||
|
||||
把 C# / .NET repo 內的 NuGet 套件依專案盤點、清理可安全移除的重複參考，然後逐一更新到最新可用版本。每個套件異動後都要驗證專案可以正常編譯；若最新版本失敗，改從目前版本之後的最小可用版本逐版升級，直到第一個編譯失敗版本為止，保留最後一個可編譯版本並記錄失敗點。
|
||||
|
||||
## 輸出規範
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼（套件 id、檔名、指令、版本號保留原文）。
|
||||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認。
|
||||
|
||||
## 輸出規範（本 skill 特有）
|
||||
|
||||
- 所有面向使用者的輸出一律使用繁體中文（台灣用語）；套件 id、檔名、指令、版本號保留原文。
|
||||
- 修改前先輸出簡短執行計畫；除非使用者要求確認、遇到多個 solution 無法判斷、或編譯失敗需要取捨，否則依計畫執行。
|
||||
- 每個套件都要留下結果：已更新 / 已降階到可編譯版本 / 已略過 / 已回復 / 已移除重複參考，以及對應版本與驗證指令。
|
||||
- 不主動 commit、push 或開 PR；使用者明確要求時才做。
|
||||
|
||||
@@ -18,12 +18,13 @@ argument-hint: "--known-issues <前次審查紀錄路徑> --exclusions <排除
|
||||
> 與 `/jsc:code-review` 的關係：code-review 的步驟 7 只會（在同意後）把 ✅ 成立 寫入已知問題檔；
|
||||
> **誤判 → 排除事項** 它不會寫。本 skill 一次補齊兩個方向，且**只吃既有裁決結果**：不跑 review、不改程式碼。
|
||||
|
||||
## 輸出規範（務必遵守）
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
|
||||
- **語言**：所有面向使用者的輸出與**寫入檔案的內容**一律使用**繁體中文（台灣用語）**；
|
||||
僅檔名、程式碼識別字、`key`／JSON 欄位名等技術標識保留原文，不可使用簡體字。
|
||||
- **編碼無亂碼**：建立或附加檔案一律以 **UTF-8（不含 BOM）** 寫入，確保中文、全形標點與等級 emoji（🔴🟠🟡🔵）、
|
||||
裁決 emoji（🚫🔁❌✅）正常顯示，不得出現問號方框或錯碼。
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼。
|
||||
|
||||
本 skill 特有補充：須確保等級 emoji（🔴🟠🟡🔵）與裁決 emoji（🚫🔁❌✅）正常顯示。
|
||||
|
||||
## 參數（與 code-review 同名旗標，方便沿用同一組路徑）
|
||||
|
||||
|
||||
@@ -18,17 +18,20 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
|
||||
|
||||
---
|
||||
|
||||
## 輸出規範（務必遵守）
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
|
||||
- **語言**：所有面向使用者的輸出（修復清單、提交計畫、總結、反問）與 **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）。
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼（含 commit 訊息、PR 標題／描述、寫檔／API body 實作要點與送出前自我檢查）。
|
||||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認。
|
||||
- `/jsc:spec-gitea`：`GITEA_TOKEN` 機密保護（不 echo、遮蔽 `***`）、API body 以 UTF-8 JSON 檔帶入。
|
||||
- `/jsc:spec-git-safety`：不破壞既有工作、develop → master 後備、保守解衝突、新分支不覆蓋既有分支。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- **必要決策**（會中斷詢問）：目標分支缺失、pull 策略不明、無法安全解衝突、需人工判斷的設計取捨、push 憑證皆失敗。
|
||||
- 涵蓋範圍：更新後的 `findings.json` / `exclusions.json`、commit 訊息、PR 標題／描述、終端訊息，與等級 emoji 🔴🟠🟡🔵。
|
||||
- 階段 E 完成後依規範清除對話內文（見 E6）。
|
||||
|
||||
---
|
||||
|
||||
@@ -132,13 +135,7 @@ source_branch="$(git rev-parse --abbrev-ref HEAD)"
|
||||
|
||||
### A6. 必要時嘗試解衝突
|
||||
|
||||
當 `git pull` 後出現衝突：
|
||||
|
||||
1. 用 `git status --porcelain` 與衝突標記定位衝突檔。
|
||||
2. 讀取衝突檔脈絡，依專案現有行為與遠端變更做最小合理整合。
|
||||
3. 可安全解決的衝突：編輯檔案移除衝突標記，執行 `git add -- <檔案...>` 標記已解決。
|
||||
4. 無法安全判斷的衝突：停止處理，列出檔案、衝突原因與需要使用者決策的點；不要硬選任一邊。
|
||||
5. 全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 `git status --porcelain` 沒有未解衝突，再回到 A5 判斷是否需要建立新工作分支。
|
||||
當 `git pull` 後出現衝突，依 `/jsc:spec-git-safety` 的保守解衝突流程處理（定位衝突檔 → 最小合理整合 → 可安全解決者 `git add` 標記、無法安全判斷者停止並列出決策點）；全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 `git status --porcelain` 沒有未解衝突，再回到 A5 判斷是否需要建立新工作分支。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -22,13 +22,15 @@ description: 以 RPG 攻防對決方式審查 git diff 的程式碼審查 skill
|
||||
|
||||
---
|
||||
|
||||
## 輸出規範（所有角色共用，務必遵守）
|
||||
## 共用規範（generic plugin，必要前置；所有角色共用）
|
||||
|
||||
- **語言**：所有面向使用者的輸出（findings 表、裁決表、總結、附註、反問）一律使用**繁體中文（台灣用語）**。
|
||||
僅程式碼識別字、檔名、git 指令、既有技術術語保留原文，**不可**使用簡體字或英文敘述句。
|
||||
- **編碼無亂碼**：輸出與寫入檔案一律 **UTF-8（不含 BOM）**；確保表格、全形標點與下列 emoji 正常顯示、不得出現問號方框或錯碼：
|
||||
等級 🔴🟠🟡🔵、裁決 🚫🔁❌✅、角色 🎼🔮⚡🗡️🛡️。
|
||||
- **派發 subagent 時**：須把本規範一併寫入每個 subagent 的提示，確保各角色回傳的內容同樣是繁體中文、無亂碼。
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、派發 subagent 時把規範一併寫入其提示。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- 須確保下列 emoji 正常顯示：等級 🔴🟠🟡🔵、裁決 🚫🔁❌✅、角色 🎼🔮⚡🗡️🛡️。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+13
-22
@@ -18,13 +18,18 @@ argument-hint: "[--target-dir <根目錄>] [--owner <擁有者,以逗號分隔>]
|
||||
|
||||
---
|
||||
|
||||
## 輸出規範（務必遵守）
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
|
||||
- **語言**：所有面向使用者的輸出（擁有者清單、專案清單、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、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 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼。
|
||||
- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認。
|
||||
- `/jsc:spec-gitea`：`GITEA_TOKEN` 機密保護（不 echo、遮蔽、clone 後還原乾淨 origin）、API 分頁完整讀取、host 決定順序。
|
||||
- `/jsc:spec-git-safety`：不破壞既有工作（未提交變更不強切、絕不 `reset --hard`／`clean`）、develop → master 後備、`pull --ff-only`。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- **必要決策**（會中斷詢問）：缺 token、無法決定 gitea 主機、目標目錄不可寫、單一專案更新時工作區有未提交變更需使用者裁示。**唯一一定會中斷的點是階段 C 的擁有者多選**（除非已帶 `--owner`）。
|
||||
- **唯讀本意**：本 skill 只做 clone 與本機分支更新，**不 push、不改遠端、不刪本機未追蹤檔**。
|
||||
|
||||
---
|
||||
@@ -46,25 +51,11 @@ argument-hint: "[--target-dir <根目錄>] [--owner <擁有者,以逗號分隔>]
|
||||
|
||||
### A1. 確認 token
|
||||
|
||||
讀取環境變數 `GITEA_TOKEN`（或助理慣用的等價變數名）。
|
||||
|
||||
```bash
|
||||
[ -n "${GITEA_TOKEN}" ] && echo "GITEA_TOKEN 已設定" || echo "GITEA_TOKEN 未設定"
|
||||
```
|
||||
|
||||
- **未設定** → 回報「缺少 `GITEA_TOKEN` 環境變數，無法存取 Gitea API」並停止；提示使用者於環境變數提供 token（不要請使用者把 token 貼進對話）。
|
||||
- **不可** echo token 本身，只確認是否存在。
|
||||
依 `/jsc:spec-gitea` 確認 `GITEA_TOKEN`（只輸出「已設定／未設定」，不可 echo token 本身）；**未設定** → 回報「缺少 `GITEA_TOKEN` 環境變數，無法存取 Gitea API」並停止（不要請使用者把 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`。
|
||||
依 `/jsc:spec-gitea` 的 host 決定順序：`--host` → `$GITEA_HOST` → 目前 repo 的 origin → 詢問使用者（不臆測）。主機僅取 host 部分（如 `gitea.jsc.idv.tw`），組 API base 為 `https://<host>/api/v1`。
|
||||
|
||||
### A3. 決定目標根目錄
|
||||
|
||||
|
||||
Reference in New Issue
Block a user