Files

T

JefferyandClaude Fable 5 0b464c5cdf feat(code-action-composite): 參數來源優先序簡化為 context→inputs、新增 A1a 問答式從零建立分支、補 INPUT_*／outputs 映射樣板、統一時間戳並移除 --yes

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-16 16:03:40 +08:00

18 KiB

Raw Blame History

name: code-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 補文件，或提到 code-action-composite 時觸發。不適用於：Docker 容器 action（用 code-action-docker）、或不需 action 化／文件化的一般 repo。 argument-hint: "[--action-dir <action 根目錄>] [--manifest <action.yml 路徑>]"

code-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. 串接 doc-funcs	對整個 action 專案完整執行 `/jsc:doc-funcs` 流程（function 文件、指令檔逐行註解、重建 README）

輸出規範（務必遵守）

語言：所有面向使用者的輸出（計畫、進度、總結、反問）一律使用繁體中文（台灣用語）；僅識別字、檔名、git 指令、API 路徑、YAML 鍵名、程式碼等技術標識保留原文，不可使用簡體字。
編碼無亂碼：凡輸出含繁體中文、全形標點、emoji，一律 UTF-8（不含 BOM），不得出現問號方框或錯碼。產生／覆寫的 action.yml／action.yaml、被引用腳本、README.md 同樣需 UTF-8（不含 BOM）。
自動執行原則：除非使用者明確要求先確認，或遇到不可忽略的必要決策，否則各階段只需輸出簡短計畫／進度後直接執行到完成。一定會中斷詢問的點：階段 B 主 action「非 composite 需對齊」時（破壞性，須先確認），以及階段 D 由 /jsc:doc-funcs 自身的「如何實作」詢問。
不破壞既有工作：改寫 action.yml／搬移或改寫被引用腳本前，若工作區有未提交變更，先提醒使用者建議先 commit／備份；絕不 reset --hard／checkout -f／clean，也不刪除使用者既有原始碼。移動檔案優先用 git mv 以保留歷史。
保留行為：對齊 composite 與注入橫幅 step 只「補強」既有流程，不得擅自改變既有 steps 的執行順序、輸入（inputs）／輸出（outputs）契約或副作用；任何無法可靠等價推論的改動一律不做，並以註解或回報標註「需人工確認」。新增 input 僅限依「參數來源優先序」經使用者同意後為之。
不擴及無關檔案：本 skill 只動 action 專案根目錄內的：action.yml／action.yaml、其 steps 直接引用的內嵌腳本（如 *.sh／*.ps1），以及階段 D 由 doc-funcs 流程處理的目標；排除 node_modules／.git／.docs／bin／obj／第三方依賴。

參數來源優先序（開發中需要新參數時）

從零建立（A1a）、對齊 composite（階段 B）、注入橫幅 step（階段 C）或補強被引用腳本的過程中，若需要新的參數值，依下列順序處理，前一項可取得就不往下：

${{ gitea.* }}／${{ github.* }} context：在 Gitea composite action 的 runs.steps 內可直接使用（Gitea 中 gitea 與 github context 互為別名）。常用如 github.repository、github.ref_name、github.server_url、github.token、github.event.*。為同時相容 GitHub Actions，composite action 內建議寫 github.*（Gitea 亦支援）；確定只跑 Gitea 的專案可用 gitea.*。run 腳本內可改讀同源的執行期環境變數（$GITHUB_REPOSITORY、$GITHUB_SERVER_URL、$GITHUB_REF_NAME 等）。
context 無法取得 → 詢問使用者新增 inputs：以 AskUserQuestion 詢問使用者是否新增對應 input（名稱／description／required／default），經同意後於 inputs 宣告並在 step 內以 ${{ inputs.<name> }} 取用；未經同意不得擅自更動 inputs／outputs 契約。

secrets／vars 一律視為不可用，不列入優先序：${{ secrets.* }}／${{ vars.* }} context 在 composite action 的 action.yml 內於 GitHub 為官方明文不可用（composite action 取不到 secrets／vars context，inputs 的 default 也不能引用）；Gitea act_runner 未嚴格檢查 context 可用性、行為無保證。為求兩邊相容，本 skill 一律視為不可用——參數值本質上屬 secrets／vars 者，直接依第 2 項宣告為 input，回報時附上呼叫端 workflow 的傳入寫法：

- uses: <owner>/<action>@<ref>
  with:
    token: ${{ secrets.MY_TOKEN }}     # secrets 由呼叫端 workflow 傳入
    registry: ${{ vars.MY_REGISTRY }}  # vars 亦同

參數

格式：[--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：

action 名稱：用於 action.yml 的 name。
輸入與輸出參數：逐一收集 inputs／outputs 的名稱與 description（description 盡量繁體中文、無亂碼）、required／default；沒有可留空。
執行目標：詢問此 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，不詢問；是否對齊／維持原樣／改用 code-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」「維持原樣只做文件化（略過對齊）」「改用 code-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 轉接）形如：

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 開頭補用途／更新時間註解區塊。

更新時間語意為「本檔最後由本 skill 產生／更新的時間」，使用台灣時區（Asia/Taipei）並固定為 yyyy/MM/dd HH:mm:ss（可用 TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S' 取得），寫成檔內固定字串（非執行期動態時間）。本階段先寫入暫定時間戳，階段 D 完成後會統一同步各處時間戳（見階段 D）。
名稱／用途取自階段 A2 的 action.yml（缺漏時以「（未提供）」標示）。
橫幅 step 須有可辨識的 name（如 顯示 action 資訊）與 shell: bash；其後緊接既有／對齊後的 steps，不更動既有 steps。
若已存在本 skill 先前插入的橫幅 step（依 name 辨識），則更新其內容與更新時間，不重複插入。

範例（既有 steps 接在橫幅 step 之後）：

name: <action name>
description: <action description>

runs:
  using: composite
  steps:
    # 啟動橫幅：輸出名稱／用途／更新時間（此 step 由 code-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 處理流程

標準化完成後，對整個 action 專案完整執行 /jsc:doc-funcs 流程，替程式碼與指令檔補文件並重建 README：

前置檢查：先確認 doc-funcs skill 可用（/jsc:doc-funcs）；不可用則回報並略過本階段，於總結標註「未文件化」。
以階段 A1 的 action 根目錄為目標，執行 doc-funcs skill 的完整流程（判斷語言 → 掃描 function 與指令檔 → 建立 .docs/ 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證）。
doc-funcs 會把 action.yml／action.yaml 視為 CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；steps 內引用的腳本（*.sh／*.ps1 等）逐行註解；專案內各 function 補文件註解。
doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，本 skill 不代為決定。
完成後依 doc-funcs 規範重建根目錄 README.md（含台灣時區更新時間、專案列表、功能列表、使用範例）。
統一時間戳：doc-funcs 全部完成後，以完成當下的 Asia/Taipei 時間（yyyy/MM/dd HH:mm:ss）回頭同步橫幅 step 內文、action.yml 開頭註解區塊與 README 的更新時間，確保各處時間戳一致。

銜接方式：在本 skill 環境中以 /jsc:doc-funcs（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用本 skill 的 action 根目錄為目標專案。

總結

各階段執行後輸出：

階段 A：action 根目錄、manifest 路徑、action 名稱／用途、runs.using、是否為 composite、既有 step 數量；若走 A1a 從零建立，列出問答收集結果（名稱／輸入輸出／目標）。
階段 B：是否對齊為 composite（及對齊摘要與「需人工確認」清單），或維持原樣的理由；依「參數來源優先序」新增的 inputs 清單與呼叫端傳入寫法（若有）。
階段 C：橫幅 step 的輸出內容（名稱／用途／更新時間）與插入位置，並確認既有 steps、inputs／outputs 未被破壞。
階段 D：doc-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	`$code-action-composite`，或 `$code-action-composite --action-dir ~/work/my-action`，或用 `/skills` 選單
OpenCode	描述需求（如「把這個 composite action 標準化，在 steps 最前面加一個會輸出 action 名稱／用途／更新時間的 step，最後跑 doc-funcs 補文件並重建 README」）自動觸發

18 KiB Raw Blame History Unescape Escape