# 快速开始 - 滑块验证自动化（v1.1.0）

## 🚀 5 分钟上手

### 1. 安装依赖

```bash
cd /Users/gavin/douban-login
npm install
```

### 2. 启用自动滑块验证登录

```bash
DOUBAN_AUTO_SLIDER=1 DOUBAN_PHONE=你的手机号 npm run login
```

就这么简单！脚本会自动：
- ✅ 检测滑块验证码
- ✅ 使用 AI 识别滑块和缺口位置
- ✅ 计算精确的滑动距离
- ✅ 模拟真人滑动轨迹
- ✅ 自动重试直到成功（最多 10 次）

### 3. 独立测试滑块功能

```bash
npm run slider
```

会启动浏览器，给你 30 秒时间导航到包含滑块的页面，然后自动尝试完成验证。

## 📖 常见场景

### 场景 1：豆瓣登录（默认）

```bash
DOUBAN_AUTO_SLIDER=1 DOUBAN_PHONE=13800138000 npm run login
```

脚本会自动完成整个登录流程，包括滑块验证。

### 场景 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);
```

## 🔧 故障排查

### 问题：检测不到滑块

**症状**：日志显示"未检测到滑块"或"检测到 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 驱动的滑块验证码自动破解功能 🎉