SuperAPI AI 工具集

distilled-sdk

编程与开发

查看项目

更新于 11-07 16:07

技能介绍

用途

distilled-sdk 描述了一套为 API 提供商构建或更新 distilled SDK 的流水线。起点是上游 API 描述(URL、git 仓库、GraphQL 端点、文档等),终点是提交到仓库的 Effect SDK TypeScript 服务代码。

流水线结构

上游 API 描述 → 由 stacks/distilled-submodules/spec-repos/<pkg>/fetch-specs.ts 抓取,写入 distilled-mirror/spec-mirror-<pkg> 镜像仓库(每日重新抓取,布局为 .meta/ 机制文件加 specs/ 载荷);该镜像以 git submodule 形式挂载到 packages/<pkg>/specs/spec-mirror-<pkg>/specs/;再由 packages/<pkg>/scripts/convert.ts 将规格方言转换为 Smithy 2.0 模型,输出到 .generated-specs/.json(提交);最后 packages/<pkg>/scripts/generate.ts 将 Smithy 编译为 Effect SDK 源码 packages/<pkg>/src/services/.ts(提交)。

由此有两点约束:生成产物需提交,CI 不运行 generate、也不检出子模块;镜像才是规格来源,包不直接子模块化上游仓库(例如 github/rest-api-description 检出一份 13 MB 文件需 6.7 GB,镜像只保留该文件)。

主要步骤

  1. 识别上游形态:没有通用抓取脚本,需复制最接近的现有实现并调整。对应关系包括:稳定 URL 的单个 OpenAPI 文档(spec-repos/hetzner,fetch→校验→写入)、活端点提供 YAML(spec-repos/posthog,fetch→YAML 解析→写 JSON)、大 git 仓库中少量文件(spec-repos/github、spec-repos/turso,按文件走 raw.githubusercontent.com,不克隆)、巨型仓库中的整个目录(spec-repos/aws、spec-repos/azure,使用 --filter=blob:none 与 --no-checkout 克隆并窄化 sparse 模式后再取 blob)、枚举多文档的索引(spec-repos/gcp,爬取 discovery 目录并写 _manifest.json 与逐条文档)、GraphQL 端点(spec-repos/railway、spec-repos/expo-eas,introspection 查询得 schema.json)、仅有人工文档(暂无实现,需先确认是否有机器可读描述;packages/cloudflare 是反面案例)。fetch-specs.ts 须从 .meta/ 运行、只写 ../specs/;写入前校验(如 typeof spec.openapi === "string" && spec.paths !== undefined);确定性输出 JSON.stringify(spec, null, 2) + "\n";只抓生成器读取的子集。

  2. 添加镜像:创建 spec-repos/<pkg> 目录(含 fetch-specs.ts、package.json、readme.md),并在 SpecRepos.ts 的 SPEC_REPOS 中按字母顺序加入 { package: "<pkg>" }。镜像仓库由 distilled-submodules 堆栈在合并到 main 时创建。

  3. 本地物化镜像:pnpm specs:local <pkg>,将同一脚手架复制到 packages/<pkg>/specs/.local/ 并运行 fetch-specs.ts,结果与真实镜像检出逐字节一致;该目录被 gitignore。

  4. 编写包:从最接近的现有包复制,在 convert.ts 用 resolveSpecPath 声明生产规格路径(OpenAPI 包在 runOpenApiConvert 中自动处理),并在根 tsconfig.json 加入两个 tsconfig 引用。

  5. 迭代:DISTILLED_SPECS_LOCAL=1 pnpm generate <pkg>,把规格读取重定向到 .local,并在 stderr 警告。可先 pnpm --filter @distilled.cloud/<pkg> run convert 停在 Smithy 模型阶段排查问题。补丁以 RFC-6902 *.json 放在 packages/<pkg>/patches/,在 convert 的 finalizeConvert 阶段应用;OpenAPI 指针(/paths、/components)在转换前作用于规格,Smithy 指针(/shapes、/metadata)在转换后作用于模型。finalizeConvert 非幂等,会以 metadata["distilled.finalized"] 标记拒绝重复运行,且目标指向不存在 shape 时会失败,过期补丁指针会使运行失败(可用 onStalePatch: "warn" 改为跳过)。操作命名属于 convert 策略而非补丁,默认 verbNoun;toVerbNoun 仅重排可识别的 id;不规则命名放入 operationNames,按 "METHOD path" 再按 operationId 查找。不要用 RFC-6902 补丁改 operationId。

  6. 接线子模块:pnpm specs:link <pkg>,入口信息由包名派生(packages/<pkg>/specs/spec-mirror-<pkg> ← https://github.com/distilled-mirror/spec-mirror-<pkg>.git)。镜像未创建前只写 .gitmodules 条目(惰性,不会被同步),镜像部署后再运行同一命令即成真实子模块。

  7. 检查:pnpm specs:check(镜像清单 ↔ spec-repos/ ↔ .gitmodules ↔ packages/)、pnpm typecheck(tsc -b)、pnpm format(生成产物以格式化形式提交)。

  8. 合并后:堆栈部署并创建 spec-mirror-<pkg>,附带 fetch 脚本与每日重抓工作流;随后再运行 pnpm specs:link <pkg> 记录 gitlink、删除 packages/<pkg>/specs/.local/,并确认 pnpm generate <pkg> 能从子模块复现提交产物。

维护现有 SDK

pnpm specs:sync(全部镜像,仅 tip 提交)、pnpm --filter @distilled.cloud/<pkg> run specs:fetch(单个)、run specs:update(移到镜像最新)、pnpm generate <pkg> [<pkg>…](convert + generate + format)、pnpm generate(全部)。这些均使用 --depth=1 且非递归;.gitmodules 每条目设 shallow = true,specs:check 会检查。

CI 规则

已提交文件不得引用 specs/.local;带 specs/ 目录的包必须有 SPEC_REPOS 条目;spec-repos/<pkg>/ 必须齐全三个文件,blocked 包则三者皆无;.gitmodules 镜像条目须符合命名约定。

已知边界

本地模式按最后一个 specs 段之后的部分重定位规格路径,因此包声明的路径须为 specs/spec-mirror-<pkg>/specs/<file>。aws 的 convert 读取 spec-mirror Smithy 模型、应用 patches/{sdkId}.json(applyAwsSpecPatches)、复制 partitions.json 并写 .generated-specs/<sdkId>.json,generate 读取补丁文件仅用于 errorCategories。cloudflare 的镜像处于 blocked,仍读取过时的仓内快照。fly-io 读取其镜像之外的 specs/sprites、specs/mpg、specs/addons 三个手工维护的小文档。