工作流程覆蓋層
工作流程覆疊讓專案可以在不編輯已安裝 workflow.yml 的情況下,擴充或覆寫已安裝的工作流程。這讓本地自訂在 specify bundle update 或 specify workflow add 升級時能安全保留。
當 specify workflow run <workflow-id> 載入工作流程時,引擎會將基礎工作流程與該工作流程 ID 的所有已啟用覆疊組合。結果會如同任何其他工作流程定義一樣進行驗證。
覆疊如何運作
覆疊是一個 YAML 檔案,宣告一組針對基礎工作流程步驟清單的編輯操作。覆疊使用數值小者勝出的優先順序:優先級數字較大的先套用,數字較小的最後套用。優先級相同的覆疊會依 ID 的字母順序套用,最後一個 ID 在衝突時勝出。
專案覆疊檔案位於:
| 位置 | 用途 |
|---|---|
.specify/workflows/overlays/<id>/*.yml |
專案本地自訂 |
覆疊檔案格式
建議的編輯格式使用操作名稱作為鍵,錨點步驟 ID 作為值:
id: "my-overlay"
extends: "speckit"
priority: 10
enabled: true
edits:
- insert_after: implement
step:
id: run-lint
type: shell
run: "ruff check src/"
- replace: review-spec
step:
id: review-spec
type: gate
message: "Review the generated spec (overlay override)."
options: [approve, reject]
on_reject: abort
也支援明確形式:
edits:
- operation: insert_after
anchor: implement
step:
id: run-lint
type: shell
run: "ruff check src/"
欄位
| 欄位 | 必填 | 說明 |
|---|---|---|
id |
是 | 此覆疊的識別碼。用於 specify workflow overlay * 命令。只能包含小寫字母、數字與連字號;不得包含點、底線、路徑分隔符號或 overlays。 |
extends |
是 | 此覆疊適用的工作流程 ID。使用與 id 相同的安全 ID 格式;overlays、runs 與 steps 為保留字。 |
priority |
否 | 整數;預設為 10。數值越小,優先級越高,衝突時勝出。缺失或無效的值會退回 10。 |
enabled |
否 | 布林值。預設為 true。已停用的覆疊會被忽略。 |
edits |
是 | 非空的編輯操作清單。 |
編輯操作
| 操作 | 需要 step |
效果 |
|---|---|---|
insert_after |
是 | 在錨點步驟之後立即插入 step。 |
insert_before |
是 | 在錨點步驟之前立即插入 step。 |
replace |
是 | 以 step 取代錨點步驟。 |
remove |
否 | 從清單中移除錨點步驟。 |
anchor 是基礎工作流程中某個步驟的 id。錨點會在 then、else、steps、cases.* 與 default 區塊內遞迴解析,因此巢狀的基礎步驟也可以作為目標。扇出範本(fan-out 步驟內的 step)不是有效的錨點。
步驟 ID 不得包含 ::該字元保留給引擎產生的巢狀 ID。
管理覆蓋層
使用覆疊 CLI 命令新增、列出、設定優先順序、啟用、停用與移除覆疊,或使用 specify workflow resolve <workflow-id> 檢查組合結果。
範例:實作後新增自動化 Lint
以內建的 speckit 工作流程為例,建立 project-overlay.yml:
id: "add-lint"
extends: "speckit"
priority: 10
edits:
- insert_after: implement
step:
id: run-lint
type: shell
run: "ruff check src/"
安裝它:
specify workflow overlay add project-overlay.yml --priority 10
執行工作流程:
specify workflow run speckit -i spec="Build a kanban board"
組合後的工作流程現在會執行完整的 SDD 循環,並在 implement 步驟後自動執行 ruff check src/。
範例:取代關卡
id: "skip-plan-review"
extends: "speckit"
priority: 5
edits:
- replace: review-plan
step:
id: review-plan
type: command
command: speckit.plan
input:
args: "{{ inputs.spec }}"
優先級數值越小,優先順序越高。此覆疊的 priority: 5 會在與優先級 10 的覆疊發生衝突時勝出。它會以另一個計畫命令取代 review-plan 關卡,因此既有的計畫命令仍會執行。
工作流程槽位(上游擴充點)
工作流程作者可以使用 type: slot 宣告具名、無操作的工作流程槽位:
- id: post-implement
type: slot
name: "Post-implementation checks"
步驟 id 是唯一的覆疊錨點;name 是必填、不可空白、
僅供人類閱讀的標籤。未填入的槽位會以 skipped 步驟完成,
並帶有 output: {slot: <name>},因此後續步驟可以正常繼續。
使用結構描述有效的覆疊 replace 編輯填入槽位,錨點是步驟
id,而非其 name:
id: fill-post-implement
extends: my-workflow
edits:
- replace: post-implement
step:
id: post-implement
type: shell
run: "echo Run project-specific checks"
當後續運算式或 fan-in.wait_for 參照槽位時,請重複使用槽位的 id。
取代內容還必須保留後續步驟取用的每個輸出鍵:
未填入的工作流程槽位只提供 steps.<id>.output.slot。槽位步驟
不支援在 fan-out.step 範本內使用,因為執行期倍增的
範本無法作為覆疊錨點。
與套件組及更新的互動
specify workflow add <local-directory> 會將完整的本地工作流程
套件安裝到 .specify/workflows/<id>/。封存檔安裝會保留相同的
套件內容。
當已安裝的工作流程被重新整理或重新安裝時,.specify/workflows/overlays/<id>/ 中的專案覆疊會被保留,因為它們位於已安裝工作流程目錄之外。
限制
- 覆疊只對步驟清單操作。它們無法變更工作流程中繼資料、輸入、輸出、
requires或工作流程層級預設值。若要變更步驟中的運算式,請取代該步驟。 - 扇出範本無法作為錨點。
- 若覆疊的目標步驟 ID 在基礎工作流程中不存在,解析工作流程時會引發驗證錯誤。
- 覆疊無法以其他覆疊新增的步驟為目標。
- 覆疊無法新增輸入,也無法變更基礎工作流程的輸入結構描述。