jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
44 lines
4.4 KiB
Markdown
44 lines
4.4 KiB
Markdown
---
|
||
name: spec-action-scaffold
|
||
description: JSC plugins 共用「action 從零建立骨架」：目錄裡沒有既有 action manifest（action.yml／action.yaml）時如何判斷 action 根目錄並觸發問答式從零建立，以及問答式從零建立時必須依序詢問使用者三個固定骨架問題（action 名稱／用途、輸入輸出、執行目標）；各 skill 可依自身 action 類型調整第 2、3 題的具體措辭，但三題的骨架與順序一致。當其他 skill 內文引用 spec-action-scaffold 或 /jsc-shared:spec-action-scaffold、或需要處理「目錄無 action manifest 時的從零建立問答」時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-action-scaffold — 共用 action 從零建立骨架
|
||
|
||
所有處理 Gitea／GitHub action 的 JSC skills（composite／docker／node 等 action 類型），在目錄裡**找不到既有 action manifest** 時，一律遵守以下規範判斷 action 根目錄，並以固定三題骨架問答式從零建立。
|
||
|
||
## 適用範圍
|
||
|
||
本規範適用於「目標本身就是 action manifest（`action.yml`／`action.yaml`）」的 skill（例如 `action-composite`／`action-docker`／`action-node`）。**不適用**於目標是既有 `Dockerfile` 而非 action manifest 的 skill（例如 `image`）——那類 skill 的職責是整理既有檔案，找不到目標檔案時應回報並詢問正確路徑或轉導到對應的 action 化 skill，**不可**套用本規範的問答式從零建立（不臆造 `Dockerfile`）。
|
||
|
||
## 判斷 action 根目錄
|
||
|
||
1. 帶 `--action-dir <action 根目錄>` → 採用（展開 `~`）。
|
||
2. 省略 → 用目前工作目錄。
|
||
3. 根目錄須存在 action manifest：帶 `--manifest` 則採用指定路徑；否則於根目錄找 `action.yml`，再退而 `action.yaml`。
|
||
4. **找不到** action manifest → **不臆測**、不逕自動工；以 `AskUserQuestion` 詢問使用者：
|
||
- 「從零建立」新的該類型 action → 進入「問答式從零建立」。
|
||
- 「提供正確的 action 路徑」→ 依新路徑重新判斷根目錄（回到第 1 步）。
|
||
|
||
## 問答式從零建立三題骨架
|
||
|
||
選擇「從零建立」後，依序以問答收集需求（順序固定、不可跳題或調換），再產生 manifest：
|
||
|
||
1. **action 名稱／用途**：action 的 `name`，以及此 action 要達成什麼（整理濃縮成一句話，作為 `action.yml` 的 `description`；盡量繁體中文、無亂碼）。
|
||
2. **輸入輸出**：`inputs`／`outputs` 長什麼樣——逐一收集名稱、`description`（盡量繁體中文、無亂碼）、`required`／`default`；沒有可留空。
|
||
3. **執行目標**：這個 action 實際要跑什麼指令或程式，據此決定 `runs` 的具體實作（composite 的 steps、docker 的主程式與 image、node 的主程式與打包方式等）。
|
||
|
||
收集完成後於 action 根目錄產生對應的 action manifest 與（若該 action 類型需要）主程式骨架；開發過程中若需要新的參數值，依 `/jsc-shared:spec-action-params` 的優先序處理，不得繞過本骨架直接詢問或編造。
|
||
|
||
## 各 skill 差異對照（骨架不變、措辭可調整）
|
||
|
||
三題的**骨架與順序一律一致**；下表列出目前三個 action 類型 skill 對第 2、3 題的具體措辭差異，僅供對照，新增其他 action 類型的 skill 時可依自身特性調整措辭，但不可更動骨架本身。
|
||
|
||
| 來源 skill | 第 1 題（固定：名稱／用途） | 第 2 題（輸入輸出，措辭可調） | 第 3 題（執行目標，措辭可調） |
|
||
| --- | --- | --- | --- |
|
||
| `action-composite` | action 名稱，用於 `action.yml` 的 `name` | 逐一收集 `inputs`／`outputs` 的名稱與 `description`、`required`／`default` | 詢問此 action 要達成什麼，濃縮成一句話作為 `description`；據此以 composite steps 實作 |
|
||
| `action-docker` | 同上 | 同上 | 同上；據此以 Node 主程式（`src/index.js`）實作，輸入以 `process.env.INPUT_<NAME>` 讀取 |
|
||
| `action-node` | 同上 | 逐一收集 `inputs`（名稱、`description`、`required`、`default`）與 `outputs`（名稱、`description`；**不收集 `value`**） | 同上；據此以 Node 主程式實作，預設走零相依路線 |
|
||
|
||
各 skill 完成問答並產生 manifest 與主程式骨架後，接續各自原本「已存在 manifest」時的後續流程（判斷／對齊 action 類型、注入橫幅或處理相依等），視同該 manifest 原本就存在，不再重複問答。
|