web-probe

AI 浏览器自动化 CLI 工具 — 面向 AI Agent 的浏览器工具箱。

核心特性

• 零打扰连接用户已登录的 Chrome（autoConnect / 独立实例 / 强制接管三级策略）
• 场景驱动的 SKILL（AI Agent 按场景模板执行，无需探索所有命令）
• 35+ 命令覆盖页面操作、AI 语义操作、认证管理、会话管理
• DevTools 桥接（可选 chrome-devtools-mcp，获得性能分析/Lighthouse 等能力）
• 8 个 AI 工具一键 Skill 注入（Cursor / Claude Code / Codex / Agents / OpenCode / Windsurf / Copilot / Trae）

安装

npm install -g web-probe-cli

# 或免安装执行
npx --yes web-probe-cli doctor

快速开始

# 1. 检查环境
web-probe doctor

# 2. 连接浏览器（自动选择最优方式）
web-probe chrome start

# 3. 查看标签页
web-probe tabs

# 4. 截图 / 分析页面
web-probe shot <tabId>
web-probe inspect <tabId>

# 5. 结束会话
web-probe chrome stop

架构

AI Agent (Cursor / Claude Code / Codex / ...)
  └→ 读取 SKILL.md → 识别场景 → 按模板执行命令
        │
        ▼
web-probe CLI（五层架构）
  ├─ Layer 4: 会话管理（产物 / 日志 / 认证快照 / 自动清理）
  ├─ Layer 3: AI 智能层（Stagehand act/observe/extract）
  ├─ Layer 2.5: DevTools 桥接（chrome-devtools CLI，可选）
  ├─ Layer 2: 操作层（Playwright 25+ API）
  └─ Layer 1: 连接层（三级连接策略 / 端口管理 / 超时守护）
        │
        ▼
  用户的 Chrome（保留登录态 / Cookie / 本地存储）

命令一览

连接 & 环境

| 命令 | 说明 | |------|------| | chrome start [--auth <name>] | 连接浏览器（三级策略） | | chrome stop [--keep] | 结束会话 | | chrome status | 端口状态 | | tabs / tab new / tab close | 标签页管理 | | doctor / setup | 环境诊断 | | config set/get/list | 配置 | | skill install | Skill 注入 |

认证

| 命令 | 说明 | |------|------| | auth save <id> --name <n> | 保存认证快照 | | auth list / auth delete | 管理快照 |

精确操作（Playwright）

| 命令 | 说明 | |------|------| | click / type / key / select | 基础交互 | | hover / drag / dialog / upload / fill | 高级交互 | | wait / scroll / nav | 页面控制 | | eval / html / shot / inspect | 信息获取 | | network / console | 网络 & 控制台 | | login / login-status | 登录管理 |

AI 智能操作（Stagehand）

| 命令 | 说明 | |------|------| | act <id> "指令" | 自然语言操作 | | observe <id> | AI 分析页面 | | extract <id> "指令" | AI 提取数据 | | explore <url> | AI 自主探索 |

会话 & DevTools

| 命令 | 说明 | |------|------| | clean [--list\|--completed\|--all] | 管理历史会话 | | devtools <tool> | 桥接 chrome-devtools CLI |

所有命令支持 --json 输出 JSON 格式。

SKILL 分层

SKILL 采用三级分层，AI Agent 按需加载：

SKILL.md (Level 0)     ← 入口：场景路由（~66 行，始终加载）
├── scenarios/          ← Level 1：按场景加载工作流模板
│   ├── testing.md           自动化测试
│   ├── automation.md        浏览器操控
│   └── analysis.md          页面分析
└── reference/          ← Level 2：按需查阅参考手册
    ├── commands.md          完整命令表
    ├── connection.md        连接 & 认证
    └── devtools.md          DevTools 桥接

支持的 AI 工具

| AI 工具 | 注入方式 | |---------|---------| | Cursor / Claude Code / Codex / Agents / OpenCode | 目录递归复制 | | Windsurf / GitHub Copilot / Trae | 合并为单文件 |

web-probe skill install          # 自动检测并注入
web-probe skill install --yes    # 跳过确认

安全特性

• 三级连接策略：优先 autoConnect（零打扰），不强制重启 Chrome
• 端口随机化：20000-29999 范围随机（isolated/launch 模式）
• 自动超时：30 分钟无活动自动关闭调试端口
• localhost 限制：CDP 端口仅绑定 127.0.0.1
• 文件权限：state.json / config.json / auth 快照权限 0600
• 产物透明：会话目录 + 清单 + 日志，stop 时自动清理

技术栈

• CLI 框架：Commander.js
• 操作引擎：Playwright Core（connectOverCDP，不下载浏览器）
• AI 引擎：Stagehand（按需加载）
• DevTools：chrome-devtools-mcp CLI 桥接（可选）
• 构建：tsup（ESM 单文件，~148KB）
• 测试：vitest（36 用例）
• 语言：TypeScript

平台支持

| 平台 | 状态 | |------|------| | macOS | ✅ 完整支持 | | Linux | ⚠️ 基础支持 | | Windows | ⚠️ 实验性 |

文档

• 架构设计
• 用户指南
• 开发维护

License

MIT