企业官网建设流程全解析

coze-studio 调试 Mock 数据共享库：@coze-studio/mockset-shared 包解析与实战指南

【免费下载链接】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/mockset-shared是 coze-studio 前端 monorepo 中负责"Mock 数据集（mockset）"共享逻辑的核心包，为 Agent、工作流（Workflow）与工具（Tool）调试场景下的 Mock 数据编辑提供统一的数据模型、常量约定与 schema 转换工具函数。本文以 frontend/packages/studio/mockset-shared/README.md 为骨架，结合包内源码与其在编辑器组件中的实际消费方式，完整讲解该包的工程化特性、命令用法、公共 API 设计以及从 JSON Schema 到可编辑 Mock 数据结构的核心转换原理，帮助读者在 coze-studio 中快速定位、使用并扩展这一共享工具箱。

一、包定位：调试 Mock 数据编辑的共享地基

在 coze-studio 的调试体系里，开发者需要在调用插件、工具或执行工作流时，为请求参数或返回结果构造一组"Mock 数据"。这些数据通常来源于后端下发的 JSON Schema 与 Mock 规则，而前端需要一个统一的结构来描述"字段名、真实值、展示值、类型、必填与否、增删状态、子节点"，并提供在 Schema 结构与可编辑结构之间互相转换的能力。

mockset-shared正是承担这一职责的共享包。它的 package.json 声明为@coze-studio/mockset-shared（版本 0.0.1，Apache-2.0 许可），描述为 "mockset shared"，main直接指向src/index.ts。包内依赖聚焦于三块：

• @coze-arch/bot-api：提供MockRule、BizCtx、MockSet、ComponentSubject、TrafficScene等调试域类型；
• @coze-arch/bot-semi：提供 Select 组件的OptionProps、optionRenderProps类型，支撑下拉选择 Mock 集的场景；
• json-schema与classnames：分别用于 JSON Schema 类型定义与类名拼接。

从仓库结构看，该包被同目录下的多个 mockset 相关包直接消费：mockset-editor、mockset-edit-modal-adapter、mockset-editor-adapter 都在各自的 package.json 中声明了对@coze-studio/mockset-shared的 workspace 依赖。这印证了它的定位：只沉淀纯逻辑与类型，不渲染任何 UI，让编辑弹窗、编辑器适配层等消费方各自复用同一套转换与校验能力。

二、工程化特性：模板化的 TypeScript 包基础

README 的 Features 一节列明了这个包所遵循的工程基线：

• eslint & ts：全量 TypeScript 代码，配合统一 ESLint 规则集；
• esm bundle：面向现代打包器输出 ES Module；
• umd bundle：面向<script>直引等场景输出 UMD；
• storybook：以 Storybook 作为组件开发与演示环境。

README 开头有一句 "Project template for react component with storybook"，说明该包沿用了 coze-studio 前端仓库"React 组件 + Storybook"项目模板的规范。需要说明的是，就当前仓库的实际配置而言，这些特性体现为配套的工程文件：

• tsconfig.json 采用composite: true的 project references 结构，分别引用tsconfig.build.json与tsconfig.misc.json，契合 Rush 增量构建对可组合编译的要求；
• vitest.config.ts 直接复用@coze-arch/vitest-config的defineConfig，并指定preset: 'web'，说明测试基建统一收口到仓库共享配置；
• config/rush-project.json 为 Rush 声明了test:cov（产物coverage）与ts-check（产物dist）两个操作的输出目录，便于缓存与产物管理；
• src/typings.d.ts 引用@coze-arch/bot-typings，为构建期注入IS_PROD、IS_OVERSEA、IS_RELEASE_VERSION等全局环境常量类型。

同时，从当前 package.json 的实际 scripts 看，build目前是exit 0的占位实现，lint为eslint ./ --cache，test为vitest --run --passWithNoTests，test:cov在其基础上叠加覆盖率输出。这说明该包当前侧重"类型与纯函数共享"，真正的构建打包环节留待后续按需开启（esm/umd 输出能力由模板与仓库构建体系承载）。

三、命令速查：初始化、开发与构建

README 的 Commands 一节给出了三类最常用命令，结合包内实际脚本，整理如下：

在 coze-studio 的 monorepo 中，包内所有 workspace 依赖（如@coze-arch/bot-api: workspace:*）都由根目录 rush.json 统一编排，因此首次进入仓库时建议按 README 执行rush update，之后即可在包目录内执行上述 npm scripts。

四、公共 API 一览：类型、常量与函数三驾马车

包的对外出口全部集中在 src/index.ts，共导出三大类内容：

4.1 数据模型与状态枚举（src/types/index.ts）

• MockDataValueType：字段值类型枚举，含STRING、INTEGER、NUMBER、OBJECT、ARRAY、BOOLEAN六种，与 JSON Schema 的 type 取值一一对应；
• MockDataStatus：字段编辑状态枚举，含DEFAULT（默认）、REMOVED（已删除）、ADDED（新增）三种，用于支撑"对比/回显"场景下的增删标记；
• MockDataWithStatus：带状态的可编辑树节点，字段包括key（唯一键）、label（字段名）、realValue（真实值）、displayValue（展示用值）、description、isRequired、type、childrenType（数组元素类型）、status、children（递归子节点）；
• MockDataInfo：一次 Mock 数据编辑会话的输入载体，包含schema（JSON Schema 字符串）、mock（MockRule规则）、mergedResultExample（合并后的结果示例）与incompatible（是否不兼容）标记。

4.2 业务上下文类型（src/types/interface.ts）

• BizCtxInfo：继承BizCtx并放宽ext字段，允许携带mockSubjectInfo等扩展信息；
• BindSubjectInfo：ComponentSubject与detail（含name）的组合，表示被绑定的调试主体；
• BasicMockSetInfo：bindSubjectInfo+bizCtx的最小组合；
• MockSetSelectProps/MockSelectOptionProps/MockSelectRenderOptionProps：面向"选择 Mock 集"下拉组件的 props 与选项类型，直接对接@coze-arch/bot-semi的 Select 类型；
• MockSetStatus：Mock 集状态枚举，Incompatible/Normal。

4.3 常量约定（src/constants/index.ts）

• FORMAT_SPACE_SETTING = 4：JSON 格式化缩进为 4 个空格；
• MAX_SUBMIT_LENGTH = 102400：Mock 数据提交长度上限（约 100KB）；
• RANDOM_BOOL_THRESHOLD = 0.5、RANDOM_SEQUENCE_LENGTH = 10：随机布尔阈值与随机序列长度，可推断用于"随机生成 Mock 值"的策略参数；
• STRING_DISPLAY_PREFIX = '"'、STRING_DISPLAY_SUFFIX = '"'：字符串类型值的展示前后缀（双引号包裹），便于用户在编辑界面直观区分字符串与裸文本；
• ROOT_KEY = 'mock'：根节点键名约定；
• MOCK_SET_ERR_CODE.REPEAT_NAME = 600303100：Mock 集重名时的后端错误码约定。

五、核心转换管线：Schema → DataWithStatus → Object

README 虽未展开实现细节，但包的价值核心正落在 src/utils/index.ts 的转换管线上。整条链路可以概括为三步：

5.1 解析工具 Schema：parseToolSchema

export function parseToolSchema(str: string) { return safeJSONParse<JSONSchema7>(str); }

它基于内部safeJSONParse对字符串做容错解析，解析失败时返回undefined（或调用方提供的兜底回调），避免非法 Schema 字符串导致编辑器崩溃。调用方拿到JSONSchema7后即可驱动后续的树构建。

5.2 从 Schema 生成可编辑树：transSchema2DataWithStatus

transSchema2DataWithStatus 是整条管线的核心，其行为要点如下：

• 通过getSchemaType提取schema.type（数组类型取首元素，null归一为undefined），无类型或无法识别时直接返回undefined，保证无效节点被跳过；
• 每个节点生成MockDataWithStatus，初始状态一律置为ADDED，isRequired依据schema.required数组判定，key在传入keyPrefix时按${keyPrefix}-${label}拼接以保证子树键全局唯一；
• OBJECT 节点：遍历schema.properties，递归为每个属性生成子节点，并向下传递required与keyPrefix；
• ARRAY 节点：读取schema.items（兼容items为数组的写法，取首项作为元素 schema），记录childrenType，并用getArrayItemKey(0)（即item_0）生成首元素子节点作为"模板元素"。

该函数支持注入generateFn自定义叶子节点的初始值生成策略；默认使用getInitialValue，即布尔取false、数字取0、字符串取''。这种"由 Schema 推导出可编辑树"的方式，让编辑器打开时就能立刻呈现完整字段结构，开发者只需修改需要变更的值。

5.3 从编辑树还原提交对象：transDataWithStatus2Object

transDataWithStatus2Object 与 5.2 互为逆过程，将带状态的树重新折叠为普通对象：

• REMOVED节点直接返回{}，即从提交结果中剔除；
• ARRAY 节点将子节点逐个还原，并按item_0的映射关系取出真实值后push进数组，值为undefined的元素被跳过；
• OBJECT 节点将子节点的还原结果逐层展开合并；
• 叶子节点则输出{ [label]: realValue }。

从实现看，函数签名中的excludeRemovedItem参数目前未被实际使用，REMOVED状态无论如何都会被过滤，这一点可供后续调用方注意。通过这对互逆函数，编辑器既能"打开即填充"，也能"提交即还原"，保证了 Mock 数据编辑前后数据形态的一致性。

5.4 值生成与展示：getMockValue

getMockValue 接受类型与三个取值回调（getStringValue/getNumberValue/getBooleanValue），返回[真实值, 展示值]二元组：字符串展示值会用STRING_DISPLAY_PREFIX/SUFFIX（双引号）包裹，布尔与数字直接以字符串形式展示。随机生成场景可注入随机函数（对应常量RANDOM_BOOL_THRESHOLD、RANDOM_SEQUENCE_LENGTH的用途方向），默认场景则注入固定初始值。

5.5 辅助能力

• stringifyEditorContent：以FORMAT_SPACE_SETTING（4 空格）缩进序列化编辑器内容；
• calcStringSize：基于Blob计算字符串字节大小，可用于提交前校验MAX_SUBMIT_LENGTH上限；
• getPluginInfo/getMockSubjectInfo：根据bizCtx.trafficScene分派——在工作流调试（CozeWorkflowDebug）场景下，主体信息取自ext.mockSubjectInfo（JSON 字符串，经safeJSONParse解析）中的componentID/parentComponentID；在单 Agent、多 Agent 与工具调试场景下，直接使用mockSubjectInfo的componentID/parentComponentID；
• getEnvironment：根据IS_PROD、IS_OVERSEA、IS_RELEASE_VERSION三个构建期全局常量拼接环境标识，如cn-boe、cn-release、oversea-inhouse等，用于请求调试接口时携带环境信息。

六、消费方视角：编辑器如何复用共享包

以 mockset-editor 为例，其MockDataEditor组件直接import { type MockDataInfo, FORMAT_SPACE_SETTING, parseToolSchema } from '@coze-studio/mockset-shared'，并将mockInfo（含schema、mock、mergedResultExample、incompatible）作为入参，配合 Monaco 编辑器实现 JSON 编辑、格式化（editor.action.formatDocument）、粘贴拦截与校验（onValidate收集 markers）等能力。编辑器内部处理 UI 与交互，而"Schema 字符串如何解析、格式缩进用几格、数据模型长什么样"等约定全部来自共享包——这正是 mockset-shared 的价值：让编辑弹窗（mockset-edit-modal-adapter）、编辑器（mockset-editor）及其适配层复用同一份数据契约，避免三处各自维护转换逻辑导致的不一致。

七、总结与扩展建议

@coze-studio/mockset-shared是一个典型的"纯共享逻辑包"：README 虽简短，但包内的类型体系（MockDataWithStatus状态树）、常量约定（提交上限、缩进、错误码、根键）与转换管线（parseToolSchema→transSchema2DataWithStatus→ 编辑 →transDataWithStatus2Object）共同支撑了 coze-studio 调试场景下 Mock 数据从 Schema 到可编辑树、再到提交对象的完整闭环。

对于希望深入该模块的读者，建议按以下顺序阅读仓库代码：

1. 包入口 src/index.ts：掌握全部对外 API；
2. 类型定义 与 业务接口：理解数据结构契约；
3. 转换工具 src/utils/index.ts：吃透 schema 与可编辑树的互转细节；
4. mockset-editor 编辑器：观察共享包在真实 UI 中的接入方式。

如需扩展新能力（例如支持新的 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