# 用 AI 助手编排工作流

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

通过 CLI 或 MCP 查询、查看和修改工作流，与工作台使用同一个 Open Flow 服务。

将 AI 助手连接到你准备使用的 Open Flow 服务。工作台、CLI 和 MCP 操作的是该服务中的同一批工作流；切换客户端不会额外创建工作区或执行服务。

[快速开始](https://openflow.run/zh-cn/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-cn/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)