Coze Studio 工作流测试运行表单 `@coze-workflow/test-run-form`：Schema 驱动表单引擎与 TestRunForm 实战指南-平芜编程栈

Coze Studio 工作流测试运行表单`@coze-workflow/test-run-form`：Schema 驱动表单引擎与 TestRunForm 实战指南

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio

导读

本文围绕 Coze Studio 开源仓库中frontend/packages/workflow/test-run-next/form包（npm 包名@coze-workflow/test-run-form）展开，系统讲解其"工作流测试运行表单（Workflow TestRun Form）"的定位、Schema 驱动表单引擎的架构原理、TestRunForm组件的使用方式、内置表单物料与工具函数，以及配套的 Vitest 测试验证。读完本文，你将掌握如何在 Coze Studio 工作流测试场景下声明式地构造运行参数表单、接入校验规则与表单状态，并能够从源码层面理解x-component、x-validator、FormSchema、TestRunFormProvider等关键机制的实际调用关系。

包定位与仓库结构

包的职责

@coze-workflow/test-run-form是 Coze Studio 前端 monorepo（由 rush.json 管理的多包仓库）中frontend/packages/workflow下的一个工作流子包，负责为**工作流运行测试（Workflow TestRun）**提供参数输入表单。其package.json中的描述为Workflow TestRun Form，版本0.0.1，入口直接指向./src/index.ts。

从依赖关系可以看出该包的技术底座：

@flowgram-adapter/free-layout-editor：底层表单引擎，提供Form、FormModel、createForm、useForm、useCurrentFieldState等核心能力；
zustand：通过zustand/traditional+shallow构建单表单内的全局状态 Store；
ajv、bignumber.js：字段校验与数值精度处理；
@coze-workflow/base、@coze-workflow/components、@coze-workflow/test-run-shared：同仓库内的工作流基础能力；
@coze-arch/coze-design、@coze-arch/i18n：设计体系与国际化；
开发工具链为 TypeScript 5.8 + Vitest 3 + ESLint（见 package.json）。

包的源码结构（目录概览）分层清晰：components（表单组件）、context（表单上下文与 Store）、form-engine（Schema 驱动表单引擎）、utils（工具函数）、constants（内部字段名常量）。

对外导出的公共 API

包入口 src/index.ts 将公共 API 分为五组：

分组	导出内容	说明
Form Engine	`createSchemaField`、`useFormSchema`、`useForm`、`useCurrentFieldState`、`FormSchema`、`FormModel`、`IFormSchema`	表单引擎的 Schema 驱动核心
组件	`TestRunForm`；`InputJson as FormBaseInputJson`、`GroupCollapse as FormBaseGroupCollapse`、`FieldItem as FormBaseFieldItem`	开箱即用的表单组件
上下文	`TestRunFormProvider`、`useTestRunFormStore`、`TestRunFormState`	单表单内的全局状态管理
工具	`generateField`、`generateFieldValidator`、`isFormSchemaPropertyEmpty`、`stringifyFormValuesFromBacked`	字段生成、校验与值序列化
常量	`TestFormFieldName`	内部固定字段名枚举

安装与接入（Getting Started）

安装

将该包加入依赖并在仓库根目录执行依赖更新：

{ "dependencies": { "@coze-workflow/test-run-form": "workspace:*" } }

rush update

由于包的主入口直接指向 TypeScript 源码（"main": "./src/index.ts"），且在 monorepo 内以workspace:*协议引用，它通常作为工作流模块内部包被其他@coze-workflow/*包消费。

基础用法

README 中给出了通用导入骨架：

import { /* exported functions/components */ } from '@coze-workflow/test-run-form'; // Example usage

结合 test-run-form.tsx 的实现，最小可用示例为：向TestRunForm传入一份IFormSchema描述，表单引擎便依据 Schema 递归渲染出对应输入控件：

import { TestRunForm } from '@coze-workflow/test-run-form'; const schema = { type: 'object', properties: { query: { type: 'string', title: '查询文本', 'x-component': 'InputString', required: true, }, top_k: { type: 'number', title: '返回条数', 'x-component': 'InputNumber', defaultValue: 5, }, }, }; export const MyTestPanel = () => ( <TestRunForm schema={schema} onFormValuesChange={payload => console.log('values changed:', payload)} onMounted={(formModel, formSchema) => console.log('mounted', formModel, formSchema)} /> );

Schema 驱动表单引擎（Form Engine）

设计思想：用`IFormSchema`描述一切

该包没有为每个业务场景手写表单，而是抽象出一套JSON Schema 风格的声明式表单协议。字段类型、顺序、显隐、禁用、校验规则、渲染组件与装饰器全部收敛在IFormSchema中，核心定义见 form-engine/types/schema.ts。

IFormSchema的字段体系可归纳为四类：

① 核心属性

version：Schema 版本；
name：字段名；
type：支持'string' | 'object' | 'array' | 'number' | 'boolean' | 'void' | string（FormSchemaTypes）；
defaultValue：默认值。源码注释特别说明：JSON Schema 标准字段是default，但它是 JS 关键字，故此处命名为defaultValue。

② 下钻属性

properties：object类型的子字段表；
items：array类型的元素 Schema。

③ UI 属性（以x-前缀命名，对齐 JSON Schema 扩展约定）

title/description：标题与描述（可为 ReactNode）；
x-index：字段排序号；
x-visible/x-hidden/x-disabled：显隐与禁用；
x-component/x-component-props：指定渲染组件及其 props；
x-decorator/x-decorator-props：指定装饰器（如FieldItem包裹层）及其 props。

④ 合法性属性

required：是否必填；
x-validator：字段级校验函数，类型为@flowgram-adapter/free-layout-editor的Validate。

此外还包含扩展能力字段：x-reactions（联动）、x-content（自定义内容）、patternProperties/additionalProperties/additionalItems（通配与兜底字段），以及业务自定义字段x-node-id（节点 ID）、x-node-type（节点类型）、x-form-mode（'form' | 'json'，表单/JSON 两种模式）、x-origin-type（字段对应的变量原始类型），并留有[key: string]: any索引签名保证可扩展性。

`FormSchema`：Schema 的运行时模型

form-engine/shared/form-schema.ts 中的FormSchema类是IFormSchema的运行时实现，承担两类职责：

透传 JSON 字段：type、title、description、required、properties、defaultValue原样保留；fromJSON()将原始 JSON 灌入实例，并把x-disabled同步到 UI 状态（this.uiState.value.disabled = json['x-disabled'] ?? false）。
模型属性：uiState是基于@flowgram-adapter/common的ReactiveState<FormSchemaUIState>的响应式 UI 状态（目前仅含disabled），path记录字段在 Schema 树中的路径。

同时提供便捷 getter（componentType、componentProps、decoratorType、decoratorProps）和静态方法getProperties()：该方法依据x-index对properties进行稳定排序——带x-index的字段放入有序数组对应下标，其余字段按声明顺序追加其后，从而保证渲染顺序可控。

`createSchemaField`与组件注册

create-schema-field.tsx 导出的createSchemaField(options)是引擎的"组件注入点"：它接收一组默认组件映射，返回一个SchemaField的 React 组件工厂。渲染时把options.components与调用方传入的components合并（后者优先），实现"引擎内置 + 业务覆盖"的组合模式。

SchemaField本身（schema-field.tsx）是纯 Provider 组件：将components放入ComponentsContext、把schema放入FormSchemaContext，然后交给RecursionField递归渲染。

递归渲染与字段类型分发

form-engine/fields 目录下共有五类字段组件，构成 Schema 树的渲染分发逻辑：

schema-field.tsx：入口 Provider；
recursion-field.tsx：递归遍历properties/items，将嵌套 Schema 逐层渲染；
object-field.tsx：渲染object类型，通常组合FieldItem与GroupCollapse组织子字段；
reactive-field.tsx：处理x-reactions等响应式联动逻辑；
general-field.tsx：按x-component从注册表中取出组件并传入x-component-props；
index.ts：统一导出。

`TestRunForm`组件与`useCreateForm`

组件实现

test-run-form.tsx 是包的对外主组件，其实现非常精简：内部通过createSchemaField注册一组默认物料（InputString、InputNumber、InputInteger、InputTime、InputJson、SelectBoolean、SelectVoice、FieldItem），随后：

export const TestRunForm: React.FC<TestRunFormProps> = ({ schema, components, onFormValuesChange, onMounted, }) => { const { control, formSchema } = useCreateForm(schema, { onFormValuesChange, onMounted, }); return ( <Form control={control}> <SchemaField schema={formSchema} components={components} /> </Form> ); };

组件 props 定义：

Prop	类型	作用
`schema`	`IFormSchema`	表单描述（必填）
`components`	`FormSchemaReactComponents`	可选，覆盖/追加渲染组件
`onFormValuesChange`	`(payload: any) => void`	表单值变化回调
`onMounted`	`(formModel: FormModel, schema: FormSchema) => void`	表单挂载完成回调，可拿到底层模型

`useCreateForm`：表单实例的创建与生命周期

use-create-form.ts 完成三件事：

校验规则解析：validateResolver(schema)深度遍历 Schema 树，凡带x-validator的字段，以点分路径（如a.b）为 key 收集进rules；外部传入的options.validate再合并覆盖（{...validateResolver(schema), ...validate}）。所有规则会注入createForm({ validate, validateTrigger: ValidateTrigger.onBlur })，即失焦触发校验。
表单实例创建：调用@flowgram-adapter/free-layout-editor的createForm生成form与control，并将 Schema 包装为new FormSchema({ type: 'object', ...schema })（顶层强制为object）。
生命周期接线：onMounted在 mount 时收到control._formModel与formSchema；同时订阅formModel.onFormValuesUpdated，值变化即回调onFormValuesChange，并在卸载时dispose订阅。

其余引擎 hooks 位于 form-engine/hooks：useFormSchema（读取 Schema）、useFieldSchema（读取当前字段 Schema）、useFieldUiState/useFormUiState（UI 状态）、useComponents（读取组件注册表），配合useForm、useCurrentFieldState在自定义组件内部访问表单模型。

内置表单物料（Form Materials）

基础物料：base-form-materials

components/base-form-materials 提供不依赖业务上下文的最小表单控件，每个控件包含index.ts、tsx实现与独立 less 样式：

field-item：字段容器（标题、必填标记、校验错误展示），配 field-item 测试；
group-collapse：可折叠分组容器，配 group-collapse 测试；
input-json：JSON 输入（导出为FormBaseInputJson）；
input-number/input-string/input-time：数字、文本、时间输入；
select-boolean：布尔选择；select-voice：音色选择；
index.ts：统一导出。

业务物料：form-materials

components/form-materials 是TestRunForm默认注册的物料集合，与基础物料同名但面向工作流测试上下文（如接入@coze-workflow/components的字段组件），它们是createSchemaField中components映射的默认值。

表单上下文与全局状态：`TestRunFormProvider`

context/form.tsx 用zustand/traditional+shallow实现"单表单内全局状态"：

export interface TestRunFormState { schema: IFormSchema | null; mode: 'form' | 'json'; patch: (next: Partial<TestRunFormState>) => void; getSchema: () => TestRunFormState['schema']; }

TestRunFormProvider在 mount 时通过useRef惰性创建一个 Store（避免每次渲染重建），存入 React Context；
useTestRunFormStore(selector)通过 selector 订阅 Store，配合shallow做相等性比较，减少不必要的重渲染；
状态核心是schema（当前表单 Schema）与mode（'form' | 'json'两种编辑模式），patch负责局部更新。

典型用法是：在TestRunFormProvider内嵌套TestRunForm，由外层组件通过useTestRunFormStore(s => s.patch)切换表单/JSON 模式或替换 Schema。

工具函数（Utils）与内部常量

四个导出工具

generateField（generate-field.ts）：依据字段类型生成对应的 Schema 描述（如从业务变量类型映射到x-component）；
generateFieldValidator（generate-field-validator.ts）：生成字段校验规则，通常基于ajv或字段的required/ 类型约束；
isFormSchemaPropertyEmpty（is-property-empty.ts）：判断 Schema 属性是否为空，配 is-property-empty 测试；
stringifyFormValuesFromBacked（stringify-form-values-from-backed.ts）：将后端返回的表单值序列化为表单可用的字符串/JSON 形态，配 stringify-form-values-from-backed 测试。

`TestFormFieldName`内部字段名

constants/index.ts 定义了表单内部保留字段名的枚举，用于区分普通业务字段与框架注入的特殊字段：

export enum TestFormFieldName { Node = '_node', // 节点 Batch = '_batch', // 批量 Input = '_input', // 输入 Setting = '_setting', // 设置 JSON = '_json', // JSON 模式 Related = '_related', // 关联内容 Bot = '_bot', // Bot Conversation = '_conversation', // 会话 TestsetSelect = '_testset_select', // 测试集选择 TestsetSave = '_testset_save', // 测试集保存 }

这些_前缀字段名在生成 Schema 时被统一管理，避免与用户业务字段名冲突。

测试验证

包的测试集中在tests目录，vitest.config.ts与setup.tsx（注入@testing-library/jest-dom）提供测试环境，package.json中test脚本为vitest run --passWithNoTests：

field-item.test.tsx 与 group-collapse.test.tsx：验证字段容器与折叠分组的渲染与交互；
is-property-empty.test.ts：覆盖空 Schema / 空 properties 等边界；
stringify-form-values-from-backed.test.ts：验证后端值序列化逻辑。

这些测试既是对工具函数与基础物料的契约约束，也为后续扩展表单控件提供了可参照的测试范式。

开发与工程约束

包以 TypeScript + 现代 JavaScript 编写，使用 Vitest 进行测试、ESLint 保证代码质量（lint脚本为eslint ./ --cache）。作为 Coze Studio monorepo 的一员，其config/rush-project.json遵循统一构建配置，开发调试与贡献需遵守仓库的 monorepo 协作规范。许可协议为 Apache-2.0。

小结

@coze-workflow/test-run-form是 Coze Studio 工作流测试运行能力的"表单心脏"：它以IFormSchema声明式协议 +FormSchema运行时模型 + 递归字段渲染引擎，把工作流节点参数从"手写 UI"解放为"Schema 描述"；TestRunForm一键渲染、useCreateForm管理校验（失焦触发）与生命周期、TestRunFormProvider提供表单/JSON 双模式切换的全局状态、四个工具函数与TestFormFieldName常量支撑 Schema 生成与序列化。结合源码目录与测试目录深入阅读，即可完整掌握其实现细节并在此基础上扩展自定义字段物料。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Coze Studio 工作流测试运行表单 `@coze-workflow/test-run-form`：Schema 驱动表单引擎与 TestRunForm 实战指南