Pinchtab：12MB Go 浏览器 API，为 AI 代理而生
Pinchtab：12 MB Go 浏览器 API，为 AI 代理而生
现代 AI 代理需要一种可靠且低成本的方式来读取、交互和控制网页。现有的解决方案如 Playwright、Puppeteer 或 Browser Use 通常会带来沉重的运行时、紧耦合的语言绑定或不必要的开销。Pinchtab 通过一个 单一、完全自包含的 Go 可执行文件 解决了这一问题，它启动一个无头 Chrome 实例，提供纯 HTTP API，并且 令牌效率 高，足以满足大规模、读取占主导的工作负载。
什么是 Pinchtab
- 独立 HTTP 服务器 — 无需语言 SDK；curl、Python、Rust 或任何 OpenAI 代理均可使用。
- 12 MB Go 可执行文件 — 使用
go build编译，无需运行时外部依赖。 - Chrome 在引擎背后 — 管理实际的 Chromium，但将所有繁重工作抽象为干净、结构化的 API。
- 双重模式 —
headless用于全自动管线，headed用于人机交互流程。 - 内置隐身 — 自动修补
navigator.webdriver，伪造 User-Agent 与其他标识。 - 会话持久化 — Cookie 和本地存储在重启后仍存留，适用于多步登录。
- 令牌高效输出 — 支持
/text（约 800 令牌）和?filter=interactive（约 3 600 令牌）快照模式，在向 LLM 提供文本时降低成本。
结果是一款 像 LLM 插件般轻巧的浏览器工具：启动快捷、使用简单且高度可配置。
为什么 Pinchtab 更胜常见方案
| 特性 | Pinchtab | Playwright MCP | Browser Use |
|---|---|---|---|
| 二进制大小 | 12 MB 单一可执行文件 | 10 + GB 依赖树 | 5 GB 容器 |
| 协议 | REST + WebSocket | CDP + 自定义包装器 | WebSocket + RPC |
| 可移植性 | Go 跨平台编译 | Node.js 运行时 | 需要 Docker |
| 令牌成本 | /text 800 tokens/页 |
全快照 10 k+ tokens | 10 k+ tokens |
| 无头 / 有头 | 内置切换 | 仅 CLI 无头 | 仅无头 |
| 隐身 | 内置修补 | 需要自定义脚本 | 无本地支持 |
当您仅需要读取页面或点击按钮时，Pinchtab 的文本或交互快照在令牌成本上比使用视觉模型的全屏截图便宜 3–10 倍，这在大规模抓取或监控中可节省数十倍成本。
快速开始
1. 安装
# 源码安装
$ go install github.com/pinchtab/pinchtab@latest
# 或 Docker（最简易）
$ docker run -d -p 9867:9867 --security-opt seccomp=unconfined pinchtab/pinchtab
可执行文件默认监听 9867 端口。若想更改请使用 BRIDGE_PORT=9870 ./pinchtab。
2. 基本 curl 用法
# 检查健康
$ curl http://localhost:9867/health
# 读取页面
$ curl http://localhost:9867/text?tabId=1
# 按引用点击按钮（快照中的 ID）
$ curl -X POST http://localhost:9867/action \
-d '{"kind":"click","ref":"e5"}'
所有端点返回干净的 JSON。请参阅下面的 API 部分以了解查询参数和高级选项的详细信息。
3. 有头模式（人机 + 代理）
$ BRIDGE_HEADLESS=false ./pinchtab
打开浏览器窗口，登录，解决 CAPTCHA，随后在您的代理中使用同一配置文件的 API（例如 http://localhost:9869）。个人档案保存在 ~/.pinchtab/profiles/<name>/ 并在重启后持续存在。
4. 使用仪表盘
$ pinchtab dashboard
# 在浏览器中打开 http://localhost:9867/dashboard
# 创建/导入配置文件，启动有头实例，停止它们
仪表盘提供了一个简洁的 UI，用于管理多个配置文件和实例。
核心 API 概览
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | /health |
服务器状态 |
| GET | /tabs |
打开的标签页列表 |
| GET | /snapshot |
无障碍树（结构化 JSON） |
| GET | /screenshot |
JPEG 图像 |
| GET | /text |
页面文本（readability 或 raw） |
| POST | /navigate |
跳转到 URL |
| POST | /action |
点击、输入、滚动等 |
| POST | /evaluate |
运行任意 JavaScript |
| POST | /tab |
打开/关闭标签页 |
| POST | /tab/lock / /unlock |
锁定/解锁标签页，以实现排他访问 |
快照查询参数
filter=interactive– 仅包含按钮、链接、输入框，减小尺寸。format=text– 纯文本树，约比 JSON 少 40–60 % 令牌。diff=true– 仅返回与上一次快照的差异。noAnimations=true– 禁用 CSS 动画，保证输出确定性。
文本查询参数
mode=raw– 原始内文本，否则通过 readability 去除广告/导航。
高级功能
隐身模式
Pinchtab 提供两种隐身级别：light（基础标识）和 full（canvas/WebGL/font 模拟）。使用 BRIDGE_STEALTH=full 启用，这在自动化具有强大机器人检测的网站时至关重要。
会话持久化
默认情况下，Pinchtab 会将 Cookie、本地存储甚至打开的标签页写入 ~/.pinchtab。您可以通过 BRIDGE_PROFILE=/my/profile 指定自定义目录。在无头模式下，还可以通过 POST /cookies 注入 Cookie。
图片与媒体阻断
设置 BRIDGE_BLOCK_IMAGES=true 或 BRIDGE_BLOCK_MEDIA=true 可减少带宽并加快快照速度。
自定义 Chrome 标识
通过 CHROME_FLAGS="--no-sandbox --disable-gpu" 传递任何 Chrome 标识，这在 CI 或资源受限的环境中很有用。
安全考虑
Pinchtab 实际上会让代理直接控制在运行您帐户数据的真实浏览器。请务必：
- 使用
BRIDGE_TOKEN保护 HTTP 端点。 - 在受限网络或防火墙后运行。
- 对实验性代理使用一次性 Chrome 配置文件。
可执行文件不会自行将任何数据发送到外部，除非您这么做。请像保护密码一样保护 ~/.pinchtab。
快速参考：使用仪表盘
# 启动仪表盘
$ pinchtab dashboard
# 在 UI 中
# 1. 导入配置文件（点击“Import Profile”）
# 2. 启动新实例（选择有头或无头）
# 3. 在代理中使用返回的 API URL
仪表盘还暴露了 POST /start/{id} 与 /stop/{id}，支持程序化生命周期管理。
常见用例
| 用例 | Pinchtab 的优势 | 示例 |
|---|---|---|
| 网页抓取 | 快速、低令牌文本提取 | 按 100 页计划抓取新闻文章，费用低于 $0.05 |
| AI 助手聊天机器人 | 无缝浏览器集成 | OpenAI LLM 实时发送点击动作 |
| 自动化测试 | 有头模式用于可视化调试 | 使用 Docker Compose + 有头实例运行集成测试 |
| 数据管道 | 在多次运行之间保持会话活跃 | 一次自动登录门户并获取每日报告 |
结论
Pinchtab 是一款务实、开源的解决方案，消除了将浏览器集成到 AI 工作流中的摩擦。其小巧的体积、以 HTTP 为首的接口以及高效的文本输出，使其成为需要读取、交互并操纵网页而不需完整浏览器框架的下一代 AI 代理的理想伴侣。试试它——12 MB 的可执行文件可在您的笔记本、服务器或 Docker 容器中运行，API 体验像插件一样为您所用。