deepspider 0.2.6 → 0.2.9

package/.trellis/spec/backend/ci-cd-guidelines.md

@@ -0,0 +1,73 @@
+# CI/CD Guidelines
+
+> GitHub Actions 自动发布规范
+
+---
+
+## npm 自动发布
+
+### 触发条件
+
+推送 `v*` 标签时自动触发发布流程。
+
+```bash
+npm version patch && git push && git push --tags
+```
+
+### Workflow 配置要点
+
+#### 1. 原生模块处理
+
+项目包含 `isolated-vm` 等原生模块，在 CI 环境编译可能失败。
+
+**解决方案**：使用 `--ignore-scripts` 跳过编译
+
+```yaml
+- run: pnpm install --no-frozen-lockfile --ignore-scripts
+```
+
+#### 2. NPM_TOKEN 认证
+
+**正确配置**：
+
+1. 在 npmjs.com 生成 **Automation** 类型的 token
+2. 添加为 GitHub **Repository secret**（不是 Environment secret）
+3. 使用 `NODE_AUTH_TOKEN` 环境变量
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    registry-url: 'https://registry.npmjs.org'
+
+- run: npm publish
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+---
+
+## 常见问题
+
+### pnpm lockfile 不匹配
+
+**错误**：`ERR_PNPM_LOCKFILE_CONFIG_MISMATCH`
+
+**解决**：添加 `--no-frozen-lockfile`
+
+### isolated-vm 编译失败
+
+**错误**：`v8::SourceLocation does not name a type`
+
+**原因**：isolated-vm 与新版 Node.js V8 API 不兼容
+
+**解决**：添加 `--ignore-scripts` 跳过原生模块编译
+
+### NPM_TOKEN 认证失败
+
+**错误**：`ENEEDAUTH` 或 `Access token expired`
+
+**检查**：
+1. Token 类型是否为 Automation
+2. Secret 是否为 Repository secret
+3. 使用 `NODE_AUTH_TOKEN` 而非直接写入 `.npmrc`

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

@@ -242,6 +242,49 @@ tools: [...analyzerTools, ...deobfuscatorTools, ...traceTools]
 tools: [...analyzerTools, ...browserTools, ...sandboxTools]
 ```
 
+### systemPrompt 按任务类型动态组合
+
+当不同任务类型需要不同的约束时，应拆分提示词并动态组合：
+
+```javascript
+// src/agent/prompts/system.js
+
+// 基础提示 - 适用于所有对话
+export const systemPrompt = `你是 DeepSpider，智能爬虫 Agent。
+
+## 浏览器面板
+当消息以"[浏览器已就绪]"开头时，浏览器已打开，不要再调用 launch_browser。
+
+## 委托子代理
+简单任务自己做，复杂任务委托子代理。`;
+
+// 完整分析专用 - 仅在特定任务时添加
+export const fullAnalysisPrompt = `
+## 完整分析任务要求
+必须完成端到端验证，验证成功后才能保存报告...`;
+```
+
+在消息处理时动态组合：
+
+```javascript
+// src/agent/run.js
+import { fullAnalysisPrompt } from './prompts/system.js';
+
+if (data.type === 'analysis') {
+  // 完整分析：添加强制验证要求
+  userPrompt = `${browserReadyPrefix}用户选中数据要求分析...
+${fullAnalysisPrompt}`;
+} else if (data.type === 'chat') {
+  // 普通聊天：不添加额外约束
+  userPrompt = `${browserReadyPrefix}${data.text}`;
+}
+```
+
+**好处**：
+- 普通聊天不受端到端验证等强制要求约束
+- 减少不必要的 token 消耗
+- 任务类型明确，Agent 行为可预测
+
 ### Skills 只写经验
 
 ```markdown

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

@@ -104,6 +104,46 @@ for (const trap in handler) {
 }
 ```
 
+### 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

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

@@ -22,6 +22,7 @@ DeepSpider 是基于 DeepAgents + Patchright 的智能爬虫 Agent。
 | [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 |
 
 ---
 

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

@@ -113,6 +113,42 @@ proc.on('close', () => {
 
 **原因**: `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
@@ -135,6 +171,47 @@ traverse.default(ast, {
 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
+
+### 版本发布流程
+
+升级版本时必须同步创建 git tag：
+
+```bash
+# 1. 升级 package.json 版本
+npm version patch --no-git-tag-version
+
+# 2. 提交版本变更
+git add package.json
+git commit -m "chore: bump version to x.x.x"
+
+# 3. 创建并推送 git tag
+git tag vx.x.x
+git push && git push origin vx.x.x
+```
+
+**原因**: npm 版本和 git tag 需要保持同步，便于版本追踪和回溯。
+
 ---
 
 ## Testing Requirements

package/.trellis/workspace/pony/index.md

@@ -8,7 +8,7 @@
 
 <!-- @@@auto:current-status -->
 - **Active File**: `journal-1.md`
-- **Total Sessions**: 1
+- **Total Sessions**: 2
 - **Last Active**: 2026-02-03
 <!-- @@@/auto:current-status -->
 
@@ -19,7 +19,7 @@
 <!-- @@@auto:active-documents -->
 | File | Lines | Status |
 |------|-------|--------|
-| `journal-1.md` | ~61 | Active |
+| `journal-1.md` | ~125 | Active |
 <!-- @@@/auto:active-documents -->
 
 ---
@@ -29,6 +29,7 @@
 <!-- @@@auto:session-history -->
 | # | Date | Title | Commits |
 |---|------|-------|---------|
+| 2 | 2026-02-03 | GitHub Actions 自动发布 npm | `4ff9a25`, `debdc4e`, `ab56fe2`, `67f9c55`, `b13b03d`, `63a6304`, `327ca39`, `78de837`, `46ce73e` |
 | 1 | 2026-02-03 | 环境变量重命名与配置检测 | `4aa6cad` |
 <!-- @@@/auto:session-history -->
 

package/.trellis/workspace/pony/journal-1.md

@@ -59,3 +59,67 @@
 ### Next Steps
 
 - None - task complete
+
+## Session 2: GitHub Actions 自动发布 npm
+
+**Date**: 2026-02-03
+**Task**: GitHub Actions 自动发布 npm
+
+### Summary
+
+(Add summary)
+
+### Main Changes
+
+## 完成内容
+
+实现 GitHub Actions 自动发布到 npm。
+
+| 变更 | 说明 |
+|------|------|
+| GitHub Actions | 添加 .github/workflows/publish.yml |
+| 触发条件 | 推送 v* 标签时自动发布 |
+| CI 流程 | lint → publish |
+| Node.js | 使用 v20 + --ignore-scripts 跳过原生模块编译 |
+
+## 遇到的问题与解决
+
+1. **pnpm lockfile 不匹配** → 添加 --no-frozen-lockfile
+2. **isolated-vm 编译失败** → 添加 --ignore-scripts
+3. **NPM_TOKEN 认证失败** → 使用 NODE_AUTH_TOKEN 环境变量
+
+## 发布流程
+
+```bash
+npm version patch && git push && git push --tags
+```
+
+## 变更文件
+
+- `.github/workflows/publish.yml` - GitHub Actions 配置
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `4ff9a25` | (see git log) |
+| `debdc4e` | (see git log) |
+| `ab56fe2` | (see git log) |
+| `67f9c55` | (see git log) |
+| `b13b03d` | (see git log) |
+| `63a6304` | (see git log) |
+| `327ca39` | (see git log) |
+| `78de837` | (see git log) |
+| `46ce73e` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete

package/CLAUDE.md

@@ -2,6 +2,11 @@
 
 > 基于 DeepAgents + Patchright 的智能爬虫 Agent，覆盖爬虫全生命周期
 
+## 分析方法论
+
+** 每次都分别从资深爬虫工程师和资深技术架构师的两个角度进行理性的辩论性的分析。**
+从最佳实践出发，结合当前项目的实际架构。
+
 ## 功能
 
 ### 逆向分析
@@ -156,6 +161,24 @@ pnpm run agent https://example.com
 
 ## 代码规范
 
+### Hook 内部数据过滤
+
+系统内部操作（消息存储、前后端通信）不应触发 Hook 记录。使用统一标记过滤：
+
+```javascript
+// Storage: 使用 deepspider_ 前缀
+sessionStorage.setItem('deepspider_messages', data);  // 不触发 Hook
+
+// JSON: 使用 __ds__ 标记
+const msg = { __ds__: true, type: 'chat', text: '...' };  // 不触发 Hook
+```
+
+| 场景 | 过滤方式 | 示例 |
+|------|----------|------|
+| sessionStorage | `deepspider_` 前缀 | `deepspider_chat_messages` |
+| 发送到后端的消息 | `__ds__: true` | `{ __ds__: true, type: 'chat' }` |
+| 面板消息对象 | `__ds__: true` | `{ __ds__: true, role, content }` |
+
 ### 浏览器交互
 
 与浏览器的交互优先使用 CDP（Chrome DevTools Protocol）方式，而非 `page.evaluate()`。

package/README.md

@@ -15,6 +15,7 @@
 - **验证码处理**: 滑块、点选、图片验证码
 - **反检测**: 指纹伪装、代理轮换、风控规避
 - **爬虫编排**: 智能调度，输出可运行的 Python 爬虫
+- **交互面板**: 浏览器内置分析面板，支持元素选择、对话交互
 
 ## 快速开始
 
@@ -37,6 +38,11 @@ cp .env.example .env
 # 编辑 .env 填入配置（见下方环境变量说明）
 ```
 
+> **注意**: 项目依赖 `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 格式的供应商。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepspider",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "description": "智能爬虫工程平台 - 基于 DeepAgents + Patchright 的 AI 爬虫 Agent",
   "type": "module",
   "main": "src/index.js",
@@ -17,6 +17,7 @@
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "setup:crypto": "uv venv .venv --python 3.11 2>/dev/null || true && uv pip install -r requirements-crypto.txt",
+    "postinstall": "patchright install chromium && npm rebuild isolated-vm 2>/dev/null || true",
     "prepare": "husky"
   },
   "keywords": [
@@ -51,7 +52,7 @@
     "@langchain/core": "^1.1.17",
     "@langchain/langgraph": "^1.1.2",
     "@langchain/openai": "^1.2.3",
-    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "crypto-js": "^4.2.0",
     "deepagents": "^1.6.0",
     "dotenv": "^17.2.3",