deepspider 0.2.12 → 0.3.0

package/README.md

@@ -37,40 +37,51 @@ cp .env.example .env  # 配置环境变量
 pnpm run setup:crypto  # 安装 Python 加密库（可选）
 ```
 
-安装完成后，首次运行会提示配置环境变量（LLM API）。
+安装完成后，首次运行会提示配置 LLM API。
 
 > **注意**: 项目依赖 `isolated-vm` 原生模块，需要 C++ 编译环境：
 > - macOS: `xcode-select --install`
 > - Ubuntu: `sudo apt install build-essential`
 > - Windows: 安装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
 
-### 环境变量配置
+### 配置
 
 DeepSpider 需要配置 LLM API 才能运行。支持任何兼容 OpenAI 格式的供应商。
 
-| 变量名 | 必填 | 说明 |
-|--------|------|------|
-| `DEEPSPIDER_API_KEY` | 是 | API 密钥 |
-| `DEEPSPIDER_BASE_URL` | 是 | API 地址 |
-| `DEEPSPIDER_MODEL` | 是 | 模型名称 |
+| 配置键 | 环境变量 | 说明 |
+|--------|----------|------|
+| `apiKey` | `DEEPSPIDER_API_KEY` | API 密钥 |
+| `baseUrl` | `DEEPSPIDER_BASE_URL` | API 地址 |
+| `model` | `DEEPSPIDER_MODEL` | 模型名称 |
 
-**常用供应商配置示例**：
+优先级：环境变量 > 配置文件 (`~/.deepspider/config/settings.json`) > 默认值
+
+**方式一：使用 CLI 命令（推荐）**
+
+```bash
+deepspider config set apiKey sk-xxx
+deepspider config set baseUrl https://api.openai.com/v1
+deepspider config set model gpt-4o
+```
+
+**方式二：环境变量**
+
+```bash
+export DEEPSPIDER_API_KEY=sk-xxx
+export DEEPSPIDER_BASE_URL=https://api.openai.com/v1
+export DEEPSPIDER_MODEL=gpt-4o
+```
+
+**常用供应商示例**：
 
 ```bash
 # OpenAI
-DEEPSPIDER_API_KEY=sk-xxx
-DEEPSPIDER_BASE_URL=https://api.openai.com/v1
-DEEPSPIDER_MODEL=gpt-4o
+deepspider config set baseUrl https://api.openai.com/v1
+deepspider config set model gpt-4o
 
 # DeepSeek
-DEEPSPIDER_API_KEY=sk-xxx
-DEEPSPIDER_BASE_URL=https://api.deepseek.com/v1
-DEEPSPIDER_MODEL=deepseek-chat
-
-# 其他 OpenAI 兼容供应商
-DEEPSPIDER_API_KEY=your-key
-DEEPSPIDER_BASE_URL=https://your-provider.com/v1
-DEEPSPIDER_MODEL=model-name
+deepspider config set baseUrl https://api.deepseek.com/v1
+deepspider config set model deepseek-chat
 ```
 
 ### 使用
@@ -78,24 +89,33 @@ DEEPSPIDER_MODEL=model-name
 #### 全局安装（npm/pnpm install -g）
 
 ```bash
-# 配置环境变量
-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
+
+# 查看帮助
+deepspider --help
+
+# 管理配置
+deepspider config list            # 查看所有配置
+deepspider config set apiKey sk-xxx
+deepspider config set model gpt-4o
+
+# 检查更新
+deepspider update
 ```
 
 #### 克隆仓库
 
 ```bash
-# 配置环境变量（二选一）
+# 配置（二选一）
 cp .env.example .env  # 编辑 .env 文件
-# 或 export DEEPSPIDER_API_KEY=... 等
+# 或使用 CLI 命令
+node bin/cli.js config set apiKey sk-xxx
+node bin/cli.js config set baseUrl https://api.openai.com/v1
+node bin/cli.js config set model gpt-4o
 
 # 安装 Python 依赖（可选，用于执行生成的 Python 代码）
 pnpm run setup:crypto
@@ -161,12 +181,19 @@ pnpm test
 
 ```
 deepspider/
+├── bin/cli.js               # CLI 入口（命令路由）
 ├── src/
 │   ├── agent/               # DeepAgent 系统
 │   │   ├── tools/           # 工具集（90+）
 │   │   ├── subagents/       # 子代理
 │   │   ├── skills/          # 领域技能
 │   │   └── prompts/         # 系统提示
+│   ├── cli/                 # CLI 命令
+│   │   ├── config.js        # 配置 re-export
+│   │   └── commands/        # 子命令（version/help/config/update）
+│   ├── config/              # 核心配置
+│   │   ├── paths.js         # 路径常量
+│   │   └── settings.js      # 配置读写（环境变量/文件/默认值）
 │   ├── browser/             # 浏览器运行时
 │   │   ├── client.js        # Patchright 客户端
 │   │   ├── cdp.js           # CDP 会话管理
@@ -177,7 +204,6 @@ deepspider/
 │   ├── env/                 # 环境补丁模块
 │   ├── store/               # 数据存储
 │   └── mcp/                 # MCP 服务
-├── bin/cli.js               # CLI 入口
 └── test/                    # 测试
 ```
 

package/bin/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * DeepSpider CLI 入口
+ * 路由命令到对应处理模块
+ */
+
+import 'dotenv/config';
+
+const args = process.argv.slice(2);
+const first = args[0];
+
+switch (first) {
+  case '-v':
+  case '--version': {
+    const { run } = await import('../src/cli/commands/version.js');
+    run();
+    break;
+  }
+
+  case '-h':
+  case '--help': {
+    const { run } = await import('../src/cli/commands/help.js');
+    run();
+    break;
+  }
+
+  case 'config': {
+    const { run } = await import('../src/cli/commands/config.js');
+    run(args.slice(1));
+    break;
+  }
+
+  case 'update': {
+    const { run } = await import('../src/cli/commands/update.js');
+    await run();
+    break;
+  }
+
+  default: {
+    // URL 或无参数 → 启动 Agent
+    const { init } = await import('../src/agent/run.js');
+    await init();
+    break;
+  }
+}

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "deepspider",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "description": "智能爬虫工程平台 - 基于 DeepAgents + Patchright 的 AI 爬虫 Agent",
   "type": "module",
   "main": "src/index.js",
+  "files": [
+    "bin/",
+    "src/",
+    "requirements-crypto.txt",
+    ".env.example"
+  ],
   "bin": {
-    "deepspider": "./src/agent/run.js"
+    "deepspider": "./bin/cli.js"
   },
   "scripts": {
     "start": "node src/index.js",
     "dev": "node --watch src/index.js",
-    "cli": "node src/agent/run.js",
+    "cli": "node bin/cli.js",
     "mcp": "node src/mcp/server.js",
-    "agent": "node src/agent/run.js",
+    "agent": "node bin/cli.js",
     "test": "node --test test/",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",

package/src/agent/run.js

@@ -1,11 +1,11 @@
-#!/usr/bin/env node
 /**
- * DeepSpider Agent 独立运行入口
+ * DeepSpider Agent 运行模块
  * 使用 CDP binding 接收浏览器消息
  * 支持流式输出显示思考过程
+ *
+ * 所有状态初始化延迟到 init() 中执行，避免 import 时产生副作用
  */
 
-import 'dotenv/config';
 import readline from 'readline';
 import { readFileSync } from 'fs';
 import { marked } from 'marked';
@@ -18,60 +18,14 @@ import { browserTools } from './tools/browser.js';
 import { ensureConfig } from './setup.js';
 import { StreamHandler, PanelBridge } from './core/index.js';
 
-const args = process.argv.slice(2);
-const targetUrl = args.find(arg => arg.startsWith('http://') || arg.startsWith('https://'));
-
-const rl = readline.createInterface({
-  input: process.stdin,
-  output: process.stdout,
-});
-
+let rl = null;
 let browser = null;
 let streamHandler = null;
-
-console.log('=== DeepSpider Agent ===');
-console.log('智能爬虫 Agent，输入 exit 退出\n');
-
-const DEBUG = process.env.DEBUG === 'true' || process.argv.includes('--debug');
-
-function debug(...args) {
-  if (DEBUG) {
-    console.log('[DEBUG]', ...args);
-  }
-}
-
-const logger = createLogger({ enabled: DEBUG, verbose: false });
-
-/**
- * 报告就绪回调 - 由中间件在 afterAgent 时调用
- */
-async function onReportReady(mdFilePath) {
-  console.log('[report] 中间件触发报告显示:', mdFilePath);
-  await showReportFromFile(mdFilePath);
-}
-
-// 创建 Agent
-const agent = createDeepSpiderAgent({ onReportReady });
-
-const config = {
-  configurable: { thread_id: `deepspider-${Date.now()}` },
-  recursionLimit: 5000,
-  callbacks: logger ? [logger] : [],
-};
-
-/**
- * 初始化流处理器
- */
-function initStreamHandler() {
-  const panelBridge = new PanelBridge(() => browser, debug);
-  streamHandler = new StreamHandler({
-    agent,
-    config,
-    panelBridge,
-    riskTools: browserTools.map(t => t.name),
-    debug,
-  });
-}
+let targetUrl = null;
+let DEBUG = false;
+let debugFn = () => {};
+let agent = null;
+let agentConfig = null;
 
 /**
  * 从文件显示报告（由中间件回调触发）
@@ -106,7 +60,7 @@ async function showReportFromFile(mdFilePath) {
  * 处理浏览器消息（通过 CDP binding 接收）
  */
 async function handleBrowserMessage(data, page) {
-  debug(`handleBrowserMessage: 收到消息, type=${data.type}, page=${!!page}`);
+  debugFn(`handleBrowserMessage: 收到消息, type=${data.type}, page=${!!page}`);
 
   const browserReadyPrefix = '[浏览器已就绪] ';
 
@@ -193,7 +147,13 @@ function prompt() {
 }
 
 async function init() {
-  debug('init: 启动');
+  // 解析参数（在 init 时才读取，避免与 CLI 路由层的 argv 冲突）
+  const args = process.argv.slice(2);
+  targetUrl = args.find(arg => arg.startsWith('http://') || arg.startsWith('https://'));
+  DEBUG = process.env.DEBUG === 'true' || args.includes('--debug');
+  debugFn = (...a) => { if (DEBUG) console.log('[DEBUG]', ...a); };
+
+  debugFn('init: 启动');
 
   if (!ensureConfig()) {
     process.exit(1);
@@ -203,27 +163,58 @@ async function init() {
     console.log('[DEBUG] 调试模式已启用');
   }
 
+  // 创建 readline、logger、agent（全部延迟到 init）
+  rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const logger = createLogger({ enabled: DEBUG, verbose: false });
+
+  async function onReportReady(mdFilePath) {
+    console.log('[report] 中间件触发报告显示:', mdFilePath);
+    await showReportFromFile(mdFilePath);
+  }
+
+  agent = createDeepSpiderAgent({ onReportReady });
+
+  agentConfig = {
+    configurable: { thread_id: `deepspider-${Date.now()}` },
+    recursionLimit: 5000,
+    callbacks: logger ? [logger] : [],
+  };
+
   // 初始化流处理器
-  initStreamHandler();
+  const panelBridge = new PanelBridge(() => browser, debugFn);
+  streamHandler = new StreamHandler({
+    agent,
+    config: agentConfig,
+    panelBridge,
+    riskTools: browserTools.map(t => t.name),
+    debug: debugFn,
+  });
+
+  console.log('=== DeepSpider Agent ===');
+  console.log('智能爬虫 Agent，输入 exit 退出\n');
 
   if (targetUrl) {
     console.log(`正在打开: ${targetUrl}\n`);
     try {
-      debug('init: 获取浏览器实例');
+      debugFn('init: 获取浏览器实例');
       browser = await getBrowser();
       browser.onMessage = handleBrowserMessage;
-      debug('init: 导航到目标URL');
+      debugFn('init: 导航到目标URL');
       await browser.navigate(targetUrl);
       markHookInjected();
-      debug('init: 浏览器就绪');
+      debugFn('init: 浏览器就绪');
       console.log('浏览器已就绪，数据自动记录中');
       console.log('点击面板选择按钮(⦿)选择数据进行分析\n');
     } catch (error) {
       console.error('启动浏览器失败:', error.message);
-      debug('init: 浏览器启动失败 -', error.stack);
+      debugFn('init: 浏览器启动失败 -', error.stack);
     }
   }
   prompt();
 }
 
-init();
+export { init };

package/src/agent/setup.js

@@ -1,17 +1,15 @@
 /**
  * DeepSpider 配置检测
- * 简单检测 + 清晰提示，不做交互式向导
+ * 环境变量 > 配置文件 > 默认值
  */
 
+import { getConfigValues } from '../config/settings.js';
+
 /**
- * 检查环境变量是否已配置
+ * 检查配置（合并环境变量和配置文件）
  */
 export function checkEnvConfig() {
-  return {
-    apiKey: process.env.DEEPSPIDER_API_KEY,
-    baseUrl: process.env.DEEPSPIDER_BASE_URL,
-    model: process.env.DEEPSPIDER_MODEL,
-  };
+  return getConfigValues();
 }
 
 /**
@@ -22,9 +20,9 @@ export function ensureConfig() {
   const { apiKey, baseUrl, model } = checkEnvConfig();
   const missing = [];
 
-  if (!apiKey) missing.push('DEEPSPIDER_API_KEY');
-  if (!baseUrl) missing.push('DEEPSPIDER_BASE_URL');
-  if (!model) missing.push('DEEPSPIDER_MODEL');
+  if (!apiKey) missing.push('apiKey (DEEPSPIDER_API_KEY)');
+  if (!baseUrl) missing.push('baseUrl (DEEPSPIDER_BASE_URL)');
+  if (!model) missing.push('model (DEEPSPIDER_MODEL)');
 
   if (missing.length === 0) {
     return true;
@@ -35,14 +33,16 @@ export function ensureConfig() {
 
 配置方式（任选其一）：
 
-1. 配置环境变量（推荐）：
+1. 使用 deepspider config 命令：
+   deepspider config set apiKey sk-xxx
+   deepspider config set baseUrl https://api.openai.com/v1
+   deepspider config set model gpt-4o
+
+2. 配置环境变量：
    export DEEPSPIDER_API_KEY=sk-xxx
    export DEEPSPIDER_BASE_URL=https://api.openai.com/v1
    export DEEPSPIDER_MODEL=gpt-4o
 
-2. 一行命令：
-   DEEPSPIDER_API_KEY=sk-xxx DEEPSPIDER_BASE_URL=https://api.openai.com/v1 DEEPSPIDER_MODEL=gpt-4o deepspider <url>
-
 请根据提示补全配置后重试。
 `);
 

package/src/cli/commands/config.js

@@ -0,0 +1,94 @@
+/**
+ * deepspider config 子命令
+ */
+
+import {
+  loadConfig,
+  saveConfig,
+  getEffectiveConfig,
+  resetConfig,
+  CONFIG_FILE,
+  ENV_MAP,
+  DEFAULTS,
+} from '../config.js';
+
+export function run(args) {
+  const sub = args[0] || 'list';
+
+  switch (sub) {
+    case 'list':
+      return list();
+    case 'get':
+      return get(args[1]);
+    case 'set':
+      return set(args[1], args[2]);
+    case 'reset':
+      return reset();
+    case 'path':
+      return path();
+    default:
+      console.error(`未知子命令: ${sub}\n可用: list, get, set, reset, path`);
+      process.exit(1);
+  }
+}
+
+function list() {
+  const effective = getEffectiveConfig();
+  console.log('配置项:');
+  for (const [key, { value, source }] of Object.entries(effective)) {
+    const display = key === 'apiKey' && value ? maskKey(value) : value || '(未设置)';
+    console.log(`  ${key} = ${display}  [${source}]`);
+  }
+}
+
+function get(key) {
+  if (!key) {
+    console.error('用法: deepspider config get <key>');
+    process.exit(1);
+  }
+  if (!Object.hasOwn(DEFAULTS, key)) {
+    console.error(`未知配置项: ${key}\n可用: ${Object.keys(DEFAULTS).join(', ')}`);
+    process.exit(1);
+  }
+  const effective = getEffectiveConfig();
+  const { value, source } = effective[key];
+  const display = key === 'apiKey' && value ? maskKey(value) : value || '(未设置)';
+  console.log(`${key} = ${display}  [${source}]`);
+}
+
+function set(key, value) {
+  if (!key || value === undefined) {
+    console.error('用法: deepspider config set <key> <value>');
+    process.exit(1);
+  }
+  if (!Object.hasOwn(DEFAULTS, key)) {
+    console.error(`未知配置项: ${key}\n可用: ${Object.keys(DEFAULTS).join(', ')}`);
+    process.exit(1);
+  }
+  const config = loadConfig();
+  config[key] = value;
+  saveConfig(config);
+
+  const envVar = ENV_MAP[key];
+  console.log(`已设置 ${key} = ${key === 'apiKey' ? maskKey(value) : value}`);
+  if (process.env[envVar]) {
+    console.log(`注意: 环境变量 ${envVar} 已设置，将优先使用环境变量的值`);
+  }
+}
+
+function reset() {
+  if (resetConfig()) {
+    console.log('配置已重置');
+  } else {
+    console.log('配置文件不存在，无需重置');
+  }
+}
+
+function path() {
+  console.log(CONFIG_FILE);
+}
+
+function maskKey(key) {
+  if (key.length <= 8) return '****';
+  return key.slice(0, 4) + '****' + key.slice(-4);
+}

package/src/cli/commands/help.js

@@ -0,0 +1,34 @@
+/**
+ * deepspider --help
+ */
+
+import { getVersion } from '../../config/settings.js';
+
+export function run() {
+  console.log(`
+deepspider v${getVersion()} - 智能爬虫工程平台
+
+用法:
+  deepspider                        启动交互式 Agent
+  deepspider <url>                  打开目标网站并启动 Agent
+  deepspider config                 管理配置
+  deepspider update                 检查更新
+
+选项:
+  -v, --version                     显示版本号
+  -h, --help                        显示帮助信息
+  --debug                           启用调试模式
+
+配置命令:
+  deepspider config list            列出所有配置
+  deepspider config get <key>       获取配置项
+  deepspider config set <key> <val> 设置配置项
+  deepspider config reset           重置配置
+  deepspider config path            显示配置文件路径
+
+示例:
+  deepspider https://example.com    分析目标网站
+  deepspider config set apiKey sk-xxx
+  deepspider config set model gpt-4o
+`.trim());
+}

package/src/cli/commands/update.js

@@ -0,0 +1,78 @@
+/**
+ * deepspider update
+ */
+
+import readline from 'readline';
+import { existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { join } from 'path';
+import { getVersion } from '../../config/settings.js';
+
+export async function run() {
+  const current = getVersion();
+
+  console.log(`当前版本: v${current}`);
+  console.log('检查更新...');
+
+  let latest;
+  try {
+    const resp = await fetch('https://registry.npmjs.org/deepspider/latest');
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    const data = await resp.json();
+    latest = data.version;
+  } catch (e) {
+    console.error(`检查更新失败: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (current === latest) {
+    console.log(`已是最新版本 v${current}`);
+    return;
+  }
+
+  console.log(`发现新版本: v${latest}`);
+
+  const isGlobal = detectGlobalInstall();
+
+  if (isGlobal) {
+    const confirmed = await confirm(`是否更新到 v${latest}？(y/N) `);
+    if (!confirmed) {
+      console.log('已取消');
+      return;
+    }
+    console.log('正在更新...');
+    try {
+      execSync('npm install -g deepspider@latest', { stdio: 'inherit' });
+      console.log(`已更新到 v${latest}`);
+    } catch {
+      console.error('更新失败，请手动执行: npm install -g deepspider@latest');
+      process.exit(1);
+    }
+  } else {
+    console.log('当前为本地安装，请手动更新:');
+    console.log('  git pull && pnpm install');
+  }
+}
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y');
+    });
+  });
+}
+
+function detectGlobalInstall() {
+  try {
+    const globalDir = execSync('npm root -g', { encoding: 'utf-8' }).trim();
+    const globalPkg = join(globalDir, 'deepspider');
+    return existsSync(globalPkg);
+  } catch {
+    return false;
+  }
+}

package/src/cli/commands/version.js

@@ -0,0 +1,9 @@
+/**
+ * deepspider --version
+ */
+
+import { getVersion } from '../../config/settings.js';
+
+export function run() {
+  console.log(`deepspider v${getVersion()}`);
+}

package/src/cli/config.js

@@ -0,0 +1,15 @@
+/**
+ * CLI 配置模块 - 从 config/ 核心层 re-export
+ */
+
+export {
+  CONFIG_FILE,
+  DEFAULTS,
+  ENV_MAP,
+  loadConfig,
+  saveConfig,
+  getEffectiveConfig,
+  getConfigValues,
+  resetConfig,
+  getVersion,
+} from '../config/settings.js';