deepspider 0.2.12 → 0.3.0

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

@@ -1,218 +0,0 @@
-# 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]);
-}
-```
-
-### 4. 内部操作触发 Hook
-
-**问题**: 系统内部的消息发送、状态存储等操作也会触发 Hook，产生噪音日志。
-
-```javascript
-// ❌ 错误：内部操作被记录
-sessionStorage.setItem('deepspider_messages', JSON.stringify(messages));
-// 触发 Storage Hook 和 JSON Hook，污染日志
-```
-
-**解决方案**: 使用统一标记过滤内部数据。
-
-1. **Storage Hook**: 使用 `deepspider_` 前缀过滤 key
-```javascript
-const INTERNAL_PREFIX = 'deepspider_';
-storage.setItem = function(key, value) {
-  if (!key.startsWith(INTERNAL_PREFIX)) {
-    deepspider.log('storage', { ... });
-  }
-  return origSet(key, value);
-};
-```
-
-2. **JSON Hook**: 使用 `__ds__` 标记过滤内部数据
-```javascript
-// 内部消息添加标记
-const msg = { __ds__: true, type: 'chat', text: '...' };
-
-// Hook 中检查标记
-const INTERNAL_MARKER = '"__ds__":true';
-if (!result.includes(INTERNAL_MARKER)) {
-  deepspider.log('json', { ... });
-}
-```
-
-**规范**:
-- sessionStorage/localStorage key 必须以 `deepspider_` 开头
-- 发送到后端的 JSON 消息必须包含 `__ds__: true`
-- 面板消息对象必须包含 `__ds__: true`
-
----
-
-## 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 日志上限 |

package/.trellis/spec/backend/index.md

@@ -1,37 +0,0 @@
-# DeepSpider Development Guidelines
-
-> DeepSpider 项目开发规范
-
----
-
-## Overview
-
-DeepSpider 是基于 DeepAgents + Patchright 的智能爬虫 Agent。
-本目录包含项目的开发规范和代码模式。
-
----
-
-## Guidelines Index
-
-| Guide | Description | Status |
-|-------|-------------|--------|
-| [Directory Structure](./directory-structure.md) | 项目目录结构和模块组织 | Done |
-| [DeepAgents Guide](./deepagents-guide.md) | DeepAgents 框架使用指南 | Done |
-| [Tool Guidelines](./tool-guidelines.md) | LangChain 工具定义规范 | Done |
-| [Hook Guidelines](./hook-guidelines.md) | 浏览器 Hook 注入规范 | Done |
-| [State Management](./state-management.md) | Agent 状态与数据存储 | Done |
-| [Quality Guidelines](./quality-guidelines.md) | 代码质量规范 | Done |
-| [Type Safety](./type-safety.md) | Zod 类型验证规范 | Done |
-| [CI/CD Guidelines](./ci-cd-guidelines.md) | GitHub Actions 自动发布规范 | Done |
-
----
-
-## Quick Reference
-
-核心规范要点：
-
-1. **Agent 创建**: 使用 `createDeepAgent()` + 配置对象
-2. **工具定义**: 使用 `@langchain/core/tools` + Zod schema
-3. **浏览器交互**: 优先使用 CDP，避免 `page.evaluate()`
-4. **AST 遍历**: 使用 `@babel/traverse`
-5. **数据存储**: 使用 `getDataStore()` 单例

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

@@ -1,377 +0,0 @@
-# Quality Guidelines
-
-> DeepSpider 代码质量规范
-
----
-
-## Overview
-
-DeepSpider 遵循 CLAUDE.md 中定义的代码规范，重点关注：
-- CDP 优先的浏览器交互
-- Babel AST 遍历模式
-- LangChain 工具定义规范
-
----
-
-## Forbidden Patterns
-
-### 1. 使用 page.evaluate 代替 CDP
-
-```javascript
-// ❌ 禁止
-const result = await page.evaluate(() => { ... });
-
-// ✅ 使用 CDP
-const cdp = await browser.getCDPSession();
-const result = await cdp.send('Runtime.evaluate', { ... });
-```
-
-### 2. 直接访问封装类的内部属性
-
-```javascript
-// ❌ 禁止：暴露内部实现
-cdpSession.client.on('Debugger.paused', handler);
-
-// ✅ 使用封装类提供的方法
-cdpSession.on('Debugger.paused', handler);
-```
-
-**原因**: 直接访问 `.client` 会导致封装泄漏，当内部实现变化时调用方会报错。
-
-### 3. 子代理不配置中间件
-
-```javascript
-// ❌ 禁止：只在主 Agent 配置中间件，子代理不配置
-// index.js
-const agent = createDeepAgent({
-  middleware: [createFilterToolsMiddleware()],
-  subagents: [subagent1, subagent2],
-});
-
-// subagent1.js - 没有中间件
-export const subagent1 = {
-  name: 'subagent1',
-  tools: [...],
-  middleware: [],  // 空！
-};
-
-// ✅ 子代理也需要配置相同的中间件
-export const subagent1 = {
-  name: 'subagent1',
-  tools: [...],
-  middleware: [
-    createFilterToolsMiddleware(),  // 必须添加
-    createSkillsMiddleware({ ... }),
-  ],
-};
-```
-
-**原因**: DeepAgents 子代理不会继承主 Agent 的中间件配置。如果主 Agent 过滤了内置工具，子代理也必须单独配置过滤中间件，否则子代理仍会使用被过滤的工具。
-
-### 4. setInterval 中使用 async 回调
-
-```javascript
-// ❌ 禁止：async 回调不会被等待，可能导致并发问题
-setInterval(async () => {
-  const result = await detectCaptcha();
-  await handleResult(result);
-}, 30000);
-
-// ✅ 保持同步，只做状态检查和标记
-let needsCheck = false;
-setInterval(() => {
-  const elapsed = Date.now() - lastEventTime;
-  if (elapsed > timeout) {
-    console.log('[提示] 超时，请检查页面');
-  }
-}, 30000);
-```
-
-**原因**: setInterval 不会等待 async 回调完成，多次触发会导致并发执行。
-
-### 5. spawn 使用不存在的 timeout 选项
-
-```javascript
-// ❌ 禁止：spawn 不支持 timeout 选项，超时不会生效
-const proc = spawn('node', ['-e', code], {
-  timeout: 10000,  // 无效！
-});
-
-// ✅ 手动实现超时
-const proc = spawn('node', ['-e', code]);
-let killed = false;
-
-const timer = setTimeout(() => {
-  killed = true;
-  proc.kill('SIGTERM');
-}, 10000);
-
-proc.on('close', () => {
-  clearTimeout(timer);
-});
-```
-
-**原因**: `spawn` 的 options 不包含 `timeout`，这是 `execSync` 的选项。使用 spawn 时必须手动实现超时逻辑。
-
-### 6. 用正则替换 HTML 字符串
-
-```javascript
-// ❌ 禁止：正则替换 HTML 字符串会破坏结构
-function linkifyPaths(html) {
-  return html.replace(/(\/[\w.\-\/]+)/g, '<a href="$1">$1</a>');
-}
-// 会把 </strong> 中的 /strong 也匹配成路径！
-
-// ✅ 使用 DOM TreeWalker 遍历文本节点
-function linkifyPaths(container) {
-  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
-  const textNodes = [];
-  while (walker.nextNode()) textNodes.push(walker.currentNode);
-
-  textNodes.forEach(node => {
-    // 只处理纯文本，不会影响 HTML 标签
-  });
-}
-```
-
-**原因**: 正则无法区分 HTML 标签和文本内容，容易误匹配导致结构破坏。
-
-### 7. LLM 工具参数传递大段代码
-
-```javascript
-// ❌ 禁止：直接传递大段代码内容，可能被 LLM 截断
-await saveReport({ pythonCode: longCodeString });
-
-// ✅ 先保存到文件，再传递文件路径
-await artifactSave({ path: 'domain/decrypt.py', content: code });
-await saveReport({ pythonCodeFile: 'domain/decrypt.py' });
-```
-
-**原因**: LLM 输出有长度限制，大段代码作为参数传递时可能被截断。分步保存确保代码完整性。
-
----
-
-## Required Patterns
-
-### 1. Babel AST 遍历
-
-```javascript
-import traverse from '@babel/traverse';
-
-traverse.default(ast, {
-  FunctionDeclaration(path) {
-    // 处理
-  }
-});
-```
-
-### 2. CDP Session 复用
-
-```javascript
-const cdp = await browser.getCDPSession();
-```
-
-### 3. Hook 日志记录调用位置
-
-```javascript
-// ✅ 在日志中包含解析后的调用位置
-const entry = {
-  ...data,
-  timestamp: Date.now(),
-  stack: stack,
-  caller: caller,  // { func, file, line, col }
-};
-
-// 控制台输出显示文件名和行号
-const loc = caller ? ' @ ' + caller.file.split('/').pop() + ':' + caller.line : '';
-console.log('[DeepSpider:' + type + ']' + loc, data);
-```
-
-**原因**: Hook 日志需要记录 JS 文件调用位置，便于快速定位加密代码来源。
-
----
-
-## Release Process
-
-### 原生模块依赖处理
-
-项目依赖 `isolated-vm` 等原生 C++ 模块，需要编译环境。
-
-**postinstall 自动处理**:
-```json
-{
-  "scripts": {
-    "postinstall": "patchright install chromium && npm rebuild isolated-vm 2>/dev/null || true"
-  }
-}
-```
-
-**编译环境要求**:
-- macOS: `xcode-select --install`
-- Ubuntu: `sudo apt install build-essential`
-- Windows: Visual Studio Build Tools
-
-> **注意**: `2>/dev/null || true` 确保编译失败不会阻塞安装，但沙箱功能可能不可用。
-
----
-
-### 版本发布流程
-
-升级版本并推送 tag，GitHub Actions 会自动发布到 npm：
-
-```bash
-# 1. 升级 package.json 版本
-# 编辑 package.json 中的 version 字段
-
-# 2. 提交版本变更
-git add package.json
-git commit -m "chore: bump version to x.x.x"
-
-# 3. 创建并推送 git tag
-git tag -a vx.x.x -m "vx.x.x"
-git push && git push origin vx.x.x
-```
-
-> **注意**: 推送 tag 后 GitHub Actions 会自动触发 npm 发布，无需手动 `npm publish`。
-
-**原因**: 自动化发布避免手动操作失误，确保版本一致性。
-
----
-
-## Testing Requirements
-
-运行测试：
-
-```bash
-pnpm test
-```
-
----
-
-## Code Review Checklist
-
-- [ ] 工具名称使用 snake_case
-- [ ] 参数有 describe 描述
-- [ ] 浏览器交互使用 CDP
-- [ ] AST 遍历使用 Babel
-- [ ] 数组访问前检查边界
-- [ ] 对象访问前检查空值
-
----
-
-## Defensive Programming
-
-### 1. 数组索引边界检查
-
-```javascript
-// ❌ 禁止：直接访问可能越界
-const stage = stages[parseInt(index)];
-stage.fields.push(field);
-
-// ✅ 先检查边界
-const idx = parseInt(index);
-if (idx < 0 || idx >= stages.length) return;
-const stage = stages[idx];
-```
-
-### 2. 工厂函数避免重复结构
-
-```javascript
-// ❌ 禁止：多处重复对象字面量
-stages.push({ name: 'list', fields: [], entry: null });
-// ... 另一处
-stages = [{ name: 'list', fields: [], entry: null }];
-
-// ✅ 使用工厂函数
-function createStage(name) {
-  return { name, fields: [], entry: null, pagination: null };
-}
-stages.push(createStage('list'));
-```
-
-### 3. 空值检查
-
-```javascript
-// ❌ 禁止：假设对象存在
-currentStage.fields.splice(index, 1);
-
-// ✅ 先检查
-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/.trellis/spec/backend/state-management.md

@@ -1,76 +0,0 @@
-# State Management
-
-> Agent 状态与数据存储规范
-
----
-
-## Overview
-
-DeepSpider 使用 DeepAgents 的状态后端和文件系统存储管理数据。
-Agent 状态通过 FilesystemBackend 持久化，采集数据通过 DataStore 存储。
-
----
-
-## State Categories
-
-| 类型 | 存储方式 | 示例 |
-|------|----------|------|
-| Agent 状态 | FilesystemBackend | `.deepspider-agent/` |
-| 采集数据 | DataStore | `.deepspider-data/` |
-| 会话状态 | MemorySaver | 内存中 |
-
----
-
-## DataStore Pattern
-
-数据存储使用单例模式：
-
-```javascript
-import { getDataStore } from '../store/DataStore.js';
-
-const store = getDataStore();
-await store.saveResponse(data);
-```
-
-**示例**: `src/store/DataStore.js:699-706`
-
----
-
-## Agent Backend
-
-Agent 状态后端配置：
-
-```javascript
-import { FilesystemBackend } from 'deepagents';
-
-const backend = new FilesystemBackend({
-  rootDir: './.deepspider-agent'
-});
-```
-
-**示例**: `src/agent/index.js:59-62`
-
----
-
-## Common Mistakes
-
-### 1. 未使用单例
-
-```javascript
-// ❌ 错误：每次创建新实例
-const store = new DataStore();
-
-// ✅ 正确：使用单例
-const store = getDataStore();
-```
-
-### 2. 忘记启动会话
-
-```javascript
-// ❌ 错误：直接保存
-await store.saveResponse(data);
-
-// ✅ 正确：先启动会话
-store.startSession();
-await store.saveResponse(data);
-```