pinchtab-skill

通过 PinchTab HTTP API 控制无头或有头 Chrome 浏览器，用于网页自动化、爬虫、表单填充、导航、截图和数据提取

Security Scan

The skill's instructions, environment settings, and documented APIs are consistent with a local Chrome-control tool; nothing in the package asks for unrelated credentials or side effects, but it legitimately requires careful operational hygiene (dedicated profiles, local binding, token) and you must trust/obtain the external pinchtab binary separately.

Purpose & Capability

Name/description claim a local HTTP API to control Chrome; all included docs and examples show use of a local pinchtab binary and a local HTTP API on port 9867. The declared requirements are minimal (no env vars required by the registry), which matches the instruction-only nature of the skill. Nothing in the docs asks for unrelated services or secrets.

Instruction Scope

SKILL.md instructs the agent to start and call a local pinchtab process and to interact with its HTTP endpoints (navigate, snapshot, action, etc.). This stays within the stated browser-automation scope. Important caveat: the docs explicitly note that if you point PinchTab at a Chrome profile containing saved logins/cookies, the agent (and any callers of the API) can access authenticated sites. The instructions also encourage binding and tokens, which is good, but they implicitly permit disabling Chrome sandbox (BRIDGE_NO_SANDBOX) and changing bind address — both are powerful options that increase risk if misused.

Install Mechanism

There is no install spec — lowest-risk delivery in that nothing is written by the skill package itself. However, that means the skill expects an external 'pinchtab' binary already present; obtaining and verifying that binary is the user's responsibility. The documentation does not include a trusted download/source or release host; verify the origin of the pinchtab binary before running.

Credentials

The skill does not require unrelated secrets. Documented environment variables (BRIDGE_BIND, BRIDGE_PORT, BRIDGE_TOKEN, BRIDGE_PROFILE, BRIDGE_BLOCK_IMAGES, etc.) are relevant to its function. Two environment-related concerns to be aware of: (1) BRIDGE_PROFILE can give the process access to cookies/saved passwords if you point it at your daily Chrome profile; (2) BRIDGE_BIND set to 0.0.0.0 or omitting BRIDGE_TOKEN exposes the API to the network. The docs call these out, which is appropriate.

Persistence & Privilege

The skill is instruction-only and not always-enabled; it does not request persistent elevated platform privileges, nor does it modify other skills or global agent configuration. Autonomous invocation is allowed (platform default), which is expected for a skill that will make local HTTP calls; this increases blast radius only if you run the pinchtab service with an unsafe configuration (public bind, no token, or shared profile).

Assessment

This skill is coherent with its stated purpose, but you must make operational choices carefully: 1) Do not point BRIDGE_PROFILE at your everyday Chrome profile — create and use an empty dedicated profile to avoid exposing saved logins. 2) Keep BRIDGE_BIND=127.0.0.1 and set BRIDGE_TOKEN if the service is reachable from any network; if you must bind publicly, restrict access with firewall rules. 3) Avoid disabling the Chrome sandbox (BRIDGE_NO_SANDBOX) unless you understand the risk. 4) There is no packaged installer or bundled binary — verify and obtain the pinchtab executable from a trusted source before running. 5) If you plan to allow an autonomous agent to call this API, consider limiting its permissions and monitoring requests/logs. If you want a deeper assessment, provide the pinchtab binary source or a release URL so I can evaluate install provenance and the binary itself.

快速、轻量级的 AI 代理浏览器控制工具，通过 HTTP + 可访问性树实现。

安全说明

PinchTab 完全在本地运行，不联系外部服务、不发送遥测数据。但它控制真实的 Chrome 实例——如果指向包含已保存登录信息的配置文件，代理可以访问认证网站。

最佳实践：

• 始终使用专用的空配置文件
• 暴露 API 时设置 BRIDGE_TOKEN
• 不要将你的日常 Chrome 配置文件指向 PinchTab

快速开始

1. 启动 PinchTab

# 无头模式（默认）- 无可见窗口
pinchtab &

# 有头模式 - 可见 Chrome 窗口，便于调试
BRIDGE_HEADLESS=false pinchtab &

# 带认证令牌
BRIDGE_TOKEN="your-secret-token" pinchtab &

# 自定义端口
BRIDGE_PORT=8080 pinchtab &

默认：端口 9867，无需认证（本地）。设置 BRIDGE_TOKEN 用于远程访问。

2. 代理工作流（30 秒模式）

# 1. 启动 PinchTab（持续运行，本地 :9867）
pinchtab &

# 2. 在代理中遵循此循环：
#    a) 导航到 URL
#    b) 快照页面（获取 refs 如 e0, e5, e12）
#    c) 对 ref 执行操作（点击 e5，输入 e12 "搜索文本"）
#    d) 再次快照查看结果
#    e) 重复步骤 c-d 直到完成

就这么简单。 Refs 是稳定的——每次操作前不需要重新快照，只在页面显著变化时快照。

核心工作流

典型的代理循环：

1. 导航 到 URL
2. 快照 可访问性树（获取 refs）
3. 执行 操作（点击、输入、按键）
4. 再次快照 查看结果

CLI 示例

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

# 获取交互式元素（紧凑格式）
pinchtab snap -i -c

# 点击元素
pinchtab click e5

# 输入文本
pinchtab type e12 hello world

# 按键
pinchtab press Enter

# 提取文本（~1K tokens）
pinchtab text

# 截图
pinchtab ss -o page.jpg

# 执行 JavaScript
pinchtab eval "document.title"

# 导出 PDF
pinchtab pdf --tab TAB_ID -o page.pdf

HTTP API 示例

导航

curl -X POST http://localhost:9867/navigate \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

获取快照

# 完整快照
curl http://localhost:9867/snapshot

# 仅交互式元素（按钮、链接、输入）
curl "http://localhost:9867/snapshot?filter=interactive"

# 紧凑格式（节省 56-64% tokens）
curl "http://localhost:9867/snapshot?format=compact"

# 仅变化部分（多步骤工作流）
curl "http://localhost:9867/snapshot?diff=true"

执行操作

# 点击
curl -X POST http://localhost:9867/action \
  -H "Content-Type: application/json" \
  -d '{"kind": "click", "ref": "e5"}'

# 输入
curl -X POST http://localhost:9867/action \
  -H "Content-Type: application/json" \
  -d '{"kind": "type", "ref": "e12", "text": "hello"}'

# 按键
curl -X POST http://localhost:9867/action \
  -H "Content-Type: application/json" \
  -d '{"kind": "press", "key": "Enter"}'

提取文本

# 可读文本（~800 tokens）
curl http://localhost:9867/text

# 原始 HTML
curl "http://localhost:9867/text?mode=raw"

截图

curl -X POST http://localhost:9867/screenshot \
  -H "Content-Type: application/json" \
  -d '{"format": "jpeg", "quality": 80}' \
  --output page.jpg

多标签页管理

# 创建新标签页
curl -X POST http://localhost:9867/tabs \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# 切换标签页
curl -X POST http://localhost:9867/tabs/switch \
  -H "Content-Type: application/json" \
  -d '{"tabId": "TAB_123"}'

# 关闭标签页
curl -X DELETE http://localhost:9867/tabs/TAB_123

快照示例

调用 /snapshot 后，获得页面的可访问性树 JSON：

{
  "refs": [
    {"id": "e0", "role": "link", "text": "Sign In", "selector": "a[href='/login']"},
    {"id": "e1", "role": "textbox", "label": "Email", "selector": "input[name='email']"},
    {"id": "e2", "role": "button", "text": "Submit", "selector": "button[type='submit']"}
  ],
  "text": "... 页面的可读文本版本 ...",
  "title": "Login Page"
}

然后对 refs 执行操作：click e0，type e1 "[e-mail]"，press e2 Enter。

Token 成本指南

方法	典型 tokens	使用场景
/text	~800	阅读页面内容
/snapshot?filter=interactive	~3,600	查找要点击的按钮/链接
/snapshot?diff=true	变化量	多步骤工作流（仅变化）
/snapshot?format=compact	减少 56-64%	每行一个节点，最佳效率
/snapshot	~10,500	完整页面理解
/screenshot	~2K (vision)	视觉验证
/tabs/{id}/pdf	0 (二进制)	导出 PDF（无 token 成本）

策略：从 ?filter=interactive&format=compact 开始。后续快照使用 ?diff=true。仅需要可读内容时使用 /text。仅在需要时使用完整 /snapshot。

代理优化

2026 年 2 月验证：测试发现关键模式，实现可靠、节省 token 的爬虫。

3 秒模式

导航后等待 3 秒再快照：

curl -X POST http://localhost:9867/navigate \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' && \
sleep 3 && \
curl http://localhost:9867/snapshot | jq

Token 节省：93% 减少（3,842 → 272 tokens）。

提示

• 多标签页时始终显式传递 tabId
• Refs 在快照和操作之间稳定——点击前无需重新快照
• 导航或页面重大变化后，获取新快照获取新鲜 refs
• PinchTab 持久化会话——标签页在重启后存活（用 BRIDGE_NO_RESTORE=true 禁用）
• Chrome 配置文件持久化——cookies/登录信息在运行间保留
• 阅读密集型任务使用 BRIDGE_BLOCK_IMAGES=true 或 "blockImages": true
• 导航后等待 3+ 秒再快照——Chrome 需要时间渲染 2000+ 可访问性树节点

环境变量

# 绑定地址（默认 127.0.0.1）
BRIDGE_BIND=127.0.0.1

# 认证令牌（默认无）
BRIDGE_TOKEN="your-secret-token"

# 端口（默认 9867）
BRIDGE_PORT=9867

# 无头模式（默认 true）
BRIDGE_HEADLESS=false

# 配置文件路径
BRIDGE_PROFILE=~/.pinchtab/automation-profile

# 阻止图片（节省带宽）
BRIDGE_BLOCK_IMAGES=true

# 禁用会话恢复
BRIDGE_NO_RESTORE=true

完整文档

• API 参考 - 完整 HTTP API
• 配置文件 - 配置文件管理
• 环境变量 - 所有配置选项