Files

T

jiantw83 3a760a462e refactor(shared): switch code skills to jsc-shared

2026-07-31 17:36:08 +00:00

12 KiB

Raw Blame History

name, description, argument-hint

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

image — Dockerfile 六步流程整理＋文件化

三階段 skill：先做前置設定與偵測（找出專案根目錄、定位目標 Dockerfile、判斷語言／生態與既有建置方式），再把 Dockerfile 重整為固定六步流程（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，並以多階段建置縮小最終映像），最後完整執行 /jsc-doc:funcs 處理流程替整個專案補文件並重建 README。

階段	動作
A. 前置設定與偵測	決定專案根目錄 → 定位目標 `Dockerfile`（找不到則詢問，不臆造）→ 讀現有指令、判斷語言／生態、既有 base image 與建置流程
B. 整理 Dockerfile 為六步流程	在保留建置行為前提下，把指令重整／歸位為六步：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口；多階段建置縮小映像；行為不等價處標「需人工確認」並先確認
C. 串接 funcs	對整個專案完整執行 `/jsc-doc:funcs` 流程（function 文件、`Dockerfile` 等指令檔逐行註解、重建 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）。
/jsc-shared:spec-dockerfile：Dockerfile 六步流程、多階段建置、對外契約不動、自我檢查。
/jsc-shared:spec-doc-funcs-handoff：最終階段完整執行 /jsc-doc:funcs 的標準流程。

本 skill 特有補充：

一定會中斷詢問的點：階段 B「重整無法可靠保證建置行為等價」時（破壞性，須先確認），以及階段 C 由 /jsc-doc:funcs 自身的「如何實作」詢問。
保留建置行為：重整只「重新組織與分層」既有指令，不得擅自改變最終映像的內容、檔案落點、相依版本、暴露的 port、ENV、ENTRYPOINT／CMD 對外契約或建置副作用；多階段建置縮小映像時，runtime 階段必須帶齊執行所需的所有產物，不得遺漏導致容器無法啟動。
本 skill 只動：階段 A／B 只動目標 Dockerfile（及與其直接相關、為保留行為而必須同步的 .dockerignore）；其餘檔案僅在階段 C 由 funcs 流程依其規範處理。

參數

格式：[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes]

--project-dir <專案根目錄>：專案根目錄。省略時預設目前工作目錄。
--dockerfile <Dockerfile 路徑>：指定要整理的 Dockerfile（相對專案根目錄）。省略時依 A2 自動定位；找到多個時詢問。
--yes：盡量不中斷。即使帶此參數，「重整無法保證建置行為等價」與 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:action-docker）。

A3. 讀現有指令並判斷語言／生態與既有建置流程

讀取目標 Dockerfile 全文，盤點並記錄（作為階段 B 重整與 C 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 funcs 第 0 步沿用，也決定縮小映像時的 runtime 基底選擇）。

輸出偵測結果（目標 Dockerfile 路徑、單／多階段、base image、推斷語言、既有 ENTRYPOINT／CMD／EXPOSE／ENV），再進入階段 B。

階段 B：整理 Dockerfile 為六步流程

在保留建置行為的前提下，把目標 Dockerfile 的指令重整／歸位為 /jsc-shared:spec-dockerfile 定義的固定六步流程（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口），並採多階段建置縮小最終映像；各步要點（ARG 集中檔首、相依描述先 COPY、同層清理快取、COPY --from 逐項明列、搬移 runtime 需要的 ENV／WORKDIR／EXPOSE／USER）依該 spec。

重整原則（關鍵）

語意等價優先：重排指令前，先確認該調整不改變最終映像內容與建置結果。某些重排會改變行為（例如 ARG 的作用範圍跨 FROM 會失效、COPY 順序影響快取與覆蓋、RUN 之間有狀態相依、單階段改多階段時 runtime 缺少 build 期才有的檔案）。凡無法可靠保證等價的重整，先以 AskUserQuestion 向使用者確認（選項至少含「依建議重整（多階段＋六步）」「只在不改變行為前提下做最小重排」「維持原結構只補註解（略過重整，交給階段 C）」「其他」），確認後才覆寫。
已是多階段 → 將既有各階段對應到六步（build 階段涵蓋 1–4、runtime 階段涵蓋 5–6），補齊缺漏的快取最佳化與清理，不破壞既有 --from 依賴。
單階段改多階段 → 僅在能可靠判斷 runtime 真正需要哪些產物時才做；無法可靠判斷時，不臆測，標 # 需人工確認：runtime 需要的產物清單 並回報，退回「最小重排＋補註解」。
多階段不適用 → 若該映像本質上無法受益於多階段（例如純資料映像、最終就是要完整建置環境），保留單階段，於步驟 5 以註解說明「此映像不適用多階段縮小」，其餘步驟仍依序歸位。
對外契約不動：依 /jsc-shared:spec-dockerfile（ENTRYPOINT／CMD／EXPOSE／ENV／VOLUME／HEALTHCHECK／USER 語意與原檔一致，只可調整位置與分層）。
.dockerignore：若為了「複製檔案」步驟的正確性需要排除建置產物／node_modules／.git，可建立或補強 .dockerignore（僅新增排除項，不刪既有），並回報。

重整骨架（實際指令、base image、語言依階段 A 偵測結果填入；非 Node 專案請換成對應語言的安裝／建置指令與 runtime 基底）：

# 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>]

自我檢查：依 /jsc-shared:spec-dockerfile 的自我檢查清單（跨階段 ARG 重新宣告、runtime 帶齊產物、對外契約一致、路徑一致）。
此檔的「用途／更新日期」開頭註解區塊與逐行註解，於階段 C 由 /jsc-doc:funcs 的指令檔流程統一補齊／覆寫為標準格式；本階段先確保建置行為正確、六步結構清楚即可。
建置驗證：若環境可執行 docker build，重整後做一次建置驗證（或至少 docker build --check／語法檢查）確認可建置；無法執行時明確說明原因並標註風險（階段 C funcs 第 11 步亦會做語法驗證）。

階段 C：完整執行 /jsc-doc:funcs 處理流程

Dockerfile 六步整理完成後，以階段 A1 的專案根目錄為目標，依 /jsc-shared:spec-doc-funcs-handoff 對整個專案完整執行 /jsc-doc:funcs 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README；本次整理的 Dockerfile 會被視為部署設定檔補齊標頭與逐行註解）。

總結

各階段執行後輸出：

階段 A：專案根目錄、目標 Dockerfile 路徑、單／多階段、base image、推斷語言、既有 ENTRYPOINT／CMD／EXPOSE／ENV。
階段 B：重整摘要（六步歸位結果、是否改為多階段、縮小映像採用的 runtime 基底）、「需人工確認」清單、是否做過建置／語法驗證；並確認對外契約（ENTRYPOINT／CMD／EXPOSE／ENV 等）未被破壞。
階段 C：funcs 流程的處理結果（文件化的 function 與指令檔、重建的 README）。
列出本次新增／變更的檔案與其相對路徑，並提醒使用者於提交前確認 Dockerfile 可正確建置、容器能正常啟動。

呼叫方式

格式：[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes] — 全部可省略（專案根目錄預設目前工作目錄；Dockerfile 自動定位，多個時詢問）。

助理	呼叫
Claude Code / Antigravity	`/jsc-code:image`，或 `/jsc-code:image --project-dir ~/work/my-app --dockerfile build/Dockerfile`
Codex	`$image`，或 `$image --dockerfile docker/Dockerfile`，或用 `/skills` 選單
OpenCode	描述需求（如「把這個專案的 Dockerfile 整理成參數處理→安裝套件→複製檔案→執行程序→縮小映像檔→設定入口六步、用多階段建置縮小映像，最後跑 funcs 補文件並重建 README」）自動觸發

12 KiB Raw Blame History Unescape Escape