deepspider 0.2.11 → 0.2.12

package/.trellis/spec/backend/directory-structure.md

@@ -17,7 +17,16 @@ DeepSpider 是一个 Node.js 后端项目，基于 DeepAgents + Patchright 构
 src/
 ├── agent/                 # DeepAgent 系统（核心）
 │   ├── index.js           # Agent 主入口，createDeepSpiderAgent()
-│   ├── run.js             # Agent 运行入口
+│   ├── run.js             # Agent 运行入口（精简协调器）
+│   ├── core/              # 核心运行时模块
+│   │   ├── index.js       # 模块导出
+│   │   ├── StreamHandler.js  # 流式输出处理
+│   │   ├── RetryManager.js   # 重试策略
+│   │   └── PanelBridge.js    # 面板通信桥接
+│   ├── errors/            # 错误处理模块
+│   │   ├── index.js       # 模块导出
+│   │   ├── ErrorClassifier.js # 错误分类器
+│   │   └── SpiderError.js    # 结构化错误类型
 │   ├── tools/             # LangChain 工具集（90+）
 │   │   ├── index.js       # 工具导出汇总
 │   │   ├── analyzer.js    # AST 分析工具
@@ -25,6 +34,7 @@ src/
 │   │   └── ...
 │   ├── subagents/         # 子代理定义
 │   │   ├── index.js       # 子代理导出
+│   │   ├── factory.js     # 子代理工厂函数
 │   │   ├── static.js      # 静态分析子代理
 │   │   ├── dynamic.js     # 动态分析子代理
 │   │   └── sandbox.js     # 沙箱执行子代理
@@ -76,16 +86,20 @@ src/
 ### 新功能开发指南
 
 1. **新增工具**: 在 `src/agent/tools/` 下创建文件，导出工具数组，在 `index.js` 中汇总
-2. **新增子代理**: 在 `src/agent/subagents/` 下创建文件，定义 subagent 对象
+2. **新增子代理**: 在 `src/agent/subagents/` 下创建文件，使用 `createSubagent()` 工厂函数
 3. **新增 Skill**: 在 `src/agent/skills/` 下创建目录，包含 `SKILL.md` 文件
 4. **新增分析器**: 在 `src/analyzer/` 下创建类文件
 5. **新增 Hook**: 在 `src/browser/hooks/` 或 `src/env/` 下创建
 6. **新增环境模拟**: 在 `src/env/modules/` 对应子目录下创建
+7. **新增核心模块**: 在 `src/agent/core/` 下创建，用于运行时逻辑
+8. **新增错误类型**: 在 `src/agent/errors/` 下扩展 `SpiderError` 类
 
 ### 模块依赖关系
 
 ```
 agent/ ──────> tools/, subagents/, skills/, prompts/
+   │
+   ├──────────> core/, errors/
    │
    └──────────> browser/, analyzer/, store/, core/
                    │
@@ -113,6 +127,8 @@ browser/ ─────> interceptors/, collectors/, hooks/, ui/
 | 单个工具 | camelCase 动词 | `analyzeAst`, `deobfuscate` |
 | 子代理 | *Subagent | `staticSubagent`, `dynamicSubagent` |
 | 类 | PascalCase | `ASTAnalyzer`, `DataStore` |
+| 错误类 | *Error | `ApiServiceError`, `BrowserError` |
+| 核心模块类 | PascalCase | `StreamHandler`, `PanelBridge` |
 
 ---
 
@@ -122,5 +138,8 @@ browser/ ─────> interceptors/, collectors/, hooks/, ui/
 
 - **工具模块**: `src/agent/tools/analyzer.js` - 清晰的工具定义和导出
 - **子代理模块**: `src/agent/subagents/static.js` - 完整的子代理配置
+- **子代理工厂**: `src/agent/subagents/factory.js` - 统一创建子代理
+- **核心模块**: `src/agent/core/StreamHandler.js` - 流式处理逻辑
+- **错误模块**: `src/agent/errors/SpiderError.js` - 结构化错误类型
 - **分析器模块**: `src/analyzer/ASTAnalyzer.js` - 类的组织和方法划分
 - **存储模块**: `src/store/DataStore.js` - 单例模式和完整的 CRUD 操作

package/.trellis/spec/backend/quality-guidelines.md

@@ -300,3 +300,78 @@ if (!currentStage) return;
 if (index < 0 || index >= currentStage.fields.length) return;
 currentStage.fields.splice(index, 1);
 ```
+
+---
+
+## Modularization Patterns
+
+### 1. 大文件拆分原则
+
+当文件超过 300 行时，考虑按职责拆分：
+
+```javascript
+// ❌ 禁止：单文件包含多种职责
+// run.js (600+ 行)
+// - 流式处理逻辑
+// - 重试策略
+// - 面板通信
+// - 错误分类
+
+// ✅ 按职责拆分到 core/ 目录
+// src/agent/core/
+// ├── StreamHandler.js   # 流式输出处理
+// ├── RetryManager.js    # 重试策略
+// ├── PanelBridge.js     # 面板通信
+// └── index.js           # 模块导出
+```
+
+**原因**: 单一职责原则，便于测试和维护。
+
+### 2. 使用子代理工厂函数
+
+```javascript
+// ❌ 禁止：每个子代理重复配置中间件
+export const staticSubagent = {
+  name: 'static-agent',
+  tools: [...staticTools, ...evolveTools],
+  middleware: [
+    createFilterToolsMiddleware(),
+    createSkillsMiddleware({ backend, sources: [SKILLS.static] }),
+  ],
+};
+
+// ✅ 使用工厂函数统一配置
+import { createSubagent, SKILLS } from './factory.js';
+
+export const staticSubagent = createSubagent({
+  name: 'static-agent',
+  description: '静态分析专家',
+  systemPrompt: '...',
+  tools: staticTools,
+  skills: [SKILLS.static],
+});
+```
+
+**原因**: 工厂函数自动注入公共中间件和 evolveTools，避免遗漏。
+
+### 3. 结构化错误类型
+
+```javascript
+// ❌ 禁止：字符串匹配判断错误类型
+if (/503|502|429/.test(error.message)) {
+  // 重试
+}
+
+// ✅ 使用结构化错误类型
+import { ApiServiceError, isApiServiceError } from './errors/index.js';
+
+// 抛出时
+throw new ApiServiceError('服务不可用', { statusCode: 503 });
+
+// 捕获时
+if (isApiServiceError(error.message)) {
+  // 重试
+}
+```
+
+**原因**: 结构化错误便于分类处理，支持携带额外上下文。

package/README.md

@@ -75,12 +75,33 @@ DEEPSPIDER_MODEL=model-name
 
 ### 使用
 
+#### 全局安装（npm/pnpm install -g）
+
 ```bash
-# Agent 模式（推荐）- 指定目标网站
-pnpm run agent https://example.com
+# 配置环境变量
+export DEEPSPIDER_API_KEY=sk-xxx
+export DEEPSPIDER_BASE_URL=https://api.openai.com/v1
+export DEEPSPIDER_MODEL=gpt-4o
+
+# 启动 Agent - 指定目标网站
+deepspider https://example.com
+
+# 启动 Agent - 纯交互模式
+deepspider
+```
 
-# Agent 模式 - 纯交互（不启动浏览器）
-pnpm run agent
+#### 克隆仓库
+
+```bash
+# 配置环境变量（二选一）
+cp .env.example .env  # 编辑 .env 文件
+# 或 export DEEPSPIDER_API_KEY=... 等
+
+# 安装 Python 依赖（可选，用于执行生成的 Python 代码）
+pnpm run setup:crypto
+
+# 启动 Agent
+pnpm run agent https://example.com
 
 # MCP 服务（供 Claude Code 等调用）
 pnpm run mcp

package/docs/GUIDE.md

@@ -34,8 +34,8 @@ DeepSpider 是一个智能爬虫 Agent，基于 DeepAgents + Patchright 构建
 deepspider/
 ├── src/
 │   ├── agent/               # DeepAgent 系统
-│   │   ├── tools/           # 39个工具
-│   │   ├── subagents/       # 3个子代理
+│   │   ├── tools/           # 工具集（90+）
+│   │   ├── subagents/       # 7个子代理
 │   │   └── prompts/         # 系统提示
 │   ├── browser/             # 浏览器运行时 (Patchright)
 │   │   ├── client.js        # 反检测浏览器客户端
@@ -53,48 +53,54 @@ deepspider/
 
 ## 安装配置
 
-### 依赖安装
+### 全局安装（推荐）
 
 ```bash
-cd /path/to/deepspider
-pnpm install
+# npm
+npm install -g deepspider
+
+# pnpm（需要先批准构建脚本）
+pnpm approve-builds -g deepspider isolated-vm
+pnpm install -g deepspider
 ```
 
-### 作为 Plugin 安装
+### 克隆仓库开发
 
 ```bash
-claude /install /path/to/deepspider
+git clone https://github.com/ma-pony/deepspider.git
+cd deepspider
+pnpm install
+cp .env.example .env  # 配置环境变量
+pnpm run setup:crypto  # 安装 Python 依赖（可选）
 ```
 
-### 本地开发测试 (不安装)
+---
 
-```bash
-claude --plugin-dir /path/to/deepspider
-```
+## 使用方式
 
-### 独立 CLI 使用
+### 全局安装后
 
 ```bash
-pnpm run cli run target.js      # 执行代码
-pnpm run cli analyze target.js  # 分析代码
-```
+# 配置环境变量
+export DEEPSPIDER_API_KEY=sk-xxx
+export DEEPSPIDER_BASE_URL=https://api.openai.com/v1
+export DEEPSPIDER_MODEL=gpt-4o
 
----
+# 启动 Agent
+deepspider https://example.com
+```
 
-## 使用方式
+### 克隆仓库后
 
-### 方式一: Commands (斜杠命令)
+```bash
+# 启动 Agent
+pnpm run agent https://example.com
 
+# MCP 服务
+pnpm run mcp
 ```
-/deepspider:run <file.js>      # 在沙箱中执行并自动补环境
-/deepspider:analyze <file.js>  # 分析代码结构和加密
-/deepspider:deob <file.js>     # 反混淆代码
-/deepspider:trace <param>      # 追踪参数生成逻辑
-```
-
-### 方式二: Agent 对话
 
-直接与 DeepSpider Agent 对话:
+### Agent 对话示例
 
 ```
 分析这段 JS 代码的加密逻辑
@@ -103,13 +109,6 @@ pnpm run cli analyze target.js  # 分析代码
 追踪 sign 参数的生成过程
 ```
 
-### 方式三: MCP 工具调用
-
-Claude 会自动调用 MCP 工具，工具命名格式:
-- `mcp__deepspider__sandbox_execute`
-- `mcp__deepspider__analyze_ast`
-- `mcp__deepspider__deobfuscate`
-
 ---
 
 ## 核心功能
@@ -302,9 +301,14 @@ export const myTool = tool(
 
 | 子代理 | 职责 |
 |--------|------|
-| static-agent | 预处理、解包、反混淆、加密定位 |
-| dynamic-agent | 浏览器控制、断点、Hook、数据采集 |
-| sandbox-agent | 环境补全、代码执行、补丁生成 |
+| crawler | 爬虫编排：整合各模块、生成完整脚本 |
+| static | 静态分析：解包、反混淆、加密定位 |
+| dynamic | 动态分析：浏览器控制、Hook、数据采集 |
+| sandbox | 沙箱执行：环境补全、代码执行 |
+| js2python | JS转Python：加密代码转换、验证 |
+| env-agent | 环境补全：生成浏览器环境模拟代码 |
+| captcha | 验证码处理：OCR、滑块、点选 |
+| anti-detect | 反检测：指纹管理、代理池 |
 
 ### 知识库
 

package/docs/PROMPT.md

@@ -1,7 +1,6 @@
 # DeepSpider Subagent 系统提示
 
 > 此文件为 Subagent 系统提示的参考文档。
-> 实际 Subagent 定义位于 `.claude/agents/deepspider.md`
 
 你是 DeepSpider，一个智能爬虫 Agent。
 

package/docs/USAGE.md

@@ -7,7 +7,11 @@
 ### 1. 启动 Agent
 
 ```bash
-pnpm run agent
+# 全局安装后
+deepspider https://example.com
+
+# 克隆仓库后
+pnpm run agent https://example.com
 ```
 
 ### 2. 基本流程

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepspider",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "智能爬虫工程平台 - 基于 DeepAgents + Patchright 的 AI 爬虫 Agent",
   "type": "module",
   "main": "src/index.js",

package/src/agent/core/PanelBridge.js

@@ -0,0 +1,133 @@
+/**
+ * DeepSpider - 面板通信桥接
+ * 处理与浏览器面板的消息通信
+ */
+
+export class PanelBridge {
+  constructor(browserGetter, debugFn = () => {}) {
+    this.getBrowser = browserGetter;
+    this.debug = debugFn;
+    this.textBuffer = '';
+    this.hasStartedAssistantMsg = false;
+  }
+
+  /**
+   * 重置状态
+   */
+  reset() {
+    this.textBuffer = '';
+    this.hasStartedAssistantMsg = false;
+  }
+
+  /**
+   * 通过 CDP 在页面主世界执行 JavaScript
+   */
+  async evaluateInPage(code) {
+    const browser = this.getBrowser();
+    const cdp = await browser?.getCDPSession?.();
+    if (!cdp) return null;
+
+    try {
+      const result = await cdp.send('Runtime.evaluate', {
+        expression: code,
+        returnByValue: true,
+      });
+      return result.result?.value;
+    } catch (e) {
+      this.debug('evaluateInPage 失败:', e.message);
+      return null;
+    }
+  }
+
+  /**
+   * 发送消息到前端面板
+   */
+  async sendToPanel(role, content) {
+    if (!content?.trim()) return;
+
+    const browser = this.getBrowser();
+    const page = browser?.getPage?.();
+    if (!page) return;
+
+    try {
+      const escaped = JSON.stringify(content.trim());
+      const code = `window.__deepspider__?.addMessage?.('${role}', ${escaped})`;
+      await this.evaluateInPage(code);
+    } catch (e) {
+      // ignore
+    }
+  }
+
+  /**
+   * 累积文本到缓冲区（用于 LLM 流式输出）
+   */
+  async appendToPanel(text) {
+    if (!text) return;
+    this.textBuffer += text;
+
+    // 每累积一定量或遇到换行时刷新
+    if (this.textBuffer.length > 200 || text.includes('\n')) {
+      await this.flushPanelText();
+    }
+  }
+
+  /**
+   * 刷新累积的文本到面板
+   */
+  async flushPanelText() {
+    if (!this.textBuffer.trim()) return;
+
+    const browser = this.getBrowser();
+    const page = browser?.getPage?.();
+    if (!page) {
+      this.textBuffer = '';
+      return;
+    }
+
+    try {
+      const content = this.textBuffer.trim();
+      const escaped = JSON.stringify(content);
+
+      if (!this.hasStartedAssistantMsg) {
+        const code = `(function() {
+          const fn = window.__deepspider__?.addMessage;
+          if (typeof fn === 'function') {
+            fn('assistant', ${escaped});
+            return { ok: true };
+          }
+          return { ok: false };
+        })()`;
+        await this.evaluateInPage(code);
+        this.hasStartedAssistantMsg = true;
+      } else {
+        const code = `(function() {
+          const fn = window.__deepspider__?.appendToLastMessage;
+          if (typeof fn === 'function') {
+            fn('assistant', ${escaped});
+            return { ok: true };
+          }
+          return { ok: false };
+        })()`;
+        await this.evaluateInPage(code);
+      }
+    } catch (e) {
+      // ignore
+    }
+
+    this.textBuffer = '';
+  }
+
+  /**
+   * 设置忙碌状态
+   */
+  async setBusy(busy) {
+    await this.evaluateInPage(`window.__deepspider__?.setBusy?.(${busy})`);
+  }
+
+  /**
+   * 完成消息，触发渲染
+   */
+  async finalizeMessage(role) {
+    await this.evaluateInPage(`window.__deepspider__?.finalizeMessage?.("${role}")`);
+  }
+}

package/src/agent/core/RetryManager.js

@@ -0,0 +1,51 @@
+/**
+ * DeepSpider - 重试管理器
+ * 处理 API 调用的重试策略
+ */
+
+// 默认重试配置
+const DEFAULT_CONFIG = {
+  maxRetries: 3,
+  baseDelayMs: 2000,
+  maxDelayMs: 30000,
+};
+
+export class RetryManager {
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * 计算重试延迟（指数退避 + 抖动）
+   */
+  getDelay(retryCount) {
+    const delay = Math.min(
+      this.config.baseDelayMs * Math.pow(2, retryCount),
+      this.config.maxDelayMs
+    );
+    // 添加 0-25% 的随机抖动
+    const jitter = delay * Math.random() * 0.25;
+    return Math.round(delay + jitter);
+  }
+
+  /**
+   * 是否可以重试
+   */
+  canRetry(retryCount) {
+    return retryCount < this.config.maxRetries;
+  }
+
+  /**
+   * 获取最大重试次数
+   */
+  get maxRetries() {
+    return this.config.maxRetries;
+  }
+}
+
+/**
+ * 延迟函数
+ */
+export function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}