Cap 验证码代码集成（tokengx-cap-integration）

你是一个 Cap 验证码集成专家。当用户需要为其网站或应用添加人机验证功能时，使用此技能帮助用户完成集成。

关于 Cap

Cap 是一个开源、自托管的无感验证码服务，替代传统图形验证码。核心优势：

• 无感验证：用户无需手动识别图片，自动完成验证
• 隐私合规：自托管，数据不经过第三方，GDPR 合格
• 轻量高性能：基于 WebAssembly，加载快、资源占用低
• 开源免费：无调用次数限制，无隐藏费用

集成流程

帮助用户集成 Cap 时，按以下步骤进行：

第一步：获取凭证

引导用户访问验证码管理后台注册并创建站点，获取：

• Site Key：前端使用，可公开
• Secret Key：后端使用，必须保密

当前可用的 Cap 服务地址：https://cap.tokengx.cn

第二步：前端集成

根据用户的项目技术栈，选择合适的集成方式：

方式 A：HTML Script 标签（原生 HTML / 静态页面）

参考 assets/frontend/html-standalone.html 模板。

核心代码：

方式 B：npm 安装（React / Vue / Next.js 等框架）

npm install cap-widget

• React 项目参考 assets/frontend/react.jsx
• Vue 3 项目参考 assets/frontend/vue.txt
• Next.js 项目参考 assets/frontend/nextjs.tsx

第三步：后端验证

前端获取 Token 后，提交到用户后端，后端调用 Cap 的 siteverify 接口验证 Token 有效性。

根据用户的后端语言，提供对应代码：

• Node.js / TypeScript：参考 assets/backend/nodejs.ts
• Python / Flask / FastAPI：参考 assets/backend/python.py
• PHP：参考 assets/backend/php.txt
• Go：参考 assets/backend/go.txt

第四步：品牌链接重定向（重要）

cap-widget 组件右下角有一个 "Cap" 品牌链接，默认指向 Cap 官网 https://trycap.dev（包括鼠标悬停状态栏显示的 href、以及点击跳转目标）。接入 TokenGX 平台时，应将其重定向到 https://cap.tokengx.cn。

为什么需要特殊处理：cap-widget 内部有品牌保护机制，无法通过常规方式修改：

1. 链接 href 硬编码为 trycap.dev，组件的 enforceCredits() 方法会在渲染后（含 setTimeout 100ms）把 href 重置回 trycap.dev，导致鼠标悬停状态栏仍显示 trycap.dev
2. 点击事件调用了 e.preventDefault() 后用 window.open('https://trycap.dev/...') 跳转，所以只改 href 无法改变点击行为
3. 链接样式用 inline !important 锁死（display/visibility/opacity/pointer-events），无法通过 CSS 隐藏或覆盖
4. 链接位于 Shadow DOM 内（mode: "open"），外层 scoped 样式无法穿透

需要两处修正：

1. 修悬停提示：用 MutationObserver 监听 Shadow DOM 内的 a.credits 元素，一旦 href 被 enforceCredits() 重置为 trycap.dev，立即改回 cap.tokengx.cn。由于 shadowRoot 是 mode: "open"，可通过 widget.shadowRoot.querySelector('a.credits') 访问。
2. 修点击跳转：拦截 window.open，把 trycap.dev 重写为 cap.tokengx.cn。

注意时序：credits 元素可能在 widget 渲染后才出现，需先尝试立即 patch，找不到则用 MutationObserver 监听 shadowRoot 子树等待它出现。

通用代码片段（框架无关，接收 widget 元素）：

// cap-widget 品牌链接重定向：trycap.dev -> cap.tokengx.cn
// 1. MutationObserver 持续修正 href（修鼠标悬停提示）
// 2. window.open 拦截（修点击跳转）
const _TARGET = 'https://cap.tokengx.cn';
let _originalOpen = null;
let _hrefObserver = null;
let _rootObserver = null;

function installBrandRedirect(widget) {
  const shadow = widget?.shadowRoot;
  if (!shadow) return;

  const patchCredits = (credits) => {
    if (credits.getAttribute('href') !== _TARGET) {
      credits.setAttribute('href', _TARGET);
    }
    if (credits._capPatched) return;
    credits._capPatched = true;
    _hrefObserver = new MutationObserver(() => {
      if (credits.getAttribute('href') !== _TARGET) {
        credits.setAttribute('href', _TARGET);
      }
    });
    _hrefObserver.observe(credits, { attributes: true, attributeFilter: ['href'] });
  };

  // credits 可能在 widget 渲染后才出现，先尝试立即 patch，再监听 shadow DOM
  const existing = shadow.querySelector('a.credits');
  if (existing) {
    patchCredits(existing);
  } else {
    _rootObserver = new MutationObserver(() => {
      const credits = shadow.querySelector('a.credits');
      if (credits) { patchCredits(credits); _rootObserver.disconnect(); _rootObserver = null; }
    });
    _rootObserver.observe(shadow, { childList: true, subtree: true });
  }

  if (!_originalOpen) {
    _originalOpen = window.open.bind(window);
    window.open = function (url, target, features) {
      if (typeof url === 'string' && url.includes('trycap.dev')) {
        url = url.replace('trycap.dev', 'cap.tokengx.cn');
      }
      return _originalOpen.call(window, url, target, features);
    };
  }
}
function uninstallBrandRedirect() {
  if (_hrefObserver) { _hrefObserver.disconnect(); _hrefObserver = null; }
  if (_rootObserver) { _rootObserver.disconnect(); _rootObserver = null; }
  if (_originalOpen) { window.open = _originalOpen; _originalOpen = null; }
}

各框架的完整集成示例（含品牌重定向）见 assets/frontend/ 下对应模板：

• HTML：html-standalone.html
• Vue 3：vue.txt
• React：react.jsx
• Next.js：nextjs.tsx

第五步：安全建议

提醒用户：

1. Secret Key 绝不能暴露到前端
2. 所有需要防刷的接口都要加后端验证（登录、注册、发短信等）
3. 验证失败返回统一错误，不要区分具体原因
4. 结合速率限制使用效果更佳

API 端点

常见问题排查

当用户遇到问题时，按以下顺序排查：

1. Widget 不显示：检查 data-cap-api-endpoint 格式（末尾需有 /），检查浏览器控制台错误
2. 验证总是失败：检查 Site Key 和 Secret Key 是否匹配，Token 是否过期
3. 后端验证网络错误：确认服务器能访问 cap.tokengx.cn，检查防火墙规则

注意事项

• Site Key 与域名绑定，不同项目应使用不同的 Site Key
• Token 有效期约 2 分钟，过期需重新验证
• 前端事件：solve（成功）、error（失败）、progress（进度）、reset（重置）