SuperAPI AI 工具集

stitch-sdk-domain-design

编程与开发

查看项目

更新于 10-16 08:48

技能介绍

用途:本技能教授 Stitch SDK 生成流水线的第二阶段——读取工具 schema,产出中间表示 domain-map.json,驱动后续代码生成。

输入:tools-manifest.json(原始 MCP 工具 schema,含 outputSchema)、ir-schema.ts(定义合法 domain-map 结构的 Zod schema)、已有的 domain-map.json(扩展时使用),以及 stitch-sdk-development 技能了解上下文。输出为含 classes 和 bindings 两部分的 domain-map.json。

设计类:每个类代表一个领域实体。关键字段包括 constructorParams(实例存储字段)、reference(identity-map 键)、parentField(从父类注入的参数)、factories(无 API 调用的本地工厂方法)、sideEffects(手写扩展方法,只声明不生成)、extensionPath(重导出模块)。IR schema 是严格的,未知键是硬校验错误;旧文档中按字段的 source-mapping 助手从未实现,身份字段由 EntityManager 依据 reference.keys、资源名解析和 id 回退填充。

设计绑定:每个 binding 将一个 MCP 工具映射到一个类方法。参数路由类型有 self、param、computed、selfArray;可选参数用 optional: true,重命名用 rename,默认值需 optional: true。方法签名中必填参数按 IR 顺序位置传入,所有可选参数归入末尾单个 options 对象。

响应投影:returns.projection 数组指引代码生成如何导航响应,每步为 ProjectionStep,含 prop、index、each、find、acknowledgeSingle;投影中每个属性在生成时对照 outputSchema 校验,贯穿数组而不带 index/each/find 会报错。对无界数组使用 index 或 find 会触发截断警告,优先用 each 加 array。returns.class 可将提取数据包装进领域类。cache 字段可检查 this.data 后再调用 API。

验证命令:bun scripts/generate-sdk.ts、npx tsc --noEmit、npx vitest run、bun scripts/e2e-test.ts、bun scripts/validate-generated.ts。