206 lines
15 KiB
Markdown
206 lines
15 KiB
Markdown
---
|
||
name: action-composite
|
||
description: 將 Gitea／GitHub「composite action」專案標準化（目錄沒有 action manifest 時可問答式從零建立）並串接文件化流程：(1) 確認 action 為 composite（`runs.using: composite`），非 composite 則保守確認後對齊；(2) 在 `runs.steps` 最前面注入啟動橫幅 step，輸出 action 名稱／用途／更新時間（Asia/Taipei `yyyy/MM/dd HH:mm:ss`），並於 `action.yml` 開頭補用途／更新時間註解區塊；(3) 開發中需要新參數時優先取用 `${{ gitea.* }}`／`${{ github.* }}` context，無法取得才詢問使用者是否新增 `inputs`（`secrets`／`vars` context 在 composite action 內一律視為不可用，需要時宣告為 `inputs` 由呼叫端 workflow 傳入）；(4) 最後完整執行 `/jsc-doc:funcs` 處理流程（function 文件、指令檔逐行註解、重建 README）。當使用者說整理 composite action、從零建立／產生一個 composite action、把 action 標準化為 composite、讓 composite action 啟動時印名稱／用途／更新時間、處理 composite action 參數來源、對 composite action 補文件，或提到 action-composite 時觸發。不適用於：Docker 容器 action（用 action-docker）、或不需 action 化／文件化的一般 repo。
|
||
argument-hint: "[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>]"
|
||
---
|
||
|
||
# action-composite — composite action 標準化＋文件化
|
||
|
||
四階段 skill：先做**前置設定與偵測**（找出 action 專案、讀取名稱／用途、判斷是否為 composite），再**確認／對齊為 composite action**，接著在 `runs.steps` 最前面**注入會輸出 action 名稱／用途／更新時間的啟動橫幅 step**，最後**完整執行 `/jsc-doc:funcs` 處理流程**替整個專案補文件並重建 README。各階段開發中需要新參數時，一律套用下方「**參數來源優先序**」規則。目錄沒有 action manifest 時，先走 A1a 問答式「**從零建立**」分支產生 composite `action.yml`，再進入後續階段。
|
||
|
||
| 階段 | 動作 |
|
||
| --- | --- |
|
||
| A. 前置設定與偵測 | 決定 action 根目錄 → 讀 `action.yml`／`action.yaml` 的 `name`／`description`／`runs` → 判斷是否為 composite（無 manifest 可走 A1a 從零建立） |
|
||
| B. 對齊為 composite | 已是 composite 則保留既有 `steps`；非 composite 則**保守確認後對齊**（高風險，先確認），整理被引用的腳本路徑 |
|
||
| C. 注入啟動橫幅 step | 在 `runs.steps` 最前面插入一個 shell step，輸出 action **名稱／用途／更新時間**；並於 `action.yml` 開頭補用途／更新時間註解區塊 |
|
||
| D. 串接 funcs | 對整個 action 專案完整執行 `/jsc-doc:funcs` 流程（function 文件、指令檔逐行註解、重建 README） |
|
||
|
||
---
|
||
|
||
## 共用規範（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 參數來源優先序（context → 經同意新增 `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 主 action「非 composite 需對齊」時（破壞性，須先確認），以及階段 D 由 `/jsc-doc:funcs` 自身的「如何實作」詢問。
|
||
- **保留行為**：對齊 composite 與注入橫幅 step 只「補強」既有流程，不得擅自改變既有 `steps` 的執行順序、輸入（`inputs`）／輸出（`outputs`）契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 `input` 僅限依 `/jsc-shared:spec-action-params` 經使用者同意後為之。
|
||
- **本 skill 只動**：action 專案根目錄內的 `action.yml`／`action.yaml`、其 `steps` 直接引用的內嵌腳本（如 `*.sh`／`*.ps1`），以及階段 D 由 funcs 流程處理的目標。
|
||
|
||
---
|
||
|
||
## 參數來源優先序（開發中需要新參數時）
|
||
|
||
從零建立（A1a）、對齊 composite（階段 B）、注入橫幅 step（階段 C）或補強被引用腳本的過程中，若需要新的參數值，一律依 `/jsc-shared:spec-action-params` 的優先序處理：composite 的 `runs.steps` 內優先取 `${{ gitea.* }}`／`${{ github.* }}` context（建議寫 `github.*` 以相容兩邊；`run` 腳本內可改讀 `$GITHUB_*` 環境變數），取不到才以 `AskUserQuestion` 經使用者同意新增 `inputs`；`secrets`／`vars` 一律視為不可用，需要時宣告為 `input` 由呼叫端 workflow 傳入（範例見該 spec）。
|
||
|
||
---
|
||
|
||
## 參數
|
||
|
||
格式：`[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>]`
|
||
|
||
- `--action-dir <action 根目錄>`：action 專案根目錄。**省略時預設目前工作目錄**（須含 `action.yml`／`action.yaml`，否則依 A1 詢問）。
|
||
- `--manifest <action.yml 路徑>`：指定 action manifest 檔（相對 action 根目錄）。省略時依 A1 自動尋找 `action.yml`／`action.yaml`。
|
||
|
||
---
|
||
|
||
## 階段 A：前置設定與偵測
|
||
|
||
### A1. 決定 action 根目錄與 manifest
|
||
|
||
- 帶 `--action-dir` → 採用（展開 `~`）；省略 → 用目前工作目錄。
|
||
- manifest：帶 `--manifest` → 採用；否則於根目錄找 `action.yml`，再退而 `action.yaml`。
|
||
- **找不到** action manifest → **不臆測**、不逕自動工；以 `AskUserQuestion` 詢問使用者要「**從零建立**新的 composite action」還是「提供正確的 action 路徑」：選「從零建立」→ 進入 A1a；選「提供路徑」→ 依新路徑重跑 A1。
|
||
|
||
### A1a. 從零建立 composite action（問答式）
|
||
|
||
依序以問答收集需求，再產生 manifest：
|
||
|
||
1. **action 名稱**：用於 `action.yml` 的 `name`。
|
||
2. **輸入與輸出參數**：逐一收集 `inputs`／`outputs` 的名稱與 `description`（description 盡量繁體中文、無亂碼）、`required`／`default`；沒有可留空。
|
||
3. **執行目標**：詢問此 action 要達成什麼，整理濃縮成一句話作為 `action.yml` 的 `description`（盡量繁體中文、無亂碼）。
|
||
|
||
收集完成後，於 action 根目錄產生 `action.yml`（`runs.using: composite`，含收集到的 `name`／`description`／`inputs`／`outputs`），並依執行目標以 composite steps 實作（開發中需要新參數時套用「參數來源優先序」）；完成後接續 A2 往後流程（A3 必為 composite，階段 B 走「已是 composite」分支）。
|
||
|
||
### A2. 讀取 action 名稱與用途
|
||
|
||
從 action manifest 讀取：
|
||
|
||
- `name`：action 名稱（供啟動橫幅與 README 使用）。
|
||
- `description`：action 用途。
|
||
- `runs`：目前的執行設定（`using`、`steps`、`main`、`image`、`entrypoint` 等）。
|
||
- `inputs`／`outputs`：對外契約（後續不得破壞）。
|
||
|
||
若 `name`／`description` 缺漏，回報缺漏並**詢問一次**；使用者跳過或無法提供時，於後續輸出以「（未提供）」標示續行，**不編造**。
|
||
|
||
### A3. 判斷是否為 composite
|
||
|
||
依 `runs.using` 判定：
|
||
|
||
- `composite` → 即為目標型態，記下既有 `runs.steps`，直接進入階段 B 的「已是 composite」分支。
|
||
- `node*`（JS action）／`docker`（Docker 容器 action）／其他 → 視為**非 composite**。
|
||
|
||
輸出偵測結果（action 名稱、用途、`runs.using`、是否為 composite、既有 step 數量），再進入階段 B。
|
||
|
||
> 若偵測為 **Docker 容器 action**，此處**僅輸出偵測結果**並提醒可改用 `/jsc-code:action-docker`，**不詢問**；是否對齊／維持原樣／改用 action-docker 的決策，統一由階段 B2 的一次 `AskUserQuestion` 收斂。
|
||
|
||
---
|
||
|
||
## 階段 B：確認／對齊為 composite action
|
||
|
||
### B1. 已是 composite
|
||
|
||
- 確認 `runs.using: composite` 與既有 `runs.steps`，**不更動既有 steps 的順序與邏輯**，直接進入階段 C。
|
||
- 順手檢查 step 的必要欄位：`run` step 缺 `shell` 屬**原檔錯誤**（GitHub／Gitea 都會拒跑），**允許補上 `shell: bash`** 並在回報中列出；其他疑慮（如 `uses` step 的引用是否存在）以回報標註、不擅改。
|
||
|
||
### B2. 非 composite（需對齊）
|
||
|
||
這是**破壞性高風險決策**：先以 `AskUserQuestion` 向使用者確認，選項至少含「對齊為 composite」「維持原樣只做文件化（略過對齊）」「改用 action-docker」「其他」。經確認「對齊為 composite」後才改寫：
|
||
|
||
- 將 `runs` 保守對齊為 composite，把原執行入口轉為 composite step：
|
||
- 原 JS action（`runs.using: node*`，`runs.main: <x>.js`）→ 轉為一個 `run` step，於 step 內以 `node <x>.js` 執行（`shell: bash`）。composite step **不會自動注入 `INPUT_*` 環境變數、也不會自動轉接 outputs**，必須手動補齊兩段映射（見下方範例）：
|
||
- **inputs 映射**：step 加 `env:`，逐一宣告 `INPUT_<大寫名稱>: ${{ inputs.<name> }}`——主程式的 `getInput()`／`process.env.INPUT_*` 才拿得到值。
|
||
- **outputs 轉接**：step 設 `id`，action 層 `outputs` 逐一宣告 `value: ${{ steps.<id>.outputs.<name> }}`（主程式寫入 `$GITHUB_OUTPUT` 的值由此轉出）。
|
||
- **硬條件**：無法完成上述兩項映射（inputs／outputs 無法逐一對應）時**不對齊**，以 `# 需人工確認` 標註並回報。
|
||
- 原 Docker action（`runs.using: docker`）→ Docker 行為通常無法可靠等價地塞進 composite；**不臆測改寫**，以回報＋`# 需人工確認` 標註，並建議改用 `/jsc-code:action-docker`。
|
||
- 任何無法可靠等價對齊處，**不臆測**：以 `# 需人工確認：...` 標註並回報，保留原檔行為。
|
||
- 對齊過程需要新的參數值（如 token、repo 資訊、外部設定）時，依「參數來源優先序」處理，不逕自新增 `inputs`。
|
||
|
||
對齊後（含 inputs 映射與 outputs 轉接）形如：
|
||
|
||
```yaml
|
||
inputs:
|
||
foo:
|
||
description: <沿用原 input 宣告>
|
||
outputs:
|
||
bar:
|
||
description: <沿用原 output 宣告>
|
||
value: ${{ steps.main.outputs.bar }} # outputs 轉接：由 step outputs 轉出
|
||
|
||
runs:
|
||
using: composite
|
||
steps:
|
||
# （階段 C 會在此處最前面插入啟動橫幅 step）
|
||
- name: <原執行入口轉成的 step>
|
||
id: main
|
||
shell: bash
|
||
env:
|
||
INPUT_FOO: ${{ inputs.foo }} # inputs 映射：composite 不會自動注入 INPUT_*
|
||
run: node ./index.js
|
||
```
|
||
|
||
---
|
||
|
||
## 階段 C：注入啟動橫幅 step（輸出名稱／用途／更新時間）
|
||
|
||
在 `runs.steps` **最前面**插入（或更新）一個輸出橫幅的 step，讓 composite action 一啟動就**輸出 action 名稱、用途、更新時間**；並於 `action.yml` 開頭補用途／更新時間註解區塊。
|
||
|
||
- **更新時間**依 `/jsc-shared:spec-time-log`（Asia/Taipei、固定 `yyyy/MM/dd HH:mm:ss`、寫成檔內固定字串）。本階段先寫入暫定時間戳，**階段 D 完成後會統一同步各處時間戳**（見階段 D）。
|
||
- 名稱／用途取自階段 A2 的 `action.yml`（缺漏時以「（未提供）」標示）。
|
||
- 橫幅 step 須有可辨識的 `name`（如 `顯示 action 資訊`）與 `shell: bash`；其後緊接既有／對齊後的 steps，**不更動既有 steps**。
|
||
- 若已存在本 skill 先前插入的橫幅 step（依 `name` 辨識），則**更新**其內容與更新時間，不重複插入。
|
||
|
||
範例（既有 steps 接在橫幅 step 之後）：
|
||
|
||
```yaml
|
||
name: <action name>
|
||
description: <action description>
|
||
|
||
runs:
|
||
using: composite
|
||
steps:
|
||
# 啟動橫幅：輸出名稱／用途／更新時間（此 step 由 action-composite 產生）
|
||
- name: 顯示 action 資訊
|
||
shell: bash
|
||
run: |
|
||
echo "================================================"
|
||
echo "Action : <action name>"
|
||
echo "用途 : <action description>"
|
||
echo "更新時間: 2026/06/30 18:30:05"
|
||
echo "================================================"
|
||
# === 以下為既有／對齊後的 steps（保持原順序與邏輯）===
|
||
- name: <既有 step>
|
||
shell: bash
|
||
run: node ./index.js
|
||
```
|
||
|
||
- `action.yml` 開頭的「用途／更新時間」註解區塊與每行註解，最終會在階段 D 由 `/jsc-doc:funcs` 的指令檔流程統一補齊／覆寫為標準格式（用途與更新日期同一註解區塊、逐行註解）；本階段先確保**執行期橫幅輸出**正確即可。
|
||
- 自我檢查：插入橫幅 step 後 YAML 仍可解析（縮排、`steps` 為 list、每個 `run` step 都有 `shell`），且 `inputs`／`outputs` 未被更動。
|
||
|
||
---
|
||
|
||
## 階段 D：完整執行 /jsc-doc:funcs 處理流程
|
||
|
||
標準化完成後，以階段 A1 的 action 根目錄為目標，依 `/jsc-shared:spec-doc-funcs-handoff` 對**整個 action 專案**完整執行 `/jsc-doc:funcs` 流程（前置可用性檢查、完整流程、由使用者裁示實作方式、重建 README）。完成後依該 spec **統一時間戳**：回頭同步橫幅 step 內文、`action.yml` 開頭註解區塊與 README 的更新時間，確保各處一致。
|
||
|
||
---
|
||
|
||
## 總結
|
||
|
||
各階段執行後輸出：
|
||
|
||
- **階段 A**：action 根目錄、manifest 路徑、action 名稱／用途、`runs.using`、是否為 composite、既有 step 數量；若走 A1a 從零建立，列出問答收集結果（名稱／輸入輸出／目標）。
|
||
- **階段 B**：是否對齊為 composite（及對齊摘要與「需人工確認」清單），或維持原樣的理由；依「參數來源優先序」新增的 `inputs` 清單與呼叫端傳入寫法（若有）。
|
||
- **階段 C**：橫幅 step 的輸出內容（名稱／用途／更新時間）與插入位置，並確認既有 steps、`inputs`／`outputs` 未被破壞。
|
||
- **階段 D**：funcs 流程的處理結果（文件化的 function 與指令檔、重建的 README）。
|
||
- 列出本次新增／變更的檔案與其相對路徑，並提醒使用者於提交前確認 `action.yml` 可正常解析、composite action 能正確啟動並輸出橫幅。
|
||
|
||
---
|
||
|
||
## 呼叫方式
|
||
|
||
格式：`[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>]` — 全部可省略（根目錄預設目前工作目錄；manifest 自動尋找）。
|
||
|
||
| 助理 | 呼叫 |
|
||
| --- | --- |
|
||
| Claude Code / Antigravity | `/jsc-code:action-composite`，或 `/jsc-code:action-composite --action-dir ~/work/my-action` |
|
||
| Codex | `$action-composite`，或 `$action-composite --action-dir ~/work/my-action`，或用 `/skills` 選單 |
|
||
| OpenCode | 描述需求（如「把這個 composite action 標準化，在 steps 最前面加一個會輸出 action 名稱／用途／更新時間的 step，最後跑 funcs 補文件並重建 README」）自動觸發 |
|