webmcp-cli-wxt

WebMCP CLI (WXT 扩展桥接模式) Skill

本 Skill 指导 AI Agent 如何通过 @opentiny/webmcp-cli --mode wxt 与用户正在使用的真实 Chrome 浏览器（通过 Tiny Robot 扩展）进行双向通信与操控。

适用场景与特征

• 复用真实用户数据：直接在用户正在使用的浏览器窗口中工作，完美继承用户的登录态、Cookie、企业内网 SSO 会话、已有标签页，告别验证码和重新登录。
• 扩展与本地双向协同：
  • 本地 Agent 可直接操控浏览器中的网页；
  • 浏览器扩展在遇到需本地环境的任务时，可通过 WebSocket 桥接安全请求本地执行 bash 指令或选择目录。
• 高层子代理委托 (agent run)：除了单步交互，可直接将高层任务整包委托给扩展内的 Tiny Robot 自主多轮执行。
• 标识特征：
  • 必须携带模式参数：webmcp-cli --mode wxt <command>（或在终端设置环境变量 export WEBMCP_MODE=wxt）；
  • Tab ID 格式为 纯数字（Chrome Tab ID，如 1024）；
  • 依赖用户已安装并启用 Tiny Robot 扩展。

安装

当 shell 终端提示找不到工具时执行：

npm install -g @opentiny/webmcp-cli

---

快速准备与前置排查

1. 认证 Token 与配对

CLI 与扩展之间通过 Token 进行安全鉴权，默认保存在 ~/.robot-wxt/bridge-token。

# 查看当前本地 Token（若扩展未连接，可将输出的 Token 配置到扩展设置中）
webmcp-cli --mode wxt token

# 将已有的扩展 Token 同步到本地
webmcp-cli --mode wxt token set <你的Token>

2. 后台守护进程（Daemon）

无需手动启动服务，执行任何 WXT 命令时 CLI 会自动拉起后台 WebSocket 桥接进程（监听 127.0.0.1:18999）。 如需手动释放端口或停止后台服务：

webmcp-cli --mode wxt stop

3. 连接异常排查

若执行命令报连接超时或等待扩展连接，请指导用户：

1. 检查 Chrome 右上角是否已安装并启用 Tiny Robot 扩展；
2. 确认扩展弹窗中的 Bridge Token 是否与 webmcp-cli --mode wxt token 一致。

---

交互模式一：高层子代理委托 (agent run) — 推荐

对于复杂、跨步骤的开放式任务（如“帮我查一下上个月的订单并导出报表”、“把该商品加入购物车”），优先整包委托扩展自主执行，无需本地逐行编写点击代码：

# 委托扩展内的 Tiny Robot 自主执行
webmcp-cli --mode wxt agent run "帮我把购物车中的第一个商品结算"

# 限制最大步数自主执行
webmcp-cli --mode wxt agent run --max-steps 10 "搜索最新的 TinyVue 实战教程"

# 针对指定页签执行
webmcp-cli --mode wxt agent run --tab 1024 "审批当前页面的加班申请，意见填同意"

---

交互模式二：细粒度自主交互（标准流程）

1. 状态感知与标签页管理

# 查询当前活跃标签页与可用工具
webmcp-cli --mode wxt state

# 查询指定标签页（注意：WXT 模式下 Tab ID 必须为纯数字）
webmcp-cli --mode wxt state --tab 1024

# 标签页操作
webmcp-cli --mode wxt tabs open "https://console.cloud.example.com"
webmcp-cli --mode wxt tabs switch 1024
webmcp-cli --mode wxt tabs close 1024
webmcp-cli --mode wxt tabs back
webmcp-cli --mode wxt tabs forward

2. 页面元素感知与操作 page-agent-tool