CAPTCHA Recognition Skill
基于 ddddocr 的验证码识别技能，提供简单易用的验证码识别功能。
When to Use This Skill
当用户有以下请求时，应该激活此技能：
-
识别验证码图片：
- "帮我识别这个验证码"
- "这个验证码是什么"
- "帮我破解这个验证码图片"
- "识别这张图片中的验证码"
-
网络验证码识别：
-
OCR 相关请求：
- "OCR 识别这个图片"
- "提取图片中的文字"
- "图片文字识别"
-
验证码验证场景：
- 用户发送了验证码图片并询问内容
- 需要自动识别网页/应用中的验证码
依赖安装
pip install ddddocr opencv-python numpy Pillow requests
支持的图片输入格式
本技能支持多种验证码图片输入方式：
| 格式 | 示例 | 说明 |
|---|
| 本地文件路径 | captcha.jpg | 本地存储的验证码图片 |
| HTTP/HTTPS URL | http://example.com/captcha.png | 网络上的验证码图片 |
| Blob URL | blob:https://example.com/... | 浏览器 Blob URL（需特殊处理） |
| 字节数据 | bytes | 图片的二进制数据 |
| PIL Image | PIL.Image.Image | PIL Image 对象 |
关于 Blob URL
Blob URL（如 blob:https://example.com/xxx）是浏览器内部创建的临时 URL，无法从服务器端直接访问。如果用户提供 Blob URL，需要：
- 在浏览器中右键保存图片到本地
- 或者使用浏览器开发者工具获取实际的图片 URL
- 或者将图片下载后提供本地路径
命令行使用
python scripts/captcha.py <image_path_or_url> [--preprocess]
参数说明:
image_path_or_url: 验证码图片路径或网络 URL（必需）--preprocess: 可选，启用图像预处理（灰度化、二值化）
示例:
# 本地文件
python scripts/captcha.py captcha.jpg
python scripts/captcha.py captcha.jpg --preprocess
# 网络 URL
python scripts/captcha.py http://example.com/captcha.png
python scripts/captcha.py https://example.com/captcha.jpg --preprocess
Python API 使用
（注意：如果想要更快速和节省Token，你应该优先使用命令行的方式！）
快速开始
from scripts.captcha import recognize_captcha
# 方法1: 从文件路径识别（最常用）
result = recognize_captcha("path/to/captcha.jpg")
print(f"验证码内容: {result}")
# 方法2: 从网络 URL 识别
result = recognize_captcha("http://example.com/captcha.png")
print(f"验证码内容: {result}")
result = recognize_captcha("https://example.com/captcha.jpg")
print(f"验证码内容: {result}")
# 方法3: 从字节数据识别
with open("captcha.jpg", "rb") as f:
image_bytes = f.read()
result = recognize_captcha(image_bytes)
# 方法4: 从 PIL Image 对象识别
from PIL import Image
pil_image = Image.open("captcha.jpg")
result = recognize_captcha(pil_image)
启用图像预处理
对于质量较差或有干扰线的验证码，可以启用预处理：
# preprocess=True 会进行灰度化和二值化处理
result = recognize_captcha("captcha.jpg", preprocess=True)
API Reference
recognize_captcha(image, preprocess=False, show_ad=False, timeout=10)
主要识别函数，支持多种输入格式。
参数：
| 参数 | 类型 | 必需 | 说明 |
|---|
image | str / bytes / PIL.Image.Image | 是 | 验证码图片，可以是文件路径、网络 URL、字节数据或 PIL Image 对象 |
preprocess | bool | 否 | 是否启用图像预处理（灰度化、二值化），默认 False |
show_ad | bool | 否 | 是否显示 ddddocr 广告，默认 False |
timeout | int | 否 | 网络 URL 请求超时时间（秒），默认 10 |
返回值：
异常：
FileNotFoundError: 图片文件不存在ValueError: 不支持的 URL 格式（如 Blob URL）RuntimeError: 网络请求失败或图像处理失败TypeError: 不支持的图片类型ImportError: 缺少必要的依赖库
CaptchaRecognizer 类
如需更细粒度的控制，可以直接使用类：
from scripts.captcha import CaptchaRecognizer
recognizer = CaptchaRecognizer(show_ad=False)
# 从文件识别
result = recognizer.recognize_from_file("captcha.jpg", preprocess=False)
# 从网络 URL 识别
result = recognizer.recognize_from_url("http://example.com/captcha.png", preprocess=False)
# 从字节识别
with open("captcha.jpg", "rb") as f:
result = recognizer.recognize_from_bytes(f.read())
# 从 PIL Image 识别
from PIL import Image
img = Image.open("captcha.jpg")
result = recognizer.recognize_from_pil(img)
最佳实践
- 优先使用文件路径：如果图片已保存为文件，直接传递路径字符串最简单
- 网络 URL 识别：支持 HTTP/HTTPS URL，会自动下载并识别验证码
- 预处理建议：对于背景复杂、有干扰线或颜色较多的验证码，尝试
preprocess=True
- 错误处理：建议捕获
FileNotFoundError、ValueError 和 TypeError 提供友好的错误提示
- 性能优化：
recognize_captcha() 使用单例模式，重复调用不会重复加载 OCR 模型
- 超时设置：对于网络 URL，可以通过
timeout 参数调整请求超时时间
完整示例
from scripts.captcha import recognize_captcha
def solve_captcha(image_source):
"""识别验证码并处理可能的错误"""
try:
# 先尝试不预处理
result = recognize_captcha(image_source)
# 如果结果为空或不合理，尝试预处理
if not result or len(result) < 2:
result = recognize_captcha(image_source, preprocess=True)
return result
except FileNotFoundError:
return "错误：找不到图片文件"
except ValueError as e:
return f"错误：{e}"
except ImportError as e:
return f"错误：缺少依赖库 - {e}"
except Exception as e:
return f"错误：识别失败 - {e}"
# 使用本地文件
result = solve_captcha("captcha.jpg")
print(f"识别结果: {result}")
# 使用网络 URL
result = solve_captcha("http://example.com/captcha.png")
print(f"识别结果: {result}")
