关于 alchemy-provider
这是一套用于构建或审计 Alchemy 云服务商的详细技能,要求对接真实 API。它强调通过 distilled SDK 覆盖各项操作、执行实时测试,并采用分阶段实现和审查检查。
主要功能
- 01服务商缺口审计
- 02逐项覆盖 API 操作
- 03集成 distilled SDK
- 04针对真实服务商的测试
- 05分阶段实现与审查
适用场景
- 01从头构建云服务商
- 02发现服务商交付项缺失
- 03通过真实 API 验证资源
- 04在各阶段节点审查服务商改动
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ alchemy-run/ alchemy --skill alchemy-provider安装后在 Claude Code 中输入/alchemy-provider确认已加载。
附带文件docs.mdreview.md
详细介绍
构建 Alchemy provider
Provider 建立在一个飞轮之上。每转动一圈,SDK 和 provider 都会变得更加完善:
1. distilled SDK ──> 2. alchemy resources ──> 3. live tests
^ │
└──── 4. distilled patches <── wrong error / wrong schema
实时 API 是唯一权威。只有针对真实 provider 的测试通过后,资源才算完成;测试发现的每处不匹配,都必须在 distilled 中修复,而不是在 alchemy 中绕过。
目标是整个 provider。“为 X 创建一个 provider”意味着,distilled SDK 覆盖的每个服务中的每项资源,要么已实现并通过实时测试,要么根据步骤 2 中的理由列为不在范围内。少量基础资源只是第一波内容,绝不是最终交付物。成本不是缩小范围的理由:成本高的资源也必须像其他资源一样实现(运行其测试请参见步骤 6)。由用户缩小范围;Agent 不得自行缩小。
**覆盖范围与 API 按操作一一对应。**每个范围内服务中的每项操作,最终都必须且只能归入以下一类:某项资源生命周期的一部分、绑定、事件源,或附有原因的 internal 行。服务有资源却没有绑定,就只完成了一半。AWS 是标杆:其 212 个服务中,有 205 个服务包含绑定,共计 2,846 个。GCP 覆盖了 161 个服务中的 57 个,Azure 覆盖了 160 个服务中的 4 个;两者都曾被报告为已完成。每次调用都必须通过 distilled。distilled 缺少某项操作时,应修补 distilled(步骤 1);绝不要在 alchemy 中绕过它。
整个 provider 还包括非资源类交付物:每项数据平面操作都要有绑定(步骤 5);每种运行时都要提供两种形式;还要提供事件源;云服务运行代码时,还要提供工作流引擎;云服务托管网站时,还要提供部署在该云 CDN 上的网站框架(步骤 7);以及示例、文档中心和生成的文档(步骤 10)。它们与资源一样,都是同一索引中的行,也有相同的状态。不要在 Agent 合约中写“后续阶段再做”,却不添加相应的行:在 Azure,合约写着“绑定属于后续阶段——不要构建绑定”,后续阶段始终没有到来,最终交付了 1,193 项资源,却没有任何绑定、运行时、示例,文档也只覆盖了 4 个服务。
AGENTS.md 规定了本技能所依赖的原则;编写代码前请阅读以下章节,并按其要求执行:
- Package boundaries — 每个 provider 都是独立的工作区包;core 绝不导入它,且它只能通过
alchemy/*访问 core。 - Reconciler doctrine —
reconcile的 observe → ensure → sync 结构。 - Typed Error Doctrine (distilled) — alchemy 处理的每个错误都必须是 SDK 中的类型化标签。
- Speed doctrine: never wait on a hang — 有界重试;每次测试运行都要设置
timeout;最多迭代三次。 - Read/Write/ReadWrite binding convention、Runtime-only methods 和 Isolate scope vs request scope — 绑定与运行时。
- Documentation Generation — JSDoc 是唯一的文档来源。
- The Resource Factory Process — 如何将工作分配给多个 Agent。
构建 GCP provider 时这些规则就已存在,但首次审查仍在数百个文件中发现了相同的违规。仅仅阅读规则还不够:review.md 将每条规则都转化为带有命令和预期结果的检查。在每一波工作的边界处以及步骤 10 之前,都要运行该审查;存在无法解释的命中项,就说明 provider 尚未完成。
将现有提供方提升至标准
如果提供方已经存在(正在进行 PR,或软件包已在
main 上),请先进行差距审查,而不是从第 0 步开始:
- 将
origin/main合并到分支,并对软件包进行类型检查(参见 分支、检查点和 PR)。 - 按照 review.md 检查当前代码中的每一项,并移植
scripts/audit-service.ts(第 2 步)以获取各服务的操作覆盖情况。 - 根据结果重建
INDEX.md:为每个缺失的资源、绑定、 运行时形式、事件源、工作流引擎、网站改造、示例、文档页面和 JSDoc 差距各添加一行;每个需要修复的审查问题(手写 HTTP、host.bind、 容器网站)也各添加一行。只有通过 review.md 检查的现有条目才能保留其状态。 - 优先完成提炼后的工作。缺失的数据平面模块、凭据提供方和手动规范会阻塞依赖它们的绑定。
- 然后从第 4 步开始执行各轮工作,遵守与新提供方相同的约定。
在第一轮工作开始前,先向用户报告审查结果:按类别统计数量,并说明计划开展的各轮工作。
编排
扇出工作(差距审查、第 2 步的目录、实现各轮、第 8 步的修复轮次、第 9 步的审查门禁)在支持工作流的执行环境中应作为工作流运行:Claude Code 的 Workflow 工具(编写脚本前先加载其
workflow-authoring 技能)、Grok 的 workflow 工具(其 create-workflow 技能),或其他环境中的等效工具。只有用户要求时才运行工作流,因为这会消耗许多 Agent。工作流会将整轮工作作为一个脚本运行,并限制并行度、强制执行 Agent 预算,还会记录每个已完成 Agent 的结果,因此发生崩溃时,只会损失仍在运行的 Agent。如果没有工作流工具,则将每个 Agent 作为独立的顶层线程启动(在 T3 Code 中使用 t3_thread_launch 和 workspaceStrategy: "worktree"),绝不要使用 delegate_task 子 Agent 线程;协调者使用 t3_thread_read 读取每个线程的结果。无论采用哪种方式,每个 Agent 都会收到 AGENTS.md 中 每个 Agent 任务提示词必须包含的内容 所规定的任务约定,各自负责一个已提炼的服务,并返回结构化结果,供协调者更新索引状态。
长时间运行期间,协调者的职责:
- 合理安排 Agent 的工作量,确保其在一小时内完成。 资源超过约 25 个的服务应拆分为多个资源批次,由一系列 Agent 接力处理。运行数小时的 Agent 会遇到模型的空闲超时,并丢失上下文。
- 读取工作流状态,而不只是查看文件活动。 每次状态检查都要按状态统计 Agent 数量,并读取每个失败或已取消 Agent 的错误信息。模型 API 故障(
auth_unavailable、空闲超时)在文件系统看来只是静默期;在 Azure 上,这种情况曾持续三小时而未被发现。原因消除后,只重新启动状态仍为missing的条目,并要求先评估再执行。 - 如果运行时间超过一小时,定期提供状态更新,并在每次更新中附上索引统计数据。
分支、检查点和 PR
- 在从
origin/main创建的分支上使用全新的工作树,并将submodules/distilled切换到 alchemy 固定的提交,再创建你的 distilled 分支。不要从工作树当前所在的分支开始。 - 首轮通过实时测试后,在 alchemy 和 distilled 中打开草稿 PR,并在每轮结束时推送检查点。描述中应包含当前索引计数。
- 每个检查点:变基到
origin/main(distilled 变基到main所用的固定main提交),进行类型检查,推送,并确认 PR 的检查确实运行了。 存在合并冲突的 PR 不会运行pull_request工作流,因此过期的绿色检查毫无意义。main上的依赖升级(Effect、Node 类型)会导致新代码出错;请在检查点发现这些问题。 - 如果变基或拉取带来了此技能的更新版本,请在下一轮开始前重新阅读整个技能和 review.md。每新增一项交付内容,都要添加一行索引,然后完成这些条目,并使用一位新的审查者运行 review.md。
pnpm exec tsrs -b会读取 distilled 构建后的声明(lib/),而测试运行器读取其src/。应用 distilled 补丁或更新固定提交后,先重新构建该包,再进行类型检查,否则新的错误类型会被误报为类型错误。- 合并
main后,先单独对提供程序包进行类型检查(cd packages/<provider> && pnpm exec tsrs -b),然后再检查整个工作区。通常问题出在更新后的 distilled 固定提交:某个类型形状变得开放([key: string]: unknown),或错误标签被重命名。 - 使用仓库的钩子提交。如果签名或钩子卡住,请询问用户;如果用户批准跳过,请自行运行
pnpm exec oxfmt,并说明这些提交未经签名。
步骤 0 — 先获取凭据
在做任何其他事情之前,务必向用户索取上游提供程序的凭据,即使请求中没有提到测试。实时测试是整个流程的核心;没有凭据构建的提供程序未经验证。请在一条消息中准确说明所需内容:
- 提供程序支持的身份验证方式(API 令牌、服务帐户密钥、OAuth 应用、访问密钥对)以及测试资源所需的最低权限范围或角色。如果提供程序支持用于部署的 OIDC 或工作负载身份联合(GitHub Actions、云身份池),请索取相关配置,并通过
alchemy/Auth/OidcToken接入;长期有效的 API 密钥只是备用方案,不是默认方案; - 专用的测试帐户、项目或组织——绝不能使用生产环境,因为测试会创建并删除资源;
- API 所需的帐户标识符(组织 ID、项目 ID、默认区域);
- 该帐户已知的限制(套餐等级、配额、需要升级才能使用的功能),以便预先规划受限测试。
将用户提供的信息存储在 Alchemy 配置文件中,绝不要存放在仓库里:
alchemy profile edit --profile testing --add <Provider>(使用用户指定的配置文件名称)。
测试通过 --profile <name> 选择配置文件。绝不要打印密钥、将其写入受版本控制的文件,或放入 PR、提交或日志中。如果用户没有凭据,请提供创建凭据的确切步骤(控制台路径或 CLI 命令、需要授予的角色),征得用户同意后可主动在浏览器中代为操作,同时继续处理目录和代码。在收到凭据之前,请在报告中将每项实时测试标记为受阻;不要声称任何测试已完成。
步骤 1 — distilled SDK
每个提供方都通过 distilled SDK 与其 API 通信
(位于 submodules/distilled/packages/<pkg> 中的 @distilled.cloud/<pkg>)。Alchemy
绝不会使用手写的 HTTP 客户端调用 API。
- 尚无 SDK: 按照子模块中的
distilled-sdk技能指南操作 (submodules/distilled/.agents/skills/distilled-sdk/SKILL.md)。其中介绍了如何获取规范、创建镜像、转换/生成、编写 README,以及提交 distilled PR。 - SDK 已存在但有误(缺少类型化错误、字段可空性不正确、响应架构错误、密钥未标记):按照
distilled-sdk-patch技能指南操作(submodules/distilled/.agents/skills/distilled-sdk-patch/SKILL.md)。 - SDK 落后于其规范: 按照
distilled-sdk-update操作。
这也包括数据平面。 绑定会调用云服务的数据 API(写入 blob、发送消息、读取密钥),这些操作和创建资源的管理 API 一样,都要通过 distilled。AWS 就是范例:sqs.sendMessage、s3.putObject 和
dynamodb.getItem 都是 distilled 操作,AWS 绑定中没有 HTTP 代码。检查 SDK 时,也要检查数据平面的覆盖情况。如果 SDK 只覆盖管理 API,请先扩展 SDK,再编写绑定:
- 规范包含数据平面模型(Azure 的
specification/<service>/data-plane/、GCP 发现文档中的数据 API):扩展转换器以包含这些内容,并将其作为独立的服务模块(storage-queue、keyvault-secrets)。 - API 没有已发布的规范(Kudu zip 部署、仅 CLI 可用的端点):在包的
manual-specs/中手动编写模型。 - 协议并非 HTTP 形式(XML 请求体、SAS 签名、每个数据平面各自的令牌受众):将其加入 distilled 协议,而不是 alchemy。
- 凭据来自运行时的身份端点(托管身份、元数据服务器、容器凭据):将其作为 distilled 凭据提供方,例如 AWS 的
fromContainerMetadata。绑定绝不自行获取令牌。
在 Azure 中,转换器会跳过 data-plane/(scripts/convert.ts),因此 Agent 手动编写了 Storage 队列和 blob、Key Vault 密钥、Service Bus、Event Hubs、静态网站上传器的 XML 请求构造器,以及托管身份令牌缓存:共 22 处原始请求调用,没有类型化错误,也没有针对规范的测试。不要重蹈覆辙。停下来扩展 distilled。
仅以下情况允许使用原始 HttpClient 调用:
- API 返回供你原样使用的 URL(预签名或 SAS 上传 URL、签名下载 URL);
- 用户自己部署的端点(调用由该技术栈部署的 Worker、Function 或服务)。
每处调用都要附上注释,说明属于哪种情况。
如果固定的子模块提交中缺少技能文件,请从 distilled 的 main 分支读取:git -C submodules/distilled fetch origin main && git -C submodules/distilled show origin/main:.agents/skills/<skill>/SKILL.md。
distilled 的改动会作为独立 PR 合并到 alchemy-run/distilled。合并后,将 alchemy 中的子模块固定到已合并的提交(git -C submodules/distilled checkout <sha>,然后提交 gitlink),并运行 pnpm install,让工作区链接该包。
步骤 2 — 编目并确定范围
在编写资源之前,编目 SDK 中的每个服务模块
(ls submodules/distilled/packages/<pkg>/src/services);对于大型 SDK,将编目工作拆分为工作流(参见 Orchestration)。每个服务都应在该部分格式对应的 processes/<Provider>/catalog/<service>.md 中列出:资源、带替换规则的属性、特征、生命周期到操作的映射、绑定、可测试性和优先级。
processes/ 已加入 gitignore,因此编目文件是本地的顺序清单;已提交的范围记录是下方的概览页面。
每个编目文件还会列出服务模块中的每个操作,并按 scripts/audit-service.ts 对 AWS 的分类方式进行分类:
| 类别 | 含义 | 转化为 |
|---|---|---|
resource-lifecycle | 对资源本身进行创建/获取/更新/删除/列出 | 资源的 reconcile/read/delete/list |
binding | 对资源或资源内部进行数据平面操作(放入对象、发送消息、查询表、读取密钥、调用函数) | Binding.Service + <Op>Http.ts |
event-source | 资源触发运行时(通知、流、订阅) | 事件源 |
internal | 对用户代码无用(长时间运行操作的轮询、已弃用的别名) | 不转换,并说明原因 |
用户在运行时调用的读取操作(获取条目、列出对象、描述队列深度)属于绑定,即使生命周期操作也会使用它们。在第一波工作开始前,将 scripts/audit-service.ts 移植到该提供方(它会读取精简模块和包并打印差距),并在每一波工作的边界处按服务运行。
processes/<Provider>/catalog/INDEX.md 中每个资源和每个绑定各占一行,状态为 missing、implemented、tested、blocked(附确切错误)或 out-of-scope(附原因)。根据此索引安排工作波次,并重复执行,直到没有任何一行处于 missing 或 implemented 状态。每份进度报告和最终报告都要列出各状态的数量;只要任何范围内的行仍为 missing,声称“已完成”就是不实的。
INDEX.md 的第一行记录其所依据的技能版本:Skill: <sha>,取自 git log -1 --format=%H -- .agents/skills/alchemy-provider。重新阅读较新的技能后,应更新该版本。
按资源确定范围,并在提供方网站的概览页中添加一个“范围之外”章节,记录范围外列表:
- 范围内: 用户配置并拥有的基础设施(数据库、存储桶、队列、网络、密钥、函数、DNS)。
- 范围外(仅限以下有效理由):终端用户数据 API(邮件、日历、文档、视频)、需要终端用户 OAuth 权限范围的 API、已弃用或已退役的 API、账单/订阅对象、封闭 Beta 端点,以及与其他服务重复的项目。
现在就确定公开名称;发布后重命名属于破坏性变更。服务命名空间采用 PascalCase(AccessContextManager),资源名称使用正确的英文单数形式(Index,而不是 Indexe;Process,而不是 Processe)。在第一个 PR 之前,仔细检查生成的名称。
步骤 3 — 提供方包
提供方是独立的工作区包,位于 packages/<provider> 中,名称为 @alchemy.run/<provider>,并遵循 AGENTS.md 中的包边界。复制最接近的小型包:packages/axiom(令牌身份验证、扁平资源)或 packages/hetzner(标签、list、nuke 顺序、绑定、托管运行时、网站)。一个包包含:
| 文件 | 用途 |
|---|---|
package.json | 名称、共享的 alchemy 版本、发布元数据、exports/publishConfig(由下文所述的方式生成)、alchemy.contributes、依赖项 |
tsconfig.json | 复合项目;引用精简版包、distilled/core 和 ../alchemy |
scripts/build.ts | 从同级包原样复制 |
src/Contributions.ts | Contributions.make({ name, auth, … }) —— CLI、Alchemist API 和测试框架加载的内容,无需加载用户的堆栈 |
src/AuthProvider.ts | makeStoredAuthProvider 字段、CI 环境变量、<Provider>Auth 层 |
src/Credentials.ts | fromAuthProvider() = lazyCredentials<Resolved, ConfigError>()(...) → 精简版 Credentials 层 |
src/Providers.ts | ProviderCollection + providers() 层(服务提供商层、凭据、FetchHttpClient、身份验证、配置文件和凭据存储) |
src/<Provider>Bindings.ts | 绑定如何从任意主机连接到云端(步骤 5) |
src/globals.d.ts | import type {} from "alchemy/Phase";,以便 globalThis.__ALCHEMY_RUNTIME__ 通过类型检查 |
src/index.ts | 重新导出每个资源、绑定和层;export * as <Service> from "./<Service>/index.ts" |
src/Labels.ts / tags helper | 所有权标签;如果 API 支持标签,则使用此文件 |
src/Bootstrap.ts | 托管运行时的进程入口;仅当云端运行代码时需要(仅导出源码) |
README.md | npm 自述文件:简短介绍、安装命令、一段完整且通过类型检查的示例、https://alchemy.run 绝对链接 |
每次启动 CLI 时都会导入 Contributions.ts,因此其中只放置元数据和
Contributions.lazy(() => import(...), pick) 字段。始终贡献 auth;
服务提供商支持时,再添加 stateStores、cli、testServices 和
devEnv(packages/aws/src/Contributions.ts 使用了所有这些字段)。
在 package.json 中声明:
"alchemy": { "contributes": ["@alchemy.run/<provider>/Contributions"] }
切勿手动编辑 exports。添加或删除服务目录后,运行 pnpm exports:sync;CI 会运行 pnpm exports:check。其他包不得导入的模块应命名为 internal.ts,或放在 internal/ 下。依赖项:@distilled.cloud/<pkg> 和
@distilled.cloud/core 是 dependencies;alchemy 和 effect 是
peer + dev 依赖项;只有所有用户都需要的其他 @alchemy.run/* 包才作为依赖项,否则应设为可选 peer 依赖项。
在仓库枚举服务提供商的所有位置注册该包。通过搜索现有包名获取完整列表(git grep -il hetzner -- ':!packages/hetzner' ':!submodules' ':!examples');截至本文撰写时,列表如下:
package.json—build:pkg过滤器列表,以及根目录的@alchemy.run/<provider>devDependency(CLI 通过项目依赖项查找Contributions);tsconfig.json— 对该包及其精简版包的项目引用;packages/integration-tests/package.json和tsconfig.json— 该 包、其精简版包及项目引用;.github/workflows/pkg.yml—@alchemy.run[Collapsed]组;.gitignore—!packages/<provider>/src/globals.d.ts;stacks/nuke.ts—<Provider>.providers();scripts/with-fake-profiles.sh— 模拟 CI 凭据;scripts/generate-api-reference.ts和scripts/fix-api-jsdocs.ts— 该包的src根目录和服务提供商前缀;packages/integration-tests/test/Bundle/ProviderBootstraps.test.ts— 该包提供的每个Bootstrap;website/astro.config.ts、website/src/components/ProviderDirectory.astro、website/scripts/generate-llms-txt.ts和website/src/content/docs/<provider>/(index.mdx、setup.mdx)—— 侧边栏、目录卡片、llms.txt、概览和设置页面。
添加服务提供商时,Core(packages/alchemy)无需更改。如果服务提供商
似乎需要修改 Core(例如添加新的身份验证注册项、CLI 命令或状态存储),应将其作为 Contributions 字段。
区域、项目或账户等配置来自凭证/配置档案,或由用户提供的层(AWS
AWS.Region(...) 模式)。不要为此虚构环境变量;环境变量仅用于 CI 凭证,以及运行时平台自身设置的值。
如果 providers() 接入了数百个资源,请对其进行记忆化
(let cached; export const providers = () => (cached ??= make())),并将嵌套的
Layer.mergeAll 分组控制在约 90 个;未记忆化的集合会在每次调用时重建每个层,导致测试进程内存耗尽。
如果 providers() 层泄漏了 unknown 要求,pnpm lint:providers 会失败。
步骤 4 — 资源
按照 Reconciler 原则实现每个资源,将契约和提供程序放在同一个位置:packages/<provider>/src/<Service>/<Resource>.ts。以下是评审中最常见的疏漏(每项都在 review.md 中有检查项):
- 阻塞直到就绪。
reconcile只有在 API 报告资源可用后才返回:轮询长时间运行的操作直至完成,然后读取就绪状态。每个提供程序使用一个共享的操作等待器,并为每个资源设置符合实际情况的时间预算(数据库和集群需要几分钟)。就绪后的传播延迟可以接受;提前返回则不行。 - 身份变更时替换。 如果用户选择的名称或 ID 是资源身份的一部分,那么它发生变化时,
diff应返回replace;否则旧资源会泄漏。 - 缺失不等于禁止访问。 只有带类型的未找到标签才表示“已删除”。将权限错误当作未找到会使状态中移除该条目,并导致资源泄漏。如果 API 对缺失资源返回 403,请在 distilled 中针对这种情况添加专用标签。
- 列表操作应明确报错并进行分页。 吞掉错误的
list会向 nuke 报告“这里什么都没有”,并掩盖资源泄漏。使用 SDK 的分页.items(...)流。 - 所有权标记应放在标签或标记中。 如果 API 两者都不支持,请在资源 JSDoc 中记录回退标记;切勿将标记放入用户可见或会改变行为的字段中。
- 共享辅助函数在每个提供程序中只保留一份(操作等待器、未找到辅助函数、标签差异比较)。按服务复制会导致实现逐渐分歧。
- 启用账户所需的服务。 对于要求按账户启用服务的云平台(Azure 资源提供程序注册、GCP API 启用),应在
reconcile中加入幂等的启用步骤,让新账户无需手动设置即可部署。 - 创建失败后清理。 即使
olds或output的部分内容缺失,read和delete也必须能正常工作,这样下一次运行开始时的destroy才能移除崩溃运行遗留的内容。通过中断一次创建来验证。 - SQL 数据库需支持
migrations。 每个承载 SQL 架构的资源都应在部署时通过@alchemy.run/sql/Migrations应用迁移;提供程序只需编写特定于云平台的调用,并基于其执行器辅助函数(withPgExecutor、makeStatementExecutor、splitSqlScript)实现。优先使用云平台的 HTTPS 数据 API,其次使用直接连接或连接器,再其次使用网络内运行器;只有在平台没有提供凭证时,才要求提供migrationsUser/migrationsPassword。遵循AGENTS.md中的 SQL 数据库迁移要求;发布不带迁移功能的 SQL 数据库是不完整的。 - **实现
list,并筛选出由 Alchemy 管理的资源;**在删除顺序有影响时声明nuke: { dependsOn: [...] },这样alchemy unsafe nuke才能清理测试账户。
步骤 5 — 绑定和运行时
遵循 AGENTS.md 中有关绑定的章节,然后参照 AWS 和 GCP 软件包:它们是绑定如何连接到宿主的参考实现,大多数问题都能通过阅读最接近的现有绑定找到答案。以下 PR 确立了这一模式;如果代码中看不出某种情况如何处理,请阅读其描述:
| PR | 结论 |
|---|---|
| #2260 | 绑定声明所需内容;<P>Bindings 模块决定主机如何获取这些内容(packages/aws/src/AWSBindings.ts) |
| #2347 | Bind / withCredentials 是有效构造器,身份来自真实资源,并折叠 __ALCHEMY_HOST_IDENTITY__ bundle(packages/gcp/src/GCPBindings.ts) |
| #2267 | 仅部署服务在运行时保护条件后读取;本地资源上的 *Http 绑定会失败并返回类型化错误(packages/cloudflare/src/HttpBindingDev.ts) |
| #2244, #2315 | 不根据其他云提供商的主机类型分支;通过 RuntimeContext 和核心主机服务访问主机(alchemy/WebhookHost) |
覆盖目录中的每项 binding 操作。遵循 AWS 的模式:每项操作对应一个 Binding.Service(SQS.SendMessage、DynamoDB.GetItem),并各自配有一个基于精简操作构建的 <Op>Http.ts 层,该层会注入绑定资源的标识符,并且只授予对该资源执行该操作的权限。对于 API 具有明确访问级别(对象存储、键值存储)的情况,还要基于每项操作的服务,提供 AGENTS.md 中的 Read/Write/ReadWrite 服务。
最小权限取决于云平台的权限模型:
- 按操作授权(AWS IAM):对资源 ARN 授予操作所需的权限,
scripts/audit-service.ts会对此进行检查。 - 基于角色授权(GCP IAM、Azure RBAC):在资源上授予涵盖该操作的最小预定义角色,绝不授予项目或订阅级权限。如果最小预定义角色包含的权限远超该操作所需,则创建一个只包含所需权限或数据操作的自定义角色,并在各主机间复用。
每项绑定都是一次精简调用:<Op>Http.ts 层封装来自 @distilled.cloud/<pkg> 的 <service>.<operation>。如果 distilled 中没有该操作(缺少数据平面,或尚未对该操作建模),请先修补 distilled(步骤 1)。
声明每项能力时,都要定义接口和工厂:
export interface SendMessage extends Binding.Service<
SendMessage,
"AWS.SQS.SendMessage",
(queue: Queue) => Effect.Effect<(request: SendMessageRequest) => Effect.Effect<…>>
> {}
export const SendMessage = Binding.Service<SendMessage>("AWS.SQS.SendMessage");
支持任意主机。 绑定既可用于云提供商自身的计算环境,也可用于其他云:Lambda 可以绑定 GCP 主题,Cloudflare Worker 可以绑定 SQS 队列。src/<Provider>Bindings.ts 负责决策并导出:
-
HostBinding— 绑定所附加的内容:授权(IAM 语句、角色绑定、角色分配)以及env。 -
Bind— 提供一个标签模板bind。它按AGENTS.md中“联合身份优先于密钥”的顺序选择主机身份:- 对于以云平台自身身份运行的主机(
runsAsRole、runsAsServiceAccount;Azure 托管身份),授权会附加到该身份上。 - 对于由平台签发身份令牌的主机(
AWSBindings中的runsAsGoogleServiceAccount和runsOnFlyMachines;GCPBindings中的runsAsAwsRole和runsOnFlyMachines),它会创建仅限于单个工作负载的信任关系(信任令牌主体的 Role、仅对应一个角色或 App 的工作负载身份池成员),并将授权附加到该身份上。不会创建密钥。 - 只有没有平台身份的主机(Cloudflare Worker)才会使用云提供商自身的资源构建身份(AWS 上的 IAM
User+AccessKey+ 仅允许该用户承担的 Role;GCP 上的ServiceAccount+ServiceAccountKey),并通过CurrentRuntimeContext将密钥放入主机的env中。
没有主机时(脚本、计划时的
execute),它不会执行任何操作。在主机 bundle 中,它也是空操作,因此身份资源会被移除。 添加提供方或新类型的运行时前,请先检查其平台是否会签发 OIDC 令牌或签名请求,再决定是否采用密钥路径;并在每个可以信任它的云平台的<P>Bindings中添加联合分支。具有令牌的运行时会实现BaseRuntimeContext.oidcToken(audience),并在其打包器中设置__ALCHEMY_HOST_IDENTITY__。 - 对于以云平台自身身份运行的主机(
-
withCredentials(operation)— 在构建层时解析一次精简后的操作:宿主的环境身份、面向联合宿主的令牌交换(AssumeRoleWithWebIdentity、Google STS)、从RuntimeContext读取回来的绑定密钥,或部署者的凭据。 -
<identity>HostBundle— 提供方自有宿主打包器应用的 rolldown 选项(Lambda/FunctionBundle.ts、CloudFunctions/FunctionSource.ts、ImageSource.ts文件)。它会设置核心Phase.ts中声明的__ALCHEMY_HOST_IDENTITY__,从而将创建密钥的路径排除在原生包之外。
绑定层随后会读取:
Effect.gen(function* () {
const publish = yield* GCPBindings.withCredentials(pubsub.publishProjectsTopics);
const bind = yield* GCPBindings.Bind;
return Effect.fn(function* (topic: Topic) {
if (!globalThis.__ALCHEMY_RUNTIME__) {
yield* bind`GCP.PubSub.WriteTopic(${topic})`({ iam: [/* scoped to topic */] });
}
return (message) => publish({ topic: …, body: … });
});
});
参考代码遵循以下规则:
- 绝不在绑定中调用
host.bind(...),也绝不将提供方自有的宿主类型列入允许列表;这两种做法都会排除外部宿主。例外情况是仅适用于宿主的附加项,在其他场景毫无意义;这类附加项会有自己的辅助函数(AWSBindings.bindVpc、GCP.SQL.Connect中的 Cloud SQL 套接字挂载)。 - 绝不命名其他提供方的资源类型(
host.Type === "Cloudflare.Worker")。通过RuntimeContext写入环境变量(部署时使用runtime.set;运行时使用runtime.get;密钥始终保持为Redacted),其他宿主必须提供的内容则使用WebhookHost等核心宿主服务。 - 仅在部署时存在的服务(
<P>Environment.current、授权所需的账户或项目 ID)会在!globalThis.__ALCHEMY_RUNTIME__代码块中读取。在层构建时读取会导致外部宿主在初始化时崩溃。 - 针对每项服务的授权辅助函数本身也是构造器(
packages/aws/src/SQS/BindingHttp.ts中的GrantOnQueue);共享框架代码放在未导出的BindingHttp.ts中,这样每个<Op>Http.ts都只需一行Layer.effect(Cap, make…({ … }))。 - 具有本地模拟功能的提供方,如果 HTTP 绑定指向本地模拟的资源,会返回一个带类型的错误,其中注明原生绑定名称以及
Alchemy.remote()(HttpBindingUnsupportedInDev)。
如果授权范围超出绑定资源(例如,项目级授权上的条件),请在绑定的 JSDoc 中说明,并注明原因。
运行时
查找目录中的每个运行时:即运行用户代码的资源(函数、容器、服务、工作器、作业,以及运行程序的虚拟机)。在 INDEX.md 中将每个运行时标记为 runtime。每个运行时都以两种形式提供,且都来自同一个资源:
Effectful — 使用 core 的 Platform(alchemy/Platform)构建的类。main: import.meta.url 使该文件既是打包入口,也是程序本身。构造时绑定资源,返回的处理程序则会在每次请求时运行:
export default class Api extends GCP.Function<Api>()(
"Api",
{ main: import.meta.url },
Effect.gen(function* () {
const db = yield* GCP.Firestore.ReadWriteDatabase(Links);
return {
fetch: Effect.gen(function* () {
const doc = yield* db.get("links/home");
return yield* HttpServerResponse.json(doc?.fields ?? {});
}).pipe(Effect.orDie),
};
}).pipe(Effect.provide(GCP.Firestore.ReadWriteDatabaseHttp)),
) {}
Async — 将同一个资源作为普通函数调用,main 指向普通处理程序文件,且不使用 Effect。Alchemy 会按原样打包该文件,其中不包含 Effect 运行时。env 属性接受资源、Config 值和字面量;<Provider>.InferEnv<typeof Fn> 用于为处理程序的 env 参数提供类型:
// alchemy.run.ts
export const Ping = Railway.Function("Ping", {
project: Site,
main: "./src/ping.ts",
env: { DATABASE_URL: db.connectionUri },
});
export type PingEnv = Railway.InferEnv<typeof Ping>;
// src/ping.ts
import type { PingEnv } from "../alchemy.run.ts";
export default {
async fetch(_request: Request, env: PingEnv) {
return new Response(env.DATABASE_URL ? "ok" : "missing");
},
};
从与你的运行时最接近的运行时中复制这两种形式:
| 运行时 | 文件 | 说明 |
|---|---|---|
| Cloudflare Worker | packages/cloudflare/src/Workers/Worker.ts, InferEnv.ts | 完整参考实现:env 条目会成为原生绑定 |
| Railway Function | packages/railway/src/Function.ts, InferEnv.ts | 绑定是环境变量,因此 InferEnv 会映射为 string |
| GCP Cloud Run、Hetzner Service | packages/gcp/src/Run/Service.ts, packages/hetzner/src/Service.ts | 在容器或进程上使用 Platform |
| AWS Lambda | packages/aws/src/Lambda/Function.ts | 提供 async 形式,但没有 InferEnv;不要照搬这个缺失项 |
每个运行时都需要:
- 两种形式,每种形式都要有独立的 JSDoc 章节(
### Effect …和### Async …),展示堆栈声明和处理程序文件。 - 从包中导出
InferEnv,让 async 用户无需手动编写类型即可为env指定类型。 - 在资源上实现
HostBinding合约,以便来自此提供方和其他提供方的 effectful 绑定可以附加授权和环境变量。 - 在 effectful bundle 上提供 宿主 bundle 选项(
<identity>HostBundle),并为进程入口提供仅包含源代码的Bootstrap导出(packages/hetzner/src/Bootstrap.ts、packages/aws/src/Bootstrap/)。 - 为云平台用于触发运行时的事件源(队列、主题、存储事件、计划任务)提供支持,结构参照 AWS
SQS.QueueEventSource和 Cloudflare cron。其合约定义在源服务中,每个运行时都提供一个实现层。 - 当运行时是云平台提供服务器端渲染页面的方式时,提供 Website 目标(第 7 步)。
- 测试两种形式:在
test/<Provider>/<Service>/fixtures/下为每种形式各提供一个测试样例(test/Cloudflare/Images/中的effect-worker.ts和async-worker.ts是参考范例),并部署后通过 HTTP 调用。
工作流引擎
如果云平台有持久执行引擎,提供方就会在其上提供 Effect 工作流引擎,从而让 alchemy/Workflows 代码无需修改即可在那里运行。
请遵循 AGENTS.md 中的 Effect 工作流引擎:其中介绍了需要保留的 DX、两种引擎形态、共享编码模块以及八个一致性测试用例。
| 云平台 | 引擎 | 状态 |
|---|---|---|
| Cloudflare | Cloudflare.Workflows.NativeEngine(Cloudflare Workflows)、DurableObjectEngine | 已完成,进程内 |
| AWS | AWS.Lambda.WorkflowFunction + DurableFunctionEngine(Lambda 持久函数) | 已完成,主机 + 远程 |
| Azure | Durable Task Scheduler 上的 Durable Functions(已存在 Azure.DurableTask.Scheduler) | 缺失 |
| GCP | 没有面向代码的持久运行时;Cloud Workflows 是 YAML 编排器 | 构建前先在目录中决定并记录 |
在步骤 2 中研究云平台的引擎,并在目录中记录其持久步骤、持久休眠、外部事件或回调原语、运行如何中断,以及其限制。然后决定采用哪种形态:
- 进程内:适用于启动运行的运行时也能承载持久构造的情况(Cloudflare)。引擎是与工作流 Layers 并列提供的 Layer。
- 主机 + 远程:适用于运行需要专用持久运行时的情况(Lambda 持久函数,以及很可能是 Azure Durable Functions)。提供一个列出其工作流的
<Runtime>.WorkflowFunction风格主机,并提供一个将请求路由到该主机并授予访问权限的<Runtime>Engine(...hosts)Layer。
如果云平台没有持久引擎,或者只有无法运行代码步骤的引擎,则在引擎索引行中填写 out-of-scope 并说明原因。不要自行构建数据库驱动的引擎。
引擎也算作一种运行时:它需要有自己的索引行、一致性测试套件、examples/<provider>-effect-workflows 示例,以及文档中心中的 compute/effect-workflows.mdx 页面。
步骤 6 — 实时测试
测试位于 packages/integration-tests/test/<Provider>/(以下路径相对于 packages/integration-tests)。请根据 AGENTS.md 的测试章节编写测试(test.provider、在开始和结束时调用 stack.destroy()、使用确定性名称、通过 distilled 进行带外验证,并使用类型化的 wait-until-gone)。使用步骤 0 中的配置运行:
pnpm test:integration test/<Provider>/<Service>/<Resource>.test.ts --profile testing --retry 0
测试必须证明:
- 每个资源都有自己的测试文件
(
test/<Provider>/<Service>/<Resource>.test.ts)。在其他资源的测试中将某资源作为依赖部署不算,因为它自身的更新、替换和删除路径都不会运行。 - 默认运行生命周期测试。 针对真实 API 执行创建、更新,以及(如适用)替换。耗时较长的生命周期由一个提供方级标志控制,并设置符合实际情况的超时时间;受权限限制的生命周期则保留一个不受标志控制的探测测试,用于断言账户返回的那个特定类型化标签。
- 绑定在已部署的主机内运行(由 fixture Worker、Function 或容器通过 HTTP 调用绑定),以便使用主机的身份而非部署者的身份测试 IAM 授权或原生绑定。测试
Bind的两条路径:提供方自己的主机,以及在test/<Provider>/ExternalHost/CloudflareWorker.test.ts中使用所创建密钥的外部主机(复制test/GCP/ExternalHost/)。如果提供方可托管代码,也要将其主机加入其他提供方的外部主机测试套件(test/Cloudflare/ExternalHost/Lambda.test.ts是示例)。 - 每个绑定都有测试。 每个绑定各有一个
describe("<BindingName>"),并由同一个已部署的 fixture 主机驱动所有测试(test/AWS/DynamoDB/Bindings.test.ts+handler.ts是示例)。如果没有测试从主机调用某个绑定,就不算完成。 - 断言必须能够失败。 不要使用永远为真的检查,不要列出多个可接受的标签,也不要用提前
return跳过断言。 高成本资源(专用集群、大型 VM 或数据库、预留容量,以及任何按小时计费且费率显著的资源)会实现并进行完整测试,但你不会自行运行这些测试。将它们置于提供商级慢速标志后面,在索引中标记为blocked: cost,并向用户列出,同时估算单次运行的成本。只有用户同意后才运行。
稀缺的账户配额(网络、集群、IP 地址)会在测试辅助工具中通过信号量共享,或转移到使用较少的区域。套件仍在单个进程中运行:pnpm test:integration test/<Provider> --profile testing。
测试一遇到专用测试账户的前置条件,就自行解除阻碍。通过提供商 API 申请提高配额并注册预览功能(任何会增加开支的操作,都需要用户根据第 0 步或第 6 步的成本规则批准),并将新账户也需要执行的任何设置放入测试辅助工具中。使用测试框架提供的任意浏览器自动化技能,在浏览器中完成一次性控制台操作(免费试用、免费组织、注册),只在需要登录时询问用户。
只有在需要付款、供应商批准、硬件,或根据下文的长尾规则跳过时,某一项才会继续标记为 blocked;请逐项报告解除阻碍所需的确切请求。
失败路径测试应断言类型化错误,并在几分钟内结束。为它们设置较短的超时,绝不要让它们一直等待缓慢的资源配置或删除操作;单个测试用例运行一小时就是测试缺陷。
达到 AGENTS.md 中 Speed doctrine 规定的三轮预算后,或用户要求停止时,就停止追逐长尾问题。如果剩余失败与缓慢的资源配置、平台行为,或云端所需的测试基础设施(可访问的端点、自定义镜像)有关,就让当前运行完成,然后为每个失败用例添加跳过门控,并附上确切错误;在索引中将对应行标记为 blocked: skipped,并在下一份报告中列出这些行,方便用户重新开启。用户设定截止时间时,将修复测试的时间限制为一半,其余时间用于其他交付内容(绑定、运行时、网站、示例、文档、PR)。在 Azure 上,用户要求跳过一小时测试后,修复轮次仍继续运行这些测试;直到用户设定一小时的收尾期限后才停止。
第 7 步 — 框架网站
如果提供商无法托管网站,请跳过此步骤。 大多数提供商都无法托管:可观测性、支付、数据库和身份验证服务(Axiom、Stripe、Turso、PlanetScale)没有网站托管功能,因此不会提供 Website 命名空间,也不会在索引中出现「不适用」行。本步骤适用于提供 HTTP 或静态文件的提供商。
这些提供商会提供 <Provider>.Website.<Framework> 复合工具,用户只需一次调用即可部署 Astro 或 Next.js 应用:
const site = yield* AWS.Website.Astro("Site", { rootDir: "./web" });
使用云平台的 Web 托管服务,而不是容器
网站应部署到云平台专为网站构建的基础设施上: 静态资源放在 CDN 上,服务端渲染则通过同一 CDN 后的云平台无服务器 函数提供。把整个构建产物放进容器或持续运行的 VM 中,且不使用 CDN, 只是图省事的默认做法。虽然这种方式对所有框架都能一次部署成功, 但不应采用。
Azure 的首次尝试就这么做了。包括仅支持静态内容的框架在内,全部 14 个框架
都被打包成 Docker 镜像并部署到 Container Apps。后续方案将静态构建产物
迁移到 Storage 静态网站,将服务端构建产物迁移到持续运行的 App Service 计划,
并可选用 Front Door。这仍然是用 VM 而不是函数,默认也没有 CDN。GCP 的组合方案
仍会为每个框架(包括 StaticSite)部署一个 Node 镜像到 Cloud Run。两者都不要照搬。
在编写代码前,先为每个云平台选择托管方式,并在目录中记录选择及其原因:
| 提供商类型 | 静态资源 | 服务端渲染 | 参考 |
|---|---|---|---|
| 具备 CDN 和函数的超大规模云平台 | CDN 后的对象存储 | 作为 CDN 动态源站的无服务器函数 | packages/aws/src/Website/(S3 + CloudFront + Lambda,SsrSite.ts) |
| 边缘平台 | 平台的资源托管服务 | 平台的函数 | packages/cloudflare/src/Website/(Workers + 静态资源) |
| 拥有自有函数运行时的平台 | 平台的资源托管服务 | 通过框架目标运行其函数 | packages/neon/src/Website/(frontend-frameworks/<framework>/neon.ts) |
| 仅提供容器或 VM 的平台 | 由同一个 Node 服务提供;若平台有 CDN,则置于 CDN 后 | Node 服务 | packages/fly/src/Website/、packages/hetzner/src/Website/、packages/railway/src/Website/(Cdn.ts) |
这对尚待构建的云平台意味着:
- **Azure:**使用 Static Web Apps,或将 Blob 静态网站置于 Front Door 后, 并使用 Azure Functions(Flex Consumption)进行服务端渲染。不要使用 Container Apps,也不要使用 App Service 计划。
- **GCP:**将 Cloud Storage 存储桶置于外部 HTTPS 负载均衡器上的 Cloud CDN 后, 并使用 Cloud Run 或 Cloud Functions 作为服务端渲染的无服务器源站。 仅托管资源的站点绝不运行容器。
规则:
- 仅包含资源的构建产物(Vite、StaticSite、SPA 输出)绝不运行计算任务。
- 默认启用 CDN,不要用
cdn: true标志控制。上传资源时应带上内容哈希和缓存标头, 部署时应失效或清除已更改的内容(AWS 上使用AssetDeployment.ts+CloudFront.Invalidation)。 - 服务端渲染应运行在可缩容至零的函数上。只有当云平台没有函数运行时, 或框架需要长时间运行的进程时,才可以使用容器或 VM。应在该框架的 JSDoc 中说明原因。
- 函数需要框架目标:在
packages/frontend-frameworks/src/<framework>/<provider>.ts下新增文件,与aws.ts、cloudflare.ts和neon.ts并列,并生成供云平台函数运行时使用的处理程序。只有容器/VM 提供商才使用 Node 目标 (@alchemy.run/frontend-frameworks/<framework>/node),并通过核心的alchemy/Website/Server调用。 - 在选择容器之前,先检查云平台文档是否提供该框架的托管页面(Azure Static Web Apps 就提供了 Next.js、Nuxt、Astro 和 SvelteKit 的托管页面)。如果有,就采用该页面所用的方案。
布局
采用与现有提供方相同的一组框架(ls packages/aws/src/Website 和 packages/hetzner/src/Website:Astro、
Foldkit、Nextjs、Nuxt、Octane、ReactRouter、SolidStart、StaticSite、
SvelteKit、TanStackStart、Vinext、Vite、Vocs、Waku):
FrameworkSite.ts负责实现makeFrameworkSite,通过框架集成(@alchemy.run/frontend-frameworks/<framework>)构建,并将输出部署到上述托管平台。其共享属性(rootDir、memo、dev、env、assets、domain、tags)沿用同级提供方使用的名称和含义。- 每个框架各有一个小文件,仅设置框架标识符、部署目标和该框架自己的选项块。
- 为仅包含资源的网站提供
StaticSite.ts,并在提供方导出入口中通过export * as Website from "./Website/index.ts"导出index.ts。
每个框架都需要有一个实时测试
packages/integration-tests/test/<Provider>/Website/<Framework>.test.ts,
用于断言响应经由 CDN 返回(检查缓存标头或 CDN 主机名),且服务器渲染的路由会命中函数;还需要一个供 alchemy dev 使用的 <Framework>.local.test.ts,以及一个共享的 PropSurface.test.ts。此外,还需要提供一个 examples/<provider>-website-<framework> 示例,将其列入 scripts/test-examples.ts,并在 website/src/content/docs/<provider>/frontend/ 下添加一个页面。
步骤 8 —— 闭环
修复实时运行暴露的每个问题之前,都要先分类,顺序如下:提供方 bug > 提炼补丁 > 测试修复。
| 症状 | 修复 |
|---|---|
Unknown<Pkg>Error,或希望据此分支处理的状态/消息 | 类型化错误补丁(distilled-sdk-patch) |
| 解码失败,线路数据中的字段为 null 或缺失 | 可空/可选补丁 |
| 机密以普通字符串形式返回 | 敏感数据补丁 |
| 资源泄漏、尚未就绪便返回、替换错误 | 修复 alchemy 中的提供方实现 |
| 测试断言了 API 未承诺的行为 | 修复测试 |
应用补丁后,只重新生成该软件包(在子模块中运行 pnpm generate <pkg>),并立即重新运行测试——测试运行器会从 src/ 读取 distilled,因此无需构建。收集所有补丁,通过 pnpm patches:audit 验证每个补丁,然后将它们作为 distilled PR 提交,接着更新固定版本(步骤 1)。
完整运行后,列出测试账户中仍然存在的资源(运行 pnpm nuke --dry-run --profile testing --include <Provider>.* 或调用提供方的列表接口)。绿色测试若留下资源,就是提供方 bug。
步骤 9 —— 审核关卡
使用一个全新的审核子 Agent 运行 review.md 中的每项检查,并修复发现的问题。向用户报告结果表及其统计数量,让他们无需手动重新审核也能了解检查内容。
步骤 10 — 文档、示例和 PR
-
为每个资源、属性、特性和绑定编写 JSDoc,达到 docs.md 中的标准:运行时的完整程度要达到
AWS.Lambda.Function,核心资源的完整程度要达到 S3 Bucket 或 R2 Bucket;对于长尾资源,则要提供创建示例和替换注意事项。然后运行pnpm docs:check-jsdoc和pnpm docs:gen。 -
按照 docs.md 的要求,手工编写位于
website/src/content/docs/<provider>/的文档中心:结构参照 AWS 文档中心(概览、设置、分为五部分的教程,以及按关注点划分的章节),代码取自经过测试的示例,并遵守其中的行文规则。仅由零散的“指南”组成、带读者浏览示例的文档中心并不合格;GCP 的文档中心就因此不得不重做。 -
提供下文 示例 一节中所述的示例集。
-
使用
pnpm exec tsrs -b进行类型检查,运行pnpm exports:check和pnpm lint:providers,并使用pnpm exec oxfmt格式化。 -
按照 Pull Request 约定 提交 alchemy PR,并链接其依赖的精简 PR。描述要展现该提供商的开发者体验(DX),而不是罗列已构建的内容:
- 用一两行介绍软件包,然后用几个项目符号列出数量(服务、资源、实时测试文件、受门控的测试)。
- 为每种运行时(每种形式)、事件源和网站分别添加一个
###章节。 - 为每个核心资源添加一个
###章节:即大多数使用该云平台的应用都会用到的 10–20 个资源(资源组或项目、身份和角色、对象存储、主要的 SQL 和文档数据库、队列和主题、密钥、容器注册表、网络和 DNS、日志)。根据该云平台自己的快速入门选择这些资源,而不是按目录中的顺序选择。将总是一起使用的资源(例如命名空间及其队列)和它们的绑定归为一组。 - 每个章节写一两句话,然后附上一段从该资源的 JSDoc 示例中复制的代码片段,这样代码就已经过验证。
- 用一行结尾,说明长尾资源并指向生成的参考文档。不要逐一列出。
除非有测试以这种方式部署绑定,否则不要展示绑定在某个宿主中运行。在 Azure 中,描述原本打算展示在
Azure.Functions.Function中使用的绑定,但它并不是已注册的绑定宿主,因此那些绑定并未生效。
示例
用户通过示例了解该提供商,文档中心也会从示例中复制代码。应提供全面的示例集,而不是一两个。Azure 首次仅提供了 azure-storage(一个不含运行时的 Stack)和一个网站;AWS、Cloudflare、Fly 和 Hetzner 则为每个框架提供一个示例,并为每种工作负载各提供一个示例。
每种 Web 框架都要有自己的示例,适用于所有托管网站的提供商:examples/<provider>-website-<framework>,每个 <Provider>.Website.<Framework> 组合对应一个示例(Astro、Foldkit、Nextjs、Nuxt、Octane、ReactRouter、SolidStart、SvelteKit、TanStackStart、Vinext、Vite、Vocs、Waku,以及 <provider>-static-site)。ls examples | grep hetzner-website- 所列内容就是要匹配的完整集合。
然后,为云平台支持的每种工作负载各提供一个示例。 沿着下方列表逐项检查,为该提供商支持的每一行添加示例,其余跳过:
| 工作负载 | 展示内容 | AWS / GCP / Cloudflare 参考示例 |
|---|---|---|
| 无服务器函数,有副作用 | 带有存储或数据库绑定的 HTTP 处理程序 | aws-lambda、gcp-cloud-function、cloudflare-worker |
| 无服务器函数,异步 | 使用普通处理程序和 InferEnv 的同类函数 | cloudflare-worker-async |
| HTTP API | 在默认运行时上运行的 Effect HTTP API 或 RPC | aws-lambda-httpapi、aws-lambda-rpc、gcp-cloud-run-api |
| 队列 | 通过事件源连接的生产者和消费者 | gcp-pubsub-worker、gcp-pubsub-fanout |
| 定时任务 | cron 触发器 | gcp-cron、gcp-scheduled-job |
| 存储事件 | 由上传操作触发的函数 | gcp-storage-uploads、gcp-eventarc-firestore |
| 持久化工作流 | 在提供商的引擎上运行的 alchemy/Workflows(步骤 5):启动、发送信号、读取运行记录 | 暂无示例;复制 packages/integration-tests/test/Cloudflare/Workers/fixtures/durable-workflow/ 中的一致性测试夹具 |
| 容器 | 容器服务 | aws-ecs、fly-service |
| Kubernetes | 在云提供商的托管集群上运行的 Deployment | aws-eks、gcp-gke |
| 虚拟机 | 运行程序的虚拟机 | aws-ec2、hetzner-server |
| SQL 数据库 | 从运行时访问并执行迁移的数据库 | aws-rds、gcp-cloud-sql-drizzle |
| 缓存 | 从运行时访问的 Redis | gcp-memorystore-redis、fly-redis |
| 密钥 | 由运行时读取的密钥 | gcp-secrets-kms |
| AI | 云提供商的模型服务 | aws-bedrock-ai、gcp-vertex-ai |
| 服务间通信 | 两个相互调用的运行时 | gcp-service-to-service |
| 本地开发 | 在 alchemy dev 下运行的同一应用 | aws-dev、cloudflare-dev |
示例按 kebab case 命名为 <provider>-<workload>。每个示例都是一个工作区项目,目录结构与 examples/gcp-pubsub-worker 相同:
package.json(包含私有配置、deploy/dev/destroy/test脚本,以及workspace:*依赖项)、引用packages/alchemy和提供商包的tsconfig.json,以及README.md。alchemy.run.ts,运行时和资源位于src/中。test/integ.test.ts,使用@alchemy.run/test/Bun:在beforeAll中部署,通过 HTTP 调用已部署的应用,通过 distilled 验证云端状态,并在afterAll中销毁。网站和支持dev的应用还需要test/dev.test.ts。
在根目录的 tsconfig.json 的 references 中以及 scripts/test-examples.ts 中注册每个示例,并在完成前使用测试配置文件运行其测试。像其他交付内容一样,在 INDEX.md 中将示例列为条目进行跟踪。
早期阶段可以提交草稿 PR;描述中应注明索引中的数量,并说明提供商尚未完成。
满足以下条件时,提供商即视为完成:
- 已编目每项 SDK 服务,并已对每项操作进行分类;
- 每个范围内的资源都有各自通过的在线测试(或标记为
blocked: cost/blocked: skipped,并已向用户提供列表); - 每项
binding操作都是通过 distilled 实现的最小权限绑定,使用<Provider>Bindings.Bind,能够访问外部主机,并在测试中由已部署的主机调用; - 没有任何 alchemy 代码发起手写 API 调用(review.md 中的“Hand-written HTTP”检查无问题);
- 每个运行时都提供使用
InferEnv的两种形式及其事件源,并且每种形式都有对应测试; - 云提供商的持久化引擎具备通过一致性测试用例的 Effect 工作流引擎;否则应说明其不在范围内及其原因;
- 框架网站(如果该云提供商支持网站托管)已部署到其 CDN 和函数;
- 示例集(每种框架一个、每种工作负载一个)均已部署并通过测试;
- JSDoc 达到 docs.md 中的标准,已生成参考文档,且 hub 与 docs.md 一致;
- PR 描述中列出了运行时和 fat head;
- review gate 检查无问题,完整运行后测试账号已清理干净,并且过程中发现的每项 SDK 不匹配都已通过 distilled 补丁合并。