ma-pony / deepspider

DeepSpider

AI 原生的 JavaScript 逆向工程平台——从真实请求证据出发，定位参数生成链路，并交付可直接请求的实现与可运行 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

这是主启动命令。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

阶段	作用	边界
Browser Oracle	用 Patchright Chromium + CDP 观察真实页面、请求、脚本和运行时事实	浏览器最终值只形成 observed 证据
Session Artifact Graph	关联 Document、Script、动态源码、请求、响应及后续恢复产物	原始内容不可覆盖，所有节点属于当前 Session
Output Contract	定义要生成的输出和请求成功条件	只恢复影响目标输出的语义
Runtime Recipe	声明固定值、属性隐藏、window proxy、UA、TLS 与超时	站点规则留在 Session Recipe，不进入通用底层分支
sdenv Worker	在独立 Node 子进程和全新 Cookie Jar 中执行页面语义	不读取 Patchright 最终输出或 browser-data/
Request Validation	仅用 Worker 生成值发起真实请求	状态与内容条件同时通过才是 reproduced
Solver	导出 Contract、Recipe 与独立入口	浏览器关闭后仍能重新生成并验证

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

三种证据等级

等级	含义
observed	来自 Browser Oracle 的真实观察，可用于定位和建立 Contract
replayed	使用已捕获值或响应重放，只能用于诊断和对照
reproduced	独立 Node 运行时重新生成目标输出，并通过真实请求验证

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

阶段	核心任务	主要产物
intake	明确目标请求、触发路径和交付要求	结构化目标与输出类型
evidence	在真实页面复现请求并读取完整响应	Browser Oracle 证据
locate	沿 Initiator、调用栈和源码定位写入边界	参数来源与关键 Artifact
recover	还原桥接合约和影响输出的关键算子	Output Contract
runtime	找到浏览器与独立运行时的首次分歧	Runtime Recipe
extraction	Agent 按 blocker 使用 Hook、Debugger 与 Code Mode 分离算法和环境语义	Worker 结果或手工局部算法实现
validation	用生成值完成真实请求	reproduced Validation Artifact
handoff	固化身份、入口和运行说明	Solver 或直接请求模块

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，不会建立第二套对话状态。

使用方式

命令	用途
deepspider agent [--port <number>] [--verbose]	启动原生 DSH Web 和 Spider Preset
deepspider mcp	启动 stdio MCP 外部适配器
deepspider fetch <url>	通过 CycleTLS 发起一次轻量 HTTP 请求
deepspider update	检查并更新全局安装
deepspider --version	显示版本
deepspider --help	显示帮助

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

工具目录

工具组	能力
Browser	页面操作、标签页与 iframe、截图、DOM、存储、控制台、Dialog
Network	请求、响应、Initiator、WebSocket
Script	脚本列表、完整源码读取、跨脚本搜索
Debugger	断点、调用栈、单步、求值与 logpoint
Hook	显式注入与运行时日志查询
Stealth	反调试拦截控制
Capture	浏览器环境、属性描述符、原型与函数事实
Recovery	recover_target_output 的 Cookie 独立生成、真实请求验证和 Solver 导出；其他输出保留证据与 Contract

工具数量由中央 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.21.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