API 参考: 工作流 (Workflows)

工作流管理端点。创建、执行、监控自动化工作流。

创建工作流

POST /v1/workflows

权限要求： write

请求体

字段	类型	必填	说明
name	string	是	工作流名称
description	string	否	描述
trigger	object	否	触发配置，默认 { "type": "manual" }
trigger.type	string	--	manual/cron/event
trigger.schedule	string	--	cron 表达式（type=cron 时）
trigger.event	string	--	事件类型（type=event 时）
nodes	array	否	节点数组
nodes[].id	string	--	节点唯一 ID
nodes[].type	string	--	节点类型：ai-generate/tool-call/http-request/condition/email-send
nodes[].config	object	--	节点配置（因类型而异）
edges	array	否	边数组，定义执行顺序
edges[].from	string	--	起始节点 ID
edges[].to	string	--	目标节点 ID
edges[].condition	string	--	条件值（用于 condition 节点出边）："true"/"false"

请求示例

curl -X POST https://api.invoratec.cn/v1/workflows \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "每日设备巡检",
    "description": "自动检查设备状态并发送报告",
    "trigger": { "type": "cron", "schedule": "0 9 * * *" },
    "nodes": [
      {
        "id": "fetch",
        "type": "tool-call",
        "config": { "tool": "iot_get_all_devices", "input": {} }
      },
      {
        "id": "analyze",
        "type": "ai-generate",
        "config": { "prompt": "分析设备数据：{{fetch.result}}" }
      },
      {
        "id": "notify",
        "type": "email-send",
        "config": { "to": "ops@example.com", "subject": "巡检报告", "body": "{{analyze.result}}" }
      }
    ],
    "edges": [
      { "from": "fetch", "to": "analyze" },
      { "from": "analyze", "to": "notify" }
    ]
  }'

响应 (201 Created)

{
  "id": "665f1a2b3c4d5e6f7a8b9c0d",
  "userId": "user_123",
  "name": "每日设备巡检",
  "description": "自动检查设备状态并发送报告",
  "trigger": { "type": "cron", "schedule": "0 9 * * *" },
  "nodes": [...],
  "edges": [...],
  "enabled": true,
  "source": "api",
  "createdAt": "2026-04-12T08:00:00.000Z",
  "updatedAt": "2026-04-12T08:00:00.000Z"
}

错误

状态码	说明
400	name 缺失
403	缺少 write 权限

---

列出工作流

返回工作流列表，不包含 nodes 和 edges 字段（减少传输量）。

GET /v1/workflows

请求示例

curl https://api.invoratec.cn/v1/workflows \
  -H "X-API-Key: claw_xxxx"

响应

{
  "workflows": [
    {
      "_id": "665f...",
      "name": "每日设备巡检",
      "description": "自动检查设备状态",
      "trigger": { "type": "cron", "schedule": "0 9 * * *" },
      "enabled": true,
      "source": "api",
      "updatedAt": "2026-04-12T08:00:00.000Z"
    }
  ],
  "total": 1
}

---

获取工作流详情

返回完整的工作流定义，包含 nodes 和 edges。

GET /v1/workflows/{id}

路径参数

参数	类型	说明
id	string	工作流 _id

请求示例

curl https://api.invoratec.cn/v1/workflows/665f... \
  -H "X-API-Key: claw_xxxx"

错误

状态码	说明
404	工作流不存在

---

更新工作流

PUT /v1/workflows/{id}

权限要求： write

路径参数

参数	类型	说明
id	string	工作流 _id

请求体

可更新字段：name, description, trigger, nodes, edges, enabled。

请求示例

curl -X PUT https://api.invoratec.cn/v1/workflows/665f... \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "description": "暂停巡检"
  }'

响应

返回更新后的完整工作流文档。

错误

状态码	说明
403	缺少 write 权限
404	工作流不存在

---

删除工作流

DELETE /v1/workflows/{id}

权限要求： write

请求示例

curl -X DELETE https://api.invoratec.cn/v1/workflows/665f... \
  -H "X-API-Key: claw_xxxx"

响应

{ "success": true }

---

执行工作流

手动触发工作流执行。工作流加入执行队列，异步处理。

POST /v1/workflows/{id}/run

权限要求： write

路径参数

参数	类型	说明
id	string	工作流 _id

请求体

字段	类型	必填	说明
data	object	否	触发数据，可在节点中通过 {{trigger.data}} 引用

请求示例

curl -X POST https://api.invoratec.cn/v1/workflows/665f.../run \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": { "building": "A栋" }
  }'

响应

{
  "runId": "665f1a2b3c4d5e6f7a8b9c0e",
  "status": "pending",
  "message": "工作流已加入执行队列"
}

错误

状态码	说明
403	缺少 write 权限
404	工作流不存在

---

查看执行历史

GET /v1/workflows/{id}/runs

路径参数

参数	类型	说明
id	string	工作流 _id

查询参数

参数	类型	说明
limit	integer	返回上限，默认 20

请求示例

curl "https://api.invoratec.cn/v1/workflows/665f.../runs?limit=10" \
  -H "X-API-Key: claw_xxxx"

响应

{
  "runs": [
    {
      "_id": "665f...",
      "workflowId": "665f...",
      "status": "completed",
      "triggeredBy": "api",
      "triggerData": { "building": "A栋" },
      "stepResults": [...],
      "createdAt": "2026-04-12T09:00:00.000Z"
    }
  ]
}

执行状态

status	说明
pending	等待执行
running	执行中
completed	执行成功
failed	执行失败

---

查看执行详情

GET /v1/workflows/{id}/runs/{runId}

路径参数

参数	类型	说明
id	string	工作流 _id
runId	string	执行记录 _id

请求示例

curl https://api.invoratec.cn/v1/workflows/665f.../runs/665f... \
  -H "X-API-Key: claw_xxxx"

响应

{
  "_id": "665f...",
  "workflowId": "665f...",
  "status": "completed",
  "triggeredBy": "api",
  "triggerData": { "building": "A栋" },
  "stepResults": [
    {
      "nodeId": "fetch",
      "status": "success",
      "result": { "devices": [...] },
      "startedAt": "2026-04-12T09:00:01.000Z",
      "completedAt": "2026-04-12T09:00:02.000Z"
    },
    {
      "nodeId": "analyze",
      "status": "success",
      "result": "所有设备运行正常...",
      "startedAt": "2026-04-12T09:00:02.000Z",
      "completedAt": "2026-04-12T09:00:05.000Z"
    }
  ],
  "createdAt": "2026-04-12T09:00:00.000Z"
}

错误

状态码	说明
404	执行记录不存在