docs(runtime): task validate api (#522)

apps/docs/src/en/guide/runtime/api.mdx

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 # FlowGram Runtime API Reference
 
-FlowGram Runtime provides four core APIs for running, monitoring, retrieving results, and canceling workflows. This document details the usage, parameters, and return values of these APIs.
+FlowGram Runtime provides five core APIs for validating, running, monitoring, retrieving results, and canceling workflows. This document details the usage, parameters, and return values of these APIs.
 
 ## TaskRun API
 
@@ -374,3 +374,142 @@ async function waitForResult(taskID, pollingInterval = 1000, timeout = 60000) {
 - It is recommended to check if the task has terminated through TaskReport API before calling TaskResult API to get the result
 - For canceled tasks, only partial results or no results may be available
 - The specific structure of the result depends on the definition of the workflow, and needs to be parsed according to the actual output of the workflow
+
+## TaskValidate API
+
+### Function Description
+
+The TaskValidate API is used to validate the validity of workflow schema and input parameters before actually running the workflow. This API helps you discover potential configuration errors before starting the workflow.
+
+### Parameters
+
+TaskValidate API accepts a `TaskValidateInput` object as its parameter:
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| schema | string | Yes | JSON string of the workflow schema, defining nodes and edges |
+| inputs | object | No | Initial input parameters for the workflow, used to validate if inputs meet schema requirements |
+
+### Return Value
+
+TaskValidate API returns a `TaskValidateOutput` object:
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| valid | boolean | Indicates whether validation passed, true means validation succeeded, false means validation failed |
+| errors | string[] | Optional field, contains specific error message list when validation fails |
+
+### Validation Content
+
+TaskValidate API validates the following content:
+
+- **Schema Structure Validation**: Checks if the schema conforms to WorkflowSchema format requirements
+- **Node Type Validation**: Validates if node types in the schema are supported
+- **Edge Connection Validation**: Checks if connections between nodes are correct
+- **Input Parameter Validation**: Validates if provided inputs meet the input requirements defined in the schema
+- **Workflow Integrity Validation**: Checks if the workflow contains necessary start and end nodes
+
+### Error Handling
+
+TaskValidate API may return the following types of validation errors:
+
+- **Schema parsing error**: When the provided schema is not a valid JSON string
+- **Schema structure error**: When the schema structure does not match the expected format
+- **Node configuration error**: When node configuration is incomplete or incorrect
+- **Connection error**: When there are issues with connections between nodes
+- **Input parameter error**: When input parameters do not meet requirements
+
+### Usage Example
+
+```javascript
+import { TaskValidateAPI } from '@flowgram.ai/runtime-js';
+
+const schema = JSON.stringify({
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      meta: { position: { x: 0, y: 0 } },
+      data: {}
+    },
+    {
+      id: 'llm',
+      type: 'llm',
+      meta: { position: { x: 200, y: 0 } },
+      data: {
+        modelName: 'gpt-3.5-turbo',
+        temperature: 0.7,
+        systemPrompt: '你是一个助手',
+        prompt: '介绍一下自己'
+      }
+    },
+    {
+      id: 'end',
+      type: 'end',
+      meta: { position: { x: 400, y: 0 } },
+      data: {}
+    }
+  ],
+  edges: [
+    {
+      sourceNodeID: 'start',
+      sourcePort: 'out',
+      targetNodeID: 'llm',
+      targetPort: 'in'
+    },
+    {
+      sourceNodeID: 'llm',
+      sourcePort: 'out',
+      targetNodeID: 'end',
+      targetPort: 'in'
+    }
+  ]
+});
+
+const inputs = {
+  userInput: 'Please introduce yourself'
+};
+
+async function validateWorkflow() {
+  try {
+    const result = await TaskValidateAPI({
+      schema,
+      inputs
+    });
+
+    if (result.valid) {
+      console.log('Workflow validation passed, safe to run');
+      return true;
+    } else {
+      console.error('Workflow validation failed:');
+      result.errors?.forEach(error => {
+        console.error('- ' + error);
+      });
+      return false;
+    }
+  } catch (error) {
+    console.error('Error occurred during validation:', error);
+    return false;
+  }
+}
+
+// Validate before running the workflow
+async function safeRunWorkflow() {
+  const isValid = await validateWorkflow();
+  if (isValid) {
+    // Run the workflow after validation passes
+    const runResult = await TaskRunAPI({ schema, inputs });
+    console.log('Workflow started, Task ID:', runResult.taskID);
+  } else {
+    console.log('Workflow validation failed, please fix errors and retry');
+  }
+}
+```
+
+### Notes
+
+- It is recommended to call TaskValidate API before calling TaskRun API for validation
+- Passing validation does not guarantee that the workflow will not encounter errors during runtime, but it can identify most configuration issues in advance
+- TaskValidate API typically executes faster than TaskRun API, making it suitable for real-time validation
+- Error messages in validation results can help quickly locate and fix issues
+- For complex workflows, it is recommended to use this API frequently during development for validation

apps/docs/src/en/guide/runtime/source-code-guide.mdx

@@ -83,8 +83,8 @@ The js-core module is the core of FlowGram Runtime, implementing the main functi
 
 The application layer is responsible for coordinating domain objects and implementing system use cases. Key files:
 
-- `application/workflow.ts`: Workflow application service, implementing workflow execution, cancellation, querying, etc.
-- `application/api.ts`: API implementation, including TaskRun, TaskResult, TaskReport, TaskCancel, etc.
+- `application/workflow.ts`: Workflow application service, implementing workflow validation, execution, cancellation, querying, etc.
+- `application/api.ts`: API implementation, including TaskValidate, TaskRun, TaskResult, TaskReport, TaskCancel, etc.
 
 #### Domain Layer
 

apps/docs/src/zh/guide/runtime/api.mdx

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 # FlowGram Runtime API 参考
 
-FlowGram Runtime 提供了四个核心 API，用于工作流的运行、监控、结果获取和取消。本文档详细介绍了这些 API 的使用方法、参数和返回值。
+FlowGram Runtime 提供了五个核心 API，用于工作流的验证、运行、监控、结果获取和取消。本文档详细介绍了这些 API 的使用方法、参数和返回值。
 
 ## TaskRun API
 
@@ -374,3 +374,180 @@ async function waitForResult(taskID, pollingInterval = 1000, timeout = 60000) {
 - 建议先通过 TaskReport API 检查任务是否已终止，再调用 TaskResult API 获取结果
 - 对于已取消的任务，可能只能获取到部分结果或没有结果
 - 结果的具体结构取决于工作流的定义，需要根据实际工作流的输出进行解析
+
+## TaskValidate API
+
+### 功能描述
+
+TaskValidate API 用于验证工作流 schema 和输入参数的有效性，在实际运行工作流之前检查配置是否正确。这个 API 可以帮助您在启动工作流之前发现潜在的配置错误。
+
+### 参数说明
+
+TaskValidate API 接收一个 `TaskValidateInput` 对象作为参数：
+
+| 参数名 | 类型 | 必填 | 描述 |
+| ------ | ---- | ---- | ---- |
+| schema | string | 是 | 工作流 schema 的 JSON 字符串，定义了工作流的节点和边 |
+| inputs | object | 否 | 工作流的初始输入参数，用于验证输入是否符合 schema 要求 |
+
+### 返回值说明
+
+TaskValidate API 返回一个 `TaskValidateOutput` 对象：
+
+| 字段名 | 类型 | 描述 |
+| ------ | ---- | ---- |
+| valid | boolean | 表示验证是否通过，true 表示验证成功，false 表示验证失败 |
+| errors | string[] | 可选字段，当验证失败时包含具体的错误信息列表 |
+
+### 验证内容
+
+TaskValidate API 会对以下内容进行验证：
+
+- **Schema 结构验证**：检查 schema 是否符合 WorkflowSchema 的格式要求
+- **节点类型验证**：验证 schema 中的节点类型是否被支持
+- **边连接验证**：检查节点之间的连接是否正确
+- **输入参数验证**：验证提供的 inputs 是否符合 schema 中定义的输入要求
+- **工作流完整性验证**：检查工作流是否包含必要的起始和结束节点
+
+### 错误处理
+
+TaskValidate API 可能会返回以下类型的验证错误：
+
+- **Schema 解析错误**：当提供的 schema 不是有效的 JSON 字符串时
+- **Schema 结构错误**：当 schema 结构不符合预期格式时
+- **节点配置错误**：当节点配置不完整或不正确时
+- **连接错误**：当节点之间的连接存在问题时
+- **输入参数错误**：当输入参数不符合要求时
+
+### 使用示例
+
+```javascript
+import { TaskValidateAPI } from '@flowgram.ai/runtime-js';
+
+const schema = JSON.stringify({
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      meta: { position: { x: 0, y: 0 } },
+      data: {
+        outputs: {
+          type: 'object',
+          properties: {
+            userInput: {
+              key: 14,
+              name: 'userInput',
+              isPropertyRequired: true,
+              type: 'string',
+              extra: {
+                index: 0,
+              },
+            }
+          },
+          required: ['userInput'],
+        },
+      }
+    },
+    {
+      id: 'llm',
+      type: 'llm',
+      meta: { position: { x: 200, y: 0 } },
+      data: {
+        title: 'LLM_0',
+        inputsValues: {
+          prompt: {
+            type: 'ref',
+            content: ['start_0', 'userInput'],
+          }
+        },
+        inputs: {
+          type: 'object',
+          required: ['editor'],
+          properties: {
+            prompt: {
+              type: 'string',
+              extra: {
+                formComponent: 'prompt-editor',
+              },
+            },
+          },
+        },
+        outputs: {
+          type: 'object',
+          properties: {
+            result: {
+              type: 'string',
+            },
+          },
+        },
+      },
+    },
+    {
+      id: 'end',
+      type: 'end',
+      meta: { position: { x: 400, y: 0 } },
+      data: {}
+    }
+  ],
+  edges: [
+    {
+      sourceNodeID: 'start',
+      sourcePort: 'out',
+      targetNodeID: 'llm',
+      targetPort: 'in'
+    },
+    {
+      sourceNodeID: 'llm',
+      sourcePort: 'out',
+      targetNodeID: 'end',
+      targetPort: 'in'
+    }
+  ]
+});
+
+const inputs = {
+  userInput: '请介绍一下自己'
+};
+
+async function validateWorkflow() {
+  try {
+    const result = await TaskValidateAPI({
+      schema,
+      inputs
+    });
+
+    if (result.valid) {
+      console.log('工作流验证通过，可以安全运行');
+      return true;
+    } else {
+      console.error('工作流验证失败:');
+      result.errors?.forEach(error => {
+        console.error('- ' + error);
+      });
+      return false;
+    }
+  } catch (error) {
+    console.error('验证过程中发生错误:', error);
+    return false;
+  }
+}
+
+// 在运行工作流之前先进行验证
+async function safeRunWorkflow() {
+  const isValid = await validateWorkflow();
+  if (isValid) {
+    // 验证通过后再运行工作流
+    const runResult = await TaskRunAPI({ schema, inputs });
+    console.log('工作流已启动，任务 ID:', runResult.taskID);
+  } else {
+    console.log('工作流验证失败，请修复错误后重试');
+  }
+}
+```
+
+### 注意事项
+
+- 建议在调用 TaskRun API 之前先调用 TaskValidate API 进行验证
+- 验证通过并不保证工作流运行时不会出错，但可以提前发现大部分配置问题
+- TaskValidate API 的执行速度通常比 TaskRun API 快，适合用于实时验证
+- 验证结果中的错误信息可以帮助快速定位和修复问题

apps/docs/src/zh/guide/runtime/source-code-guide.mdx

@@ -83,8 +83,8 @@ js-core 模块是 FlowGram Runtime 的核心，实现了工作流引擎的主要
 
 应用层负责协调领域对象，实现系统的用例。主要文件：
 
-- `application/workflow.ts`: 工作流应用服务，实现工作流的执行、取消、查询等功能
-- `application/api.ts`: API 实现，包括 TaskRun、TaskResult、TaskReport、TaskCancel 等
+- `application/workflow.ts`: 工作流应用服务，实现工作流的验证、执行、取消、查询等功能
+- `application/api.ts`: API 实现，包括 TaskValidate、TaskRun、TaskResult、TaskReport、TaskCancel 等
 
 #### 领域层 (domain)