前言¶
注册、登录、联系表单、评论提交——凡是用户触发的写操作，都容易被脚本批量撞库或刷垃圾数据。常见做法是前端挂 CAPTCHA、后端再验 token；Turnstile 是 Cloudflare 提供的 bot 校验方案，文档里强调可在不经过 Cloudflare CDN 的前提下嵌入站点，并按访客风险自适应挑战强度。
实际落地时，难点往往不在「看懂文档」，而在：扫一遍现有仓库该改哪几处、在控制台创建 widget 并配对域名、按框架写嵌入片段、在现有后端接上 siteverify，以及改完后是否真的验通。Cloudflare 在 cloudflare/skills 仓库里提供了 turnstile-spin Skill，把上述步骤收成带脚本的向导式编排，由 Agent 读代码、确认插入点、改前后端，并在上报成功前做一次真实校验。
这是什么¶
turnstile-spin 是 Cloudflare 官方维护的 Agent Skill（目录：skills/turnstile-spin）。官方描述为：在既有前端与后端中新建、修复或迁移 Cloudflare Turnstile bot 校验，并包含服务端 Siteverify。
Skill 把「set up Turnstile」拆成可执行链路：检查鉴权、扫描代码库、创建 widget（或使用已有 sitekey）、在选定位置嵌入前端片段、在客户现有后端写入规范的 siteverify 逻辑，并在结束前完成一次验证通过。确定性逻辑（API 调用、重试与错误处理）放在 scripts/ 下的脚本里；Agent 负责编排、读仓库、与用户确认，以及完成前后端编辑。行为以 Skill 内的 SKILL.md 为规范来源，产品要求对齐 Turnstile 文档。
核心功能¶
触发与范围¶
当对话里出现 Turnstile、CAPTCHA、bot protection、siteverify、cf-turnstile-response，或「保护表单/接口/按钮、阻止 bot 注册」等表述，且与 Cloudflare 或 bot 场景相关时，Agent 会加载本 Skill。未提及 Turnstile 的纯 Workers、Pages、R2 等任务不应单独因本 Skill 加载。
若用户已说明 widget 已创建并提供了 sitekey，Skill 要求走「已有 widget」分支，不再走创建 widget 的向导。
多框架参考¶
嵌入前端时，Skill 要求按现有技术栈查阅对应 reference：
| 前端 | 参考路径（仓库内） |
|---|---|
| Vanilla HTML | references/vanilla-html.md |
| Next.js App Router | references/nextjs-app.md |
| Next.js Pages Router | references/nextjs-pages.md |
| Astro | references/astro.md |
| SvelteKit | references/sveltekit.md |
| Hugo | references/hugo.md |
向导式对话流程（概要）¶
下面按官方 SKILL.md 中的 numbered wizard 归纳；带 [wait for user] 的步骤需要用户确认或回复后再继续。
- 简短确认：一句话说明将端到端完成鉴权、扫描、创建 widget、嵌入、siteverify 与验证，并等待用户同意（此步不先展开完整计划）。
- CLI 检查：辅助脚本通过
curl访问api.cloudflare.com。枚举账号时需要明确的$CLOUDFLARE_ACCOUNT_ID，或用户批准的、项目外的 canonicalWRANGLER_BIN及精确WRANGLER_VERSION。禁止用npx、pnpm exec、项目内二进制或未批准的可执行文件执行带凭证的命令；流程中也不会自动安装 Wrangler。 - 鉴权与范围探测（首个不可逆步骤）：运行
scripts/auth-probe.sh，按 JSON 的status分支处理（见下一节）。 - 账号选择：多账号场景下由用户选定
CLOUDFLARE_ACCOUNT_ID后重新探测。 - 域名：默认包含
localhost与127.0.0.1；生产域名从package.json的homepage、wrangler.toml、README.md、AGENTS.md、git remote 等扫描，与用户确认后注册。文档提醒：同一 widget 注册本地与生产域名时，各环境后端应校验 siteverify 返回的精确前端 hostname；生产后端的预期 hostname 白名单不应包含localhost/127.0.0.1。 - 代码库扫描：识别前端框架、后端处理位置（Express 路由、Next API、Rails、Workers、Pages Function 等），以及是否已有 reCAPTCHA / hCaptcha（有则进入迁移模式）。
- 插入计划：列出候选插入点（含
[recommended]/[skip by default]），用户确认后为每个面指定稳定action（如signup、login，1–32 字符，仅字母数字下划线连字符），并确认 action 与 handler 的映射。 - 创建 widget：优先使用已批准且支持
turnstile widget子命令的 Wrangler；否则使用scripts/widget-create.sh。创建示例（managed 模式）：
WRANGLER_WRITE_LOGS=false WRANGLER_LOG=log WRANGLER_LOG_SANITIZE=true \
"$WRANGLER_BIN" turnstile widget create "<name>" \
--domain <d1> --domain <d2> ... --mode managed --json
在 set +x 子 shell 中捕获完整 stdout JSON，用 jq 解析 SITEKEY 与非空的 WIDGET_SECRET，随后 unset 响应变量。
后续步骤（资料截断处未展开的细节）在完整 Skill 中还包括：将 secret 写入后端环境、按 reference 改前端、写入 siteverify、以及成功前的实机验证。
鉴权探测结果怎么处理¶
运行 scripts/auth-probe.sh 后常见分支：
ok：继续扫描与集成。missing_token/missing_scope：引导用户在 API Tokens 创建 Custom token，权限为Account.Turnstile:Edit，并在 Account Resources 中包含目标账号。不要求用户把 token 粘贴到聊天；可提供「终端 export 后重启 Agent」或「写入仅用户可读文件」等方式。除非所用 Wrangler 版本的 OAuth scope 已包含Account.Turnstile:Edit，否则不要默认让用户wrangler login。network_failure/upstream_failure：按诊断处理网络或短暂重试，勿误判为 token 权限问题。multiple_accounts/account_mismatch：展示账号列表或修正CLOUDFLARE_ACCOUNT_ID。
从其他 CAPTCHA 迁移¶
扫描到 reCAPTCHA 或 hCaptcha 时，Step 7 改为展示迁移计划（细节见 Skill 内 “Migrating from another CAPTCHA” 小节），而不是仅做新建嵌入。
安装与启用¶
turnstile-spin 随 cloudflare/skills 插件或技能包安装；各 Agent 入口如下（摘自官方 README）。
Codex
codex plugin marketplace add cloudflare/skills
codex plugin add cloudflare@cloudflare
安装后新开 Codex 会话。
Claude Code
/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare
VS Code / GitHub Copilot
- 在设置中启用
chat.plugins.enabled。 - 命令面板执行 Chat: Install Plugin From Source。
- 填入
https://github.com/cloudflare/skills。
Cursor
从 Cursor Marketplace 安装，或在 Settings > Rules > Add Rule > Remote Rule (Github) 添加 cloudflare/skills。
npx skills
npx skills add https://github.com/cloudflare/skills
仅复制 Skill 目录
也可克隆仓库后将 turnstile-spin 等技能文件夹复制到 Agent 约定目录，例如 Cursor 为 ~/.cursor/skills/（完整表格见官方 README）。
Skills 按对话上下文自动加载；当请求匹配 Skill 的触发条件时，Agent 载入 turnstile-spin 并按 SKILL.md 执行。
典型用法¶
典型用法不是手写一长串配置，而是在支持 Agent Skills 的 IDE 或 CLI 里用自然语言发起集成，由 Skill 驱动脚本与改码。
示例 1：新站表单防刷
在已安装 Cloudflare 插件的 Cursor 中，可表述：「在这个 Next.js 项目里给注册表单加 Turnstile，并在 API 路由里做 siteverify。」Skill 会先确认端到端步骤，再跑 auth-probe.sh、扫描 App Router 结构、引用 references/nextjs-app.md，与用户确认注册域与插入点后创建或使用 widget，最后改前端与 API 并做验证。
示例 2：已有 sitekey
若 widget 已在控制台创建，对话中直接提供 sitekey（及后续步骤所需的 secret 配置方式按 Skill 指引），Agent 应跳过 widget 创建向导，进入「已有 widget」流程，只做嵌入与 siteverify。
示例 3：从 reCAPTCHA 迁移
说明「登录页现在是 reCAPTCHA，想换成 Turnstile」，扫描后会进入迁移模式，在确认插入点与 handler 映射后再替换前端与校验逻辑。
上述示例描述的是 Skill 文档声明的行为路径；具体命令输出与文件改动以你仓库扫描结果和用户确认为准。
适用场景与注意¶
适合谁
- 需要在现有前后端（非从零脚手架）里接入或修复 Turnstile 的团队。
- 使用 Next.js（App/Pages）、Astro、SvelteKit、Hugo 或纯 HTML 的项目。
- 希望 bot 防护落在注册、登录、联系表单、评论、下载按钮等用户触发请求上的场景。
限制与注意
- 必须有 Cloudflare API Token，且包含
Account.Turnstile:Edit；多账号需明确CLOUDFLARE_ACCOUNT_ID。 - Wrangler 仅在使用已批准的二进制且版本满足
turnstile widget子命令时用于创建 widget；流程不会自动安装 Wrangler，也不会用npx等方式执行带凭证命令。 - Token 不应出现在聊天或 shell history；Skill 文档给出了更安全的录入方式。
- 本地与生产域名同 widget 时，务必在后端按 hostname 严格校验 siteverify 结果，避免本地配置误用于生产白名单。
- 本 Skill 专注 Turnstile 集成，不替代 Turnstile 以外的 Cloudflare 产品配置。
Turnstile 本身在官方概述中说明：挑战在客户端完成，用于区分人与自动化流量；Managed 模式为推荐 widget 类型，并支持 Non-interactive、Invisible 等类型（创建向导示例使用 managed）。
结尾¶
turnstile-spin 把 Turnstile 从「文档 + 控制台 + 多处改代码」收敛成可确认的端到端流程：脚本负责 API 与探测，Agent 负责读库、选插入点、改前后端并在成功前做实机校验。若你正在 Cursor、Codex、Claude Code 或 VS Code Copilot 上开发需要 bot 防护的 Web 应用，安装 cloudflare/skills 后，用对话触发即可加载本 Skill。
Skill 目录与完整向导：https://github.com/cloudflare/skills/tree/main/skills/turnstile-spin
