refactor(code): 接上 shared 共用規範,去除重抄段落並補模型檢查串接

依 todo.md 執行的規範治理專案:action-composite/action-docker/action-node/
image/issues/nuget/review-resolve/sync/target 九個 skill 改為引用
shared 新增的共用 spec(conventional-commit、pull-request、git-push、
git-safety 分支選擇、issue-read、todo-list、ask-user、action-scaffold、
node-src-layout、skill-invocation),移除大量重抄內容(review-resolve/
target 光是 commit/PR/push 三塊就精簡約 175 行);target/issues 補上讀到
帶 model: frontmatter 清單檔時依 /jsc-shared:spec-model 做模型檢查的規則。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-11 06:04:18 +00:00
co-authored by Claude Sonnet 5
parent 9d8ac26a3b
commit 85a4128f5e
14 changed files with 215 additions and 671 deletions
+17 -35
View File
@@ -18,16 +18,11 @@ argument-hint: "[--action-dir <action 根目錄>] [--node-version <node runtime
---
## 共用規範(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`)、`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` 的標準流程。
先載入 `/jsc-shared:spec-preflight` 並依其流程處理;載入不到即代表 shared plugin 未安裝,
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`,不安裝則中斷本 skill。
本 skill 需要的規範:`spec-output`、`spec-execution`、`spec-git-safety`、`spec-action-scaffold`、`spec-ask-user`、`spec-node-src-layout`、`spec-action-params`、`spec-time-log`、`spec-doc-funcs-handoff`、`spec-skill-invocation`
本 skill 特有補充:
@@ -59,7 +54,7 @@ node action 相對 docker/composite 的**關鍵差異**(全程據此處理
## 參數來源優先序(開發中需要新參數時)
從零建立(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)。
從零建立(A1a)、主程式 Node 化(階段 B)、對齊 `action.yml`(階段 C)或打包(階段 D)的過程中,若需要新的參數值,依 `/jsc-shared:spec-action-params` 的優先序處理;node action 主程式讀值方式:優先取 `process.env.GITHUB_*`(Gitea 亦提供 `GITEA_*` 同義變數,建議讀 `GITHUB_*` 以相容兩邊),既有 `inputs` 以 `process.env.INPUT_<大寫名稱>`(或 `core.getInput`)取用。
---
@@ -77,17 +72,11 @@ node action 相對 docker/composite 的**關鍵差異**(全程據此處理
### A1. 決定 action 根目錄
- 帶 `--action-dir` → 採用(展開 `~`)。
- 省略 → 用目前工作目錄。
- 根目錄須存在 `action.yml` 或 `action.yaml`(action manifest)。**找不到** action manifest → **不臆測**、不逕自動工;以 `AskUserQuestion` 詢問使用者要「**從零建立**新的 Node action」還是「提供正確的 action 路徑」:選「從零建立」→ 進入 A1a;選「提供路徑」→ 依新路徑重跑 A1。
依 `/jsc-shared:spec-action-scaffold` 判斷 action 根目錄;**找不到** action manifest 時,依該 spec 詢問使用者「從零建立」或「提供正確的 action 路徑」,選「從零建立」→ 進入 A1a。
### A1a. 從零建立 Node action(問答式)
依序以問答收集需求,再產生 manifest 與主程式骨架:
1. **action 名稱**:用於 `action.yml` 的 `name`。
2. **輸入與輸出參數**:逐一收集 `inputs`(名稱、`description`、`required`、`default`)與 `outputs`(名稱、`description`;**不收集 `value`**);description 盡量繁體中文、無亂碼;沒有可留空。
3. **執行目標**:詢問此 action 要達成什麼,整理濃縮成一句話作為 `action.yml` 的 `description`(盡量繁體中文、無亂碼)。
依 `/jsc-shared:spec-action-scaffold` 的三題骨架問答收集需求(action 名稱/用途、輸入輸出、執行目標;第 2 題收集 `outputs` 時**不收集 `value`**)。
收集完成後,於 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 與處理相依)。
@@ -121,7 +110,7 @@ node action 相對 docker/composite 的**關鍵差異**(全程據此處理
### B1. 主程式 Node 化
- **已是 Node** → 確認入口檔,不改寫邏輯,直接進 B2。
- **非 Node(shell/python/其他)** → 這是**破壞性高風險決策**:先以 `AskUserQuestion` 向使用者確認是否改寫為 Node,選項至少含「改寫為 Node」「改用 action-docker(維持原語言容器化)」「其他」。經確認後才改寫:
- **非 Node(shell/python/其他)** → 這是**破壞性高風險決策**,依 `/jsc-shared:spec-ask-user` 以 `AskUserQuestion` 向使用者確認是否改寫為 Node,選項至少含「改寫為 Node」「改用 action-docker(維持原語言容器化)」「其他」。經確認後才改寫:
- 逐段把原主程式邏輯**保守翻譯**為 Node(建議 `src/index.js`);保留對外行為、輸入(環境變數/`INPUT_*`/args)與輸出(`$GITHUB_OUTPUT`/stdout/exit code/檔案副作用)契約。
- 外部指令呼叫以 `child_process`(`execFileSync`/`spawnSync`)對應;檔案操作以 `fs`;環境變數以 `process.env`。
- 任何無法可靠等價翻譯處,**不臆測**:以 `// 需人工確認:...` 標註並回報。
@@ -129,14 +118,7 @@ node action 相對 docker/composite 的**關鍵差異**(全程據此處理
### 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 相依,經同意後才加)。
依 `/jsc-shared:spec-node-src-layout` 把主程式入口及其依賴鏈的 `.js`/`.mjs`/`.cjs` 收進 `src/`,並同步更新所有引用。`package.json` 的 `scripts.build`(ncc 入口)與 `action.yml` 的 `runs.main` 先指向 `src/index.js`;若階段 D 判定需打包,再改指 `dist/index.js`。`@vercel/ncc` 屬階段 D 的 build 相依,經同意後才加,不在本階段新增。
---
@@ -162,7 +144,7 @@ runs:
node action 沒有 `entrypoint.sh`,橫幅改由**主程式 JS 最前面輸出**。在 `src/index.js`(或階段 B 決定的入口)最上方,於任何其他邏輯**之前**插入(或更新)橫幅輸出:
- **更新時間**依 `/jsc-shared:spec-time-log`(Asia/Taipei、固定 `yyyy/MM/dd HH:mm:ss`、寫成檔內固定字串)。本階段先寫入暫定時間戳,**階段 E 完成後會統一同步各處時間戳**(見階段 E)。
- **更新時間**依 `/jsc-shared:spec-time-log` 處理。本階段先寫入暫定時間戳,**階段 E 完成後會統一同步各處時間戳**(見階段 E)。
- 名稱/用途取自階段 A2 的 `action.yml`(缺漏時以「(未提供)」標示)。
- 若已存在本 skill 先前插入的橫幅(依可辨識註解標記),則**更新**其內容與時間戳,不重複插入。
@@ -223,7 +205,7 @@ node action 的 runner **不會自動 `npm install`**,因此相依必須隨 re
## 階段 E:完整執行 /jsc-doc:funcs 處理流程
標準化與打包完成後,以階段 A1 的 action 根目錄為目標,依 `/jsc-shared: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` 流程;本次新增/變更的 `src/` 內 Node 主程式、`action.yml`、`package.json` 都會被涵蓋,完成後依該 spec 統一同步主程式橫幅輸出、`action.yml` 開頭註解區塊與 README 的更新時間。
---
@@ -242,10 +224,10 @@ node action 的 runner **不會自動 `npm install`**,因此相依必須隨 re
## 呼叫方式
格式:`[--action-dir <action 根目錄>] [--node-version <node runtime>] [--main <主程式檔>]` — 全部可省略(根目錄預設目前工作目錄;node 版本預設 `node24`;主程式自動判斷)。
依 `/jsc-shared:spec-skill-invocation` 的呼叫方式;本 skill 為 `jsc-code:action-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 | `$action-node`,或 `$action-node --action-dir ~/work/my-action`,或用 `/skills` 選單 |
| OpenCode | 描述需求(如「把這個 action 主程式改成 node、主程式相關 js 收進 src/,對齊 action.yml 為 node action、在主程式最前面輸出 action 名稱/用途/更新時間,有相依就用 ncc 打包成 dist 並 commit,最後跑 funcs 補文件並重建 README」)自動觸發 |
範例:
- Claude Code / Antigravity:`/jsc-code:action-node --action-dir ~/work/my-action --node-version node24`
- Codex:`$action-node --action-dir ~/work/my-action`
- OpenCode:描述需求(如「把這個 action 主程式改成 node、主程式相關 js 收進 src/,對齊 action.yml 為 node action、在主程式最前面輸出 action 名稱/用途/更新時間,有相依就用 ncc 打包成 dist 並 commit,最後跑 funcs 補文件並重建 README」)自動觸發