接入文档

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

测试隔离与检查清单

验收和试用都会真的调用你的动作。「不计费」只是 Relay 不扣你的手续费,你的产品照样会建订单、发短信、给商家发消息、公开发布内容。上线前把测试流量和真实业务隔开,再按下面的清单只做必做的检查。

哪些调用是测试

来源 怎么认出来 计费
本机接入验收工具 订单号以 ord_cf 开头;user.relay_uid 是 u_conformance_probe(测绑定码复用时是 u_conformance_other) 不经过 Relay,不计费
后台「在线验收」 同上:订单号以 ord_cf 开头 不计费,不进订单列表
你自己用 Claude、ChatGPT 试 和真实用户一样,只能靠你绑定的测试买家账号(或测试手机号)认出来 照常计费:成交就扣手续费(订单免手续费的推广期内记 0 元)

所以要准备两样东西:认出 ord_cf 订单的开关,和一个测试买家账号。

隔离方案

  1. 测试买家:在你的产品里建一个账号,比如 test_buyer。需要账号绑定的,用它生成绑定码;不需要绑定的,约定一个测试手机号(比如 13800138000)。

  2. 测试商家:多方案、撮合类产品再建一两个测试商家,只给测试买家的需求报价,不出现在真实用户的结果里。

  3. 判断是不是测试单:

    const isTest = env.order_id.startsWith("ord_cf") || TEST_ACCOUNTS.has(env.user?.supplier_user_ref);
    

    是测试单就走测试数据:不发真实短信和站内消息,不通知真实商家,不公开发布,订单写进测试库或打上测试标记。起步模板已经把 test 传给每个业务函数。

  4. 测试数据放哪:最简单是测试单写同一个库但带 is_test 标记,列表和统计默认过滤掉;更稳的是测试单用单独的库(模板里设不同的 DB_FILE,Postgres 用单独的 schema)。

  5. 用完清理:定期删掉测试单,测试商家的消息箱也清空。

绑定码怎么准备

需要账号绑定(user_binding: "token")的供给方,验收要一个真绑定码。每次验收前,用测试买家生成一个新的(一次性、10 分钟有效):

  • 起步模板:npm run -s binding-code test_buyer,在部署端点的那台机器上跑。
  • 你自己的产品:用测试买家登录,打开 binding.help_url 那个页面生成。

本机:--binding-code <码>。后台在线验收:页面上有一个绑定码输入框,填进去,不保存。只想先测动作、暂时不测绑定的,本机可以用 --supplier-user-ref test_buyer 直接指定测试账号;在线验收必须真绑定一次才算全绿。

必做检查(最短路径)

照这个顺序,做完就能提交审核:

  1. 本机接入验收全绿(退出码 0,警告和「未测」不挡)。
  2. 部署到 HTTPS,清单里的 endpoint.url 改成正式地址,secret 换成后台给的。
  3. 后台「在线验收」全绿。
  4. 提交审核。

不需要自己另写一套全面回归、并发压测、模拟回调丢失再演练。验收工具已经覆盖验签、幂等重放、取消、补拉、回调签名和终态规则,后台在线验收用的是同一套检查。

选做(出问题再看)

情况 怎么查
在线验收红、本机绿 多半是部署差异:secret 没换成后台的、反向代理改了请求体(验签要原始字节)、回调根地址还指着本机
异步动作超时 在线验收每个异步动作最多等 90 秒,整次最多 4 分钟。业务本身慢的,测试单走快路径
回调被拒(401/404/409/422) 看 L2 回调的响应表;这些不要重发
担心并发 清单写 endpoint.max_concurrency;Relay 目前不按它限流,自己的端点要能拒绝超量请求(回 rate_limited)
想压测 用测试买家和测试商家,压你自己的预发环境,不要压线上真实商家