# Workflow v1 数据格式与节点说明

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

## 顶层结构

```json
{
  "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`：节点之间的连线，包括控制流和数据流。

## 节点结构

```json
{
  "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` 只影响前端画布显示。

## 输入来源

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

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

## 连线结构

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

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

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

```json
{
  "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` 为准。前端节点库和属性面板应使用该接口动态生成。

## 执行结果

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

```json
{
  "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` 返回路径，供前端展示给用户继续分析。