24 KiB
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) |
共用規範(shared plugin,必要前置)
執行本 skill 前,先以 Skill 工具載入下列共用規範並全程遵守;任一載入不到(shared plugin 未安裝)時,先詢問使用者是否安裝 shared plugin(https://gitea.jsc.idv.tw/plugins/shared.git),使用者不安裝則直接中斷本 skill,不得只憑下方一行摘要繼續執行:
/jsc-shared:spec-output:繁體中文(台灣用語)、UTF-8(不含 BOM)無亂碼。/jsc-shared:spec-execution:自動執行原則(必要決策才中斷)、不臆測/需人工確認、不擴及無關檔案。/jsc-shared:spec-git-safety:不破壞既有工作(絕不reset --hard/clean)、git mv保留歷史。/jsc-shared:spec-action-params:action 參數來源優先序(環境變數 → 經同意新增inputs)、secrets/vars一律視為不可用。/jsc-shared:spec-time-log:更新時間 Asia/Taipeiyyyy/MM/dd HH:mm:ss、完成後統一同步時間戳。/jsc-shared:spec-dockerfile:Dockerfile 六步流程、多階段建置、固定版號、自我檢查。/jsc-shared:spec-doc-funcs-handoff:最終階段完整執行/jsc-doc:funcs的標準流程。
本 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 注入的執行期環境變數(Node 主程式讀 process.env.GITHUB_*、entrypoint.sh 讀 $GITHUB_*;Gitea 亦提供 GITEA_* 同義變數,建議讀 GITHUB_* 以相容兩邊),取不到才以 AskUserQuestion 經使用者同意新增 inputs(容器內以 INPUT_<大寫名稱> 取用);secrets/vars 一律視為不可用,需要時宣告為 input 由呼叫端 workflow 傳入(範例見該 spec)。
參數
格式:[--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 根目錄
- 帶
--action-dir→ 採用(展開~)。 - 省略 → 用目前工作目錄。
- 根目錄須存在
action.yml或action.yaml(action manifest)。找不到 action manifest → 不臆測、不逕自動工;以AskUserQuestion詢問使用者要「從零建立新的 Docker 容器 action」還是「提供正確的 action 路徑」:選「從零建立」→ 進入 A1a;選「提供路徑」→ 依新路徑重跑 A1。
A1a. 從零建立 Docker 容器 action(問答式)
依序以問答收集需求,再產生 manifest 與主程式骨架:
- action 名稱:用於
action.yml的name。 - 輸入與輸出參數:逐一收集
inputs/outputs的名稱與description(description 盡量繁體中文、無亂碼)、required/default;沒有可留空。 - 執行目標:詢問此 action 要達成什麼,整理濃縮成一句話作為
action.yml的description(盡量繁體中文、無亂碼)。
收集完成後,於 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. 判斷目前主程式與語言
依序判斷主程式入口(取第一個成立者):
- 帶
--main <主程式檔>→ 直接採用。 action.yml為 JS action(runs.using: node*)→ 取runs.main。action.yml為 docker action(runs.using: docker)→ 看runs.entrypoint/Dockerfile的ENTRYPOINT/CMD推主程式。- 以上皆無 → 依專案檔與副檔名分布推斷(
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 取代)。
- 逐段把原主程式邏輯保守翻譯為 Node(建議
B2. 主程式依賴鏈的 .js 集中到 src/
- 在 action 根目錄建立
src/(若不存在)。 - 將主程式入口及其
require/import依賴鏈的.js/.mjs/.cjs(排除node_modules/.git/.docs/bin/obj/第三方依賴)移入src/,優先git mv保留歷史。主程式入口統一為src/index.js(或src/<main>.js)。 - 明文排除、不搬:外部工具依慣例路徑尋找的檔案——
*.config.js(eslint.config.js/jest.config.js/webpack.config.js等)、.*rc.js、husky/commitlint 等工具設定,以及test//tests//scripts/目錄;搬走會弄壞 lint/test/build 流程。 - 移動後必須更新所有引用,確保不破壞:
- 模組間的
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):
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(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 "$@")。
範例(實際路徑依階段 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 版本,六步流程依主程式實作量身產生)
在 action 根目錄產生(或覆寫)Dockerfile,base image 使用最新 LTS node 版本(固定 major tag),採多階段建置以縮小最終映像檔。六步流程是骨架,但每一步的實際內容必須依階段 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路徑。 - 產生
.dockerignore:於 action 根目錄產生(或補齊).dockerignore,至少排除.git、.docs、node_modules(宿主端,可能含平台不符的原生模組)與其他非執行必需檔案,避免帶進 build context。
D1~D6:依盤點結果填入六步
- 參數處理:以
ARG注入 node 版本(預設最新)與主程式需要的 build-time 參數;可調參數集中在檔案開頭。 - 安裝套件:依 D0 的相依結果安裝——有 lockfile 用
npm ci、否則npm install,二擇一寫死於 Dockerfile(不得以npm ci || npm install之類 fallback 串接,避免靜默吞錯、破壞 lockfile 的可重現性);不需 build 時加--omit=dev,需 build 時先裝完整相依(含 dev)供第 4 步使用。只在主程式真的會用到時才apt-get installOS 套件,並於同一RUN清掉 apt 快取。先COPY相依描述(package*.json)再安裝,以利 layer 快取。 - 複製檔案:
COPY主程式實際需要的檔案(src/、entrypoint.sh,及主程式會讀取的資源),明列路徑、不整包COPY .,並配合.dockerignore排除非必要檔案。 - 執行程序:賦予
entrypoint.sh執行權限;僅當 D0 判定需要 build/transpile 時才執行(如npm run build),否則此步只做權限設定,不要硬加建置指令。 - 縮小映像檔:多階段建置,runtime 改用 slim 基底,只
COPY --from=build帶入主程式執行真正需要的產物——有 build 產物時帶入dist/與 productionnode_modules(npm prune --omit=dev或重裝 production 相依),純 JS 無 build 時帶入src/與 productionnode_modules;若 D0 判定 runtime 需要某些 OS 執行檔,於 runtime 階段一併安裝(slim 基底可能不含)。不要把 build 階段的 dev 相依與快取帶進最終映像;COPY --from=build必須逐項明列路徑,不得整包COPY --from=build /action /action(整包搬等於沒有縮小)。 - 設定入口:
ENTRYPOINT指向entrypoint.sh,其內node路徑為 D0 的入口檔。
base image 版本依 /jsc-shared: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 套件等視主程式需要增刪:
# 1. 參數處理:node 版本以 ARG 注入(預設當前最新 LTS major,範例為 22;--node-version 可覆寫)
ARG NODE_VERSION=22
ARG NODE_RUNTIME=22-slim
# ---- build 階段:安裝相依、準備產物 ----
FROM node:${NODE_VERSION} AS build
WORKDIR /action
# 2. 安裝套件:先帶相依描述以利 layer 快取,再裝 src/ 相依
# (依 D0 盤點二擇一寫死:有 lockfile 用 npm ci、否則 npm install,不用 || 串接;
# 需 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; \
fi
# 3. 複製檔案:明列主程式實際需要的檔案(配合 .dockerignore,不整包 COPY .)
COPY src/ /action/src/
COPY entrypoint.sh /action/entrypoint.sh
# 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/src /action/src
COPY --from=build /action/entrypoint.sh /action/entrypoint.sh
# 6. 設定入口:以 entrypoint.sh 啟動(其內 node 指向 D0 的入口檔)
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)。 - 版號對齊:依
/jsc-shared: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 由 funcs 指令檔流程統一補齊。
階段 E:完整執行 /jsc-doc:funcs 處理流程
容器化與 Node 化完成後,以階段 A1 的 action 根目錄為目標,依 /jsc-shared:spec-doc-funcs-handoff 對整個 action 專案完整執行 /jsc-doc:funcs 流程(前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README;本次新增/變更的 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有可執行權限、容器能正確啟動。
呼叫方式
格式:[--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」)自動觸發 |