# 测试与提交工作流项目

在工作流生成任务内，收集当前项目目录快照并提交给服务端编译和测试，验证通过后提交可供用户审阅的候选方案。

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

1. 从当前项目目录一次性读取 `workflow`、`operators` 与 `tests` 子目录中的普通文件快照。
2. 提交候选测试请求，核对测试报告状态达到 `completed`。
3. 使用同一份内存文件快照提交候选方案，核对编译通过（`ok` 为真）且候选测试状态为 `passed`。
4. 等待原生成任务返回候选产物后，提取任务 ID、产物 ID 与确认提案 ID 交由用户审阅。

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

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的 SDK 安装与环境准备。
2. **生成任务运行时环境**：在当前工作流生成任务的执行环境中运行，保留任务注入的 `MOI_ENDPOINT`、`MOI_API_KEY`、`MOI_RUNTIME_AUTHORIZATION` 与 `MOI_WORKSPACE_ID`；服务端在提交候选时会校验所属任务与对话范围。
3. **项目目录与测试样例**：从任务提供的项目目录取得当前工作流定义、自定义算子及测试用例，保留与本次修改无关的节点和配置；候选测试会实际运行节点，运行前先确认外部写入或消息发送节点的授权范围。

(sdk-ai-studio-workflow-project-submit)=
## 测试当前快照并提交候选

设置项目根目录环境变量后运行示例。客户端一次性读取本地目录文件内容并复用同一份快照执行测试与提交，防止两次请求之间本地文件发生变动。

```bash
export WORKFLOW_PROJECT_DIR="/path/to/current/project"
```

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

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

```python
import os
from pathlib import Path

from google.protobuf.json_format import MessageToDict
import moi_product_sdk as sdk

root = Path(os.environ["WORKFLOW_PROJECT_DIR"])
if root.is_symlink() or not root.is_dir():
    raise ValueError("Project root must be a regular directory")
files = {}
for name in ("workflow", "operators", "tests"):
    directory = root / name
    if not directory.exists() and name != "workflow":
        continue
    if directory.is_symlink() or not directory.is_dir():
        raise ValueError(f"Invalid project directory: {name}")
    for path in directory.rglob("*"):
        if path.is_symlink():
            raise ValueError(f"Symbolic link is not allowed: {path}")
        if path.is_file():
            files[path.relative_to(root).as_posix()] = path.read_bytes()
        elif not path.is_dir():
            raise ValueError(f"Non-regular file: {path}")
client = sdk.Client(
    os.environ["MOI_ENDPOINT"],
    sdk.with_api_key(os.environ["MOI_API_KEY"]),
    sdk.with_runtime_authorization(os.environ["MOI_RUNTIME_AUTHORIZATION"]),
)
workflows = client.workspace(os.environ["MOI_WORKSPACE_ID"]).workflows()
report = workflows.test_candidate(sdk.WorkflowCandidateTestRequest(project_files=files))
print("Test report:", MessageToDict(report, preserving_proto_field_name=True))
if report.status != "completed":
    raise SystemExit("Repair the project before submitting a candidate")
candidate = workflows.submit_candidate(sdk.WorkflowCandidateSubmitRequest(project_files=files))
print("Compiled:", candidate.ok, "Test status:", candidate.test_status)
print("Candidate:", candidate.candidate_id)
if not candidate.ok or candidate.test_status != "passed":
    raise SystemExit("Inspect candidate diagnostics and current test evidence")
print("Ready for review; no acceptance or deployment was performed.")
```

::::

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

```go
package main

import (
	"context"
	"fmt"
	"io/fs"
	"os"
	"path/filepath"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
	"google.golang.org/protobuf/encoding/protojson"
)

func main() {
	root := os.Getenv("WORKFLOW_PROJECT_DIR")
	info, err := os.Lstat(root)
	if err != nil {
		panic(err)
	}
	if !info.IsDir() {
		panic("Project root must be a regular directory")
	}
	files := map[string][]byte{}
	for _, name := range []string{"workflow", "operators", "tests"} {
		directory := filepath.Join(root, name)
		if _, err := os.Lstat(directory); err != nil {
			if os.IsNotExist(err) && name != "workflow" {
				continue
			}
			panic(err)
		}
		err = filepath.WalkDir(directory, func(path string, entry fs.DirEntry, walkErr error) error {
			if walkErr != nil {
				return walkErr
			}
			if entry.IsDir() {
				return nil
			}
			if !entry.Type().IsRegular() {
				return fmt.Errorf("Non-regular file: %s", path)
			}
			relative, err := filepath.Rel(root, path)
			if err != nil {
				return err
			}
			files[filepath.ToSlash(relative)], err = os.ReadFile(path)
			return err
		})
		if err != nil {
			panic(err)
		}
	}
	client, err := sdk.New(os.Getenv("MOI_ENDPOINT"),
		sdk.WithAPIKey(os.Getenv("MOI_API_KEY")),
		sdk.WithRuntimeAuthorization(os.Getenv("MOI_RUNTIME_AUTHORIZATION")))
	if err != nil {
		panic(err)
	}
	defer client.Close()
	workspace, err := client.Workspace(os.Getenv("MOI_WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	workflows := workspace.Workflows()
	ctx := context.Background()
	report, err := workflows.TestCandidate(ctx, &sdk.WorkflowCandidateTestRequest{ProjectFiles: files})
	if err != nil {
		panic(err)
	}
	encoded, err := protojson.MarshalOptions{UseProtoNames: true}.Marshal(report)
	if err != nil {
		panic(err)
	}
	fmt.Println("Test report:", string(encoded))
	if report.GetStatus() != "completed" {
		panic("Repair the project before submitting a candidate")
	}
	candidate, err := workflows.SubmitCandidate(ctx, &sdk.WorkflowCandidateSubmitRequest{ProjectFiles: files})
	if err != nil {
		panic(err)
	}
	fmt.Println("Compiled:", candidate.GetOk(), "Test status:", candidate.GetTestStatus())
	fmt.Println("Candidate:", candidate.GetCandidateId())
	if !candidate.GetOk() || candidate.GetTestStatus() != "passed" {
		panic("Inspect candidate diagnostics and current test evidence")
	}
	fmt.Println("Ready for review; no acceptance or deployment was performed.")
}
```

::::

:::::

请求仅上传 `workflow`、`operators` 和 `tests` 三个目录中的项目源码与测试定义，平台生成的测试证据与参考资料由服务端维护。编译成功、测试请求执行完毕（`completed`）和候选整体测试通过（`passed`）分别对应不同阶段的状态；修改任意项目文件后均需重新执行测试并提交新快照。

(sdk-ai-studio-workflow-project-review)=
## 读取候选产物并交由用户审阅

提交候选接口返回当前候选标识与测试状态投影，本身不会自动确认或部署工作流。等待原生成任务结束并产出候选产物后，从该产物读取同一方案的任务 ID、产物 ID 与确认提案 ID（后续确认流程使用产物 ID，候选标识仅用于标识本次编译快照）。

单个测试用例仅用于定位具体节点问题；交付审阅前需一并核对完整测试套件、节点执行覆盖范围与当前候选测试状态。若测试过程分配了临时数据库、卷或表等测试临时区资源，可通过工作流服务的测试临时区接口准备、查看或按任务 ID 重置清理。

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

- [确认与发布工作流方案](确认并发布工作流方案.md#sdk-ai-studio-workflow-proposal-publish)
- [查看与恢复工作流历史](查看和恢复工作流历史.md#sdk-ai-studio-workflow-history-list)
