Hermes + PinchTab 浏览器引擎手册 🦎

🦎 Hermes + PinchTab 浏览器引擎手册

版本: 1.0 | 更新日期: 2026-05-16 | 维护人: Hermes Agent

📑 目录

  1. 架构概览
  2. 安装
  3. 配置
  4. MCP 集成
  5. 基本使用
  6. 安全策略
  7. 性能对比
  8. FAQ

1. 🏗️ 架构概览

PinchTab 是一个轻量级的浏览器控制 API 工具，专为 AI Agent 设计。它通过 chrome DevTools Protocol (CDP) 操控浏览器，提供 Headless 浏览能力。

┌──────────────┐     MCP stdio      ┌──────────────────┐
│  Hermes      │ ◄──────────────►   │  PinchTab MCP    │
│  Agent       │                    │  Server (Go)     │
└──────────────┘                    └────────┬─────────┘
                                             │
                                             ▼
                                    ┌──────────────────┐
                                    │  Chromium        │
                                    │  Headless Shell  │
                                    │  (CDP Protocol)  │
                                    └──────────────────┘

定位:

  • 优先 Web 浏览: Hermes 的标配浏览器工具，用于需要 JS 渲染、页面交互的场景
  • 兜底 curl: 纯 API/数据获取场景使用 curl，延迟最低
  • 弃用 Playwright: PinchTab 比 Playwright Chromium 快约 2 倍，作为浏览器引擎的首选

2. 📦 安装

2.1 npm 安装

mkdir -p /www/kc-ai-hermes/pinchtab
cd /www/kc-ai-hermes/pinchtab
npm init -y
npm install pinchtab

2.2 验证安装

# 检查版本
/www/kc-ai-hermes/pinchtab/node_modules/.bin/pinchtab --version
# 应输出: pinchtab 0.12.0

2.3 浏览器引擎

PinchTab 需要 Chromium 浏览器二进制文件。在 Hermes Docker 环境中，可直接复用 Playwright 已下载的头壳：

# 路径
/opt/hermes/.playwright/chromium_headless_shell-1217/chrome-linux/headless_shell

3. ⚙️ 配置

3.1 PinchTab 自身配置

配置文件路径: /opt/data/home/.pinchtab/config.json

必须修改的配置项：

配置路径 值 说明
security.allowedDomains ["*"] 允许访问所有外部 URL，默认仅 localhost
browser.binary Chromium 头壳路径 指定浏览器可执行文件路径 
# 快速修改
pinchtab config set security.allowedDomains '["*"]'

3.2 Hermes MCP 配置

在 /opt/data/config.yaml 的 mcp_servers 段添加：

mcp_servers:
  pinchtab:
    command: /www/kc-ai-hermes/pinchtab/node_modules/.bin/pinchtab
    args: ["mcp"]
    timeout: 120

重启 Hermes 后，PinchTab 的 MCP 工具将自动注册为 mcp_pinchtab_* 前缀的工具。

注意: Hermes 会自动管理 PinchTab 服务进程生命周期，无需手动启动/停止。

4. 🔌 MCP 集成

4.1 启动方式

PinchTab MCP 服务器在 Hermes 启动时自动连接，连接方式为 stdio 模式：

pinchtab mcp

首次启动会自动初始化浏览器实例，过程约 3-5 秒。

4.2 MCP 工具清单

PinchTab 通过 MCP 协议提供以下浏览器控制工具（前缀 mcp_pinchtab_）：

  • mcp_pinchtab_navigate — 导航到 URL
  • mcp_pinchtab_click — 点击页面元素
  • mcp_pinchtab_screenshot — 页面截图
  • mcp_pinchtab_snap — 获取页面结构
  • mcp_pinchtab_back — 浏览器后退
  • mcp_pinchtab_forward — 浏览器前进
  • mcp_pinchtab_console — 查看控制台日志
  • mcp_pinchtab_cookies — 管理 Cookies
  • mcp_pinchtab_download — 下载文件
  • mcp_pinchtab_pdf — 保存为 PDF

5. 🛠️ 基本使用

5.1 CLI 命令

# 导航
pinchtab nav https://example.com --json

# 导航并查看页面结构
pinchtab nav https://example.com
pinchtab snap

# 截图
pinchtab screenshot --tab <tab-id> -o page.png

# 查看实例
pinchtab instances --json

# 查看页面对话框/控制台
pinchtab console --tab <tab-id>
pinchtab errors --tab <tab-id>

5.2 标签管理

pinchtab tabs           # 列出所有标签页
pinchtab close <id>     # 关闭标签页
pinchtab state           # 管理浏览器会话状态
pinchtab storage         # 管理浏览器存储

5.3 输出格式

使用 --json 标志获取 JSON 格式输出，便于程序解析：

{
  "tabId": "4795CA0848C47E8A8010EBAC5B14449A",
  "title": "Example Domain",
  "url": "https://example.com/"
}

6. 🔒 安全策略

PinchTab 默认启用严格安全策略，仅允许访问 localhost:

Security
├── loopback bind      127.0.0.1     # 仅本地绑定
├── api auth           required      # API 认证必需
├── website whitelist  127.0.0.1     # 仅限本地 URL
├── IDPI strict mode   enforcing     # 内容注入防护
└── IDPI content guard active        # 内容安全扫描

安全级别调整

# 全面防护（默认）
pinchtab security up

# 降低限制（用于 AI Agent 场景）
pinchtab security down
pinchtab config set security.allowedDomains '["*"]'

# 临时免密运行（仅本次，不修改配置文件）
pinchtab server -y

推荐配置（Hermes Agent 环境）：

  • 允许所有域名: security.allowedDomains = ["*"]
  • 保持 loopback 绑定: server.bind = 127.0.0.1（不对外暴露）

7. 📊 性能对比

测试环境

  • Hermes Docker Container (aarch64)
  • 3 URL 类型 × 3 次迭代 = 9 次采样
  • 测试日期: 2026-05-16

结果汇总

引擎 综合平均 vs curl
curl 590ms 1.00x (基准)
PinchTab 946ms 1.60x
Playwright Chromium 1758ms 2.98x

分场景分析

场景 curl PinchTab Playwright
轻量页面 (example.com) 300ms 501ms (1.67x) 1469ms (4.90x)
本地 Trilium 共享 569ms 1503ms (2.64x) 1934ms (3.40x)
API 端点 901ms 835ms (0.93x) 1870ms (2.08x)

结论

  • curl — 纯数据获取场景最快，适合 API 调用、简单页面抓取
  • PinchTab — 浏览器交互场景的首选，兼顾速度与能力，比 Playwright 快 2 倍
  • Playwright Chromium — 功能最全但启动开销最大，仅在全套浏览器自动化场景使用

8. ❓ FAQ

Q: PinchTab 和 Hermes 内置浏览器工具有什么关系？

PinchTab 通过 MCP 提供额外的浏览器工具集（mcp_pinchtab_*），与 Hermes 内置的 browser_navigate 等工具并存。PinchTab 速度更快、更轻量，推荐作为首选浏览器引擎。

Q: PinchTab 需要单独维护服务器进程吗？

不需要。Hermes 的 MCP 客户端会在启动时自动管理 PinchTab 服务进程的生命周期。进程退出后会自动尝试重连。

Q: 为什么初始化会报 503 Instance Not Ready？

PinchTab 首次启动浏览器实例需要 3-5 秒。如果 nav 命令执行得太快，实例尚未就绪就会报 503。等待几秒重试即可。安全策略不对时也会导致此错误。

Q: 如何让 PinchTab 访问外部网站？

默认安全策略只允许访问 localhost。执行 pinchtab security down 降低限制，然后修改 security.allowedDomains 为 ["*"]。

Q: PinchTab 在 Hermes 环境中占多少空间？

npm 包约 50MB，Go 二进制约 70MB（~/.pinchtab/bin/），Chromium 头壳 279MB（Playwright 共享）。总计约 400MB。

Q: 能否只装 PinchTab 不装 Playwright？

可以，但需要为 PinchTab 提供其他 Chromium 二进制，或者让 PinchTab 自动下载（需网络通畅且不在 Docker 中时）。

— 本文档由 Hermes Agent 自动生成并维护于 Trilium