deepspider 0.3.0 → 0.3.2

package/src/agent/subagents/factory.js

@@ -3,19 +3,107 @@
  * 统一子代理创建，自动注入公共配置
  */
 
+import { createMiddleware, toolRetryMiddleware, contextEditingMiddleware, ClearToolUsesEdit } from 'langchain';
 import { createSkillsMiddleware } from 'deepagents';
 import { SKILLS, skillsBackend } from '../skills/config.js';
 import { createFilterToolsMiddleware } from '../middleware/filterTools.js';
 import { evolveTools } from '../tools/evolve.js';
 
+/**
+ * 子代理工具调用上限
+ * 正常任务 30-50 次足够，80 留有余量但能防止无限循环
+ */
+const SUBAGENT_RUN_LIMIT = 80;
+
+/**
+ * 子代理执行纪律提示（精简版）
+ * 强制纪律通过 middleware 实现，而非提示词
+ */
+export const SUBAGENT_DISCIPLINE_PROMPT = `
+
+## 执行纪律
+- 先用最小代价验证假设（一次工具调用），确认可行后再展开`;
+
+/**
+ * 创建工具调用次数限制中间件
+ * - wrapToolCall 计数
+ * - wrapModelCall 达到上限后注入提示引导模型总结返回
+ * - beforeAgent 每次子代理被调用时重置计数器，避免跨任务累积
+ *
+ * 注意：callCount 通过闭包持有，假设同一子代理不会被并行调用。
+ * deepagents 当前是串行调度子代理，如果未来支持并行需改为 per-invocation 计数。
+ */
+function createToolCallLimitMiddleware(runLimit = SUBAGENT_RUN_LIMIT) {
+  let callCount = 0;
+
+  return createMiddleware({
+    name: 'toolCallLimitMiddleware',
+
+    beforeAgent: async () => {
+      callCount = 0;
+    },
+
+    wrapToolCall: async (request, handler) => {
+      callCount++;
+
+      // 超过上限直接阻止，不经过 LLM
+      if (callCount > runLimit) {
+        return {
+          type: 'tool',
+          name: request.tool?.name || request.toolCall?.name || 'unknown',
+          content: JSON.stringify({
+            success: false,
+            error: `工具调用次数已达上限 (${runLimit})。请总结当前发现并返回。`,
+            callCount,
+            runLimit,
+          }),
+          tool_call_id: request.toolCall?.id || `limit_${callCount}`,
+          status: 'error',
+        };
+      }
+
+      return handler(request);
+    },
+  });
+}
+
+/**
+ * 创建子代理基础中间件数组
+ * 包含：工具错误兜底 + 工具过滤 + 调用次数限制 + 技能注入
+ * @param {Array} skillsSources - 技能源列表
+ */
+export function createBaseMiddleware(skillsSources = []) {
+  return [
+    toolRetryMiddleware({                    // 工具错误 → ToolMessage，LLM 自我修正
+      maxRetries: 0,                          // schema 错误是确定性的，不重试
+      onFailure: (err) => `Tool call failed: ${err.message}\nPlease fix the arguments and retry.`,
+    }),
+    createFilterToolsMiddleware(),
+    createToolCallLimitMiddleware(),
+    contextEditingMiddleware({                    // 清理旧工具结果，防止上下文膨胀
+      edits: [new ClearToolUsesEdit({
+        trigger: { tokens: 80000 },               // 80k token 触发（子代理上下文较短）
+        keep: { messages: 5 },                     // 保留最近 5 条工具结果
+        excludeTools: ['save_memo'],               // scratchpad 内容不清理
+      })],
+    }),
+    createSkillsMiddleware({
+      backend: skillsBackend,
+      sources: skillsSources,
+    }),
+  ];
+}
+
 /**
  * 创建子代理配置
+ * 自动注入 evolveTools + createBaseMiddleware，减少子代理定义中的重复代码
  * @param {Object} config - 子代理配置
  * @param {string} config.name - 子代理名称
  * @param {string} config.description - 子代理描述
  * @param {string} config.systemPrompt - 系统提示
  * @param {Array} config.tools - 工具列表
- * @param {Array} [config.skills] - 技能源列表（SKILLS 枚举值）
+ * @param {Array<string>} [config.skills] - SKILLS 的 key 列表（如 ['static', 'xpath']），自动映射为路径
+ * @param {string|string[]} [config.evolveSkill='general'] - evolve_skill 的目标 skill（对应 evolve.js skillMap key），支持数组表示多领域
  * @param {Array} [config.middleware] - 额外的中间件
  * @param {boolean} [config.includeEvolve=true] - 是否包含 evolve 工具
  */
@@ -26,29 +114,41 @@ export function createSubagent(config) {
     systemPrompt,
     tools,
     skills = [],
+    evolveSkill = 'general',
     middleware = [],
     includeEvolve = true,
   } = config;
 
-  // 合并工具列表
   const finalTools = includeEvolve
     ? [...tools, ...evolveTools]
     : tools;
 
-  // 构建中间件列表
+  // skills key → SKILLS 路径值
+  const skillsSources = skills.map((key) => {
+    const source = SKILLS[key];
+    if (!source) throw new Error(`Unknown skill key: "${key}". Valid keys: ${Object.keys(SKILLS).join(', ')}`);
+    return source;
+  });
+
   const finalMiddleware = [
-    createFilterToolsMiddleware(),
-    createSkillsMiddleware({
-      backend: skillsBackend,
-      sources: skills,
-    }),
+    ...createBaseMiddleware(skillsSources),
     ...middleware,
   ];
 
+  // 自动拼接通用 prompt 段落：经验记录 + 执行纪律
+  let evolvePrompt;
+  if (Array.isArray(evolveSkill)) {
+    const list = evolveSkill.map(s => `  - "${s}"`).join('\n');
+    evolvePrompt = `\n\n## 经验记录\n完成任务后，如发现有价值的经验，使用 evolve_skill 记录。根据经验所属领域选择对应 skill：\n${list}`;
+  } else {
+    evolvePrompt = `\n\n## 经验记录\n完成任务后，如发现有价值的经验，使用 evolve_skill 记录：\n- skill: "${evolveSkill}"`;
+  }
+  const fullPrompt = systemPrompt + evolvePrompt + SUBAGENT_DISCIPLINE_PROMPT;
+
   return {
     name,
     description,
-    systemPrompt,
+    systemPrompt: fullPrompt,
     tools: finalTools,
     middleware: finalMiddleware,
   };

package/src/agent/subagents/index.js

@@ -8,33 +8,24 @@ export { createSubagent, SKILLS } from './factory.js';
 // 编排层
 export { crawlerSubagent } from './crawler.js';
 
-// 逆向分析
-export { staticSubagent } from './static.js';
-export { dynamicSubagent } from './dynamic.js';
-export { sandboxSubagent } from './sandbox.js';
+// 逆向分析（合并原 static + dynamic + sandbox + env-agent）
+export { reverseSubagent } from './reverse.js';
 export { js2pythonSubagent } from './js2python.js';
-export { envAgentSubagent } from './env-agent.js';
 
 // 爬虫能力
 export { captchaSubagent } from './captcha.js';
 export { antiDetectSubagent } from './anti-detect.js';
 
 import { crawlerSubagent } from './crawler.js';
-import { staticSubagent } from './static.js';
-import { dynamicSubagent } from './dynamic.js';
-import { sandboxSubagent } from './sandbox.js';
+import { reverseSubagent } from './reverse.js';
 import { js2pythonSubagent } from './js2python.js';
-import { envAgentSubagent } from './env-agent.js';
 import { captchaSubagent } from './captcha.js';
 import { antiDetectSubagent } from './anti-detect.js';
 
 export const allSubagents = [
   crawlerSubagent,
-  staticSubagent,
-  dynamicSubagent,
-  sandboxSubagent,
+  reverseSubagent,
   js2pythonSubagent,
-  envAgentSubagent,
   captchaSubagent,
   antiDetectSubagent,
 ];

package/src/agent/subagents/js2python.js

@@ -3,19 +3,16 @@
  * 将 JS 加密逻辑转换为 Python 代码
  */
 
-import { createSkillsMiddleware } from 'deepagents';
-import { SKILLS, skillsBackend } from '../skills/config.js';
-import { createFilterToolsMiddleware } from '../middleware/filterTools.js';
+import { createSubagent } from './factory.js';
 
 import { pythonTools } from '../tools/python.js';
 import { nodejsTools } from '../tools/nodejs.js';
 import { analyzerTools } from '../tools/analyzer.js';
 import { fileTools } from '../tools/file.js';
-import { evolveTools } from '../tools/evolve.js';
 
-export const js2pythonSubagent = {
+export const js2pythonSubagent = createSubagent({
   name: 'js2python',
-  description: 'JS转Python专家。当需要将JS加密代码转换为Python时使用，适用于：爬虫项目需要Python实现、标准加密算法转换、复杂算法使用execjs方案。',
+  description: 'JS转Python专家。适用于：将已还原的 JS 加密代码转换为 Python 实现、标准加密算法转换、复杂算法 execjs 方案。输入必须是已分析清楚的 JS 代码。不能做代码分析、不能反混淆、不能控制浏览器。',
   systemPrompt: `你是 DeepSpider 的 JS 转 Python 专家，负责将 JS 加密逻辑转换为 Python 代码。
 
 ## 核心职责
@@ -51,22 +48,13 @@ export const js2pythonSubagent = {
 纯 Python 转换失败 3 次 → 改用 execjs 方案
 
 目标是保证最终输出可用的代码。
-
-## 经验记录
-完成转换后，如发现有价值的经验，使用 evolve_skill 记录：
-- skill: "js2python"`,
+`,
   tools: [
     ...pythonTools,
     ...nodejsTools,
     ...analyzerTools,
     ...fileTools,
-    ...evolveTools,
-  ],
-  middleware: [
-    createFilterToolsMiddleware(),
-    createSkillsMiddleware({
-      backend: skillsBackend,
-      sources: [SKILLS.js2python],
-    }),
   ],
-};
+  skills: ['js2python'],
+  evolveSkill: 'js2python',
+});

package/src/agent/subagents/reverse.js

@@ -0,0 +1,180 @@
+/**
+ * DeepSpider - 逆向分析子代理
+ * 合并原 static + dynamic + sandbox + env-agent 的核心能力
+ */
+
+import { createSubagent } from './factory.js';
+
+// 数据查询（读脚本、搜索请求，不含 clear 工具）
+import {
+  getSiteList, searchInResponses, getRequestDetail, getRequestList,
+  getRequestInitiator, getScriptList, getScriptSource, searchInScripts,
+} from '../tools/tracing.js';
+// 静态分析
+import { preprocessTools } from '../tools/preprocess.js';
+import { webcrackTools } from '../tools/webcrack.js';
+import { analyzerTools } from '../tools/analyzer.js';
+import { deobfuscatorTools } from '../tools/deobfuscator.js';
+import { correlateTools } from '../tools/correlate.js';
+import { traceTools } from '../tools/trace.js';
+import { extractorTools } from '../tools/extractor.js';
+// 动态分析
+import { debugTools } from '../tools/debug.js';
+import { captureTools } from '../tools/capture.js';
+import { hookManagerTools } from '../tools/hookManager.js';
+import { generateHookTools } from '../tools/generateHook.js';
+// 沙箱 + 补环境
+import { sandboxTools } from '../tools/sandbox.js';
+import { envTools } from '../tools/env.js';
+import { envDumpTools } from '../tools/envdump.js';
+import { extractTools } from '../tools/extract.js';
+import { patchTools } from '../tools/patch.js';
+// 验证 + 执行
+import { verifyAlgorithmTools } from '../tools/verifyAlgorithm.js';
+import { nodejsTools } from '../tools/nodejs.js';
+// 输出
+import { fileTools } from '../tools/file.js';
+import { storeTools } from '../tools/store.js';
+// 页面交互（仅断点触发 + Cookie 采集所需的最小集）
+import { reloadPage, clickElement, scrollPage, getCookies, getPageSource } from '../tools/browser.js';
+// 工作记忆
+import { scratchpadTools } from '../tools/scratchpad.js';
+
+export const reverseSubagent = createSubagent({
+  name: 'reverse-agent',
+  description: '逆向分析专家。适用于：分析加密参数、反混淆、定位加密入口、还原算法、浏览器断点调试、运行时变量采集、Hook注入、沙箱执行验证、补环境。覆盖逆向分析全流程，无需在多个子代理间切换。不能生成 Python 代码（用 js2python）、不能编排爬虫（用 crawler）。',
+  systemPrompt: `你是 DeepSpider 的逆向分析专家，覆盖从代码分析到验证的完整逆向流程。
+
+## 核心能力
+- **请求追溯**：从目标请求的 initiator（调用栈）直接定位发起请求的代码位置
+- **静态分析**：预处理、解包、反混淆、AST 分析、加密入口定位
+- **动态分析**：断点调试、Hook 注入、运行时变量采集、加密调用追踪
+- **沙箱执行**：补环境、沙箱运行、算法验证
+- **关联分析**：请求参数与加密函数的关联、Cookie/Header 加密定位
+
+## 工作流程
+
+### 标准逆向路径（请求驱动，必须遵守）
+
+**核心原则：从请求出发，沿调用链向上追溯，精准定位加密入口。**
+
+1. **找请求** — get_request_list 找到目标 API 请求（主 agent 通常会在任务描述中提供 site 和 requestId）
+2. **看调用栈** — get_request_initiator 获取请求的 initiator（调用栈）
+   - 有 callFrames → 直接定位到发起请求的函数（脚本URL + 行号）→ 跳到第 3 步
+   - 没有 initiator → 走退化路径（见下方）
+3. **定位函数** — 根据调用栈中的脚本 URL 和行号：
+   - get_script_source 获取对应脚本（只取相关片段，用 offset/limit 控制，不要全量拉取）
+   - get_function_code 提取目标函数及其依赖
+4. **分析加密** — 在定位到的函数范围内分析加密逻辑
+   - 代码混淆严重 → preprocess_code + deobfuscate
+   - 引用运行时变量（window.x、document.x 等）→ **必须用断点采集，禁止猜测**：
+     a. set_breakpoint 在目标函数入口设断点
+     b. 触发目标代码执行（根据场景选择触发方式，见「断点触发」）
+     c. evaluate_at_breakpoint 采集所有运行时变量值
+     d. resume_execution 继续执行
+   - collect_property 返回 undefined 时，说明变量仅在函数执行时存在，必须走断点路径
+   - **禁止用 search_in_scripts 搜索变量定义来猜测值，禁止用 run_node_code 穷举尝试**
+5. **验证** — sandbox_execute 或 run_node_code 验证算法正确性
+
+### 退化路径（initiator 不可用时）
+**触发条件：get_request_initiator 返回 error，或返回的 callFrames 为空数组。**
+1. analyze_request_params 快速识别可疑加密参数（自动检测 hex/base64/hash 模式，不依赖 Hook）
+2. search_in_scripts 搜索参数名或参数赋值位置
+3. 如果搜不到（参数名被混淆）→ set_xhr_breakpoint + get_call_stack 动态获取调用栈
+4. 定位到函数后回到标准路径第 3 步
+
+### 何时使用断点（优先于 Hook）
+- 需要获取函数入参/返回值 → set_breakpoint + evaluate_at_breakpoint
+- 需要追踪调用链 → set_xhr_breakpoint + get_call_stack
+- 断点是 CDP 原生能力，不修改页面 JS，不触发反调试检测
+
+### 何时使用 Hook
+- 需要持续监控（如观察多次请求的加密参数变化）→ Hook
+- 断点无法使用时（如异步回调链复杂）→ Hook
+- 注意：inject_hook 可能触发反调试检测，优先用内置 Hook（enable_hook）
+- 需要生成 Hook 代码时，使用 generate_hook(type) 生成，再通过 inject_hook 注入
+
+### 补环境路径（算法复杂难还原时）
+1. generate_env_dump_code 生成环境自吐代码
+2. collect_env / collect_property 采集真实环境
+3. generate_patch / load_env_module 生成补丁
+4. sandbox_inject + sandbox_execute 运行
+
+### 禁止行为
+- 禁止在有目标请求的情况下，跳过 initiator 直接拉全量源码
+- 禁止把超过 5000 字符的混淆代码塞入分析上下文
+- 禁止在没有明确目标函数的情况下使用 inject_hook
+
+## 浏览器状态
+- 浏览器生命周期由主 agent 管理，你没有 launch_browser / navigate_to 工具
+- 如果任务描述中包含"浏览器已就绪"，你可以直接使用断点、Hook、采集工具、页面交互工具
+- 如果浏览器未启动，返回结果告知主 agent 需要先启动浏览器
+- 你有 reload_page、click_element、scroll_page 用于触发断点，get_cookies 用于采集 Cookie，get_page_source 用于获取页面源码（定位内联脚本等）
+
+### 断点触发（必须掌握）
+设置断点后，断点不会立即命中 — 需要目标代码被执行。根据目标代码的执行时机选择触发方式：
+- 代码在页面加载时执行（如初始化、首次请求）→ **reload_page**
+- 代码在用户交互时执行（如翻页、点击按钮、提交表单）→ **click_element**
+- 代码在滚动时执行（如懒加载、无限滚动）→ **scroll_page**
+- 不确定触发时机 → 先看调用栈上下文判断，或用 **reload_page** 尝试
+
+断点命中后，用 **evaluate_at_breakpoint** 采集运行时变量，用 **resume_execution** 继续执行
+
+## 工作记忆
+多步分析时，用 save_memo 记录关键发现，防止上下文丢失：
+- 定位到加密函数后 → save_memo("crypto-func", "函数名 + 位置 + 算法类型")
+- 找到 key/iv 来源后 → save_memo("key-source", "来源 + 值")
+- 验证成功后 → save_memo("verified-code", "可运行的完整代码")
+分析开始时用 list_memo 检查是否有之前的记录可以复用。
+
+## 输出要求
+- 返回加密算法的完整分析（入口函数、参数来源、算法类型）
+- 如已验证成功，返回可独立运行的 JS 代码片段
+- 如需转 Python，明确告知主 agent 委托 js2python
+
+### 保存前置条件（必须遵守）
+- **只有通过 run_node_code 或 sandbox_execute 验证算法正确后，才能调用 artifact_save 保存代码**
+- 未验证成功时，返回文本说明当前进度和卡点，不保存文件
+- 禁止保存"框架代码"或"需要动态采集"的半成品代码
+
+## 能力边界
+- 你不能生成 Python 代码，需要转换时返回结果让主 agent 委托 js2python
+- 你不能编排完整爬虫流程，那是 crawler 的工作
+- 你不能启动/关闭浏览器或导航到新 URL，需要时返回让主 agent 处理`,
+  tools: [
+    // 数据查询（不含 clear_site_data / clear_all_data）
+    getSiteList, searchInResponses, getRequestDetail, getRequestList,
+    getRequestInitiator, getScriptList, getScriptSource, searchInScripts,
+    // 静态分析
+    ...preprocessTools,
+    ...webcrackTools,
+    ...analyzerTools,
+    ...deobfuscatorTools,
+    ...correlateTools,
+    ...traceTools,
+    ...extractorTools,
+    // 动态分析
+    ...debugTools,
+    ...captureTools,
+    ...hookManagerTools,
+    ...generateHookTools,
+    // 沙箱 + 补环境
+    ...sandboxTools,
+    ...envTools,
+    ...envDumpTools,
+    ...extractTools,
+    ...patchTools,
+    // 验证 + 执行
+    ...verifyAlgorithmTools,
+    ...nodejsTools,
+    // 页面交互（断点触发 + Cookie 采集 + 页面源码）
+    reloadPage, clickElement, scrollPage, getCookies, getPageSource,
+    // 输出
+    ...fileTools,
+    ...storeTools,
+    // 工作记忆
+    ...scratchpadTools,
+  ],
+  skills: ['static', 'dynamic', 'sandbox', 'env'],
+  evolveSkill: ['static-analysis', 'dynamic-analysis', 'sandbox', 'env'],
+});

package/src/agent/tools/analysis.js

@@ -89,7 +89,26 @@ export const sendPanelMessage = tool(
 
     const escaped = JSON.stringify(message);
     const r = role || 'assistant';
-    await evaluateViaCDP(client, `window.__deepspider__?.addMessage?.('${r}', ${escaped})`);
+
+    // 检查 __deepspider__ 和 addMessage 是否存在
+    const checkResult = await evaluateViaCDP(client, `
+      (function() {
+        if (!window.__deepspider__) return { error: '__deepspider__ not found' };
+        if (!window.__deepspider__.addMessage) return { error: 'addMessage not found' };
+        return { ok: true };
+      })()
+    `);
+
+    if (checkResult?.error) {
+      return JSON.stringify({ error: `面板未就绪: ${checkResult.error}` });
+    }
+
+    // 调用 addMessage
+    const result = await evaluateViaCDP(client, `window.__deepspider__.addMessage(${JSON.stringify(r)}, ${escaped})`);
+
+    if (result === null || result === undefined) {
+      return JSON.stringify({ error: 'addMessage 调用失败或返回空值' });
+    }
 
     return JSON.stringify({ success: true });
   },
@@ -127,9 +146,73 @@ export const startSelector = tool(
   }
 );
 
+/**
+ * 向浏览器面板发送可点击选项
+ */
+export const sendPanelChoices = tool(
+  async ({ question, options, allowCustom }) => {
+    const client = getBrowserClient();
+    if (!client?.page) {
+      return JSON.stringify({ error: '浏览器未启动' });
+    }
+
+    const data = { question, options, allowCustom: allowCustom ?? false };
+    const escapedType = JSON.stringify('choices');
+    const escapedData = JSON.stringify(data);
+    await evaluateViaCDP(client,
+      `window.__deepspider__?.addStructuredMessage?.(${escapedType}, ${escapedData})`
+    );
+    return JSON.stringify({ success: true, message: '已发送选项到面板，等待用户选择' });
+  },
+  {
+    name: 'send_panel_choices',
+    description: '向浏览器面板发送可点击的选项让用户选择。用户点击后结果会通过对话返回。',
+    schema: z.object({
+      question: z.string().describe('问题描述'),
+      options: z.array(z.object({
+        id: z.string().describe('选项唯一标识'),
+        label: z.string().describe('选项显示文字'),
+        description: z.string().optional().describe('选项补充说明'),
+      })).describe('可选项列表'),
+      allowCustom: z.boolean().optional().default(false).describe('是否允许用户自定义输入'),
+    }),
+  }
+);
+
+/**
+ * 向浏览器面板发送确认对话框
+ */
+export const sendPanelConfirm = tool(
+  async ({ question, confirmText, cancelText }) => {
+    const client = getBrowserClient();
+    if (!client?.page) {
+      return JSON.stringify({ error: '浏览器未启动' });
+    }
+
+    const data = { question, confirmText: confirmText ?? '确认', cancelText: cancelText ?? '取消' };
+    const escapedType = JSON.stringify('confirm');
+    const escapedData = JSON.stringify(data);
+    await evaluateViaCDP(client,
+      `window.__deepspider__?.addStructuredMessage?.(${escapedType}, ${escapedData})`
+    );
+    return JSON.stringify({ success: true, message: '已发送确认请求到面板' });
+  },
+  {
+    name: 'send_panel_confirm',
+    description: '向浏览器面板发送确认/取消对话框。用于执行爬虫、删除数据等需要用户确认的操作。',
+    schema: z.object({
+      question: z.string().describe('确认问题'),
+      confirmText: z.string().optional().default('确认'),
+      cancelText: z.string().optional().default('取消'),
+    }),
+  }
+);
+
 export const analysisTools = [
   getPendingAnalysis,
   getPendingChat,
   sendPanelMessage,
   startSelector,
+  sendPanelChoices,
+  sendPanelConfirm,
 ];

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

@@ -9,11 +9,14 @@ import { getBrowser } from '../../browser/index.js';
 export const proxyTest = tool(
   async ({ proxy_url }) => {
     try {
-      // 测试代理可用性
+      // 测试代理可用性（用 AbortController 实现超时，Node.js fetch 不支持 timeout 选项）
+      const controller = new globalThis.AbortController();
+      const timer = setTimeout(() => controller.abort(), 10000);
       const response = await fetch('https://httpbin.org/ip', {
         agent: proxy_url ? new (await import('https-proxy-agent')).HttpsProxyAgent(proxy_url) : undefined,
-        timeout: 10000,
+        signal: controller.signal,
       });
+      clearTimeout(timer);
       const data = await response.json();
       return JSON.stringify({ success: true, ip: data.origin, proxy: proxy_url });
     } catch (e) {