# Pinchtab

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

- Skill: `dvcrn/pinchtab-2` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add dvcrn/pinchtab-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/pinchtab-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/dvcrn/pinchtab-2

---


# PinchTab Skill

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

## 安全说明

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

**最佳实践：**
- 始终使用专用的空配置文件
- 暴露 API 时设置 `BRIDGE_TOKEN`
- 不要将你的日常 Chrome 配置文件指向 PinchTab

## 快速开始

### 1. 启动 PinchTab

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

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

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

# 自定义端口
BRIDGE_PORT=8080 pinchtab &
```

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

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

```bash
# 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 示例

```bash
# 导航
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 示例

### 导航

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

### 获取快照

```bash
# 完整快照
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"
```

### 执行操作

```bash
# 点击
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"}'
```

### 提取文本

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

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

### 截图

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

### 多标签页管理

```bash
# 创建新标签页
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：

```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 "user@example.com"`，`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 秒再快照：

```bash
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+ 可访问性树节点

## 环境变量

```bash
# 绑定地址（默认 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 参考](references/api.md) - 完整 HTTP API
- [配置文件](references/profiles.md) - 配置文件管理
- [环境变量](references/env.md) - 所有配置选项