# 按显式工作流版本创建 Worker 任务

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

`POST /workspaces/{id}/tasks` 是 Worker 兼容入口，调用统一工作流执行 service。单个非空 `X-Workspace-ID` 须等于路径工作区。不是自动化规则创建，也不是配置定时任务的接口。

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```json
{
  "task": {
    "name": "sample-run",
    "workflow_version_id": "version-example",
    "data": "{\"text\":\"sample\"}",
    "vars": "{}"
  }
}
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `task` | object | 是 | 以下对象 |
| `task.name` | string | 是 | handler 要求非空；未据此补造全局唯一或首尾空白规则 |
| `task.workflow_version_id` | string | 是 | 当前工作区明确指定的已发布版本 ID，不能填工作流应用 ID |
| `task.data` | string | 否 | 编码后的 JSON 对象字符串；省略或空白按空对象，数组、null、无效JSON不接受 |
| `task.vars` | string | 否 | 同样是编码后的 JSON 对象字符串，非直接 JSON 对象 |

body 只允许一个完整 JSON 值，并拒绝未知字段。请求体或 task 中增加 cron_expression、transient、trace 等字段会落入当前严格 DTO 的未知字段拒绝路径；未知字段不能写成“被忽略”。

:::::
::::::
:::::::

## 执行条件与副作用

指定版本须能解析到唯一工作流应用，该应用须有部署定义和最新版本引用，目标版本须属于相同定义、为published且有非空工作流内容。暂停或停用的应用拒绝执行；动态服务版本仍验证输入 schema。

权限检查边界先解析应用及资源事实、核对主体并授权，然后注入有效角色。任务名与版本路径选择 one_shot delivery：即使应用本身是 Cron，也创建独立单次子执行，不创建或替换计划。完整资源发现与运行期策略尚待复核，不能把单个 service 测试扩大成全部 Catalog 依赖授权通过。

统一执行链准备 Mowl task/case，在事务中持久化执行与血缘并回读，提交后才唤醒执行。后续唤醒失败可能发生在记录已提交之后；失败后先查已有运行，不能自动重复提交。接口没有请求幂等键，不承诺重试去重。

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "task": {
    "id": "worker-task-example",
    "name": "sample-run",
    "workflow_version_id": "version-example",
    "workflow_execution_id": "execution-example"
  }
}
```

:::::
:::::{tab-item} 字段说明

HTTP200 直接返回 `task`，没有 code/msg/data 外层：



| 字段 | 类型 | 后续用途 |
| --- | --- | --- |
| `task.id` | string | Mowl/Worker 任务 ID，不是智能体 authoring task ID |
| `task.name` | string | 请求任务名 |
| `task.workflow_version_id` | string | 请求的显式版本 ID |
| `task.workflow_execution_id` | string | 产品工作流执行 ID，用于执行详情和结果查询 |

响应没有状态字段。Worker protobuf 的零值或客户端默认值不证明已运行、完成或输出成功。常见参数和未部署等错误为400/ErrParamInvalid，工作区缺失为400/ErrWorkspaceRequired；其他授权、资源、执行身份、依赖、存储和唤醒错误沿共享工作流错误映射。

:::::
::::::
:::::::
