前言¶
註冊、登錄、聯繫表單、評論提交——凡是用戶觸發的寫操作，都容易被腳本批量撞庫或刷垃圾數據。常見做法是前端掛 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
