# DeepSpider

[![npm version](https://img.shields.io/npm/v/deepspider.svg)](https://www.npmjs.com/package/deepspider)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

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

[English](README_EN.md)

## 快速开始

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

```bash
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 日志或仅能回放的请求都不是完成证据。

## 输出驱动的语义恢复

```text
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`。

## 一个恢复入口

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

```text
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 手工恢复影响目标输出的局部逻辑，或等待后续算法引擎实现；系统不会把未实现的升级描述成自动完成。

## 八阶段逆向工作流

```text
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

```text
~/.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/` 下生成四个文件：

```text
solver.mjs
contract.json
recipe.json
package.json
```

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

```bash
npm install
node solver.mjs
```

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

## 架构

```text
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`。

```bash
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