Coze Studio 工作流测试运行表单coze-workflow/test-run-formSchema 驱动表单引擎与 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/traditionalshallow构建单表单内的全局状态 Storeajv、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-engineSchema 驱动表单引擎、utils工具函数、constants内部字段名常量。对外导出的公共 API包入口 src/index.ts 将公共 API 分为五组分组导出内容说明Form EnginecreateSchemaField、useFormSchema、useForm、useCurrentFieldState、FormSchema、FormModel、IFormSchema表单引擎的 Schema 驱动核心组件TestRunFormInputJson 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的字段体系可归纳为四类① 核心属性versionSchema 版本name字段名type支持string | object | array | number | boolean | void | stringFormSchemaTypesdefaultValue默认值。源码注释特别说明JSON Schema 标准字段是default但它是 JS 关键字故此处命名为defaultValue。② 下钻属性propertiesobject类型的子字段表itemsarray类型的元素 Schema。③ UI 属性以x-前缀命名对齐 JSON Schema 扩展约定title/description标题与描述可为 ReactNodex-index字段排序号x-visible/x-hidden/x-disabled显隐与禁用x-component/x-component-props指定渲染组件及其 propsx-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-modeform | json表单/JSON 两种模式、x-origin-type字段对应的变量原始类型并留有[key: string]: any索引签名保证可扩展性。FormSchemaSchema 的运行时模型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的ReactiveStateFormSchemaUIState的响应式 UI 状态目前仅含disabledpath记录字段在 Schema 树中的路径。同时提供便捷 gettercomponentType、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入口 Providerrecursion-field.tsx递归遍历properties/items将嵌套 Schema 逐层渲染object-field.tsx渲染object类型通常组合FieldItem与GroupCollapse组织子字段reactive-field.tsx处理x-reactions等响应式联动逻辑general-field.tsx按x-component从注册表中取出组件并传入x-component-propsindex.ts统一导出。TestRunForm组件与useCreateForm组件实现test-run-form.tsx 是包的对外主组件其实现非常精简内部通过createSchemaField注册一组默认物料InputString、InputNumber、InputInteger、InputTime、InputJson、SelectBoolean、SelectVoice、FieldItem随后export const TestRunForm: React.FCTestRunFormProps ({ schema, components, onFormValuesChange, onMounted, }) { const { control, formSchema } useCreateForm(schema, { onFormValuesChange, onMounted, }); return ( Form control{control} SchemaField schema{formSchema} components{components} / /Form ); };组件 props 定义Prop类型作用schemaIFormSchema表单描述必填componentsFormSchemaReactComponents可选覆盖/追加渲染组件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/hooksuseFormSchema读取 Schema、useFieldSchema读取当前字段 Schema、useFieldUiState/useFormUiStateUI 状态、useComponents读取组件注册表配合useForm、useCurrentFieldState在自定义组件内部访问表单模型。内置表单物料Form Materials基础物料base-form-materialscomponents/base-form-materials 提供不依赖业务上下文的最小表单控件每个控件包含index.ts、tsx实现与独立 less 样式field-item字段容器标题、必填标记、校验错误展示配 field-item 测试group-collapse可折叠分组容器配 group-collapse 测试input-jsonJSON 输入导出为FormBaseInputJsoninput-number/input-string/input-time数字、文本、时间输入select-boolean布尔选择select-voice音色选择index.ts统一导出。业务物料form-materialscomponents/form-materials 是TestRunForm默认注册的物料集合与基础物料同名但面向工作流测试上下文如接入coze-workflow/components的字段组件它们是createSchemaField中components映射的默认值。表单上下文与全局状态TestRunFormProvidercontext/form.tsx 用zustand/traditionalshallow实现单表单内全局状态export interface TestRunFormState { schema: IFormSchema | null; mode: form | json; patch: (next: PartialTestRunFormState) void; getSchema: () TestRunFormState[schema]; }TestRunFormProvider在 mount 时通过useRef惰性创建一个 Store避免每次渲染重建存入 React ContextuseTestRunFormStore(selector)通过 selector 订阅 Store配合shallow做相等性比较减少不必要的重渲染状态核心是schema当前表单 Schema与modeform | json两种编辑模式patch负责局部更新。典型用法是在TestRunFormProvider内嵌套TestRunForm由外层组件通过useTestRunFormStore(s s.patch)切换表单/JSON 模式或替换 Schema。工具函数Utils与内部常量四个导出工具generateFieldgenerate-field.ts依据字段类型生成对应的 Schema 描述如从业务变量类型映射到x-componentgenerateFieldValidatorgenerate-field-validator.ts生成字段校验规则通常基于ajv或字段的required/ 类型约束isFormSchemaPropertyEmptyis-property-empty.ts判断 Schema 属性是否为空配 is-property-empty 测试stringifyFormValuesFromBackedstringify-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 --passWithNoTestsfield-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 生成与序列化。结合 源码目录 与 测试目录 深入阅读即可完整掌握其实现细节并在此基础上扩展自定义字段物料。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考