{"skill":{"slug":"captcha-base-skill","displayName":"captcha-base-skill","summary":"免费优先的验证码基础能力 Skill。默认本地识别，复杂场景可切换低价云码兜底。适用于 OpenClaw/ClawHub、浏览器自动化与 RPA 场景。","description":"---\nname: captcha-skill\ndescription: 免费优先的验证码基础能力 Skill。默认本地识别，复杂场景可切换低价云码兜底。适用于 OpenClaw/ClawHub、浏览器自动化与 RPA 场景。\n---\n\n# 验证码基础能力 Skill\n\n这是一个面向公共场景的验证码基础能力 Skill，目标很直接：\n\n- 常见验证码，优先用本地免费能力解决\n- 本地不稳或题型复杂时，再切到低价云码兜底\n- 让调用方尽量只关心“要识别什么”，而不是先研究一堆接口细节\n\n它更适合被当成一个公共底层能力来用，而不是单一网站的定制脚本。\n\n## 给 Agent 的最短说明\n\n如果你是另一个 Skill 或 Agent，请先按下面规则使用：\n\n1. 默认入口用 `JfbymClient.solve_auto_fallback(...)`\n2. 简单文本、算术、基础滑块，默认 `prefer=\"free\"`\n3. 点选、九宫格、空间推理、旋转、ReCaptcha、hCaptcha，优先直接走付费接口\n4. 输入支持三种形式：文件路径、`bytes`、base64 字符串\n5. 成功结果优先读取返回值里的 `result` 或云码接口 `data`\n\n最常用入口：\n\n- 文本：`solve_auto_fallback(task=\"text\", image_input=...)`\n- 算术：`solve_auto_fallback(task=\"math\", image_input=...)`\n- 滑块：`solve_auto_fallback(task=\"slide\", back_image_input=..., slide_image_input=...)`\n- 复杂题型：`solve_common(...)` / `solve_slide(...)`\n\n如果你只需要模块选择：\n\n- 只要本地免费能力：`local_captcha.py`\n- 只要云码 SDK：`jfbym_sdk.py`\n- 想自动兜底、保留兼容入口、或直接用 CLI：`jfbym_api.py`\n\n## 云端与隐私说明\n\n这部分请在调用前明确理解：\n\n- 本地免费能力不需要 `JFBYM_TOKEN`\n- `JFBYM_TOKEN` 仅在调用云端收费接口时使用，是可选项，不是本 Skill 的必填前置条件\n- 云端兜底平台为云码 JFBYM：<https://console.jfbym.com/register/TG133710>\n- 一旦启用云端兜底，传入的图片数据和 `JFBYM_TOKEN` 会发送到 `https://api.jfbym.com`\n- 代码中包含固定 `developer_tag`，用于渠道归因\n\n如果你的场景对隐私更敏感：\n\n- 只使用本地免费能力\n- 不设置 `JFBYM_TOKEN`\n- 不把非验证码敏感图片传给云端接口\n\n## 调用边界摘要\n\n- 本地模式：不上传图片，不需要 token\n- 云端模式：会把调用时传入的图片发送到 `https://api.jfbym.com`\n- 云端模式：会发送 `JFBYM_TOKEN`（如果已配置）\n- 不读取其他系统凭据\n- 不修改系统配置\n- 不要求常驻运行\n\n## 适合谁\n\n- 需要验证码基础能力的 OpenClaw / ClawHub Skill 作者\n- 做浏览器自动化、RPA、数据采集的人\n- 想先免费解决大部分简单场景，再为复杂题型保留便宜兜底的人\n\n## 核心定位\n\n- 免费优先：文本、算术、基础滑块可先走本地能力\n- 低价兜底：复杂场景可接云码 API，按量付费\n- 开发友好：支持文件路径、`bytes`、base64，适合脚本和二次封装\n- 场景覆盖广：文本、算术、滑块、点选、旋转、空间推理、ReCaptcha/hCaptcha\n\n## 什么时候用哪种方式\n\n| 场景 | 推荐策略 | 原因 |\n|---|---|---|\n| 4-6 位文本验证码 | 免费优先 | 本地 OCR 往往够用，零成本 |\n| 简单算术验证码 | 免费优先 | 本地识别后可直接算结果 |\n| 常见双图滑块 | 免费优先 | ddddocr / OpenCV 可先跑 |\n| 点选、九宫格、空间推理 | 直接付费 | 本地通用能力不稳定，直接走云码省时间 |\n| 旋转、轨迹验证 | 直接付费 | 题型偏复杂，云码成功率更稳 |\n| ReCaptcha / hCaptcha / Turnstile | 直接付费 | 属于典型云端令牌场景 |\n\n一句话：\n\n- 简单题，先免费\n- 复杂题，直接低价兜底\n- 不确定时，就用 `solve_auto_fallback`\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### 2. 最推荐的用法：自动策略\n\n```python\nfrom jfbym_api import JfbymClient\n\nclient = JfbymClient()  # 不配 token 也能先跑免费分支\n\nret = client.solve_auto_fallback(\n    task=\"text\",\n    image_input=\"captcha.png\",\n    charset_range=\"0123456789\",\n)\n\nprint(ret)\n```\n\n默认 `prefer=\"free\"`，也就是：\n\n- 先走本地免费能力\n- 免费失败时，若已配置 `JFBYM_TOKEN`，再自动走付费兜底\n\n返回结构固定优先看这几个字段：\n\n```python\n{\n  \"task\": \"text|math|slide\",\n  \"mode\": \"free|paid\",\n  \"result\": ...,\n  \"fallback_reason\": \"...\"  # 仅在发生兜底时存在\n}\n```\n\n### 3. 命令行直接跑\n\n文本验证码：\n\n```bash\npython jfbym_api.py text --image captcha.png --charset 0123456789\n```\n\n算术验证码：\n\n```bash\npython jfbym_api.py math --image math.png\n```\n\n双图滑块：\n\n```bash\npython jfbym_api.py slide --background back.png --slide slide.png\n```\n\n如需优先走付费兜底：\n\n```bash\npython jfbym_api.py text --image captcha.png --prefer paid\n```\n\n输出默认为 JSON，方便给其他 Skill 或 Agent 继续处理。\n\n猜你该用哪个 `captcha_type`：\n\n```bash\npython jfbym_api.py guess --description \"九宫格点选\"\n```\n\n查余额：\n\n```bash\npython jfbym_api.py balance\n```\n\n返分：\n\n```bash\npython jfbym_api.py report-error --unique-code 打码返回的uniqueCode\n```\n\n## 输入与输出约定\n\n### 输入约定\n\n- `image_input`：文件路径、`bytes`、base64\n- `back_image_input` / `slide_image_input`：文件路径、`bytes`、base64\n- `extra`：复杂点选/推理类场景的文字提示\n- `paid_captcha_type`：覆盖默认云码类型\n\n### 输出约定\n\n- 自动策略接口：统一返回外层结构 `task/mode/result/fallback_reason`\n- 本地文本识别：返回 `str`\n- 本地算术识别：返回 `dict`\n- 本地滑块识别：返回 `dict` 或 `int`\n- 云码接口：返回云码原始 `data`\n\nAgent 调用建议：\n\n- 自动策略返回时，优先读 `ret[\"result\"]`\n- 云码接口返回时，优先读 `ret.get(\"data\")` 或按题型字段读取\n- 不要假定所有付费题型返回结构完全一致\n\n## 免费能力（本地）\n\n> 适合优先降本，覆盖常见简单验证码。无需 `token`。\n\n### 支持能力\n\n- 通用文本识别：`solve_local_text_captcha(image_input)`\n- 字符集约束识别：`solve_local_text_captcha_with_range(image_input, charset_range=...)`\n- 算术验证码识别：`solve_local_math_captcha(image_input)`\n- 文本框检测：`detect_local_text_boxes(image_input)`\n- 滑块匹配（ddddocr）：`solve_local_slide_distance_ddddocr(back, slide)`\n- 滑块匹配（OpenCV）：`solve_local_slide_distance(back_base64, slide_base64)`\n\n### 适用建议\n\n- 纯数字、纯字母、简单字母数字混合：优先免费\n- 简单算术题：优先免费\n- 常见双图滑块：优先免费\n- 干扰严重、点选、旋转、空间推理：通常直接走云码更省时间\n\n### 免费本地示例\n\n```python\nfrom jfbym_api import JfbymClient\n\ntext = JfbymClient.solve_local_text_captcha(\"captcha.png\")\nmath_ret = JfbymClient.solve_local_math_captcha(\"math.png\")\nslide_ret = JfbymClient.solve_local_slide_distance_ddddocr(\"back.png\", \"slide.png\")\n```\n\n## 低价兜底能力（云码 API / JFBYM）\n\n> 适合复杂验证码或高成功率场景。仅在调用云端接口时需要 `token`。\n\n平台主页：\n\n- <https://console.jfbym.com/register/TG133710>\n\n### 透明说明\n\n- 这是我推荐的低价兜底渠道，不影响免费功能使用\n- 你完全可以只用本地免费能力，不注册、不充值也没问题\n\n注册链接：\n\n- <https://console.jfbym.com/register/TG133710>\n\n### 为什么我愿意推荐它\n\n- 价格低，适合作为“偶尔才用一次”的兜底渠道\n- 很多验证码场景本来就不高频，通常不需要高额充值\n- 文本、算术、基础滑块本来就可以先走本地免费，只有复杂题型才建议付费\n\n### token 配置\n\n```bash\nexport JFBYM_TOKEN=\"你的云码token\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:JFBYM_TOKEN=\"你的云码token\"\n```\n\n### 常见复杂题型\n\n价格来源：<https://www.jfbym.com/price.html>（日期：2026-03-12）\n\n| 场景 | 推荐 type | 低至价格 | 推荐接口 | 关键说明 |\n|---|---|---|---|---|\n| 空间推理点选（无确定按钮） | `50009` | `0.012元` | `solve_common` | 如：点击侧对着你的字母 |\n| 空间推理点选（有确定按钮） | `30340` | `0.01元` | `solve_common` | 如：点击正方体上面字母的小写字母 |\n| 文字点选（通用） | `30100` | `0.01元` | `solve_common` | 按顺序点击需求文字 |\n| 推理拼图 | `30108` | `0.008元` | `solve_common` | 交换 2 个图块 |\n| 九宫格点选 | `30008` | `0.01元` | `solve_common` | 9 宫格图片验证 |\n| 双图滑块（收费兜底） | `20111` | `0.01元` | `solve_slide` | 2 个或多个缺口的滑块场景 |\n| 轨迹验证/单图滑块优化 | `22222` | `0.008元` | `solve_common` | 返回坐标或偏移相关结果 |\n| 单图旋转 | `90007` | `按官网/定制` | `solve_common` | 通用旋转验证码 |\n| 双图旋转 | `90004` | `0.01元` | `solve_common` | 内圈、外圈图片旋转验证 |\n| 双图旋转（高频场景） | `90015` | `按官网/定制` | `solve_common` | 返回 `rotate_angle` 和 `slide_px` |\n| 问答题 | `50103` | `0.016元` | `solve_common` | 看图问答 |\n\n说明：价格与活动可能随时间变化，最终请以官网实时页面为准。\n\n## 推荐调用策略\n\n### 方案 A：大多数人最适合\n\n- 文本：先 `solve_auto_fallback(task=\"text\", ...)`\n- 算术：先 `solve_auto_fallback(task=\"math\", ...)`\n- 滑块：先 `solve_auto_fallback(task=\"slide\", ...)`\n\n### 方案 B：你已经明确知道是复杂题型\n\n- 点选、空间推理、旋转、ReCaptcha、hCaptcha\n- 直接走云码接口，减少本地重试\n\n## 典型场景\n\n### 场景 1：登录页数字验证码\n\n```python\nfrom jfbym_api import JfbymClient\n\nclient = JfbymClient()\nret = client.solve_auto_fallback(\n    task=\"text\",\n    image_input=\"captcha.png\",\n    charset_range=\"0123456789\",\n)\n```\n\n### 场景 2：算术验证码\n\n```python\nfrom jfbym_api import JfbymClient\n\nret = JfbymClient.solve_local_math_captcha(\"math.png\")\nprint(ret[\"result\"])\n```\n\n### 场景 3：双图滑块\n\n```python\nfrom jfbym_api import JfbymClient\n\nclient = JfbymClient()\nret = client.solve_auto_fallback(\n    task=\"slide\",\n    back_image_input=\"back.png\",\n    slide_image_input=\"slide.png\",\n)\n```\n\n### 场景 4：九宫格 / 空间推理 / 点选\n\n```python\nfrom jfbym_api import JfbymClient\n\nclient = JfbymClient()\nret = client.solve_common(\n    image_input=image_b64,\n    captcha_type=\"30008\",\n    label_image=label_image_b64,\n)\n```\n\n### 场景 5：不确定该走哪个付费 type\n\n```bash\npython jfbym_api.py guess --description \"点击所有朝向左边的字母\"\n```\n\n## 自动策略接口\n\n统一入口：\n\n- `solve_auto_fallback(task, image_input=None, back_image_input=None, slide_image_input=None, charset_range=None, paid_captcha_type=None, extra=None, prefer=\"free\")`\n\n### 参数说明\n\n- `task`: 必填。支持 `text` / `math` / `slide`\n- `image_input`: `text`、`math` 任务必填。支持文件路径、`bytes`、base64\n- `back_image_input`、`slide_image_input`: `slide` 任务必填\n- `charset_range`: 文本任务可选。可限制字符集\n- `paid_captcha_type`: 可选。覆盖默认云码 type\n- `extra`: 可选。透传给收费 `solve_common`\n- `prefer`: `free` 或 `paid`，默认 `free`\n\n### 返回结构\n\n```python\n{\n  \"task\": \"text|math|slide\",\n  \"mode\": \"free|paid\",\n  \"result\": ...,\n  \"fallback_reason\": \"...\"  # 仅在发生兜底时存在\n}\n```\n\n### 示例\n\n```python\nfrom jfbym_api import JfbymClient\n\nclient = JfbymClient()\n\ntext_ret = client.solve_auto_fallback(\n    task=\"text\",\n    image_input=\"captcha.png\",\n    charset_range=\"0123456789\",\n)\n\nmath_ret = client.solve_auto_fallback(\n    task=\"math\",\n    image_input=\"math.png\",\n)\n\nslide_ret = client.solve_auto_fallback(\n    task=\"slide\",\n    back_image_input=\"back.png\",\n    slide_image_input=\"slide.png\",\n)\n```\n\n## 进阶：直接调用云码接口\n\n### 通用单图接口\n\n```python\nret = client.solve_common(\n    image_input=image_b64,\n    captcha_type=\"30100\",\n    extra=\"猫,狗,车\",\n)\n```\n\n### 双图滑块接口\n\n```python\nret = client.solve_slide(\n    slide_image=\"slide.png\",\n    bg_image=\"back.png\",\n    captcha_type=\"20111\",\n)\n```\n\n### 双图旋转（90015）\n\n```python\nret = client.solve_common(\n    image_input=None,\n    out_ring_image=out_ring_b64,\n    inner_circle_image=inner_circle_b64,\n    captcha_type=\"90015\",\n)\n\nrotate_angle = ret.get(\"data\", {}).get(\"rotate_angle\")\nslide_px = ret.get(\"data\", {}).get(\"slide_px\")\n```\n\n## 识别结果说明\n\n### 免费本地接口返回\n\n- `solve_local_text_captcha(...)`：返回 `str`\n- `solve_local_text_captcha_with_range(...)`：返回 `str`\n- `solve_local_math_captcha(...)`：返回 `dict`\n- `detect_local_text_boxes(...)`：返回 `list`\n- `solve_local_slide_distance_ddddocr(...)`：返回 `dict`\n- `solve_local_slide_distance(...)`：返回 `int`\n\n### 收费云码接口返回\n\n- `solve_common(...)`：返回云码接口 `data`\n- `solve_slide(...)`：返回云码接口 `data`\n- `solve_recaptcha(...)`：返回可提交 token\n- `get_balance()`：返回积分余额\n- `report_error(unique_code)`：返回是否退款成功\n- `guess_captcha_type(description)`：返回推荐 type\n\n## 安全与边界\n\n- 本地免费能力不会上传图片到第三方 API\n- 使用云码兜底时，图片会提交到第三方服务，请自行评估场景敏感度\n- 建议不要把它用于含有敏感隐私信息的整页截图上传场景\n- 调用方最好自己控制失败重试次数，避免无意义消耗\n\n## 依赖建议\n\n- 建议在虚拟环境或隔离环境中安装依赖\n- ddddocr、OpenCV、Pillow、numpy 这类图像处理依赖体积可能较大\n- 如果你只打算使用本地免费能力，先完成依赖安装再测试\n- 如果你只打算接入云码 SDK，仍建议先在受控环境中验证网络调用与返回结构\n\n## 开源致谢\n\n本 Skill 的本地免费能力基于开源项目 [ddddocr](https://github.com/sml2h3/ddddocr) 构建，感谢作者与社区贡献。\n\n## 支持与反馈\n\n如果这个 Skill 对你有帮助，欢迎：\n\n- 在 ClawHub 给它点个星标，能帮助更多人看到它\n- 遇到问题时提交 issue 或直接反馈复现信息、错误样例、题型截图\n- 分享你的使用场景，方便我继续优化免费能力和兜底策略\n\n说明：\n\n- 星标、反馈和真实案例都很重要，公共基础能力只有在被持续使用时才有维护价值\n- 如果后续你有 GitHub 仓库，建议把这里补成正式的 Issues 链接\n\n## 项目结构\n\n```text\ncaptcha-base-skill/\n├── SKILL.md\n├── requirements.txt\n├── local_captcha.py   # 本地免费能力\n├── jfbym_sdk.py       # 云码 SDK\n└── jfbym_api.py       # 统一门面 + 自动兜底 + CLI\n```\n","topics":["浏览器自动化"],"tags":{"latest":"1.0.10"},"stats":{"comments":0,"downloads":785,"installsAllTime":29,"installsCurrent":0,"stars":1,"versions":4},"createdAt":1773547726284,"updatedAt":1779078187002},"latestVersion":{"version":"1.0.10","createdAt":1773550931605,"changelog":"No changes detected in this release.\n\n- Version 1.0.10 matches the previous version; no modifications or updates have been made.","license":"MIT-0"},"metadata":null,"owner":{"handle":"zhaoqf-cq","userId":"s171ywqncpft3p1gpk2zxh7qy583hx1m","displayName":"veles","image":"https://avatars.githubusercontent.com/u/27794583?v=4"},"moderation":null}