riceprompt-engine：把 agent 工作流寫成一份 YAML
YAML-native agent workflow execution engine, written in Rust
秒懂
- 它是什麼？
- 這是一個 Rust 寫的 YAML 原生 agent 工作流執行引擎，節點涵蓋 LLM 呼叫、Rhai 腳本、資料連接器與 MCP 工具。核心判斷是：宣告式流程圖換來可檢視與可續跑，代價是 0.1.x 階段 YAML 規格仍會變動。
- 適合誰用？
- 如果你要的是可版本控管、可 diff、能整份 YAML 交給下游工具重繪拓撲的 agent 流程，而且能接受 0.1.x 期間規格會動，這個引擎值得進評估清單；若你的流程需要大量動態分支或即時人工介入，宣告式圖會綁手綁腳。決定採用前先確認三件事：讀 docs/FLOW_SPEC.md 對照你要用的節點是否都已定義、在 Cargo.toml 固定 riceprompt-engine 的完整版本號、以及實測 checkpoint 還原後哪些節點會重跑。
- 可以商用嗎？
- 可以。Apache-2.0 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 141 天前。
- 用什麼語言寫的？
- 主要是 Rust（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它把工作流從程式碼搬進一份可 diff 的檔案
多數 agent 框架把流程寫成程式碼：函式呼叫函式，狀態存在變數裡。這種做法除錯方便，但流程本身很難被非工程角色檢視，也很難整份交給另一個工具渲染。riceprompt-engine 走另一條路，README 開頭寫得很直接：你把 agent 工作流描述成一份 YAML，裡面有 nodes、edges、prompts、data sources、MCP tools，引擎負責解析、解析相依關係、然後執行這張圖。
目標讀者是已經在用 Rust 寫服務、想把 agent 流程從應用程式碼裡抽出來的人。抽出來之後那張圖可以被版本控管、可以在 PR 裡被 review、可以被 IDE 讀取。README 也點名 RicePrompt 這個視覺化 IDE 就是建立在這個引擎之上，同一份 YAML 既能在圖形編輯器裡設計，也能被引擎直接吃下去。
這裡有個容易誤解的地方：YAML 只是外層描述,執行仍然是 Rust 的非同步程式。engine.run_yaml 是非同步函式，回傳 ExecutionResult。所以它不是設定檔驅動的 shell 腳本，而是一個嵌入進你服務的函式庫。
節點、邊、模板：圖是怎麼被執行的
從 README 的範例可以讀出執行模型的骨架。一份流程宣告 version、name、providers、nodes、edges、templates。節點有 id 與 type，type 決定行為。範例用到三種：start 是入口，generate 呼叫 LLM，response 定義輸出。
generate 節點的 config 裡指定 provider、model、template 與 variables。variables 的值寫成 "start.name" 這種路徑字串，意思是從上游節點的輸出取值。edges 用 from 與 to 描述方向，範例是 start 到 greet、greet 到 response 兩條線。templates 區塊則把 prompt 文字獨立出來，用 {{name}} 這種佔位符代入。
README 列出的節點型別遠多於範例：transform 用 Rhai 腳本做資料轉換，iterator 對資料迭代，supervisor 負責多 agent 路由，subgraph 做子圖，data_connector 接資料源，skill_set 是所謂漸進式揭露的知識包，mcp 與 mcp_tools 走 Model Context Protocol。這份清單的意義是：引擎把常見的 agent 編排動作都收斂成節點型別，而不是留給你用任意程式碼填。
還有一層是 harness。README 描述它是工作流層級的指令，形式類似 CLAUDE.md，會被注入到每一個 generate 節點，並支援持久記憶。這個設計等於在圖之外再放一層全域提示，讓每個 LLM 呼叫都帶著相同的背景約束。
跑起來需要的最小步驟
依賴宣告在 Cargo.toml：riceprompt-engine = "0.1"。README 的狀態說明建議，如果需要穩定就固定完整版本號，因為 0.1.x 期間 API 可能在次版本之間變動。
啟動程式碼是建立 Engine 後呼叫 run_yaml。Engine::builder().build() 產生引擎實例，run_yaml 接受兩個參數：YAML 字串與一份 serde_json 的初始輸入。範例傳入 json!({ "name": "Ada" })，回傳的 result 用 serde_json::to_string_pretty 印出。整段包在 #[tokio::main] 裡，說明執行期是 Tokio。
憑證從環境變數來。範例的 providers 區塊寫 api_key: "${OPENAI_API_KEY}"，用 ${} 語法參照環境變數，而不是把金鑰寫進 YAML。這一點在把流程檔提交進版控時很關鍵。
README 說 examples/ 目錄下還有更多可執行範例，但沒有列出清單。權威規格在 docs/FLOW_SPEC.md，README 明講它是 YAML 工作流規格的正本，涵蓋節點型別、欄位、供應商、資料源、harness、skills 與 MCP。貢獻指南也要求：任何動到 YAML 表面的改動，必須在同一個 PR 更新這份規格。對採用者來說，這份檔案比 README 更值得先讀。
供應商抽象與資料連接器的實際範圍
多供應商支援列得很長：OpenAI、Anthropic、Gemini、DeepSeek、Qwen、Zhipu、Moonshot、MiniMax、xAI、Huoshan，以及任何 OpenAI 相容端點。最後那一項實務上最重要，因為它意味著只要對方提供 OpenAI 相容介面，就不需要等官方新增適配。
串流、tool calling、結構化輸出被列為跨供應商的第一級能力。這裡該保持懷疑：不同供應商對結構化輸出的支援程度本來就不一致，README 沒有說明當某個供應商不支援某項能力時引擎如何降級或報錯。這是需要自己驗證的地方，不是文件能回答的。
內建資料連接器包含 PostgreSQL、MySQL、MongoDB、Redis、Qdrant、S3 相容物件儲存與 REST API。把向量資料庫 Qdrant 和關聯式資料庫放在同一層，表示 data_connector 節點是統一的取數入口，而不是每種資料源各自一套 API。
另一個設計是 ExecutionResult 可以帶上來源 YAML。README 的說法是 downstream tooling 能從單一檔案同時渲染拓撲與每個節點的結果。對寫除錯工具或前端的人來說，這比事後拼湊日誌省事。
checkpoint 與 0.1.x：兩個必須先接受的約束
README 把 checkpoint / resume 列為功能，說可以暫停並恢復長時間執行的工作流。但沒有說明檢查點的粒度、存在哪裡、恢復時哪些節點會重跑。對有副作用的節點，例如寫入資料庫或呼叫外部 API 的 data_connector，重跑語意是採用前必須自己測出來的，不能靠推測。
第二個約束是版本狀態。專案自述為 0.1.x，並明說在規格穩定之前 API 可能在次版本之間變動。這不是客套話：YAML 是這個專案對外的合約，規格一動，你手上的流程檔就可能需要跟著改。貢獻指南要求改動 YAML 表面時同步更新 FLOW_SPEC.md，正好說明這個表面被視為核心介面。
什麼情況下這不是對的工具？如果你的流程需要大量執行期才決定的動態分支、需要人在迴圈中即時介入、或流程本身短到不值得抽成圖，那麼宣告式 YAML 只會增加一層間接。把邏輯寫在 Rust 裡會更直接。
還有一個現實問題：README 提到使用者導向的 skill guide 會另外發布，也就是說目前唯一的權威文件是規格檔本身。遇到規格沒寫清楚的行為，你只能讀原始碼或發 issue。
跟 LangGraph 這類程式碼優先框架的差別
LangGraph 是這個位置上最常見的對照。它同樣用圖來表達 agent 流程，但圖是用 Python 程式碼建構的：你實例化 StateGraph、加節點、加邊、定義狀態 schema，條件邊就是回傳字串的函式。流程的真相在程式碼裡，型別檢查與 IDE 補全跟著 Python 走。
riceprompt-engine 把同一件事搬到 YAML。差別不只是檔案格式。在 LangGraph 裡，分支邏輯是任意 Python 函式，想寫多複雜都行；在這裡，分支要靠節點型別與邊的組合表達，能做的事被規格框住。反過來說，YAML 流程可以被不寫程式的人讀懂、被視覺化工具直接渲染，也能整份塞進 ExecutionResult 交給下游。
選擇的關鍵在於你的流程會不會頻繁超出框架預設的節點語意。會，就用程式碼優先的框架；不會，宣告式帶來的可檢視性就是淨收益。
另外要注意生態綁定：這個引擎是 RicePrompt 這個視覺化 IDE 的底層。README 沒有說明引擎是否能脫離 RicePrompt 獨立使用，從程式碼範例看是可以的，Engine::builder().build() 不需要任何 IDE 相關設定。
授權、升級與長期維護成本
授權是雙軌：Apache License 2.0 或 MIT，由使用者擇一。README 引用的是 Apache-2.0 的貢獻條款，說明除非明確聲明，否則提交的貢獻會自動以同樣的雙授權方式提供。對商業採用者來說，這兩個授權都屬於寬鬆型，主要義務是保留著作權與授權聲明。這不是法律意見，實際條款仍應以 LICENSE-APACHE 與 LICENSE-MIT 檔案為準。
升級成本主要來自 YAML 表面。既然 0.1.x 期間 API 可能在次版本之間變動，而且規格檔被當作權威合約，那麼每次升級就應該先 diff docs/FLOW_SPEC.md，再看引擎程式碼變了什麼。這個順序比反過來有效，因為破壞性變動通常先反映在規格上。
貢獻流程本身也透露維護風格：提交前要跑 cargo fmt 與 cargo clippy --all-targets，新增節點型別或供應商行為要加測試。這代表專案對程式碼品質有基本要求，但也意味著如果你要自己加一個節點型別，得連測試與規格文件一起改。
最後一個不確定項：README 沒有提供版本發布節奏或支援政策，也沒有列出最近的版本紀錄。對需要長期維護的服務來說，這代表你得自己盯上游變動，而不是等官方公告。
編輯結論
如果你要的是可版本控管、可 diff、能整份 YAML 交給下游工具重繪拓撲的 agent 流程，而且能接受 0.1.x 期間規格會動，這個引擎值得進評估清單；若你的流程需要大量動態分支或即時人工介入，宣告式圖會綁手綁腳。決定採用前先確認三件事：讀 docs/FLOW_SPEC.md 對照你要用的節點是否都已定義、在 Cargo.toml 固定 riceprompt-engine 的完整版本號、以及實測 checkpoint 還原後哪些節點會重跑。
社群筆記