最近在做一个叫 MoleClaw 的 Chrome 扩展，一个在任意网页上用的 AI 助手。今天趁文档站刚上线，来跟大家聊聊这个项目，主要分享下设计上踩过的坑和做的一些选择。(求star 
)
还是先说一下这个东西是做什么
在任意网页上按 Cmd+E 唤起一个搜索框，用自然语言告诉它你要干什么，它就钻到后台去干活，干完了把结果给你。整个过程不打扰你当前在做的事。目前原子操作涵盖了 页面感知，页面操作，导航，浏览器的能力，自动化与定时，工作流，以及最核心的cdp 共计 35+ 的工具，还在持续迭代
名字叫 Mole（鼹鼠），因为它的工作方式就像鼹鼠挖洞——你在地面上提了个需求，它就钻到地下去挖，挖完带着东西浮出来。对应到技术上就是：悬浮球是地面（Content Script），AI 调度在地下（Background Service
Worker），中间靠隧道网络连接（自己写的 Channel 通信系统）。
核心设计哲学
做这个项目最大的体会是一句话：代码管机制和边界，模型管决策和策略。
什么意思呢？代码层面只负责"采样 → 执行 → 回写"这个机械循环，加上预算控制（最多跑几轮、上下文多长截断）、死循环检测（同一个工具+同样参数重复调了 N
次就强制停）。至于"要不要调工具、调哪个、参数填什么、结果满不满意要不要再来一轮"——全部交给模型自己决定。 开发过程中其实也借鉴了 codex 跟 claudeCode 的设计理念，初版的codex逐渐切片的调度机制效果不是很好，最后还是选择结合 cc 的一些调度机制来混合了一下
这样做的好处是代码极简，不到几百行就是完整的调度循环。模型能力上来了，整个系统的上限就跟着上来，不用改代码。
为什么选 Workflow 而不是让 AI 直接读 DOM
这是我想重点聊的。
市面上很多浏览器 AI 助手的做法是：把当前页面的 DOM 树（或者简化版）丢给模型，让模型理解页面结构，然后生成操作指令。这个路径听起来很直觉，但实际用下来问题不少：
- Token 成本爆炸
一个普通的电商页面，DOM 树序列化出来几万 token 打底。你每一轮 function calling 都要带上这个上下文，一个"帮我搜个商品"的操作可能要跑 3-5 轮，token 直接起飞。更别提淘宝京东这种重型页面了。
- 不稳定
DOM 结构是前端工程师随时可能改的东西。今天这个列表是 .search-result-item，明天改版可能就变了。你让模型去"理解" DOM，本质上是在让一个概率模型去做确定性解析，翻车概率不低。同一个页面，同一个问题，跑两次可能结果不一样。
- 慢
先抓 DOM → 序列化 → 发给模型 → 模型理解 → 生成操作 → 执行 → 再抓 DOM… 每一步都有延迟，体验上就是用户干等着。
所以我选了另一条路：声明式工作流（Site Workflow）。
思路很简单——对于那些确定性的、可以预定义的操作（比如"在京东搜商品"“在淘宝看详情”“在 Boss 直聘回消息”），直接用 JSON 声明一系列步骤，这些步骤被打包为一个workflow
这样做的效果是：
- 零 token 消耗在页面理解上 — 步骤是预定义的，不需要模型去"看懂"页面
- 确定性执行 — 同一个 workflow 跑一百次结果一样
- 快 — 没有多余的 LLM 往返，步骤直接顺序执行
- 可分发 — workflow 定义就是个 JSON 文件，支持远程 Manifest 同步，我更新了 workflow 定义，所有用户自动同步
AI 在这里的角色变了——它不需要去理解 DOM，只需要判断"用户的意图匹配哪个 workflow"，然后填参数调用就行。这个判断对模型来说简单得多，准确率也高得多。
当然 workflow 覆盖不到的长尾场景，模型还是可以回退到直接操作页面（page_snapshot + element_action），这两条路不冲突。但体感上，80% 的高频操作用 workflow 就够了。
CDP 是能力层的最强工具，cdp 其实就是完全接管了你的浏览器，抓包，读取 storage，解决图灵验证，是 mole 的能力核心，当然所有的对话都是落在本地的，mole 只是一个本地工具，最终还是需要使用者自行连接 llm 的
Content Script 能干的事其实有限。稍微涉及一点跨域 iframe、反爬检测、网络细节，就全歇菜。所以我接了 Chrome DevTools Protocol（CDP），打通了 10 个协议域：
- 发 isTrusted=true 的鼠标键盘事件，过反爬
- 穿透跨域 iframe，搞定验证码、支付表单这些场景
- 请求拦截和篡改，能注入 headers、mock API、绕 CORS
- 跨域读写 localStorage/sessionStorage
- 元素高亮标注，操作的时候用户能看到 AI 在点哪里
这些能力加起来，基本上人在浏览器里能做的事，它都能做。
其他细节
- LLM 自由选择：兼容任何 OpenAI API 格式的服务，endpoint / key / model 自己配。想用 GPT 用 GPT，想用 Claude 套个兼容层也行，本地 Ollama 也没问题。数据不经过我的服务器
- MCP 协议：工具注册走的是 MCP（Model Context Protocol），同进程内跑 Server/Client/Transport，也支持 HTTP 远程工具动态扩展
- 上下文自动压缩：多轮任务跑久了上下文会超，自动压缩历史保留关键信息，不会半路崩掉
- 子任务拆分：复杂任务可以 spawn 出独立子任务，每个子任务有隔离的上下文，避免信息互相污染
链接
- GitHub：GitHub - clark-maybe/mole-extension: Mole - AI-powered browser assistant with workflow automation · GitHub
- 文档站：https://moleclaw.site
- 协议：AGPL-3.0，完全开源
