从 Cloudflare Turnstile 迁移
Caputchin 用和 Cloudflare Turnstile 同样的两段式模型，即页面上一个产出令牌的组件、加一次确认它的服务端检查，所以迁移大多是一次机械的替换，而非一次重写。Turnstile 是常见提供商里最接近 Caputchin 的那个，因为两者都返回一个权威的通过/失败、而非一个风险分数，所以没有阈值要重新调。这份指南给出每一部分的改前改后。
如果你还没创建一个 Caputchin 账户和站点密钥，就先去 创建你的账户；你会需要一个给页面用的 公钥（cpt_pub_...）和一个给你后端用的 密钥（cpt_sec_...），和 Turnstile 的 site key 与 secret key 同样的划分。
心智模型不变
你已经围绕 Turnstile 建好的一切，即渲染一个组件、收集一个令牌、把它 POST 到你的服务器、在信任请求之前核验它，都留着。只有名字和端点变。
1. 换掉客户端代码片段
| Turnstile | Caputchin | |
|---|---|---|
| 脚本 | <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| 元素 | <div class="cf-turnstile" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| 表单里的令牌字段 | cf-turnstile-response（自动注入） | caputchin-token（自动注入） |
| 在 JS 里读取令牌 | turnstile.getResponse() | pass 事件 的 detail.token |
和 Turnstile 一样，Caputchin 组件 自动注入一个隐藏的令牌字段 进它所在的那个表单，所以如果你的表单本来就做一次普通 POST，你只改那个元素和你后端读取的字段名。完整的客户端设置见 添加组件，CDN 对 npm 的选择。
2. 换掉服务端核验
这是两者最接近的地方，请求和响应的形状几乎逐字段对齐。
| Turnstile | Caputchin | |
|---|---|---|
| 端点 | POST https://challenges.cloudflare.com/turnstile/v0/siteverify | POST https://caputchin.com/api/v1/siteverify |
| 请求字段 | secret、response | secret、response（相同） |
| 响应 | { success, challenge_ts, hostname, "error-codes", action, cdata } | { success, challenge_ts, hostname, error-codes } |
| 信任规则 | 仅当 success === true 时行动 | 仅当 success === true 时行动（相同） |
在大多数技术栈里，你验证代码唯一的改动就是那个 URL 和那个密钥值；两者都已经据 success 分支，所以没有分数阈值要移植。Turnstile 也接受 JSON 做核验调用，恰好和 Caputchin 一样，所以请求体形状原样沿用。完整的请求/响应参考，包括错误码，在 在你的后端核验一个令牌 上；框架代码片段在 后端示例。
如果你的 Turnstile 集成从响应里读 action 或 cdata，注意 Caputchin 没有直接对应物；那些是你设在组件上的 Turnstile 专属标签。Caputchin 类似的元数据（玩了哪个游戏、它的分数）住在响应的 platform 块里，且仅供参考。
什么沿用过来，以及什么变得更好
- 仍是一个干净的通过/失败。 你保留可能最简单的信任规则，
if (success)，没有概率或阈值要维护。 - 你选 Turnstile 时看中的那个隐私姿态，保留。 Caputchin 不采集 IP、User-Agent、指纹或行为遥测；这个协议无处安放一个访客标识符。见 理念。
- 一个可选的游戏。 不再是一道隐形或托管的挑战，你可以把验证变成一个你访客真心去玩的简短游戏，而它正是能扛住 AI 求解器的那一部分。见 添加一个游戏。
- 一个严格的 CSP 保持严格。 Caputchin 在一个收紧的 Content-Security-Policy 下运行；你允许少数几个来源，而不是放松你的策略。见 Caputchin 如何沙箱化游戏。
坑
- 两个密钥，两个家。 公钥（
cpt_pub_...）放在页面上；密钥（cpt_sec_...）只留在服务端，恰好是那套 Turnstile 纪律。不要把密钥交付给浏览器。 - 令牌是一次性的。 和 Turnstile 一样，一个令牌只核验一次。不要缓存或重放它。
- 改你后端读取的字段名。 那个隐藏字段是
caputchin-token，不是cf-turnstile-response，一个常见的一行之失。 - 没有
action/cdata。 如果你据那些分支过，把那个逻辑挪到别处；Caputchin 不携带它们。
另见
- 添加组件：完整的客户端设置。
- 在你的后端核验一个令牌：那个权威的
siteverify参考。 - 后端示例：每种语言里的核验调用。
- 添加一个游戏：把验证变成一个游戏。