工作流程步驟 API 參考

本參考說明內建(嵌入式)工作流程步驟與已安裝自訂步驟類型皆支援的 Python 合約。它們實作相同的 StepBase 方法,並使用相同的 StepContext、StepResult 與 StepStatus 類型。工作流程定義與引擎擁有的執行語意仍在工作流程 API 參考中。

交付路由

內建步驟隨 Specify CLI 出貨,不需要另外安裝 step.yml 套件。來源註冊是內部貢獻者的議題,不是步驟實作 API。

已安裝的自訂步驟使用相同的執行合約,另加開發步驟中記載的套件中繼資料、相符的類型身分與安裝需求。兩種交付途徑都不授權步驟變更引擎的登錄檔或檢查點狀態。

步驟 Python API

請從 specify_cli.workflows.base 匯入 StepBase、StepContext、StepResult 與 StepStatus。

API 合約
StepBase.type_key 符合 YAML type;已安裝的自訂步驟還必須符合其套件身分
validate(config) -> list[str] 驗證錯誤;空清單表示有效
execute(config, context) -> StepResult 無狀態、執行緒安全的執行
can_resume(state) -> bool 回傳 true 的基底方法;目前的引擎不會將它作為繼續執行的關卡來呼叫
StepContext 輸入、先前的結果、預設值、路徑、執行 ID、扇出項目與繼續執行上下文
StepResult.status pending、running、completed、failed、skipped 或 paused;預設為 completed
StepResult.output 輸出對應,預設為空
StepResult.next_steps 巢狀展開,預設為空
StepResult.error 失敗時的錯誤訊息,否則為 null

config 是步驟的 YAML 對應。基底的 validate() 會檢查 id;覆寫時應以 super().validate(config) 保留該檢查,再加入自己的錯誤。執行時不會自動呼叫驗證器,因此也請在 execute() 中防護無效的設定。

StepContext 欄位

欄位 類型 意義
inputs dict[str, Any] 已解析的工作流程輸入
steps dict[str, dict[str, Any]] 先前步驟的結果記錄,依撰寫的步驟 ID 鍵入;輸出位於每筆記錄的 output 之下
item Any 目前的扇出項目,否則為 None
inside_fan_out bool 執行是否位於扇出範本內
fan_in dict[str, Any] 彙總的扇入上下文
default_integration str \| None 工作流程整合預設值
default_model str \| None 工作流程模型預設值
default_options dict[str, Any] 工作流程派送預設值
project_root str \| None 專案目錄
run_id str \| None 目前的執行 ID
is_resume bool 此次執行是否為繼續執行的嘗試
workflow_dir str \| None 目前工作流程定義的來源目錄
default_reasoning_effort str \| None 工作流程 reasoning_effort 預設值,依撰寫原樣;可以是未求值的運算式
default_context_size str \| None 工作流程 context_size 預設值,依撰寫原樣;可以是未求值的運算式

對應預設為空字典,布林旗標預設為 false,選用的路徑/識別碼預設為 None。路徑是字串,不是 Path 物件。請使用 workflow_dir 存取相對於工作流程的資源,使用 project_root 進行專案本機操作;兩者不一定是同一個目錄。

請將輸入與先前的結果記錄視為上下文,而非改寫執行狀態的途徑。請透過 StepResult 回傳輸出。扇出項目有各自獨立的結果上下文;工作流程呼叫有自己的輸入與預設值。

結果與失敗

請使用 StepStatus 的值,而非任意的狀態字串。正常的成功步驟會回傳 COMPLETED;SKIPPED 記錄已跳過的步驟,PAUSED 請求暫停,FAILED 記錄錯誤。列舉中也有 PENDING 與 RUNNING,但回傳任一者並不會讓該次發生保持待處理或執行中:引擎會將它視為已完成。請回傳 PAUSED 以便日後繼續執行時停止,而非作為進度狀態。

請回傳可序列化的輸出值,因為引擎會持久化輸出,並將它們暴露給後續的 {{ steps.<id>.output.* }} 運算式。next_steps 是控制流程展開用的巢狀步驟定義對應清單,不是步驟執行個體的清單。

對於預期的失敗,請回傳 StepResult(status=StepStatus.FAILED, error=...),並將相關診斷放在 output 中。 這讓引擎可以套用 continue_on_error。未處理的例外無論該旗標為何都會停止執行; 請勿將無效的設定或失敗的操作變成成功的預設值。

from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus


class GreetingStep(StepBase):
    type_key = "greeting"

    def validate(self, config: dict) -> list[str]:
        errors = super().validate(config)
        if not isinstance(config.get("name"), str) or not config["name"].strip():
            errors.append("'name' must be a non-empty string.")
        return errors

    def execute(self, config: dict, context: StepContext) -> StepResult:
        errors = self.validate(config)
        if errors:
            return StepResult(
                status=StepStatus.FAILED,
                error="; ".join(errors),
            )
        return StepResult(output={"message": f"Hello, {config['name']}!"})

執行與繼續執行合約

步驟執行個體可能會被同時呼叫。請保持執行無狀態且執行緒安全:從 config 與 context 衍生每次執行的值,而非 self 上的可變屬性。

引擎擁有檢查點與生命週期轉換。已完成的發生會在繼續執行時重播,而不會再次呼叫其實作。選取的分支與巢狀展開維持固定;未完成的發生會依工作流程繼續執行規則繼續。請勿將 can_resume() 用作授權或安全檢查;它不是受強制執行的引擎關卡。

在完成檢查點之前執行的副作用,可能在中斷後重複。請讓外部操作具冪等性或可安全重試;執行並非恰好一次的保證。工作流程快照會凍結定義,而非步驟套件程式碼或外部資源。

已安裝類型探索

每個已安裝的步驟只記錄其來源的種類——catalog(可附型錄名稱)、local 或 url。本機路徑與來源 URL 永不持久化。請使用 specify workflow step list 與 specify workflow step info <id> 探索已安裝的類型與來源;請勿變更主機內部的 Python 登錄檔。

狀態與設定位置

元件 位置 格式 用途
自訂步驟 .specify/workflows/steps/{id}/ 套件 已安裝的步驟資訊清單與 Python
步驟登錄檔 .specify/workflows/steps/step-registry.json JSON 已安裝的步驟中繼資料
步驟型錄快取 .specify/workflows/steps/.cache/*.json JSON 快取的步驟型錄條目
專案步驟型錄 .specify/step-catalogs.yml YAML 專案層級的步驟來源
使用者步驟型錄 ~/.specify/step-catalogs.yml YAML 使用者層級的步驟來源

另請參閱