# 用 AI 助手編排工作流程

Source: https://openflow.run/zh-tw/docs/guides/agent-authoring/
Language: zh-TW
Product version: 0.1.0-beta.77

透過 CLI 或 MCP 查詢、檢視和修改工作流程，與工作台使用同一個 Open Flow 服務。

將 AI 助手連線到你準備使用的 Open Flow 服務。工作台、CLI 和 MCP 操作的是該服務中的同一批工作流程；切換用戶端不會額外建立工作區或執行服務。

[快速開始](https://openflow.run/zh-tw/quickstart/)介紹了 AI 助手的環境設定。以下命令使用 `oo flow` 命令組。MCP 提供對應的 `flow_read`、`flow_schema`、`flow_edit`、`flow_check` 和執行工具。

## 修改前先查詢

```bash
oo flow schema code --json
oo flow read FLOW_ID --json
```

修改節點前，先讀取相關節點的詳情，以及完整的程式碼或提示詞。節點結構說明會列出支援的設定、輸入來源、預設值和示例。應用操作和觸發器的識別碼應從部署端的目錄查詢，不能自行猜測。

## 基於目前修訂版本送出修改

修改請求包含讀取時的 `baseRevision`、固定的 `requestId`，以及按順序執行的操作。下面的示例新增一個開始節點、一個程式碼節點、一條執行連線和一個數據綁定：

```json
{
  "baseRevision": "OBSERVED_REVISION",
  "requestId": "UNIQUE_REQUEST_ID",
  "edits": [
    {
      "op": "node.add", "as": "start", "type": "start", "name": "Start",
      "config": { "inputDefs": { "name": { "schema": { "type": "string" }, "nullable": false } } }
    },
    {
      "op": "node.add", "as": "greet", "type": "code", "name": "Compose greeting",
      "code": "export default ({name}) => ({message: `Hello, ${name}!`});",
      "config": { "outputs": { "message": { "schema": { "type": "string" }, "nullable": false } } },
      "inputs": { "name": { "kind": "output", "node": "$start", "port": "name" } }
    },
    { "op": "edge.connect", "source": "$start", "target": "$greet" }
  ]
}
```

```bash
oo flow edit FLOW_ID --file edits.json --json
oo flow check FLOW_ID --json
```

`as` 宣告別名時不帶 `$`；同批後續操作用 `$alias` 引用它。後續請求則使用服務回傳的節點引用。同一批修改要麼全部送出，要麼全部不送出，但儲存下來的草稿仍可能存在驗證問題。

## 保留無關設定

更新會遞迴合併物件，包括 schema。陣列會整體替換。未提供的欄位保持原值，傳入空物件也不會清空原有設定。

```json
{
  "op": "node.update",
  "node": "NODE_REFERENCE",
  "clear": [["retry"]]
}
```

顯式 `clear`、JSON `null`、未設定輸入和繼承預設值，含義各不相同。修改前先讀取現有值，並按目前節點結構說明選擇支援的輸入來源。

## 處理衝突和回應不確定的情況

如果送出後未能確認結果，使用相同的請求識別碼重試完全相同的請求。確認原修改是否成功之前，不要換一個新的請求識別碼。遇到修訂版本衝突，需要重新讀取草稿，再決定如何合併修改，不能直接覆蓋其他人的編輯。

驗證不會執行工作流程，也不能證明外部帳號已準備就緒。發布前，測試相應入口並檢查執行紀錄。詳見[測試與發布](https://openflow.run/zh-tw/docs/guides/test-and-publish/index.md)。

## 資料來源

*   [docs/authoring/node-authoring.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/authoring/node-authoring.md)
*   [docs/control/contracts/control-api.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/control/contracts/control-api.md#node-authoring)
*   [docs/distribution/command.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/distribution/command.md)