DeepSpider

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