jiantw83andClaude Sonnet 5
766142c3ba
新建 hooks/hooks.json，PreToolUse 沿用跨 plugin 腳本定位手法呼叫 shared 的 version-guard.mjs（判定仍固定讀自己的 plugin.json，只是腳本檔借用 shared 的）； action-composite/action-docker/action-node/image/issues/nuget/review-resolve/ sync/target 九個 skill 檔頭補上 spec-version-guard。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
187 lines
16 KiB
Markdown
187 lines
16 KiB
Markdown
---
|
||
name: action-docker
|
||
description: 將 Gitea／GitHub「Docker 容器 action」專案標準化為 Node 主程式＋容器化（目錄沒有 action manifest 時可問答式從零建立），並串接文件化流程：(1) 檢查 action 主程式是否為 Node，否則保守改寫為 Node，且主程式及其依賴鏈的 `.js` 檔集中到 `src/` 資料夾（工具設定檔與測試目錄不搬）；(2) 產生 `entrypoint.sh`，啟動前先輸出 action 名稱／用途／更新時間，再執行 node 主程式；(3) 產生使用最新 LTS node 版本的 `Dockerfile`；(4) 開發中需要新參數時優先取用 runner 注入的 `GITHUB_*`（Gitea 亦有 `GITEA_*`）執行期環境變數（即 `gitea.*`／`github.*` context 的同源資訊），無法取得才詢問使用者是否新增 `inputs`（`secrets`／`vars` context 在 docker action 內一律視為不可用，需要時宣告為 `inputs` 由呼叫端 workflow 傳入）；(5) 最後完整執行 `/jsc-doc:funcs` 處理流程（function 文件、指令檔逐行註解、重建 README）。當使用者說把 action 改成 docker／node、從零建立／產生一個 docker action、容器化 action、action 主程式 node 化、把 js 收進 src、產 entrypoint.sh／Dockerfile 給 action、處理 docker action 參數來源，或提到 action-docker 時觸發。不適用於：composite action（用 action-composite）、純前端打包、或不需容器化的一般 repo。
|
||
argument-hint: "[--action-dir <action 根目錄>] [--node-version <node tag>] [--main <主程式檔>]"
|
||
---
|
||
|
||
# action-docker — action 容器化（Node 主程式）＋文件化
|
||
|
||
五階段 skill：先做**前置設定與偵測**（找出 action 專案、讀取名稱／用途、判斷主程式語言），再把**主程式 Node 化並將主程式依賴鏈的 `.js` 收進 `src/`**，接著產生**啟動前先輸出 action 名稱／用途／更新時間的 `entrypoint.sh`**，然後產生**使用最新 LTS node 版本的 `Dockerfile`**（並對齊 `action.yml` 的 docker 設定），最後**完整執行 `/jsc-doc:funcs` 處理流程**替整個專案補文件並重建 README。產出的 docker action 需在**具 Docker 能力的 runner（docker 模式）**上執行。各階段開發中需要新參數時，一律套用下方「**參數來源優先序**」規則。目錄沒有 action manifest 時，先走 A1a 問答式「**從零建立**」分支產生 `action.yml` 與 Node 主程式骨架，再進入後續階段。
|
||
|
||
| 階段 | 動作 |
|
||
| --- | --- |
|
||
| A. 前置設定與偵測 | 決定 action 根目錄 → 讀 `action.yml`／`action.yaml` 的 `name`／`description` → 判斷目前主程式與語言（無 manifest 可走 A1a 從零建立） |
|
||
| B. 主程式 Node 化 | 主程式非 Node 則**保守改寫**為 Node（高風險，先確認）→ 主程式依賴鏈的 `.js` 集中到 `src/`，更新所有引用、`package.json`、`action.yml` |
|
||
| C. entrypoint.sh | 產生 `entrypoint.sh`：先輸出 action **名稱／用途／更新時間**，再 `exec` node 主程式 |
|
||
| D. Dockerfile | 依六步流程（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口）產生使用**最新 LTS node 版本**的 `Dockerfile`，多階段建置縮小映像、`ENTRYPOINT` 指向 `entrypoint.sh` |
|
||
| E. 串接 funcs | 對整個 action 專案完整執行 `/jsc-doc:funcs` 流程（function 文件、指令檔逐行註解、重建 README） |
|
||
|
||
---
|
||
|
||
## 共用規範（必要前置）
|
||
|
||
先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝，
|
||
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。
|
||
本 skill 需要的規範：`spec-version-guard`、`spec-output`、`spec-execution`、`spec-git-safety`、`spec-action-params`、`spec-action-scaffold`、`spec-ask-user`、`spec-node-src-layout`、`spec-time-log`、`spec-dockerfile`、`spec-doc-funcs-handoff`、`spec-skill-invocation`
|
||
|
||
本 skill 特有補充：
|
||
|
||
- **一定會中斷詢問的點**：階段 B 主程式「非 Node 需改寫」時（破壞性，須先確認），以及階段 E 由 `/jsc-doc:funcs` 自身的「如何實作」詢問。
|
||
- **保留行為**：Node 化只「翻譯」既有邏輯，不得擅自改變對外行為、輸入輸出契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依 `/jsc-shared:spec-action-params` 經使用者同意後為之。
|
||
- **本 skill 只動**：action 專案根目錄內的主程式、主程式依賴鏈的 `.js`（搬移到 `src/`）、`package.json`、`action.yml`／`action.yaml`、`entrypoint.sh`、`Dockerfile`、`.dockerignore`，以及階段 E 由 funcs 流程處理的目標。
|
||
|
||
---
|
||
|
||
## 參數來源優先序（開發中需要新參數時）
|
||
|
||
從零建立（A1a）、主程式 Node 化（階段 B）、產生 `entrypoint.sh`（階段 C）或產生 `Dockerfile`（階段 D）的過程中，若需要新的參數值，依 `/jsc-shared:spec-action-params` 執行（Docker 容器 action 讀取 runner 注入的執行期環境變數）。
|
||
|
||
---
|
||
|
||
## 參數
|
||
|
||
格式：`[--action-dir <action 根目錄>] [--node-version <node tag>] [--main <主程式檔>]`
|
||
|
||
- `--action-dir <action 根目錄>`：action 專案根目錄。**省略時預設目前工作目錄**（須含 `action.yml`／`action.yaml`，否則依 A1 詢問）。
|
||
- `--node-version <node tag>`：`Dockerfile` 的 node base image tag（如 `22`、`22-alpine`、`lts`）。**省略時預設使用當前最新 LTS major**（如 `node:22`，見階段 D）。tag 已是 `-alpine`／`-slim` 變體時，build 與 runtime **直接沿用同一 tag**、不再另組 `-slim`。
|
||
- `--main <主程式檔>`：指定主程式入口檔（相對 action 根目錄）。省略時依 A3 自動判斷。
|
||
|
||
---
|
||
|
||
## 階段 A：前置設定與偵測
|
||
|
||
### A1. 決定 action 根目錄
|
||
|
||
依 `/jsc-shared:spec-action-scaffold` 判斷 action 根目錄；找不到 action manifest 時進入 A1a 問答式從零建立。
|
||
|
||
### A1a. 從零建立 Docker 容器 action（問答式）
|
||
|
||
依 `/jsc-shared:spec-action-scaffold` 的三題問答骨架收集需求。收集完成後，於 action 根目錄產生：`action.yml`（`runs.using: docker`、`image: Dockerfile`，含收集到的 `name`／`description`／`inputs`／`outputs`）與 `src/index.js` 主程式（依執行目標以 Node 實作，輸入以 `process.env.INPUT_<NAME>` 讀取，開發中需要新參數時套用「參數來源優先序」）；完成後接續 A2 往後流程（A3 判定為 Node，階段 B 走「已是 Node」分支，階段 C／D 照常產生 `entrypoint.sh` 與 `Dockerfile`）。
|
||
|
||
### 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／其他）** → 依 `/jsc-shared:spec-ask-user` 的破壞性決策規則，先以 `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/`
|
||
|
||
依 `/jsc-shared:spec-node-src-layout` 把主程式入口及其依賴鏈的 `.js`／`.mjs`／`.cjs` 收進 `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
|
||
```
|
||
|
||
- **不設 `runs.entrypoint`**：執行入口由 `Dockerfile` 的 `ENTRYPOINT ["/action/entrypoint.sh"]`（絕對路徑）決定。`runs.entrypoint` 會**覆蓋** Dockerfile 的 `ENTRYPOINT`，且 runner 執行 docker action 時容器工作目錄是使用者 repo 的 workspace（不是 `/action`），相對路徑會找不到檔案。若原 manifest 已有 `entrypoint`，改為絕對路徑（`/action/entrypoint.sh`）或直接移除。
|
||
- 若原本是 JS action（`using: node*`），改為上述 docker 設定；若已是 docker action，確認 `image` 指向 `Dockerfile`，並依上一點處理 `entrypoint`。
|
||
- **docker 化代價揭示**（回報即可，不中斷詢問）：轉為 docker action 後**僅能在 Linux runner 執行**、每次 workflow 執行多一段 image build 時間、host 模式的 act_runner 無法執行（runner 需具 Docker 能力）。
|
||
|
||
改寫主程式或對齊 `action.yml` 過程需要新的參數值（如 token、repo 資訊、外部設定）時，依「參數來源優先序」處理，不逕自新增 `inputs`。
|
||
|
||
---
|
||
|
||
## 階段 C：產生 entrypoint.sh（先輸出名稱／用途／更新時間，再啟動 node 主程式）
|
||
|
||
在 action 根目錄產生（或覆寫）`entrypoint.sh`：**啟動 node 主程式前，先輸出 action 名稱、用途、更新時間**。
|
||
|
||
- **更新時間**依 `/jsc-shared:spec-time-log` 執行；本階段先寫入暫定時間戳，**階段 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 "$@"`）。
|
||
|
||
範例（實際路徑依階段 B 入口而定）：
|
||
|
||
```sh
|
||
#!/bin/sh
|
||
set -e
|
||
|
||
# action 啟動橫幅：輸出名稱／用途／更新時間（此檔由 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（使用最新 LTS node 版本）
|
||
|
||
先檢視 `src/` 主程式與 `package.json`（相依與 lockfile、是否需要 build／transpile、OS 層相依、執行期需求、入口檔），依盤點結果依 `/jsc-shared:spec-dockerfile` 的六步流程（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口）產生（或覆寫）action 根目錄的 `Dockerfile`；並產生（或補齊）`.dockerignore`，至少排除 `.git`、`.docs`、`node_modules`（宿主端，可能含平台不符的原生模組）。
|
||
|
||
本 skill 特有差異：
|
||
|
||
- **base image 預設 Node LTS**：預設使用產生當下的最新 LTS major 固定 tag（如 build 基底 `node:22`、runtime 基底 `node:22-slim`，可查詢 `https://hub.docker.com/_/node` 確認版號），帶 `--node-version <tag>` 時改用 `node:<tag>`／`node:<tag>-slim`。**若階段 B 裁示「維持非 Node」**：base image 改用對應語言官方映像（如 `python:3-slim`），第 2 步改安裝該生態相依（如 `pip install -r requirements.txt`），其餘六步結構不變；`ENTRYPOINT` 仍指向 `entrypoint.sh`（其內 `exec` 原直譯器，見階段 C）。
|
||
- **入口一致性自我檢查**（補充於 spec-dockerfile 通用自我檢查之外）：`entrypoint.sh` 內 `node <主程式>` 路徑（如 `/action/src/index.js`）須與 `Dockerfile` 的 `WORKDIR`／`COPY` 落點一致，避免容器啟動時找不到主程式；`action.yml` 的 `runs.entrypoint` 若存在，必須是**絕對路徑**且與 `Dockerfile` 落點一致（預設不設，讓 `Dockerfile` 的 `ENTRYPOINT` 生效）。
|
||
- 此檔的用途／更新日期註解與逐行註解，同樣於階段 E 由 funcs 指令檔流程統一補齊。
|
||
|
||
---
|
||
|
||
## 階段 E：完整執行 /jsc-doc:funcs 處理流程
|
||
|
||
容器化與 Node 化完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc-shared:spec-doc-funcs-handoff` 對**整個 action 專案**執行 `/jsc-doc:funcs` 流程（本次新增／變更的 `entrypoint.sh`、`Dockerfile` 與 `src/` 內 Node 主程式都會被涵蓋）；完成後依該 spec 統一時間戳，回頭同步 `entrypoint.sh` 橫幅輸出、`Dockerfile` 註解區塊與 README 的更新時間。
|
||
|
||
---
|
||
|
||
## 總結
|
||
|
||
各階段執行後輸出：
|
||
|
||
- **階段 A**：action 根目錄、action 名稱／用途、原主程式檔與語言、是否為 Node；若走 A1a 從零建立，列出問答收集結果（名稱／輸入輸出／目標）。
|
||
- **階段 B**：是否改寫主程式（及改寫摘要與「需人工確認」清單）、搬入 `src/` 的 `.js` 清單、已更新的引用（`package.json`／`action.yml`／路徑）；依「參數來源優先序」新增的 `inputs` 清單與呼叫端傳入寫法（若有）。
|
||
- **階段 C／D**：`entrypoint.sh` 的輸出內容（名稱／用途／更新時間）與啟動的 node 主程式、`Dockerfile` 採用的 node 版本與 `ENTRYPOINT`。
|
||
- **階段 E**：funcs 流程的處理結果（文件化的 function 與指令檔、重建的 README）。
|
||
- 列出本次新增／變更的檔案與其相對路徑，並提醒使用者於提交前確認 `entrypoint.sh` 有可執行權限、容器能正確啟動。
|
||
|
||
---
|
||
|
||
## 呼叫方式
|
||
|
||
依 `/jsc-shared:spec-skill-invocation`；本 skill 的 `<name>` 為 `action-docker`，參數格式：`[--action-dir <action 根目錄>] [--node-version <node tag>] [--main <主程式檔>]` — 全部可省略（根目錄預設目前工作目錄；node 版本預設最新 LTS；主程式自動判斷）。
|
||
|
||
範例：
|
||
|
||
- Claude Code / Antigravity：`/jsc-code:action-docker`，或 `/jsc-code:action-docker --action-dir ~/work/my-action --node-version 22`
|
||
- Codex：`$action-docker`，或 `$action-docker --action-dir ~/work/my-action`，或用 `/skills` 選單
|
||
- OpenCode：描述需求（如「把這個 action 主程式改成 node、主程式相關 js 收進 src/，產生會先輸出 action 名稱／用途／更新時間再啟動 node 的 entrypoint.sh、用最新 LTS node 版本的 Dockerfile，最後跑 funcs 補文件並重建 README」）自動觸發
|