code/skills/action-docker/SKILL.md

name, description, argument-hint

name	description	argument-hint
action-docker	將 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。	[--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）：

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 入口而定）：

#!/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」）自動觸發