refactor(shared): switch code skills to jsc-shared
This commit is contained in:
@@ -18,29 +18,29 @@ argument-hint: "[--action-dir <action 根目錄>] [--node-version <node tag>] [-
|
||||
|
||||
---
|
||||
|
||||
## 共用規範（generic plugin，必要前置）
|
||||
## 共用規範（shared plugin，必要前置）
|
||||
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc-generic:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼。
|
||||
- `/jsc-generic:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認、不擴及無關檔案。
|
||||
- `/jsc-generic:spec-git-safety`：不破壞既有工作（絕不 `reset --hard`／`clean`）、`git mv` 保留歷史。
|
||||
- `/jsc-generic:spec-action-params`：action 參數來源優先序（環境變數 → 經同意新增 `inputs`）、`secrets`／`vars` 一律視為不可用。
|
||||
- `/jsc-generic:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、完成後統一同步時間戳。
|
||||
- `/jsc-generic:spec-dockerfile`：Dockerfile 六步流程、多階段建置、固定版號、自我檢查。
|
||||
- `/jsc-generic:spec-doc-funcs-handoff`：最終階段完整執行 `/jsc-doc:funcs` 的標準流程。
|
||||
- `/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/Taipei `yyyy/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-generic:spec-action-params` 經使用者同意後為之。
|
||||
- **保留行為**：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-generic:spec-action-params` 的優先序處理：Docker 容器 action 優先取 runner 注入的執行期環境變數（Node 主程式讀 `process.env.GITHUB_*`、`entrypoint.sh` 讀 `$GITHUB_*`；Gitea 亦提供 `GITEA_*` 同義變數，建議讀 `GITHUB_*` 以相容兩邊），取不到才以 `AskUserQuestion` 經使用者同意新增 `inputs`（容器內以 `INPUT_<大寫名稱>` 取用）；`secrets`／`vars` 一律視為不可用，需要時宣告為 `input` 由呼叫端 workflow 傳入（範例見該 spec）。
|
||||
從零建立（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）。
|
||||
|
||||
---
|
||||
|
||||
@@ -139,7 +139,7 @@ runs:
|
||||
|
||||
在 action 根目錄產生（或覆寫）`entrypoint.sh`：**啟動 node 主程式前，先輸出 action 名稱、用途、更新時間**。
|
||||
|
||||
- **更新時間**依 `/jsc-generic:spec-time-log`（Asia/Taipei、固定 `yyyy/MM/dd HH:mm:ss`、寫成檔內固定字串）。本階段先寫入暫定時間戳，**階段 E 完成後會統一同步各處時間戳**（見階段 E）。
|
||||
- **更新時間**依 `/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 "$@"`）。
|
||||
@@ -190,7 +190,7 @@ exec node /action/src/index.js "$@"
|
||||
5. **縮小映像檔**：多階段建置，runtime 改用 slim 基底，只 `COPY --from=build` 帶入主程式執行**真正需要**的產物——有 build 產物時帶入 `dist/` 與 production `node_modules`（`npm prune --omit=dev` 或重裝 production 相依），純 JS 無 build 時帶入 `src/` 與 production `node_modules`；若 D0 判定 runtime 需要某些 OS 執行檔，於 runtime 階段一併安裝（slim 基底可能不含）。不要把 build 階段的 dev 相依與快取帶進最終映像；**`COPY --from=build` 必須逐項明列路徑，不得整包 `COPY --from=build /action /action`**（整包搬等於沒有縮小）。
|
||||
6. **設定入口**：`ENTRYPOINT` 指向 `entrypoint.sh`，其內 `node` 路徑為 D0 的入口檔。
|
||||
|
||||
base image 版本依 `/jsc-generic: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`。
|
||||
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 套件等視主程式需要增刪：
|
||||
|
||||
@@ -231,7 +231,7 @@ 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-generic:spec-dockerfile`（runtime 與 build 版號一致、以獨立 runtime ARG 帶入不用 `${VERSION}-slim` 組裝、`-alpine`／`-slim` 變體沿用同一 tag、使用者要求 `latest` 時 runtime 用 `node:slim`）。
|
||||
- **版號對齊**：依 `/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 指令檔流程統一補齊。
|
||||
|
||||
@@ -239,7 +239,7 @@ ENTRYPOINT ["/action/entrypoint.sh"]
|
||||
|
||||
## 階段 E：完整執行 /jsc-doc:funcs 處理流程
|
||||
|
||||
容器化與 Node 化完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc-generic:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc-doc:funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README；本次新增／變更的 `entrypoint.sh`、`Dockerfile` 與 `src/` 內 Node 主程式都會被涵蓋）。完成後依該 spec **統一時間戳**：回頭同步 `entrypoint.sh` 橫幅輸出與註解區塊、`Dockerfile` 註解區塊與 README 的更新時間，確保各處一致。
|
||||
容器化與 Node 化完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc-shared:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc-doc:funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README；本次新增／變更的 `entrypoint.sh`、`Dockerfile` 與 `src/` 內 Node 主程式都會被涵蓋）。完成後依該 spec **統一時間戳**：回頭同步 `entrypoint.sh` 橫幅輸出與註解區塊、`Dockerfile` 註解區塊與 README 的更新時間，確保各處一致。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user