# 查看与恢复工作流历史

按工作流生成对话分页查看候选方案历史，并将选定的已编译历史方案恢复为新的待确认提案。

(sdk-ai-studio-workflow-history-flow)=
## 任务流程

1. 传入原生成任务的对话上下文 ID（`WORKFLOW_CONTEXT_ID`），按生成任务分页读取历史候选条目。
2. 从返回列表中筛选已编译通过（`ok` 为真）的候选条目，记录其来源任务 ID 与来源产物 ID。
3. 生成唯一请求标识（`RESTORE_REQUEST_ID`）并提交恢复请求，取得新的产物 ID、提案 ID 与重置后的测试状态。
4. 在原对话内重新核查并测试恢复出的候选方案，确认无误后再接受和发布。

(sdk-ai-studio-workflow-history-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. **对话上下文 ID**（`WORKFLOW_CONTEXT_ID`）：从原工作流生成任务保存对话上下文 ID；历史接口按该生成对话聚合查询，工作流 ID、独立持久会话 ID 和运行 ID 分属其他资源维度。
3. **恢复请求标识**（`RESTORE_REQUEST_ID`）：在发起恢复前生成并保存唯一幂等请求标识；网络结果未明时保留同一标识与同一来源候选重试，改选其他来源候选时生成新标识。

(sdk-ai-studio-workflow-history-list)=
## 按任务分页读取历史

以下示例最多翻阅 10 页，每页按 20 个生成任务查询。单个生成任务可能包含多个候选条目，也可能尚无可展示条目；翻页进度按服务端返回的任务总数（`total_tasks`）和每页任务上限（`limit`）推进，当偏移量达到或超过任务总数时停止翻页。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"], os.environ["PRODUCT_API_KEY"]
)
workflows = client.workspace(os.environ["WORKSPACE_ID"]).workflows()
context_id = os.environ["WORKFLOW_CONTEXT_ID"]
entries = []
offset = 0
for _ in range(10):
    page = workflows.history(context_id, 20, offset)
    entries.extend(page.items)
    for entry in page.items:
        print(entry.candidate_ref.task_id, entry.candidate_ref.artifact_id,
              entry.status, entry.candidate.test_status, entry.created_at)
    offset += page.limit
    if offset >= page.total_tasks:
        break
    if page.limit <= 0:
        raise RuntimeError("Invalid task pagination")
else:
    raise RuntimeError("History page budget reached; continue at the returned task offset")
print("Candidate entries:", len(entries), "Task offset:", offset)
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	defer client.Close()
	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	workflows := workspace.Workflows()
	contextID := os.Getenv("WORKFLOW_CONTEXT_ID")
	var entries []*sdk.WorkflowHistoryEntry
	offset, complete := 0, false
	for pageIndex := 0; pageIndex < 10; pageIndex++ {
		page, err := workflows.History(ctx, contextID, 20, offset)
		if err != nil {
			panic(err)
		}
		entries = append(entries, page.GetItems()...)
		for _, entry := range page.GetItems() {
			fmt.Println(entry.GetCandidateRef().GetTaskId(), entry.GetCandidateRef().GetArtifactId(),
				entry.GetStatus(), entry.GetCandidate().GetTestStatus(), entry.GetCreatedAt())
		}
		offset += int(page.GetLimit())
		if offset >= int(page.GetTotalTasks()) {
			complete = true
			break
		}
		if page.GetLimit() <= 0 {
			panic("Invalid task pagination")
		}
	}
	if !complete {
		panic("History page budget reached; continue at the returned task offset")
	}
	fmt.Println("Candidate entries:", len(entries), "Task offset:", offset)
}
```

::::

:::::

(sdk-ai-studio-workflow-history-restore)=
## 恢复选中的历史方案

从上一步读取的历史条目中选择已编译通过的候选方案（编译失败的源码快照无法恢复），传入其来源任务 ID（`RESTORE_TASK_ID`）与来源产物 ID（`RESTORE_ARTIFACT_ID`）。恢复操作会在原来源任务下生成新的待确认方案，返回新的 `artifact_id`、新的确认提案 ID 及重置后的测试状态；后续测试与确认必须改用新返回的 `artifact_id` 和提案 ID。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
source_task = os.environ["RESTORE_TASK_ID"]
source_artifact = os.environ["RESTORE_ARTIFACT_ID"]
selected = next((entry for entry in entries
                 if entry.candidate_ref.task_id == source_task
                 and entry.candidate_ref.artifact_id == source_artifact
                 and entry.candidate.ok), None)
if selected is None:
    raise RuntimeError("Choose a compiled candidate from the history page")
restored = workflows.restore_history(sdk.WorkflowHistoryRestoreRequest(
    context_id=context_id, request_id=os.environ["RESTORE_REQUEST_ID"],
    candidate_ref=sdk.WorkflowCandidateRef(source_task, source_artifact),
))
print("Restored reference:", restored.candidate_ref.task_id, restored.candidate_ref.artifact_id)
print("Proposal:", restored.candidate.proposal_id, "State:", restored.status,
      "Tests:", restored.candidate.test_status)
```

::::

::::{tab-item} Go
:sync: go

```go
sourceTask, sourceArtifact := os.Getenv("RESTORE_TASK_ID"), os.Getenv("RESTORE_ARTIFACT_ID")
found := false
for _, entry := range entries {
	if entry.GetCandidateRef().GetTaskId() == sourceTask &&
		entry.GetCandidateRef().GetArtifactId() == sourceArtifact &&
		entry.GetCandidate().GetOk() {
		found = true
	}
}
if !found {
	panic("Choose a compiled candidate from the history page")
}
restored, err := workflows.RestoreHistory(ctx, sdk.WorkflowHistoryRestoreRequest{
	ContextID:    contextID,
	RequestID:    os.Getenv("RESTORE_REQUEST_ID"),
	CandidateRef: sdk.WorkflowCandidateRef{TaskID: sourceTask, ArtifactID: sourceArtifact},
})
if err != nil {
	panic(err)
}
fmt.Println("Restored reference:", restored.GetCandidateRef().GetTaskId(), restored.GetCandidateRef().GetArtifactId())
fmt.Println("Proposal:", restored.GetCandidate().GetProposalId(), "State:", restored.GetStatus(), "Tests:", restored.GetCandidate().GetTestStatus())
```

::::

:::::

恢复操作保留来源候选不变，且不会自动接受、发布或覆盖线上已保存的工作流。恢复出的方案测试状态从初始状态重新计算；在原对话中核对配置、重新测试并通过审阅后，再按 [确认与发布工作流方案](确认并发布工作流方案.md#sdk-ai-studio-workflow-proposal-publish) 执行确认和发布。读取历史响应时需分别检查 `current` 与 `saved_workflow`（两者均可能为空）：存在接受记录仅代表该方案曾被确认采用，已保存的工作流版本可能早于该次接受，也可能由同一工作流的其他对话发布。

(sdk-ai-studio-workflow-history-next)=
## 下一步

- [测试与提交工作流项目](测试并提交工作流项目.md#sdk-ai-studio-workflow-project-submit)
- [确认与发布工作流方案](确认并发布工作流方案.md#sdk-ai-studio-workflow-proposal-publish)
