> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 用 AI Agent 接入

> 把提示词发给正在写代码的 agent，让它完成接入。

项目本来就用 AI coding agent 在开发的话，可以让它直接把 Clink 接进去，不用照着文档一步步写。

Clink 提供了一个开源的接入 skill [clink-integ-skills](https://github.com/clinkbillcom/clink-integ-skills)，里面有接入规则、离线 CLI 和给 agent 用的提示词。装好之后，把提示词发过去就行。

<Note>
  这条路径适合已经有 agent 在改项目代码的情况。手写代码的话，走 [Hosted Checkout 接入](/cn/build-integration) 更直接。

  两条路径产出的东西是一样的，agent 只是代劳敲字。它写出来的代码仍然要看懂、要验收。
</Note>

## agent 会做什么

* 先摸清项目结构、启动方式、路由位置、环境变量注入方式，再决定怎么接
* 扫描现有的定价页或商品数据，生成 `clink-catalog.json`，导入成 Clink 的产品和价格
* 写服务端的 checkout、订阅、webhook 接口
* 注册 webhook 端点，把签名密钥同步进项目的环境变量
* 给出 curl 示例、启动命令和验证结果

## agent 不负责的部分

**决定商业逻辑。** 卖什么、怎么定价、退款政策，这些要商户自己定。

**证明支付真的通了。** 必须有人打开 `checkoutUrl` 用测试卡付一笔，并且确认本地订单变成 paid、发货逻辑真的跑了。agent 说"接入完成"不等于这件事发生过。

**上生产。** 这个 skill 默认只在沙盒工作，生产切换要走 [上线检查](/cn/go-live)。

## 第一步：让 agent 装上 skill

最省事的办法是直接对 agent 说：

```text theme={null}
Install clink-integ-skills from: https://github.com/clinkbillcom/clink-integ-skills
```

也可以自己装到本地 skills 目录：

```bash theme={null}
mkdir -p ~/.codex/skills
git clone https://github.com/clinkbillcom/clink-integ-skills.git /tmp/clink-integ-skills
cp -R /tmp/clink-integ-skills ~/.codex/skills/clink-integ-skills
```

skill 本身不需要额外装运行时依赖，接入用的 CLI 已经打包在里面。

<Note>
  这个 skill 按 Codex 的技能格式组织，目录是 `~/.codex/skills/`。agent 不支持这个格式时，第二步的提示词里已经写了退路——让它直接读 GitHub 仓库。
</Note>

## 第二步：把提示词发给它

整段复制给 agent：

```text theme={null}
请使用 $clink-integ-skills 帮我把 ClinkBill 支付接入到当前网站项目。

目标：尽量全自动完成 ClinkBill sandbox 测试支付接入。

认证方式请按环境选择：
- 优先使用当前 skill 内置的离线 CLI bundle：`vendor/clink-integ-cli/clink-integ-cli`；不要在正常执行时从 GitHub 或 npm 安装 `clink-integ-cli`。
- 优先使用已有或用户手动提供的 `CLINK_SECRET_KEY`，并通过 `clink auth secret set --api-key env:CLINK_SECRET_KEY --env sandbox` 保存到 CLI profile。
- 如果你在本地/桌面环境运行、没有现成 Secret Key，并且可以打开浏览器，且 Playwright 已经通过离线方式预置，才运行 `clink login`，让我在打开的 Dashboard 登录页里手动完成登录，用于让 CLI 读取或创建 Secret Key。
- 如果你在云 IDE、低代码编辑器、sandbox 或其他没有可用浏览器的环境运行，不要卡在 `clink login`。请让我自己登录 ClinkBill Dashboard 后把 Secret Key 提供给你，然后你把它只写入安全的服务端环境变量、平台 Secret 或本地 `.env`。
- 无浏览器环境下，只能先向我索取 `CLINK_SECRET_KEY`。不要初始索取 `CLINK_WEBHOOK_SIGNING_KEY`；当前 CLI 已支持用 Secret Key 管理 webhook endpoint，webhook signing key 应该由你运行 `clink webhook endpoint ensure --save-secret` 后自动生成/保存，再由你写入平台 Secret。

重要要求：

1. 先侦察项目结构、启动方式、服务端入口、路由位置、环境变量方式、订单/购买入口和 webhook raw body 能力，再决定怎么接入。同时判断这个项目是否需要周期性收费和优惠码；不需要就不要实现 subscription 或 coupon 相关接口。如果需要订阅，必须创建 recurring 价格、实现订阅状态到权益的映射，并订阅完整的事件名（subscription.created、subscription.trialing、subscription.activated、subscription.past_due、subscription.incomplete_expired、subscription.cancelled、subscription.updated.plan_changed、subscription.updated.plan_change_canceled、subscription.updated.renewed、subscription.updated.cancel_at_period_end_set、subscription.updated.cancel_at_period_end_revoked、invoice.open、invoice.paid、invoice.void），不要提交 subscription.* 这类通配符。
2. 如果项目没有可信后端，不要把 `CLINK_SECRET_KEY` 或 webhook signing key 放进前端代码，也不要让浏览器直接请求 Clink sandbox API。
3. 必须实现或验证 checkout session 服务端接口、subscription 服务端接口、webhook 接收接口、本地启动/验证方式、curl 示例、自动测试或 smoke test。
4. 如果网站已有价格页、付费产品或订阅套餐，先按"运行中 API/价格页 DOM/hydrated JSON > 源码/配置 > 最后再问用户"的顺序扫描这些产品，并生成 `clink-catalog.json`，再用 `clink catalog validate/plan/import` 创建 Clink product/price；不要让我手动复制 productId/priceId。
5. `clink-catalog.json` 里的每个 product 必须包含且只包含一个图片来源：`imageId`、`imageUrl` 或 `imageFile`。URL 必须写 `imageUrl`，本地 public/static 资源写 `imageFile`，不要把 URL 写进 `imageId`。运行 catalog 命令时，如项目有 public/static 目录，优先加 `--project-root . --public-dir public`。
6. 真实密钥只能写入本地环境变量或平台 Secret，不能写入源码、README、前端变量、测试 fixture 或最终回复。
7. 每次成功运行 `clink webhook endpoint ensure --save-secret` 后，必须同步最新 webhook signing key 到项目运行环境，并重启服务；本地 `.env` 项目优先使用 `--sync-env-file <env-file>`，否则 webhook 验签会失败。
8. 有公网 HTTPS 域名就直接配置 webhook endpoint；只有纯本地 `localhost` / `127.0.0.1` 环境才需要 cloudflared tunnel。
9. 不要把 webhook endpoint 管理说成 Dashboard-only；`clink dashboard webhook ensure` 只是兼容别名，优先使用 `clink webhook endpoint ensure`。
10. webhook handler 必须用 `merchantReferenceId` + `sessionId` 双重匹配本地订单；如果两个字段指向不同本地订单，必须拒绝、隔离或升级处理，不能只依赖其中一个字段。
11. 明确区分本地 mock、签名模拟 webhook、真实 sandbox checkout session、真实 sandbox 测试支付完成后的真实 webhook。
12. 如果没有人打开 `checkoutUrl` 并完成 sandbox 测试支付，不要把"真实 checkout session 创建成功 + 模拟 webhook 通过"说成"真实付款全链路完成"。即使真实 webhook 返回 200，也必须确认本地订单 paid/completed，并确认额度、权益、发货、下载权限或其他 fulfillment 已完成。

完成后请交付架构侦察结果、修改文件列表、新增 API route / service 说明、环境变量说明和 `.env.example`、一键启动命令、curl 示例、CLI 验证结果摘要、webhook endpoint、tunnel URL / 本地 URL、测试结果，以及剩余需要我人工完成的步骤。
```

中途 agent 会索取 **沙盒 Secret Key**。去 [沙盒后台](https://uat-dashboard.clinkbill.com) 的 **开发者** 页面初始化一个（`sk_uat_` 开头）给它。

<Warning>
  只给沙盒密钥，不要给生产密钥。也别让 agent 把密钥写进源码或提交到 Git——上面的提示词里已经有这条约束，但仍然要自己盯一眼。
</Warning>

## 第三步：自己验收

**这一步不能省。** agent 报告"接入完成"和支付真的能用，是两件事。

<Steps>
  <Step title="翻一遍前端产物">
    确认浏览器里拿不到 `sk_` 开头的密钥，也拿不到 webhook 签名密钥。
  </Step>

  <Step title="真的付一笔">
    打开 agent 返回的 `checkoutUrl`，用测试卡 `4242 4242 4242 4242` 完整付一次。没人付过款，就不算跑通。
  </Step>

  <Step title="查商户订单">
    数据库里那条订单要真的变成 paid，发货、充值或开通权益的逻辑也要真的执行了。
  </Step>

  <Step title="逐行核对 webhook 处理器">
    这是 agent 最容易写错的一段，五件事都要对：

    * 验签用的是**原始请求体**，不是解析后又序列化回去的
    * 校验了 `X-Clink-SignType` 是 `SHA256`
    * 业务对象从 **`event.data.object`** 取，不是 `event.data`
    * 按 `event.id` 去重
    * 用 `merchantReferenceId` 和 `sessionId` 双重匹配订单

    中间两条尤其要盯——写错了在模拟事件里发现不了，只有真实付款时才暴露。逐条对照 [Hosted Checkout 接入](/cn/build-integration)。
  </Step>

  <Step title="过一遍上线清单">
    切生产前照 [上线检查](/cn/go-live) 逐条核对。
  </Step>
</Steps>

## 几种常见情况

**agent 说完成了，但没人付过款。** 那只说明 Session 建出来了。要求它明确区分"创建成功"和"付款成功"——提示词第 11、12 条就是管这个的。

**项目没有服务端。** 纯静态站点接不了，因为 Secret Key 必须放在服务器上。让 agent 先加一个最小的后端路由或 serverless 函数。

**agent 要求手动复制 productId。** 站点已经有定价页的话，它应该扫描并用 `clink catalog import` 导入，不该让人手抄 ID。

## 接下来

<CardGroup cols={2}>
  <Card title="Hosted Checkout 接入" icon="wrench" href="/cn/build-integration">
    看懂 agent 写出来的代码，尤其 Webhook 那部分。
  </Card>

  <Card title="上线检查" icon="rocket" href="/cn/go-live">
    切生产前要过的清单。
  </Card>
</CardGroup>