Weavetab

---

Weavetab 是面向 AI Agent 的开源自动化引擎。它通过原生 Chrome DevTools Protocol (CDP) 套接字，将模型直接连接到运行中的 Chromium 浏览器和 Electron 桌面应用，无需 WebDriver 二进制文件、无需云中继，也不收集任何遥测数据。

操作执行延迟低于 10 ms。网页会被转换为 Agent 可读的语义映射，并通过逐轮差异对比将令牌用量最多降低 95%。内置安全机制可强制执行本地域策略、基于角色的访问控制和客户端凭据注入。

由 fy2ne 构建并设计架构。

---

为什么不选 Playwright 或 Puppeteer？

标准方案——通过 MCP 使用 Playwright——确实可行。但它存在根本性的架构成本，规模越大，累积影响越明显。

	Playwright / Puppeteer	Weavetab
协议层	通过浏览器二进制文件使用 WebDriver BiDi 或 CDP	原始 CDP WebSocket，第 0 层
工具执行延迟	50–300 ms（二进制文件 + IPC 开销）	3–8 ms
桌面应用控制	仅限浏览器	Chrome + 任意 Electron 应用（Discord、VS Code、Figma…）
DOM 表示方式	向大模型输出完整 HTML	Semantic Map 3.0，支持增量差异对比
每个映射的令牌成本	~2,000–8,000 个令牌	~80–400 个令牌（通过增量差异降低 95%）
CAPTCHA	需要 API 服务	通过 CDP 鼠标轨迹模拟实现零 API
凭据安全	以明文传递机密信息	盲注入——绝不进入大模型上下文
扩展程序访问	受限	完整的 Chrome 扩展 API 接口

---

架构

MCP Client (Claude / Cursor / Antigravity / Copilot / Windsurf)
       |
       |  JSON-RPC 2.0  (stdio or WebSocket 127.0.0.1:3000)
       v
+-------------------------------------------------------------+
|                   Weavetab MCP Server                       |
|                                                             |
|  +-----------------+   +---------------------------------+  |
|  | Security Layer  |-->|  Intelligence Engine            |  |
|  | Rate · RBAC     |   |  Map 3.0 · Delta · Memory       |  |
|  | Policy · Audit  |   |  Pruner · Framework Detector    |  |
|  +-----------------+   +----------------+----------------+  |
|                                         |                   |
|                              +----------v----------------+  |
|                              |  CDP Bridge               |  |
|                              |  Ghost Cursor · Typing    |  |
|                              |  App Router · Loop Guard  |  |
|                              +----------+----------------+  |
+-------------------------------------------------------------+
                                          |  CDP WebSocket (127.0.0.1)
              +---------------------------+-----------------------------+
              v                           v                            v
       Chrome / Edge               VS Code / Discord          Your Electron App
       (any tab)                   (Electron apps)            (local dev)

无云服务，无外部进程。CDP WebSocket 连接和可选的 MCP WebSocket 守护进程（--ws）都严格绑定到 127.0.0.1，并通过共享密钥进行身份验证（~/.weavetab-system/ws-secret），同时验证 Origin/Host 请求头。

---

快速开始

npx -y @weavetab/mcp

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": ["-y", "@weavetab/mcp"]
    }
  }
}

客户端	配置路径
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	claude mcp add weavetab -- npx -y @weavetab/mcp
Cursor	.cursor/mcp.json
Antigravity	~/.gemini/antigravity/mcp/weavetab/
VS Code Copilot	.vscode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json

---

核心技术

语义地图 3.0

基于浏览器的 Agent 面临的主要瓶颈是 DOM 表示。完整的 HTML 转储冗长、庞大，对大模型而言也没有明确的结构意义。Weavetab 的 browser_map 会运行一个浏览器内 CDP 遍历器，生成精简的语义地图：

╔═ ACTIVE DIALOG: "Confirm Payment" ═╗
  [w:3] button "Confirm"  [w:4] button "Cancel"

┌ "Pro Plan — $49/mo"
  [w:12] button "Upgrade"   [w:13] button "View Details"
  [w:14] input val:"[email protected]"  ph:"Email address"  FOCUSED

[w:20...w:38] 18 nav links: "Dashboard" ... "Sign out"

主要特性：

• 引用 ID（w:N）在会话期间保持稳定，供所有交互工具使用
• 容器绑定——按钮和输入框按其父卡片、行或分区标题分组
• 弹窗置顶——打开的对话框会单独置于顶部，确保 Agent 不会漏看
• 链接折叠——将重复的导航栏／页脚中连续出现的 4 个或更多链接压缩为单个令牌行
• 语义差异——重新读取时，仅传输发生变化的节点（~ 已修改，+ 已添加，− 已移除），最多可将重新读取成本降低 95%

幽灵光标

点击不会作为合成 DOM 事件分发，而是通过一系列物理 Input.dispatchMouseEvent CDP 调用发送，沿着贝塞尔曲线轨迹移动，并带有随机加速度、自然抖动和按压时长。用于标记基于事件的自动化的反机器人指纹检测不会触发。

browser_pointer 支持 hover_chain，可在一次工具调用中遍历多级菜单：

{
  "hover_chain": ["File", "Export As", "PNG"],
  "click_final": true
}

盲注入凭据

browser_type_secret 会在服务端从 ~/.weavetab/secrets.json 解析密钥。解析后的值绝不会包含在 MCP 响应中，也不会出现在 DOM 快照中，并且在所有审计日志中始终会被遮蔽为 [REDACTED]。大模型上下文永远不会看到凭据。

weavetab secrets set GITHUB_TOKEN
# Stored. Never echoed, never logged, never surfaced to the agent.

Electron 与桌面应用自动化

任何工具都接受可选的 app 参数，可将命令路由到已注册的 Electron 进程，而不是浏览器标签页：

{ "app": "discord", "ref": "w:24", "text": "Hey, deploying now" }

在 ~/.weavetab/config.json 中注册应用：

{
  "electron": {
    "discord":  "C:\\Users\\<user>\\AppData\\Local\\Discord\\Discord.exe",
    "vscode":   "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
    "figma":    "C:\\Users\\<user>\\AppData\\Local\\Figma\\Figma.exe"
  }
}

Weavetab 会通过 CDP 自动连接到已注册的进程。目标应用无需修改代码。

零 API 验证码求解

browser_captcha 通过编排模拟人类行为特征的 CDP 鼠标事件来解决 Cloudflare Turnstile、reCAPTCHA v2/v3、GeeTest 和 hCaptcha——包括速度曲线、微暂停和滚动惯性——无需第三方 API、外部服务或 API 密钥。

---

工具套件

9 个类别共 41 个工具。完整参数参考：docs/tools/tools.md

类别	工具
视觉与 DOM	browser_map browser_find browser_scrape browser_inspect browser_snapshot browser_screenshot browser_console browser_extract_design
输入与交互	browser_click browser_type browser_type_secret browser_key browser_pointer browser_select browser_fill browser_upload browser_scroll
导航与环境	browser_navigate browser_tabs browser_detect browser_viewport browser_emulate
任务与自动化	browser_burst browser_automation browser_recording browser_pattern_learn
安全与人工监督	browser_dialog browser_thoughts browser_clipboard browser_wait
自主验证码求解	browser_captcha
网络与存储	browser_network_intercept browser_storage browser_cookies browser_checkpoint browser_performance
Office 文档	browser_office
画布与求值	browser_eval browser_pdf browser_canvas browser_highlight

---

安全性

• 传输：CDP WebSocket 和 MCP WebSocket 守护进程（--ws）均严格绑定到 127.0.0.1，并通过 256 位共享密钥 Bearer/握手认证以及 Origin/Host 验证。不会在外部接口上监听。
• 策略引擎：在 ~/.weavetab/config.json 顶层的 policies 数组中配置按域名划分的 allow / read-only / deny / audit 规则（默认阻止 *.bank.* 和 paypal.com）
• RBAC：五种角色——operator（默认）、viewer（权限最低的只读角色）、automation、system、admin——强制执行工具级权限门控
• 插件信任与清单：三级验证（@weavetab/* 官方插件、已验证的注册表允许列表，以及对未经验证的包进行强制交互式确认并检查 weavetab.json 权限清单）
• 盲注入：凭据在服务端解析，并在所有输出和审计日志中屏蔽
• 循环断路器：基于违规次数的卡死循环检测器会停止失控的自主序列
• 审计日志：所有工具调用、策略决策和错误都会写入 ~/.weavetab-system/logs/mission_<timestamp>.log

安全漏洞请发送至：[email protected]（请勿通过公开议题报告）。

---

CLI 参考

weavetab                        # Start in stdio mode (default)
weavetab --ws --port 3000       # WebSocket daemon mode (bound to 127.0.0.1)
weavetab config                 # Interactive configuration wizard
weavetab secrets set KEY_NAME   # Store a secret (never echoed)
weavetab secrets list           # List stored secret keys (not values)
weavetab plugin add <name>      # Install a verified/confirmed plugin
weavetab plugin list            # List installed plugins

配置文件：~/.weavetab/config.json

{
  "browserType": "chromium",
  "headless": false,
  "extension": true,
  "maxActionsPerMinute": 60,
  "role": "operator",
  "electron": {
    "discord":     "...",
    "vscode":      "...",
    "antigravity": "..."
  }
}

---

可扩展性

Weavetab 提供类型化插件 SDK，可用于编写自定义 MCP 工具、HUD 覆盖层和工具生命周期钩子：

npx @weavetab/sdk init my-plugin

有关架构、清单规范和 SDK API 参考，请参阅 docs/PLUGINS.md。

---

许可证

AGPL-3.0-only。通过 stdio 或 WebSocket 建立的客户端连接，不会将 copyleft 义务延伸至你的客户端应用或模型。

赞助开发  ·  讨论  ·  SUPPORT.md