# https://github.com/ryenwang/pire-browser 项目说明书

生成时间：2026-07-05 11:54:55 UTC

## 目录

- [系统架构与核心组件](#page-1)
- [浏览器自动化与命令参考](#page-2)
- [AI 代理集成与 MCP](#page-3)
- [部署、构建与运维](#page-4)

<a id='page-1'></a>

## 系统架构与核心组件

### 相关页面

相关主题：[浏览器自动化与命令参考](#page-2), [部署、构建与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ryenwang/pire-browser/blob/main/README.md)
- [docs/architecture.md](https://github.com/ryenwang/pire-browser/blob/main/docs/architecture.md)
- [cli/pire-browser-core/src/lib.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/lib.rs)
- [cli/pire-browser-core/src/protocol.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/protocol.rs)
- [cli/pire-browser-core/src/ipc.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/ipc.rs)
- [cli/pire-browser-core/src/native.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/native.rs)
</details>

# 系统架构与核心组件

## 概述

pire-browser 是一个采用 Rust 语言实现的模块化浏览器项目，整体采用分层架构，将 CLI 前端、核心逻辑、通信协议与原生系统调用解耦，以提升可维护性与可扩展性。项目顶层通过 `cli/pire-browser-core` 提供统一入口，底层则通过标准化的进程间通信与原生绑定层接入宿主操作系统能力。资料来源：[README.md:1-40]() [docs/architecture.md:1-60]()

## 总体架构

项目遵循"核心库 + 命令行外壳"的经典 Rust 工程布局。`pire-browser-core` 作为可复用的核心 crate，对外暴露稳定的 API；其内部又细分为协议抽象、IPC 通道与原生集成三个子模块。CLI 工具通过调用 `lib.rs` 中的入口函数组装各子模块能力，向用户提供浏览器控制能力。

```mermaid
flowchart TB
    A[CLI 入口] --> B[lib.rs 核心库]
    B --> C[protocol.rs 协议层]
    B --> D[ipc.rs 进程间通信]
    B --> E[native.rs 原生绑定]
    C --> D
    D --> E
```

## 核心模块（lib.rs）

`lib.rs` 是整个 `pire-browser-core` 的中枢，负责将协议解析、IPC 通道管理与原生调用统一编排。该模块通常承担以下职责：

- 定义对外暴露的公共 API 与错误类型；
- 协调各子模块的初始化顺序与生命周期；
- 在命令与事件之间建立调度管线。

通过将核心逻辑收敛到 `lib.rs`，CLI 层与未来可能出现的 GUI、SDK 等其他前端可以共享同一套底层能力，避免重复实现。资料来源：[cli/pire-browser-core/src/lib.rs:1-120]()

## 协议层（protocol.rs）

`protocol.rs` 定义了浏览器内部以及浏览器与外部进程之间传输的消息格式。该层通常包含：

- 命令与响应的枚举定义；
- 事件订阅与发布的序列化规范；
- 版本号、能力协商等握手字段。

将协议独立成模块的目的，是让上层调度逻辑与具体字节布局解耦。当未来需要升级协议版本或新增消息类型时，仅需修改 `protocol.rs` 而不影响 IPC 与原生层。资料来源：[cli/pire-browser-core/src/protocol.rs:1-150]()

## 进程间通信层（ipc.rs）

浏览器天然需要多进程协作，例如渲染进程、扩展进程与控制进程之间的隔离。`ipc.rs` 封装了底层传输细节，提供：

- 跨进程消息发送与接收的异步通道；
- 基于 `protocol.rs` 消息结构的编解码适配；
- 通道断开、重连与错误传播的兜底逻辑。

该层是连接协议定义与实际进程边界的桥梁，其稳定性直接决定多进程模型能否可靠运行。资料来源：[cli/pire-browser-core/src/ipc.rs:1-180]()

## 原生集成层（native.rs）

`native.rs` 承担与操作系统交互的职责，封装平台相关的窗口管理、网络栈调用、文件系统访问等能力。其设计原则是：

- 将所有 `unsafe` 与平台特性收敛到单一模块；
- 通过安全的 Rust 接口向上层暴露平台能力；
- 隔离不同操作系统之间的实现差异。

通过这一层，上层业务逻辑可以保持平台无关，从而便于跨平台编译与测试。资料来源：[cli/pire-browser-core/src/native.rs:1-200]()

## 模块协作关系

四个子模块构成自上而下的依赖链：CLI 调用 `lib.rs`，`lib.rs` 同时引用 `protocol`、`ipc`、`native` 三个模块；`protocol` 为 `ipc` 提供消息结构；`ipc` 又通过 `native` 获取必要的系统调用支持。这种分层确保每一层只依赖其下方的能力集合，便于单元测试与替换实现。资料来源：[docs/architecture.md:60-140]()

---

<a id='page-2'></a>

## 浏览器自动化与命令参考

### 相关页面

相关主题：[系统架构与核心组件](#page-1), [AI 代理集成与 MCP](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ryenwang/pire-browser/blob/main/README.md)
- [cli/pire-browser-core/src/cli.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/cli.rs)
- [cli/pire-browser-core/src/session.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/session.rs)
- [cli/pire-browser-core/src/download.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/download.rs)
- [cli/pire-browser-core/src/upload.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/upload.rs)
- [cli/pire-browser-core/src/transfer.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/transfer.rs)
</details>

# 浏览器自动化与命令参考

`pire-browser` 是一个面向终端用户的浏览器自动化命令行工具，通过 Rust 编写的 `pire-browser-core` 模块暴露可被 Shell 脚本与 AI Agent 复用的浏览器操作原语。本页整理其命令体系、会话模型以及文件/数据流相关子系统的结构。 资料来源：[README.md:1-40]()

## 一、CLI 入口与命令分层

### 1. 命令解析入口
`cli.rs` 负责使用 `clap`/`structopt` 风格定义顶级命令动词（例如 `open`、`click`、`screenshot`、`eval`、`download`、`upload`、`transfer` 等），并将其路由到对应的子模块处理函数。CLI 选项层面通常会暴露持久化参数（如 `--session`、`--timeout`、`--profile-dir`），以控制调用 `session.rs` 中的会话生命周期。 资料来源：[cli/pire-browser-core/src/cli.rs:1-120]()

### 2. 子命令职责划分
项目按照职责将实现拆分到独立文件，便于以模块为单位扩展：

| 模块文件 | 职责概要 |
| --- | --- |
| `session.rs` | 启动/复用浏览器进程、维护 WebSocket/CDP 连接、句柄池与状态机 |
| `download.rs` | 监听浏览器 `Page.downloadWillBegin`/`downloadProgress` 事件，将文件落地 |
| `upload.rs` | 通过 `Page.setFileChooserFiles` 等协议通道注入本地文件 |
| `transfer.rs` | 文件/字节流在 CLI 进程与浏览器执行环境之间的双向转发 |

资料来源：[cli/pire-browser-core/src/session.rs:1-80]() | [cli/pire-browser-core/src/download.rs:1-60]()

## 二、会话模型与浏览器生命周期

`session.rs` 中的会话是所有命令运行时的容器。一次会话对应一个长期存活的浏览器上下文（含若干 `Page`），用于在多次 CLI 调用间复用 Cookie、LocalStorage 与已渲染的 DOM，避免重复冷启动。其典型工作流见下图。

```mermaid
flowchart LR
    A[CLI 调用] --> B{会话存在?}
    B -- 否 --> C[启动 Chromium/Firefox]
    C --> D[创建 Context 与 Page]
    D --> E[注册事件监听]
    B -- 是 --> F[复用现有句柄]
    E --> G[执行命令]
    F --> G
    G --> H[返回结构化结果]
```

会话层还会持有下载目录、上传白名单、代理配置等共享上下文，并负责在空闲超时或显式 `close` 时优雅终止进程。 资料来源：[cli/pire-browser-core/src/session.rs:80-180]()

## 三、下载、上传与传输子系统

### 1. 下载流程
`download.rs` 实现"等待触发 → 接受路径建议 → 持久化 → 回报完成事件"的完整闭环。其核心依赖会话层注入的下载事件回调，命令返回时通常附带 `suggestedFilename`、`savedPath`、`state` 字段。 资料来源：[cli/pire-browser-core/src/download.rs:60-150]()

### 2. 上传流程
`upload.rs` 在检测到 `<input type="file">` 或拖放区激活后，将本地路径列表通过受信任通道注入到当前 Page。它常与 `eval` 命令配合，用于在表单自动化前主动打开文件选择器。 资料来源：[cli/pire-browser-core/src/upload.rs:1-120]()

### 3. 双向传输
`transfer.rs` 抽象出通用的"字节流方向传输"模型，使下载/上传可以共享同一组错误处理、重试与进度上报逻辑，避免在两个模块中重复实现。 资料来源：[cli/pire-browser-core/src/transfer.rs:1-100]()

## 四、与外部 Agent/脚本的集成约定

CLI 的标准输出被设计为可被 shell 管道稳定解析的 JSON 行（NDJSON）格式，错误以非零退出码表达，便于在 Python、Node 或 LLM Agent 工具链中作为"工具函数"直接调用。`README.md` 通常会给出端到端的 `open → click → upload → submit` 最小示例，体现"一次安装、跨脚本复用同一会话"的设计目标。 资料来源：[README.md:40-120]()

## 五、使用建议

- 将耗时任务放在同一会话内连续执行，复用已加载页面以降低延迟。 资料来源：[cli/pire-browser-core/src/session.rs:120-180]()
- 下载/上传路径建议使用绝对路径，并由 `transfer.rs` 中的归一化函数统一处理。 资料来源：[cli/pire-browser-core/src/transfer.rs:60-120]()
- 在自动化脚本中始终通过退出码判断执行结果，将 stdout 的 JSON 留作用户侧可读的详细输出。 资料来源：[cli/pire-browser-core/src/cli.rs:120-200]()

---

<a id='page-3'></a>

## AI 代理集成与 MCP

### 相关页面

相关主题：[系统架构与核心组件](#page-1), [浏览器自动化与命令参考](#page-2), [部署、构建与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cli/pire-browser-cli/src/mcp.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-cli/src/mcp.rs)
- [cli/pire-browser-core/src/skills.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/skills.rs)
- [cli/pire-browser-core/src/auth_vault.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/auth_vault.rs)
- [cli/pire-browser-core/src/auth_handoff.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/auth_handoff.rs)
- [cli/pire-browser-core/src/session.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/session.rs)
- [cli/pire-browser-core/src/state_policy.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/state_policy.rs)
</details>

# AI 代理集成与 MCP

## 概述

pire-browser 通过 MCP（Model Context Protocol，模型上下文协议）把浏览器自动化能力以"工具 + 资源"的形式暴露给外部 AI 代理（例如 Claude、Cursor 或本地 LLM 代理）。CLI 进程启动时加载已注册技能并向 MCP 客户端通告清单；当代理发起 `tools/call` 时，浏览器侧会在隔离会话中执行对应动作，再由策略引擎限制可访问的状态范围 资料来源：[cli/pire-browser-cli/src/mcp.rs:1-80]()。

整套集成可分为四层：**协议接入、技能执行、认证治理、状态策略**，它们各自关注"如何通信""做什么""以谁身份""被允许到什么程度"。

## 协议接入层

`mcp.rs` 搭建一个 stdio 或 TCP 模式的 MCP 服务器，负责 JSON-RPC 方法分发、心跳保活和能力声明（capabilities）。它把收到的 `tools/call` 反序列化为内部指令并转发到核心库，然后把执行结果封装成结构化的 `ToolResult` 返回，从而让代理能直接解析页面快照、错误定位和重试信息 资料来源：[cli/pire-browser-cli/src/mcp.rs:40-160]()。这一层不关心浏览器内部实现，只负责把外部协议请求翻译成统一的事件流。

## 技能执行层

技能（skill）是浏览器对 AI 代理暴露的最小动作单元，例如 `navigate`、`click`、`extract_text`、`screenshot`、`fill_form` 等。`skills.rs` 通过 trait 抽象统一签名 `invoke(ctx, args) -> Result`，并在模块初始化时由 `inventory` 风格的宏收集到全局注册表 资料来源：[cli/pire-browser-core/src/skills.rs:20-95]()。调用前，技能读取会话上下文中的目标标签页、URL 白名单、Cookie 域等，确保每一次动作都落在受控范围内 资料来源：[cli/pire-browser-core/src/skills.rs:100-180]()。技能还会在返回结果中附带语义化标签，便于代理在多步任务中串联调用。

## 认证与会话隔离

AI 代理执行登录、支付等敏感动作时，必须在不接触明文口令的前提下复用人类已登录的凭证。`auth_vault.rs` 封装系统 Keyring，仅对通过策略校验的技能返回令牌句柄，并避免在日志或内存中泄露原文 资料来源：[cli/pire-browser-core/src/auth_vault.rs:30-90]()。`auth_handoff.rs` 实现"人类登录 → 代理接管"的握手：探测到登录页时把标签页冻结为只读视图，请用户在终端手动输入凭据，成功后再为代理派生临时会话并解密令牌 资料来源：[cli/pire-browser-core/src/auth_handoff.rs:45-130]()。`session.rs` 为每条代理调用维护独立的标签页句柄、网络监听、上下文存储和 Cookie jar，确保不同代理或同代理多次调用之间互不串扰 资料来源：[cli/pire-browser-core/src/session.rs:25-85]()。

## 状态访问策略

为防止 AI 代理误删书签、读取隐私历史或写坏持久化数据，`state_policy.rs` 在技能执行前按"作用域 × 操作"的二维矩阵校验。可配置维度包括 URL 前缀、标签页 ID、会话身份以及动作类型（读 / 写 / 破坏性）；命中违规则立刻返回 `PolicyViolation`，既不会写入任何浏览器状态，也不会把数据回传给代理 资料来源：[cli/pire-browser-core/src/state_policy.rs:15-110]()。会话结束或代理断开连接后，引擎会回收临时资源，并清除代理本次写入的缓存与本地存储条目 资料来源：[cli/pire-browser-core/src/state_policy.rs:120-180]()。

## 端到端调用流程

下面以一次 `browser_navigate` 调用为例，展示代理、MCP 服务器、技能模块、策略引擎与浏览器内核之间的协作顺序：

```mermaid
sequenceDiagram
    participant Agent as AI 代理
    participant MCP as MCP 服务器
    participant Skill as 技能模块
    participant Policy as 策略引擎
    participant Browser as 浏览器内核

    Agent->>MCP: tools/call browser_navigate(url)
    MCP->>Skill: 反序列化为 NavigateSkill::invoke
    Skill->>Policy: 检查 URL / 标签页 / 会话作用域
    Policy-->>Skill: 允许
    Skill->>Browser: 在隔离标签页中打开 URL
    Browser-->>Skill: 返回 DOM 快照与可访问性树
    Skill-->>MCP: ToolResult(snapshot, status)
    MCP-->>Agent: JSON-RPC 响应
```

资料来源：[cli/pire-browser-cli/src/mcp.rs:160-220]()。

## 小结

通过协议层、技能层、认证会话层与策略层的协同，pire-browser 为 AI 代理构建了一条受控、可审计的浏览器操作通道：**协议层负责互联互通，技能层封装原子动作，认证与会话层隔离身份，策略层兜底安全边界**。这种分层设计让新的 AI 工具可以在不修改浏览器内部的前提下接入，而安全策略和审计口径则集中在策略引擎一处维护。

---

<a id='page-4'></a>

## 部署、构建与运维

### 相关页面

相关主题：[系统架构与核心组件](#page-1), [AI 代理集成与 MCP](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ryenwang/pire-browser/blob/main/README.md)
- [cli/pire-browser-core/src/setup.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/setup.rs)
- [cli/pire-browser-core/src/launch.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/launch.rs)
- [cli/pire-browser-core/src/platform.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/platform.rs)
- [cli/pire-browser-core/src/install_status.rs](https://github.com/ryenwang/pire-browser/blob/main/cli/pire-browser-core/src/install_status.rs)
- [cli/Cargo.toml](https://github.com/ryenwang/pire-browser/blob/main/cli/Cargo.toml)
</details>

# 部署、构建与运维

pire-browser 的"部署、构建与运维"主题聚焦于 CLI 工具链 `pire-browser-core` 的发布形态、跨平台安装检测以及浏览器进程的生命周期管理。仓库将所有相关逻辑集中在 `cli/pire-browser-core/src` 子模块下，通过 `cli/Cargo.toml` 描述元信息与依赖，使构建、初始安装、状态查询与启动流程形成闭环。

## 构建产物与项目元信息

`cli/Cargo.toml` 定义了二进制 crate 的发布形态，包含包名、版本、作者、许可证、描述以及 Rust 依赖项，是 CI 与本地 `cargo build` / `cargo install` 的事实来源。README 中通常会引用该清单中的版本号来同步文档与发布说明。资料来源：[cli/Cargo.toml:1-40]()。

构建流程遵循标准 Rust 工作流：

1. 在 `cli/` 目录下执行 `cargo build --release`，产物位于 `target/release/pire-browser`。
2. 通过 `cargo install --path .` 可将二进制安装到 `~/.cargo/bin`，供全局调用。
3. CI 通常使用跨平台目标矩阵（`x86_64-unknown-linux-gnu`、`aarch64-apple-darwin`、`x86_64-pc-windows-msvc` 等）分别编译，README 中会列出已验证平台。

## 安装状态机与平台抽象

模块 `install_status.rs` 负责把"浏览器是否已就绪"抽象为枚举或状态码，避免上层业务重复探测文件路径。`platform.rs` 进一步封装了 OS 差异（macOS、Linux、Windows），包括默认安装目录、用户数据目录以及权限模型。两者协作后，`setup.rs` 在第一次运行 CLI 时根据当前平台执行一次性安装或修补。

典型状态流转如下表所示：

| 状态 | 含义 | 后续动作 |
|------|------|----------|
| `NotInstalled` | 浏览器二进制或运行时缺失 | 调用 `setup.rs` 走安装分支 |
| `Outdated` | 已安装但版本低于 `cli/Cargo.toml` 声明的最低要求 | 触发升级 |
| `Ready` | 满足启动条件 | 直接进入 `launch.rs` |
| `Corrupted` | 安装存在但校验失败 | 卸载后重装 |

资料来源：[cli/pire-browser-core/src/install_status.rs:1-80]()、[cli/pire-browser-core/src/platform.rs:1-120]()。

## 启动与进程生命周期

`launch.rs` 是运行时入口，它读取 `install_status` 的结果，决定是直接拉起浏览器进程，还是先回退到 `setup.rs` 完成准备工作。启动阶段还会处理进程句柄、日志路径、用户配置注入与优雅退出信号。平台差异由 `platform.rs` 提供的 trait/函数屏蔽，使 `launch.rs` 主体保持平台无关。资料来源：[cli/pire-browser-core/src/launch.rs:1-150]()。

## 运维要点

运维层面的关键点包括：

- **幂等安装**：`setup.rs` 在每次启动前都会重新检查状态，确保多次调用安全。
- **可观测性**：`launch.rs` 将 PID、退出码与平台标识写入日志，便于排障。
- **跨平台一致性**：`platform.rs` 集中处理路径分隔符、默认浏览器名与权限提升请求。
- **升级路径**：当 `cli/Cargo.toml` 提升最低浏览器版本时，`install_status.rs` 自动检测并触发 `setup.rs` 的升级流程。

资料来源：[README.md:1-200]()、[cli/pire-browser-core/src/setup.rs:1-200]()。

通过上述分层，pire-browser 把"构建配置 → 安装检测 → 平台适配 → 进程启动"四个职责解耦，使维护者可以独立演进每一层而无需改动调用方。

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：ryenwang/pire-browser

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/ryenwang/pire-browser | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/ryenwang/pire-browser | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/ryenwang/pire-browser | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/ryenwang/pire-browser | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/ryenwang/pire-browser | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/ryenwang/pire-browser | release_recency=unknown

<!-- canonical_name: ryenwang/pire-browser; human_manual_source: deepwiki_human_wiki -->