162 lines
15 KiB
Markdown
162 lines
15 KiB
Markdown
---
|
||
name: code-image
|
||
description: 把專案的 `Dockerfile` 整理成固定六步流程並串接文件化流程：(1) 找出專案根目錄與目標 `Dockerfile`、判斷語言／生態與既有建置方式；(2) 在保留建置行為的前提下，把 `Dockerfile` 重整為 **參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口** 六步流程（以多階段建置縮小最終映像，可調參數集中於檔首 `ARG`，相依描述先 `COPY` 以利 layer 快取）；(3) 最後完整執行 `/jsc:doc-funcs` 處理流程（function 文件、`Dockerfile` 等指令檔逐行註解、重建 README）。當使用者說整理／重構 Dockerfile、把 Dockerfile 排成參數處理→安裝→複製→執行→縮小→入口六步、優化映像檔分層／多階段建置、縮小 image，或提到 code-image 時觸發。不適用於：Gitea／GitHub action 容器化（用 code-action-docker）、composite action（用 code-action-composite）、或專案內沒有也不需要 Dockerfile 的情況。
|
||
argument-hint: "[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes]"
|
||
---
|
||
|
||
# code-image — Dockerfile 六步流程整理＋文件化
|
||
|
||
三階段 skill：先做**前置設定與偵測**（找出專案根目錄、定位目標 `Dockerfile`、判斷語言／生態與既有建置方式），再把 `Dockerfile` **重整為固定六步流程**（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，並以多階段建置縮小最終映像），最後**完整執行 `/jsc:doc-funcs` 處理流程**替整個專案補文件並重建 README。
|
||
|
||
| 階段 | 動作 |
|
||
| --- | --- |
|
||
| A. 前置設定與偵測 | 決定專案根目錄 → 定位目標 `Dockerfile`（找不到則詢問，不臆造）→ 讀現有指令、判斷語言／生態、既有 base image 與建置流程 |
|
||
| B. 整理 Dockerfile 為六步流程 | 在**保留建置行為**前提下，把指令重整／歸位為六步：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口；多階段建置縮小映像；行為不等價處標「需人工確認」並先確認 |
|
||
| C. 串接 doc-funcs | 對整個專案完整執行 `/jsc:doc-funcs` 流程（function 文件、`Dockerfile` 等指令檔逐行註解、重建 README） |
|
||
|
||
---
|
||
|
||
## 輸出規範（務必遵守）
|
||
|
||
- **語言**：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用**繁體中文（台灣用語）**；僅識別字、檔名、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`／第三方依賴。
|
||
|
||
---
|
||
|
||
## 參數
|
||
|
||
格式：`[--project-dir <專案根目錄>] [--dockerfile <Dockerfile 路徑>] [--yes]`
|
||
|
||
- `--project-dir <專案根目錄>`：專案根目錄。**省略時預設目前工作目錄**。
|
||
- `--dockerfile <Dockerfile 路徑>`：指定要整理的 `Dockerfile`（相對專案根目錄）。省略時依 A2 自動定位；找到多個時詢問。
|
||
- `--yes`：盡量不中斷。即使帶此參數，「重整無法保證建置行為等價」與 doc-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 doc-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 doc-funcs 第 0 步沿用，也決定縮小映像時的 runtime 基底選擇）。
|
||
|
||
輸出偵測結果（目標 Dockerfile 路徑、單／多階段、base image、推斷語言、既有 `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`），再進入階段 B。
|
||
|
||
---
|
||
|
||
## 階段 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` 置於最後，語意與原檔一致。
|
||
|
||
**重整原則（關鍵）**
|
||
|
||
- **語意等價優先**：重排指令前，先確認該調整不改變最終映像內容與建置結果。某些重排會改變行為（例如 `ARG` 的作用範圍跨 `FROM` 會失效、`COPY` 順序影響快取與覆蓋、`RUN` 之間有狀態相依、單階段改多階段時 runtime 缺少 build 期才有的檔案）。**凡無法可靠保證等價的重整，先以 `AskUserQuestion` 向使用者確認**（選項至少含「依建議重整（多階段＋六步）」「只在不改變行為前提下做最小重排」「維持原結構只補註解（略過重整，交給階段 C）」「其他」），確認後才覆寫。
|
||
- **已是多階段** → 將既有各階段對應到六步（build 階段涵蓋 1–4、runtime 階段涵蓋 5–6），補齊缺漏的快取最佳化與清理，不破壞既有 `--from` 依賴。
|
||
- **單階段改多階段** → 僅在能可靠判斷 runtime 真正需要哪些產物時才做；無法可靠判斷時，**不臆測**，標 `# 需人工確認：runtime 需要的產物清單` 並回報，退回「最小重排＋補註解」。
|
||
- **多階段不適用** → 若該映像本質上無法受益於多階段（例如純資料映像、最終就是要完整建置環境），保留單階段，於步驟 5 以註解說明「此映像不適用多階段縮小」，其餘步驟仍依序歸位。
|
||
- **對外契約不動**：`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`／`VOLUME`／`HEALTHCHECK`／`USER` 的語意保持與原檔一致；只可調整位置與分層，不可改變值或刪除。
|
||
- **`.dockerignore`**：若為了「複製檔案」步驟的正確性需要排除建置產物／`node_modules`／`.git`，可建立或補強 `.dockerignore`（僅新增排除項，不刪既有），並回報。
|
||
|
||
重整骨架（實際指令、base image、語言依階段 A 偵測結果填入；非 Node 專案請換成對應語言的安裝／建置指令與 runtime 基底）：
|
||
|
||
```Dockerfile
|
||
# 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>]
|
||
```
|
||
|
||
- **自我檢查**：重整後確認 (1) `ARG` 在使用它的 `FROM` 之後有重新宣告（跨階段 `ARG` 規則）；(2) runtime 階段 `COPY --from` 帶齊執行所需全部產物；(3) `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV` 與原檔語意一致；(4) 路徑（`WORKDIR`／`COPY` 落點）一致、容器能找到入口。
|
||
- 此檔的「用途／更新日期」開頭註解區塊與逐行註解，於階段 C 由 `/jsc:doc-funcs` 的指令檔流程統一補齊／覆寫為標準格式；本階段先確保**建置行為**正確、六步結構清楚即可。
|
||
- **建置驗證**：若環境可執行 `docker build`，重整後做一次建置驗證（或至少 `docker build --check`／語法檢查）確認可建置；無法執行時明確說明原因並標註風險（階段 C doc-funcs 第 11 步亦會做語法驗證）。
|
||
|
||
---
|
||
|
||
## 階段 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 的專案根目錄為目標專案。
|
||
|
||
---
|
||
|
||
## 總結
|
||
|
||
各階段執行後輸出：
|
||
|
||
- **階段 A**：專案根目錄、目標 `Dockerfile` 路徑、單／多階段、base image、推斷語言、既有 `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`。
|
||
- **階段 B**：重整摘要（六步歸位結果、是否改為多階段、縮小映像採用的 runtime 基底）、「需人工確認」清單、是否做過建置／語法驗證；並確認對外契約（`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV` 等）未被破壞。
|
||
- **階段 C**：doc-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 | `$code-image`，或 `$code-image --dockerfile docker/Dockerfile`，或用 `/skills` 選單 |
|
||
| OpenCode | 描述需求（如「把這個專案的 Dockerfile 整理成參數處理→安裝套件→複製檔案→執行程序→縮小映像檔→設定入口六步、用多階段建置縮小映像，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |
|