CraftStation 浏览器与电脑操控能力完全指南:Browser 与 Computer Use 工具接入详解

原创2026-10-27 15:16:461,833 阅读

CraftStation 浏览器与电脑操控能力完全指南:Browser 与 Computer Use 工具接入详解

CraftStation 是一个开源的 Agent Runtime Composition System(Agent 运行时组合系统),除了写代码之外,它还内置了三大"手眼"能力:Browser(应用内浏览器操控)、Chrome(驱动你真实的 Chrome/Brave/Edge 浏览器) 和 Computer Use(macOS/Windows 桌面点击、输入与截图)。本文用一篇指南讲清楚这三套工具的接入方式、核心命令清单和安全开关,新手照着做即可上手 🚀

CraftStation 首页与统一 Agent 输入区,展示浏览器与电脑操控工具入口

一图看懂:Agent 如何"看见"并"操作"你的环境

CraftStation 把浏览器与桌面操控做成了三个独立的 MCP 服务器(MCP = Model Context Protocol,大模型调外部工具的标准协议):

能力 MCP 服务器名 控制对象 典型场景
应用内浏览器 browser CraftStation 内置浏览器面板 网页测试、表单填写、截图验证
真实浏览器 chrome 你正在使用的 Chrome/Brave/Edge 复用已登录的网页会话
桌面操控 computer_use 主机上的原生桌面应用 点击、打字、滚动、拖拽、窗口截图

三者的代码入口分别是:

一、Browser:内置浏览器操控工具清单

CraftStation 内置浏览器面板:Agent 可直接浏览、点击与截图

browser MCP 服务器内置了 30 多个细粒度工具,完整定义见 src/main/browser/mcp/tools/specs.ts。按用途分组后大致是:

1. 会话与标签页管理

  • browser.enable / browser.disable:开启/结束一次不间断的浏览器会话(这是官方推荐的第一步和最后一步)
  • list_tabs、new_tab、open、navigate、activate_tab、close_tab、back、forward、reload、get_url、get_title:标签页与导航

2. 页面感知(先"看"后"动")

  • snapshot / inspect:返回页面上可见交互元素的结构化快照(角色、名称、文本、@e 引用),官方指令明确要求"优先用 snapshot 或 find,再去 click/fill/type"
  • find:按可访问性属性查找元素(role、name、placeholder、text 等),返回可直接使用的 selector 与 ref
  • screenshot:支持整页、视口或按 CSS 选择器裁剪截图
  • query、get、is、frames:读元素文本/属性/状态、查看 iframe 树

3. 页面交互

  • click、dblclick、hover、focus、press(按键,如 Enter、Tab)
  • type(追加输入)、fill(清空后填入)、check / uncheck、select(下拉选择)
  • scroll(滚动到指定元素)、wait / wait_for / wait_for_text / wait_for_url(等待条件成立,避免"盲猜延迟")

4. 调试与数据

  • console:读取页面最近的 console 与异常输出
  • requests:查看最近的网络请求(URL、状态码、耗时、大小)
  • dialog:自动应答 alert/confirm/prompt 弹窗
  • eval、cookies、storage:执行 JS、读写 Cookie 与 localStorage —— 这三类默认关闭,需要手动开启权限开关

💡 官方给 Agent 的标准工作流写在 src/main/browser/mcp/tools/specs.ts#L3-L4:先 enable → snapshot/find 定位元素 → click/fill 操作 → 暂停或结束前 disable。

二、Chrome 扩展:三步驱动你"真实"的浏览器

内置浏览器是干净的"沙盒",但很多任务需要你已登录的真实会话(比如已登录的管理后台)。这时 chrome MCP 服务器 + 配套 Chrome 扩展就派上用场,架构是:

Agent → chrome MCP(CraftStation)→ 本机 WebSocket → 扩展 → chrome.debugger (CDP) → 你的标签页

一键安装步骤

  1. 打开 chrome://extensions(Brave/Edge 同理),开启开发者模式
  2. 点击 Load unpacked(加载已解压的扩展),选择仓库中的 chrome-extension/ 目录
  3. 完成 —— 无需配对、无需填端口。扩展会自动连接运行中的 CraftStation,popup 显示绿色 Connected 即成功

详细机制说明见 chrome-extension/README.md。

常用调用顺序

让 Agent 试试:"用 chrome 工具检查连接状态,列出我的标签页,然后截图当前活动标签页。" 典型调用链是 chrome_status → chrome_list_tabs → chrome_attach → chrome_snapshot / chrome_screenshot(工具定义见 src/main/browser/external/chromeTools.ts#L350-L420)。

安全设计(重要)

  • WebSocket 只绑定 127.0.0.1,且只接受浏览器扩展来源的请求,网页无法直连
  • 被驱动的标签页会出现 Chrome 原生的 "CraftStation started debugging this browser" 横幅 —— 它就是你的知情同意 + 急停开关,随时可停止
  • chrome_eval、chrome_cookies 与内置浏览器共享同一套 eval/数据访问开关,默认关闭
  • 它驱动的是你的已认证浏览器,请始终把 Agent 的行为视为你本人的操作

CraftStation 桌面工作区整体界面

三、Computer Use:让 Agent 点击、打字和截图桌面应用

computer_use MCP 服务器把 macOS 与 Windows 上的原生应用变成 Agent 可操作的对象(macOS 实现基于 System Events,见 src/main/computer-use/drivers/macos.ts;Windows 有独立驱动与真机 GUI 测试 src/main/computer-use/windowsRealGui.e2e.test.ts)。

核心工具清单

工具 作用 模式
list_apps / list_windows 列出可操作的应用与窗口 被动(不抢焦点)
get_window_state 截取指定窗口截图(默认 JPEG、最长边 1280px),可选读取辅助文本 被动
launch_app 按名称或路径启动应用 交互
activate_window 把窗口带到前台 交互
click / press_key / type_text 点击(支持左右键)、按键组合、输入文本 交互
scroll / drag 滚动、拖拽 交互
enable / disable 开启/结束一次不间断操控会话,控制桌面覆盖层显隐 会话

坐标与截图:为什么不会点错位置

这是桌面操控最容易翻车的地方,CraftStation 做了严格约定(说明见 src/main/computer-use/mcp/toolRegistry.ts#L32-L33):

  1. 点击/滚动/拖拽的坐标以窗口左上角为原点(含标题栏),与最近一次 get_window_state 截图的左上角像素一一对应
  2. 截图若被缩放过,返回的 notes 会附带缩放系数,Agent 需把截图像素坐标除以系数再发送
  3. 窗口一旦移动/缩放导致失效,会提示重新 list_windows / get_window 获取新 id 后重试

你能直观看到 Agent 在做什么

操控进行时,桌面会出现带 CraftStation 徽标的指针动画,标识"这是 Agent 的鼠标";每次点击、滚动、拖拽结束后,你的光标会自动恢复(覆盖层实现见 src/main/computer-use/ComputerUseDesktopOverlay.ts)。Agent 在窗口间来回切换、操作真实鼠标键盘时,你始终能看到它"手"在哪里 👀

边界与红线

  • 服务只绑定本机回环地址 127.0.0.1(见 src/main/computer-use/ComputerUseMcpIngress.ts#L38-L45),外部网络无法调用
  • 锁定屏幕、系统安全提示、权限弹窗、密码/认证输入框必须由你亲自操作
  • 网页操作优先用 browser 工具,computer_use 专门留给没有网页形态的原生桌面应用

四、怎么开启:在输入框的"+"菜单里勾选

三套能力都遵循"按线程注入"原则:不是全局强加,而是你在某个对话线程里显式启用才生效。

CraftStation 首页合成台与模型选择界面

  1. 在任意线程的输入区(Composer)点击 "+" 添加菜单
  2. 勾选 Browser、Chrome 或桌面操控开关(注册逻辑见 src/renderer/components/composer/composerMcpServers.ts#L101-L138)
  3. 输入区会出现对应的小徽章(MCP chip),再次点击即可移除
  4. 涉及 eval、cookies、localStorage 的高危工具,还需在 设置 → Browser 中额外打开权限开关,双重把关

对于 WSL 远程项目等场景,Chrome 会自动标记为不可用(chromeMcpServer.isAvailable),避免误配置。

五、常见问题 FAQ

Q1:Agent 一直点不到元素怎么办? 先让它 snapshot 或 find 拿最新的 @e ref,再操作;页面异步刷新后旧 ref 会失效,重新取一次即可。

Q2:内置浏览器和 Chrome 扩展怎么选? 要干净环境、无登录态的自动化 → 用 browser;要复用你真实浏览器的账号和 Cookie → 用 chrome 扩展(注意其安全提示横幅)。

Q3:Computer Use 会乱动我的鼠标吗? 它确实会驱动真实鼠标键盘,但每次交互动作后光标都会交还给你;看到带徽标的指针动画即代表 Agent 正在操作,disable 会立即结束会话并隐藏覆盖层。

Q4:这套能力支持哪些平台? Computer Use 提供 macOS 与 Windows 双驱动;Chrome 扩展支持 Chrome/Brave/Edge;Windows 安装包开箱即用(详见 README.zh-CN.md)。

写在最后

CraftStation 的哲学是"你的模型、你的 Harness、你的 Agent":浏览器、真实 Chrome、桌面应用三种"手眼"都以 MCP 标准暴露给任意兼容的 Agent 运行时,按线程按需注入、默认最小权限。从 browser.enable 到 computer_use.click,你只需要勾选开关,然后把任务交给 Agent 即可 —— 这正是组合式 Agent 工作区的意义所在 ✨

登录后查看全文
CraftStation