CraftStation 浏览器与电脑操控能力完全指南:Browser 与 Computer Use 工具接入详解
CraftStation 浏览器与电脑操控能力完全指南:Browser 与 Computer Use 工具接入详解
CraftStation 是一个开源的 Agent Runtime Composition System(Agent 运行时组合系统),除了写代码之外,它还内置了三大"手眼"能力:Browser(应用内浏览器操控)、Chrome(驱动你真实的 Chrome/Brave/Edge 浏览器) 和 Computer Use(macOS/Windows 桌面点击、输入与截图)。本文用一篇指南讲清楚这三套工具的接入方式、核心命令清单和安全开关,新手照着做即可上手 🚀
一图看懂:Agent 如何"看见"并"操作"你的环境
CraftStation 把浏览器与桌面操控做成了三个独立的 MCP 服务器(MCP = Model Context Protocol,大模型调外部工具的标准协议):
| 能力 | MCP 服务器名 | 控制对象 | 典型场景 |
|---|---|---|---|
| 应用内浏览器 | browser |
CraftStation 内置浏览器面板 | 网页测试、表单填写、截图验证 |
| 真实浏览器 | chrome |
你正在使用的 Chrome/Brave/Edge | 复用已登录的网页会话 |
| 桌面操控 | computer_use |
主机上的原生桌面应用 | 点击、打字、滚动、拖拽、窗口截图 |
三者的代码入口分别是:
- 内置浏览器工具注册表:src/main/browser/mcp/toolRegistry.ts
- 外部 Chrome 驱动工具:src/main/browser/external/chromeTools.ts
- 桌面操控工具注册表:src/main/computer-use/mcp/toolRegistry.ts
一、Browser:内置浏览器操控工具清单
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 与 refscreenshot:支持整页、视口或按 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) → 你的标签页
一键安装步骤
- 打开
chrome://extensions(Brave/Edge 同理),开启开发者模式 - 点击 Load unpacked(加载已解压的扩展),选择仓库中的 chrome-extension/ 目录
- 完成 —— 无需配对、无需填端口。扩展会自动连接运行中的 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 的行为视为你本人的操作
三、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):
- 点击/滚动/拖拽的坐标以窗口左上角为原点(含标题栏),与最近一次
get_window_state截图的左上角像素一一对应 - 截图若被缩放过,返回的 notes 会附带缩放系数,Agent 需把截图像素坐标除以系数再发送
- 窗口一旦移动/缩放导致失效,会提示重新
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专门留给没有网页形态的原生桌面应用
四、怎么开启:在输入框的"+"菜单里勾选
三套能力都遵循"按线程注入"原则:不是全局强加,而是你在某个对话线程里显式启用才生效。
- 在任意线程的输入区(Composer)点击 "+" 添加菜单
- 勾选 Browser、Chrome 或桌面操控开关(注册逻辑见 src/renderer/components/composer/composerMcpServers.ts#L101-L138)
- 输入区会出现对应的小徽章(MCP chip),再次点击即可移除
- 涉及
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 工作区的意义所在 ✨


