流星雨人机验证 - 对接文档

快速开始

三种方式接入，最快只需一行代码

零 JS 接入 -- 最简方式

只需引入 loader.js 并添加一个容器，自动完成所有初始化工作。

<div data-captcha></div>
<script src="https://captcha.example.com/captcha/loader.js"></script>

loader.js 会自动扫描页面中所有 [data-captcha] 容器并初始化验证码组件。

注意：验证码组件需要至少 250px 宽度的容器空间。如果容器尺寸不足，会自动切换到全屏弹窗模式。

表单

表单自动集成

将验证码放在 form 内，会自动拦截表单提交，验证通过后自动注入隐藏字段。

<form action="/submit" method="POST">
  <input name="username" required>
  <div data-captcha></div>
  <button type="submit">提交</button>
</form>
<script src="https://captcha.example.com/captcha/loader.js"></script>

验证通过后会自动注入 <input type="hidden" name="captcha_token">。

API

JS API 调用

使用 Captcha.init() 进行精细控制，支持回调函数和 Promise。

<div id="my-captcha"></div>
<script src="https://captcha.example.com/captcha/loader.js"></script>
<script>
window.addEventListener('CaptchaLoaded', function() {
  const captcha = Captcha.init('#my-captcha', {
    onVerified: function(token) {
      console.log('验证成功:', token);
    },
    onError: function(err) {
      console.log('验证失败:', err);
    }
  });
});
</script>

Promise 方式

try {
  const result = await Captcha.verify('#my-captcha');
  console.log('验证成功:', result.token);
} catch (err) {
  console.log('验证失败:', err.message);
}

实时演示

前往在线演示

Android 接入

通过 Kotlin WebView SDK 复用验证页面，令牌由你的业务后端校验

Kotlin SDK

添加 SDK 模块

下载 Android SDK ZIP

解压后将 captcha-sdk/ 放入 Android 工程，并在 settings.gradle.kts 注册模块：

include(":captcha-sdk")
project(":captcha-sdk").projectDir = file("captcha-sdk")

在 App 模块添加依赖，并在 AndroidManifest.xml 声明网络权限：

dependencies {
    implementation(project(":captcha-sdk"))
}

<uses-permission android:name="android.permission.INTERNET" />

Activity Result

打开验证并接收结果

在 ComponentActivity 注册合约。成功时将 token 交给你的业务后端；取消和加载/验证失败分别处理：

private val captcha = registerForActivityResult(CaptchaContract("https://captcha.example.com")) { result ->
    when (result) {
        is CaptchaResult.Success -> submitToYourBackend(result.token)
        CaptchaResult.Cancelled -> showMessage("验证已取消")
        is CaptchaResult.Failure -> showMessage(result.message)
    }
}

// 用户点击需要保护的操作时
captcha.launch(Unit)

安全说明：请将示例地址换成自己的 HTTPS 服务来源；SDK 仅允许该来源，并通过受限消息桥传递结果。无参数时沿用原有默认域名。不要在 App 中放置服务端密钥，也不要仅凭客户端拿到 token 就放行业务操作。

服务端校验

后端验证一次性令牌

App 将 token 随业务请求发给你自己的后端。普通模式调用 POST /api/v1/check，快速模式调用 POST /api/v1/fast/check，仅当 success 和 data.valid 均为 true 时继续处理。该令牌一次性使用。

请求格式见 API 文档。仓库内还提供完整示例 App：sample/；构建需要 Gradle 8.13 和 JDK 17，命令为 gradle :sample:assembleDebug。

API 文档

接口字段格式与接入方法；以下类型描述不是实际请求数据

验证服务地址由接入方配置。JSON 请求需设置 Content-Type: application/json。建议使用 SDK 处理普通验证的挑战及可选加密。

POST

/api/v1/token — 创建普通验证会话

请求字段：deviceFingerprint（string，必填，至少 8 字符）；origin（string，可选，默认使用请求的 Origin）。

成功响应：success（boolean），data.token、data.targetImage、data.verificationType（string），data.encrypt（boolean），启用加密时可能返回 data.sessionKey。令牌需要完成验证后才能交给业务后端校验。

POST

/api/v1/verify — 提交普通验证

共同字段：token（string，必填）、origin（string，可选）、verifyType（string，滑动为 slider，算术为 math）。

滑动验证提交 sliderBehavior.duration（number，毫秒）及 sliderBehavior.trajectory（轨迹点数组，每点包含数值 x、y、t）。

算术验证先以 verifyType: 'math' 获取 data.questionId、data.questionImage 和 data.answerImage；再提交同一令牌、secondVerify: true、questionId 和 answer（含百分比坐标 x、y 的对象）。成功响应的 data.verified 为 true。

POST

/api/v1/check — 校验验证令牌

业务后端提交 token（string，必填），兼容普通及快速令牌。成功时 success 和 data.valid 均为 true，data.verificationType 为 normal 或 fast。校验成功会消费令牌；无效、未验证、过期或已使用时返回失败，不能仅按 HTTP 状态判断。

SDK

快速验证接入

现有网页组件默认优先快速验证，用户可通过“使用其他验证方式”切换滑动或数字计算；传入 mode: 'normal' 可直接显示手动验证选择。加载 /captcha/loader.js 并等待 CaptchaLoaded 后，也可调用 Captcha.verifyFast() 显示快速验证弹窗，或传入 { container: selectorOrElement } 在页面容器内显示。用户点击按钮后开始计算并显示进度。

<div id="fast-captcha"></div>
<script src="验证服务地址/captcha/loader.js"></script>
<script>
window.addEventListener('CaptchaLoaded', async () => {
  try {
    const result = await Captcha.verifyFast({ container: '#fast-captcha' });
    // 将 result.token 发送给自己的业务后端
  } catch (error) {
    if (error.code !== 'USER_CANCELLED') console.error(error);
  }
});
</script>

成功返回 token（string）、verified（boolean）和 verificationType（fast）；取消时 Promise 抛出 code === 'USER_CANCELLED'。失败时可在组件中重试。调用方将令牌发送给业务后端，由后端调用快速校验接口。

新版 Android SDK 默认 CaptchaMode.AUTO，优先快速验证并允许切换手动方式；FAST 和 NORMAL 分别固定快速和手动模式。成功后将 CaptchaResult.Success.token 交给业务后端。已安装旧 SDK 保持原有模式。快速验证需要 HTTPS 或 localhost、Web Worker 和 WASM。

POST

/api/v1/fast/check — 校验快速令牌

请求字段：token（string，必填，带 fast_ 前缀）；origin（string，可选，接入页面来源，建议由业务服务固定指定）。来源不匹配不会消费令牌。

成功响应包含 success: true、data.valid: true 和 data.verificationType: 'fast'。令牌有效期为五分钟，成功校验后只能使用一次。失败时 success 为 false；服务不可用还可能返回 HTTP 503。业务后端必须同时检查 HTTP 状态、success 和 data.valid。

快速令牌也可通过兼容接口 /api/v1/check 消费；普通令牌不能通过快速专用接口。业务服务应根据服务端返回的验证类型决定是否放行，不能信任客户端声明的类型。

POST

/api/v1/fast/challenge 与 /api/v1/fast/redeem — 底层协议

challenge 不要求请求字段；成功响应包含 challenge（对象，字段 c、s、d）、token（挑战令牌）和 expires（Unix 毫秒时间戳）。

redeem 提交 token（挑战令牌）和 solutions（计算结果数组）；成功响应包含 success、token（快速验证令牌）、expires 和 verificationType。挑战与请求来源绑定，且只能兑换一次。

无效请求返回 HTTP 400，请求过于频繁返回 429，服务不可用返回 503；失败信息在 error 中。推荐使用 SDK 自动处理挑战和计算。

配置选项

组件参数与 HTML 属性

组件配置

参数	类型	默认值	说明
`apiUrl`	string	加载器所在服务的来源	验证服务器地址，可显式覆盖
`theme`	string	`'light'`	主题：`'light'` 或 `'dark'`
`debug`	boolean	`false`	调试模式
`mock`	boolean	`false`	模拟模式（跳过真实验证）
`autoVerify`	boolean	`false`	是否自动验证
`onVerified`	function	-	验证成功回调
`onError`	function	-	验证失败回调

HTML 属性

属性	说明
`data-captcha`	标记为验证容器（必须）
`data-captcha-api`	API 地址
`data-captcha-theme`	主题：light / dark
`data-captcha-debug`	调试模式：true
`data-captcha-mock`	模拟模式：true
`data-captcha-onverified`	验证成功回调函数名
`data-captcha-onerror`	验证失败回调函数名

MCP 接入（给 Agent 用）

挂上 MCP Server，Agent 即可自行读取接入说明、生成代码并实测校验

配置

客户端配置项

在支持 MCP 的客户端（WorkBuddy / Claude Desktop / Cursor 等）的 MCP 配置中加入以下内容即可，无需安装任何本地脚本：

{
  "mcpServers": {
    "captcha": {
      "type": "http",
      "url": "https://captcha.example.com/mcp"
    }
  }
}

配置项	必填	说明
`type`	是	`http` —— Streamable HTTP，服务端网络接入
`url`	是	MCP 端点地址 `https://captcha.example.com/mcp`

该端点为无状态实现：只接受 POST（JSON-RPC 2.0），不提供服务端主动推送（GET 返回 405）；通知类消息返回 202。

工具

可用工具与参数

工具	参数	返回
`captcha_integration_guide`	`mode`：form / json / both（默认 both） `backend`：node / other（默认 node）	配置项、前端参数、两种提交方式的最小可运行代码、后端校验写法、`/api/v1/check` 全部返回结果
`captcha_verify_token`	`token`：前端验证通过后拿到的令牌	✅ 令牌有效 / ❌ 校验未通过：原因
`captcha_health`	无	服务可达性、HTTP 状态与延迟、版本、构建指纹、加密开关

典型用法：对 Agent 说「给这个注册页接入人机验证」，它会调用 captcha_integration_guide 取回代码并写入项目；说「验证服务正常吗」则调用 captcha_health。

注意：captcha_verify_token 会消费掉令牌（一次性语义），仅适合接入自测；正式业务必须由你自己的后端调用 /api/v1/check。

/api/v1/check 返回结果约定

业务结果以 success 字段判断；服务故障可能返回 HTTP 500：

success	message	业务处理
`true`	令牌验证通过	放行（令牌已被消费）
`false`	缺少验证令牌	400，提示重新验证
`false`	令牌不存在或已过期	400，提示重新验证（5 分钟有效期）
`false`	令牌未验证	400，提示完成验证
`false`	令牌已被使用	400，拒绝且不要重试（防重放机制生效）
`false`	无效的验证令牌	400，拒绝并记录告警（签名伪造 / 篡改）