deepspider 0.3.1 → 0.4.0

package/src/agent/run.js

@@ -10,13 +10,17 @@ import readline from 'readline';
 import { readFileSync } from 'fs';
 import { marked } from 'marked';
 import { createDeepSpiderAgent } from './index.js';
-import { fullAnalysisPrompt } from './prompts/system.js';
+import { fullAnalysisPrompt, tracePrompt, decryptPrompt, extractPrompt } from './prompts/system.js';
 import { getBrowser } from '../browser/index.js';
 import { markHookInjected } from './tools/runtime.js';
+import { getDataStore } from '../store/DataStore.js';
 import { createLogger } from './logger.js';
 import { browserTools } from './tools/browser.js';
 import { ensureConfig } from './setup.js';
+import { getConfigValues } from '../config/settings.js';
+import { PATHS, ensureDir } from '../config/paths.js';
 import { StreamHandler, PanelBridge } from './core/index.js';
+import { createCheckpointer, generateThreadId, createSession, listSessions, touchSession, cleanExpiredSessions } from './sessions.js';
 
 let rl = null;
 let browser = null;
@@ -26,14 +30,15 @@ let DEBUG = false;
 let debugFn = () => {};
 let agent = null;
 let agentConfig = null;
+let currentThreadId = null;
+let isResuming = false;
 
 /**
  * 从文件显示报告（由中间件回调触发）
  */
 async function showReportFromFile(mdFilePath) {
-  const page = browser?.getPage?.();
-  if (!page) {
-    console.log('[report] 错误: 无法获取 page');
+  if (!browser) {
+    console.log('[report] 错误: 无浏览器实例');
     return;
   }
 
@@ -45,10 +50,15 @@ async function showReportFromFile(mdFilePath) {
     const escaped = JSON.stringify(htmlContent);
     const cdp = await browser?.getCDPSession?.();
     if (cdp) {
-      await cdp.send('Runtime.evaluate', {
-        expression: `window.__deepspider__?.showReport?.(${escaped}, true)`,
-        returnByValue: true,
-      });
+      await Promise.race([
+        cdp.send('Runtime.evaluate', {
+          expression: `window.__deepspider__?.showReport?.(${escaped}, true)`,
+          returnByValue: true,
+        }),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('showReport timeout')), 5000)
+        ),
+      ]);
     }
     console.log('[report] 已显示分析报告');
   } catch (e) {
@@ -56,11 +66,40 @@ async function showReportFromFile(mdFilePath) {
   }
 }
 
+function getActionPrompt(action) {
+  switch (action) {
+    case 'trace': return tracePrompt;
+    case 'decrypt': return decryptPrompt;
+    case 'extract': return extractPrompt;
+    case 'full':
+    default: return fullAnalysisPrompt;
+  }
+}
+
+/**
+ * 生成轻量浏览器状态摘要（注入 prompt，帮助主 agent 判断和委派）
+ * 只含计数信息，不含实际数据
+ */
+function getBrowserStateSummary() {
+  try {
+    const store = getDataStore();
+    const sites = store.getSiteList();
+    if (!sites.length) return '';
+
+    const lines = sites.map(s =>
+      `  - ${s.hostname}: ${s.responseCount} 条请求, ${s.scriptCount} 个脚本`
+    );
+    return `\n已捕获数据:\n${lines.join('\n')}`;
+  } catch {
+    return '';
+  }
+}
+
 /**
  * 处理浏览器消息（通过 CDP binding 接收）
  */
-async function handleBrowserMessage(data, page) {
-  debugFn(`handleBrowserMessage: 收到消息, type=${data.type}, page=${!!page}`);
+async function handleBrowserMessage(data) {
+  debugFn(`handleBrowserMessage: 收到消息, type=${data.type}`);
 
   const browserReadyPrefix = '[浏览器已就绪] ';
 
@@ -72,12 +111,13 @@ async function handleBrowserMessage(data, page) {
     ).join('\n');
 
     const supplementText = data.text ? `\n\n用户补充说明: ${data.text}` : '';
+    const action = data.action || 'full';
 
-    userPrompt = `${browserReadyPrefix}用户选中了以下数据要求完整分析：
+    userPrompt = `${browserReadyPrefix}用户选中了以下数据：
 
 ${elementsDesc}${supplementText}
 
-${fullAnalysisPrompt}`;
+${getActionPrompt(action)}`;
   } else if (data.type === 'generate-config') {
     const config = data.config;
     userPrompt = `${browserReadyPrefix}请使用 crawler 子代理生成爬虫。
@@ -89,16 +129,21 @@ ${JSON.stringify(config.fields, null, 2)}
 
 请先用 query_store 查询已有的加密代码，然后整合生成配置和脚本。`;
   } else if (data.type === 'chat') {
+    const pageUrl = browser?.getPage()?.url?.() || targetUrl || '';
+    const urlLine = pageUrl ? `当前页面: ${pageUrl}\n` : '';
+    const stateSummary = getBrowserStateSummary();
     if (data.elements && data.elements.length > 0) {
       const elementsDesc = data.elements.map((el, i) =>
         `${i + 1}. "${el.text?.slice(0, 100) || ''}"\n   XPath: ${el.xpath}`
       ).join('\n');
-      userPrompt = `${browserReadyPrefix}${data.text}
+      userPrompt = `${browserReadyPrefix}${urlLine}${stateSummary}
+
+${data.text}
 
 用户选中的元素：
 ${elementsDesc}`;
     } else {
-      userPrompt = `${browserReadyPrefix}${data.text}`;
+      userPrompt = `${browserReadyPrefix}${urlLine}${stateSummary}\n\n${data.text}`;
     }
   } else if (data.type === 'open-file') {
     let filePath = data.path;
@@ -117,12 +162,41 @@ ${elementsDesc}`;
       });
     }
     return;
+  } else if (data.type === 'choice') {
+    // interrupt 恢复：用户点击了选项
+    console.log('\n[浏览器] 用户选择: ' + data.value);
+    await streamHandler.resumeInterrupt(data.value);
+    console.log('\n');
+    process.stdout.write('> ');
+    return;
+  } else if (data.type === 'confirm-result') {
+    // interrupt 恢复：用户点击了确认/取消
+    console.log('\n[浏览器] 用户' + (data.confirmed ? '确认' : '取消'));
+    await streamHandler.resumeInterrupt(data.confirmed);
+    console.log('\n');
+    process.stdout.write('> ');
+    return;
+  } else if (data.type === 'resume') {
+    if (isResuming) return;
+    isResuming = true;
+    console.log('\n[恢复] 用户选择恢复 session: ' + data.threadId);
+    currentThreadId = data.threadId;
+    agentConfig.configurable.thread_id = data.threadId;
+    try {
+      await streamHandler.chatStreamResume();
+    } finally {
+      isResuming = false;
+    }
+    console.log('\n');
+    process.stdout.write('> ');
+    return;
   } else {
     return;
   }
 
   console.log('\n[浏览器] ' + (data.type === 'analysis' ? '分析请求' : data.type === 'generate-config' ? '生成配置' : '对话'));
   await streamHandler.chatStream(userPrompt);
+  if (currentThreadId) touchSession(currentThreadId);
   console.log('\n');
   process.stdout.write('> ');
 }
@@ -140,7 +214,13 @@ function prompt() {
       return;
     }
 
-    await streamHandler.chatStream(input);
+    let enrichedInput = input;
+    if (browser) {
+      const url = browser.getPage()?.url?.() || targetUrl || '';
+      enrichedInput = `[浏览器已就绪] 当前页面: ${url}\n\n${input}`;
+    }
+    await streamHandler.chatStream(enrichedInput);
+    if (currentThreadId) touchSession(currentThreadId);
     console.log('\n');
     prompt();
   });
@@ -151,6 +231,8 @@ async function init() {
   const args = process.argv.slice(2);
   targetUrl = args.find(arg => arg.startsWith('http://') || arg.startsWith('https://'));
   DEBUG = process.env.DEBUG === 'true' || args.includes('--debug');
+  const PERSIST = args.includes('--persist');
+  const RESUME = args.includes('--resume');
   debugFn = (...a) => { if (DEBUG) console.log('[DEBUG]', ...a); };
 
   debugFn('init: 启动');
@@ -169,23 +251,57 @@ async function init() {
     output: process.stdout,
   });
 
-  const logger = createLogger({ enabled: DEBUG, verbose: false });
+  const loggerCallbacks = createLogger();
 
   async function onReportReady(mdFilePath) {
     console.log('[report] 中间件触发报告显示:', mdFilePath);
     await showReportFromFile(mdFilePath);
   }
 
-  agent = createDeepSpiderAgent({ onReportReady });
+  // panelBridge 引用，在后面初始化后赋值
+  let sharedPanelBridge = null;
 
+  async function onFileSaved({ path, type }) {
+    console.log(`[report] 文件已保存: ${path} (${type})`);
+    if (!sharedPanelBridge) return;
+    const shortPath = path.replace(process.env.HOME || '', '~');
+    await sharedPanelBridge.sendMessage('file-saved', { path: shortPath, type });
+  }
+
+  // 持久化 checkpointer + session 管理
+  const checkpointer = createCheckpointer();
+  cleanExpiredSessions();
+  let domain = targetUrl ? new URL(targetUrl).hostname : null;
+  let threadId;
+  let autoResume = false;
+
+  if (RESUME && domain) {
+    const existing = listSessions(domain);
+    if (existing.length > 0) {
+      threadId = existing[0].thread_id;
+      autoResume = true;
+      console.log(`[恢复] 找到上次 session: ${threadId}`);
+      console.log(`[恢复] 上次活跃: ${new Date(existing[0].updated_at).toLocaleString()}, 消息数: ${existing[0].message_count}`);
+    }
+  }
+
+  if (!threadId) {
+    threadId = domain ? generateThreadId(domain) : `deepspider-${Date.now()}`;
+    if (domain) createSession(threadId, domain, targetUrl);
+  }
+
+  agent = createDeepSpiderAgent({ onReportReady, onFileSaved, checkpointer });
+
+  currentThreadId = threadId;
   agentConfig = {
-    configurable: { thread_id: `deepspider-${Date.now()}` },
+    configurable: { thread_id: threadId },
     recursionLimit: 5000,
-    callbacks: logger ? [logger] : [],
+    callbacks: loggerCallbacks,
   };
 
   // 初始化流处理器
   const panelBridge = new PanelBridge(() => browser, debugFn);
+  sharedPanelBridge = panelBridge;
   streamHandler = new StreamHandler({
     agent,
     config: agentConfig,
@@ -201,7 +317,14 @@ async function init() {
     console.log(`正在打开: ${targetUrl}\n`);
     try {
       debugFn('init: 获取浏览器实例');
-      browser = await getBrowser();
+      const browserOptions = {};
+      const config = getConfigValues();
+      if (PERSIST || config.persistBrowserData) {
+        ensureDir(PATHS.BROWSER_DATA_DIR);
+        browserOptions.userDataDir = PATHS.BROWSER_DATA_DIR;
+        console.log(`[持久化模式] 浏览器数据保存在 ${PATHS.BROWSER_DATA_DIR}`);
+      }
+      browser = await getBrowser(browserOptions);
       browser.onMessage = handleBrowserMessage;
       debugFn('init: 导航到目标URL');
       await browser.navigate(targetUrl);
@@ -209,6 +332,31 @@ async function init() {
       debugFn('init: 浏览器就绪');
       console.log('浏览器已就绪，数据自动记录中');
       console.log('点击面板选择按钮(⦿)选择数据进行分析\n');
+
+      // 恢复逻辑
+      if (autoResume) {
+        console.log('[恢复] 从上次中断处继续...\n');
+        await streamHandler.chatStreamResume();
+        console.log('\n');
+      } else if (domain) {
+        const existing = listSessions(domain).filter(s => s.thread_id !== threadId && s.message_count > 0);
+        if (existing.length > 0) {
+          const ready = await panelBridge.waitForPanel();
+          if (ready) {
+            const s = existing[0];
+            const ago = Math.round((Date.now() - s.updated_at) / 60000);
+            const timeStr = ago < 60 ? `${ago}分钟前` : `${Math.round(ago / 60)}小时前`;
+            await panelBridge.sendMessage('resume-available', {
+              threadId: s.thread_id,
+              domain: s.domain,
+              messageCount: s.message_count,
+              timeAgo: timeStr,
+            });
+          } else {
+            debugFn('init: 面板未就绪，跳过恢复横幅');
+          }
+        }
+      }
     } catch (error) {
       console.error('启动浏览器失败:', error.message);
       debugFn('init: 浏览器启动失败 -', error.stack);

package/src/agent/sessions.js

@@ -0,0 +1,88 @@
+/**
+ * DeepSpider - Session 管理
+ * 基于 SQLite 持久化 session 元数据，支持跨进程恢复
+ */
+
+import Database from 'better-sqlite3';
+import { join } from 'path';
+import { SqliteSaver } from '@langchain/langgraph-checkpoint-sqlite';
+import { DEEPSPIDER_HOME, ensureDir } from '../config/paths.js';
+
+const DB_PATH = join(DEEPSPIDER_HOME, 'sessions.db');
+const CHECKPOINT_DB_PATH = join(DEEPSPIDER_HOME, 'checkpoints.db');
+const SESSION_EXPIRE_DAYS = 7;
+
+let _db = null;
+
+function getDb() {
+  if (!_db) {
+    ensureDir(DEEPSPIDER_HOME);
+    _db = new Database(DB_PATH);
+    _db.pragma('journal_mode=WAL');
+    _db.exec(`
+CREATE TABLE IF NOT EXISTS sessions (
+  thread_id TEXT PRIMARY KEY,
+  domain TEXT NOT NULL,
+  url TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  message_count INTEGER DEFAULT 0,
+  status TEXT DEFAULT 'active'
+)`);
+  }
+  return _db;
+}
+
+/**
+ * 创建 LangGraph checkpointer（独立 DB 文件，避免与 session 元数据竞争）
+ */
+export function createCheckpointer() {
+  ensureDir(DEEPSPIDER_HOME);
+  return SqliteSaver.fromConnString(CHECKPOINT_DB_PATH);
+}
+
+/**
+ * 生成 thread_id
+ */
+export function generateThreadId(domain) {
+  return `deepspider-${domain}-${Date.now()}`;
+}
+
+/**
+ * 创建新 session
+ */
+export function createSession(threadId, domain, url) {
+  const now = Date.now();
+  getDb().prepare(
+    'INSERT INTO sessions (thread_id, domain, url, created_at, updated_at) VALUES (?, ?, ?, ?, ?)'
+  ).run(threadId, domain, url, now, now);
+}
+
+/**
+ * 更新 session 活跃时间和消息数
+ */
+export function touchSession(threadId) {
+  getDb().prepare('UPDATE sessions SET updated_at = ?, message_count = message_count + 1 WHERE thread_id = ?')
+    .run(Date.now(), threadId);
+}
+
+/**
+ * 清理过期 session
+ */
+export function cleanExpiredSessions() {
+  const cutoff = Date.now() - SESSION_EXPIRE_DAYS * 86400000;
+  getDb().prepare('DELETE FROM sessions WHERE updated_at < ?').run(cutoff);
+}
+
+/**
+ * 列出可恢复的 session（按域名过滤，7天内）
+ */
+export function listSessions(domain = null) {
+  const db = getDb();
+  const cutoff = Date.now() - SESSION_EXPIRE_DAYS * 86400000;
+  const sql = domain
+    ? 'SELECT * FROM sessions WHERE domain = ? AND status = ? AND updated_at >= ? ORDER BY updated_at DESC'
+    : 'SELECT * FROM sessions WHERE status = ? AND updated_at >= ? ORDER BY updated_at DESC';
+  const params = domain ? [domain, 'active', cutoff] : ['active', cutoff];
+  return db.prepare(sql).all(...params);
+}

package/src/agent/skills/anti-detect/SKILL.md

@@ -1,28 +1,103 @@
 ---
 name: anti-detect
 description: |
-  反检测经验。浏览器指纹、代理IP、风控规避技巧。
+  反检测经验。浏览器指纹、代理IP、TLS指纹、行为检测、风控规避技巧。
+  触发：反爬绕过、IP封禁、指纹检测、风控拦截、403/429处理。
 ---
 
 # 反检测经验
 
+## 快速诊断流程
+
+```
+请求被拦截？
+├── 403 Forbidden
+│   ├── 换 IP 后正常 → IP 黑名单
+│   ├── 换 IP 仍 403 → 指纹/TLS 检测
+│   └── 带 Cookie 正常 → Cookie 验证
+├── 429 Too Many Requests → 频率限制
+├── 返回验证码页面 → 风控触发（转 captcha）
+├── 返回空数据/假数据 → 静默风控
+└── JS 渲染异常 → 环境检测
+```
+
 ## 浏览器指纹
 
-### 常见检测点
-- navigator.webdriver
-- window.chrome
-- Canvas 指纹
-- WebGL 指纹
+### 检测点与绕过
+
+| 检测项 | 检测方式 | 绕过策略 |
+|--------|----------|----------|
+| webdriver | `navigator.webdriver` | Patchright 已自动处理 |
+| chrome 对象 | `window.chrome` 存在性 | Patchright 已自动处理 |
+| Canvas | `toDataURL()` 哈希 | 注入噪声或固定返回值 |
+| WebGL | `getParameter()` 渲染器信息 | 伪造 vendor/renderer 字符串 |
+| Audio | `AudioContext` 指纹 | 固定 oscillator 输出 |
+| 字体 | `measureText()` 宽度差异 | 安装常见字体集 |
+| 屏幕 | `screen.width/height` | 设置 viewport 匹配常见分辨率 |
+| 插件 | `navigator.plugins.length` | 注入常见插件列表 |
+
+### 指纹一致性原则
+- 同一 Profile 内所有指纹项必须自洽（如 UA 说 Windows 但 platform 说 MacIntel 会被检测）
+- User-Agent 与 navigator 属性、屏幕分辨率、时区要匹配
+- 持久化 Profile 复用，避免每次生成新指纹
 
 ## 代理 IP
 
-### 代理类型
-- HTTP/HTTPS 代理
-- SOCKS5 代理
-- 隧道代理
+### 代理选型
+
+| 类型 | 适用场景 | 特点 |
+|------|----------|------|
+| 数据中心代理 | 大规模采集、对 IP 质量要求不高 | 便宜、速度快、易被识别 |
+| 住宅代理 | 反检测要求高的网站 | 贵、IP 质量高、不易被封 |
+| ISP 代理 | 需要固定 IP 的场景 | 稳定、速度快 |
+| 移动代理 | 移动端 API 采集 | IP 池大、信任度高 |
+
+### 轮换策略
+- 每个 IP 请求次数上限（根据目标网站调整，通常 10-50 次）
+- 被封后标记冷却时间，不要立即重试
+- 同一 session 保持同一 IP（避免 Cookie 与 IP 绑定检测）
+
+## TLS 指纹
+
+### JA3/JA4 指纹
+- 原理：TLS 握手中的 cipher suites、extensions 顺序构成唯一指纹
+- requests 库的 JA3 与真实浏览器不同，容易被识别
+- 绕过方案：
+  - `curl_cffi`：模拟 Chrome/Firefox 的 TLS 指纹
+  - `tls_client`：Go 实现的 TLS 客户端
+  - Patchright/Playwright：真实浏览器，指纹天然正确
+
+### HTTP/2 指纹
+- 部分网站检测 HTTP/2 的 SETTINGS 帧和优先级
+- requests 不支持 HTTP/2，用 `httpx` 或 `curl_cffi`
+
+## 行为检测
+
+### 常见检测维度
+- 鼠标轨迹：是否有自然的移动路径
+- 点击间隔：是否过于均匀
+- 滚动行为：是否有自然的加速减速
+- 页面停留时间：是否过短
+- 请求顺序：是否跳过了正常浏览流程（如直接请求 API 不加载页面）
+
+### 应对策略
+- 请求间隔随机化：`random.uniform(1, 3)` 秒
+- 模拟正常浏览流程：先请求页面 → 加载静态资源 → 再请求 API
+- Referer 链完整：每个请求的 Referer 要与浏览路径一致
+
+## 常见风控系统
 
-## 风控规避
+| 系统 | 识别特征 | 绕过难度 |
+|------|----------|----------|
+| Cloudflare | `cf-` 前缀 Cookie、JS Challenge | 高（建议用浏览器方案） |
+| Akamai | `_abck` Cookie、sensor_data | 高 |
+| PerimeterX | `_px` 前缀 Cookie | 高 |
+| 瑞数信息 | `$_ts` 变量、动态 JS | 极高 |
+| 同盾 | 设备指纹 + 行为分析 | 中高 |
+| 极验 | 滑块/点选验证码 | 中（转 captcha 处理） |
 
-### 请求频率
-- 随机延迟
-- 分布式请求
+### 通用原则
+- 能用请求重放就不用浏览器（性能好）
+- 请求重放被拦截再升级到浏览器方案
+- 浏览器方案优先用 Patchright（反检测最好）
+- 遇到瑞数/Akamai 等高强度风控，考虑补环境方案或放弃纯请求

package/src/agent/skills/captcha/SKILL.md

@@ -2,36 +2,110 @@
 name: captcha
 description: |
   验证码处理经验。滑块验证码、图片验证码、点选验证码的识别与绕过技巧。
+  触发：验证码识别、滑块绕过、OCR、点选验证码、验证码拦截。
 ---
 
 # 验证码处理经验
 
+## 快速识别流程
+
+```
+页面出现验证码？
+├── 有滑动条 + 背景图 + 滑块图 → 滑块验证码
+├── 有图片 + 输入框 → 图片验证码（OCR）
+├── 有背景图 + 文字/图标提示 → 点选验证码
+├── 有旋转图片 → 旋转验证码
+├── 有拼图 → 拼图验证码（类似滑块）
+└── 弹出第三方页面（极验/网易/腾讯）→ 第三方验证码服务
+```
+
 ## 滑块验证码
 
-### 缺口检测
-- 边缘检测：Canny 算法定位缺口边缘
-- 模板匹配：滑块图与背景图匹配
+### 缺口检测方法
+
+| 方法 | 适用场景 | 精度 |
+|------|----------|------|
+| Canny 边缘检测 | 缺口边缘清晰 | 高 |
+| 模板匹配 | 有独立滑块图片 | 高 |
+| 像素差异对比 | 有完整背景图和缺口背景图 | 最高 |
+| 灰度梯度 | 缺口区域与背景对比度大 | 中 |
+
+### 轨迹生成参数
 
-### 轨迹生成要点
-- 起始慢，中间快，结束慢
-- 添加微小随机抖动
-- 总时长 300-800ms
-- 结束时有轻微回弹
+```
+总时长: 300-800ms（过快被检测，过慢不自然）
+阶段分配:
+  - 起步 (0-15%): 加速，速度从 0 到峰值
+  - 中段 (15-75%): 匀速或微加速
+  - 减速 (75-90%): 明显减速
+  - 微调 (90-100%): 缓慢靠近 + 轻微回弹 (1-3px)
+
+Y 轴抖动: ±1-2px 随机偏移（纯水平移动会被检测）
+采样间隔: 10-30ms（模拟 requestAnimationFrame）
+```
+
+### 常见失败原因
+- 缺口偏移量不准 → 加 ±2px 随机偏移重试
+- 轨迹太规则 → 增加 Y 轴抖动和速度波动
+- 滑动太快 → 总时长调到 500ms+
+- 验证接口校验 → 检查是否需要额外参数（如 trace 数据、加密 token）
 
 ## 图片验证码
 
-### OCR 选择
-- ddddocr：开源免费，识别率一般
-- 打码平台：付费，识别率高
+### OCR 方案选择
+
+| 方案 | 识别率 | 成本 | 适用场景 |
+|------|--------|------|----------|
+| ddddocr | 60-80% | 免费 | 简单数字/字母验证码 |
+| Tesseract + 预处理 | 50-70% | 免费 | 清晰文字 |
+| 打码平台 (超级鹰等) | 90%+ | 付费 | 复杂验证码、量大 |
+| 自训练模型 | 95%+ | 开发成本高 | 固定样式、长期使用 |
 
-### 预处理技巧
-- 二值化去除背景
-- 去噪点
-- 字符分割
+### 图片预处理流程
+1. 灰度化 → 去除颜色干扰
+2. 二值化 → 分离文字和背景（阈值需调试）
+3. 去噪点 → 中值滤波或形态学操作
+4. 字符分割 → 连通域分析（粘连字符需特殊处理）
+
+### 常见失败原因
+- 背景干扰线 → 加强二值化阈值或用形态学开运算
+- 字符粘连 → 投影分割或滴水算法
+- 字体扭曲 → ddddocr 通常比 Tesseract 更好
+- 识别错误 → 刷新验证码重试（最多 3 次）
 
 ## 点选验证码
 
-### 目标检测
-- 文字定位
-- 图标识别
-- 顺序判断
+### 处理流程
+1. 获取提示信息（"请依次点击：X、Y、Z"）
+2. 目标检测：定位背景图中每个候选目标的坐标
+3. 匹配：将提示与候选目标对应
+4. 按顺序点击坐标
+
+### 难点与应对
+- 文字点选：OCR 识别背景图中的文字位置
+- 图标点选：图像分类匹配提示图标
+- 语义点选（"点击最大的"）：需要目标检测 + 属性比较
+- 3D/旋转文字：打码平台更可靠
+
+## 第三方验证码服务
+
+| 服务商 | 常见类型 | 特征 |
+|--------|----------|------|
+| 极验 (GeeTest) | 滑块、点选、九宫格 | `gt` + `challenge` 参数 |
+| 网易易盾 | 滑块、拼图、点选 | `NECaptcha` 对象 |
+| 腾讯防水墙 | 滑块 | `TencentCaptcha` 对象 |
+| 阿里云 | 滑块、智能验证 | `ALIYUN` 前缀 |
+| hCaptcha | 图像分类 | `h-captcha` class |
+| reCAPTCHA | 图像分类、评分 | `g-recaptcha` class |
+
+### 通用应对策略
+- 优先尝试绕过：部分验证码有 API 直接获取 token 的方式
+- 浏览器方案：用 Patchright 模拟真实操作
+- 打码平台：极验/hCaptcha 等有专门的打码服务
+- 降低触发频率：通过反检测手段减少验证码出现
+
+## 验证失败通用处理
+
+1. 第 1 次失败 → 刷新验证码，调整参数重试
+2. 第 2 次失败 → 换方案（如 OCR → 打码平台）
+3. 第 3 次失败 → 返回告知主 agent，建议人工介入或换策略