update at 2025-10-24 22:25:24

ARCHITECTURE.md

@@ -1,81 +1,71 @@
 # 架构说明
 
-本文档描述项目中的主要模块、职责划分以及关键流程，帮助维护者快速理解整体结构。
+本文档梳理项目中的主要模块、职责划分以及核心流程，帮助维护者快速了解整体结构。当前版本仅关注短信验证码登录与 Cookie 持久化，滑块验证码需人工操作。
 
 ## 模块概览
 
 ```
-├── README.md              // 使用说明与命令入口
-├── ARCHITECTURE.md        // 架构与流程说明（本文档）
-├── login.md               // 需求与步骤原始描述
-├── block.md               // 滑块破解背景与参考脚本
+├── README.md              // 使用说明与运行指引
+├── ARCHITECTURE.md        // 架构概览与流程说明（本文档）
+├── IMPLEMENTATION.md      // 关键实现细节记录
+├── login.md               // 早期需求与操作步骤
 ├── src/
-│   ├── login.ts           // 豆瓣登录主流程（Cookie 复用、短信登录、滑块自动化）
-│   └── slider.ts          // 滑块模拟工具函数与命令行入口
-└── typescript-spec.md     // TypeScript 编码规范与示例
+│   └── login.ts           // 豆瓣登录脚本入口（Cookie 复用 + 短信登录）
+└── typescript-spec.md     // 团队 TypeScript 编码规范
 ```
 
 ## 登录流程分层
 
 ```
-┌─────────────────────────────────────────────┐
+┌────────────────────────────────────┐
 │ main()                             │
-│  - 创建浏览器                               │
+│  - 启动 Chromium                   │
 │  - 复用或创建上下文                │
 │  - 调用 loginWithSms()             │
 │  - 保存 Cookies                    │
-└─────────────────────────────────────────────┘
+└────────────────────────────────────┘
                  │
-┌────────────────▼────────────────────────────┐
+┌────────────────▼──────────────────┐
 │ loginWithSms()                    │
 │  - 输入手机号                     │
-│  - 点击“获取验证码”                          │
-│  - trySolveSlider() 自动滑块（可选）         │
-│  - 提示人工输入短信验证码                   │
-│  - 提交并校验登录状态                       │
-└────────────────▲────────────────────────────┘
+│  - 触发短信验证码                 │
+│  - 提示用户完成页面额外验证       │
+│  - 等待并提交短信验证码           │
+│  - 校验是否登录成功               │
+└────────────────────────────────────┘
                  │
-┌────────────────▼────────────────────────────┐
-│ trySolveSlider()                             │
-│  - locateSlider() 识别滑块所在 frame/元素    │
-│  - inferSliderDistance() 推测拖动距离        │
-│  - performSlide() 实际模拟拖动（来自 slider.ts）│
-│  - 检查滑块成功标记                          │
-└─────────────────────────────────────────────┘
+┌────────────────▼──────────────────┐
+│ isLoggedIn()                      │
+│  - 检查关键 Cookie（dbcl2）        │
+│  - 确认登录表单是否仍然可见        │
+└────────────────────────────────────┘
 ```
 
-- `prepareContext()`：独立负责 Cookie 复用与上下文创建。
-- `isLoggedIn()`：封装登录状态检测逻辑，避免主流程重复判断。
-- `slider.ts`：抽离通用滑块控制方法，既服务登录流程，也支持命令行调试。
+- `prepareContext()`：负责加载已有 Cookie、创建新上下文以及兜底跳转登录页。
+- `loginWithSms()`：串联短信登录流程，涵盖用户输入与结果确认。
+- `isLoggedIn()`：封装判定逻辑，避免各处重复编写 Cookie/页面检查。
 
 ## 依赖与交互
 
-- Playwright：浏览器自动化；
-- Node.js：运行环境、文件/路径操作；
-- readline：控制台交互，输入验证码；
-- 环境变量：控制手机号、滑块自动化开关与参数；
-- `~/cookies.json`：持久化登录态，供下一次运行直接复用。
-
-## 扩展点
-
-- **滑块识别**：`sliderHandleSelectors` 与 `sliderTrackSelectors` 可按需扩充、覆盖，以支持不同验证码厂商。
-- **距离计算**：先截取背景图与拼图块做模板匹配确定缺口位置，必要时退回二值化列分析，再配合多组偏移反复尝试；也可用 `DOUBAN_SLIDER_DISTANCE` / `DOUBAN_SLIDER_OFFSETS` 手动覆盖。
-- **距离推断**：默认通过轨道宽度估算，特殊情况可直接设置 `DOUBAN_SLIDER_DISTANCE`。
-- **验证码输入**：目前依赖人工短信验证码，可接入短信网关或 API 进一步自动化。
-- **多账号管理**：现仅支持单账号，可通过配置文件或参数改造为批量登录。
+- **Playwright**：启动浏览器、操作页面元素、持久化 `storageState`。
+- **Node.js**：文件读写、路径与环境变量处理。
+- **readline**：在控制台等待用户输入短信验证码。
+- **环境变量**：当前仅使用 `DOUBAN_PHONE` 指定登录手机号。
+- **`~/douban-cookie.json`**：保存登录态的 storageState 文件，下次运行直接复用。
 
 ## 数据流
 
-1. 启动脚本读取 `DOUBAN_PHONE`、Cookies 路径等基础配置；
-2. 初始化浏览器上下文，必要时进入登录页面；
-3. 提交手机号，触发滑块验证；
-4. 若启用自动滑块，定位组件并拖动；否则提示人工操作；
-5. 读取短信验证码，提交登录表单；
-6. 验证成功后将 `storageState` 写入 `cookies.json`；
-7. 后续执行逻辑复用当前登录态或退出浏览器。
+1. 读取 `DOUBAN_PHONE`，未配置则终止；
+2. 若存在本地 Cookie 文件，加载后访问登录页以确认是否仍然有效；
+3. 无有效登录态时执行短信登录：
+   - Playwright 填写手机号并请求验证码；
+   - 用户在浏览器中手动完成滑块等验证；
+   - 控制台输入短信验证码并提交；
+4. 登录成功后调用 `context.storageState()` 写入 `~/douban-cookie.json`；
+5. 浏览器关闭，后续脚本可直接复用该文件。
 
 ## 日志与错误处理
 
-- 主流程捕获未处理异常并输出错误信息；
-- 自动滑块阶段出现异常时仅发出警告并回退到人工操作；
-- CLI 提示说明每一步的执行结果，便于排查问题。
+- 关键步骤均在控制台打印提示，便于追踪流程；
+- 验证码相关操作采用提示 + `prompt` 方式等待人工输入；
+- 登录失败或异常会设置 `process.exitCode` 并输出详细错误信息。

IMPLEMENTATION.md

@@ -1,237 +1,80 @@
-# 滑块验证自动化实现总结
+# 登录脚本实现笔记
 
-## 实现概述
-
-参考 https://github.com/omigo/crack-slide-captcha 项目，成功实现了滑轨自动验证功能。
+本文记录当前版本豆瓣登录脚本的实现细节、关键函数以及后续可扩展点。滑块验证码相关逻辑已移除，若页面出现额外验证需人工完成。
 
 ## 文件结构
 
 ```
 src/
-├── login.ts         # 主登录流程，集成滑块验证
-├── slider.ts        # 滑块验证核心实现
-└── examples.ts      # 使用示例代码
+└── login.ts          # Playwright 入口脚本
 ```
 
-## 核心功能
+辅助文档位于项目根目录：
 
-### 1. slider.ts - 滑块验证核心模块
+- `README.md`：使用说明与常见问题；
+- `ARCHITECTURE.md`：整体架构与流程拆解；
+- `login.md`：早期需求说明，可作为手动操作参考。
 
-**主要函数：**
+## 核心流程
 
-- `autoSlide(page, config)` - 自动完成滑块验证
-- `hasSlider(page, config)` - 检测是否存在滑块
-- `waitAndHandleSlider(page, config)` - 等待并自动处理滑块
-- `generateTrack(distance)` - 生成模拟人类的滑动轨迹
-- `calculateDistance(bgBuffer, pieceBuffer)` - 通过图像处理计算滑动距离
+1. **读取配置**  
+   通过 `process.env.DOUBAN_PHONE` 获取手机号，缺失时直接退出。
 
-**核心特性：**
+2. **准备浏览器上下文** (`prepareContext`)  
+   - 若存在 `~/douban-cookie.json`，以 `storageState` 形式加载；  
+   - 打开登录页并调用 `isLoggedIn` 校验是否仍在登录态；  
+   - 失效时关闭旧上下文并创建全新 session。
 
-1. **图像处理识别**
-   - 使用 sharp 库处理图像
-   - 灰度化和边缘检测
-   - 计算缺口位置
+3. **执行短信登录** (`loginWithSms`)  
+   - 输入手机号 → 点击「获取验证码」；  
+   - 控制台提醒用户在浏览器中手动完成滑块等页面验证；  
+   - 通过 `prompt` 等待用户输入短信验证码并提交；  
+   - 等待 Playwright 检测到页面离开登录地址或抛出超时。
 
-2. **真实轨迹模拟**
-   - 三段式速度曲线：加速 → 匀速 → 减速
-   - 垂直方向随机抖动
-   - 随机总时长（1-2秒）
-   - 随机反应时间
+4. **确认状态并写入 Cookie 文件**  
+   - `isLoggedIn` 再次判断是否登录成功；  
+   - 调用 `context.storageState({ path })` 将状态写入 `~/douban-cookie.json`；  
+   - 终端提示成功信息，方便用户确认文件路径。
 
-3. **多次重试机制**
-   - 默认偏移序列：[0, -2, 2, -5, 5, -10, 10]
-   - 自动尝试不同偏移值
-   - 直到成功或尝试完毕
+## 关键函数
 
-### 2. login.ts - 登录流程集成
+### `isLoggedIn(page: Page): Promise<boolean>`
 
-**修改内容：**
+检查 `dbcl2` Cookie 是否存在，并确认登录表单元素是否仍可见。该组合可较准确判断是否处于登录态，同时避免依赖豆瓣首页 DOM。
 
-1. 导入滑块验证模块
-2. 添加 `AUTO_SLIDER` 环境变量支持
-3. 在 `loginWithSms` 函数中集成滑块处理：
-   - 点击"获取验证码"后检测滑块
-   - 根据配置自动或手动完成验证
-   - 支持环境变量自定义参数
+### `prepareContext(browser: Browser)`
 
-### 3. examples.ts - 使用示例
+负责上下文复用策略：优先尝试加载本地 Cookie 创建上下文，如果判定仍未登录则回退到全新会话并跳转登录页。函数返回 `{ context, page, usedCookies }`，调用方可据此判断是否需要重走登录流程。
 
-提供了 6 个详细示例：
-1. 基础使用 - 自动检测并处理
-2. 手动检测和处理
-3. 自定义配置
-4. 登录流程集成
-5. 批量处理多个滑块
-6. 使用环境变量配置
+### `loginWithSms(page: Page, phone: string)`
 
-## 使用方法
+串联短信验证码登录的主要逻辑，所有用户交互点都通过控制台提示：
 
-### 在登录时启用自动滑块
+- 页面操作由脚本自动完成（填手机号、点击按钮）；
+- 人机验证与短信输入由用户处理；
+- 函数内部对提交过程设置合理的等待时间，避免过早关闭浏览器。
 
-```bash
-# 基础使用
-DOUBAN_AUTO_SLIDER=1 DOUBAN_PHONE=13800138000 npm run login
+### `main()`
 
-# 带自定义参数
-DOUBAN_AUTO_SLIDER=1 \
-DOUBAN_SLIDER_DISTANCE=250 \
-DOUBAN_SLIDER_OFFSETS=0,-5,5,-10,10 \
-DOUBAN_PHONE=13800138000 \
-npm run login
-```
+作为 CLI 入口，负责整体 orchestrate：校验配置 → 启动浏览器 → 调用上述函数 → 捕获异常并设置 `process.exitCode`。
 
-### 独立测试滑块功能
+## 错误处理与提示
 
-```bash
-npm run slider
-```
+- 打印清晰的步骤提示，例如“请等待短信验证码…”、“正在提交验证码…”；
+- 捕获 Playwright 的超时异常，允许在页面未完全跳转时通过 `isLoggedIn` 再次确认；
+- 如登录失败会输出明确日志并保持退出码非零，方便在 CI 或脚本中检测。
 
-### 在代码中调用
+## 手动操作注意事项
 
-```typescript
-import { autoSlide, hasSlider } from './slider';
+- Playwright 会以非无头模式启动 Chromium，务必保持窗口前台以便人工处理滑块或图形验证码；
+- 如短信验证码输入错误，可重新运行脚本并继续人工操作；
+- 保存的 `douban-cookie.json` 与账号强绑定，若切换账号需手动删除或覆盖该文件。
 
-// 检测并自动处理
-if (await hasSlider(page)) {
-  const success = await autoSlide(page, {
-    distance: 250,
-    offsets: [0, -5, 5, -10, 10],
-  });
-}
-```
+## 后续拓展建议
 
-## 配置选项
+1. **多账号支持**：通过配置文件或命令行参数管理多组手机号与存储路径；
+2. **验证码服务集成**：接入外部短信/验证码平台以减少人工步骤；
+3. **任务编排**：在登录后追加业务逻辑（例如抓取列表、导出数据），可在 `main` 函数成功分支追加调用；
+4. **CLI 体验**：封装命令行参数解析，避免频繁依赖环境变量。
 
-支持以下环境变量：
-
-| 变量名 | 说明 | 默认值 |
-|--------|------|--------|
-| `DOUBAN_AUTO_SLIDER` | 启用自动滑块 | `0` |
-| `DOUBAN_SLIDER_DISTANCE` | 手动指定距离（像素） | 自动计算 |
-| `DOUBAN_SLIDER_OFFSETS` | 偏移尝试序列（逗号分隔） | `0,-2,2,-5,5,-10,10` |
-| `DOUBAN_SLIDER_HANDLE_SELECTOR` | 滑块按钮选择器 | 多个候选 |
-| `DOUBAN_SLIDER_TRACK_SELECTOR` | 滑块轨道选择器 | 多个候选 |
-| `DOUBAN_SLIDER_BG_SELECTOR` | 背景图选择器 | 多个候选 |
-| `DOUBAN_SLIDER_PIECE_SELECTOR` | 缺口图选择器 | 多个候选 |
-| `DOUBAN_SLIDER_TIMEOUT` | 超时时间（毫秒） | `20000` |
-
-## 技术亮点
-
-### 1. 图像识别算法
-
-```typescript
-// 边缘检测卷积核
-kernel: [-1, -1, -1, -1, 8, -1, -1, -1, -1]
-
-// 窗口平滑减少噪声
-const windowScore = columnScores.slice(i - 5, i + 5).reduce((a, b) => a + b, 0);
-```
-
-### 2. 轨迹生成算法
-
-```typescript
-// 加速阶段 - 二次函数
-const x = accelDist * ratio * ratio;
-
-// 减速阶段 - 平方根函数
-const x = decelDist * Math.sqrt(ratio);
-
-// 垂直抖动
-const y = (Math.random() - 0.5) * range;
-```
-
-### 3. 多次重试逻辑
-
-```typescript
-for (const offset of offsets) {
-  const adjustedDistance = distance + offset;
-  const track = generateTrack(adjustedDistance);
-  await executeSlide(page, handle, track);
-  
-  if (await checkSuccess(page)) {
-    return true;
-  }
-}
-```
-
-## 参考实现对比
-
-| 特性 | 原项目 (Go+OpenCV) | 本实现 (TypeScript+Sharp) |
-|------|-------------------|-------------------------|
-| 语言环境 | Go | TypeScript/Node.js |
-| 图像处理 | OpenCV | Sharp |
-| 执行方式 | Go服务 + JS客户端 | 纯 Playwright |
-| 模板匹配 | 多种算法 | 边缘检测 + 列分析 |
-| 轨迹模拟 | 简单匀速 | 三段式变速 + 抖动 |
-| 集成方式 | 独立服务 | 代码库集成 |
-
-## 优化建议
-
-### 提高识别准确率
-
-1. **使用更强大的图像处理算法**
-   - 集成 OpenCV.js
-   - 实现模板匹配
-   - 使用机器学习模型
-
-2. **缓存已识别的验证码**
-   - 计算图片哈希
-   - 缓存距离结果
-   - 避免重复计算
-
-3. **动态调整偏移策略**
-   - 记录成功的偏移值
-   - 学习最优偏移分布
-   - 自适应调整
-
-### 提高真实性
-
-1. **更复杂的轨迹算法**
-   - 贝塞尔曲线
-   - 真实数据训练
-   - 个性化轨迹
-
-2. **设备指纹模拟**
-   - Canvas 指纹
-   - WebGL 指纹
-   - 音频指纹
-
-3. **行为特征模拟**
-   - 鼠标移动历史
-   - 按键节奏
-   - 页面交互模式
-
-## 注意事项
-
-1. ⚠️ **准确率限制**：简化的图像识别方法准确率约 70-80%
-2. ⚠️ **反爬限制**：频繁使用可能触发更严格验证
-3. ⚠️ **合规使用**：仅用于学习研究，遵守网站服务条款
-4. ⚠️ **维护成本**：需要根据验证码更新调整选择器
-
-## 测试情况
-
-✅ TypeScript 编译通过  
-✅ 代码结构清晰  
-✅ 类型定义完整  
-✅ 文档详细完善  
-
-## 后续改进
-
-- [ ] 实际测试豆瓣滑块验证
-- [ ] 根据测试结果优化参数
-- [ ] 添加更多验证码类型支持
-- [ ] 集成更强大的图像识别库
-- [ ] 添加单元测试
-- [ ] 性能优化
-
-## 相关文档
-
-- [SLIDER.md](../SLIDER.md) - 详细使用文档
-- [README.md](../README.md) - 项目总览
-- [examples.ts](./examples.ts) - 使用示例
-
-## 参考资源
-
-- [crack-slide-captcha](https://github.com/omigo/crack-slide-captcha) - 原始参考项目
-- [Sharp 文档](https://sharp.pixelplumbing.com/)
-- [Playwright 文档](https://playwright.dev/)
+以上内容覆盖当前脚本主要实现。若后续重新引入滑块自动化，可在此文档扩展新的模块说明。

README.md

@@ -1,63 +1,72 @@
 # douban-crawler
 
-使用 Playwright + TypeScript 实现的豆瓣登录与辅助脚本，主要功能包括：
+> Playwright + TypeScript 脚本，用于完成豆瓣短信验证码登录，并将登录态持久化到本地 Cookie 文件。滑块验证码需人工处理，本项目不再尝试自动识别。
 
-- 通过短信验证码完成豆瓣登录，并持久化 Cookies；
-- 自动尝试滑块验证，降低人工干预；
-- 可单独运行的滑块模拟脚本，便于在其它场景复用。
+## 功能概览
 
-## 快速开始
+- 启动 Chromium 浏览器并访问豆瓣登录页；
+- 自动填写手机号，触发短信验证码；
+- 控制台提示用户完成页面内的额外验证（如滑块）并输入短信验证码；
+- 登录成功后将 Cookie 状态保存到 `~/douban-cookie.json`，后续运行可直接复用。
+
+## 环境准备
 
 ```bash
 npm install
 npx playwright install chromium
 ```
 
-首次运行登录脚本需要提供手机号：
+需要 Node.js ≥ 18。Playwright 会自动下载 Chromium，首次运行请确保网络可访问 Playwright CDN。
+
+## 使用方式
+
+1. 设置手机号环境变量并运行登录脚本：
 
    ```bash
-DOUBAN_PHONE=13357108011 npm run login
+   DOUBAN_PHONE=13800000000 npm run login
    ```
 
-若需启用滑块自动化，可增加 `DOUBAN_AUTO_SLIDER=1`，更多环境变量见下文。
+2. 浏览器会自动打开豆瓣登录页，脚本完成以下操作：
+   - 填入手机号并点击「获取验证码」；
+   - 控制台提示等待页面验证（若出现滑块，请手动完成）；
+   - 控制台等待用户输入短信验证码；
+   - 验证码提交成功后，脚本将登录态写入 `~/douban-cookie.json` 并退出。
 
-## 脚本说明
+3. 下次运行会优先尝试加载该 Cookie 文件，若仍在有效期内可直接登录。
+
+## 命令列表
 
 | 命令            | 说明                         |
-| -------------------- | ------------------------------- |
-| `npm run login`      | 豆瓣短信登录，复用 `~/cookies.json` |
-| `npm run slider`     | 独立测试滑块验证功能              |
+| --------------- | ---------------------------- |
+| `npm run login` | 启动豆瓣登录流程并保存 Cookie |
 
-## 配置项
+## 可配置项
 
-登录流程支持以下环境变量：
+当前脚本仅使用一个环境变量：
 
-| 变量名                             | 说明                                                                    | 默认值           |
-| ---------------------------------- | ----------------------------------------------------------------------- | ---------------- |
-| `DOUBAN_PHONE`                     | 登录手机号（必填）                                                      | -                |
-| `DOUBAN_AUTO_SLIDER`               | 是否尝试自动完成滑块验证（`1` 表示开启）                               | `0`              |
-| `DOUBAN_SLIDER_DISTANCE`           | 自定义滑块拖动距离（像素）；缺省时脚本根据轨道宽度推测                 | 自动推测或 200px |
-| `DOUBAN_SLIDER_OFFSETS`            | 距离微调列表（逗号分隔，逐个尝试以校正识别误差）                        | 自动选择        |
-| `DOUBAN_SLIDER_HANDLE_SELECTOR`    | 覆盖默认滑块按钮选择器                                                  | 内置候选         |
-| `DOUBAN_SLIDER_TRACK_SELECTOR`     | 覆盖默认滑块轨道选择器                                                  | 内置候选         |
-| `DOUBAN_SLIDER_BG_SELECTOR`        | 覆盖滑块背景图选择器                                                     | 内置候选         |
-| `DOUBAN_SLIDER_PIECE_SELECTOR`     | 覆盖滑块拼图块选择器                                                     | 内置候选         |
-| `DOUBAN_SLIDER_TIMEOUT`            | 等待滑块组件出现的超时（毫秒）                                          | 20000            |
+| 变量名         | 说明             | 是否必填 | 默认值 |
+| -------------- | ---------------- | -------- | ------ |
+| `DOUBAN_PHONE` | 登录手机号（大陆） | 必填     | -      |
 
-Cookies 将默认保存到用户主目录下的 `~/cookies.json`，可根据需要修改 `src/login.ts` 中的路径。
+若需要更改 Cookie 保存位置，可在 `src/login.ts` 中调整 `COOKIES_PATH` 定义。
 
-## 滑块验证自动化
+## 工作流程说明
 
-本项目集成了滑块验证码自动破解功能，参考了 [crack-slide-captcha](https://github.com/omigo/crack-slide-captcha) 项目。
+1. 读取 `DOUBAN_PHONE`，未提供则直接退出；
+2. 若存在 `~/douban-cookie.json`，加载后访问登录页并校验登录态；
+3. 如未登录，执行短信验证码流程，期间需手动处理页面可能出现的滑块或图形验证码；
+4. 用户在终端输入收到的短信验证码；
+5. 验证通过后，将当前浏览器上下文的 `storageState` 写入 `~/douban-cookie.json`。
 
-### 核心特性
+## 常见问题
 
-- 🔍 **智能识别**：通过图像处理自动计算滑动距离
-- 🎭 **模拟真人**：先快后慢的速度曲线、轨迹抖动、随机反应时间
-- 🔄 **多次重试**：支持偏移修正，提高成功率
-- ⚙️ **高度可配**：支持自定义选择器、距离、偏移等参数
+- **登录后仍提示手机号未填写？** 确认 Playwright 浏览器窗口焦点在页面内，避免浏览器阻止自动填充。
+- **提示滑块验证但脚本无动作？** 脚本已停止自动滑块功能，请在浏览器中手动拖动滑块完成验证。
+- **Cookie 未生成？** 只有当脚本确认登录成功时才会写入 Cookie。若终端未看到 “登录成功，Cookies 已保存…” 的日志，请检查短信验证码是否正确。
 
-### 快速使用
+## 声明
+
+该项目仅供学习与功能验证，请勿用于违反豆瓣平台服务条款的场景。开发者需自行承担使用风险。
 
 ```bash
 # 启用自动滑块验证