ruyiPage 框架解读/刨析
ruyiPage 框架解读/刨析
1. 项目定位与核心价值
ruyiPage是下一代 Python Web 自动化过检测框架，专为AI 分析 + 高风控数据采集场景设计。
- 核心技术路线：Firefox + WebDriver BiDi 协议（完全放弃 CDP）。
- 最大亮点：
- 大量原生
isTrusted: true动作链。 - 支持构造多种 JS 事件并附加
ruyi: true标记，让事件更接近真实用户行为。 - 支持直接接管 ADS、比特浏览器等 Firefox 内核指纹浏览器。
- 实战中可稳定通过 Cloudflare 5s 盾、hCaptcha、DataDome、Outlook/Gmail、bet365 等高风控站点。
- 大量原生
一句话总结：它不是追求“跨浏览器万金油”，而是在 Firefox 一条路上把反检测做到极致，更适合需要长时间稳定运行、真实交互的高风控场景。
2. 项目仓库整体结构
ruyipage（仓库根目录） ├── ruyipage/ # ← Python 包核心源码（你截图里的内容） ├── examples/ # 46+ 个教学示例（最推荐的学习资料） ├── quickstart_*.py # 3 个最简上手脚本（强烈建议先跑） ├── tests/ # 测试用例 ├── scripts/ # 辅助脚本 ├── images/ # README 用图 ├── README.md / README_EN.md ├── pyproject.toml └── requirements.txt3. 源码包ruyipage/详细解读（严格按你的截图顺序）
| 顺序 | 模块/文件 | 核心职责 | 学习重点 |
|---|---|---|---|
| 1 | _adapter | BiDi 协议适配器层 | 把原始协议命令/事件翻译成框架内部对象 |
| 2 | _async | 异步 API 实现 | greenlet桥接，实现同步/异步双风格 |
| 3 | _base | 基类与抽象接口 | BasePage、BaseElement等 |
| 4 | _bidi | WebDriver BiDi 协议核心 | WebSocket 连接、命令发送、事件监听（最底层、最重要） |
| 5 | _configs | 配置管理 | FirefoxOptions所有启动参数处理 |
| 6 | _elements | 元素定位与操作 | ele()、eles()、Shadow DOM、iframe、XPath Picker |
| 7 | _functions | 通用函数库 | bezier/windmouse 拟人算法、事件构造、ruyi:true注入 |
| 8 | _pages | FirefoxPage主实现 | 导航、动作链、网络拦截、下载、截图等高层 API |
| 9 | _units | 最小功能单元 | Cookie、下载、事件监听器等小组件 |
| 10 | __init__.py | 包入口 | 对外暴露FirefoxPage、launch()等 |
| 11 | aio.py | 异步快捷入口 | from ruyipage.aio import launch |
| 12 | common.py | 公共常量、枚举 | 全项目共享 |
| 13 | errors.py | 自定义异常 | 更友好的错误提示 |
| 14 | version.py | 版本号 | __version__ |
架构设计特点：采用分层 + 私有模块（下划线前缀），底层协议与高层 API 高度解耦，便于维护和扩展。
4. 安装与快速上手（官方推荐顺序）
pipinstallruyiPage--upgrade# 异步支持pipinstallruyiPage[async]--upgrade最简同步启动：
fromruyipageimportFirefoxPage page=FirefoxPage()page.get("https://www.example.com")print(page.title)page.quit()推荐新手入口：launch()函数（支持大部分常用参数）。
5. 核心竞争力（官方重点强调）
- 真实事件：原生 BiDi +
ruyi: true标记 →isTrusted更真实。 - 拟人行为：内置 bezier + windmouse 鼠标轨迹（
human_move、human_click、human_type）。 - 浏览器接管：
attach已打开的 Firefox / 指纹浏览器（几乎零启动延迟）。 - 指纹配合：
--fpfile+firefox-fingerprintBrowser实现可控指纹。 - 网络控制：完整请求/响应拦截、Mock、数据采集。
- 调试工具：XPath Picker + 动作可视化（
enable_action_visual=True）。
6. 学习路线推荐（最快上手路径）
- 10 分钟入门：跑根目录 3 个
quickstart_*.py - 1 小时基础：
examples/00_quickstart.py→06_screenshot.py - 核心反检测（必看）：
45_js_setter_untrusted_input.py（isTrusted对比）46_human_behavior_showcase.py（拟人行为完整展示）39_attach_exist_browser.py（接管外部浏览器）42_xpath_picker_complex_showcase.py
- 高阶：
37_three_isolated_user_context_tabs.py（user-context 隔离）
7. 配套生态（官方强烈推荐）
- firefox-fingerprintBrowser：指纹浏览器内核
- ruyipage-skill：AI Agent Skill
- ruyipage-js / ruyipage-go：多语言实现
总结：
ruyiPage 是一个专注 Firefox + BiDi + 真实交互的高风控自动化框架。它牺牲了跨浏览器兼容性，换来了更低的检测面和更真实的交互能力。目前在 Python + Firefox 这条赛道上属于窗口期很好的方案。
拓展科普
✅ BiDi vs CDP 全面科普（通俗易懂版）
1. 什么是 CDP（传统方案）
CDP = Chrome DevTools Protocol
- 诞生背景：Chrome 官方提供的调试协议，最初是为了 Chrome DevTools（F12 开发者工具）而生。
- 工作方式：通过 WebSocket 连接 Chrome 的调试端口（9222 等），发送 JSON 命令。
- 目前地位：Selenium、Playwright、Puppeteer 等主流自动化框架最常用的协议。
优点：
- 功能极其强大（几乎能控制 Chrome 的所有内部功能）。
- 生态成熟，文档丰富。
- 支持 Chrome / Edge / 新版 Edge 等 Chromium 内核浏览器。
致命缺点（高风控场景容易被检测）：
- 暴露特征明显：浏览器里能检测到
window.CDP、navigator.webdriver等自动化痕迹。 - 事件不可信：模拟的点击、输入事件
isTrusted大多为false（网站能轻易识别是脚本操作）。 - 协议层指纹：很多风控直接检测是否连接了 CDP。
- 行为不自然：线性鼠标移动、瞬时点击，容易被行为分析模型识别。
2. 什么是 BiDi（新一代方案）
BiDi = WebDriver BiDirectional Protocol（WebDriver 双向协议）
- 诞生背景：W3C 标准组织推出的下一代 Web 自动化协议（2023-2025 年逐渐成熟）。
- 全称：WebDriver Bi-Directional Protocol。
- 核心理念：双向通信—— 浏览器既能接收命令，也能主动推送事件给自动化脚本。
目前支持情况：
- Firefox 原生支持最好（ruyiPage 就是基于此）。
- Chrome / Edge 也在逐步支持（但还不完善）。
3. BiDi vs CDP 详细对比表
| 维度 | CDP (传统) | BiDi (新一代) | 谁更优（高风控场景） |
|---|---|---|---|
| 协议标准 | Chrome 私有协议 | W3C 公开标准 | BiDi 更规范 |
| 浏览器支持 | Chromium 系（Chrome/Edge）最佳 | Firefox 原生最佳，Chrome 逐步支持 | BiDi（Firefox 路线） |
| 事件真实性 | isTrusted大多为 false | 原生支持isTrusted: true | BiDi 完胜 |
| 检测难度 | 极易被检测（CDP 特征明显） | 检测难度大幅提升 | BiDi 完胜 |
| 性能 | 较好 | 更好（双向通信更高效） | BiDi 略胜 |
| 功能完整度 | 目前最完善 | 正在快速追赶（2025-2026 已很强） | CDP 暂时领先 |
| 鼠标/键盘行为 | 模拟痕迹明显 | 支持构造真实 MouseEvent / InputEvent | BiDi 完胜 |
| ruyiPage 特色 | - | 可额外附加ruyi: true标记 | BiDi 专属 |
| 学习难度 | 较低 | 稍高（协议较新） | - |
4. 为什么 ruyiPage 选择 BiDi？
- 规避 CDP 检测：很多风控（Cloudflare、DataDome 等）已把 CDP 作为重要检测特征。
- 事件真实性：BiDi 可以直接构造浏览器原生事件，
isTrusted为 true，极大提升过检测概率。 - 未来趋势：W3C 标准，长期看 CDP 会逐渐被 BiDi 替代。
- Firefox 路线更干净：Firefox 对自动化特征隐藏得比 Chrome 更好。