核心用法
tappi 是一款基于 Chrome DevTools Protocol (CDP) 的轻量级浏览器控制 CLI，专为 AI Agent 场景优化。核心设计理念是最小化输出、最大化可操作性——通过索引化交互元素列表，让 Agent 无需解析复杂的可访问性树即可直接执行操作。
基础工作流：
1. bjs open <url> 导航至目标页面
2. bjs elements 获取可交互元素索引列表（自动穿透 Shadow DOM）
3. bjs click <index> / bjs type <index> <text> 执行操作
4. bjs text 或 bjs screenshot 验证结果
智能命令 vs 底层命令： 前者（click、type、paste）内置焦点管理、验证和回退机制；后者（focus、check、eval）提供细粒度控制，用于解决边缘情况。
特殊场景支持：
- Canvas 应用：Google Sheets/Docs/Figma 等使用
bjs keys发送原始键盘事件 - 跨域 iframe：验证码、支付表单使用
bjs click-xy坐标点击绕过 DOM 边界 - 大段内容输入：
bjs paste优于type，支持文件直读并自动验证
显著优点
1. 极致 Token 效率：单次交互 50-200 tokens，较内置浏览器工具（2,000-8,000 tokens）节省 3-10 倍，长流程场景差异可达 20-50 倍
2. 原生 Shadow DOM 支持：自动递归穿透 web components，Reddit、GitHub 等现代 SPA 开箱即用
3. 真实鼠标事件：使用 CDP Input.dispatchMouseEvent 而非 JS .click()，可靠触发 React/Vue/Angular 合成事件
4. 会话保持：继承已登录状态，无需重复认证
5. 零 OS 对话框文件上传：直接注入文件到隐藏 input 元素
潜在缺点与局限性
1. 依赖外部浏览器：需 Chrome/Chromium 以 --remote-debugging-port 启动，OpenClaw 环境外需手动配置
2. 无视觉理解能力：返回的是结构化文本而非截图分析，复杂布局仍需 screenshot 辅助
3. Canvas 内容不可遍历：Google Sheets 等 canvas 应用的内容区域无 DOM 元素，必须切换到 keys 模式
4. 坐标命令需人工计算：iframe 内元素定位依赖 iframe-rect 获取基准后再偏移，非完全自动化
5. 错误恢复需显式处理：虽智能命令内置回退，但焦点丢失、弹窗干扰等仍需 check/focus 手动修复
适合人群
- 高频网页自动化开发者：需要以最低 token 成本完成多步骤浏览任务的 AI Agent 构建者
- Shadow DOM 重度用户：经常操作 React/Vue/Angular 现代 SPA 或 Web Components 站点
- 成本敏感型项目：LLM API 调用量大的生产环境，需严格控制上下文长度
- 已有 CDP/Playwright 经验者：熟悉 Chrome DevTools Protocol 概念的用户上手更快
常规风险
| 风险类别 | 具体表现 | 缓解措施 |
|---------|---------|---------|
| **焦点漂移** | 自动完成弹窗、悬浮卡片窃取输入焦点 | 操作前 `check` 验证，异常时 `keys --escape` + `focus` 恢复 |
| **状态同步延迟** | AJAX 更新后元素索引过期 | 智能命令自动重索引，或手动重调 `elements` |
| **iframe 安全隔离** | 跨域内容无法 DOM 访问 | 预计算坐标使用 `click-xy`，接受定位精度 trade-off |
| **长文本截断** | `text`/`html` 有 8KB/10KB 上限 | 配合 `eval` 自定义提取逻辑或分页处理 |
| **浏览器崩溃** | CDP 连接断开无自动重连 | 流程中插入 `bjs tabs` 心跳检测，异常时重启浏览器 |
认证状态说明：安全认证报告显示为占位符，未执行实际安全扫描。建议在生产部署前进行依赖审计（npm install 的第三方包）和 CDP 端口访问控制检查。