deepspider 0.3.0 → 0.3.2

package/src/agent/skills/dynamic-analysis/SKILL.md

@@ -1,20 +1,26 @@
 ---
 name: dynamic-analysis
 description: |
-  JS 动态调试经验。断点技巧、Hook 策略、反调试绕过。
-  触发：运行时调试、拦截加密调用、绕过反调试。
+  JS 动态调试经验。请求追踪、调用栈分析、initiator、断点技巧、Hook 策略、反调试绕过。
+  触发：运行时调试、拦截加密调用、绕过反调试、请求追踪、调用栈、initiator。
 ---
 
 # 动态分析经验
 
 ## 定位技巧
 
-**XHR 断点法（最高效）：**
-1. 在目标请求 URL 设断点
-2. 触发请求，断住后看调用栈
-3. 从下往上找 encrypt/sign 相关函数
+**Initiator 追溯法（最高效，首选）：**
+1. get_request_list 找到目标请求（注意 hasInitiator 标记）
+2. get_request_initiator 获取调用栈
+3. 调用栈直接指向发起请求的函数位置（脚本URL + 行号）
+4. get_function_code 提取该函数及依赖
 
-**Hook 观察法：**
+**XHR 断点法（Initiator 不可用时）：**
+1. set_xhr_breakpoint(urlPattern) — 设置 URL 关键词断点
+2. 触发请求，断住后 get_call_stack
+3. 从栈底向上找 encrypt/sign 相关函数
+
+**Hook 观察法（需要持续监控时）：**
 1. 注入通用加密 Hook
 2. 触发操作，观察日志
 3. 根据日志定位具体函数
@@ -89,3 +95,64 @@ obj.func = function(...args) {
 - 现象：页面变卡
 - 原因：调用栈记录开销大
 - 经验：关闭 `captureStack` 或启用 `silent` 模式
+
+## 调试工作流模板
+
+### 标准 XHR 断点工作流
+1. set_xhr_breakpoint(urlPattern) — 设置 URL 关键词断点
+2. 在页面触发目标请求
+3. 断住后 get_call_stack() — 查看调用栈
+4. 从栈底向上找 encrypt/sign/token 相关帧
+5. get_frame_variables(frameIndex) — 查看关键帧的变量
+6. evaluate_at_breakpoint('JSON.stringify(arguments)') — 获取函数入参
+7. resume_execution() — 放行，观察下一次断住
+
+### Cookie 生成追踪工作流
+1. inject_hook('cookie') — 注入 Cookie Hook
+2. 触发页面操作（登录/翻页）
+3. get_hook_logs() — 查看 Cookie 写入日志
+4. 从日志中找到目标 Cookie 的写入调用栈
+5. 根据调用栈定位生成函数
+6. set_breakpoint 在生成函数处断住，逐步分析
+
+### 加密参数追踪工作流
+1. analyze_request_params(site, id) — 识别可疑加密参数（hex/base64/hash）
+2. search_in_scripts(site, paramName) — 搜索参数赋值位置
+3. 如果搜不到（动态生成）→ set_xhr_breakpoint + 调用栈追踪
+4. 定位到加密函数后 → get_function_code 提取完整代码
+5. sandbox_execute 验证
+
+## Hook 模板库
+
+### Cookie 加密定位 Hook
+```javascript
+// 拦截 document.cookie 写入，记录调用栈
+// 使用 inject_hook('cookie') 自动注入
+// 日志格式：{ action: 'set', key, value, stack }
+```
+
+### XMLHttpRequest 参数 Hook
+```javascript
+// 拦截 XHR open/send，记录请求参数
+// 使用 inject_hook('xhr') 自动注入
+// 日志格式：{ method, url, body, headers, stack }
+```
+
+### CryptoJS 全量 Hook
+```javascript
+// 拦截 CryptoJS 所有加密/解密调用
+// 使用 generate_cryptojs_hook() 生成
+// 日志格式：{ algorithm, mode, input, key, iv, output, stack }
+```
+
+### 自定义函数 Hook 模式
+```javascript
+// 当标准 Hook 未捕获到加密调用时：
+// 1. 通过静态分析找到可疑函数名
+// 2. evaluate_at_breakpoint 注入针对性 Hook：
+//    const _orig = window.targetFunc;
+//    window.targetFunc = function(...args) {
+//      console.log('[Hook]', args, new Error().stack);
+//      return _orig.apply(this, args);
+//    };
+```

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

@@ -70,3 +70,78 @@ var document = {
 | headless | `navigator.plugins.length` |
 | canvas | `toDataURL()` |
 | WebGL | `getParameter()` |
+
+## 完整环境补丁模板
+
+### navigator 完整补丁
+```javascript
+var navigator = {
+  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+  appVersion: '5.0 (Windows NT 10.0; Win64; x64)',
+  platform: 'Win32',
+  language: 'zh-CN',
+  languages: ['zh-CN', 'zh'],
+  cookieEnabled: true,
+  webdriver: undefined,
+  plugins: { length: 3, 0: {name: 'Chrome PDF Plugin'}, 1: {name: 'Chrome PDF Viewer'}, 2: {name: 'Native Client'} },
+  mimeTypes: { length: 4 },
+  hardwareConcurrency: 8,
+  maxTouchPoints: 0,
+  vendor: 'Google Inc.',
+  productSub: '20030107',
+};
+Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+```
+
+### localStorage / sessionStorage 补丁
+```javascript
+class FakeStorage {
+  constructor() { this._data = {}; }
+  getItem(k) { return this._data[k] ?? null; }
+  setItem(k, v) { this._data[k] = String(v); }
+  removeItem(k) { delete this._data[k]; }
+  clear() { this._data = {}; }
+  get length() { return Object.keys(this._data).length; }
+  key(i) { return Object.keys(this._data)[i] ?? null; }
+}
+var localStorage = new FakeStorage();
+var sessionStorage = new FakeStorage();
+```
+
+### XMLHttpRequest 补丁
+```javascript
+class XMLHttpRequest {
+  constructor() { this.readyState = 0; this.status = 0; this.responseText = ''; }
+  open(method, url) { this._method = method; this._url = url; this.readyState = 1; }
+  send(body) { this.readyState = 4; this.status = 200; if (this.onreadystatechange) this.onreadystatechange(); }
+  setRequestHeader() {}
+  getResponseHeader() { return null; }
+}
+```
+
+### Canvas / WebGL 指纹补丁
+```javascript
+// Canvas
+var HTMLCanvasElement = function() {};
+HTMLCanvasElement.prototype.getContext = function(type) {
+  if (type === '2d') return {
+    fillRect: () => {}, fillText: () => {}, measureText: () => ({width: 0}),
+    getImageData: () => ({data: new Uint8Array(0)}),
+  };
+  return null;
+};
+HTMLCanvasElement.prototype.toDataURL = () => 'data:image/png;base64,iVBOR...';
+
+// WebGL
+var WebGLRenderingContext = function() {};
+WebGLRenderingContext.prototype.getParameter = function(p) {
+  const map = { 7937: 'WebKit WebGL', 7936: 'WebKit', 37445: 'Google Inc.', 37446: 'ANGLE' };
+  return map[p] || 0;
+};
+```
+
+### 补环境调试策略
+1. 先跑一遍，收集所有 `xxx is not defined` 错误
+2. 按错误顺序逐个补丁（window → document → navigator → ...）
+3. 每补一个重新跑，直到无报错
+4. 对比浏览器输出验证结果一致性

package/src/agent/skills/evolve.js

@@ -3,9 +3,6 @@
  * 合并静态 SKILL.md + 动态 evolved.md
  */
 
-import fs from 'fs';
-import path from 'path';
-
 // 配置
 const MAX_RECENT_ITEMS = 10;
 const MERGE_THRESHOLD = 20;

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

@@ -20,3 +20,38 @@ description: |
 ## 验证技巧
 
 用浏览器控制台的输入输出作为测试用例，对比沙箱执行结果。
+
+## 分层验证策略
+
+### 第一层：函数级验证
+```
+1. get_function_code 提取目标函数（含依赖）
+2. sandbox_execute 直接运行
+3. 对比浏览器控制台的输出
+```
+如果报错 `xxx is not defined` → 进入第二层
+
+### 第二层：补环境验证
+```
+1. 收集报错中缺失的变量名
+2. 用 collect_env / collect_property 从浏览器采集真实值
+3. generate_patch 生成补丁
+4. sandbox_inject(补丁) + sandbox_execute(函数)
+5. 对比结果
+```
+如果结果不一致 → 进入第三层
+
+### 第三层：完整环境验证
+```
+1. generate_env_dump_code 生成全量环境自吐
+2. 在浏览器执行，收集完整环境
+3. load_all_env_modules 加载全部补丁
+4. sandbox_inject + sandbox_execute
+5. 如果仍不一致 → 检查是否有反调试/时间检测
+```
+
+### 验证对比技巧
+- 哈希值：直接字符串比较
+- 加密结果：如果有 IV/随机数，固定后再比较
+- 时间戳相关：Hook Date.now() 返回固定值
+- 多次执行：确认结果稳定性（排除随机因素）

package/src/agent/skills/static-analysis/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: static-analysis
 description: |
-  JS 静态代码分析经验。混淆识别、加密定位、代码还原技巧。
-  触发：分析混淆代码、定位加密函数、还原算法逻辑。
+  JS 静态代码分析经验。混淆识别、加密定位、代码还原、CSS/字体反爬。
+  触发：分析混淆代码、定位加密函数、还原算法逻辑、CSS反爬、字体反爬、伪元素反爬、SVG反爬。
 ---
 
 # 静态分析经验
@@ -211,3 +211,99 @@ C1C2C3 格式 (旧):
    - ey开头 → JWT
    - -----BEGIN → PEM格式密钥
 ```
+
+## CSS/字体反爬（数据混淆还原）
+
+### 字体反爬（font-face）
+**特征**：页面数字/文字显示正常，但复制出来是乱码或错误字符。
+**原理**：自定义 @font-face 将 Unicode 码点映射到不同字形。
+**破解思路**：
+1. 找到 @font-face 的 woff/ttf 文件 URL
+2. 下载字体文件，解析 cmap 表获取映射关系
+3. 建立 显示字符 → 真实字符 的映射表
+4. 替换页面文本
+
+**识别关键词**：`@font-face`、`font-family` 自定义名称、`.woff`、`.ttf`
+
+### CSS 偏移反爬
+**特征**：HTML 中数字顺序与显示不同，通过 CSS position/left/transform 重排。
+**原理**：每个数字用 span 包裹，通过 CSS 偏移到正确位置。
+**破解思路**：
+1. 获取每个 span 的 computed style（left/transform 值）
+2. 按偏移量排序还原真实顺序
+3. 或直接用 element.innerText 获取渲染后文本
+
+**识别关键词**：`position: absolute`、`left: -Npx`、`transform: translateX`
+
+### 伪元素反爬（::before/::after）
+**特征**：页面有内容但 DOM 中对应元素为空。
+**原理**：通过 CSS `content` 属性在伪元素中插入文本。
+**破解思路**：
+1. `getComputedStyle(el, '::before').content` 获取伪元素内容
+2. 或解析 CSS 样式表中的 content 规则
+
+**识别关键词**：`::before`、`::after`、`content:`
+
+### SVG 路径反爬
+**特征**：数字是 SVG 图形而非文本。
+**原理**：用 SVG path 绘制数字，无法直接提取文本。
+**破解思路**：
+1. 提取 SVG viewBox 和 path d 属性
+2. 对比已知数字的 path 特征（模板匹配）
+3. 或 OCR 识别截图
+
+### 背景图片反爬
+**特征**：数字通过 background-image + background-position 显示。
+**原理**：一张雪碧图包含所有数字，通过偏移显示特定数字。
+**破解思路**：
+1. 下载雪碧图
+2. 根据 background-position 计算显示的是哪个数字
+3. 建立 position → 数字 的映射
+
+### 快速判断流程
+
+```
+页面数字复制异常？
+├── 复制出乱码 → 字体反爬（检查 @font-face）
+├── 复制出错误顺序 → CSS 偏移（检查 position/transform）
+├── 复制为空 → 伪元素（检查 ::before/::after）或 SVG/Canvas
+└── 复制正常但值不对 → JS 动态渲染（检查 MutationObserver）
+```
+
+## 加密链路追踪
+
+### 追踪方法论
+从请求参数出发，逆向追踪到加密函数：
+
+```
+请求参数 sign=xxx
+  → analyze_correlation 找到参数来源
+  → search_in_scripts 搜索赋值位置
+  → get_function_code 提取加密函数（含依赖）
+  → 分析函数内部：识别算法 + 找到 key/iv 来源
+  → 如果 key 是动态的 → 继续追踪 key 的生成逻辑
+```
+
+### 多层加密识别
+常见模式：外层签名 + 内层加密
+```
+sign = MD5(timestamp + token + data)
+      其中 token = AES(userId, serverKey)
+      其中 serverKey = RSA_decrypt(encryptedKey, privateKey)
+```
+
+**识别技巧**：
+- 一个函数的输出是另一个函数的输入 → 链式加密
+- 同一个请求有多个加密参数 → 可能共享中间值
+- 参数名含 `sign`/`token`/`ticket` → 通常是最外层
+
+### 参数来源分类
+
+| 来源 | 特征 | 追踪方式 |
+|------|------|----------|
+| 硬编码 | 代码中直接赋值 | 静态搜索 |
+| 服务端下发 | 从接口响应中提取 | search_in_responses |
+| 页面元素 | 从 DOM 中读取 | 搜索 getElementById/querySelector |
+| Cookie | document.cookie | Cookie Hook |
+| 时间戳 | Date.now() / new Date() | 固定值即可 |
+| 随机数 | Math.random() | 固定值即可 |

package/src/agent/subagents/anti-detect.js

@@ -3,19 +3,17 @@
  * 浏览器指纹管理、代理池、风控规避
  */
 
-import { createSkillsMiddleware } from 'deepagents';
-import { SKILLS, skillsBackend } from '../skills/config.js';
-import { createFilterToolsMiddleware } from '../middleware/filterTools.js';
+import { createSubagent } from './factory.js';
 
 import { antiDetectTools } from '../tools/index.js';
 import { browserTools } from '../tools/browser.js';
+import { profileTools } from '../tools/profile.js';
 import { fileTools } from '../tools/file.js';
-import { evolveTools } from '../tools/evolve.js';
 
-export const antiDetectSubagent = {
+export const antiDetectSubagent = createSubagent({
   name: 'anti-detect',
-  description: '反检测专家。当目标网站有风控检测、IP封禁、指纹识别时使用，适用于：代理IP配置、浏览器指纹伪装、请求特征修改、风控规避。',
-  systemPrompt: `你是 DeepSpider 的反检测专家，负责绑过网站的反爬虫检测。
+  description: '反检测专家。适用于：代理 IP 配置与轮换、浏览器指纹伪装、请求特征修改、风控规避策略。不能做加密分析、不能反混淆、不能处理验证码。',
+  systemPrompt: `你是 DeepSpider 的反检测专家，负责绕过网站的反爬虫检测。
 
 ## 核心职责
 配置反检测环境，规避风控系统，确保爬虫稳定运行。
@@ -25,21 +23,13 @@ export const antiDetectSubagent = {
 - 浏览器指纹：指纹伪装
 - 行为检测：模拟人类操作
 - TLS 指纹：使用真实浏览器
-
-## 经验记录
-完成反检测配置后，如发现有价值的经验，使用 evolve_skill 记录：
-- skill: "anti-detect"`,
+`,
   tools: [
     ...antiDetectTools,
     ...browserTools,
+    ...profileTools,
     ...fileTools,
-    ...evolveTools,
-  ],
-  middleware: [
-    createFilterToolsMiddleware(),
-    createSkillsMiddleware({
-      backend: skillsBackend,
-      sources: [SKILLS.antiDetect],
-    }),
   ],
-};
+  skills: ['antiDetect'],
+  evolveSkill: 'anti-detect',
+});

package/src/agent/subagents/captcha.js

@@ -3,18 +3,15 @@
  * 识别和绕过各类验证码
  */
 
-import { createSkillsMiddleware } from 'deepagents';
-import { SKILLS, skillsBackend } from '../skills/config.js';
-import { createFilterToolsMiddleware } from '../middleware/filterTools.js';
+import { createSubagent } from './factory.js';
 
 import { captchaTools } from '../tools/captcha.js';
 import { browserTools } from '../tools/browser.js';
 import { fileTools } from '../tools/file.js';
-import { evolveTools } from '../tools/evolve.js';
 
-export const captchaSubagent = {
+export const captchaSubagent = createSubagent({
   name: 'captcha',
-  description: '验证码处理专家。当遇到验证码需要识别或绕过时使用，适用于：图片验证码OCR、滑块验证码、点选验证码、短信验证码处理。',
+  description: '验证码处理专家。适用于：图片验证码 OCR、滑块验证码缺口检测与轨迹模拟、点选验证码目标检测。不能做加密分析、不能反混淆、不能生成爬虫脚本。',
   systemPrompt: `你是 DeepSpider 的验证码处理专家，负责识别和绕过各类验证码。
 
 ## 核心职责
@@ -31,21 +28,12 @@ export const captchaSubagent = {
 2. 选择处理策略
 3. 执行验证
 4. 检查结果，失败则重试
-
-## 经验记录
-完成验证码处理后，如发现有价值的经验，使用 evolve_skill 记录：
-- skill: "captcha"`,
+`,
   tools: [
     ...captchaTools,
     ...browserTools,
     ...fileTools,
-    ...evolveTools,
-  ],
-  middleware: [
-    createFilterToolsMiddleware(),
-    createSkillsMiddleware({
-      backend: skillsBackend,
-      sources: [SKILLS.captcha],
-    }),
   ],
-};
+  skills: ['captcha'],
+  evolveSkill: 'captcha',
+});

package/src/agent/subagents/crawler.js

@@ -3,28 +3,24 @@
  * 智能调度、流程规划、脚本生成
  */
 
-import { createSkillsMiddleware } from 'deepagents';
-import { SKILLS, skillsBackend } from '../skills/config.js';
-import { createFilterToolsMiddleware } from '../middleware/filterTools.js';
+import { createSubagent } from './factory.js';
 
 import { crawlerTools } from '../tools/crawler.js';
 import { fileTools } from '../tools/file.js';
-import { evolveTools } from '../tools/evolve.js';
 import { storeTools } from '../tools/store.js';
+import { getPageSource, getElementHtml } from '../tools/browser.js';
 
-export const crawlerSubagent = {
+export const crawlerSubagent = createSubagent({
   name: 'crawler',
-  description: '爬虫编排专家。当需要规划完整爬虫流程、生成爬虫脚本、进行端到端测试时使用。负责分析目标网站复杂度，按需调度其他子代理，输出完整可运行的爬虫代码。',
+  description: '爬虫编排专家。适用于：规划完整爬虫流程、整合各模块生成完整 Python 爬虫脚本。不能做加密分析、不能反混淆、不能控制浏览器。依赖其他子代理提供加密/验证码等模块。',
   systemPrompt: `你是 DeepSpider 的爬虫编排专家，负责生成完整可运行的 Python 爬虫脚本。
 
 ## 核心职责
 **最终目标：输出一份用户可以直接 python crawler.py 运行的完整爬虫代码**
 
-1. 分析目标网站，识别需要处理的环节
-2. 调度其他子代理获取各模块代码
-3. 整合所有模块，生成完整 Python 爬虫脚本
-4. E2E 测试验证脚本可运行
-5. 输出最终代码文件
+1. 根据主 agent 提供的分析结果和已验证的代码模块，整合生成完整 Python 爬虫脚本
+2. 使用 artifact_save 保存代码文件
+3. 输出最终代码文件路径
 
 ## 网站复杂度分级
 
@@ -46,16 +42,15 @@ export const crawlerSubagent = {
 - 设备指纹检测
 - 行为分析
 
-## 调度策略
+## 输入来源
 
-根据网站特征，按需调用子代理获取代码模块：
+主 agent 会在 task description 中提供：
+- 接口分析结果（URL、方法、参数、Headers）
+- 已验证的加密代码文件路径（如有）
+- 用户选择的框架（requests / scrapy / playwright 等）
 
-| 网站特征 | 调用子代理 | 获取模块 |
-|----------|-----------|----------|
-| 有加密参数 | static → js2python | crypto.py |
-| 有验证码 | captcha 分析 | 生成验证码处理代码 |
-| 有风控 | anti-detect 分析 | 生成反检测配置代码 |
-| 需要登录 | dynamic 分析 | 生成登录流程代码 |
+你的任务是基于这些信息整合生成完整爬虫脚本，不需要自己分析加密或调度其他子代理。
+如需查看已有的加密代码，用 \`query_store\` 或 \`artifact_load\` 读取。
 
 ## 输出规范
 
@@ -113,26 +108,19 @@ if __name__ == "__main__":
 \`\`\`
 
 ## 工作流程
-1. 分析网站特征
-2. 调度子代理获取模块
-3. 整合为完整脚本
-4. E2E 验证
-5. 输出文件
-
-## 经验记录
-完成爬虫编排后，如发现有价值的经验，使用 evolve_skill 记录：
-- skill: "crawler"`,
+1. 读取主 agent 提供的分析结果和已有代码模块（query_store / artifact_load）
+2. 整合为完整可运行的 Python 爬虫脚本
+3. 使用 artifact_save 保存文件
+4. 输出文件路径
+`,
   tools: [
     ...crawlerTools,
     ...fileTools,
-    ...evolveTools,
     ...storeTools,
+    // 页面结构分析（主 agent 不持有，防止拉 HTML 自己分析 JS）
+    getPageSource,
+    getElementHtml,
   ],
-  middleware: [
-    createFilterToolsMiddleware(),
-    createSkillsMiddleware({
-      backend: skillsBackend,
-      sources: [SKILLS.crawler, SKILLS.xpath],
-    }),
-  ],
-};
+  skills: ['crawler', 'xpath'],
+  evolveSkill: 'crawler',
+});