deepspider

一句话定位

DeepSpider 是一款运行在 DSH 之上的浏览器逆向工程平台。它用 Patchright 浏览器观察真实页面、请求和脚本事实，把这些事实转成 Output Contract 与 Runtime Recipe，再交给独立的 Node 运行时（sdenv Worker）重新生成参数，最后用真实 HTTP 请求确认结果，并把验证通过的部分固化成可脱离浏览器复跑的 Solver。

核心能力

• 用 Patchright Chromium（反检测版 Playwright）观察真实页面，捕获脚本、请求与运行时事实
• 通过 CDP 控制台、断点、单步、求值、logpoint 完成 JavaScript 调试
• 显式注入运行时 Hook 与属性采集，补齐浏览器侧事实，不修改捕获源码
• 沿请求 Initiator、调用栈定位参数写入边界，导出 Output Contract 与 Runtime Recipe
• 在独立的 sdenv Worker 子进程中重新生成参数，再用 CycleTLS 发起真实请求做端到端验证
• 验证通过后导出四个文件的独立 Solver，关闭浏览器后仍可在新环境复跑

技术实现

• 语言: JavaScript（ESM）
• 关键依赖: @deepseek-ai/dsh、patchright、sdenv、cycletls
• 架构模式: 通过 dsh.bundle.patch（dsh/cordis.patch.yml）向 DSH Host Plane 注入 Host 与 Preset 插件，同时向 Agent Plane 注册中央工具目录；每个 Session 独立持有 DeepSpiderRuntime（Patchright Chromium + CDP + Dialog + sdenv Worker + SessionArtifactStore + CycleTLS Validator）
• 入口文件: src/dsh/host-plugin.js、src/dsh/agent-plugin.js、src/dsh/launcher.js、bin/cli.js

适用场景

当你面对一个普通爬虫拿不到数据的网站，需要理解并复现它的请求参数或 Cookie 生成逻辑时，可以用 DeepSpider 让 AI 自动观察浏览器事实并尝试恢复生成流程。它把"分析"和"独立复跑"两件事打通：分析出来的结果必须是脱离浏览器、在独立 Node 运行时里也能用真实请求复现的 Solver，适合需要把分析成果固化成可审计、可复跑脚本交付给下游的场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:ma-pony/deepspider

配置项

本插件没有 DSH 侧的配置面板；只有启动命令行参数和少量环境变量。

常见问题

Q: 这个插件和普通的爬虫或 Selenium 自动化有什么不一样？

A: DeepSpider 不止做页面自动化，它把浏览器观察到的事实转成 Output Contract + Runtime Recipe，再交给独立的 Node 运行时重新生成参数，用真实请求确认结果正确，最后输出可脱离浏览器复跑的 Solver，而不是停留在"一次抓取成功"。

Q: 它能自动恢复哪些输出类型？

A: 首版端到端自动链路只覆盖 Cookie。Header、Query、Body、返回值和导航可以进入证据和 Output Contract，但当前不会由高层工具自动完成独立生成、真实请求验证和 Solver 导出，仍需要人工介入。

Q: 自动恢复的产物和 Solver 文件放在哪里？

A: 每个 Agent Session 在 ~/.deepspider/sessions/<sha256(agent.id)>/ 下有独立目录，包含 evidence/、artifacts/、runs/、solvers/、screenshots/、browser-data/，不同 Session 互相隔离。验证通过的 Cookie 恢复会在 solvers/<contract-recipe-hash>/ 下生成 solver.mjs、contract.json、recipe.json、package.json 四个文件。

Q: 启动 deepspider agent 失败的常见原因有哪些？

A: 主要是 Node 版本低于 24.15.0、首次安装时 postinstall 没把 Patchright Chromium 下载下来，或运行环境禁止派生 Chromium 子进程。项目根目录的 .env 不会被自动加载，要在无头模式下运行需要显式设置 DEEPSPIDER_HEADLESS=true。

Q: 用 mode: 'algorithm' 会发生什么？

A: 当前没有自动算法引擎，会显式返回 algorithm-recovery-engine-not-implemented blocker，让 Agent 用 Hook、Debugger、Code Mode 手工恢复或等待后续实现。DeepSpider 不会把未实现的部分描述成自动完成。

Q: 我只想发一次不带浏览器的轻量请求，怎么做？

A: 用 deepspider fetch <url> 通过 CycleTLS 发一次轻量 HTTP 请求，不启动浏览器也不进入逆向流程；如果响应码 ≥400，命令行会提示改用 deepspider agent 处理。

上手难度

专家 — 需要熟悉 DSH 工具调用、Patchright/CDP 调试、JavaScript 逆向与 sdenv 运行时；建议先用普通 DSH 与 Patchright 跑通页面自动化再使用自动恢复。

已知问题与限制

• 首版端到端自动链路只覆盖 Cookie；Header、Query、Body、返回值、导航的独立生成与 Solver 导出尚未由高层工具自动完成（src/recovery/contracts.js:3，README.md:63）
• mode: 'algorithm' 当前没有自动算法引擎，会显式返回 program blocker 而非自动完成（src/recovery/coordinator.js:129，src/recovery/strategy-detector.js:11）
• RecoveryCoordinator 单次恢复最多重试 3 次；3 次都未通过时不会自动调整 Runtime Recipe，只会返回首个 blocker 和下一动作（src/recovery/coordinator.js:11，README.md:112）
• 集成测试和 Patchright Chromium 启动依赖允许派生 Chromium 子进程；在受限容器或 CI 里可能直接失败（README.md:218）
• 项目根目录的 .env 不会被自动加载；无头模式需显式设置 DEEPSPIDER_HEADLESS=true（src/runtime/DeepSpiderRuntime.js:302，README.md:218）
• Solver 创建全新的 Cookie Jar 并只读 contract.json 与 recipe.json，不会读取 browser-data/ 或捕获的 Cookie（src/recovery/solver.js，README.md:182）

AI 原生的智能爬虫与 JavaScript 逆向工程平台——基于 DSH、Patchright/CDP 与独立语义运行时，从浏览器证据恢复参数生成逻辑，并交付经过真实请求验证的可运行 Solver。

DeepSpider 将 DSH Web、Patchright Chromium、Chrome DevTools Protocol（CDP）和独立 Node 语义运行时组合成一套逆向工作台。浏览器负责采集请求、脚本与运行时事实；最终结果必须由非浏览器运行时重新生成，并通过真实请求验证，而不是停留在页面自动化或一次抓取结果。

English

快速开始

需要 Node.js >=24.15.0。全局安装会下载 Patchright Chromium。

npm install -g deepspider
deepspider agent

deepspider 同时发布为原生 DSH Bundle。主启动命令会通过 DSH Profile 管理器将它挂载到 web Profile；已有 DSH 环境也可以直接安装：

dsh plugin --profile web add deepspider
dsh web

这是主启动命令。DSH Web 会加载 Spider Preset；新建一个 Session，说明目标 URL、触发路径和目标输出。首版自动语义恢复只支持 Cookie。Header、Query、Body、返回值和导航仍可作为浏览器证据、Output Contract 和手工分析目标，但当前不会由高层工具自动生成 reproduced 结果或 Solver。多个 Session 可以同时运行，各自持有独立浏览器、SessionArtifactStore、Worker 和产物目录。

Ctrl+C 会关闭 DSH Web，并等待所有 Session 的 Patchright Chromium、sdenv Worker 和运行资源退出。

DeepSpider 解决什么问题

• 沿真实请求的 Initiator、调用栈和脚本源码定位参数写入边界。
• 分析动态执行、Webpack、Worker、WebAssembly、状态机和高度混淆代码。
• 用 Hook、Debugger 和属性采集补足浏览器事实，而不是直接修改捕获源码。
• 将 Cookie 生成所需的浏览器依赖描述成可审计的 Runtime Recipe，再由独立 Worker 执行。
• 用真实请求验证自动生成的 Cookie，并导出可以脱离浏览器 Session 重跑的 Solver；其他输出继续使用通用浏览器、Hook、Debugger 和 Code Mode 定位与实现。

唯一完成定义

对于当前自动支持的 Cookie 恢复，只有以下链路全部成立才算完成：Browser Oracle 已保存目标证据；Output Contract 与 Runtime Recipe 已绑定当前 Session；独立 sdenv Worker 用全新状态生成 Cookie；CycleTLS 仅使用这些生成值完成真实请求；验证等级为 reproduced；导出的 Solver 能在浏览器关闭后再次得到同一验收结果。

浏览器结果、页面自动化脚本、捕获 Cookie、单次 Hook 日志或仅能回放的请求都不是完成证据。

输出驱动的语义恢复

Browser Oracle → Session Artifact Graph → Output Contract → Runtime Recipe
               → sdenv Worker → Real-request Validation → Solver

Output Contract 可以描述 Cookie、Header、Query、Body、返回值和导航。首版端到端自动链路只对 Cookie 实现 Worker 生成、真实请求验证和 Solver 导出；其余类型保留 Contract、Artifact Graph 和手工逆向能力，不宣称自动 reproduced。

三种证据等级

Runtime Recipe 的站点边界

确定的固定指纹、属性隐藏、window proxy 配置和站点规则可以写入当前 Session 的 Runtime Recipe。Recipe 与 Contract、引擎版本、上游 Artifact ID 和 SHA-256 一起进入生成结果身份链。通用底层只执行声明式规则，不按站点名称、Cookie 名或风控厂商分支。

Patchright Session 是重要样本，但不是浏览器环境的唯一真值。遇到自动化特征或时序差异时，可结合普通 Chrome、多个 Session 或已确认的目标行为采集新证据，再更新 Recipe。

原始证据与派生产物

捕获的脚本、响应和动态源码保存为不可变 observed Artifact。格式化、去混淆或定点处理会创建新的 derived Artifact，并保留来源 ID、变换说明和内容哈希。Worker 输出保存为 generated Artifact；只有真实请求验证通过，结果才达到 reproduced。

一个恢复入口

正常恢复只使用高层工具：

recover_target_output({ url, outputKind, outputSelector?, mode? })

对于 Cookie Contract，工具建立 Artifact Graph、Output Contract 和 Runtime Recipe，启动 Session-owned sdenv Worker，执行真实请求验证并导出 Solver。Header、Query、Body、返回值和导航可以进入证据与 Contract，但当前高层工具不会为它们自动完成独立生成和 Solver 导出。工具只向 Agent 返回阶段状态、证据等级、策略、首个 blocker、Solver Artifact ID 和下一动作；源码、Cookie 值和完整运行日志保留在私有 Session Artifact 中。

mode: "auto" 默认选择语义运行时。mode: "algorithm" 当前没有自动算法引擎，会返回显式 program blocker：algorithm-recovery-engine-not-implemented。随后由 Agent 使用现有 Hook、Debugger 和 Code Mode 手工恢复影响目标输出的局部逻辑，或等待后续算法引擎实现；系统不会把未实现的升级描述成自动完成。

八阶段逆向工作流

intake → evidence → locate → recover → runtime → extraction → validation → handoff

Coordinator 最多执行三次语义尝试，成功即停止。它不会在尝试之间自动修改 Runtime Recipe 或处理 blocker；三次均未通过时，只返回首个 blocker 和下一动作。Agent 再按该结果补充证据或手工修改 Recipe 后发起新一轮恢复。environment 表示缺失的浏览器语义，resource 表示依赖或网络响应问题，program 表示当前引擎无法执行的程序行为，validation 表示已生成输出但真实请求未接受。

DSH Agent 与 Dialog

• Sessions：多个任务并行运行，浏览器、Worker 与文件相互隔离。
• Goals 与 Todo：分别记录任务目标和当前执行项。
• Code Mode：通过 run_code 与生成的 TypeScript SDK 调用 DeepSpider 工具。
• Cordis 动态工具：按当前 Agent 权限检查和调用运行时能力。
• Web Search：查找公开资料；真实页面事实仍由 Browser Oracle 采集。
• Dialog：浏览器内的可选交互面板，显示浏览器证据、Artifact Graph、Node 生成和请求验证四段状态。

输出类型不明确、需要登录操作或需要升级算法恢复时，DeepSpider 使用 DSH 原生单选、多选和自定义答案协议。browser_dialog 只在当前 Session 已启动浏览器时打开；回答回到同一 Session，不会建立第二套对话状态。

使用方式

fetch 不启动浏览器，也不进入 Agent 逆向流程。MCP stdio 外部适配器向其他客户端提供同一中央工具目录；完整的多 Session 工作流使用 DSH Web。

工具目录

工具数量由中央 Catalog 生成，不作为文档契约固定。

Session 产物与 Solver

~/.deepspider/sessions/<sha256(agent.id)>/
├── evidence/
│   ├── sites/            # 请求、响应、脚本与站点索引
│   └── artifacts/        # Artifact Graph、Contract、Recipe、Run、Validation、Solver
├── runs/                 # sdenv Worker 请求、结果与诊断
├── solvers/              # 可独立运行的 Solver
├── screenshots/
└── browser-data/

每个成功的 Cookie 自动恢复会在 solvers/ 下生成四个文件：

solver.mjs
contract.json
recipe.json
package.json

在该目录使用 npm 安装并运行，安装阶段会构建 sdenv 原生模块：

npm install
node solver.mjs

Solver 创建全新 Cookie Jar，不导入 Patchright，也不读取 Session 的 browser-data/ 或捕获 Cookie。它输出紧凑的验证结果，并在退出前关闭 sdenv 与 CycleTLS。

架构

DSH Web Host Plane
├── Sessions、模型、Goals、Todo、Cordis 与事件路由
└── Spider Agent Plane
    ├── Code Mode + DeepSpider Catalog
    └── Session-owned DeepSpider Runtime
        ├── Patchright Chromium + CDP + Dialog
        ├── Browser Oracle + SessionArtifactStore
        ├── Session Artifact Graph + RecoveryCoordinator
        └── sdenv Worker + CycleTLS Validator + Solver

MCP stdio adapter
└── 同一 DeepSpider Catalog

Host Plane 管理应用级服务和多个 Session；Agent Plane 在单个 Session 内执行逆向任务。RuntimeManager 维护状态边界。Session 被销毁或 Host 收到退出信号时，DeepSpider 先中止当前操作并关闭 Worker，再关闭 Dialog、CDP、Patchright Chromium 和 Store。

开发与发布验证

源码开发使用 Node.js >=24.15.0 和 pnpm 11.22.0。

git clone https://github.com/ma-pony/deepspider.git
cd deepspider
pnpm install

pnpm test
pnpm lint
pnpm test:integration
pnpm smoke:pack

集成测试需要本机允许启动 Patchright Chromium。DeepSpider 不会自动加载项目根目录的 .env；无头模式可显式设置 DEEPSPIDER_HEADLESS=true。

授权边界

DSH 保存模型 provider 设置与凭据，DeepSpider 不内置账号。Cordis、浏览器调试、脚本执行和网络访问属于高权限能力，只应在可信任务中使用。请仅分析自己拥有或已获授权的目标，并遵守目标条款和适用法律。

License

MIT