作者：小檬 XMeng · 墨迹 Moji发布时间：2026-08-17约 11 分钟阅读

MengPaw.Browser 开发文档

独立 APK (Android 浏览器应用), 内置 Playwright 语义命令面, 供 AI Agent 半自动控制。
文档版本: v0.10.1 · 2026-09-10 · 许可: AGPL-3.0-or-later OR LicenseRef-Commercial
本文档分两部分: 第一部分引导 Shell Agent 经 am 桥控制浏览器并开始操作;
第二部分面向开发者, 讲解目录结构与实现。
配套文档: MengPaw_Browser_skills.md(Agent 完整操作手册: 命令面全表/
半自动循环/表单/抓取/排障/Playwright 对照)。

前文引导

MengPaw.Browser 是什么

MengPaw.Browser(包名 com.mengpaw.browser)是一款可被 AI Agent 编程控制的
Android 浏览器 APK: 基于 WebView 的完整浏览器(人可以直接用), 同时内置
Playwright 语义命令面(page.* 22 条 + browser.* 21 条), 经 Termux 式
am 桥(RunCommandService, signature 权限)对外暴露给同签名应用(MengPaw Shell 是其中之一)。

一句话概括: 给人用的浏览器, 也是给 Agent 用的浏览器——Agent 可以像操作
Playwright 一样, 驱动它打开网页、全页截图、坐标点击、填表、提取内容、管理标签页。

为什么需要它

Agent 需要"真实浏览器": 纯 HTTP 抓取拿不到登录后内容 / JS 渲染页面 / 强反爬
页面; 真实浏览器自带会话、Cookie 与 JS 执行环境。
Playwright 语义, 零学习成本: 命令名与参数对齐 LLM 训练语料中最熟悉的
Playwright API, Agent 无需额外学习自定义命令。
独立 APK, 与 Shell 已脱钩: 浏览器是中性的独立项目(独立版本节奏、独立仓库、独立发版);
Shell 经 am 桥控制属于外部使用方行为, 既无需为浏览器写专门插件, 也不影响本项目独立演进。
半自动协作: page.load 一次完成"导航 + 全页分段截图 + 坐标系统", Agent
看图即可坐标点击, 往返少、上下文省。
安全可控: am 桥 signature 权限(仅同签名应用可调)+ 命令面白名单 +
输出路径限制; 9880 桥与开放模式已退役(决策 #7), 第三方接入不再支持。

怎么读本文档

目标: 让 Shell Agent 经 am 桥控制浏览器并开始操作 → 读第一部分快速开始
(§1-4); 连接成功后的完整操作能力由配套文档 MengPaw_Browser_skills.md 传达。
目标: 从源码理解/修改浏览器、做二次开发、接入自己的框架 → 直接跳转
第二部分从源码开始(§5-12), 目录结构与实现细节都在那里。

第一部分快速开始 — Shell Agent 经 am 桥控制浏览器

1. 控制前提

设备已安装 MengPaw.Browser APK(包名 com.mengpaw.browser)与 MengPaw Shell(同签名)
控制通道为 Termux 式 am 桥(RunCommandService), 受 signature 权限
com.mengpaw.permission.RUN_BROWSER_COMMAND 保护——仅同签名应用可调,
第三方 App 调用会被系统拒绝(9880 HTTP 桥与开放模式已退役, 第三方接入不再支持)
Agent 具备两项能力: am 命令执行(唤起浏览器/调命令) / 读取公共目录文件
(查看截图与输出)

2. 两步调用

# ① 唤起浏览器(未运行或被杀时 am 桥不可达, 必须先唤起)
am start -a com.mengpaw.action.OPEN_URL --es url "https://example.com"

# ② 执行浏览器命令: 输出落盘公共目录, Shell 经 agent.read / grep / head / tail 读回
am startservice -n com.mengpaw.browser/.service.RunCommandService \
  --es com.mengpaw.browser.RUN_COMMAND_ARGUMENTS "-c,page.content --head 20" \
  --es com.mengpaw.browser.RUN_COMMAND_OUTPUT /storage/emulated/0/MengPaw/out.txt

浏览器进程被杀后 am 桥不可达, 重新唤起即恢复; 未运行时报
「浏览器未就绪(请先打开 MP 浏览器再调用)」。

3. 安全模型

层	措施
调用方认证	am 桥 signature 权限 `RUN_BROWSER_COMMAND`, 仅同签名应用可调
命令面	am 桥 payload 白名单 `page.`/`browser.`, 拒绝任意 shell 命令
输出路径	输出文件限制在公共目录 `MengPaw/` 下, 禁止系统路径
存储	`MANAGE_EXTERNAL_STORAGE`, 首启弹窗; 拒绝后每次 `page.load` 提示重授

4. 连接成功后的操作

连接建立后, 浏览器的全部操作能力(43 条命令全表 / 半自动循环 / 表单自动化 /
网页抓取 / 排障速查 / Playwright 对照)由配套文档
MengPaw_Browser_skills.md 传达, 本开发文档不再重复。

第二部分从源码开始 — 目录结构与实现

5. 仓库与构建

本仓库是独立的浏览器项目(rootProject MengPawBrowser, 仅 :mengpaw-browser 一个模块),
由 MengPaw 主仓库按 APK 产物拆分而来、现已独立演进。共享地基(微内核/Android 适配/设计系统)
不在本仓库, 经 JitPack 依赖主仓库发布构件 com.github.WowBlueStudio.MengPaw:<module>:<tag>。

与 Shell / 主仓库的耦合边界 (仅两项, 其余全部脱钩): ① 命令手册
docs/MengPaw_Browser_skills.md 需同步给 Shell 侧; ② Android 开发经验共同沉淀在主仓库
docs/lessons.md。已脱钩: 版本线 / 发版 / 更新链路 / 路线图 / 文档归属。本项目是中性工具 —
Shell 把 Browser 当工具使用、乃至主动检查安装其更新, 都属 Shell 自身行为, 与本项目独立演进不矛盾;
第三方 Shell 类软件同样可按命令手册适配。

模块: mengpaw-browser(Gradle Android application, 独立 APK com.mengpaw.browser)
版本: 独立节奏 v0.10.x, 单点 gradle.properties 的 mengpaw.browser.version
(与 mengpaw-browser/build.gradle.kts 同步, versionCode 也在该文件)
共享地基版本: gradle.properties 的 mengpaw.foundation.version(指向主仓库 kernel tag;
本地验证可用 mengpaw.useLocal=true 走 mavenLocal, 生产走 JitPack)
依赖: mengpaw-kernel(CLI 执行/端口表/错误码)、mengpaw-core(DataPaths/Logger)、
mengpaw-design-system(ArcoTheme)
构建: .\gradlew.bat :mengpaw-browser:assembleDebug /
.\gradlew.bat :mengpaw-browser:assembleRelease(release 关闭混淆与资源收缩, 见 build.gradle.kts)
测试: .\gradlew.bat :mengpaw-browser:testDebugUnitTest(纯 JVM 单测)
产物: mengpaw-browser/build/outputs/apk/{debug,release}/mengpaw-browser-v<ver>-{debug,release}.apk
(本仓库独立发布: 每次 Release 附带 release APK; Shell 侧主动取用/安装更新属其自身行为, 本项目不依赖)

6. 目录结构(文件地图)

com.mengpaw.browser
├── BrowserActivity.kt         # APK 入口: 状态桥/权限引导/am 桥共享实例
├── BrowserApp.kt              # Compose 主 UI (标签页/地址栏/对话框状态)
├── BrowserAppDialogs.kt       # 对话框渲染层 (状态提升, 参数显式传入)
├── BrowserContentArea.kt      # 内容区 (NewTabPage / 多标签 WebView)
├── BrowserDarkMode.kt         # 暗色模式注入
├── bridge/                    # BrowserBridge / BrowserScripts / FullPageScreenshotter
├── data/                      # BrowserPrefs / BrowserTypes / HistoryStore
├── plugin/                    # BuiltinBrowserPlugin + 4 命令组 + BrowserCommandContext
├── service/                   # RunCommandService (am 桥) / GoogleTranslate
├── ui/                        # TopBar / 设置 / 书签 / 历史 / 标签页等 Compose UI
├── util/                      # AdBlocker / BrowserStorage / DownloadUtil / PdfUtil / SmartNavigate
└── web/                       # WebViewFactory / MdViewer* / PdfViewer*

文档查看器: .md 经 MdViewer* + assets/markdown_viewer(commonmark→HTML);
.pdf 经 PdfViewer* + assets/pdf_viewer(pdf.js 2.16 + CMap, 支持放大/缩小/文字选取,
网络 .pdf URL 与本地 file/content VIEW 均可预览)。两者都是近全屏 WebView 对话框。

关键生命周期:

BrowserActivity.onCreate: 初始化 DataPaths/Logger → 绑定 Quick Click/截图设置到
BuiltinBrowserPlugin → BuiltinBrowserPlugin.shared 供 am 桥复用 →
首启申请「所有文件访问」。
BrowserActivity.onDestroy: 销毁全部 WebView、清空状态桥。
9880 HTTP 桥(McpHttpServer/McpAuthPolicy/BrowserMcpTools)已随决策 #7 退役删除。

7. 命令面实现

注册源头: BuiltinBrowserPlugin.commands =
BrowserTabCommands + BrowserPageCommands + BrowserQueryCommands +
BrowserPlaywrightCommands。共 43 条(page.* 22 + browser.* 21)。

BrowserPlaywrightCommands: page.* 22 条 — 参数解析支持位置参数 +
--flag 值(wait/max-height/grep/head/tail/timeout)+ 布尔 flag(-i 等)
BrowserTabCommands: tabs / tab / tab.open / tab.close / tab.all
BrowserPageCommands: inject / diff / preload / wait / wait.nav /
cookies / cookies.set / cookies.clear / dialog.accept / dialog.dismiss
BrowserQueryCommands: visible / enabled / storage / viewport /
userAgent / version

命令实现统一接收 (List<String>, ExecutionContext) -> ExecutionResult, 经
BrowserCommandContext 访问 WebView 桥(BrowserBridge)/标签页状态/截图器。

8. 调用通道实现 — am 桥(`RunCommandService`)

action:  com.mengpaw.browser.RUN_COMMAND
extra:   com.mengpaw.browser.RUN_COMMAND_ARGUMENTS = "-c,<命令串>"
extra:   com.mengpaw.browser.RUN_COMMAND_OUTPUT    = <输出文件路径, 公共目录>
extra:   com.mengpaw.browser.RUN_COMMAND_BACKGROUND = true
权限:    com.mengpaw.permission.RUN_BROWSER_COMMAND (signature)
白名单:  仅 page.* / browser.* 前缀

RunCommandService 引号感知分词, 经 BuiltinBrowserPlugin.shared 执行命令,
输出落盘后由调用方读取。浏览器未运行时报「浏览器未就绪(请先打开 MP 浏览器再调用)」。

9880 HTTP 桥(McpHttpServer)与 MCP 开放模式已按决策 #7 退役删除:
浏览器侧不再有 HTTP 桥/token/GET /health/POST /mcp;
kernel 侧文档表/提示词节与 mengpaw-connectors 的 browser-mcp-plugin 清理
留待主仓库执行(见 browser-autopilot-plan.md §九)。

9. 安全模型

层	措施
am 桥	signature 权限 `RUN_BROWSER_COMMAND`, 仅同签名应用可调
命令面	am 桥 payload 白名单 `page.`/`browser.`, 拒绝任意 shell
输出路径	am 桥输出限制在公共目录 `MengPaw/` 下
存储	`MANAGE_EXTERNAL_STORAGE`, 首启弹窗; 拒绝后每次 `page.load` 提示重授

9880 桥与开放模式已退役(决策 #7)——不再有 token/免认证通道, 攻击面收敛为
单一 am 桥 + signature 权限。

10. 存储与截图

截图/输出落盘: /storage/emulated/0/MengPaw/截图存档(公共目录)
超长页分段: 每段 ≈ 视口高, 上限 30 段, 超出标注 partial:true
坐标系统: 段图坐标 → 页面坐标由浏览器自动还原 (缩放比/段偏移)
设置持久化: BrowserPrefs(SharedPreferences mp_browser)

11. 测试

src/test/kotlin/com/mengpaw/browser/:

util/SmartNavigateTest.kt / util/AdBlockerTest.kt / util/PdfUtilTest.kt
(26 用例: 13 + 8 + 5, v0.10.0 快照)

改命令面/桥/安全逻辑必须补对应单测; 核心链路改动跑
:mengpaw-browser:testDebugUnitTest 全绿。

12. 开发规范

命令核对以注册处为准(BuiltinBrowserPlugin.commands 聚合, 不凭 grep 印象)
新增命令四源同步: 命令注册 / MengPaw_Browser_skills.md / 开发指南 / 提示词
端口单一事实源: Ports.kt(9876 内核保留 / 9881 MCP 网关; 9880 浏览器 MCP 已退役,
常量随主仓库 kernel 清理)
新 .kt 必须带 SPDX 双许可头; 单文件 ≤400 行; 禁 !!
双许可: AGPL-3.0-or-later OR LicenseRef-Commercial