KuiChi-x/reverseloom

## 💡 一句话简介 大多数浏览器 Agent 只向模型提供“一张屏幕截图 + 可点击元素”，因此它们只能停留在“帮我点击这个按钮”的层面。 **reverseloom 使用 observer 架构向模型完全开放浏览器** —— DOM、屏幕截图、每一个网络请求，甚至是实时的 JS 调试器状态，全部作为“浏览器当前状态”注入。这让它能完成两项工作： - 🤖 **作为浏览器 Agent**：导航、点击、填写表单、破解验证码、跨标签页工作、抓取数据 —— 常规操作，表现出色。 - 🔬 **作为逆向工程师**：当数据受到签名 / token / 加密请求体保护时，它会设置 CDP 断点，一路追溯到生成器，将其拖入 Node 沙盒中进行离线复现，并最终交付一个**无需浏览器即可冷启动运行**的爬虫。 从“我能抓取我能看到的内容”升级到“我能逆向我看不见的内容”。这就是将*整个*浏览器暴露给模型的回报。 ## 🧱 抓取面临三堵墙。reverseloom 在一个技术栈内突破所有屏障。 任何构建过爬虫的人都知道你和数据之间隔着三堵墙。大多数工具只能跨越其中一堵。reverseloom 将这三堵墙融合成**单一流水线**： | | 面临的墙 | 常用方式 | reverseloom 的一站式解决方案 | |---|---|---|---| | 🧱 **第一堵墙** | **进不去** —— 网站检测到自动化浏览器并阻止了你 | 手动修补指纹或使用付费云服务，依然会泄露 `navigator.webdriver` 和 CDP 痕迹 | 搭配 [**kc-browser**](https://github.com/KuiChi-x/kc-browser)：一款 **C++ 内核级**反检测指纹浏览器 —— 身份从引擎内部原生构建，没有可被识破的注入脚本，**任何网站都让你进入** | | 🧱 **第二堵墙** | **无法逆向** —— 数据受到签名 / token / 加密请求体保护 | 手动阅读混淆过的 JS，每个算法耗费一整天 | **全面暴露 + CDP 断点**：模型自行设置断点，追溯生成器，将其拖入 Node 沙盒离线复现 —— 直到 5/5 冷启动重放通过才算完成 | | 🧱 **第三堵墙** | **无法运行** —— 爬虫仍需挂载浏览器，既慢又脆弱 | 永久驻留无头浏览器，每次更新都会出错 | 交付一份**免浏览器、可直接冷启动**的纯代码爬虫蓝图 | **这就是它的核心价值**：其他工具在一堵墙前止步；reverseloom 则将“进入 -> 逆向 -> 交付独立爬虫”焊接成一条完整的链条。而针对第一堵墙的终极解决方案是它的兄弟项目，**[kc-browser](https://github.com/KuiChi-x/kc-browser)** —— 参见 [全部能力](#full-power)。 ## ✨ 亮点 - 🔬 **真正的逆向工程** —— 不仅仅是读取 DOM。运行时断点调试（`set_line_breakpoint` / `break_on_request` / `evaluate_in_call_frame` / `step_execution`）、网络请求追踪、webpack 模块提取 —— 从混淆代码中提取出签名/token/加密算法。 - 🧪 **离线沙盒复现** —— 将转储出的生成器丢进内置的 Node + jsdom 沙盒（反检测装甲 + 深度 Proxy 监控）中，无需真实浏览器即可复现算法。交付要求通过 5/5 的冷启动重放。 - 🖥️ **桌面端，零配置** —— `python -m reverseloom` 打开原生窗口（纯 Python，无需 Rust/Node 工具链）。自动检测您安装的 Chrome / Edge / Chromium / Brave。**不会下载或捆绑 Chromium。** - 🧠 **observer 架构，上下文永不膨胀** —— 每一轮只注入*当前*的浏览器快照（覆盖，绝不写入历史），因此长期的逆向工程会话绝不会让上下文窗口被大量屏幕截图淹没。 - 🛠️ **30+ 工具 + 渐进式技能** —— 浏览器自动化、CDP 逆向工程、多模态视觉定位、文件/shell。`web-crawl` / `deep-reverse` 技能按需加载，不会污染上下文。 - 🔌 **支持任何 OpenAI 兼容模型** —— GPT / Claude / Gemini / DeepSeek / OpenRouter / Ollama……只需一行配置即可切换。 - 🥷 **反检测 + 拟人化 + 隔离** —— 利用 [kc-browser](https://github.com/KuiChi-x/kc-browser) 的内核级指纹触达任何网站；WindMouse 拟人化路径应对滑块验证码；每个会话都有专属的指纹、配置文件和可选的带 IP 轮换的授权代理隧道。 - 🔒 **完全本地化** —— API 密钥、cookie、输出和历史记录全部保留在您的机器上。没有云端往返。 ## 🆚 与普通浏览器 Agent 的区别 | | 普通浏览器 Agent | **reverseloom** | |---|---|---| | 模型所见 | 仅限屏幕截图 + 可点击元素 | ✅ **全面暴露**：DOM + 截图 + 网络 + JS 调试器 | | 交互 | 点击 / 输入 / 抓取可见文本 | ✅ 以上所有 **+ CDP 调试 + 网络追踪** | | 签名/加密参数 | 卡住或产生幻觉 | ✅ 追溯生成器 -> 在沙盒中复现 | | 上下文管理 | 截图/DOM堆积在历史记录中，极易迅速膨胀 | ✅ observer 覆盖注入；历史记录仅保留推理 | | 交付物 | 一次性操作结果 | ✅ 可直接冷启动的**爬虫蓝图**，免浏览器 | | 浏览器 | 通常需手动启动，需下载 Chromium | ✅ 自动启动系统浏览器，零下载 | | 运行方式 | 多为云端 SaaS | ✅ 完全本地化，数据不外传 | ## 🚀 快速开始 两种方式 —— 任选其一。首先，列出切实的前提条件，以免安装后出现隐式失败： ### 方式 A：下载 EXE 并运行（Windows，建议先尝试此项） 无需 Python，无需环境配置。 1. 从 [**Releases**](https://github.com/KuiChi-x/reverseloom/releases) 获取最新的 `reverseloom-win.exe`； 2. 双击 —— 将打开一个原生桌面窗口； 3. 在 **Settings -> Model** 中填入您模型的 `BASE_URL` / `API Key` / `MODEL`（参见 [配置说明](#configure)）并保存。 ### 方式 B：从源码运行（开发者 / macOS / Linux） reverseloom 依赖于 [graphloom](https://github.com/KuiChi-x/graphloom)： ``` # 1. Clone git clone https://github.com/KuiChi-x/reverseloom.git cd reverseloom # 2. Install (graphloom 尚未在 PyPI 上 — 从源码安装) pip install "graphloom @ git+https://github.com/KuiChi-x/graphloom.git" pip install -e . pip install patchright # browser driver — no `patchright install chromium` needed # 3. Configure the model (将 .env.example 复制到 .env) # BASE_URL / OPENAI_API_KEY / MODEL — 或者在启动后在 UI 的 Settings 中设置它们 # 4. Run python -m reverseloom # native desktop window (Win / Mac / Linux) python -m reverseloom --web # or: serve only, open in your system browser ``` 沙盒引擎以预构建的 `reverseloom-sandbox.bundle.js` 形式提供 —— **开箱即用**。若要重新构建：在 `src/reverseloom/browser/sandbox_env/` 中运行 `npm install && npm run build`。 ### 配置说明 最小化的 `.env`： ``` MODEL_PROTOCOL=openai # openai / anthropic / gemini / deepseek / ollama ... BASE_URL=https://api.openai.com/v1 OPENAI_API_KEY=sk-... MODEL=gpt-4o MODEL_REASONING_EFFORT= # empty = model decides, or low / medium / high ``` 浏览器和代理（可选，也可在 UI 的 Settings 中编辑）： | 环境变量 | 用途 | |---|---| | `REVERSELOOM_BROWSER_PATH` | 基于 Chromium 的浏览器路径。留空则自动检测：在 Windows/macOS/Linux 上按顺序扫描 Chrome -> Edge -> Chromium -> Brave 的标准安装位置。仅当您的浏览器位于非标准位置，或需要强制指定特定版本（例如 kc-browser）时才设置此项。如果未找到且未设置此项，启动将失败并提示您安装一个或设置此变量 —— reverseloom 绝不会下载浏览器。 | | `REVERSELOOM_PROXY_HOST` / `_PORT` / `_USERNAME` / `_PASSWORD` | 可选的上游代理；认证由本地隧道注入，不会直接交给 Chromium | ## 🛠️ 功能特性（30+ 工具） 浏览器自动化和 JS 逆向工程是两大核心支柱；视觉定位、文件/shell 和渐进式技能作为辅助。

🌐 浏览器自动化（核心）

`browser_navigate` / `browser_click` (通过 ocId 或像素) / `browser_type` / `select_option` / `press_key` / `scroll_page` / `browser_drag` (针对滑块的 WindMouse 拟人化路径) / 标签页 / `browser_evaluate` / `reset_browser_state` (可轮换指纹)

🔬 JS 逆向工程 · CDP（核心）

- **断点调试**：`set_line_breakpoint` / `break_on_request` / `get_paused_state` / `evaluate_in_call_frame` / `step_execution` - **网络分析**：`search_in_network_payloads` / `inspect_network_request` (包含发起方调用栈) - **脚本追踪**：`search_in_js_codes` / `get_script_source` / `dump_runtime_asset` / `extract_webpack_loader`

👁️ 视觉 · 人工辅助（核心）

- `visual_locate` —— 多模态坐标定位（验证码、canvas 组件及其他无法枚举的目标） - `request_user_interaction` —— 统一用于澄清、方案选择、风险确认以及诸如登录/验证码等人工操作；通过 graphloom `interrupt()` 进行中断和恢复

📁 通用工具（辅助） · 🧩 技能（渐进式披露）

- `read_file` / `write_file` / `edit_file` / `list_dir` / `search_code` / `run_shell` —— 相对路径会解析为当前会话的 Artifact 目录 - `web-crawl` —— 自适应采集：对于小量结果直接返回，仅在需要多页/批量/文件处理时生成爬虫 - `deep-reverse` —— 深度协议分析 + 独立重放 + 交付审查，仅在逆向工程任务中加载 - 自定义技能位于 `~/.reverseloom/skills//SKILL.md`，启动时自动发现

## 🧬 工作原理 **为什么用 observer，而不是 MCP？** 按照“工具返回值进入历史记录”的常规方式构建浏览器 Agent 有一个致命缺陷：浏览器状态、DOM 和屏幕截图每一轮都在变化且体积庞大 —— 将它们堆积在历史记录中会使其呈指数级增长，并迅速撑爆上下文窗口。 reverseloom 通过 graphloom 的 **observer 节点**解决了这个问题：在每次决策之前，它会捕获*当前*的浏览器快照（URL / 包含 ocIds DOM 摘要 / 调试器状态 / 屏幕截图），并将其仅作为该轮的“最新状态”注入 —— **绝不写入 `past_steps`，绝不写入记忆**。Agent 始终看到的是“浏览器当前的状态”；历史记录只保留它的推理和动作，而不是一堆陈旧的屏幕截图。 ``` ┌───────────────────────────── graphloom ─────────────────────────────┐ │ agent loop · short-term memory · context compaction · observer · skills │ └───────────────────────────────────┬────────────────────────────────────┘ │ reverseloom contributes ↓ ┌──────────────┬───────────────┼───────────────┬──────────────┐ browser mgmt tool groups system prompt web shell Node sandbox (patchright+CDP) (automation/ (reverse review) (FastAPI+WS) (jsdom repro) reverse/vision/ file) ``` **浏览器层**：patchright（一个反检测 Playwright 分支）自动启动您的系统 Chromium。`launch_persistent_context` 为每个会话提供独立的配置文件，注入指纹启动参数（`--fp-seed` / `--fp-timezone` / `--fp-platform`），可选择附加本地授权代理隧道，并为每个页面提供独立的 CDP 处理程序，以实现无损的网络捕获和 JS 调试。 **沙盒层**：获取从页面转储的签名/token/加密请求体生成器，并在 Node + jsdom 中**离线运行**它。沙盒具有反检测装甲（mark-native / jsdom-hider / chrome-overlay / 指纹覆盖）以及深度 Proxy 监控；向其输入 JSON payload（目标脚本 + 调用代码 + 指纹），它将返回生成的结果、缺失 API 的待办事项列表以及捕获到的网络请求。 ## 🥷 全部能力：搭配 kc-browser 触达任何网站 reverseloom 的第一堵墙 —— **绕过机器人检测** —— 在其兄弟项目 [**kc-browser**](https://github.com/KuiChi-x/kc-browser) 中找到了终极解决方案。 普通的反检测手段在 JS 层“打补丁”：抹除 `navigator.webdriver`，伪造 UA…… 但补丁总会留下可以被剥开的缝隙。**kc-browser 另辟蹊径 —— 它直接修改 Chromium 的 C++ 内核**，因此指纹是自底向上从引擎内部构建的： - 🧬 **内核级伪造，而非外部脚本挂载** —— UA / Client Hints / WebGL / Canvas / Audio / 字体 / 硬件 / 时区全部在引擎内部一致生成；没有可被识破的注入脚本，没有 `navigator.webdriver`，也没有 CDP 痕迹。 - 🌱 **一颗种子 = 一个逻辑自洽的身份** —— 通过 64 位种子确定性地推导出整个指纹；GPU 根据市场份额从约 130 张真实消费级显卡中采样，区域设置/时区与出口 IP 在 95+ 个地区内保持一致。 - 🔄 **无需重启即可轮换身份**，随意呈现为 Windows / macOS / Linux，支持无头或有头模式。 reverseloom 已经原生支持其接口 —— `fingerprint.py` 中的 `--fp-seed` / `--fp-timezone` / `--fp-platform` 参数正是 kc-browser 的标志。**将其指向 kc-browser，任何网站都会向您敞开大门。** 只需在 **Settings -> Browser & proxy tunnel** 下将浏览器可执行文件设置为 kc-browser： 源码用户也可以使用环境变量： ``` # 为 reverseloom 提供可执行文件路径 REVERSELOOM_BROWSER_PATH=/path/to/kc-browser ``` ## 📂 项目布局 ``` src/reverseloom/ __main__.py desktop entry point (pywebview native window) agent/ agent assembly, model adapter, prompts runtime/ config, settings I/O, graph-execution persistence conversation/ session list and message history browser/ browser runtime and management browser_manager process and session lifecycle session_manager pages, contexts, debugger sessions cdp_handler network capture and debugging protocol proxy / fingerprint authenticated proxy tunnel / browser fingerprint observer browser state observation dom/ DOM extraction and serialization sandbox_env/ Node + jsdom sandbox assets tools/ every tool exposed to the agent filesystem file ops, search, shell browser/automation navigation, click, drag, tabs browser/investigation network, source, breakpoint, runtime analysis browser/visual multimodal coordinate location web/ HTTP and WebSocket adapters static/ desktop interface assets ``` ## ⚖️ 合规与责任 reverseloom 是一款用于**研究、测试和授权数据集成**（QA 自动化、对自有网站的安全评估、授权协议集成、逆向工程教育等）的工具。在使用之前，请确保您： - 仅在您**拥有或获得明确授权**的网站上操作； - 遵守目标网站的服务条款、`robots.txt`、当地法律以及数据保护规定； - 了解逆向签名/token、绕过验证码以及使用指纹/代理可能会违反某些网站的规定 —— **风险与责任完全由您自行承担**。 ## 🧩 工具家族 三个项目，一条流水线 —— 进入、逆向、驱动： | 项目 | 层级 | 一句话简介 | |---|---|---| | [**kc-browser**](https://github.com/KuiChi-x/kc-browser) | 🥷 进入 | C++ 内核级反检测指纹浏览器 —— 一颗种子 = 一个逻辑自洽的身份，任何网站都让你进入 | | [**reverseloom**](https://github.com/KuiChi-x/reverseloom) | 🔬 逆向 | observer 全方位暴露 + CDP 逆向工程 + 沙盒复现，交付免浏览器爬虫（本仓库） | | [**graphloom**](https://github.com/KuiChi-x/graphloom) | 🧵 驱动 | 底层 Agent 框架 —— observer 架构、上下文压缩和渐进式技能皆源于此 | ## 📄 许可证 [Apache 2.0](LICENSE) © KuiChi-x

标签：CDP协议, MITM代理, 反爬虫绕过, 大模型Agent, 浏览器自动化, 爬虫框架, 网页逆向, 逆向工具