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

## Overview

Use this skill to integrate Geelab Captcha v4 into an existing user project. This is an execution-first workflow: by default, analyze the project, choose the target platform, modify code, update client-side configuration, provide validation steps, and clearly report any remaining user actions.

Use the official Geelab documentation links below as the source of truth. Do not invent SDK parameters, callback fields, package names, or platform APIs.

## Official Documentation

- Base docs: https://docs.geelab.tech/en
- Product overview: https://docs.geelab.tech/en/docs/product-introduction
- Quick start: https://docs.geelab.tech/en/docs/getting-started
- Region selection: https://docs.geelab.tech/en/docs/region-selection
- Web deployment: https://docs.geelab.tech/en/docs/deployment/web
- iOS deployment: https://docs.geelab.tech/en/docs/deployment/ios
- Android deployment: https://docs.geelab.tech/en/docs/deployment/android
- Web API reference: https://docs.geelab.tech/en/docs/api-reference/web
- Server deployment: https://docs.geelab.tech/en/docs/deployment/server
- Server API reference: https://docs.geelab.tech/en/docs/api-reference/server
- Fallback plan: https://docs.geelab.tech/en/docs/fallback-plan
- FAQ: https://docs.geelab.tech/en/docs/faq
- Compliance: https://docs.geelab.tech/en/docs/compliance

## Contract

- Supported product: Geelab Captcha v4
- Supported platforms: Web/H5, iOS, Android
- Default behavior: directly implement client-side integration in the current project
- Missing `captchaId`, region or Web SDK product configuration must not block Web integration; use safe placeholders and report them at the end
- Secret values must never be written into Web, iOS, or Android client source code
- If multiple high-risk business integration points are possible, ask the user to choose before modifying business flow code

## Required User Inputs

The user may provide only partial information. Apply the default rules for missing values.

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

Region values must strictly follow the official Geelab Region Selection documentation:

- `global`: Global region, for example `cap-global.geelabapi.com`
- `eu`: Europe region, for example `cap-eu.geelabapi.com`
- `na`: North America region, for example `cap-na.geelabapi.com`

Default placeholders:

- Web public ID: `NEXT_PUBLIC_GEELAB_CAPTCHA_ID=YOUR_CAPTCHA_ID`
- Region: `GEELAB_REGION=global`
- Web SDK `product` 展示模式：`NEXT_PUBLIC_GEELAB_CAPTCHA_PRODUCT=float`

## Workflow

### Phase 1: Identify the Project and Target Platform

1. Scan the project type:
   - 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. Determine the product line:
   - Always use Captcha v4
3. Determine the platform:
   - If the user explicitly specifies a platform, follow the user choice
   - For Web projects, default to the Web SDK
   - For iOS or Android projects, default to the matching native SDK

### Phase 2: Collect or Placeholder Configuration

1. If the user provides ID or region values:
   - Use those values in environment examples or configuration loading code
2. If values are missing:
   - Do not stop the integration
   - Use placeholders such as `YOUR_CAPTCHA_ID`
   - Update `.env.example` or the equivalent sample configuration
   - Include a final "variables to replace" list
3. Configuration placement rules:
   - `NEXT_PUBLIC_GEELAB_CAPTCHA_ID` may be exposed to Web frontend code
   - Secrets must not enter Web, iOS, or Android client source code
   - iOS and Android may use non-secret public IDs

### Phase 3: Determine the Integration Point

The integration point must be requested or confirmed first, but the workflow should not stall indefinitely.

1. If the user did not specify an integration point, ask where they want Captcha inserted:
   - login
   - register / signup
   - submit form
   - payment
   - sendSms
   - custom
2. If the user already specified the integration point, use that location.
3. If the user does not answer or asks for automatic detection, scan code and prioritize:
   - 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. If exactly one high-confidence integration point is found:
   - Integrate there directly
   - In the final response, state that the integration point was inferred from code
5. If multiple candidate points are found:
   - Do not modify business flow code
   - Output the candidate list and ask the user to choose
   - Each candidate must include file path, function/component name, triggering event, and recommendation rationale
6. If no integration point is found:
   - Generate a standalone wrapper module
   - Do not wire it into business flow code
   - Tell the user exactly where to call it

Hard rule: never choose arbitrarily among multiple business flows. Only modify business code when there is a single high-confidence integration point.

### Phase 4: Read Official Docs and Plan the Implementation

1. Select the official documentation URL based on the detected platform:
   - Web: https://docs.geelab.tech/en/docs/deployment/web
   - iOS: https://docs.geelab.tech/en/docs/deployment/ios
   - Android: https://docs.geelab.tech/en/docs/deployment/android
2. If network access is available, read the official documentation page and extract:
   - SDK loading or installation method
   - initialization parameters
   - success/failure callbacks
   - region/API configuration
   - fallback and error-handling requirements
3. If official docs are unavailable:
   - Do not invent unknown API details
   - Only complete project-structure analysis and safe wrapper placeholders
   - Clearly list SDK/API details that require user confirmation
4. For iOS or Android, check local SDK files before code integration:
   - iOS: search the project for `GeeLabCaptcha.xcframework`
   - iOS: also search for both `GeeLabCaptcha.bundle` and `GeeLabCaptcha.Bundle`
   - Android: search the project for `geelab_captcha_android_*.aar`
   - If the SDK file is missing, do not fabricate dependency paths
   - When an SDK file is missing, stop the code integration flow and only report search results plus recommended placement

### Phase 5: Implement Client-Side Integration

#### Web/H5

- Implement SDK loading and initialization based on the official Web documentation
- First detect the framework, language, directory conventions, and existing code style
- Create or update a Captcha wrapper module that follows the project's framework conventions
- Run Captcha before the selected business action; continue only on success, block submission and show an error on failure
- Support official Web SDK `product` values: `bind`, `float`, `popup`
- Default to `float` when the user does not specify a display mode
- Use `bind` or `popup` only when the project already has a fixed Captcha container or the user explicitly requests button binding

#### iOS

- First search for `GeeLabCaptcha.xcframework`
- Also search for the Geelab resource bundle using both common names:
  - `GeeLabCaptcha.bundle`
  - `GeeLabCaptcha.Bundle`
- If `GeeLabCaptcha.xcframework` does not exist, stop integration and ask the user to download the iOS SDK and drag/copy it into the project directory
- If neither `GeeLabCaptcha.bundle` nor `GeeLabCaptcha.Bundle` exists, stop integration and ask the user to add the resource bundle from the SDK package
- Before the SDK files exist, do not claim build configuration is complete
- If SDK files are missing, do not create or modify SDK wrapper classes
- If SDK files are missing, do not modify login, registration, payment, SMS, or other business integration points
- If SDK files are missing, do not modify Xcode SDK dependency configuration
- If SDK files are missing, do not claim Captcha is deployed, integrated, configured, or triggerable
- If SDK files exist, follow the official iOS documentation to add `GeeLabCaptcha.xcframework` to the target framework settings, including `Linked Frameworks and Libraries` or equivalent target configuration
- Add the Geelab resource bundle to the target resource configuration, such as Copy Bundle Resources when required by the project
- Check required system frameworks from the official documentation, including `WebKit.framework` when applicable
- Add `-ObjC` to Other Linker Flags if required by the official documentation and project setup
- Create or update a project-conventional local wrapper, for example `GeelabCaptchaService.swift`
- The wrapper name and method names are local integration examples, not official SDK API names. Use the official SDK API from the documentation when implementing the wrapper
- Call the wrapper only from a single high-confidence button or flow; wait for user choice when multiple candidates exist

##### iOS SDK Completion Standard

Do not treat Xcode project-file edits alone as completion. A complete iOS integration must first pass SDK file checks, then target configuration and build validation.

Pre-build checks must verify:

- `GeeLabCaptcha.xcframework` exists
- A usable `GeeLabCaptcha.framework` exists inside `GeeLabCaptcha.xcframework`
- At least one Geelab resource bundle exists:
  - `GeeLabCaptcha.bundle`
  - `GeeLabCaptcha.Bundle`
- If the framework or resource bundle is missing, stop integration and only report missing files plus recommended placement

After SDK files exist, verify:

- `GeeLabCaptcha.xcframework` is added to the target framework configuration required by the official docs
- The Geelab resource bundle is added to the app target resources
- Required system dependencies, such as `WebKit.framework` when applicable, are configured
- Required linker flags, such as `-ObjC` when applicable, are configured
- `xcodebuild clean build` succeeds when the local environment supports it

#### Android

- First search for `geelab_captcha_android_*.aar`
- The official Android SDK AAR package name follows this format: `geelab_captcha_android_XXXXXX.aar`, where `XXXXXX` is a version or build identifier
- If the AAR file does not exist, stop the code integration flow and only report search results plus recommended placement
- If the SDK is missing, do not create or modify `GeelabCaptchaManager.kt`
- If the SDK is missing, do not modify login, registration, payment, SMS, or other business integration points
- If the SDK is missing, do not modify Gradle SDK dependency configuration
- If the SDK is missing, do not claim Captcha is deployed, integrated, configured, or triggerable
- If the SDK is missing, ask the user to download the Android SDK and drag/copy `geelab_captcha_android_XXXXXX.aar` into the Android project directory
- If an AAR exists, do not immediately assume SDK dependencies are complete
- Continue checking whether the current project includes runtime dependencies required by the AAR
- Android dependency detection standard:
  - Gradle declares a local AAR dependency, such as `implementation files("libs/geelab_captcha_android_XXXXXX.aar")`, or an equivalent `flatDir` / `implementation(name: ..., ext: "aar")` setup
  - Kotlin standard library is available, such as `org.jetbrains.kotlin:kotlin-stdlib`, `kotlin-stdlib-jdk7`, `kotlin-stdlib-jdk8`, or an equivalent Kotlin Gradle plugin/BOM setup
  - Pure Java Android projects must still verify that the Kotlin runtime required by the AAR is packaged into the app
  - If dependencies are missing, only add or report the missing Gradle runtime dependency before claiming Android SDK integration is complete
- After the AAR file and runtime dependencies are satisfied, integrate Gradle dependencies or point out the required local SDK/AAR placement
- Create or update `GeelabCaptchaManager.kt`
- The wrapper name and method names are local integration examples, not official SDK API names. Use the official SDK API from the documentation when implementing the wrapper
- Call the wrapper only from a single high-confidence click or submit flow; wait for user choice when multiple candidates exist
- Check `AndroidManifest.xml`, ProGuard/R8 rules, error callbacks, and lifecycle impact

### Phase 6: Validate

Run the lowest-risk practical validation for the detected project type:

- Web: start the local dev server, open the relevant flow in a browser, and inspect console plus network behavior
- iOS: follow the iOS SDK completion standard, including SDK file checks, target framework configuration, target resource configuration, required system dependencies, required linker flags, and `xcodebuild clean build` when supported
- Android: confirm AAR and Kotlin/runtime dependency checks first, then run the lowest-cost available Gradle sync/test/assemble command

If validation cannot be run, explain why and provide exact commands for the user to run.

### Phase 7: Final Output

The final response must include:

- Completed integration scope: product line, platform, and integration point
- Modified file list
- Added or changed environment variables
- Variables the user must replace
- iOS/Android SDK file detection result, and if missing, the exact SDK files that must be downloaded and dragged/copied into the project
- Server-side secondary verification reminder: this skill does not implement server-side code by default, but critical business flows should add secondary verification later; `GEELAB_CAPTCHA_KEY` belongs only in server-side environment variables and must not enter Web, iOS, or Android client source code
- Whether fallback/error handling was implemented
- Local validation results or validation commands
- Remaining questions that require user confirmation

## Fallback Module Strategy

When no business integration point is found, create a standalone wrapper module by platform. Do not create arbitrary files. First identify the current framework, language, directory structure, and existing code style, then follow that framework's conventions.

- Web:
  - Identify framework first: Next.js, Vite React, Vue, Nuxt, plain HTML/JS, or other
  - Identify language first: TypeScript or JavaScript
  - Identify directory conventions first: existing `src/lib`, `src/utils`, `src/services`, `app/`, `composables/`, `plugins/`, or equivalent
  - Next.js: prefer a client-only module such as `geelabCaptcha.ts` under the existing `lib/` or `src/lib/`; callers must be client components or browser event handlers
  - Vite React: prefer the existing `src/lib/`, `src/utils/`, or `src/services/`; export a hook or plain function according to project style
  - Vue/Nuxt: prefer existing `composables/`, `plugins/`, or `src/utils/`; naming and exports must follow project conventions
  - Plain HTML/JS: prefer existing `assets/js/`, `src/`, or the current script directory; do not assume a build tool
  - If framework or directory conventions cannot be determined, output candidate approaches and ask the user before creating files
- iOS: use a project-conventional wrapper name, for example `GeelabCaptchaService.swift`
- Android: use a project-conventional wrapper name, for example `GeelabCaptchaManager.kt`

The wrapper module must include a usage example that tells the user where to call it before login, registration, payment, SMS sending, or form submission.

## Key Principles

1. Directly modify code by default; do not stop at advice.
2. Missing variables do not block integration. Use placeholder environment variables and remind the user to replace them.
3. Secrets never enter Web, iOS, or Android client source code.
4. Do not implement server-side code by default, but the final response must mention secondary verification and safe handling of `GEELAB_CAPTCHA_KEY`.
5. Ask the user to choose when multiple integration points exist.
6. Prioritize official docs; never fabricate SDK/API details.
7. Preserve a verifiable path so the user can run the project immediately.
8. Web SDK `product`  defaults to `float` unless the user specifies otherwise or the project clearly fits `bind`/`popup`.
9. Missing iOS/Android local SDK files are a hard stop: only report search results and recommended placement; do not create wrappers, modify business code, or change Xcode/Gradle dependency configuration.
10. Web fallback modules must match the current framework, language, and directory style. Ask first when those conventions cannot be determined.