refactor(shared): switch code skills to jsc-shared
This commit is contained in:
+15
-15
@@ -18,21 +18,21 @@ argument-hint: "[--action-dir <action 根目錄>] [--node-version <node runtime
|
||||
|
||||
---
|
||||
|
||||
## 共用規範（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-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-doc-funcs-handoff`：最終階段完整執行 `/jsc-doc:funcs` 的標準流程。
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- **一定會中斷詢問的點**：階段 B 主程式「非 Node 需改寫」時（破壞性，須先確認），階段 D「新增 `@vercel/ncc` 等 build 相依」時（依 `/jsc-generic:spec-action-params` 經同意），以及階段 E 由 `/jsc-doc:funcs` 自身的「如何實作」詢問。
|
||||
- **保留行為**：Node 化只「翻譯」既有邏輯，不得擅自改變對外行為、輸入輸出契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依 `/jsc-generic:spec-action-params` 經使用者同意後為之。
|
||||
- **一定會中斷詢問的點**：階段 B 主程式「非 Node 需改寫」時（破壞性，須先確認），階段 D「新增 `@vercel/ncc` 等 build 相依」時（依 `/jsc-shared:spec-action-params` 經同意），以及階段 E 由 `/jsc-doc:funcs` 自身的「如何實作」詢問。
|
||||
- **保留行為**：Node 化只「翻譯」既有邏輯，不得擅自改變對外行為、輸入輸出契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依 `/jsc-shared:spec-action-params` 經使用者同意後為之。
|
||||
- **本 skill 只動**：action 專案根目錄內的主程式、主程式依賴鏈的 `.js`（搬移到 `src/`）、`package.json`（含 `scripts.build`）、`action.yml`／`action.yaml`、打包產物 `dist/`、`.gitignore`（確保 `dist/` 不被忽略），以及階段 E 由 funcs 流程處理的目標。**不產生** `Dockerfile`／`entrypoint.sh`（那是 action-docker 的範疇）。
|
||||
|
||||
---
|
||||
@@ -59,7 +59,7 @@ node action 相對 docker／composite 的**關鍵差異**（全程據此處理
|
||||
|
||||
## 參數來源優先序（開發中需要新參數時）
|
||||
|
||||
從零建立（A1a）、主程式 Node 化（階段 B）、對齊 `action.yml`（階段 C）或打包（階段 D）的過程中，若需要新的參數值，一律依 `/jsc-generic:spec-action-params` 的優先序處理：node action 主程式優先取 runner 注入的執行期環境變數（`process.env.GITHUB_*`；Gitea 亦提供 `GITEA_*` 同義變數，建議讀 `GITHUB_*` 以相容兩邊），既有 `inputs` 以 `process.env.INPUT_<大寫名稱>`（或 `core.getInput`）取用，取不到才以 `AskUserQuestion` 經使用者同意新增 `inputs`（由呼叫端 workflow 以 `with:` 傳入）；`secrets`／`vars` 一律視為不可用，需要時宣告為 `input` 由呼叫端傳入（範例見該 spec）。
|
||||
從零建立（A1a）、主程式 Node 化（階段 B）、對齊 `action.yml`（階段 C）或打包（階段 D）的過程中，若需要新的參數值，一律依 `/jsc-shared:spec-action-params` 的優先序處理：node action 主程式優先取 runner 注入的執行期環境變數（`process.env.GITHUB_*`；Gitea 亦提供 `GITEA_*` 同義變數，建議讀 `GITHUB_*` 以相容兩邊），既有 `inputs` 以 `process.env.INPUT_<大寫名稱>`（或 `core.getInput`）取用，取不到才以 `AskUserQuestion` 經使用者同意新增 `inputs`（由呼叫端 workflow 以 `with:` 傳入）；`secrets`／`vars` 一律視為不可用，需要時宣告為 `input` 由呼叫端傳入（範例見該 spec）。
|
||||
|
||||
---
|
||||
|
||||
@@ -152,7 +152,7 @@ runs:
|
||||
main: 'src/index.js' # 有相依打包後於階段 D 改為 'dist/index.js'
|
||||
```
|
||||
|
||||
- **`using` 版本**依 `/jsc-generic:spec-time-log` 之外另遵循版本規則：**預設 `node24`**（現行最新、本生態範本採用），帶 `--node-version` 時改用指定值。`node24` 需較新的 act runner；runner 太舊會報 `The runs.using key in action.yml must be one of: [composite docker node12 node16 node20 go], got node24`——此時**升級 act runner**，或（回報後）暫時退回 `node20`。**不用**沒有意義的 `latest`。
|
||||
- **`using` 版本**依 `/jsc-shared:spec-time-log` 之外另遵循版本規則：**預設 `node24`**（現行最新、本生態範本採用），帶 `--node-version` 時改用指定值。`node24` 需較新的 act runner；runner 太舊會報 `The runs.using key in action.yml must be one of: [composite docker node12 node16 node20 go], got node24`——此時**升級 act runner**，或（回報後）暫時退回 `node20`。**不用**沒有意義的 `latest`。
|
||||
- **`outputs` 去 `value`**：node action 的 `outputs.<name>` 只保留 `description`，**移除**任何 `value: ${{ steps.* }}`（那是 composite 寫法）；實際值於執行時由程式寫入 `$GITHUB_OUTPUT`。
|
||||
- **`inputs` 契約保留**：不更動既有 `inputs` 名稱／`required`／`default`；主程式以 `process.env.INPUT_<大寫名稱>`（或 `core.getInput`）取用，runner 會自動注入，**不需**像 composite 手動映射 `env:`。
|
||||
- 原本是 **docker／composite** action 改為 node 時，一併移除只服務原型態的欄位（`image`／`entrypoint`／`steps`），並在回報標示型態已變更；無法可靠等價轉換處以 `# 需人工確認` 標註、不臆測。
|
||||
@@ -162,7 +162,7 @@ runs:
|
||||
|
||||
node action 沒有 `entrypoint.sh`，橫幅改由**主程式 JS 最前面輸出**。在 `src/index.js`（或階段 B 決定的入口）最上方，於任何其他邏輯**之前**插入（或更新）橫幅輸出：
|
||||
|
||||
- **更新時間**依 `/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`（缺漏時以「（未提供）」標示）。
|
||||
- 若已存在本 skill 先前插入的橫幅（依可辨識註解標記），則**更新**其內容與時間戳，不重複插入。
|
||||
|
||||
@@ -202,7 +202,7 @@ node action 的 runner **不會自動 `npm install`**，因此相依必須隨 re
|
||||
|
||||
打包能把原始碼與相依編成單一檔，避免 commit 龐大的 `node_modules`：
|
||||
|
||||
1. 新增 build 相依（依 `/jsc-generic:spec-action-params`／本 skill「一定會中斷詢問的點」，屬新增相依，先向使用者確認）：`npm i -D @vercel/ncc`，並確保 `package.json` 有：
|
||||
1. 新增 build 相依（依 `/jsc-shared:spec-action-params`／本 skill「一定會中斷詢問的點」，屬新增相依，先向使用者確認）：`npm i -D @vercel/ncc`，並確保 `package.json` 有：
|
||||
```json
|
||||
"scripts": { "build": "ncc build src/index.js -o dist" }
|
||||
```
|
||||
@@ -223,7 +223,7 @@ node action 的 runner **不會自動 `npm install`**，因此相依必須隨 re
|
||||
|
||||
## 階段 E：完整執行 /jsc-doc:funcs 處理流程
|
||||
|
||||
標準化與打包完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc-generic:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc-doc:funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README；本次新增／變更的 `src/` 內 Node 主程式、`action.yml`、`package.json` 都會被涵蓋）。完成後依該 spec **統一時間戳**：回頭同步主程式橫幅輸出與註解區塊、`action.yml` 開頭註解區塊與 README 的更新時間，確保各處一致。
|
||||
標準化與打包完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc-shared:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc-doc:funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README；本次新增／變更的 `src/` 內 Node 主程式、`action.yml`、`package.json` 都會被涵蓋）。完成後依該 spec **統一時間戳**：回頭同步主程式橫幅輸出與註解區塊、`action.yml` 開頭註解區塊與 README 的更新時間，確保各處一致。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user