Hermes + PinchTab 浏览器引擎手册 🦎

🦎 Hermes + PinchTab 浏览器引擎手册

版本: 5.0 | 更新日期: 2026-07-10 | 维护人: Hermes Agent

基于实际环境审计，修正部署路径、版本号、进程架构及使用统计数据。

📑 目录

  1. 部署
  2. 生命周期与运行时架构
  3. 使用记录与统计
  4. 当前配置快照
  5. 故障排查

1. 🚀 部署

1.1 存在形式

组件当前实际路径大小说明
二进制/opt/data/home/.pinchtab/bin/pinchtab19MBGo 静态编译单文件，v0.12.0（非 v0.13.0）
/opt/data/.pinchtab/bin/pinchtab19MB✅ 重复副本，版本一致
运行配置/opt/data/.pinchtab/config.json4K当前活动配置（token 鉴权）
用户配置/opt/data/home/.pinchtab/config.json4K历史冗余，内容与上面一致
Profile 数据/opt/data/.pinchtab/profiles/default/Default/699MChrome 用户数据（Cache 468M + Code Cache 219M）
活动日志/opt/data/.pinchtab/activity/284K历史（Jun 4 - Jul 3）
/opt/data/home/.pinchtab/activity/4K近期（Jul 3 - Jul 7）
Server 日志/opt/data/home/.pinchtab/server.log4K启动日志 + 请求记录
MCP 配置/opt/data/config.yaml → mcp_servers.pinchtab—command: /opt/data/home/.pinchtab/bin/pinchtab, args: [mcp]

1.2 依赖

依赖版本路径
Chromium144.0.7559.133/opt/hermes/.playwright/chromium_headless_shell-1223/chrome-linux/headless_shell
Go 运行时—无需，Go 静态编译二进制

注意：浏览器引擎使用的是 Hermes 自带的 headless_shell（在 /opt/hermes/.playwright/ 下），不是 /opt/data/home/.local/share/playwright/ 中的 Playwright Chromium。前者由 Hermes 容器镜像自带，后者是用户通过 pip install playwright 安装的。

1.3 磁盘占用

项目大小路径
Profile 缓存699M/opt/data/.pinchtab/profiles/
  ├─ Cache468MChrome 磁盘缓存
  └─ Code Cache219MJavaScript 编译缓存
二进制19M × 2两个副本
活动日志288K两处 activity 目录
合计~761M浏览器引擎（headless_shell）不计，属容器基础镜像

2. 🔄 生命周期与运行时架构

2.1 进程架构

v0.12.0 进程模型（与旧版文档不同，当前版本没有独立的 server → bridge 分离链路，而是：）

┌─ Hermes Gateway ──────────────────────────────────────┐
│  MCP Client (stdio)                                    │
│     │ JSON-RPC                                         │
│     ▼                                                  │
├─ pinchtab mcp ────────────────────────────────────────┤
│  PID 14348 / 14360  (两个 MCP 子进程)                   │
│  · 接收 Hermes MCP 调用                                │
│  · 转发为 PinchTab HTTP API 请求                       │
│  · 由 Gateway 启动/管理                                │
│     │ HTTP :9867 (带 Bearer token)                     │
│     ▼                                                  │
├─ pinchtab server ─────────────────────────────────────┤
│  PID 14125  (主 daemon)                                │
│  · 中央控制面，端口 9867                               │
│  · 管理 Chrome 实例声明周期                            │
│  · 记录 activity 日志                                  │
│     │ CDP (Chrome DevTools Protocol)                   │
│     ▼                                                  │
├─ pinchtab bridge ─────────────────────────────────────┤
│  PID 19956  (实例代理)                                 │
│  · 转发 CDP 命令到 Chrome                              │
│  · 管理标签页状态                                     │
│     │ CDP                                              │
│     ▼                                                  │
├─ Chrome (headless_shell) ─────────────────────────────┤
│  · headless 模式                                       │
│  · Profile: /opt/data/.pinchtab/profiles/default/     │
│  · 多个子进程 (zygote/network/renderer/storage)        │
└────────────────────────────────────────────────────────┘

2.2 生命周期时间线

完整生命周期（基于服务器日志 + 活动记录）

时间事件说明
May 16首次安装二进制 home/.pinchtab/bin/pinchtab 就位
May 18-30活跃使用期性能基准测试等（旧版对比测试）
Jun 4服务重启stateDir 切至 /opt/data/.pinchtab/，activity 开始记录
Jun 4-30密集使用期日均 20-100+ events，含 navigate/snapshot/text/click 等
Jun 9 10:23后台关闭shutting down dashboard... 实例被故意停止
Jul 1-2休眠期仅 1 event/日（health check）
Jul 3 08:00+服务重启重新启动 server，触发 148 events
Jul 3-7Token 异常期几乎所有请求返回 401（token 不匹配）
Jul 3 - now进程持续运行server/mcp/bridge 进程持续运行 6+ 天

2.3 进程状态（当前）

进程PID运行时长角色
pinchtab server141256d 17h中央 daemon，端口 9867
pinchtab mcp143486d 17hMCP 桥接 #1
pinchtab mcp143606d 17hMCP 桥接 #2
pinchtab bridge199566d 17hChrome CDP 代理

2.4 常驻 vs 按需

当前架构是常驻 daemon 模式（非旧版文档所述的"按需启动"）。

  • server/mcp/bridge 进程持续运行，在 Hermes Gateway 启动时即加载，非首次调用时启动
  • Chrome 实例在 server 启动时自动启动（always-on 策略），非按需启动
  • 进程自 Jul 3 以来已持续运行 6 天 17 小时未重启

资源消耗：

  • server 进程 RSS: 27MB
  • mcp 进程 ×2: ~20MB 各
  • bridge 进程: ~28MB
  • Chrome 及其子进程: 按页面数量浮动（每个渲染进程 ~100-170MB）

3. 📊 使用记录与统计

3.1 每日活动量

日期事件数活跃度
Jun 423⭐
Jun 518
Jun 966⭐⭐
Jun 1082⭐⭐⭐
Jun 1287⭐⭐⭐
Jun 14109⭐⭐⭐⭐
Jun 16-1739+71⭐⭐⭐
Jun 2123
Jun 23-305-77/日偶发使用
Jul 3148🔥 峰值（服务重启）
Jul 4-71-2/日Token 异常，实质不可用

3.2 操作统计（全历史）

操作成功次数占比说明
navigate18945%页面导航（最多）
snapshot9222%获取页面结构
text7919%提取页面纯文本
click184%点击页面元素
press / mouse-wheel / hover51%其他交互
合计~383100%另含 ~105 health check 等辅助调用

导航 (navigate) + 内容提取 (snapshot + text) 占所有操作的 86%，为主要使用模式。点击等交互操作仅占 4%。screenshot 等可视化输出仅 7 次。

3.3 当前状态：Token 异常

自 Jul 3 服务重启后，所有 PinchTab API 调用返回 401。 MCP 进程发送的请求不含有效的 Bearer token，导致每次操作实际失败。7 月 4 日至 7 日仅 1-2 次/日的 health check（也 401）。

根因：两处 config.json 中的 token 在服务重启后未同步。当前 config 中有 token：3df8213a...，但 MCP 进程可能持有旧 token 或不带 token 发送请求。

修复：

# 将 home 下的 config 同步到运行目录
cp /opt/data/home/.pinchtab/config.json /opt/data/.pinchtab/config.json

# 或重启 Gateway 重新加载 MCP
fuser -k 9867/tcp
# 等待 Gateway 重启（自动拉起 pinchtab mcp）

4. ⚙️ 当前配置快照（v0.12.0）

活动配置位于 /opt/data/.pinchtab/config.json（与 /opt/data/home/.pinchtab/config.json 内容一致）。

4.1 Server 配置

server.port9867服务端口
server.bind127.0.0.1loopback 绑定
server.token3df8213a...Bearer 鉴权
stateDir/opt/data/.pinchtab状态目录
engine空未配置

4.2 浏览器配置

browser.binary/opt/hermes/.playwright/chromium_headless_shell-1223/chrome-linux/headless_shell
browser.version144.0.7559.133
instanceDefaults.modeheadless
instanceDefaults.stealthLevellight
instanceDefaults.maxTabs20
instanceDefaults.tabEvictionPolicyclose_lru

4.3 安全配置

allowedDomains["*"]⚠️ 全部放行
allowEvaluatetrue⚠️ JS 执行开启
allowNetworkIntercepttrue⚠️ 网络拦截开启
allowDownload / Uploadtrue⚠️ 文件上下开开启
allowClipboardfalse✅ 剪贴板关闭
allowStateExportfalse✅ 状态导出关闭
idpi.enabledfalse⚠️ IDPI 关闭（旧文档声称 true）
idpi.strictModefalse⚠️ 非限定模式
trustedProxyCIDRs / ResolveCIDRs[]⚠️ 无内网信任配置

4.4 多实例配置

strategyalways-on常驻运行
allocationPolicyfcfs先到先得
instancePortStart~End9868 - 9968实例端口池
restart.maxRestarts20崩溃自动重启上限

4.5 Hermes config.yaml MCP 配置

mcp_servers:
  pinchtab:
    command: /opt/data/home/.pinchtab/bin/pinchtab
    args:
      - mcp
    timeout: 120

关键点：

  • args 只有 ["mcp"]，无 --server（否则 stdout 污染）
  • timeout 120s 充足
  • MCP 工具集共 38+ 个工具（navigate/click/snapshot/fill/type 等）

5. 🔧 故障排查

5.1 当前问题：401 missing_token

症状：MCP 调用返回 401，activity 日志显示 status=401

根因：服务重启后 token 不一致

修复：

# 从 home 复制 config（含正确 token）到运行目录
cp /opt/data/home/.pinchtab/config.json /opt/data/.pinchtab/config.json
# 重启服务
fuser -k 9867/tcp

5.2 MCP 工具不可见

# 检查配置
grep -A5 "pinchtab:" /opt/data/config.yaml
# 确认 args 只有 ["mcp"]
# 重启 Gateway

5.3 Chrome 无法启动

容器环境自动使用 headless_shell（headless 模式），无需沙箱。确认二进制路径存在。

5.4 磁盘占用

Profile 缓存（699M）为主要磁盘消耗，可定期清除：

# 清除浏览器缓存（不影响配置）
rm -rf /opt/data/.pinchtab/profiles/default/Default/Cache/*
rm -rf /opt/data/.pinchtab/profiles/default/Default/Code\ Cache/*

5.5 清理重复文件

目前 /opt/data/.pinchtab/bin/pinchtab 和 /opt/data/home/.pinchtab/bin/pinchtab 为同版本重复副本（19MB × 2）。MCP 配置指向 home 下的，/opt/data/.pinchtab/bin/ 下的副本可清理。

与旧版文档差异总结

项目旧版（v4.0）实际（v5.0）
版本v0.13.0v0.12.0
二进制路径/opt/data/mcp/pinchtab//opt/data/home/.pinchtab/bin/pinchtab
浏览器引擎Playwright ChromiumHermes 内置 headless_shell
进程模型按需启动常驻 daemon（6+ 天）
stateDir未明确/opt/data/.pinchtab/
IDPI 状态enabled + strictdisabled
Token 同步需手动内容一致但 MCP 仍 401（bug）

— 本文档由 Hermes Agent 维护于 Trilium | v5.0 基于实际环境审计