douban-login/QUICKSTART.md

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

🚀 5 分钟上手

1. 安装依赖

cd /Users/gavin/douban-login
npm install

2. 授予完全磁盘访问权限（macOS）

• 系统设置 → 隐私与安全性 → 完全磁盘访问权限 → 添加终端（Terminal/iTerm2/VS Code）
• 勾选开关后重启终端，确保能够读取 ~/Library/Messages/chat.db
• 想快速验证，可执行 ls ~/Library/Messages/chat.db 检查权限

3. 启用自动滑块验证登录

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

就这么简单！脚本会自动：

• ✅ 检测滑块验证码
• ✅ 使用 AI 识别滑块和缺口位置
• ✅ 计算精确的滑动距离
• ✅ 模拟真人滑动轨迹
• ✅ 自动重试直到成功（最多 10 次）
• ✅ 在 macOS 上自动读取短信验证码，读取失败会提示手动输入

4. 独立测试滑块功能

npm run slider

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

📖 常见场景

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

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：批量复核历史截图

npm run slider -- --pic-dir=noflag

会对 noflag/ 目录中的所有验证码图片重新检测，并将标注结果输出到 output/ 目录。

💻 在代码中使用

最简单的方式

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('验证失败，需要手动完成');
  }
}

更多控制

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 - 项目总览和功能介绍
• src/slider/README.md - 滑块模块详细文档
• CHANGELOG.md - 版本更新日志
• release.md - 发布说明

🎯 核心 API

// 滑块检测器
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 驱动的滑块验证码自动破解功能 🎉