pinchtab

# 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 "...