接入文档

把你的产品接入 AI Relay：选档位、写清单、实现 POST /relay、过接入验收。

接入 AI Relay

让用户的 AI（Claude、ChatGPT、豆包等）直接调用你的产品：AI 通过 AI Relay 找到你的动作，替用户下单，Relay 负责确认、授权和记账，你只管把事办好。

一句话交给你的编码 AI

先把下面「开始前准备」收齐，再把这句话发给 Cursor、Claude Code、Codex 等编码 AI。签名 secret 自己填进环境变量，不要贴给 AI，也不要提交进代码仓库。

请按 https://relay.newbeeai.online/llms.txt 里的接入指南把我们的产品接入 AI Relay：先对照「开始前准备」确认信息齐全，从起步模板改起，实现 POST /relay，用接入验收工具跑到全绿，再部署、在线验收、提交审核。这个账号已经接过别的产品的话，先确认这次是新产品还是给已接入的产品加功能：新产品按「一个账号接多个产品」另开一个供给方，不要复用别的产品的 supplier_id、secret 和端点；加功能就改那个产品原来的清单。

开始前准备

接入时间大多花在中途才发现缺东西、来回补。动手前花 5 分钟把这张表填完：

要准备的 为什么 怎么算准备好
这次是新产品还是加功能 一个账号可以接多个产品，每个产品单独一个供给方 账号没接过：直接注册。接过别的产品：新产品另开供给方；给已接入的产品加功能、换端点地址或收款方式，都还是改它原来的清单。见一个账号接多个产品
代码仓库地址和改代码的权限 端点要加进你的产品 编码 AI 能读写这个仓库
部署通道 端点要上线才能在线验收 能 SSH 登录服务器；服务器能拉到代码，或者能 scp/rsync 上传；部署脚本中断后能从断点重跑。先验证这一条，别靠网页控制台来回上传
公网 HTTPS 地址 Relay 只调 https:// 端点 有域名和证书，确定端点路径，比如 https://api.example.com/relay
签名 secret 放哪 注册时只显示一次 服务器上的环境变量或密钥管理里留好位置，比如 RELAY_SECRET
测试买家（多方案再加测试商家） 验收会真的下单 建好测试账号；需要账号绑定的，知道怎么用它生成绑定码。见测试隔离
能不能做真实业务操作 「不计费」不等于「不产生数据」：验收照样会建单、发消息、公开发布 定好测试单怎么认、走哪套数据（测试隔离）
上线余额 收费动作要预付手续费才会出现在搜索里（订单免手续费的推广期内不要求） 首次审核通过会送 ¥100 体验额度（每个账号一次，给最先审核通过的那个供给方；账号已经领过的，之后的供给方不再送，推广期结束后要先充值）；手续费高、单量大的，提前充值（看下面「钱的事」）

最短路线

按顺序做，前 8 步都是必做，其余检查放到出问题再看：

# 做什么 在哪
1 收齐上面的准备 —
2 选档位（L0 / L1 / L2，见下文） —
3 从起步模板拷一份，改清单和标了 TODO(业务) 的函数 你的仓库
4 本机接入验收全绿 你的电脑
5 注册供给方，拿到 supplier_id 和 secret（账号接过别的产品：后台左上角「再开一个供给方」） 供给方后台
6 部署到 HTTPS，配好 secret；准备测试买家的绑定码 你的服务器
7 保存清单、填样例输入，点「在线验收」到全绿，提交审核 供给方后台
8 审核通过后，确认后台首页「上线状态」5 项全绿 供给方后台

完成的标准是第 8 步，不是「审核通过」。「代码部署完成」「审核通过」「AI 能搜到并调用」是三个不同的状态，只有下面 5 项同时满足，用户的 AI 才能找到你：

条件 没满足时
接口可达：Relay 能 ping 通你的端点 后台「立即检测」看具体错误
在线验收通过 看红项，改完重新验收
审核通过，清单在线上 等管理员处理；被驳回会写原因
可用额度够付一笔手续费（免费动作、订单免手续费的推广期内不要求） 手续费超过可用额度的动作搜不到、也不能下单。可用额度 = 余额 − 还没结算的订单占着的手续费 + 透支额度（默认 ¥50）。体验额度用完后在「余额与流水」页充值（平台没开在线充值时联系管理员）
能被搜到：供给方没被暂停，动作没被下架 后台显示原因；可以在「试搜一下」里用用户会说的话搜一次

钱的事

动手前先知道这几条，详细规则见计费与结算：

  • 谁付钱：你付给 Relay 手续费。订单免手续费的推广期内订单和查询都不收；这个推广期结束后订单按成交价的 3% 收（没有成交价的动作按清单里的固定 fee，¥1–¥100），查询类目前免费。入驻费在免入驻费的推广期内免收。两个推广期分开管，不一定同时结束。用户付给你的钱照旧走你自己的收款渠道，Relay 不经手。详见计费与结算。
  • 什么算成交、什么时候扣：默认收到 completed（同步响应或回调）时扣。失败、取消、过期、结果未知的单都不扣。
  • 测试扣不扣：本机验收和后台在线验收不扣。你自己用 Claude、ChatGPT 试，成交了照常扣。
  • 余额不够会怎样：余额用完以后还能透支一点（平台统一设，默认 ¥50）接单。可用额度（余额 − 还没结算的订单占着的手续费 + 透支额度）不够付一单的手续费时，这一单不发给你；手续费超过可用额度的动作从搜索里隐藏。已经进了 Relay、在下发前才被拦下的单，订单列表里写明「没发给你」的原因（AI 发起时就被拦的不建单，也不会出现在列表里）。免费动作、已经发给你的订单不受影响。快用完、用完时都会发邮件提醒（只发给上线中的供给方），充值后马上恢复。订单免手续费的推广期内不看余额。透支欠下的（余额是负数）要先充值补上才能注销。
  • 怎么充值：首次审核通过时自动送 ¥100 体验额度（每个账号一次，开多个供给方也只送给最先审核通过的那个），够上线后先跑起来；之后在后台「余额与流水」页扫码充值，到账自动加余额。平台没开在线充值时联系管理员手工入账。

选档位

档位 适合 你要实现 典型耗时 指南
L0 零代码 已经有 OpenAPI 文档的 REST 接口，动作都能当场给结果 在后台导入 OpenAPI，勾选要开放的接口 1–2 小时 L0：从 OpenAPI 导入
L1 一个端点 动作 3 秒内能给结果：查询、预约、下单 POST /relay 处理 ping 和 action.invoke 半天 L1：一个端点
L2 异步单结果 要排队、人工处理、等第三方 L1 加上接单、回调、补拉、取消 1 天 L2：异步与多方案
L2 异步多方案 多家报价、撮合，让用户选一个 再加方案推送、选定、撤回，通常还要账号绑定 1–2 天 L2：多方案要处理的事

拿不准就先做 L1。产品要知道「这是我们哪个用户」时，在所在档位之上再做账号绑定。

你要做什么

你做 Relay 做
一份 JSON 清单：有哪些动作，输入输出长什么样，风险多高，收不收费 让 AI 搜到你的动作，按清单校验输入
一个 HTTPS 端点 POST /relay：验签，按动作办事，如实返回结果 按用户给 AI 的授权判定要不要确认，要确认就让用户在网页上点
（异步才要）办完后签名回调 Relay 下发、重试、补拉、超时取消，到计费点扣手续费

你的代码不碰计费、不做确认、不判断授权。

从注册到上线

供给方后台在 https://relay.newbeeai.online/supplier，首页的「上线状态」和上面最短路线的第 5–8 步对应。

  1. 注册：用手机号登录 Relay，在供给方后台填产品名（1–100 字）、一句话介绍（1–200 字）、端点地址（https://）、联系人和邮箱。拿到 supplier_id 和签名 secret（whsec_ 开头，只显示一次，Relay 加密保存，后台也看不到明文）。端点还没部署好可以先填计划的地址，审核以清单为准。
  2. 写清单：在「动作清单」里用表单填，或直接粘贴 JSON；L0 在「从 OpenAPI 导入」里生成。每个动作填一份样例输入，在线验收要用。
  3. 在线验收：打开清单版本页，点「开始在线验收」。Relay 用真签名调用你的端点，逐项给出红绿。每个动作都会真的下单：同步动作一单，异步动作两单（一单走完、另一单验取消），订单号以 ord_cf 开头，不计费。需要账号绑定的，填一个测试买家刚生成的绑定码。全绿才能提交审核。
  4. 提交审核：管理员一般 1 个工作日内处理。审核标准：动作描述人能看懂；风险等级不低于平台规则（对外发布、代付款必须是 high）；没有成交价的收费动作，固定手续费在 ¥1–¥100 每笔；不是违法业务。驳回会写原因，结果发邮件到联系邮箱。
  5. 确认上线状态：审核通过后看后台首页「上线状态」，5 项全绿才算能用。

上线后还可以在后台看订单、流水、争议和质量指标。改清单要另存一个新版本，重新验收、提交审核；在途订单按下单时的版本走。

一个账号接多个产品

一个登录账号最多开 10 个供给方（含已注销的），每个产品单独一个供给方。AI 搜到的、用户在对话里看到的都是「供给方名 + 动作」，不同产品放进同一个供给方，用户分不清在跟谁下单。

情况 做法
账号还没接过产品 按上面「从注册到上线」注册第一个
给已接入的产品加功能、改动作，或者换端点地址、换收款方式 不另开。还是同一个产品，在它的「动作清单」里另存新版本（端点地址就改 endpoint.url），重新验收、提交审核，审核通过后按新版本生效
接另一个产品（用户眼里是另一个牌子、另一项服务） 另开一个：供给方后台左上角的切换菜单 →「再开一个供给方」，或打开 https://relay.newbeeai.online/supplier/new，填的资料和第一次一样

每个供给方各自独立：

  • supplier_id 和签名 secret：每个供给方一套，注册时只显示一次。Relay 发来的请求里不带 supplier_id，只能靠端点地址区分，所以每个产品用自己的端点地址、自己的 secret 验签和签回调。SDK 的 secrets 数组是给同一个供给方轮换 secret 用的，不要把两个产品的 secret 放进同一个数组。
  • 端点地址：就是清单里的 endpoint.url，路径随你定，/relay 只是约定。两个供给方不要填同一个地址。两个产品放在同一个服务里时，已上线的那个保持原样（比如继续用 /relay 和 RELAY_SECRET），新产品用新路径和新变量（比如 /relay/booking 和 RELAY_SECRET_BOOKING）。幂等表可以共用：idempotency_key 等于 order_id，全局唯一，不会跨供给方撞。写法见起步模板「一个服务接两个产品」。
  • 清单、在线验收、审核：各走各的；一个被驳回不影响另一个。
  • 余额和流水：按供给方算，互不转账。新开的供给方余额从 0 起；体验额度每个账号只送一次，已经送过的话，新供给方有收费动作就要先充值（或者靠透支额度），不然「上线状态」的可用额度一项不会绿（订单免手续费的推广期内不看余额，不用先充）。想知道送给了哪个：在各供给方的「余额与流水」里找备注「体验额度（首次审核通过赠送）」那一笔。
  • 订单、争议、质量指标、暂停、注销：都按供给方。注销一个，其他的照常。
  • 名字：同一账号下没注销的供给方不能重名（不分大小写、不算首尾空格）。清单里的产品名审核时也按这条查，撞名的版本过不了审核，改名后重新提交。

后台地址按供给方分：https://relay.newbeeai.online/supplier/<supplier_id>，/supplier 打开上次看的那个，左上角随时切换。

已上线产品的代码挪进共用服务、重新部署后：本机对它再跑一遍接入验收，部署完在它的后台首页点「立即检测」确认能 ping 通。清单没变就不用另存版本、重新审核。

给编码 AI：开始前问用户这个账号有没有接过别的产品。接过的话，先确认这次是新产品还是给已有的加功能（同一个产品换端点地址、换收款方式也算后者，改原来的清单，不另开）；新产品请用户在后台另开供给方，把新 secret 配进这个产品自己的环境变量，不要改已有产品的 secret、端点和清单。

接入验收工具

@dreamcavy/ai-relay-conformance 读你的清单，用真签名逐项调用你的端点：验签、ping、每个动作、同键重放、未知类型、响应 Schema，异步动作还跟到最终结果，多方案会选一次方案、测一次取消。后台的「在线验收」用的是同一套检查，本机全绿，后台也会全绿。用法和全部检查项见 Conformance README。

包的发布状态

四个包都还没有发布到 npm 和 PyPI，npx @dreamcavy/ai-relay-conformance 现在跑不了。下面这组命令现在就能跑：

git clone https://github.com/fengdejiyihi/ai-relay-protocol.git && cd ai-relay-protocol
pnpm install && pnpm build        # 要 Node 22 以上和 pnpm 10

# 接入验收：回到你的项目目录运行
RELAY_SECRET=whsec_dev node <公开仓库路径>/packages/conformance/dist/cli.js --manifest manifest.json \
  --endpoint http://127.0.0.1:8787/relay --inputs inputs.json

# Node SDK（可选）：打成 tgz 装到你的项目
pnpm --filter @dreamcavy/ai-relay-protocol --filter @dreamcavy/ai-relay-sdk pack --pack-destination /tmp/relay-pkgs
npm install /tmp/relay-pkgs/*.tgz

# Python SDK（可选）
pip install "git+https://github.com/fengdejiyihi/ai-relay-protocol.git#subdirectory=packages/sdk-python"

pnpm install 时提示 Failed to create bin … sandbox-shop 是因为还没构建，可以忽略。装好的 SDK 在 Node 20 以上就能跑。起步模板不依赖任何包，只要 Node 22.13 以上。

包 用途 状态
@dreamcavy/ai-relay-sdk（npm） Node 供给方 SDK：验签、分发、输入校验、幂等、回调 准备发布
dreamcavy-ai-relay-sdk（PyPI） Python 供给方 SDK，适配 FastAPI、Flask、WSGI 准备发布
@dreamcavy/ai-relay-conformance（npm） 接入验收工具 准备发布
@dreamcavy/ai-relay-protocol（npm） 协议包：Schema、校验、签名 准备发布

发布之后，文档里的 node <公开仓库路径>/packages/conformance/dist/cli.js 都可以换成 npx @dreamcavy/ai-relay-conformance。不用 SDK 也能接：协议只要一个端点和约 15 行的 HMAC 验签，任何语言都能写，见规范附录 B。

文档目录