Workflow v1 数据格式与节点说明

本项目的自动化工作流使用 workflow/v1。该格式把工作流看成一个有向图：节点负责执行动作或产出数据，连线负责控制执行顺序或传递数据。

顶层结构

{
  "schema_version": "workflow/v1",
  "workflow_key": "notepad-demo",
  "name": "打开记事本并输入文本",
  "description": "示例",
  "variables": {
    "target_text": {
      "type": "string",
      "default": "hello",
      "description": "要输入的文本"
    }
  },
  "settings": {
    "max_steps": 100,
    "default_timeout_ms": 30000,
    "on_unhandled_error": "pause_for_user"
  },
  "nodes": [],
  "edges": []
}

字段说明：

workflow_key：可选的稳定调用 key，只能使用字母、数字、下划线和连字符；适合手机快捷指令等远程入口按 key 执行。
variables：工作流变量。运行时可以通过接口传入同名变量覆盖默认值。
settings.max_steps：防止流程循环或异常跳转导致无限执行。
nodes：节点实例列表。
edges：节点之间的连线，包括控制流和数据流。

节点结构

{
  "id": "mouse_1",
  "type": "mouse.click",
  "title": "点击目标",
  "position": { "x": 360, "y": 180 },
  "params": {
    "button": "left",
    "clicks": 1
  },
  "inputs": {
    "x": { "source": "node_output", "node_id": "locate_1", "output": "x" },
    "y": { "source": "node_output", "node_id": "locate_1", "output": "y" }
  }
}

type 必须来自 GET /api/automation/workflow-nodes 返回的节点定义。
params 是界面中固定编辑的参数。
inputs 是运行时输入，可以来自固定值、变量、上游节点输出或运行时上下文。
position 只影响前端画布显示。

输入来源

{ "source": "literal", "value": 100 }
{ "source": "variable", "name": "target_text" }
{ "source": "node_output", "node_id": "node_a", "output": "x" }
{ "source": "runtime", "name": "current_screenshot_path" }

第一版执行器支持以上四类输入。数据流连线也会在运行时转换成目标节点的输入值。

连线结构

控制流连线决定执行顺序：

{
  "id": "edge_1",
  "kind": "control",
  "source": "start_1",
  "source_port": "next",
  "target": "program_1",
  "target_port": "run"
}

数据流连线把源节点输出传给目标节点输入：

{
  "id": "edge_data_x",
  "kind": "data",
  "source": "locate_1",
  "source_port": "x",
  "target": "mouse_1",
  "target_port": "x"
}

内置节点类型

当前内置节点由后端注册表集中提供：

flow.start、flow.end、flow.condition
mouse.click、mouse.double_click、mouse.right_click、mouse.move、mouse.scroll
keyboard.press、keyboard.hotkey、keyboard.key_down、keyboard.key_up
text.input
browser.open_url
program.start、program.stop、program.close_opened
screen.screenshot
wait.seconds
human.ask_user

每个节点类型的参数、输入、输出和控制端口以 GET /api/automation/workflow-nodes 为准。前端节点库和属性面板应使用该接口动态生成。

执行结果

工作流运行接口按节点返回结果：

{
  "workflow_id": 1,
  "status": "SUCCESS",
  "results": [
    {
      "node_id": "program_1",
      "status": "SUCCESS",
      "inputs": {},
      "outputs": { "pid": 1234, "command": "notepad" }
    }
  ],
  "outputs": {
    "program_1": { "pid": 1234, "command": "notepad" }
  }
}

如果节点需要用户判断，执行结果会返回 status: "PAUSED"，并包含暂停节点、问题和可选截图路径。节点失败时，后端会尽量保存当前屏幕截图到自动化错误目录，并在失败项的 artifacts.screenshot_path 返回路径，供前端展示给用户继续分析。

workflow-format.md 3.8 KB 文件歷史 原始文件