SuperAPI AI 工具集

alchemy-provider

部署与运维

查看项目

更新于 11-07 17:07

技能介绍

用途

该技能用于把一个新的 Alchemy 云提供方(位于 packages/<provider> 下、包名为 @alchemy.run/<provider>)端到端地建立起来,包括凭据、蒸馏 SDK、Alchemy 资源等;也用于把已存在的提供方提升到同一标准。其核心是一个闭环:蒸馏 SDK → Alchemy 资源 → 实时测试 → 根据错误或 schema 不符回补蒸馏补丁。实时 API 是唯一权威,资源只有在针对真实提供方的测试通过后才算完成,测试暴露的每个不匹配都要在 distilled 中修复,而不是在 alchemy 中绕过。

主要能力与要求

  • 覆盖目标是整个提供方:distilled SDK 覆盖的每个服务中的每个资源,要么实现并通过实时测试,要么在范围说明中列出并给出理由。成本不是缩小范围的理由,范围由用户缩小,而非代理自行缩小。
  • 覆盖与 API 操作一一对应:每个范围内服务中的每个操作最终必须属于资源生命周期、绑定、事件源或带理由的内部行之一。只有资源没有绑定的服务算半成品。
  • AWS 被作为标杆(205/212 个服务、2,846 个绑定服务);GCP 达 161 个服务中的 57 个、Azure 达 160 个中的 4 个,均被报告为完成。所有调用都经过 distilled;distilled 缺少操作时应修补 distilled,不得在 alchemy 中绕行。
  • 非资源交付物同样属于「整个提供方」:每个数据面操作的绑定、两种形式的运行时、事件源、云可运行代码时的工作流引擎、云托管网站时的 CDN 与函数、示例、文档中心、生成的文档;它们与资源一样在索引中占行并具有相同状态。
  • 需遵循 AGENTS.md 中的教义:包边界(每个提供方是独立工作区包,核心永不导入它,只能通过 alchemy/* 访问核心)、Reconciler 教义(observe→ensure→sync)、类型化错误教义、速度教义(有界重试、每次测试运行设超时、三次迭代预算)、绑定约定与运行时方法、文档生成(JSDoc 是唯一文档来源)、资源工厂流程。review.md 把每条规则变成带命令和预期结果的检查,应在每个波次边界和步骤 10 前运行。

使用方式

  • 对已存在的提供方:先做缺口审计——合并 origin/main 并类型检查包,运行 review.md 全部检查,移植 scripts/audit-service.ts 获取逐服务操作覆盖,重建 INDEX.md(每个缺失资源、绑定、运行时形式、事件源、工作流引擎、网站改造、示例、文档页、JSDoc 缺口各一行,外加每个需修复的评审命中),先做 distilled 工作,再从步骤 4 起按与新建提供方相同的契约运行波次,并在第一波前向用户报告审计计数与计划波次。
  • 编排:当运行环境有工作流工具(如 Claude Code 的 Workflow、Grok 的 workflow)时,将扇出工作作为工作流运行,且仅在用户要求时运行;没有工作流工具时,以分离的顶层线程启动每个代理(T3 Code 中 t3_thread_launch 配合 workspaceStrategy: "worktree"),而非 delegate_task 子代理线程。协调者按状态统计代理、读取每个失败或取消代理的错误,仅重发仍缺失的行。
  • 分支与检查点:在从 origin/main 新开的工作树的干净分支上工作,附带 distilled 子模块;第一波实时测试通过后在 alchemy 和 distilled 开草稿 PR,每个波次边界推送检查点,描述携带当前索引计数;每个检查点需 rebase、类型检查、推送并确认 PR 检查实际运行。
  • 步骤 0:先获取凭据,询问上游提供方支持的身份验证方式与最小作用域/角色、专用测试账号或项目(不得用生产)、账号标识符、已知限制;将凭据存入 Alchemy profile(alchemy profile edit --profile testing --add <Provider>),测试用 --profile <name> 选择,绝不打印密钥或写入仓库;无凭据时给出创建步骤,期间可继续目录与代码工作,并在报告中把所有实时测试标记为阻塞。
  • 步骤 1:所有提供方通过蒸馏 SDK(@distilled.cloud/<pkg>,位于 submodules/distilled/packages/<pkg>)访问 API;无 SDK 时遵循 distilled-sdk 技能;SDK 有误时遵循 distilled-sdk-patch;SDK 落后规范时遵循 distilled-sdk-update。绑定调用的数据 API 同样经 distilled 访问,AWS 是榜样(sqs.sendMessage、s3.putObject、dynamodb.getItem 均为 distilled 操作)。原始 HttpClient 调用只允许用于 API 返回的预签名/ SAS URL 或用户自己部署的端点,且需注释说明属于哪种情况。distilled 变更作为独立 PR 合入 alchemy-run/distilled,合入后将 alchemy 的子模块 pin 移到合并提交并运行 pnpm install。
  • 步骤 2:在写资源前,对 SDK 中每个服务模块做目录(processes/<Provider>/catalog/<service>.md),记录资源、props 替换规则、属性、生命周期到操作映射、绑定、可测试性和优先级;每个服务模块中的每个操作按 resource-lifecycle / binding / event-source / internal 分类。在第一波前将 scripts/audit-service.ts 移植到提供方,并在每个波次边界按服务运行。INDEX.md 每个资源和每个绑定一行,状态为 missing、implemented、tested、blocked(附确切错误)或 out-of-scope(附理由),首行记录技能版本。按资源逐项决定范围,超出范围的仅限最终用户数据 API、需要最终用户 OAuth 作用域、弃用或退役 API、计费/订阅对象、封闭测试端点、另一服务的重复项等,并记录在提供方网站概览的「Out of scope」部分。发布后改名是破坏性变更,公开名称应现在确定(服务命名空间 PascalCase、资源名为正确英文单数)。
  • 步骤 3:提供方是独立工作区包,可复制最接近的小包(packages/axiom 或 packages/hetzner);包内包含 package.json、tsconfig.json、scripts/build.ts 等文件,scripts/build.ts 从兄弟包逐字复制。

适用场景与限制

适用于 Alchemy 提供方开发与维护:新建提供方、将进行中的 PR 或 main 上的包提升到标准、按 API 操作逐项落实资源与绑定、生成文档与示例。限制与注意事项:必须遵循 AGENTS.md 与 review.md 规则,未解释的评审命中即不算完成;需专用测试账号;OpenAI 类 API 若无规范需手写模型;不得在 alchemy 中手写 HTTP 或让绑定自行获取令牌;长时间代理需控制在一小时内完成以免空闲超时;模型 API 故障可能表现为安静期,需读取工作流状态。具体费用、价格、平台兼容性等资料未提供。