huashu-chrome

「工具返回『已点击』不算数，页面真的动了才算。」

让任何 AI agent 操控你自己的 Chrome——带着你全部的登录态。

一个 MCP server + 一个 Chrome 扩展，22 个浏览器工具。Claude Code、Codex CLI、Cursor、Gemini CLI、Cline、Windsurf 通用。

看效果 · 安装 · 22 个工具 · 经验回流 · 安全 · 排错

你：帮我把这份 CSV 里的 30 条客户信息录进 CRM
agent：（打开你已登录的 CRM，逐条填表提交）

不用 API key，不用重新登录，不用处理验证码——用的就是你此刻这个浏览器里的身份。

「npm 包？插件？CLI？还是 MCP？」——都是。它们是同一个产品的五个器官：npm 包是分发载体， CLI 是入口（install / mcp / doctor），MCP server 是 agent 的接口，本地桥是 127.0.0.1 上的 常驻路由器，Chrome 扩展是手。上图就是一条命令穿过它们的全程。

图解版完整说明书 → huasheng.ai/huashu-chrome

看效果

装上之后，你在 agent 里说的是这种话：

「查一下这本书在京东有几家在卖，评价怎么样」
「把这篇稿子发到小红书，配这 9 张图，明早 7:30 定时发」
「这个 B 站 UP 主最近 30 条视频的播放和字幕全拉下来」
「明天武汉到上海的高铁还有没有二等座，顺便告诉我票价」
「把这份表格里的记录加进飞书多维表格」

下面每一行都是真跑通过的，右边那列点进去就是它的实测笔记——包括踩过的坑和被推翻的结论：

最后一行是故意留的。能干什么和干不了什么同样重要——出厂经验里有好几条是负面结论， 省下的是 agent 在墙上撞十几个回合的时间。

为什么需要它

浏览器控制这件事，现在的格局是：能拿到你真实登录态的，多半只给自家客户端用； 对任何 agent 开放的，多半开的是一个干净的、没登录的浏览器。huashu-chrome 两头都要。

核查日期 2026-09-09，每一格都对着官方文档或官方仓库填的，完整八方案矩阵和每格来源见 docs/对比.md。两句公道话：Playwright MCP 的扩展模式也能拿到登录态、 也有按客户端隔离，它缺的是站点经验和人工交接；Claude in Chrome 遇到验证码也会停下等你， 它的问题是只给 Anthropic 自家客户端用。

安装

npx huashu-chrome install

一条命令：自动检测这台机器上装了哪些 agent、写好各自的 MCP 配置（动手前先备份， 已配过的自动跳过；只想看不想写加 --dry-run），然后弹出引导页带你装扩展—— 装扩展这一下必须你自己点，浏览器不允许脚本代劳。

它认得出哪些 agent，分三层：

1. 已知表 —— src/agents.json 列了 20 个：Claude Code、Codex CLI、Cursor、 Gemini CLI、Windsurf、Cline、Roo Code、Claude Desktop，以及 WorkBuddy、CodeBuddy、 Kimi Code、通义灵码、MiniMax Mavis、Trae、豆包、千问 / Qwen Code、Qoder、 DeepSeek、iFlow、OpenClaw。加一个只要往数组里加一行，不用改代码 —— 欢迎 PR。 不只是编程 agent：WorkBuddy、千问办公、豆包工作这类办公 agent，只要能配本地 MCP， 同样接得上——它们最常干的「查后台数据、填表、跨站搬运」正是登录态最要紧的活。
2. 自动发现 —— 没列出来的也能认出来。install 会扫 home 下的点目录， 按预设文件名查找含mcpServers的配置；Codex的TOML另行适配。 这不是任意MCP客户端的通用安装器：OpenCode使用顶层mcp与命令数组，当前不支持自动写入，见下方手动配置。
3. 都不匹配 —— 打印该填的 JSON，你自己贴。

OpenCode手动配置：依据官方MCP文档与配置文档（2026-09-25核对），在现有全局配置~/.config/opencode/opencode.json或opencode.jsonc的mcp对象中合并以下条目，保留已有设置。实际配置位置以当前OpenCode版本及环境变量为准。

{
  "mcp": {
    "huashu-chrome": {
      "type": "local",
      "command": ["npx", "-y", "huashu-chrome", "mcp", "--client", "opencode"],
      "enabled": true
    }
  }
}

Windows若无法解析npx，可按本机安装方式改用npx.cmd。这是手动配置说明，不表示install已支持OpenCode自动安装。

已知客户端的Windows / macOS / Linux配置路径按src/agents.json匹配。装完验证：

npx huashu-chrome doctor

看到「握手正常 · Chrome 扩展在线」就成了。桥进程由 agent 首次调用时自动拉起 （doctor 发现桥没跑也会先拉一个再探），你不用手动开任何东西。

Claude Code

claude mcp add huashu-chrome -- npx -y huashu-chrome mcp --client claude-code

Codex CLI — ~/.codex/config.toml

[mcp_servers.huashu-chrome]
command = "npx"
args = ["-y", "huashu-chrome", "mcp", "--client", "codex"]

Cursor / Gemini CLI / Windsurf / Claude Desktop — 各自的 JSON 配置里加：

{ "mcpServers": { "huashu-chrome": { "command": "npx", "args": ["-y", "huashu-chrome", "mcp"] } } }

--client 可以不写、写错也没关系：侧栏和审计日志里显示的是宿主在 MCP 握手里 自报的身份（Claude Code / Codex CLI / Gemini CLI / OpenClaw …），这个参数只在宿主没报时兜底。

扩展：npx huashu-chrome extension 打印目录，然后 chrome://extensions → 开发者模式 → 加载已解压的扩展程序。

工具：按「网页只有三种信息载体」来分

22 个工具不是一堆平铺的功能，是三层。这个分层决定了 agent 面对陌生网站时按什么顺序出牌， 完整推演见 docs/能力模型.md——里面每条规则都跟着撞出它的那堵墙。

数据层（要数字、列表、表格，从这里开始）

操作层（要做事，以及读文章）

批处理

人

兜底层

这套顺序不用你教给 agent——MCP server 在握手时就把它作为 instructions 下发了。

每个操作都要交待「到底动没动」

浏览器 agent 最大的问题不是点不准，是静默失败：工具返回成功，页面其实没动。 一个三十步的任务，第八步悄悄失效，后面二十二步全是垃圾——而没有任何人知道。

所以这里每个写操作都不允许只回一句「已点击」，必须交待页面的反应：

[e7] 已点击
效果：expanded false → true

⚠️ 操作已发出，但页面完全没有反应（DOM、正文、焦点、目标状态、页面提示都没变）。
   可能是：① 这个元素只是容器，真正的按钮在它内部或旁边；② 只有异步副作用；③ 站点忽略了这次输入。

⚠️ 没有可归因于这次操作的变化。这个页面本身在持续变化（正文 -4 字），
   但目标元素的状态没动、也没有新的页面提示——那些变化多半不是这次操作造成的。

判定只回答一个确定性问题——页面动没动，不猜「成功还是失败」（那需要理解意图）。 而且只认「变化发生在目标附近」的证据：全局正文长度是页面里最脏的信号， 直播弹幕和懒加载列表每时每刻都在改它。

顺带的好处是更快：有反应就早停，不再固定等 400ms。

一次说完，别来回八趟

浏览器 agent 的另一个大成本是回合数。一个「点开始 → 填手机号 → 勾同意 → 下一步」的流程，逐个调用是 4 次模型推理加 4 份快照，而中间那 3 份快照 没有任何人读——agent 在发出第一个点击之前就知道后面三步要干什么了。

act 让它一次说完：

act 停在第 4 步 3/4：
  ✅ click button 「开始填写」   效果：目标区块文本 +29 字
  ✅ type  textbox 「手机号」←11字  效果：value 空 → 13800138000
  ✅ click button 「下一步」     效果：页面顶层移除 1 个元素（整块内容被换掉了）
  ⏸ click button 「提交订单」
     这是提交/支付/删除一类的动作，批处理不代做。单独调用一次 click 把它做掉。

它不是个盲目的宏：每一步都验过效果才走下一步，任何一步没反应就当场停下， 把「做到哪、为什么停、还剩什么」讲清楚。而且提交、支付、删除、发布这类动作 永远不代做——一串动作里夹一个它，跑完了中间没有任何人看得见。

越用越快：经验回流

浏览器 agent 最大的时间成本是在陌生网站上试错。同一个飞书多维表格任务， 从零摸索用了 281 次调用、54 分钟；把摸清的规律记下来之后，第二次只需要不到 10 次。

learnings 工具就是干这个的，经验分两层：

• 出厂经验：随 npm 包分发（docs/经验/），装上就有。当前 23 个站—— 上面那张表里的 10 个，加上淘宝、微信公众号、搜狗微信搜索、微博、知乎、豆瓣、脉脉、 大麦、即刻、腾讯文档、Ollama，以及两个 canvas 游戏（sudoku.com / flappybird.io， 它们是「棋盘不在 DOM 里」这类页面的样板）。已验证的接口名、墙、坑， 每条都标了实测日期。升级版本就拿到新经验。
• 本机经验：~/.huashu-chrome/learnings/，agent 每次干活学到的新规律 自己存进去（新站摸清了门路、老站发现记录过时了），永远不会被升级覆盖。 全在你自己的磁盘上，不上传。

agent 开工前查一次（learnings {domain}），收工时把非显而易见的发现存回去 （learnings {domain, save}）。经验是提示不是规则——站点会改版、每个人的 环境不一样，所以工具返回的每一份经验都带着同一句话：与页面实际不符时， 以实际为准，然后把记录改对。查不到经验也不阻塞，按通用策略干就是了。

摸清了一个新站？欢迎把 ~/.huashu-chrome/learnings/ 里的文件提 PR 到 docs/经验/，让所有用户受益。提之前记得先看一遍有没有把你自己的 账号、行程、订单号写进去——那个目录是 agent 自动写的，它不知道哪些字不该出门。

点不动的时候，自动换真实事件

content script 派发的事件 isTrusted 永远是 false。四类场景因此结构性失效： 检查 isTrusted 的风控站点、自管输入的编辑器（Monaco / CodeMirror / 飞书富文本）、 需要用户手势才解锁的 API、以及原生文件对话框。

所以当一次操作没有留下任何证据时，会自动换成浏览器级的真实输入事件再试一次：

[#trustedOnly] 已点击（真实事件）　←　普通事件无效，已自动改用真实事件
效果：目标区块文本 +6 字

两条边界：

• 提交 / 支付 / 下单 / 删除 / 发布这类目标，永不自动重试。 普通事件可能其实已经 生效、只是没留下痕迹，重试就是下第二笔单。这道闸是正则加 DOM 特征的确定性判断， 不问模型。需要时由 agent 显式传 real:true。
• **原生 `<sel