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",
    "return": {"node_id": "result_node", "output": "data"}
  },
  "nodes": [],
  "edges": []
}

字段说明：

workflow_key：可选的稳定调用 key，只能使用字母、数字、下划线和连字符；适合手机快捷指令等远程入口按 key 执行。
variables：工作流变量。运行时可以通过接口传入同名变量覆盖默认值。
settings.max_steps：防止流程循环或异常跳转导致无限执行。
settings.return：异步任务完成后，从指定节点输出中提取 return_data。省略 output 时返回该节点的全部输出。
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
browser.ensure_foreground：打开或唤起浏览器，可选打开网址并最大化窗口。
browser.control：执行浏览器全屏、返回、刷新、关闭标签页等快捷控制。
browser.video_action：打开 YouTube/Bilibili/抖音视频，或在抖音视频流切换下一条。
browser.web_search：使用真实浏览器截图和多模态模型，完成搜索结果提取、去重排序、详情页研究和总结。
research.ai_web_research：让 AI 规划查询、执行多轮视觉搜索、评估目标并按 JSON Schema 生成最终数据。
vision.locate_element：截取当前屏幕，调用多模态 AI 定位目标元素的相对百分比位置，并输出换算后的屏幕坐标。
vision.click_target：定位目标并立即点击，减少常见“定位节点 + 鼠标节点”的重复搭线。
vision.verify_page：用多模态 AI 判断当前屏幕是否符合预期状态，并输出匹配分支。
vision.close_popups：尝试识别并点击关闭、跳过、稍后再说等弹窗按钮。
media.control：面向客厅遥控场景的播放暂停、全屏、静音、音量和上下条控制。
program.start、program.stop、program.close_opened
screen.screenshot
wait.seconds
human.ask_user

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

异步执行

工作流只通过稳定 key 执行：

POST /api/automation/workflows/by-key/{workflow_key}/run

接口立即返回任务 ID。所有 workflow 共用一个串行队列，任意时刻只有一个任务运行。使用以下接口读取状态和结果：

GET /api/automation/workflow-tasks/{task_id}
GET /api/automation/workflow-tasks

任务完成后同时提供完整 result 和按 settings.return 提取的 return_data：

{
  "id": "task-uuid",
  "status": "SUCCESS",
  "return_data": {"answer": "..."},
  "result": {"status": "SUCCESS", "results": [], "outputs": {}}
}

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

AI 多轮网页研究工作流

仓库提供 workflows/ai-web-research.workflow.json。该 workflow 的 key 为 ai-web-research，变量包括：

objective：搜索和研究目标。
output_schema：最终 data 必须满足的 JSON Schema。
constraints：语言、最少来源数、必需域名等约束。
max_attempts：未达成目标时的最大搜索轮数。

节点会先让本地 AI 制定查询计划，再循环调用视觉网页搜索。每轮结束后同时执行 JSON Schema 校验、来源约束校验和 AI 语义目标判断，直到目标达成或达到次数上限。

导入导出

POST /api/automation/workflows/import：导入 workflow JSON，可选择遇到相同 key 时覆盖。
GET /api/automation/workflows/by-key/{workflow_key}/export：导出可迁移 JSON。
前端自动化工作流页面提供“导入 JSON”和“导出”按钮。

workflow-format.md 6.3 KB Historie Surový