Saccade Skill 技能

技能简介

Saccade 是一个专为 AI 浏览器 Agent 设计的闭环浏览器控制运行时，通过 Chrome/Edge 扩展配合 Node.js MCP 服务器，让 AI Agent 能够以语义对象而非屏幕坐标的方式操控浏览器。AI 读取当前页面的语义对象（如「搜索框」「提交按钮」），执行操作后本地验证结果，而不是反复全页截图或依赖不稳定的坐标点击。项目通过 MCP 协议与主流本地 Agent 客户端集成，MIT 许可证，当前版本 0.2.1。

核心能力

语义对象寻址

AI 不再依赖 XPath 或屏幕坐标定位元素，而是使用稳定语义标识（如「id=text-0xa3f1 的文本输入框」）进行读写，每次操作都基于当前页面的真实结构，扩展程序持续将标签页内容编译为语义对象推送给 Agent。

操作本地验证

每个操作（点击、输入、上传、导航）完成后，扩展程序在本地立即验证可见性、启用状态、几何位置和操作权限，确认操作生效后才返回操作回执，Agent 无需重新读取全页即可判断上一步是否成功。

增量状态推送（Delta 推送）

首次读取获取完整的语义工作集，之后扩展程序只推送页面变化的部分（Delta），Token 消耗大幅降低。扩展程序支持同文档无关修订的容错，避免因页面自身刷新导致的对象 ID 漂移问题。

表单批量预检

相互独立的表单字段可以预检后打包为一次批量提交，减少 AI 与浏览器的往返次数；提交、导航、上传等关键操作保持显式调用，避免自动重放带来意外副作用。

安全恢复机制

被替换的语义对象会标记为过期（Stale），Agent 可以感知对象已失效并主动重新读取；副作用不明确的操作不会自动重放，由 Agent 决定如何处理。

MCP 协议集成

通过 npx -y @nanlogic/saccade mcp 启动 MCP 服务器，扩展程序将支持的工具（tabs.list、tabs.open、truth.read、act 等）注册到 Agent 端，配置一次后可持续使用。

安装配置

环境要求

• Node.js 18 或更高版本
• Chrome 或 Edge 浏览器（安装 Saccade 扩展）
• 本地运行的 Agent 客户端（如 Claude Desktop、Cline 等）

安装步骤

第一步：安装 npm 包

npx -y @nanlogic/saccade install

第二步：运行诊断

npx -y @nanlogic/saccade doctor

诊断命令检查环境是否满足所有依赖，返回浏览器扩展就绪状态。

第三步：加载浏览器扩展

在 Chrome/Edge 中加载 extension/ 目录作为解压扩展（开发者模式 → 加载解压的扩展程序）。

第四步：启动 MCP 服务器

npx -y @nanlogic/saccade mcp

此命令在本地启动 MCP 服务器，Agent 客户端通过 stdio 连接。启动新 Agent 任务后即可使用 saccade.* 系列工具。

使用步骤

第一步：检查系统就绪

Agent 调用 saccade.system.capabilities，获取当前 Broker、扩展程序、浏览器和会话状态，确认所有组件在线。

第二步：打开目标标签页

调用 saccade.tabs.open 在授权的 Chrome/Edge 标签页中打开目标 URL，每个标签页有唯一 tab_id，支持多标签页并发隔离。

第三步：读取初始语义视图

调用 saccade.truth.read 获取当前页面的完整语义工作集，包含所有可交互对象（输入框、按钮、下拉框等）的 ID、类型、状态和内容。

第四步：执行操作并验证

根据任务需要调用 saccade.act 执行操作（如填写表单、点击按钮），扩展程序在本地完成验证后返回操作结果回执（成功/失败/副作用待确认），Agent 依据回执决定下一步。

第五步：接收增量更新

页面发生变化时（用户操作或动态内容加载），扩展程序推送 Delta，Agent 只需读取变化部分，无需重新全页抓取。

适用场景

• 登录态管理页面：Agent 在已登录的管理后台执行操作，需要稳定识别登录表单字段和提交按钮
• 长表单填写：需要跨多步完成的注册、申请、配置类表单，避免坐标点击导致的输入位置错误
• 动态内容页面：内容在 Agent 操作过程中实时变化的单页应用，需要感知而非轮询页面变化
• 富文本编辑器：same-origin iframe 编辑器内的文本操作，需要精确的语义对象而非视觉坐标
• 文件上传流程：标准文件 input 和软触发上传，需要验证 input 就绪状态而非等待固定时间

适用人群

• AI Agent 开发者：构建需要操控浏览器的本地 Agent 系统（如自动化测试、数据采集、账号管理）
• 浏览器自动化工程师：需要比 Playwright 更适合 Agent 使用习惯的语义级自动化方案
• Claude/Cline/Windsurf 用户：通过 MCP 集成扩展 AI 编程助手的浏览器操控能力

技术实现

Saccade 由两个核心部分组成：Node.js MCP 服务器（@nanlogic/saccade）和 Chrome/Edge 扩展程序（Extension）。扩展程序通过 CDP（Chrome DevTools Protocol）劫持浏览器标签页的内容脚本，持续将 DOM 编译为语义对象树，通过 WebSocket 推送给本地 Broker。MCP 服务器作为 stdio 服务端，将 Broker 的能力映射为 MCP 工具暴露给 Agent。语义对象 ID 基于 DOM 结构稳定性生成（stable object identity），即使 DOM 重排，同一对象的 ID 保持不变，这是实现「操作验证」的技术基础。与 Playwright 相比，Saccade 的设计目标是「live Agent work in a current, authorized tab」而非「reproducible browser tests」。

官方链接

• GitHub：https://github.com/nanlogic/saccade
• npm：https://www.npmjs.com/package/@nanlogic/saccade
• 官方文档：项目 README 及 docs/ 目录