# 恢复历史工作流候选为新提案

```{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/restore
```

## 调用前准备

准备目标工作区的个人访问令牌及相应工作流操作权限；使用同一环境中的对话、任务和产物。安装 jq 并设置示例所用变量。

## 请求体

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

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-candidates/restore" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg v0 "$WORKFLOW_CONTEXT_ID" --arg v1 "$RESTORE_REQUEST_ID" --arg v2 "$RESTORE_TASK_ID" --arg v3 "$RESTORE_ARTIFACT_ID" '{"context_id":$v0,"request_id":$v1,"candidate_ref":{"task_id":$v2,"artifact_id":$v3}}')"
```

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

选择同一对话中已完成任务的有效编译候选，不能恢复 failed 源记录。服务端在来源任务下追加新的产物和 pending 提案，重置 test_status 为 not_run，并保留 restored_from。task_id 可以不变，artifact_id 和 proposal_id 改变；后续必须用返回的新引用。恢复不会接受、发布或覆盖已保存应用，且保留原提案的目标绑定。相同请求标识和选择可重放；始终一起保存两者，不依赖服务端为同任务不同产物的标识复用报冲突。新提案有效期为创建后 24 小时。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `context_id` | string | 是 | 与来源任务一致的生成对话 ID。 |
| `request_id` | string | 是 | 为这次恢复保存的稳定标识；更换来源必须更换标识。 |
| `candidate_ref` | object | 是 | 从同一历史条目或任务产物保留完整引用。 |
| `candidate_ref.task_id` | string | 是 | 来源任务 ID；不是工作流应用 ID。 |
| `candidate_ref.artifact_id` | string | 是 | 该任务中的候选产物 ID。 |

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

## 成功响应

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "workflow_restore_b5c5286c71c60c1371946c8568e7f916",
    "candidate_ref": {
      "task_id": "task-1",
      "artifact_id": "workflow_candidate_b5c5286c71c60c1371946c8568e7f916"
    },
    "candidate": {
      "ok": true,
      "candidate_id": "workflow_candidate_b5c5286c71c60c1371946c8568e7f916",
      "proposal_id": "workflow_restore_b5c5286c71c60c1371946c8568e7f916_proposal",
      "summary": "candidate",
      "message": "waiting for explicit acceptance",
      "workflow": {
        "name": "candidate",
        "root": "root",
        "nets": {
          "root": {
            "nodes": {
              "__end": {
                "id": "mowl:end",
                "in_connector": {
                  "type": "simple",
                  "nodes": [
                    "__start"
                  ]
                }
              },
              "__start": {
                "id": "mowl:start",
                "out_connector": {
                  "type": "simple",
                  "nodes": [
                    "__end"
                  ]
                }
              }
            }
          }
        }
      },
      "runtime_fields": {
        "fields": [
          {
            "field_id": "source_ref",
            "label": "",
            "widget": ""
          },
          {
            "field_id": "prompt",
            "label": "",
            "widget": ""
          }
        ]
      },
      "catalog_revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "snapshot_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "syntax_version": "workflow-go/v1",
      "compiler_version": "workflow-go-compiler/v2",
      "source_code": "package workflow\nfunc Build() {}\n\n",
      "restored_from": {
        "task_id": "task-1",
        "artifact_id": "workflow_candidate_beae4775c142fe6e5dccdced956154fe"
      },
      "test_status": "not_run"
    },
    "status": "pending",
    "created_at": "2026-08-31T01:00:00Z"
  }
}
```

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应信息。 |
| `data` | object | 本动作结果。 |
| `data.id` | string | 新历史事件 ID。 |
| `data.candidate_ref` | object | 来源任务中的新候选产物引用。 |
| `data.candidate` | object | 新候选快照。 |
| `data.candidate.proposal_id` | string | 新待确认提案 ID。 |
| `data.candidate.restored_from` | object | 原始来源的任务/产物引用。 |
| `data.candidate.test_status` | string | 首次恢复为 not_run；重新测试后再确认。 |
| `data.status` | string | 首次恢复为 pending；重放以已持久化提案状态为准。 |
| `data.created_at` | string | 创建时间。 |

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

## 错误响应

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