douban-login/QUICKSTART.md

# 快速开始 - 滑块验证自动化

## 🚀 5 分钟上手

### 1. 安装依赖

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

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

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

就这么简单！脚本会自动：
- ✅ 检测滑块验证码
- ✅ 计算滑动距离
- ✅ 模拟真人滑动
- ✅ 多次重试直到成功

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

```bash
npm run slider
```

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

## 📖 常见场景

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

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

### 场景 2：识别不准，手动指定距离

```bash
DOUBAN_AUTO_SLIDER=1 \
DOUBAN_SLIDER_DISTANCE=280 \
DOUBAN_PHONE=13800138000 \
npm run login
```

### 场景 3：调整重试偏移

```bash
DOUBAN_AUTO_SLIDER=1 \
DOUBAN_SLIDER_OFFSETS=0,-5,5,-10,10,-15,15 \
DOUBAN_PHONE=13800138000 \
npm run login
```

### 场景 4：增加超时时间（网络慢）

```bash
DOUBAN_AUTO_SLIDER=1 \
DOUBAN_SLIDER_TIMEOUT=60000 \
DOUBAN_PHONE=13800138000 \
npm run login
```

## 💻 在代码中使用

### 最简单的方式

```typescript
import { Page } from 'playwright';
import { waitAndHandleSlider } from './slider';

async function myFunction(page: Page) {
  // 触发可能出现滑块的操作
  await page.click('#some-button');
  
  // 自动等待并处理滑块（如果出现）
  await waitAndHandleSlider(page);
}
```

### 更多控制

```typescript
import { hasSlider, autoSlide } from './slider';

async function myFunction(page: Page) {
  await page.click('#some-button');
  await page.waitForTimeout(1000);
  
  // 检查是否有滑块
  if (await hasSlider(page)) {
    console.log('需要完成滑块验证');
    
    // 自动完成
    const success = await autoSlide(page, {
      distance: 250,  // 可选：手动指定距离
      offsets: [0, -5, 5, -10, 10],  // 可选：重试偏移
    });
    
    if (!success) {
      console.log('自动验证失败，请手动完成');
      // 处理失败情况
    }
  }
}
```

### 自定义配置（针对不同网站）

```typescript
// 腾讯防水墙
await autoSlide(page, {
  handleSelector: '.tc-drag-thumb',
  trackSelector: '.tc-drag-track',
  bgSelector: '.tc-bg-img',
  pieceSelector: '.tc-jig-img',
});

// 极验验证
await autoSlide(page, {
  handleSelector: '.geetest_slider_button',
  trackSelector: '.geetest_slider',
  bgSelector: '.geetest_canvas_bg',
  pieceSelector: '.geetest_canvas_slice',
});
```

## 🔧 故障排查

### 问题：找不到滑块元素

**解决**：打开浏览器开发者工具，检查 HTML 结构，然后：

```bash
DOUBAN_SLIDER_HANDLE_SELECTOR='.your-slider-class' npm run login
```

### 问题：距离总是差一点

**解决**：调整偏移序列，重点尝试差距范围：

```bash
# 如果总是差 10 像素左右
DOUBAN_SLIDER_OFFSETS=0,10,8,12,5,15 npm run login
```

### 问题：验证总是失败

**原因和解决**：

1. **图像识别不准** → 手动指定距离
   ```bash
   DOUBAN_SLIDER_DISTANCE=250 npm run login
   ```

2. **滑动太快被识别为机器人** → 修改 `slider.ts` 增加总时长
   ```typescript
   // 在 generateTrack 函数中
   const totalTime = 1500 + Math.random() * 1500; // 改为 1.5-3 秒
   ```

3. **选择器不对** → 检查并指定正确选择器

### 问题：程序卡住不动

**检查**：
- 是否在等待手动完成验证？查看终端提示
- 超时设置是否太短？增加 `DOUBAN_SLIDER_TIMEOUT`
- 网络是否正常？

## 📚 深入了解

- [SLIDER.md](./SLIDER.md) - 详细功能文档
- [IMPLEMENTATION.md](./IMPLEMENTATION.md) - 实现原理
- [src/examples.ts](./src/examples.ts) - 更多使用示例

## 🎯 核心 API

```typescript
// 检测是否存在滑块
hasSlider(page: Page, config?: SliderConfig): Promise<boolean>

// 自动完成滑块验证
autoSlide(page: Page, config?: SliderConfig): Promise<boolean>

// 等待并处理滑块（推荐）
waitAndHandleSlider(page: Page, config?: SliderConfig): Promise<boolean>
```

## ⚙️ 配置选项

```typescript
interface SliderConfig {
  handleSelector?: string;   // 滑块按钮选择器
  trackSelector?: string;    // 滑块轨道选择器
  bgSelector?: string;       // 背景图选择器
  pieceSelector?: string;    // 缺口图选择器
  timeout?: number;          // 超时时间（毫秒）
  distance?: number;         // 手动指定距离（像素）
  offsets?: number[];        // 偏移尝试序列
}
```

## 🎉 运行示例

查看 6 个详细示例：

```bash
# 基础使用
npm run ts-node src/examples.ts 1

# 手动检测
npm run ts-node src/examples.ts 2

# 自定义配置
npm run ts-node src/examples.ts 3

# 登录流程集成
npm run ts-node src/examples.ts 4

# 批量处理
npm run ts-node src/examples.ts 5

# 环境变量配置
npm run ts-node src/examples.ts 6
```

## 💡 提示

1. **首次使用建议先不开启自动验证**，观察滑块行为
2. **记录成功的参数配置**，后续重复使用
3. **避免过于频繁使用**，可能触发更严格验证
4. **定期检查更新**，验证码可能会变化

## ⚠️ 重要提示

- 本功能仅用于学习研究
- 使用时请遵守网站服务条款
- 图像识别准确率约 70-80%
- 需配合偏移重试提高成功率

## 🤝 需要帮助？

查看详细文档或运行示例代码了解更多用法。