Skip to content
实践案例

辅助前端开发 ​

这篇案例把 CLI WebSocket 桥接 和 DOM 元素选取 串成一次修改页面的流程。桥接让侧边栏能在你本机的前端工程里查看和修改文件;DOM 元素选取把页面上点中的那一个控件交给 AI,带上它当时的路径、属性、计算样式和文案。两者配合,就可以对照已经运行的本地页面指定要修改的区域,由 AI 修改工程里的源码。

两个功能的开关、白名单和命令防护,分别见 CLI WebSocket 桥接 与 DOM 元素选取。本文介绍如何配合这两个功能修改本地页面。

实践目的 ​

  1. 如何连接 CLI WebSocket 桥接,并把本地前端工程绑成当前会话的工作空间。
  2. 如何在本地页面上进入 DOM 选区,把选中元素的信息放进侧边栏。
  3. 如何根据选中元素的信息修改本地源码,再回到页面核对结果。

开始之前 ​

  • 扩展已经安装,并且已经登录。未登录时不能发起对话。
  • 本机可以运行 npx(需要 Node.js),以便完成桥接配对。
  • 本地已有一份前端工程,开发服务已在你自己的终端里启动,页面能在浏览器中打开。常见地址是 http://localhost:5173 或 http://127.0.0.1 上的某个端口。
  • CLI WebSocket 桥接 与 DOM 元素选取 默认都是关闭的,需要在功能管理里打开。

开发服务请保持在你自己的终端里运行。桥接上的单次命令大约 30 秒就会超时,用来长期挂着开发服务不合适。桥接负责查看和修改这个工程里的文件。

WARNING

桥接接通之后,AI 可以在你的电脑上执行命令。请只绑定你信任的工程目录。

实践步骤 ​

步骤一:开启两个功能 ​

  1. 打开配置页:侧边栏左下角的设置齿轮,或悬浮球右键菜单中的「设置」。
  2. 在「功能管理」中打开 CLI WebSocket 桥接 卡片右上角的开关。
  3. 在同一页打开 DOM 元素选取 的开关。

两个开关写入扩展存储后即时生效,不必为了开关本身刷新网页。开启桥接后,侧边栏顶部会出现 WS 状态徽章,输入区会出现工作空间按钮。开启 DOM 元素选取后,悬浮球左键菜单会多出「DOM 元素选取」。

功能管理中同时开启 CLI WebSocket 桥接与 DOM 元素选取

本地页面的主机名若是 localhost 或 127.0.0.1,DOM 选区的默认白名单已经覆盖,这一步不用改配置。开发服务若挂在自定义主机名上(例如 my-app.test),打开 DOM 元素选取卡片上的设置,把该主机名写入生效域名白名单,点击保存配置,然后刷新开发页。匹配只看主机名,不看端口:写上 localhost 后,http://localhost:3000 与 http://localhost:5173 都会生效。

步骤二:连接桥接,并绑定工程目录 ​

  1. 回到侧边栏,将鼠标移到顶部的 WS 待连接 徽章上,展开「本地WebSocket桥接」面板。
  2. 点击复制CLI设置命令。剪贴板中的命令形如 npx @opentiny/webmcp-cli --mode wxt token set <Token>。
  3. 在本机终端执行这条命令。它会写入连接凭据,并拉起 127.0.0.1:18999 上的桥接服务。
  4. 徽章变为 WS 已连接。若仍停在「WS 待连接」,在面板中点击重新连接。
  5. 点击输入区的工作空间按钮(或面板里的选择本地文件夹),在系统对话框中选中前端工程的根目录,也就是包含 package.json 的那一层。
  6. 按钮上的文字变成该目录的名称,悬停面板的标记为「已绑定目录」。之后这个会话里的本地命令都从这里开始执行。

未进入具体会话时选择的文件夹,会作为之后新建会话的预设;在某个会话里更改的文件夹,只对这个会话生效。同一次修改请留在同一个会话里完成,避免命令在另一个目录中执行。

桥接已连接,且当前会话已绑定本地前端工程

配对、Token 和命令防护的完整说明见 CLI WebSocket 桥接。

步骤三:在页面上点选要改的元素 ​

  1. 在浏览器中打开正在运行的本地页面,确认地址栏里的主机名在 DOM 选区白名单内。
  2. 用下面任一方式进入选区:
    • 左键点击悬浮球,选择「DOM 元素选取」。
    • 快捷键:Mac 为 ⌥⇧C,Windows / Linux 为 Alt+Shift+C。
  3. 鼠标变为十字光标后,单击要修改的控件,例如一个按钮、一段标题或一张卡片。请点到具体控件上。
  4. 侧边栏打开,输入框上方出现一枚元素标签,上面显示标签名,例如 <button>。
  5. 将鼠标悬停在这枚标签上,可以查看这次快照里的 PATH、ATTRIBUTES、COMPUTED STYLES、INNER TEXT 等段落。ATTRIBUTES 里的类名和 INNER TEXT 里的文案,是之后让 AI 在工程中定位源码的主要线索。
  6. 需要对照的控件可以连续点选,例如先点按钮、再点它旁边的标题。同一元素再点一次不会重复添加标签。
  7. 按 Esc 退出选区。已经放进输入框的标签会保留。

在本地页面点选控件,输入框出现元素标签

PATH 是页面上的结构路径,用来说明元素在 DOM 里的位置,并不是源码文件路径。AI 会根据标签名、类名和文案,到已绑定的工程目录里查找对应文件。

TIP

COMPUTED STYLES 是点选那一刻浏览器算出的当前样式,用来说明现在的呈现效果。修改意见里写清目标样式,并让 AI 修改工程里对应的类名、设计变量或组件样式。

步骤四:写下修改意见并发送 ​

在元素标签后面直接写要修改的内容,然后发送。元素信息会排在前面,你的修改意见紧随其后。一次选中多个元素时,这段意见会分别作用在每一个元素上。即使只有标签、没有文字也可以发送;写清修改意见,更容易得到预期结果。

可以这样说:

把这个区域的背景色改成橙色 #ff7a1a,请直接修改当前工作空间里的源码。

发送之后,AI 通过工具 execute_host_bash 在已绑定的目录里查找和修改文件。默认的智能沙箱会直接放行 ls、cat、grep 这类只读命令,以及白名单中的 pnpm test、git status、git diff 等。会修改文件的命令需要确认后才会执行,卡片标题为「安全拦截确认:是否允许执行该 Bash 命令?」。

元素标签与修改意见

确认时三选一:

选择结果
允许本次执行只放行这一次,相同命令下次仍要确认
始终允许该 Bash 命令把这一条命令写入免审批白名单。多行脚本、命令替换,或用 > 覆盖文件时,没有这一项
拒绝执行终止这次命令,并把拒绝原因交回给 AI

看清命令作用在已绑定的工程目录里、并且确实是在改你要点的那处源码之后,再点允许。系统红线(例如删除根目录)在任何防护模式下都不会执行。防护模式和白名单的细则见 CLI WebSocket 桥接 · 配置。

步骤五:核对页面修改效果 ​

修改源码后,AI 不一定会主动核对页面。需要它核对时,在修改意见里写上「改完后检查页面」。下面的截图来自一次实际运行:AI 在改完源码后又查看了正在运行的本地页面。

这次运行使用了页面工具,对话里留有记录。另一种方式是网页子 Agent。两者的分工见 扩展与 MCP:

  • 网页子 Agent web_page_operator:接到「去页面上看看改好了没有」这类指令后,在目标标签页上分多步查看。执行期间页面会出现操作遮罩和模拟光标,对话里按步骤展示每一次动作。
  • 页面工具 page-agent-tool:它的动作里没有单独的「读取计算样式」,可以通过 executeJavascript 在页面中执行脚本获取样式。这次运行读到 section#center 的 backgroundColor 是 rgb(255, 122, 26),也就是 #ff7a1a。

开发服务开启热更新时,保存后页面会自动更新;没有热更新时,先刷新该页再让 AI 读取,读到的才是最新样式。

你也可以自己在浏览器里查看页面。效果还不对时,留在同一个会话里继续说明,例如「背景色已经变了,再换成 #1677ff,只改这一块」。输入框里的标签记录的是点选那一刻的快照。页面变化之后如果要按最新页面再改,先关掉旧标签,重新进入选区再点一次。

本地页面背景已变为橙色,对话中用 page-agent-tool 核对计算样式

常见问法 ​

想做的事可以这样说
改文案点中该元素后:「把这段文案改成『提交申请』,只改文案。请修改当前工作空间里的源码。」
改背景色悬停标签看过计算样式后:「把这块背景改成 #ff7a1a,其余样式不动。请修改当前工作空间里的源码,改完后检查页面。」
让两处对齐连续点选两个元素后:「让第一个输入框和第二个按钮左对齐,两者间距 12px。」
只查不改「先告诉我这个元素对应工程里的哪个文件、哪一段样式,先不要改文件。」

常见问题 ​

  • 侧边栏没有 WS 徽章,也没有工作空间按钮:在「功能管理」中确认 CLI WebSocket 桥接 已经开启。
  • 徽章一直是「WS 待连接」:在终端执行面板里复制的 CLI 设置命令,再点重新连接。本机需要能运行 npx。
  • 点了工作空间却选不出文件夹:文件夹选择对话框由本地 CLI 打开。请先确认徽章已经是 WS 已连接。
  • AI 改的不是这份工程:查看输入区工作空间按钮上的目录名,悬停可核对完整路径。每个会话可以单独绑定;未绑定时,命令在 ~/.robot-wxt/workspaces/<会话 ID>/ 下执行。
  • 悬浮球菜单里没有「DOM 元素选取」:在「功能管理」中确认该开关已开启。悬浮球被隐藏时,先到 悬浮球设置 恢复显示。
  • 点了菜单却提示不在白名单:把开发页的主机名加进 DOM 元素选取的生效域名白名单,保存后刷新该页。localhost 与 127.0.0.1 默认已在名单内。
  • 点了元素,输入框没有标签:确认已经进入选区(悬浮球变为任务胶囊)。浏览器拦截剪贴板写入时,标签也不会出现。超过约 1 分钟才打开侧边栏时,该次点选会被丢弃,需要再点一次。
  • 源码改了,页面没有变化:确认开发服务仍在运行,并刷新页面。对话里若停在命令确认且选择了拒绝,文件不会被修改。热更新没有生效时,以刷新后的页面为准。
  • AI 只在对话里给出了代码,没有改本地文件:在同一会话里补一句「请直接修改当前工作空间中的文件」,并确认工作空间按钮上是这份工程的目录名。

相关链接 ​