GoLive开发者指南：用Capabilities与Links为你的应用扩展新供应商支持（含代码实战）-平芜编程栈

GoLive开发者指南：用Capabilities与Links为你的应用扩展新供应商支持（含代码实战）

【免费下载链接】golive-skillTake your agent-built product live: hosting, database, domain, email, payments — on your own accounts. Open-source Agent Skill + zero-dependency Node CLI: detect → plan → approve → apply → verify. No GoLive account, backend or telemetry.项目地址: https://gitcode.com/gh_mirrors/go/golive-skill

GoLive是一个开源 Agent Skill + 零依赖 Node CLI，帮助你把 AI 代理构建的应用真正上线：托管、数据库、域名、邮箱、支付——全部跑在你自己的账号上，无需 GoLive 账号、后端或遥测。本文面向想为 GoLive 集成新供应商（Provider）的开发者，带你理解Capabilities（能力）与Links（跨供应商链路）这两块核心扩展机制，并给出从 0 到 1 添加供应商支持的代码实战步骤。

为什么 GoLive 加新供应商只需"一个适配器"？

传统做法里，每接入一个支付商就要为每种托管环境重写一套"支付 → 托管环境变量"的对接代码，组合爆炸。GoLive 用三层设计解掉了这个问题：

层	角色	一句话理解
Adapter（适配器）	对接单个供应商	会说这个供应商的"语言"，并声明自己有哪些能力
Capabilities（能力）	供应商暴露的标准接口	如 EnvStore、WebhookRegistry、DnsZone 等，所有能力定义在 src/core/types.ts
Links（链路）	跨供应商粘合层	只面向能力编程，写一次即可复用到任意供应商组合

正如 src/core/types.ts 顶部的设计注释所说：

一个 LINK 是针对能力写一次的跨供应商粘合（例如"支付 webhook → 托管环境变量 + 托管 URL"），所以新增供应商永远不需要为每种两两组合重写配方。

完整心智模型见 docs/ARCHITECTURE.md 的 "Adapters, capabilities and links" 一节（docs/ARCHITECTURE.md#L136-L143）。

全景图：7 条轴、3 个注册表、1 个执行流程

GoLive 把"上线"拆成 7 条轴（Axis）：hosting、db、auth、payments、email、dns、monitoring（定义见 src/core/types.ts#L16-L17）。每条轴可以独立选择供应商，彼此自由组合。

注册中心在 src/registry.ts：

src/adapters/ → ADAPTERS （供应商适配器） src/links/ → LINKS （跨供应商链路，按规划顺序排列） src/checks/ → CHECKS （对真实系统的只读验证）

执行流程固定为：detect → plan → approve → apply → verify（docs/ARCHITECTURE.md#L10-L12）。你的新供应商接入后，自动融入这条流水线，不需要改主流程。

能力查找通过adapterFor/cap两个小工具函数完成，实现在 src/core/caps.ts：

cap(ctx, 'payments', 'webhooks') // 取 payments 轴供应商的 webhook 能力

实战：三步接入一个新供应商

以下示例假设你要接入一个虚构的托管商myhost（hosting 轴）。

步骤 1：编写 Adapter，声明它支持的 Capabilities

一个 Adapter 的最小契约在 src/core/types.ts#L116-L126：id、title、axes、automated、auth、capabilities。骨架代码：

// src/adapters/myhost.ts import type { Adapter } from '../core/types.js'; export const myhostAdapter: Adapter = { id: 'myhost', title: 'MyHost', axes: ['hosting'], automated: true, async auth(ctx) { // 检查登录状态（CLI 登录或环境变量 token），返回 { ok, via, howToFix } return { ok: Boolean(ctx.envToken('MYHOST_TOKEN')), via: 'MYHOST_TOKEN env' }; }, capabilities: { project: { /* ProjectLinker：选择/创建项目 */ }, env: { /* EnvStore：listNames / set / canSet */ }, url: { /* PublicUrl：get 各目标的公网 URL */ }, deploy: { /* Deployer：deploy 并回报 provider 自己的部署 id */ }, }, };

关键原则（来自代码注释与 docs/ARCHITECTURE.md#L145-L155）：

能力宁缺勿假：供应商读不回的数据就返回null或不暴露该能力，GoLive 会显式说明原因，而不是猜。
密钥只在传输边界揭示，永远放进Secret包装器（见 docs/ARCHITECTURE.md#L223-L229）。

然后把适配器登记进 src/adapters/index.ts#L17 的ADAPTERS数组，注册即生效——这正是 src/registry.ts#L2-L3 注释里说的："加一个供应商 = 加一个 adapter 文件 + 在这里列一下；links 和 checks 通过 capabilities 自动发现它"。

步骤 2：写 Link，只面向能力编程

Link 是 src/core/plan.ts#L42-L47 定义的接口：plan(ctx)返回步骤（Steps）、人工交接项（Handoffs）或null（不适用时静默退出）。

以监控链路 src/links/analytics.ts 为模板，你可以看到标准姿势：

// 1. 只查能力，不认供应商名字 const r = await ready(ctx, 'monitoring', 'project'); const host = await ready(ctx, 'hosting', 'env'); // 2. 能力缺失时降级为人工交接（handoff），而不是报错 if (!host) { for (const target of ctx.config.targets) handoffs.push(envHandoff(ctx, adapter, mapped, target)); }

所有 Link 按规划顺序登记在 src/links/all.ts#L36。你的新供应商只要能提供outputs/webhooks/sendingDomain等能力，现有的payments、email、analytics等链路会直接复用——这是 Capabilities 设计的核心红利。

⚠️ 注意顺序约束：accounts 必须在最前（重置每轮规划缓存），所有写 env 的 link 必须在 deploy 之前（src/links/all.ts#L22-L34）。

步骤 3：加 Check，用真实读取证明"真的生效了"

每个 Check 由applies(ctx)+run(ctx)组成，产出pass/fail/warn/skip四种明确结论（src/core/types.ts#L810-L817）。以 src/checks/db-connection.ts 为例：

applies: (ctx) => Boolean(cap(ctx, 'db', 'dbConnection')), async run(ctx) { const connection = cap(ctx, 'db', 'dbConnection'); // 只读探测，证据全部无密钥 }

两个新手常踩的坑：

skip ≠ pass。供应商不可读就是 skip，绝不能用"2xx 响应"冒充验证成功（参见 PostHog/Sentry 的 ingest 检查设计，src/links/sentry.ts#L29-L31）。
注册进 src/checks/index.ts 引用的ALL_CHECKS后即被golive verify自动调度。

无法自动化的供应商？加入 GUIDED 清单

如果供应商没有 API 或 CLI，不用写完整适配器——加入引导清单 src/adapters/guided.ts#L15-L46 即可：

{ id: 'myprovider', title: 'MyProvider', axes: ['payments'] },

此时 GoLive 会走"guided"路径：代理引导人工操作，但仍用 check 从外部验证结果（流程见 skills/golive/references/guided.md）。

验证你的改动：不需要真实账号

按 CONTRIBUTING.md 的本地开发规范（Node 24 + pnpm）：

pnpm install pnpm vitest run pnpm tsc --noEmit pnpm build

所有测试使用模拟响应（test/fakes.ts、test/helpers.ts），禁止在测试中访问真实供应商。
行为变更需要基于 mock 的回归测试；新供应商在完整工作流拿到真实验证证据前，都标注为experimental（CONTRIBUTING.md#L61-L62）。

常见问题 FAQ

Q：新能力该放 Adapter 还是 Link？A：单一供应商的读/写操作放 Adapter 的 capability；两个及以上供应商之间的组合逻辑（"支付密钥 → 托管环境变量"）放 Link。

Q：供应商 API 不支持回读部署状态怎么办？A：不暴露对应能力（如 Vercel 没有release能力），GoLive 会跳过该步骤并说明原因，而不是盲写（docs/ARCHITECTURE.md#L129-L134）。

Q：写操作的安全边界在哪？A：一切写操作必须进入 Plan、经人类按 plan id 批准后由apply执行；DNS 写、删除、live 支付各有独立确认门（docs/ARCHITECTURE.md#L182-L189）。你的 Link 中每一步都要声明risk。

GoLive开发者指南：用Capabilities与Links为你的应用扩展新供应商支持（含代码实战）