给 AI 一双手：用 webmcp-cli-skill 让大模型直接操控浏览器

「帮我打开网页、登录系统、把这个表单填完。」如果这句话是对 AI 说的，你第一反应多半是：得给 AI 接一个浏览器 API，或者写一堆自动化脚本。其实还有一条不用写代码的路——把一份 Markdown 说明书喂给 AI 当系统提示词，它就能自己在终端里打开 Chrome、找到输入框、点击按钮。这篇文章就用「AI 替你登录一个系统」这个例子，把这条链路完整走一遍。你能照着复现，也能看懂它每一步在做什么。

先理解：大脑、手和操作手册

很多人把「让 AI 操作浏览器」理解成「调一个大模型 API」。webmcp-cli-skill 走的是另一条路：AI 不直接操作浏览器，它操作的是命令行工具，工具再控制 Chrome。整条链路里只有三个角色：

角色	职责	类比
AI 大模型（DeepSeek、通义千问、ChatGPT 等）	理解用户意图、决定下一步执行哪条命令	大脑
webmcp-cli	在终端里控制 Chrome 的命令行工具	手
webmcp-cli-skill（SKILL.md）	告诉 AI 有哪些命令、参数怎么写、有哪些操作规范	操作手册

关键在于：AI 全程在终端里执行命令，不需要额外的 API 对接。SKILL.md 详细描述了 webmcp-cli 的命令格式、参数说明和操作规范，AI 读完就能照着执行。这份 SKILL.md 位于 opentiny/webmcp-sdk 仓库的 packages/webmcp-cli-skill/SKILL.md（当前版本 1.2.0，配套的 @opentiny/webmcp-cli npm 最新版为 0.0.6）。

前置准备：三样东西

动手前把三样东西备齐，缺一样链路就断：

1. 安装 webmcp-cli（手）。多数环境已经装好，只有终端提示找不到工具时才执行：

   npm install -g @opentiny/webmcp-cli
   

2. 拿到 SKILL.md（操作手册）。从 opentiny/webmcp-sdk 的 packages/webmcp-cli-skill/SKILL.md 获取；如果通过 npm 安装 skill 包，文件在 node_modules/@opentiny/webmcp-cli-skill/SKILL.md。

3. 准备一个支持系统提示词的 AI Agent。DeepSeek、通义千问、ChatGPT、Cursor 等都可以，具体接入方式放到后面讲。

准备就绪后，AI 与浏览器的对话只围绕一组命令展开，这就是下一节的核心循环。

核心循环：四步，重复到完成

webmcp-cli 的操作循环可以浓缩成四步：打开页面 → 确认状态 → 定位元素 → 交互并看变化，重复直到任务完成。

第 1 步：打开页面

webmcp-cli tabs open https://excalidraw.com

tabs open 是唯一一个不需要先执行 state 就能直接运行的命令，它会启动 Chrome 并打开目标页面。

第 2 步：确认状态

webmcp-cli state

state 返回当前浏览器的导航元数据：url、title、activeTabid、webmcpTools（已注入的 MCP 工具列表）和所有已打开的标签页 tabs。state 不返回页面 DOM 内容——它只告诉你「这个页面有哪些工具可用」，不告诉你「页面上有哪些按钮和输入框」。获取可交互元素必须走第 3 步。

{
  "url": "https://www.baidu.com/",
  "title": "百度一下，你就知道",
  "activeTabid": "2EA73ED323E46E5E108D4E46DA4E4AA7",
  "webmcpTools": [{ "name": "page-agent-tool" }, { "name": "baidu_search" }],
  "tabs": [
    { "tabid": "2EA73ED323E46E5E108D4E46DA4E4AA7", "title": "百度一下,你就知道", "url": "https://www.baidu.com/" }
  ]
}

如果 webmcpTools 里出现 system-overview，并且本轮对话中还没调用过它，AI 应当立即执行一次 webmcp-cli run system-overview '{}'——它的返回值包含网站的模块、路由、页面工具和使用规范，能指导后续操作。

第 3 步：定位元素

这是与页面交互最关键的一步。state 不含 DOM，必须通过 page-agent-tool 获取可交互元素，有两种方式：

• 方式 A（按需搜索，优先）：明确知道要找什么元素时，用 searchTree 精准搜索，token 消耗比全量树减少 80% 以上：

  webmcp-cli run page-agent-tool '{"action": "searchTree", "query": "登录"}'
  

• 方式 B（全量获取）：需要全面了解页面结构、或不知道页面上有什么时，用 browserState 抓完整无障碍树：

  webmcp-cli run page-agent-tool '{"action": "browserState", "responseMode": "full"}'
  

返回的无障碍树里，只有带 #N 索引的节点才能被操作，操作时把 N 作为 index 传入。

第 4 步：交互并看变化

拿到元素索引后执行具体动作：click、fill、select、scroll。执行后工具默认返回增量差异（diff），AI 直接看返回就能确认操作是否生效，不必再手动拉一次全量树：

webmcp-cli run page-agent-tool '{"action": "click", "index": 18}'
webmcp-cli run page-agent-tool '{"action": "fill", "index": 13, "text": "Hello"}'

四步走完，如果任务还没完成，就回到第 2 步继续循环。

实操示例：让 AI 登录系统

把上面的循环套到一个具体任务上。假设用户说：「帮我登录 http://127.0.0.1:3003/login，账号 admin，密码 password123」。

AI 读完 SKILL.md 后会这样操作：

第 1 步：打开页面

webmcp-cli tabs open "http://127.0.0.1:3003/login"

第 2 步：查看可用工具

webmcp-cli state

返回 webmcpTools: [{ "name": "page-agent-tool" }]，说明页面上有万能工具 page-agent-tool 可用。

第 3 步：搜索页面元素

AI 知道要找输入框和登录按钮，用 searchTree 精准搜索而不是拉全量树：

webmcp-cli run page-agent-tool '{"action": "searchTree", "query": "textbox"}'

返回类似：用户名输入框是 #0，密码输入框是 #1，登录按钮是 #2。

第 4 步：填写表单

# 填用户名
webmcp-cli run page-agent-tool '{"action": "fill", "index": 0, "text": "admin"}'
# 填密码
webmcp-cli run page-agent-tool '{"action": "fill", "index": 1, "text": "password123"}'

每次 fill 后工具会自动返回页面变化（diff），AI 可以确认操作是否成功。

第 5 步：点击登录

因为每次操作后元素编号会重新分配，AI 先重新搜索「登录」按钮拿到当前索引，再点击（示例中是 2，实际以搜索结果为准）：

webmcp-cli run page-agent-tool '{"action": "searchTree", "query": "登录"}'
webmcp-cli run page-agent-tool '{"action": "click", "index": 2}'

页面跳转后，AI 看到返回的 URL 变成了首页，就知道任务完成了。

领域专用工具：有些网站给 AI 准备了更顺手的工具

page-agent-tool 是每个页面都有的万能工具，但部分域名会注入领域专用工具，交互更可靠，AI 应当优先使用。SKILL.md 的 domains/ 目录下有对应的子技能文档，AI 根据当前页面 URL 自动判断该读哪一份：

域名	注入的工具	说明
excalidraw.com	excalidraw_execute_command	画布元素操作，读 domains/excalidraw.md
juejin.cn	create_article、publish_current_draft、get_article_info	掘金发文，读对应子技能
editor.csdn.net	create_article、get_article_info、publish_current_draft	CSDN 发文，读对应子技能
segmentfault.com	create_article、get_article_info、publish_current_draft、segmentfault_publish_article	思否发文，读对应子技能
my.oschina.net	create_article、get_article_info、publish_current_draft	开源中国发文，读对应子技能
xiaohongshu.com	xhs_search_notes、xhs_get_note_detail 等	小红书搜索与笔记
www.baidu.com	baidu_search、baidu_get_results	百度搜索

例如打开 Excalidraw 后，state 返回的 webmcpTools 里会出现 excalidraw_execute_command，这时 AI 应该用它而不是 page-agent-tool：

webmcp-cli run excalidraw_execute_command '{"eventName": "getSceneElements"}'

操作规范与常见坑

SKILL.md 给 AI 定了几条核心规则，也是 AI 操作浏览器最容易翻车的地方：

1. state 优先。 除 tabs open 外，执行任何命令前必须先 state；tabs open 之后也必须再 state 一次。不要凭记忆猜元素索引或工具列表。

2. searchTree 优先。 已知要找的元素类型或名称时，必须优先 searchTree 而不是直接拉全量树——这和业界 AI 编辑器「按需读文件」的策略一致，token 消耗比全量树减少 80% 以上：

# ✅ 知道要找「提交」按钮：精准搜索
webmcp-cli run page-agent-tool '{"action": "searchTree", "query": "提交"}'
# ❌ 无脑拉全量树，浪费 token
webmcp-cli run page-agent-tool '{"action": "browserState", "responseMode": "full"}'

3. 编号用完即失效。 每次操作后 #N 索引会重新分配，不能复用旧索引。这也是登录示例里点击前要重新 searchTree 的原因。

4. 专属工具优先。 存在领域专用工具时，优先于 page-agent-tool 使用，它们对特定域名更可靠。

5. JSON 引号规则要分清终端。 run 的 json-args 参数在不同终端写法不同，遇到「参数不是有效的 JSON」报错先查这里：

# bash：单引号包裹
webmcp-cli run page-agent-tool '{"action": "fill", "index": 0, "text": "你好"}'
# cmd：双引号包裹，内部双引号转义
webmcp-cli run page-agent-tool "{\"action\": \"fill\", \"index\": 0, \"text\":\"你好\"}"
# powershell：单引号包裹，内部双引号转义
webmcp-cli run page-agent-tool '{\"action\": \"fill\", \"index\": 0, \"text\":\"你好\"}'

6. 避免无效重试。 同一操作不要重复超过 3 次；遇到验证码要告知用户手动处理；没有凭据不要尝试登录；不要点击 target="_blank" 的链接（会在新窗口打开），需要新页面就用 tabs open。任务失败是可以接受的——请求不可行、缺信息或页面有 bug 时，如实告知用户比盲目重试更好。

接入方式：把操作手册交给你的 AI

最后一步是把 SKILL.md 交到 AI 手里，取决于你用的 Agent 平台：

• 对话型 AI（DeepSeek、通义千问、ChatGPT 等）：把 SKILL.md 的内容作为系统提示词（System Prompt）粘贴进去，或作为附件上传。
• 编程型 AI（Cursor、Windsurf 等）：把 packages/webmcp-cli-skill/ 目录放进项目，AI 会自动读取。
• 自定义 Agent 平台：通过 API 把 SKILL.md 内容注入到系统提示中。

只要 AI 能读到这份操作手册，并且终端里装了 webmcp-cli，它就能开始干活了。

注意事项与常见问题

• 命令细节会随版本迭代变化。本文基于 webmcp-sdk dev 分支 commit e78423d 与 @opentiny/webmcp-cli 0.0.6；正文命令以 SKILL.md 原文为准，官方文档示例仅作参考。
• 不同终端引号规则不同，示例里的命令默认按 bash 书写；换到 cmd 或 PowerShell 先对照上一节的转义规则。
• AI 只能操作页面暴露的可交互元素。它操作的对象是无障碍树里带 #N 索引的节点，页面没有暴露的元素它调不到；page-agent-tool 只处理单页应用，需要打开新页面时用 tabs open。

关于 OpenTiny NEXT

OpenTiny NEXT 是一套企业智能前端开发解决方案，以生成式 UI 和 WebMCP 两大核心技术为基础，对现有传统的 TinyVue 组件库、TinyEngine 低代码引擎等产品进行智能化升级，构建出面向 Agent 应用的前端 NEXT-SDKs、AI Extension、TinyRobot 智能助手、GenUI 等新产品，实现 AI 理解用户意图自主完成任务，加速企业应用的智能化改造。

欢迎加入 OpenTiny 开源社区。添加微信小助手：opentiny-official 一起参与交流前端技术～
OpenTiny 官网：opentiny.design
WebMCP SDK 代码仓库：github.com/opentiny/webmcp-sdk（欢迎 star ⭐）
如果你也想要共建，可以进入代码仓库，找到 good first issue 标签，一起参与开源贡献～如果你有任何问题，欢迎在评论区留言交流！