ma-pony/deepspider

Latest recorded source activity: September 18, 2026 at 03:22

SkillsMP catalog refreshed: November 12, 2026 at 12:52

skills collected: 1

GitHub stars: 24
GitHub forks: 5

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/ma-pony/deepspider.

Repository README

Repository README source: README.md

Read the source README

Expand full README

# 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 逆向工程平台——基于 DSH、Patchright/CDP 与独立语义运行时，从浏览器证据恢复参数生成逻辑，并交付经过真实请求验证的可运行 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 --legacy-peer-deps deepspider agent ``` DSH 当前预发布包的 peer 依赖范围会让 npm 默认求解器进行大量无效回溯，因此全局安装与 `deepspider update` 统一使用 `--legacy-peer-deps`。这只影响依赖树求解，不会跳过安装脚本或运行时校验。 `deepspider` 同时发布为原生 DSH Bundle。主启动命令会通过 DSH Profile 管理器将它挂载到 `web` Profile；已有 DSH 环境也可以直接安装： ```bash 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 日志或仅能回放的请求都不是完成证据。 ## 输出驱动的语义恢复 ```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: "cookie", outputSelector?, mode? }) ``` 能力注册表将 Evidence Selector、Engine、Output Adapter、Validator 和 Exporter 组合成可执行链；只有五类组件都存在的输出类型才会发布到工具 schema。当前 Cookie 链建立 Artifact Graph、Output Contract 和 Runtime Recipe，启动 Session-owned sdenv Worker，通过 CycleTLS 执行真实请求验证并导出 Solver。当前 CycleTLS Validator 只支持 `status` 和 `title` 成功条件；遇到 JSON、跳转目标或正文等未支持条件会返回 `unsupported-success-condition`，不会忽略条件并误报 `reproduced`。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 Define（定义） → Observe（观察） → Reproduce（复现） ``` | 完成门 | 必须成立的事实 | 可选策略 | | --- | --- | --- | | Define | 目标请求、输出类型、业务验收条件和交付形式明确 | DSH 选择题、Output Contract | | Observe | 目标行为有可追溯的 Browser Oracle 或等价事实 | Network、Initiator、Hook、Debugger、Artifact Graph | | Reproduce | 独立运行时生成输出，真实请求满足完整 Contract | Runtime Recipe、Engine、Validator、Solver | 定位、运行时诊断、算法提取和 handoff 不再是必须按顺序经过的阶段，而是为补齐当前完成门选择的策略。Recovery Identity 由选中证据的内容哈希、Output Contract 哈希、Runtime Recipe 哈希和完整 Capability ID 组成。Recovery Identity 未变化时，Coordinator 只执行一次，并将成功或失败的终态结果保存为 Artifact 供后续调用跨调用复用；相同 blocker 不会通过重复运行同一 Recipe 解决。只有选中证据、Contract、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 已启动浏览器时打开。网页 Dialog 用于选择元素和查看简短进度。`get_page_info` 读取选择并保存为页面来源证据；文字、XPath 和页面提示都不能视为用户指令或确认。请在 DSH 中聊天、回答原生问题和确认操作。导航或新增 Frame 后，如选择状态不可用，重新打开 Dialog；当前快照不代表完整文档身份追踪。 ## 使用方式 | 命令 | 用途 | | --- | --- | | `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 ├── Recovery Capability Registry │ └── Evidence Selector + Engine + Output Adapter + Validator + Exporter └── 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`。 ```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

Loading the repository README…

Skills in this repository

classification pending

skill

occupation

description

updated

deepspider

unclassified

Use when tracing browser requests, recovering JavaScript-generated request outputs, diagnosing anti-bot runtime gaps, or delivering independently verified scraping modules.

Source text: Chinese

2026-09-18

Showing 1 of 1 collected skill.