feat(code-action-node): 新增 Node（JavaScript）action 標準化 skill 並登錄 README

2026-07-17 13:34:02 +08:00
parent 8419dbbca9
commit be96880022
2 changed files with 263 additions and 1 deletions
@@ -42,6 +42,7 @@ code/
 │   ├── code-sync/           # 依擁有者批次 clone／更新 Gitea 專案
 │   ├── code-action-docker/  # action 容器化（Node 主程式）+ 串接 doc-funcs
 │   ├── code-action-composite/ # composite action 標準化 + 串接 doc-funcs
+│   ├── code-action-node/    # Node（JS）action 標準化（ncc 打包）+ 串接 doc-funcs
 │   └── code-image/          # Dockerfile 整理成六步流程 + 串接 doc-funcs
 ├── AGENTS.md                # 跨助理共用指引
 └── README.md
@@ -134,7 +135,7 @@ git -C ~/jsc-plugin pull
 cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/

 # 移除
-rm -rf ~/.config/opencode/skills/{code-review-resolve,code-issues,code-nuget,code-sync,code-action-docker,code-action-composite,code-image}
+rm -rf ~/.config/opencode/skills/{code-review-resolve,code-issues,code-nuget,code-sync,code-action-docker,code-action-composite,code-action-node,code-image}
 ```

 > **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
@@ -228,6 +229,16 @@ rm -rf ~/.config/opencode/skills/{code-review-resolve,code-issues,code-nuget,cod
 - **Codex**：`$code-action-composite`，或 `$code-action-composite --action-dir ~/work/my-action`，或用 `/skills` 選單
 - **OpenCode**：描述需求（如「把這個 composite action 標準化，在 steps 最前面加一個會輸出 action 名稱／用途／更新時間的 step，最後跑 doc-funcs 補文件並重建 README」）自動觸發

+### `code-action-node`
+
+把 Gitea／GitHub「Node（JavaScript）action」專案標準化，再串接文件化流程。node action 由 **runner 內建 Node 直接執行 `runs.main`**（不需 Docker、啟動比 docker action 快），但 **runner 不會自動 `npm install`**——這是與 docker／composite 最大的差異。五階段：(A) 找出 action 專案、讀 `action.yml`／`action.yaml` 的 `name`／`description`、判斷主程式語言（無 manifest 可**問答式從零建立**）；(B) 主程式**非 Node 則保守改寫為 Node**（高風險，先以 AskUserQuestion 確認，保留對外行為），並把**主程式依賴鏈**的 `.js` 集中到 **`src/`**（工具設定檔與測試目錄不搬）、同步更新 `require`／`import` 路徑、`package.json` 與 `action.yml`；(C) 對齊 `runs` 為 node action（`using: node24` + `main`，`--node-version` 可覆寫、runner 太舊退 `node20`），**`outputs` 去除 `value`**（node 只需 `description`，值於執行時寫入 `$GITHUB_OUTPUT`）、**`inputs` 由 runner 自動注入 `INPUT_*`**（不像 composite 需手動映射），並在**主程式入口最前面**以 `console.log` 輸出 action 名稱／用途／更新時間（Asia/Taipei `yyyy/MM/dd HH:mm:ss`；node action 無 `entrypoint.sh`，橫幅改在 JS 輸出）；(D) 相依處理——**零相依**則 `main` 直接指 `src/index.js`，**有相依**則以 [`@vercel/ncc`](https://github.com/vercel/ncc) 打包成 `dist/index.js`、`main` 改指 `dist/index.js` 並**把 `dist/` commit 進 repo**（確認 `.gitignore` 未忽略）；(E) 對整個專案**完整執行 `/jsc:doc-funcs`**（function 文件、`src/` 主程式與 `action.yml` 註解、重建 README）。開發中需要新參數時依**參數來源優先序**處理：主程式優先取 runner 注入的 `GITHUB_*`／`GITEA_*` 執行期環境變數，既有 `inputs` 以 `process.env.INPUT_*`（或 `core.getInput`）取用，無法取得才經使用者同意**新增 `inputs`**；`secrets`／`vars` **一律視為不可用**，需要時宣告為 `inputs` 由呼叫端 workflow 以 `with:` 傳入，未經同意不擅改 `inputs`／`outputs` 契約。skill 各檔的「更新時間」於最終階段（doc-funcs 完成後）**統一同步為同一時間戳**。
+
+參數：`[--action-dir <action 根目錄>] [--node-version <node runtime>] [--main <主程式檔>]`（根目錄預設目前工作目錄；node 版本預設 `node24`；主程式自動判斷）。
+
+- **Claude Code / Antigravity**：`/jsc:code-action-node`，或 `/jsc:code-action-node --action-dir ~/work/my-action --node-version node24`
+- **Codex**：`$code-action-node`，或 `$code-action-node --action-dir ~/work/my-action`，或用 `/skills` 選單
+- **OpenCode**：描述需求（如「把這個 action 主程式改成 node、主程式相關 js 收進 src/，對齊 action.yml 為 node action、在主程式最前面輸出 action 名稱／用途／更新時間，有相依就用 ncc 打包成 dist 並 commit，最後跑 doc-funcs 補文件並重建 README」）自動觸發
+
 ### `code-image`

 把專案既有的 `Dockerfile` **整理成固定六步流程**，再串接文件化流程。三階段：(A) 找出專案根目錄、定位目標 `Dockerfile`（找不到則詢問、**不臆造**；要產生全新 action 容器請改用 `code-action-docker`），讀現有指令、判斷語言／生態與既有 base image／建置流程；(B) 在**保留建置行為**前提下，把指令重整／歸位為**六步流程**（參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口）：可調參數集中於檔首 `ARG`、相依描述先 `COPY` 以利 layer 快取、**多階段建置**讓 runtime 改用較小基底（`*-slim`／`*-alpine`／`distroless` 等）只帶執行所需產物；`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV` 等對外契約不動，**無法保證等價的重整先以 AskUserQuestion 確認**（可選最小重排或只補註解）；(C) 對整個專案**完整執行 `/jsc:doc-funcs`**（`Dockerfile` 等指令檔逐行註解、function 文件、重建 README）。
@@ -0,0 +1,251 @@
+---
+name: code-action-node
+description: 將 Gitea／GitHub「Node（JavaScript）action」專案標準化（目錄沒有 action manifest 時可問答式從零建立），並串接文件化流程：(1) 檢查 action 主程式是否為 Node，否則保守改寫為 Node，且主程式及其依賴鏈的 `.js` 檔集中到 `src/` 資料夾（工具設定檔與測試目錄不搬）；(2) 對齊 `action.yml` 為 node action（`runs.using` 設為 `node24`、指定 `runs.main`，`outputs` 只留 `description` 不設 `value`，`inputs` 由 runner 自動注入 `INPUT_*`），並在主程式入口最前面輸出 action 名稱／用途／更新時間橫幅；(3) 處理相依打包——零相依則 `main` 直接指向 `src/index.js`，有相依則以 `@vercel/ncc` 打包成 `dist/index.js`、`main` 改指 `dist/index.js` 並將 `dist/` commit 進 repo（runner 不會自動 `npm install`）；(4) 開發中需要新參數時優先取用 runner 注入的 `GITHUB_*`（Gitea 亦有 `GITEA_*`）執行期環境變數，無法取得才詢問使用者是否新增 `inputs`（`secrets`／`vars` 一律視為不可用，需要時宣告為 `inputs` 由呼叫端 workflow 傳入）；(5) 最後完整執行 `/jsc:doc-funcs` 處理流程（function 文件、指令檔逐行註解、重建 README）。當使用者說把 action 改成 node／JavaScript action、從零建立／產生一個 node action、action 主程式 node 化、把 js 收進 src、用 ncc 打包 action、處理 node action 相依或參數來源，或提到 code-action-node 時觸發。不適用於：Docker 容器 action（用 code-action-docker）、composite action（用 code-action-composite）、只整理既有 Dockerfile（用 code-image）、或不需 action 化／文件化的一般 repo。
+argument-hint: "[--action-dir <action 根目錄>] [--node-version <node runtime，如 node24>] [--main <主程式檔>]"
+---
+
+# code-action-node — Node（JavaScript）action 標準化＋文件化
+
+五階段 skill：先做**前置設定與偵測**（找出 action 專案、讀取名稱／用途、判斷主程式語言），再把**主程式 Node 化並將主程式依賴鏈的 `.js` 收進 `src/`**，接著**對齊 `action.yml` 為 node action 並在主程式入口最前面注入輸出名稱／用途／更新時間的啟動橫幅**，然後**處理相依打包**（零相依直接跑 `src/`，有相依以 `@vercel/ncc` 打包成 `dist/` 並 commit），最後**完整執行 `/jsc:doc-funcs` 處理流程**替整個專案補文件並重建 README。產出的 node action 由 **runner 內建的 Node runtime 直接執行 `runs.main`**（不需 Docker、啟動比 docker action 快）。各階段開發中需要新參數時，一律套用下方「**參數來源優先序**」規則。目錄沒有 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. 對齊 action.yml + 啟動橫幅 | `runs` 對齊 node action（`using: node24` + `main`）、`outputs` 去除 `value`、`inputs` 契約保留；在主程式入口最前面輸出 action **名稱／用途／更新時間** |
+| D. 相依處理與打包 | 零相依 → `main` 指 `src/index.js`；有相依 → `ncc build` 成 `dist/index.js`、`main` 改指 `dist/index.js`、`dist/` commit 進 repo（runner 不會 `npm install`） |
+| E. 串接 doc-funcs | 對整個 action 專案完整執行 `/jsc:doc-funcs` 流程（function 文件、指令檔逐行註解、重建 README） |
+
+---
+
+## 共用規範（generic plugin，必要前置）
+
+執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
+
+- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼。
+- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測／需人工確認、不擴及無關檔案。
+- `/jsc:spec-git-safety`：不破壞既有工作（絕不 `reset --hard`／`clean`）、`git mv` 保留歷史。
+- `/jsc:spec-action-params`：action 參數來源優先序（環境變數 → 經同意新增 `inputs`）、`secrets`／`vars` 一律視為不可用。
+- `/jsc:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、完成後統一同步時間戳。
+- `/jsc:spec-doc-funcs-handoff`：最終階段完整執行 `/jsc:doc-funcs` 的標準流程。
+
+本 skill 特有補充：
+
+- **一定會中斷詢問的點**：階段 B 主程式「非 Node 需改寫」時（破壞性，須先確認），階段 D「新增 `@vercel/ncc` 等 build 相依」時（依 `/jsc:spec-action-params` 經同意），以及階段 E 由 `/jsc:doc-funcs` 自身的「如何實作」詢問。
+- **保留行為**：Node 化只「翻譯」既有邏輯，不得擅自改變對外行為、輸入輸出契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依 `/jsc:spec-action-params` 經使用者同意後為之。
+- **本 skill 只動**：action 專案根目錄內的主程式、主程式依賴鏈的 `.js`（搬移到 `src/`）、`package.json`（含 `scripts.build`）、`action.yml`／`action.yaml`、打包產物 `dist/`、`.gitignore`（確保 `dist/` 不被忽略），以及階段 E 由 doc-funcs 流程處理的目標。**不產生** `Dockerfile`／`entrypoint.sh`（那是 code-action-docker 的範疇）。
+
+---
+
+## 三種 action 的分工（先確認選對 skill）
+
+| 型態 | `runs.using` | 執行方式 | 對應 skill |
+| --- | --- | --- | --- |
+| **node（本 skill）** | `node24`／`node20`… | runner 內建 Node 直接跑 `main` 指定的 `.js`；**不會 `npm install`** | `code-action-node` |
+| composite | `composite` | 依序執行 `steps`（純 YAML 組合） | `code-action-composite` |
+| docker | `docker` | 建 image、於容器內執行（可 `npm ci`） | `code-action-docker` |
+
+node action 相對 docker／composite 的**關鍵差異**（全程據此處理）：
+
+1. **相依不會自動安裝**：runner 不在 action repo 內跑 `npm install`。要嘛**零相依**，要嘛把相依**打包／commit 進 repo**（見階段 D）。
+2. **無 `entrypoint.sh`／`Dockerfile`**：啟動橫幅改由**主程式（JS）最前面 `console.log` 輸出**，不另外產生 shell 入口。
+3. **`inputs` 自動注入**：runner 會把每個 input 轉成 `INPUT_<NAME>` 環境變數（名稱轉大寫、空白換底線），JS 內以 `process.env.INPUT_<NAME>` 或 `core.getInput('<name>')` 取值；composite 需手動映射，node **不用**。
+4. **`outputs` 只需 `description`**：實際值在執行時由程式寫入 `$GITHUB_OUTPUT`（或 `core.setOutput`），`action.yml` 的 `outputs` **不設也不該有 `value`**（那是 composite 的寫法）。
+5. **`required: true` 不會自動擋、input 一律字串**：必填檢查與型別轉換都要在程式裡自己做。
+6. **`main` 路徑相對 action 根目錄**：讀 action 自帶檔案用 `__dirname` 或 `process.env.GITHUB_ACTION_PATH` 定位，不要用相對呼叫端工作目錄的路徑。
+7. **node 專屬的 `pre`／`post`**：可用 `runs.pre`／`runs.post`（`pre` 不支援 `uses: ./` 的 local action）；composite／docker 沒有。
+
+---
+
+## 參數來源優先序（開發中需要新參數時）
+
+從零建立（A1a）、主程式 Node 化（階段 B）、對齊 `action.yml`（階段 C）或打包（階段 D）的過程中，若需要新的參數值，一律依 `/jsc: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）。
+
+---
+
+## 參數
+
+格式：`[--action-dir <action 根目錄>] [--node-version <node runtime>] [--main <主程式檔>]`
+
+- `--action-dir <action 根目錄>`：action 專案根目錄。**省略時預設目前工作目錄**（須含 `action.yml`／`action.yaml`，否則依 A1 詢問）。
+- `--node-version <node runtime>`：`action.yml` 的 `runs.using` node runtime（如 `node24`、`node20`）。**省略時預設 `node24`**（現行最新，本生態範本採用）；`node24` 需較新的 act runner，runner 太舊會報 `The runs.using key ... got node24`，此時升級 act runner 或退回 `node20`（見階段 C）。
+- `--main <主程式檔>`：指定主程式入口檔（相對 action 根目錄）。省略時依 A3 自動判斷。
+
+---
+
+## 階段 A：前置設定與偵測
+
+### A1. 決定 action 根目錄
+
+- 帶 `--action-dir` → 採用（展開 `~`）。
+- 省略 → 用目前工作目錄。
+- 根目錄須存在 `action.yml` 或 `action.yaml`（action manifest）。**找不到** action manifest → **不臆測**、不逕自動工；以 `AskUserQuestion` 詢問使用者要「**從零建立**新的 Node action」還是「提供正確的 action 路徑」：選「從零建立」→ 進入 A1a；選「提供路徑」→ 依新路徑重跑 A1。
+
+### A1a. 從零建立 Node action（問答式）
+
+依序以問答收集需求，再產生 manifest 與主程式骨架：
+
+1. **action 名稱**：用於 `action.yml` 的 `name`。
+2. **輸入與輸出參數**：逐一收集 `inputs`（名稱、`description`、`required`、`default`）與 `outputs`（名稱、`description`；**不收集 `value`**）；description 盡量繁體中文、無亂碼；沒有可留空。
+3. **執行目標**：詢問此 action 要達成什麼，整理濃縮成一句話作為 `action.yml` 的 `description`（盡量繁體中文、無亂碼）。
+
+收集完成後，於 action 根目錄產生：`action.yml`（`runs.using: node24`、`runs.main: src/index.js`，含收集到的 `name`／`description`／`inputs`／`outputs`）與 `src/index.js` 主程式（依執行目標以 Node 實作，輸入以 `process.env.INPUT_<NAME>` 讀取、輸出以附加寫入 `process.env.GITHUB_OUTPUT`，開發中需要新參數時套用「參數來源優先序」）；預設走**零相依**路線。完成後接續 A2 往後流程（A3 判定為 Node，階段 B 走「已是 Node」分支，階段 C／D 照常對齊 manifest 與處理相依）。
+
+### A2. 讀取 action 名稱與用途
+
+從 action manifest 讀取：
+
+- `name`：action 名稱（供啟動橫幅與 README 使用）。
+- `description`：action 用途。
+- `runs`：目前的執行設定（`using`、`main`、`image`、`entrypoint`、`steps` 等）。
+- `inputs`／`outputs`：對外契約（後續不得破壞）。
+
+若 `name`／`description` 缺漏，回報並請使用者補；無法取得時於後續輸出以「（未提供）」保守標示，**不編造**。
+
+### A3. 判斷目前主程式與語言
+
+依序判斷主程式入口（取第一個成立者）：
+
+1. 帶 `--main <主程式檔>` → 直接採用。
+2. `action.yml` 為 JS action（`runs.using: node*`）→ 取 `runs.main`。
+3. `action.yml` 為 docker action（`runs.using: docker`）→ 看 `runs.entrypoint`／`Dockerfile` 的 `ENTRYPOINT`／`CMD` 推主程式（並提醒：轉為 node action 會**移除容器化**，若原本刻意用 docker，宜改用 `code-action-docker`）。
+4. `action.yml` 為 composite（`runs.using: composite`）→ 從 `steps` 內實際執行的指令推主程式（提醒：composite 轉 node 屬破壞性改寫）。
+5. 以上皆無 → 依專案檔與副檔名分布推斷（`package.json` 的 `main`／`bin`、`index.js`、`*.sh`、`*.py` 等）。
+
+判定**主程式是否為 Node**：入口為 `.js`／`.mjs`／`.cjs` 且由 `node` 執行即視為 Node；入口為 shell／python／其他則視為非 Node。輸出偵測結果（action 名稱、用途、主程式檔、判定語言、是否為 Node、目前 `runs.using`），再進入階段 B。
+
+---
+
+## 階段 B：主程式 Node 化，並將主程式依賴鏈的 `.js` 收進 `src/`
+
+### B1. 主程式 Node 化
+
+- **已是 Node** → 確認入口檔，不改寫邏輯，直接進 B2。
+- **非 Node（shell／python／其他）** → 這是**破壞性高風險決策**：先以 `AskUserQuestion` 向使用者確認是否改寫為 Node，選項至少含「改寫為 Node」「改用 code-action-docker（維持原語言容器化）」「其他」。經確認後才改寫：
+  - 逐段把原主程式邏輯**保守翻譯**為 Node（建議 `src/index.js`）；保留對外行為、輸入（環境變數／`INPUT_*`／args）與輸出（`$GITHUB_OUTPUT`／stdout／exit code／檔案副作用）契約。
+  - 外部指令呼叫以 `child_process`（`execFileSync`／`spawnSync`）對應；檔案操作以 `fs`；環境變數以 `process.env`。
+  - 任何無法可靠等價翻譯處，**不臆測**：以 `// 需人工確認：...` 標註並回報。
+  - 改寫完成後，原非 Node 主程式於 B2 一併處理（移除或保留由使用者裁示；預設保留並在 README／回報標註已由 Node 取代）。
+
+### B2. 主程式依賴鏈的 `.js` 集中到 `src/`
+
+- 在 action 根目錄建立 `src/`（若不存在）。
+- 將**主程式入口及其 `require`／`import` 依賴鏈**的 `.js`／`.mjs`／`.cjs`（排除 `node_modules`／`.git`／`.docs`／`dist`／第三方依賴）**移入 `src/`**，優先 `git mv` 保留歷史。主程式入口統一為 `src/index.js`（或 `src/<main>.js`）。
+- **明文排除、不搬**：外部工具依慣例路徑尋找的檔案——`*.config.js`（`eslint.config.js`／`jest.config.js`／`ncc` 等工具設定）、`.*rc.js`、husky／commitlint 等工具設定，以及 `test/`／`tests/`／`scripts/` 目錄；搬走會弄壞 lint／test／build 流程。
+- **移動後必須更新所有引用**，確保不破壞：
+  - 模組間的 `require`／`import` 相對路徑。
+  - `package.json` 的 `main`／`bin`／`scripts`／`exports`（指向 `src/...`；`scripts.build` 的 ncc 入口指向 `src/index.js`）。
+  - `action.yml` 的 `runs.main`（先指向 `src/index.js`；若階段 D 判定需打包，再改指 `dist/index.js`）。
+- 若 `src/` 需要的相依尚未宣告，於 `package.json` 補上；不擅自新增與功能無關的相依（`@vercel/ncc` 屬階段 D 的 build 相依，經同意後才加）。
+
+---
+
+## 階段 C：對齊 action.yml 為 node action，並注入啟動橫幅
+
+### C1. 對齊 `runs` 為 node action
+
+將 manifest 的 `runs` 對齊為 node（JavaScript）action，**保留既有 `inputs`／`outputs`／`name`／`description`**：
+
+```yaml
+runs:
+  using: 'node24'        # 見版本說明；--node-version 可覆寫、runner 太舊退 node20
+  main: 'src/index.js'   # 有相依打包後於階段 D 改為 'dist/index.js'
+```
+
+- **`using` 版本**依 `/jsc: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`），並在回報標示型態已變更；無法可靠等價轉換處以 `# 需人工確認` 標註、不臆測。
+- 選填的 `runs.pre`／`runs.post`（node 專屬）僅在原本已有、或使用者明確要求時才設定；`pre` 不支援 `uses: ./` 的 local action。
+
+### C2. 注入啟動橫幅（主程式入口最前面輸出名稱／用途／更新時間）
+
+node action 沒有 `entrypoint.sh`，橫幅改由**主程式 JS 最前面輸出**。在 `src/index.js`（或階段 B 決定的入口）最上方，於任何其他邏輯**之前**插入（或更新）橫幅輸出：
+
+- **更新時間**依 `/jsc:spec-time-log`（Asia/Taipei、固定 `yyyy/MM/dd HH:mm:ss`、寫成檔內固定字串）。本階段先寫入暫定時間戳，**階段 E 完成後會統一同步各處時間戳**（見階段 E）。
+- 名稱／用途取自階段 A2 的 `action.yml`（缺漏時以「（未提供）」標示）。
+- 若已存在本 skill 先前插入的橫幅（依可辨識註解標記），則**更新**其內容與時間戳，不重複插入。
+
+範例（純 `console.log`、零相依；用 `@actions/core` 時可改 `core.info`）：
+
+```js
+// action 啟動橫幅：輸出名稱／用途／更新時間（此區塊由 code-action-node 維護）
+console.log('================================================');
+console.log('Action  : <action name>');
+console.log('用途    : <action description>');
+console.log('更新時間: 2026/07/17 12:00:00');
+console.log('================================================');
+```
+
+- 橫幅只做輸出，**不得**改變既有主邏輯的執行順序或副作用。
+- 此區塊的「用途／更新時間」與檔內註解，最終會在階段 E 由 `/jsc:doc-funcs` 的指令檔／function 流程統一補齊／覆寫為標準格式；本階段先確保**執行期輸出**正確即可。
+
+---
+
+## 階段 D：相依處理與打包（零相依直接跑 src/，有相依用 ncc 打包成 dist/）
+
+node action 的 runner **不會自動 `npm install`**，因此相依必須隨 repo 提供。先盤點主程式相依，再二擇一：
+
+### D0. 盤點相依
+
+檢視 `src/` 主程式與 `package.json` 的 `dependencies`：
+
+- **完全零相依**（只用 Node 內建模組，如 `fs`／`os`／`path`／`child_process`）→ 走 D1。
+- **有第三方相依**（如 `@actions/core`／`@actions/github` 或其他 npm 套件）→ 走 D2 打包。
+
+### D1. 零相依：main 直接指 src/index.js
+
+- 確認 `action.yml` 的 `runs.main: src/index.js`，**不需** build 步驟、**不需** `dist/`。
+- `package.json` 可保留（或補上）`scripts.build`（`ncc build src/index.js -o dist`）備用，但零相依情況不必執行。
+
+### D2. 有相依：以 @vercel/ncc 打包成 dist/ 並 commit
+
+打包能把原始碼與相依編成單一檔，避免 commit 龐大的 `node_modules`：
+
+1. 新增 build 相依（依 `/jsc:spec-action-params`／本 skill「一定會中斷詢問的點」，屬新增相依，先向使用者確認）：`npm i -D @vercel/ncc`，並確保 `package.json` 有：
+   ```json
+   "scripts": { "build": "ncc build src/index.js -o dist" }
+   ```
+2. 執行打包產生 `dist/index.js`：`npx ncc build src/index.js -o dist`。
+3. 將 `action.yml` 的 `runs.main` 改為 `dist/index.js`。
+4. **把 `dist/` commit 進 repo**：確認 `.gitignore` **沒有**忽略 `dist/`（若有，移除該規則或加 `!dist/`），並 `git add dist/`。
+5. 於回報提醒：**每次改 `src/` 都要重新 `ncc build` 並提交 `dist/`**，否則 action 執行的是舊版打包產物。
+
+> 另一可行但不建議的做法：直接 commit `node_modules`（體積大、跨平台原生模組易出問題）。預設採用 ncc 打包。
+
+### D3. 版本與自我檢查
+
+- `runs.main` 指向的檔案（`src/index.js` 或 `dist/index.js`）必須**確實存在於 repo**、且為 runner 可直接執行的 JS。
+- `runs.using` 的 node 版本需與目標 runner 相容（見階段 C）。
+- 橫幅輸出、`INPUT_*` 讀取、`$GITHUB_OUTPUT` 寫入在打包後仍正確（ncc 打包不改執行語意，但入口路徑改變，確認 `main` 已同步更新）。
+
+---
+
+## 階段 E：完整執行 /jsc:doc-funcs 處理流程
+
+標準化與打包完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc:doc-funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README；本次新增／變更的 `src/` 內 Node 主程式、`action.yml`、`package.json` 都會被涵蓋）。完成後依該 spec **統一時間戳**：回頭同步主程式橫幅輸出與註解區塊、`action.yml` 開頭註解區塊與 README 的更新時間，確保各處一致。
+
+---
+
+## 總結
+
+各階段執行後輸出：
+
+- **階段 A**：action 根目錄、action 名稱／用途、原主程式檔與語言、是否為 Node、目前 `runs.using`；若走 A1a 從零建立，列出問答收集結果（名稱／輸入輸出／目標）。
+- **階段 B**：是否改寫主程式（及改寫摘要與「需人工確認」清單）、搬入 `src/` 的 `.js` 清單、已更新的引用（`package.json`／`action.yml`／路徑）；依「參數來源優先序」新增的 `inputs` 清單與呼叫端傳入寫法（若有）。
+- **階段 C**：對齊後的 `runs`（`using`／`main`）、`outputs` 是否已去除 `value`、`inputs` 契約保留情形、橫幅輸出內容（名稱／用途／更新時間）與插入位置。
+- **階段 D**：相依判定（零相依／打包）、是否新增 `@vercel/ncc`、`runs.main` 最終指向（`src/index.js` 或 `dist/index.js`）、`dist/` 是否已 commit。
+- **階段 E**：doc-funcs 流程的處理結果（文件化的 function 與指令檔、重建的 README）。
+- 列出本次新增／變更的檔案與其相對路徑，並提醒使用者於提交前確認 `runs.main` 檔案存在、（打包時）`dist/` 已提交、目標 runner 支援指定的 node 版本。
+
+---
+
+## 呼叫方式
+
+格式：`[--action-dir <action 根目錄>] [--node-version <node runtime>] [--main <主程式檔>]` — 全部可省略（根目錄預設目前工作目錄；node 版本預設 `node24`；主程式自動判斷）。
+
+| 助理 | 呼叫 |
+| --- | --- |
+| Claude Code / Antigravity | `/jsc:code-action-node`，或 `/jsc:code-action-node --action-dir ~/work/my-action --node-version node24` |
+| Codex | `$code-action-node`，或 `$code-action-node --action-dir ~/work/my-action`，或用 `/skills` 選單 |
+| OpenCode | 描述需求（如「把這個 action 主程式改成 node、主程式相關 js 收進 src/，對齊 action.yml 為 node action、在主程式最前面輸出 action 名稱／用途／更新時間，有相依就用 ncc 打包成 dist 並 commit，最後跑 doc-funcs 補文件並重建 README」）自動觸發 |