# 提交任务项目候选

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

编译当前任务的项目快照，生成供用户检查的候选。相关对象、变量及环境边界见[公共说明](objects.md)。

```text
POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-candidates/submit
```

## 调用前准备

在当前生成任务执行环境中保留注入的服务地址、凭据、工作区和短期授权。授权头使用完整原值。安装 jq 并设置示例所用变量。

## 请求体

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

```bash
jq -n --slurpfile files "$PROJECT_FILES_JSON" '{project_files:$files[0]}' > request.json
curl -X POST "${MOI_ENDPOINT%/}/workflow/v2/workflow-candidates/submit" \
  -H "X-API-Key: $MOI_API_KEY" \
  -H "X-Workspace-ID: $MOI_WORKSPACE_ID" \
  -H "X-MOI-Runtime-Authorization: $MOI_RUNTIME_AUTHORIZATION" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json
```

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

只传 workflow/、operators/、tests/ 下服务端允许编写的普通文件；不要上传平台证据或把本地绝对路径作为服务端路径。不能同时提交 source、summary、catalog_revision、intent、test_status 或 test_result。先完整测试同一快照，再提交。普通 PAT 不足以使用此项目分支；提交后等待任务完成并发布候选产物，才进入用户确认。旧 source 分支另需独立复核，不能套用本分支参数。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `project_files` | object | 本分支必填 | 项目相对路径到 Base64 文件字节的映射；由当前任务工作目录读取。 |
| `scope` | object | 否 | 提交接口的任务范围；省略由经过校验的当前任务身份确定。 |
| `scope.task_id` | string | 否 | 提供时必须与当前任务一致。 |
| `scope.context_id` | string | 否 | 提供时必须与当前生成对话一致。 |

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

## 成功响应

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "ok": false,
    "message": "项目未形成可用候选"
  }
}
```

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应信息。 |
| `data` | object | 本动作结果。 |
| `data.ok` | boolean | 是否得到可用的编译候选；不表示已通过全部测试或已接受。 |
| `data.candidate_id` | string | 编译候选标识；等任务产物发布后再读取用于确认的 artifact_id。 |
| `data.proposal_id` | string | 存在时为对应确认提案；与候选及其任务一起保存。 |
| `data.diagnostics` | object[] | 编译或校验诊断；按 message、stage、path、line、column 排查。 |
| `data.test_status` | string | 当前快照的服务端测试投影；不得由客户端自行宣称通过。 |
| `data.test_result` | object | 存在时为关联测试证据；与当前可执行快照对应。 |

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

## 错误响应

按 HTTP 状态和业务字段处理。历史查询与恢复另有专用错误代码，见[错误与环境](objects.md#错误与环境)。先保留身份、来源引用和操作标识，核对状态后处理；不自动改换工作区、候选或确认键。
