306 lines
8.6 KiB
Markdown
306 lines
8.6 KiB
Markdown
# 快速开始 - 滑块验证自动化（v1.2.0）
|
||
|
||
## 🚀 5 分钟上手
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd /Users/gavin/douban-login
|
||
npm install
|
||
```
|
||
|
||
### 2. 授予完全磁盘访问权限（macOS）
|
||
|
||
- 系统设置 → 隐私与安全性 → 完全磁盘访问权限 → 添加终端（Terminal/iTerm2/VS Code）
|
||
- 勾选开关后重启终端，确保能够读取 `~/Library/Messages/chat.db`
|
||
- 想快速验证，可执行 `ls ~/Library/Messages/chat.db` 检查权限
|
||
|
||
### 3. 启用自动滑块验证登录
|
||
|
||
```bash
|
||
DOUBAN_AUTO_SLIDER=1 DOUBAN_PHONE=你的手机号 npm run login
|
||
```
|
||
|
||
就这么简单！脚本会自动：
|
||
- ✅ 检测滑块验证码
|
||
- ✅ 使用 AI 识别滑块和缺口位置
|
||
- ✅ 计算精确的滑动距离
|
||
- ✅ 模拟真人滑动轨迹
|
||
- ✅ 自动重试直到成功（最多 10 次）
|
||
- ✅ 在 macOS 上自动读取短信验证码，读取失败会提示手动输入
|
||
|
||
### 4. 独立测试滑块功能
|
||
|
||
```bash
|
||
npm run slider
|
||
```
|
||
|
||
会启动浏览器，给你 30 秒时间导航到包含滑块的页面，然后自动尝试完成验证。
|
||
|
||
## 📖 常见场景
|
||
|
||
### 场景 1：豆瓣登录（默认）
|
||
|
||
```bash
|
||
DOUBAN_AUTO_SLIDER=1 DOUBAN_PHONE=13800138000 npm run login
|
||
```
|
||
|
||
脚本会自动完成整个登录流程，包括滑块验证与 macOS 短信验证码读取（授权不足时会提示手动输入）。
|
||
|
||
### 场景 2：查看检测过程
|
||
|
||
登录后查看生成的截图：
|
||
- `noflag/` 目录：原始验证码图片
|
||
- `output/` 目录：带红框标注的检测结果
|
||
|
||
红框标注说明：
|
||
- 左侧红框：检测到的滑块位置
|
||
- 右侧红框：检测到的缺口位置
|
||
|
||
### 场景 3：调试识别准确性
|
||
|
||
如果识别总是失败，可以：
|
||
|
||
1. 查看 `output/` 目录的标注图，确认红框位置是否准确
|
||
2. 检查控制台日志中的 `scaleX` 值（应该约为 2.35）
|
||
3. 确认距离计算公式：`(缺口X - 滑块X) / scaleX`
|
||
|
||
### 场景 4：批量复核历史截图
|
||
|
||
```bash
|
||
npm run slider -- --pic-dir=noflag
|
||
```
|
||
|
||
会对 `noflag/` 目录中的所有验证码图片重新检测，并将标注结果输出到 `output/` 目录。
|
||
|
||
## 💻 在代码中使用
|
||
|
||
### 最简单的方式
|
||
|
||
```typescript
|
||
import { Page } from 'playwright';
|
||
import { SliderController } from './slider';
|
||
|
||
async function login(page: Page) {
|
||
// 触发登录操作
|
||
await page.click('#login-button');
|
||
|
||
// 自动处理滑块验证（如果出现）
|
||
const controller = new SliderController(10);
|
||
const result = await controller.solveSlider(
|
||
page,
|
||
'.tcaptcha_drag_button', // 滑块按钮选择器
|
||
'#tcaptcha_iframe' // 验证码 iframe 选择器
|
||
);
|
||
|
||
if (result.success) {
|
||
console.log(`验证成功！尝试 ${result.attempts} 次`);
|
||
} else {
|
||
console.log('验证失败，需要手动完成');
|
||
}
|
||
}
|
||
```
|
||
|
||
### 更多控制
|
||
|
||
```typescript
|
||
import { SliderDetector, SliderController } from './slider';
|
||
|
||
// 1. 单独使用检测器
|
||
const detector = new SliderDetector();
|
||
const boxes = await detector.detectSlider(
|
||
'captcha.png', // 输入图片路径
|
||
'output/result.png', // 标注结果保存路径
|
||
true // 是否绘制标注框
|
||
);
|
||
|
||
if (boxes && boxes.length > 0) {
|
||
console.log('检测到滑块:', boxes);
|
||
console.log('第一个滑块位置:', boxes[0].x, boxes[0].y);
|
||
console.log('第一个滑块尺寸:', boxes[0].width, boxes[0].height);
|
||
}
|
||
|
||
// 2. 使用控制器完成整个流程
|
||
const controller = new SliderController(10);
|
||
const result = await controller.solveSlider(page);
|
||
```
|
||
|
||
## 🔧 故障排查
|
||
|
||
### 问题：短信读取失败或一直等待
|
||
|
||
**症状**：终端反复打印 `[短信读取] 未检测到新的豆瓣验证码短信`，最终回退到手动输入。
|
||
|
||
**排查步骤**：
|
||
1. 确认已为终端授予“完全磁盘访问权限”，并在授权后重新启动终端；
|
||
2. 使用 `ls ~/Library/Messages/chat.db` 验证终端是否具备读取权限；
|
||
3. 检查短信是否确实到达 Mac 的“信息”应用；
|
||
4. 若仍失败，可直接在提示时手动输入验证码，稍后再排查权限问题。
|
||
|
||
### 问题：检测不到滑块
|
||
|
||
**症状**：日志显示"未检测到滑块"或"检测到 0 个滑块"
|
||
|
||
**排查步骤**：
|
||
1. 检查 `noflag/` 目录下的原始截图是否正确
|
||
2. 确认验证码已完全加载（等待 iframe 和图片元素）
|
||
3. 查看 `output/` 目录的标注图，确认候选框是否被正确识别
|
||
4. 尝试多次运行，因为验证码图片质量可能不同
|
||
|
||
### 问题：滑动距离不准确
|
||
|
||
**症状**：滑块滑过头或不够远
|
||
|
||
**v1.1.0 简化算法**：
|
||
- 使用公式：`距离 = (缺口X - 滑块X) / scaleX`
|
||
- scaleX 约为 2.35（340px → 800px 的缩放比例）
|
||
- 基于"两只小鸟嘴尖距离"的几何原理
|
||
|
||
**排查步骤**：
|
||
1. 查看控制台日志中的距离计算过程
|
||
2. 检查 `output/` 目录标注图，红框是否准确
|
||
3. 确认检测到的是双滑块模式（2 个红框）
|
||
|
||
**示例日志**：
|
||
```
|
||
[SliderDetector] 检测到 2 个滑块候选框
|
||
[SliderDetector] 滑块 1: x=45, width=60, score=0.85
|
||
[SliderDetector] 滑块 2: x=195, width=55, score=0.82
|
||
[SliderController] 计算距离: (195 - 45) / 2.35 = 63.8px
|
||
```
|
||
|
||
### 问题：验证总是失败
|
||
|
||
**可能原因**：
|
||
|
||
1. **图像识别不准确**
|
||
- 查看 `output/` 目录检查标注准确性
|
||
- 复杂背景或低对比度图片识别率较低
|
||
- 当前准确率约 70-80%
|
||
|
||
2. **反爬虫检测**
|
||
- 避免过于频繁使用
|
||
- 已集成拟人化轨迹，但仍可能被识别
|
||
|
||
3. **网络延迟**
|
||
- 成功标识（`.tc-success`）可能延迟出现
|
||
- 当前等待时间 1000ms，可能需要延长
|
||
|
||
**解决方案**：
|
||
- 使用自动重试机制（最多 10 次）
|
||
- 查看详细日志定位问题
|
||
- 必要时手动完成验证
|
||
|
||
### 问题：程序卡住不动
|
||
|
||
**检查**：
|
||
- 是否在等待 iframe 加载？查看日志 "等待验证码 iframe 加载..."
|
||
- 是否在等待图片加载？查看日志 "等待滑块背景图加载..."
|
||
- 网络是否正常？尝试增加超时时间
|
||
|
||
### 视觉调试技巧
|
||
|
||
**查看检测结果**：
|
||
1. 运行登录后，打开 `output/` 目录
|
||
2. 找到最新的 `*-detected.png` 文件
|
||
3. 检查红框是否准确标注了滑块和缺口
|
||
4. 对比 `noflag/` 目录的原始图
|
||
|
||
**理想的标注结果**：
|
||
- 左侧滑块：红框紧贴滑块边缘
|
||
- 右侧缺口：红框框住缺口区域
|
||
- 两个红框高度基本一致（y 坐标偏差 < 25px）
|
||
- 红框宽度接近滑块实际宽度（约 50-70px）
|
||
|
||
## 📚 深入了解
|
||
|
||
- [README.md](./README.md) - 项目总览和功能介绍
|
||
- [src/slider/README.md](./src/slider/README.md) - 滑块模块详细文档
|
||
- [CHANGELOG.md](./CHANGELOG.md) - 版本更新日志
|
||
- [release.md](./release.md) - 发布说明
|
||
|
||
## 🎯 核心 API
|
||
|
||
```typescript
|
||
// 滑块检测器
|
||
class SliderDetector {
|
||
async detectSlider(
|
||
imagePath: string,
|
||
outputPath: string,
|
||
drawBoxes: boolean = true
|
||
): Promise<BoundingBox[] | null>
|
||
}
|
||
|
||
// 滑块控制器
|
||
class SliderController {
|
||
constructor(maxAttempts: number = 10)
|
||
|
||
async solveSlider(
|
||
page: Page,
|
||
sliderSelector?: string,
|
||
captchaSelector?: string
|
||
): Promise<SliderSolveResult>
|
||
}
|
||
|
||
// 返回结果
|
||
interface SliderSolveResult {
|
||
success: boolean; // 是否成功
|
||
attempts: number; // 尝试次数
|
||
distance?: number; // 滑动距离（像素）
|
||
}
|
||
|
||
// 边界框
|
||
interface BoundingBox {
|
||
x: number;
|
||
y: number;
|
||
width: number;
|
||
height: number;
|
||
}
|
||
```
|
||
|
||
## 💡 提示
|
||
|
||
1. **首次使用**：
|
||
- 建议先运行一次观察完整流程
|
||
- 查看 `output/` 和 `noflag/` 目录的输出
|
||
- 了解红框标注的含义
|
||
|
||
2. **提高成功率**：
|
||
- 依赖自动重试机制（最多 10 次）
|
||
- 每次验证码图片不同，识别难度也不同
|
||
- 当前成功率约 50%，已经可以应对日常使用
|
||
|
||
3. **调试建议**：
|
||
- 查看控制台日志了解检测过程
|
||
- 检查 `output/` 目录的标注图验证准确性
|
||
- 使用 CLI 工具批量测试：`npm run slider -- --pic-dir=noflag`
|
||
|
||
4. **避免滥用**：
|
||
- 不要过于频繁使用，可能触发更严格验证
|
||
- 遵守网站服务条款
|
||
- 仅用于个人学习研究
|
||
|
||
## ⚠️ 重要提示
|
||
|
||
- **本功能仅用于学习研究**
|
||
- **使用时请遵守网站服务条款**
|
||
- **图像识别准确率约 70-80%**
|
||
- **验证成功率约 50%（含重试）**
|
||
- **不保证 100% 成功，请做好手动完成的准备**
|
||
|
||
## 📊 性能指标
|
||
|
||
- **检测耗时**：约 2-3 秒/次（含截图、检测、标注）
|
||
- **平均尝试次数**：1-3 次
|
||
- **最大尝试次数**：10 次
|
||
- **图像缩放比例**：340px → 800px（scaleX ≈ 2.35）
|
||
|
||
## 🤝 需要帮助？
|
||
|
||
查看详细文档或提交 Issue 了解更多用法。
|
||
|
||
---
|
||
|
||
**v1.1.0** - 2025-10-25
|
||
引入 AI 驱动的滑块验证码自动破解功能 🎉
|