工作流接口

所有 workflow profile 管理接口都需要鉴权，并受 settings.* 权限控制。

List workflow profiles

GET /api/v1/system/workflows

需要权限：settings.read 返回所有 workflow profile。当前列表会按 isAutoRun 优先、再按名称排序。

响应字段

id
name
description
isAutoRun
graphJson
createdAtUtc
updatedAtUtc

Get workflow profile

GET /api/v1/system/workflows/{id}

需要权限：settings.read 如果 workflow 不存在，返回 404，错误码为 workflow_profile_not_found。

Create workflow profile

POST /api/v1/system/workflows

需要权限：settings.update

Request body

{
  "name": "image-post-process",
  "description": "Generate thumbnail and caption after upload.",
  "isAutoRun": true,
  "graphJson": "{\"nodes\":[{\"id\":\"node-1\",\"data\":{\"skillId\":\"thumbnail\"}}],\"edges\":[],\"viewport\":{\"x\":0,\"y\":0,\"zoom\":1}}"
}

校验规则

name 必填，最长 100 字符
description 可为空，最长 1000 字符
graphJson 必填，且必须是合法 JSON 对象
workflow 名称必须唯一，否则返回 workflow_profile_name_conflict
如果创建时 isAutoRun=true，后端会自动清除其他 workflow 的自动运行标记

Update workflow profile

PUT /api/v1/system/workflows/{id}

需要权限：settings.update 请求体字段与创建时相同，但这是整体更新，不是 PATCH 语义。

说明

你需要重新提交完整的 name、description、isAutoRun、graphJson
如果 isAutoRun=true，后端同样会自动取消其他 workflow 的自动运行状态

Delete workflow profile

DELETE /api/v1/system/workflows/{id}

需要权限：settings.update 成功时返回 204 No Content。

Set workflow as auto-run

PATCH /api/v1/system/workflows/{id}/autorun

需要权限：settings.update 把指定 workflow 设为自动运行 workflow。当前约束：

同一时刻只能有一个 isAutoRun=true 的 workflow
后端会自动清除其他 workflow 的自动运行标记

Run workflow on an asset

POST /api/v1/assets/{id}/workflows/{workflowId}/run

需要权限：assets.update 这个接口不是 workflow profile 管理接口，但它是 workflow 的实际执行入口。

行为

后端会先读取 asset 和 workflow profile
解析 graphJson 中的技能节点
在入队前检查这些 skill 是否适用于当前 asset
校验通过后，将 workflow 对应 skill 序列放入异步处理队列

响应

成功时返回 202 Accepted：

{
  "data": {
    "assetId": "01956f8d-88e4-7c6a-a8f1-5f235293db7a",
    "workflowId": "01957000-0000-7000-0000-000000000001",
    "skillIds": [
      "thumbnail",
      "ai-caption"
    ]
  }
}

常见错误

workflow_profile_not_found
workflow_profile_has_no_skills
workflow_profile_contains_unsupported_skills

graphJson 结构说明

后端当前要求 graphJson 是一个 JSON 对象。解析时：

优先读取 nodes[].data.skillId
如果没有 data.skillId，再回退到旧结构里的 nodes[].type
如果 data.parameters 存在，则作为该节点的参数
如果是旧图结构，后端也会尝试把 data 中除 skillId 以外的字段视为参数

最小示例：

{
  "nodes": [
    {
      "id": "node-1",
      "data": {
        "skillId": "thumbnail"
      }
    },
    {
      "id": "node-2",
      "data": {
        "skillId": "watermark",
        "parameters": {
          "Text": "NekoHub",
          "Opacity": 0.5,
          "FontSize": 36,
          "Position": "BottomRight"
        }
      }
    }
  ],
  "edges": [],
  "viewport": {
    "x": 0,
    "y": 0,
    "zoom": 1
  }
}

当前执行模型仍按节点保存顺序线性执行，edges 和 viewport 主要用于前端编辑器展示与回填。

概览

端点

List workflow profiles

响应字段

Get workflow profile

Create workflow profile

Request body

校验规则

Update workflow profile

说明

Delete workflow profile

Set workflow as auto-run

Run workflow on an asset

行为

响应

常见错误

graphJson 结构说明

​List workflow profiles

​响应字段

​Get workflow profile

​Create workflow profile

​Request body

​校验规则

​Update workflow profile

​说明

​Delete workflow profile

​Set workflow as auto-run

​Run workflow on an asset

​行为

​响应

​常见错误

​graphJson 结构说明

List workflow profiles

响应字段

Get workflow profile

Create workflow profile

Request body

校验规则

Update workflow profile

说明

Delete workflow profile

Set workflow as auto-run

Run workflow on an asset

行为

响应

常见错误

graphJson 结构说明