deepspider 0.1.0

package/.trellis/spec/backend/deepagents-guide.md

@@ -0,0 +1,337 @@
+# DeepAgents 框架使用指南
+
+> DeepSpider 项目的 DeepAgents 框架规范
+
+---
+
+## Overview
+
+DeepAgents 是基于 LangGraph 的 Agent 框架，DeepSpider 使用它构建多代理系统。
+
+---
+
+## Agent 创建
+
+### 基础配置
+
+```javascript
+import { createDeepAgent, FilesystemBackend } from 'deepagents';
+import { ChatOpenAI } from '@langchain/openai';
+
+const agent = createDeepAgent({
+  name: 'deepspider',
+  model: new ChatOpenAI({ model: 'gpt-4o' }),
+  tools: coreTools,
+  subagents: allSubagents,
+  systemPrompt,
+  backend: new FilesystemBackend({ rootDir: './.deepspider-agent' }),
+});
+```
+
+### 必需参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | Agent 名称 |
+| `model` | BaseChatModel | LLM 模型实例 |
+| `tools` | Tool[] | 工具数组 |
+| `systemPrompt` | string | 系统提示词 |
+
+---
+
+## 子代理定义
+
+### 字典式子代理
+
+```javascript
+export const staticSubagent = {
+  name: 'static-agent',
+  description: '静态代码分析专家。当需要分析混淆代码时使用。',
+  systemPrompt: `你是静态分析专家...`,
+  tools: [...analyzerTools, ...deobfuscatorTools],
+  middleware: [
+    createSkillsMiddleware({
+      backend: skillsBackend,
+      sources: [SKILLS.static],
+    }),
+  ],
+};
+```
+
+### 必需字段
+
+| 字段 | 说明 |
+|------|------|
+| `name` | 子代理名称，用于调用 |
+| `description` | 描述何时使用该子代理 |
+| `systemPrompt` | 子代理的系统提示 |
+| `tools` | 子代理可用的工具 |
+
+### 可选字段
+
+| 字段 | 说明 |
+|------|------|
+| `model` | 覆盖默认模型 |
+| `middleware` | 子代理中间件（如 Skills） |
+
+---
+
+## Skills 系统
+
+### 配置独立 Skills
+
+每个子代理只加载属于自己的 skills：
+
+```javascript
+// src/agent/skills/config.js
+export const SKILLS = {
+  // 逆向分析
+  static: `${BASE_DIR}static-analysis`,
+  dynamic: `${BASE_DIR}dynamic-analysis`,
+  sandbox: `${BASE_DIR}sandbox`,
+  env: `${BASE_DIR}env`,
+  js2python: `${BASE_DIR}js2python`,
+  // 爬虫能力
+  captcha: `${BASE_DIR}captcha`,
+  antiDetect: `${BASE_DIR}anti-detect`,
+  crawler: `${BASE_DIR}crawler`,
+};
+```
+
+### 子代理绑定 Skills
+
+```javascript
+import { createSkillsMiddleware } from 'deepagents';
+import { SKILLS, skillsBackend } from '../skills/config.js';
+
+export const staticSubagent = {
+  // ...其他配置
+  middleware: [
+    createSkillsMiddleware({
+      backend: skillsBackend,
+      sources: [SKILLS.static],  // 只加载静态分析 skill
+    }),
+  ],
+};
+```
+
+### SKILL.md 格式
+
+```markdown
+---
+name: skill-name
+description: |
+  技能描述。触发场景。关键词。
+---
+
+# 技能内容
+
+只写领域知识和经验，不写工具调用。
+```
+
+### 自我进化 Skills
+
+Skills 分为静态和动态两部分：
+
+| 类型 | 文件 | 管理方式 |
+|------|------|----------|
+| 静态 | SKILL.md | Git 版本控制 |
+| 动态 | evolved.md | 运行时积累 |
+
+#### evolved.md 格式
+
+```markdown
+---
+total: 5
+last_merged: 2024-01-15
+---
+
+## 核心经验
+
+<!-- 经过验证的高价值经验 -->
+
+### [2024-01-10] 经验标题
+**场景**: 具体场景描述
+**经验**: 一句话总结
+
+## 近期发现
+
+<!-- FIFO 滚动，最多 10 条 -->
+```
+
+#### 触发经验记录
+
+在 subagent 的 systemPrompt 末尾添加引导：
+
+```javascript
+systemPrompt: `...原有内容...
+
+## 经验记录
+完成分析后，如发现有价值的经验，使用 evolve_skill 记录：
+- skill: "static-analysis"
+- 新技巧、踩坑记录、通用方案都值得记录`,
+```
+
+> **注意**: evolve_skill 工具不会自动触发，需要通过 Prompt 引导 Agent 主动调用。
+
+#### 合并策略
+
+- 近期发现保留最多 10 条（FIFO）
+- 动态经验达到 20 条时提示合并
+- 使用 `/evolve:merge <skill>` 命令触发合并
+
+---
+
+## 后端存储
+
+### FilesystemBackend（推荐）
+
+```javascript
+import { FilesystemBackend } from 'deepagents';
+
+const backend = new FilesystemBackend({
+  rootDir: './.deepspider-agent',
+});
+```
+
+### StateBackend（临时）
+
+```javascript
+import { StateBackend } from 'deepagents';
+
+const backend = new StateBackend();  // 数据不持久化
+```
+
+---
+
+## 人机交互
+
+### 配置敏感工具审批
+
+```javascript
+const agent = createDeepAgent({
+  interruptOn: {
+    sandbox_execute: { allowedDecisions: ['approve', 'reject', 'edit'] },
+    sandbox_inject: { allowedDecisions: ['approve', 'reject'] },
+  },
+  checkpointer: new MemorySaver(),  // 必需
+});
+```
+
+---
+
+## 最佳实践
+
+### 子代理描述要具体
+
+```javascript
+// ✅ 好
+description: '静态代码分析专家。当需要分析混淆代码结构时使用，适用于：Webpack 解包、反混淆、定位加密函数。'
+
+// ❌ 差
+description: '分析代码'
+```
+
+### 工具集要专注
+
+```javascript
+// ✅ 好：静态分析子代理只有分析工具
+tools: [...analyzerTools, ...deobfuscatorTools, ...traceTools]
+
+// ❌ 差：混入不相关工具
+tools: [...analyzerTools, ...browserTools, ...sandboxTools]
+```
+
+### Skills 只写经验
+
+```markdown
+// ✅ 好：领域知识
+## 常见检测点
+- navigator.webdriver → undefined
+- window.chrome → 完整对象
+
+// ❌ 差：工具调用
+## 工具使用
+- sandbox_inject(code) - 注入代码
+```
+
+---
+
+## 常见错误
+
+### 错误 1: 所有 agent 加载全部 skills
+
+**问题**: 使用单一 `SKILLS_DIR` 让所有 agent 加载全部 skills。
+
+**后果**: 上下文膨胀，skills 内容与 agent 职责不匹配。
+
+**正确做法**: 每个 agent 只加载自己的 skills。
+
+### 错误 2: 主 agent 加载 skills
+
+**问题**: 主 agent 配置了 `skills: [SKILLS_DIR]`。
+
+**后果**: 主 agent 负责分发任务，不需要领域知识。
+
+**正确做法**: 主 agent 不配置 skills，只有子代理配置。
+
+### 错误 3: SKILL.md 写工具文档
+
+**问题**: 在 SKILL.md 中列出工具名称和参数说明。
+
+**后果**: 与 systemPrompt 重复，浪费 token。
+
+**正确做法**: Skills 只写领域经验、技巧、常见问题。
+
+### 错误 4: Skills 记录开发经验而非领域知识
+
+**问题**: 在 evolved.md 中记录项目开发经验（如 Playwright 用法）。
+
+**后果**: 污染 Agent 的领域知识库，与 JS 逆向分析无关。
+
+**正确做法**: Skills 只记录 Agent 执行任务时需要的领域知识（如加密算法差异）。
+
+### 错误 5: systemPrompt 中列出工具清单
+
+**问题**: 在 systemPrompt 中手动列出工具名称和用法说明。
+
+```javascript
+// ❌ 差
+systemPrompt: `你是分析专家。
+
+## 可用工具
+- analyze_ast: 分析 AST
+- deobfuscate: 反混淆代码
+...`
+```
+
+**后果**: LangChain 会自动注入工具信息，手动列出导致重复和不一致。
+
+**正确做法**: systemPrompt 只写职责和工作流程，工具信息由框架自动注入。
+
+### 错误 6: 子代理职责重叠
+
+**问题**: 创建多个子代理处理相似任务（如 static-agent 和 algo-agent 都做加密分析）。
+
+**后果**: 主 agent 难以选择正确的子代理，导致任务分发混乱。
+
+**正确做法**: 合并职责相近的子代理，确保每个子代理有明确独立的职责边界。
+
+### 错误 7: 引用不存在的工具模块
+
+**问题**: 在子代理中导入不存在的工具模块（如 `browserTools` 实际文件名是 `trigger.js`）。
+
+```javascript
+// ❌ 差：模块不存在
+import { browserTools } from '../tools/browser.js';
+
+// ✅ 好：确认模块存在后再导入
+import { browserTools } from '../tools/browser.js';  // 文件确实存在
+```
+
+**后果**: 运行时报错 `Cannot find module`。
+
+**正确做法**:
+1. 添加新子代理前，先确认所需工具模块存在
+2. 工具模块命名应语义化（如 `browser.js` 比 `trigger.js` 更清晰）
+3. 修改模块名时同步更新所有引用

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

@@ -0,0 +1,126 @@
+# Directory Structure
+
+> DeepSpider 项目的代码组织结构
+
+---
+
+## Overview
+
+DeepSpider 是一个 Node.js 后端项目，基于 DeepAgents + Patchright 构建的 JS 逆向分析引擎。
+项目采用模块化架构，按功能职责划分目录。
+
+---
+
+## Directory Layout
+
+```
+src/
+├── agent/                 # DeepAgent 系统（核心）
+│   ├── index.js           # Agent 主入口，createDeepSpiderAgent()
+│   ├── run.js             # Agent 运行入口
+│   ├── tools/             # LangChain 工具集（90+）
+│   │   ├── index.js       # 工具导出汇总
+│   │   ├── analyzer.js    # AST 分析工具
+│   │   ├── deobfuscator.js # 反混淆工具
+│   │   └── ...
+│   ├── subagents/         # 子代理定义
+│   │   ├── index.js       # 子代理导出
+│   │   ├── static.js      # 静态分析子代理
+│   │   ├── dynamic.js     # 动态分析子代理
+│   │   └── sandbox.js     # 沙箱执行子代理
+│   ├── skills/            # Agent Skills（领域知识）
+│   │   ├── config.js      # Skills 配置
+│   │   ├── static-analysis/  # 静态分析经验
+│   │   ├── dynamic-analysis/ # 动态分析经验
+│   │   ├── env/           # 补环境经验
+│   │   ├── sandbox/       # 沙箱执行经验
+│   │   └── js2python/     # JS转Python经验
+│   ├── middleware/        # Agent 中间件
+│   └── prompts/           # 系统提示词
+├── browser/               # 浏览器运行时
+│   ├── client.js          # Patchright 客户端
+│   ├── cdp.js             # CDP 会话管理
+│   ├── defaultHooks.js    # 默认注入的 Hook
+│   ├── interceptors/      # CDP 拦截器
+│   ├── collectors/        # 数据采集器
+│   ├── hooks/             # Hook 脚本
+│   └── ui/                # 浏览器内 UI（注入脚本）
+├── analyzer/              # 静态分析器
+│   ├── ASTAnalyzer.js     # AST 分析
+│   ├── Deobfuscator.js    # 反混淆器
+│   └── EncryptionAnalyzer.js # 加密分析
+├── store/                 # 数据存储
+│   └── DataStore.js       # 文件系统存储
+├── core/                  # 核心模块
+│   ├── Sandbox.js         # 沙箱执行
+│   └── PatchGenerator.js  # 补丁生成
+├── env/                   # 环境补丁模块
+│   ├── modules/           # 浏览器环境模拟
+│   │   ├── bom/           # BOM 对象模拟
+│   │   ├── dom/           # DOM 对象模拟
+│   │   └── webapi/        # Web API 模拟
+│   └── *Hook.js           # 各类 Hook 实现
+├── config/                # 配置
+│   ├── index.js           # 配置入口
+│   ├── paths.js           # 路径配置
+│   └── patterns/          # 模式配置
+├── mcp/                   # MCP 服务
+│   └── server.js          # MCP 服务器
+└── index.js               # 主入口
+```
+
+---
+
+## Module Organization
+
+### 新功能开发指南
+
+1. **新增工具**: 在 `src/agent/tools/` 下创建文件，导出工具数组，在 `index.js` 中汇总
+2. **新增子代理**: 在 `src/agent/subagents/` 下创建文件，定义 subagent 对象
+3. **新增 Skill**: 在 `src/agent/skills/` 下创建目录，包含 `SKILL.md` 文件
+4. **新增分析器**: 在 `src/analyzer/` 下创建类文件
+5. **新增 Hook**: 在 `src/browser/hooks/` 或 `src/env/` 下创建
+6. **新增环境模拟**: 在 `src/env/modules/` 对应子目录下创建
+
+### 模块依赖关系
+
+```
+agent/ ──────> tools/, subagents/, skills/, prompts/
+   │
+   └──────────> browser/, analyzer/, store/, core/
+                   │
+browser/ ─────> interceptors/, collectors/, hooks/, ui/
+```
+
+---
+
+## Naming Conventions
+
+### 文件命名
+
+| 类型 | 命名规则 | 示例 |
+|------|----------|------|
+| 工具文件 | 小写，描述功能 | `analyzer.js`, `deobfuscator.js` |
+| 类文件 | PascalCase | `ASTAnalyzer.js`, `DataStore.js` |
+| Hook 文件 | *Hook.js | `CryptoHook.js`, `NetworkHook.js` |
+| 索引文件 | index.js | `index.js` |
+
+### 导出命名
+
+| 类型 | 命名规则 | 示例 |
+|------|----------|------|
+| 工具数组 | *Tools | `analyzerTools`, `deobfuscatorTools` |
+| 单个工具 | camelCase 动词 | `analyzeAst`, `deobfuscate` |
+| 子代理 | *Subagent | `staticSubagent`, `dynamicSubagent` |
+| 类 | PascalCase | `ASTAnalyzer`, `DataStore` |
+
+---
+
+## Examples
+
+### 良好组织的模块示例
+
+- **工具模块**: `src/agent/tools/analyzer.js` - 清晰的工具定义和导出
+- **子代理模块**: `src/agent/subagents/static.js` - 完整的子代理配置
+- **分析器模块**: `src/analyzer/ASTAnalyzer.js` - 类的组织和方法划分
+- **存储模块**: `src/store/DataStore.js` - 单例模式和完整的 CRUD 操作

package/.trellis/spec/backend/examples/skills/deepagents-guide/README.md

@@ -0,0 +1,11 @@
+# DeepAgents 示例
+
+DeepSpider 项目中 DeepAgents 的使用示例。
+
+## 文件说明
+
+| 文件 | 说明 |
+|------|------|
+| `agent.js.template` | 主 Agent 创建示例 |
+| `subagent.js.template` | 子代理定义示例 |
+| `skills-config.js.template` | Skills 配置示例 |

package/.trellis/spec/backend/examples/skills/deepagents-guide/agent.js.template

@@ -0,0 +1,20 @@
+/**
+ * 主 Agent 创建示例
+ */
+import { createDeepAgent, FilesystemBackend } from 'deepagents';
+import { ChatOpenAI } from '@langchain/openai';
+import { MemorySaver } from '@langchain/langgraph';
+
+export function createAgent(options = {}) {
+  const { model, tools, subagents, systemPrompt } = options;
+
+  return createDeepAgent({
+    name: 'my-agent',
+    model: new ChatOpenAI({ model }),
+    tools,
+    subagents,
+    systemPrompt,
+    backend: new FilesystemBackend({ rootDir: './agent-data' }),
+    checkpointer: new MemorySaver(),
+  });
+}

package/.trellis/spec/backend/examples/skills/deepagents-guide/skills-config.js.template

@@ -0,0 +1,13 @@
+/**
+ * Skills 配置示例
+ */
+import { FilesystemBackend } from 'deepagents';
+
+export const skillsBackend = new FilesystemBackend({ rootDir: '/' });
+
+const BASE_DIR = new URL('.', import.meta.url).pathname;
+
+export const SKILLS = {
+  static: `${BASE_DIR}static-analysis`,
+  dynamic: `${BASE_DIR}dynamic-analysis`,
+};

package/.trellis/spec/backend/examples/skills/deepagents-guide/subagent.js.template

@@ -0,0 +1,19 @@
+/**
+ * 子代理定义示例
+ */
+import { createSkillsMiddleware } from 'deepagents';
+import { SKILLS, skillsBackend } from '../skills/config.js';
+import { myTools } from '../tools/my-tools.js';
+
+export const mySubagent = {
+  name: 'my-agent',
+  description: '专家描述。触发场景。',
+  systemPrompt: `你是专家...`,
+  tools: [...myTools],
+  middleware: [
+    createSkillsMiddleware({
+      backend: skillsBackend,
+      sources: [SKILLS.mySkill],
+    }),
+  ],
+};

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

@@ -0,0 +1,178 @@
+# Hook Guidelines
+
+> 浏览器 Hook 注入规范
+
+---
+
+## Overview
+
+DeepSpider 使用 Hook 拦截浏览器 API 来采集加密调用、网络请求等数据。
+Hook 脚本通过 CDP 注入到页面中执行。
+
+---
+
+## Hook Types
+
+| Hook 类型 | 位置 | 用途 |
+|-----------|------|------|
+| CryptoHook | `src/env/CryptoHook.js` | 拦截加密 API |
+| NetworkHook | `src/env/NetworkHook.js` | 拦截网络请求 |
+| Browser Hooks | `src/browser/hooks/` | 浏览器注入脚本 |
+
+---
+
+## Browser Hook Pattern
+
+浏览器注入脚本结构：
+
+```javascript
+// src/browser/hooks/crypto.js
+export function getCryptoHookScript() {
+  return `
+(function() {
+  const original = window.crypto.subtle.digest;
+  window.crypto.subtle.digest = async function(...args) {
+    console.log('[Hook] crypto.digest:', args);
+    return original.apply(this, args);
+  };
+})();
+`;
+}
+```
+
+**示例**: `src/browser/hooks/crypto.js`
+
+---
+
+## Naming Conventions
+
+| 类型 | 命名规则 | 示例 |
+|------|----------|------|
+| Hook 类 | *Hook | `CryptoHook`, `NetworkHook` |
+| 脚本函数 | get*Script | `getCryptoHookScript()` |
+| 全局对象 | __deepspider__* | `__deepspider__`, `__deepspider_send__` |
+
+---
+
+## Common Mistakes
+
+### 1. 未保存原始函数
+
+```javascript
+// ❌ 错误：直接覆盖
+window.fetch = function() { ... };
+
+// ✅ 正确：保存原始函数
+const originalFetch = window.fetch;
+window.fetch = function(...args) {
+  // 记录
+  return originalFetch.apply(this, args);
+};
+```
+
+### 2. Hook 脚本未使用 IIFE
+
+```javascript
+// ❌ 错误：污染全局
+const hook = ...;
+
+// ✅ 正确：使用 IIFE 隔离
+(function() {
+  const hook = ...;
+})();
+```
+
+### 3. 闭包变量陷阱
+
+```javascript
+// ❌ 错误：循环中的闭包
+for (const trap in handler) {
+  wrappedHandler[trap] = function() {
+    console.log(trap); // trap 始终是最后一个值
+  };
+}
+
+// ✅ 正确：使用函数工厂
+function wrapTrap(trapName, fn) {
+  return function() {
+    console.log(trapName);
+    return fn.apply(this, arguments);
+  };
+}
+for (const trap in handler) {
+  wrappedHandler[trap] = wrapTrap(trap, handler[trap]);
+}
+```
+
+---
+
+## Anti-Detection Patterns
+
+Hook 容易被网站检测，必须做好伪装。
+
+### 1. toString 伪装（必须）
+
+```javascript
+const originalToString = Function.prototype.toString;
+const hookedFns = new WeakMap();
+
+// 包装函数
+function native(hookFunc, originalFunc) {
+  hookedFns.set(hookFunc, originalToString.call(originalFunc));
+  return hookFunc;
+}
+
+// 重写 toString
+Function.prototype.toString = function() {
+  return hookedFns.has(this)
+    ? hookedFns.get(this)
+    : originalToString.call(this);
+};
+```
+
+### 2. getOwnPropertyDescriptor 保护
+
+```javascript
+// 网站可能检测属性描述符
+const origGetDesc = Object.getOwnPropertyDescriptor;
+Object.getOwnPropertyDescriptor = function(obj, prop) {
+  const desc = origGetDesc.call(Object, obj, prop);
+  if (desc && hookedFns.has(desc.value)) {
+    return { value: desc.value, writable: true, enumerable: false, configurable: true };
+  }
+  return desc;
+};
+```
+
+### 3. 隐藏内部属性
+
+```javascript
+// 隐藏 __deepspider__ 等内部属性
+const hiddenProps = ['__deepspider__'];
+const origKeys = Object.keys;
+Object.keys = function(obj) {
+  const keys = origKeys.call(Object, obj);
+  return obj === window ? keys.filter(k => !hiddenProps.includes(k)) : keys;
+};
+```
+
+---
+
+## Dynamic Hook Management
+
+Hook 应支持运行时动态启用/禁用。
+
+### 架构设计
+
+| 类型 | 控制方式 | 用途 |
+|------|----------|------|
+| 内置 Hook | config[name] | xhr, fetch, crypto 等 |
+| 自定义 Hook | hookRegistry | 针对特定网站 |
+
+### 性能优化
+
+| 配置项 | 默认 | 说明 |
+|--------|------|------|
+| captureStack | true | 关闭可提升性能 |
+| silent | false | 关闭控制台输出 |
+| logLimit | 50 | 每个 API 日志上限 |