Geelab Captcha Skill

---
name: geelab-captcha-skill
description: Use when integrating Geelab Captcha v4 into an existing Web, iOS, or Android project and the user wants the agent to directly implement the client-side product integration in code
---

# Geelab Captcha Skill

## 概述

用于把 Geelab Captcha v4 接入到已有用户项目中。这个 skill 是强执行型 workflow：默认要分析项目、判断目标端侧、修改代码、更新客户端配置、给出验证步骤，并清楚列出仍需用户处理的事项。

以下 Geelab 官方文档链接是实现依据。不要凭空编造 SDK 参数、回调字段、包名或平台 API。

## 官方文档

- 文档首页：https://docs.geelab.tech/zh
- 产品介绍：https://docs.geelab.tech/zh/docs/product-introduction
- 快速开始：https://docs.geelab.tech/zh/docs/getting-started
- 区域选择：https://docs.geelab.tech/zh/docs/region-selection
- Web 接入：https://docs.geelab.tech/zh/docs/deployment/web
- iOS 接入：https://docs.geelab.tech/zh/docs/deployment/ios
- Android 接入：https://docs.geelab.tech/zh/docs/deployment/android
- Web API 参考：https://docs.geelab.tech/zh/docs/api-reference/web
- 服务端接入：https://docs.geelab.tech/zh/docs/deployment/server
- 服务端 API 参考：https://docs.geelab.tech/zh/docs/api-reference/server
- 降级方案：https://docs.geelab.tech/zh/docs/fallback-plan
- 常见问题：https://docs.geelab.tech/zh/docs/faq
- 合规说明：https://docs.geelab.tech/zh/docs/compliance

## 契约

- 支持产品：Geelab Captcha v4
- 支持端侧：Web/H5、iOS、Android
- 默认行为：在当前项目中直接完成客户端接入代码改造
- 缺少 `captchaId`、region等配置时，不阻塞 Web 接入；使用安全占位变量继续，并在最后提醒用户替换
- secret 类变量绝不能写入 Web、iOS 或 Android 客户端源码
- 如果存在多个高风险业务接入点，必须先让用户选择，再修改业务流程代码

## 用户可提供的信息

用户可以只提供部分信息。缺失信息按默认规则处理。

- `product`: `captcha-v4`
- `platform`: `web` | `ios` | `android` | `auto`
- `integration_point`: `login` | `register` | `signup` | `submit` | `payment` | `sendSms` | custom
- `captchaId`
- `region`: `global` | `eu` | `na`

region 取值必须严格遵循 Geelab 官方 Region Selection 文档：
- `global`：Global 区域，例如 `cap-global.geelabapi.com`
- `eu`：Europe 区域，例如 `cap-eu.geelabapi.com`
- `na`：North America 区域，例如 `cap-na.geelabapi.com`

默认占位变量：

- Web public ID：`NEXT_PUBLIC_GEELAB_CAPTCHA_ID=YOUR_CAPTCHA_ID`
- Region：`GEELAB_REGION=global`
- Web Captcha display mode：`NEXT_PUBLIC_GEELAB_CAPTCHA_DISPLAY=float`

## 工作流

### 第一阶段：识别项目和目标端侧

1. 扫描项目类型：
   - Web：`package.json`、`vite.config.*`、`next.config.*`、`src/`、`app/`、`pages/`
   - iOS：`.xcodeproj`、`.xcworkspace`、`Podfile`、`Package.swift`、`.swift`、`.m`
   - Android：`settings.gradle*`、`build.gradle*`、`AndroidManifest.xml`、`app/src/main`
2. 判断产品线：
   - 固定为 Captcha v4
3. 判断端侧：
   - 用户明确指定时，以用户为准
   - Web 项目默认接 Web SDK
   - iOS/Android 项目默认接对应原生 SDK

### 第二阶段：获取或占位配置

1. 如果用户提供了 ID 或 region：
   - 使用用户值更新环境变量示例或配置读取逻辑
2. 如果用户没有提供：
   - 不停止接入
   - 使用 `YOUR_CAPTCHA_ID` 等占位值
   - 更新 `.env.example` 或等价示例配置
   - 最终输出“待用户替换变量清单”
3. 配置放置规则：
   - `NEXT_PUBLIC_GEELAB_CAPTCHA_ID` 可以暴露给 Web 前端
   - secret 不能进入 Web、iOS 或 Android 客户端源码
   - iOS/Android 可使用非 secret 的 public ID

### 第三阶段：确定接入点

接入点必须先询问或确认，但不能无限阻塞。

1. 如果用户未指定接入点，先问用户希望接入在哪个业务点：
   - login
   - register / signup
   - submit form
   - payment
   - sendSms
   - custom
2. 如果用户已经说明接入点，直接按用户指定位置处理。
3. 如果用户没有回答或要求自动判断，扫描代码并优先查找：
   - Web：`login`、`signIn`、`signin`、`register`、`signup`、`submit`、`handleSubmit`、`payment`、`checkout`、`pay`、`createOrder`、`sendSms`、`sendCode`、`sendOtp`
   - iOS：`loginButtonTapped`、`registerButtonTapped`、`submitButtonTapped`、`sendSms`、`payment`、`verify`
   - Android：`onLoginClick`、`onRegisterClick`、`onSubmit`、`sendSms`、`checkout`、`payment`
4. 如果只找到一个高置信接入点：
   - 直接接入
   - 最终说明“已根据代码推断接入到 xxx”
5. 如果找到多个候选点：
   - 不直接修改业务流程
   - 输出候选列表，请用户选择
   - 候选项必须包含文件路径、函数名/组件名、触发事件和推荐理由
6. 如果找不到接入点：
   - 生成独立封装模块
   - 不接入业务流程
   - 明确告诉用户在哪调用

强规则：不要在多个候选业务流程中擅自选择；只有单一高置信接入点才直接改业务代码。

### 第四阶段：读取官方文档并制定实现方案

1. 根据识别到的端侧选择官方文档 URL：
   - Web：https://docs.geelab.tech/zh/docs/deployment/web
   - iOS：https://docs.geelab.tech/zh/docs/deployment/ios
   - Android：https://docs.geelab.tech/zh/docs/deployment/android
2. 如当前环境可联网，读取官方文档页面并提取：
   - SDK 引入或安装方式
   - 初始化参数
   - success/failure callback
   - region/API 配置
   - fallback 和错误处理要求
3. 如无法访问官方文档：
   - 不编造未知 API 细节
   - 只完成项目结构分析和安全封装占位
   - 明确列出待用户确认的 SDK/API 细节
4. 如果端侧是 iOS 或 Android，先检测本地 SDK 文件：
   - iOS：在项目中搜索 `GeeLabCaptcha.xcframework`
   - iOS：同时搜索 `GeeLabCaptcha.bundle` 或者 `GeeLabCaptcha.Bundle`
   - Android：在项目中搜索 `geelab_captcha_android_*.aar`
   - 如果 SDK 文件不存在，不要伪造依赖路径
   - SDK 文件缺失时必须停止代码接入流程，只报告搜索结果和建议放置路径

### 第五阶段：客户端代码接入

#### Web/H5

- 根据官方 Web 文档接入 SDK 加载和初始化
- 先判断当前 Web 项目使用的框架、语言、目录规范和既有代码风格
- 生成或更新符合项目框架规范的 Captcha 封装模块
- 在选定业务动作前置 Captcha 验证；成功后继续原业务流程，失败时阻止提交并显示错误
- 支持官方 Web SDK `product` 取值：`bind`、`float`、`popup`
- 用户未指定 `product` 时默认使用 `float`
- 如果项目已有固定验证码容器或用户明确指定按钮绑定，再使用 `bind` 或 `popup`

#### iOS

- 先搜索 `GeeLabCaptcha.xcframework`
- 同时用以下两个常见名称搜索 Geelab resource bundle：
  - `GeeLabCaptcha.bundle`
  - `GeeLabCaptcha.Bundle`
- 如果 `GeeLabCaptcha.xcframework` 不存在，必须停止接入，并提示用户下载 iOS SDK 后将其拖拽/复制到工程目录下
- 如果 `GeeLabCaptcha.bundle` 和 `GeeLabCaptcha.Bundle` 都不存在，必须停止接入，并提示用户从 SDK 包中添加 resource bundle
- 在 SDK 文件存在前，不要声称编译配置已完成
- SDK 文件缺失时禁止创建或修改 SDK 封装类
- SDK 文件缺失时禁止修改登录、注册、支付、短信发送等业务接入点
- SDK 文件缺失时禁止修改 Xcode SDK 依赖配置
- SDK 文件缺失时禁止声称验证码已部署、已接入、已配置完成或可正常触发
- SDK 文件存在后，按照官方 iOS 文档将 `GeeLabCaptcha.xcframework` 加入 target framework 配置，包括 `Linked Frameworks and Libraries` 或项目等价配置
- 将 Geelab resource bundle 加入 target resource 配置，例如项目需要时加入 Copy Bundle Resources
- 检查官方文档要求的系统 framework，例如适用时的 `WebKit.framework`
- 如果官方文档和项目配置要求，给 Other Linker Flags 添加 `-ObjC`
- 创建或更新符合项目规范的本地封装，例如 `GeelabCaptchaService.swift`
- 封装类名和方法名只是本地接入示例，不是官方 SDK API 名称；实现封装时必须使用官方文档中的 SDK API
- 只在单一高置信按钮或流程中调用封装；多个候选时等待用户选择

##### iOS SDK 接入完成标准

不能只以 Xcode 工程文件修改为完成标准。完整 iOS 接入必须先通过 SDK 文件检查，再进行 target 配置和构建验证。

构建前必须验证：

- `GeeLabCaptcha.xcframework` 存在
- `GeeLabCaptcha.xcframework` 内部存在可用的 `GeeLabCaptcha.framework`
- 至少存在一个 Geelab resource bundle：
  - `GeeLabCaptcha.bundle`
  - `GeeLabCaptcha.Bundle`
- 如果 framework 或 resource bundle 缺失，必须停止接入，只报告缺失文件和建议放置路径

SDK 文件存在后，必须验证：

- `GeeLabCaptcha.xcframework` 已加入官方文档要求的 target framework 配置
- Geelab resource bundle 已加入 App target resources
- 官方要求的系统依赖已配置，例如适用时的 `WebKit.framework`
- 官方要求的 linker flags 已配置，例如适用时的 `-ObjC`
- 本地环境支持时，`xcodebuild clean build` 成功

#### Android

- 先搜索 `geelab_captcha_android_*.aar`
- 官方 Android SDK AAR 包名格式为：`geelab_captcha_android_XXXXXX.aar`，其中 `XXXXXX` 是版本号或构建标识等可变部分
- 如果 AAR 文件不存在，必须停止代码接入流程，只报告搜索结果和建议放置路径
- SDK 缺失时禁止创建或修改 `GeelabCaptchaManager.kt`
- SDK 缺失时禁止修改登录、注册、支付、短信发送等业务接入点
- SDK 缺失时禁止修改 Gradle SDK 依赖配置
- SDK 缺失时禁止声称验证码已部署、已接入、已配置完成或可正常触发
- SDK 缺失时提示用户下载 Android SDK，并将 `geelab_captcha_android_XXXXXX.aar` 拖拽/复制到 Android 工程目录下
- 如果 AAR 存在，不能立即认为 SDK 依赖已完成
- 必须继续检查当前项目是否已包含 AAR 所需运行时依赖
- Android 依赖检测标准：
  - Gradle 已声明本地 AAR 依赖，例如 `implementation files("libs/geelab_captcha_android_XXXXXX.aar")`，或等价 `flatDir` / `implementation(name: ..., ext: "aar")` 配置
  - Kotlin 标准库可用，例如 `org.jetbrains.kotlin:kotlin-stdlib`、`kotlin-stdlib-jdk7`、`kotlin-stdlib-jdk8`，或等价 Kotlin Gradle plugin/BOM 配置
  - 纯 Java Android 项目也必须确认 AAR 所需 Kotlin runtime 会被打包进 App
  - 如果依赖缺失，只能补充或报告缺失的 Gradle runtime 依赖，不能声称 Android SDK 接入已完成
- AAR 文件和运行时依赖都满足后，才接入 Gradle 依赖或指出本地 SDK/AAR 放置方式
- 创建或更新 `GeelabCaptchaManager.kt`
- 封装类名和方法名只是本地接入示例，不是官方 SDK API 名称；实现封装时必须使用官方文档中的 SDK API
- 只在单一高置信点击或提交流程中调用封装；多个候选时等待用户选择
- 检查 `AndroidManifest.xml`、ProGuard/R8 规则、错误回调和生命周期影响

### 第六阶段：验证

按项目类型执行最低风险且可行的验证：

- Web：启动本地服务，用浏览器走对应流程，检查 console 和 network 行为
- iOS：按 iOS SDK 接入完成标准检查 SDK 文件、target framework 配置、target resource 配置、系统依赖、linker flags，并在环境支持时运行 `xcodebuild clean build`
- Android：先确认 AAR 和 Kotlin/runtime 依赖检查，再运行 Gradle sync/test/assemble 中可用的最低成本命令

如果无法运行验证，说明原因并给出用户可执行命令。

### 第七阶段：最终输出

最终回复必须包含：

- 已完成的接入范围：产品线、端侧、接入点
- 修改文件清单
- 新增或变更的环境变量
- 待用户替换变量清单
- iOS/Android SDK 文件检测结果；如缺失，列出需要下载并拖入/复制到工程的文件名
- 服务端二次校验提示：本 skill 默认不实现 server 相关代码，但关键业务建议后续接入二次校验；`GEELAB_CAPTCHA_KEY` 用于保存官方服务端 `captcha_key`, 只能放在服务端环境变量中，不能进入 Web、iOS 或 Android 客户端源码
- fallback/error handling 是否已处理
- 本地验证结果或验证命令
- 仍需用户确认的问题

## Fallback Module Strategy

找不到业务接入点时，按平台生成独立封装模块。不能随意创建文件，必须先判断当前项目的框架、语言、目录结构和既有代码风格，再按框架规范生成。

- Web：
  - 先识别框架：Next.js、Vite React、Vue、Nuxt、普通 HTML/JS 或其他
  - 先识别语言：TypeScript 或 JavaScript
  - 先识别目录规范：`src/lib`、`src/utils`、`src/services`、`app/`、`composables/`、`plugins/` 等项目既有约定
  - Next.js：优先生成 client-only 模块，例如既有 `lib/` 或 `src/lib/` 下的 `geelabCaptcha.ts`，调用侧必须位于 client component 或浏览器事件中
  - Vite React：优先放入既有 `src/lib/`、`src/utils/` 或 `src/services/`，导出 hook 或 plain function 取决于项目已有风格
  - Vue/Nuxt：优先放入既有 `composables/`、`plugins/` 或 `src/utils/`，命名和导出方式跟随项目约定
  - 普通 HTML/JS：优先放入既有 `assets/js/`、`src/` 或当前脚本目录，避免引入构建工具假设
  - 如果无法判断框架或目录规范，只输出候选方案并询问用户，不直接创建文件
- iOS：使用符合项目规范的封装名，例如 `GeelabCaptchaService.swift`
- Android：使用符合项目规范的封装名，例如 `GeelabCaptchaManager.kt`

封装模块必须附带调用示例，告诉用户在登录、注册、支付、短信发送或表单提交前调用。

## Key Principles

1. 默认直接改代码，不只给建议。
2. 缺变量不阻塞，用占位环境变量继续接入，并在最终输出提醒替换。
3. secret 永远不进入 Web、iOS 或 Android 客户端源码。
4. 默认不实现 server 相关代码，但最终必须提示服务端二次校验和 `GEELAB_CAPTCHA_KEY` 的安全放置要求。
5. 多个候选接入点时必须让用户选，不能擅自接到错误业务流程。
6. 官方文档优先；不确定 SDK/API 细节时不要编造。
7. 每次接入都要保留可验证路径，让用户能马上跑起来。
8. Web SDK `product` 默认 `float`，除非用户指定或项目结构明显更适合 `bind`/`popup`。
9. iOS/Android 本地 SDK 文件缺失时必须强停止，只报告搜索结果和建议放置路径，不创建封装类、不改业务接入点、不改 Xcode/Gradle 依赖配置。
10. Web fallback 模块必须符合当前框架、语言和目录风格；无法判断时先问用户。