SuperAPI AI 工具集

add-composite-type

通用与其它

查看项目

更新于 10-15 22:38

技能介绍

用途:这是为 Forman Schema 项目新增一种 Composite Type(复合类型)的开发者指南。复合类型指可用多个更基础字段组合出来的结构,例如 udtspec 包装了一个数组结构,包含 name、label、help、type 等字段。

主要能力与要求:复合类型定义在 src/composites 目录。每个复合类型需要支持三种能力:FormanSchema 到 JSON Schema 的转换、JSON Schema 到 FormanSchema 的反向转换,以及 FormanSchema 的校验。开发者需先掌握该复合类型所展开的原始字段结构,然后按展开后的顶层类型加入转换映射表,并在类型级 switch 中处理。

实现方式:在 src/composites/${compositeType}.ts 中导出四个函数:${compositeType}Expand(把复合字段变形为展开的原始结构,修改 field 定义并返回)、${compositeType}ExtractInner(从转换后的 JSON Schema 中取出内部结构片段存入 $defs,不含字段级 title/description)、${compositeType}WrapRef(构造引用 $defs 的每次使用包装,携带 title/description/default)、${compositeType}Collapse(把展开字段反向还原为复合结构)。随后在 src/forman.ts 的 compositeHandlers 中注册:mytype: { expand: mytypeExpand, extractInner: mytypeExtractInner, wrapRef: mytypeWrapRef }。

递归与校验:$defs 只存内部片段,title/description 保留在每处包装上;首次遇到时登记占位、展开、转换并抽取内部,之后仅返回包装。只有实际用到时才惰性写入 $defs。校验无需递归保护,按数据深度递归即可终止。反向转换时检查 x-composite 是否等于目标类型,若是则还原且不再展开。最后需在 test/composites 下按现有结构补充转换与校验测试。