1. 项目概述一个完全在浏览器内运行的本地AI助手最近在折腾一个挺有意思的东西一个叫 Gemma Gem 的 Chrome 浏览器扩展。简单来说它把你的浏览器变成了一个拥有“眼睛”和“手”的本地AI助手。最吸引我的地方在于它完全在本地运行不依赖任何云端API你电脑上的任何网页内容都不会离开你的设备。它基于 Google 最新的 Gemma 4 模型通过 WebGPU 技术直接在浏览器里进行推理运算。想象一下你打开一个复杂的网页比如一个满是表格和按钮的后台管理系统或者一篇冗长的技术文档。你不需要再手动复制粘贴、来回切换窗口去问 ChatGPT 了。你只需要在页面右下角点开这个“宝石”图标直接问它“这个页面上有哪些可点击的按钮”、“把第三段的核心观点总结一下”、“帮我在搜索框里输入‘机器学习’并点击搜索”。它不仅能看懂页面内容还能直接操作页面元素帮你完成这些任务。这背后的核心价值是隐私、实时性和自动化。没有网络延迟没有API调用费用最关键的是你的数据尤其是敏感的公司内部页面、个人账户信息始终安全地待在你的电脑里。这对于需要处理大量网页信息但又对数据安全有要求的开发者、研究人员或普通用户来说是个非常实用的工具。2. 核心架构与工作原理拆解要理解 Gemma Gem 如何工作我们需要深入到它的技术架构里看看。它不是一个简单的“聊天机器人”插件而是一个精心设计的、由多个独立部分协同工作的浏览器内智能体系统。2.1 三层架构各司其职的精密协作项目文档里那个架构图非常清晰地揭示了它的设计思想。整个扩展可以看作三个核心模块它们运行在浏览器不同的“沙箱”环境中通过消息传递进行通信。第一层内容脚本这是直接与网页“肌肤相亲”的一层。它被注入到每一个你访问的页面中但运行在一个隔离的环境里不会干扰页面本身的JavaScript。它的核心职责有两个提供用户界面在页面右下角注入那个宝石图标以及点击后弹出的、用 Shadow DOM 技术实现的聊天悬浮窗。Shadow DOM 确保了聊天框的样式和行为不会与网页本身冲突。执行“物理”操作它拥有一套“DOM 工具”可以直接读取页面内容、点击按钮、输入文字、滚动页面。例如当AI模型发出“点击那个 id 为submit-btn的按钮”的指令时最终是由这一层的脚本去执行document.querySelector(#submit-btn).click()。第二层服务工作者你可以把它想象成整个扩展的“中央调度员”和“特权操作员”。它是一个在后台长期运行的脚本即使你关闭了所有相关标签页它也可能还在取决于浏览器策略。它的关键作用包括消息路由在内容脚本和第三层离屏文档之间传递指令和结果。它们彼此不能直接对话必须通过服务工作者中转。执行高权限操作有些操作内容脚本做不了比如截取整个页面的完整截图包括跨域 iframe 内容或者在页面的主执行上下文中运行任意 JavaScript 代码。这些需要更高权限的任务就由服务工作者来完成。第三层离屏文档这是整个系统的“大脑”所在地。它是一个隐藏的、不可见的浏览器页面专门用来做“重活”。在这里通过huggingface/transformers.js这个库加载并运行着量化后的 Gemma 4 模型E2B 或 E4B 版本。WebGPU 的加持使得在浏览器中进行高效的神经网络推理成为可能。AI 的“思考”过程——接收用户问题、结合页面内容理解意图、规划工具调用序列——都在这个离屏文档中完成。注意这种架构是 Chrome 扩展开发 MV3Manifest V3规范下的最佳实践。它将耗资源的模型推理放在独立的离屏文档中避免了阻塞页面主线程或服务工作者确保了扩展的响应速度和稳定性。2.2 工具系统AI的“手眼”能力清单Gemma Gem 的强大很大程度上源于它给 AI 模型配备的一套精确定义的工具。这就像给一个聪明但原本没有实体的人装上了机械臂和摄像头。每个工具都有明确的输入、输出和执行环境。工具名称功能描述执行环境典型使用场景与内部原理read_page_content读取页面文本或指定CSS选择器的内容。内容脚本这是AI的“眼睛”。当用户问“这个页面讲了什么”时AI会调用此工具。它内部会执行类似document.body.innerText或document.querySelector(selector).outerHTML的操作获取结构化或非结构化的文本信息作为AI理解的上下文。take_screenshot捕获当前可视区域为PNG图片。服务工作者AI的“另一只眼”用于理解视觉布局。服务工作者通过chrome.tabs.captureVisibleTabAPI 实现。这对于理解图表、复杂UI布局特别有用但注意模型本身是文本模型截图需要先被转换成描述性文本可能通过其他方式但当前版本可能主要用于开发者调试。click_element通过CSS选择器点击一个元素。内容脚本AI的“手指”。指令如click_element(#agree-checkbox)。内部就是简单的document.querySelector(selector).click()。难点在于AI需要从页面内容中准确识别出目标元素的选择器。type_text向指定CSS选择器的输入框输入文本。内容脚本模拟键盘输入。例如type_text(input[type\search\], Gemma 4)。内部会聚焦元素并触发input事件。scroll_page按像素数向上或向下滚动页面。内容脚本浏览长页面。scroll_page(500)向下滚500像素。这帮助AI获取当前视口之外的信息。run_javascript在页面主上下文中执行任意JavaScript代码。服务工作者AI的“瑞士军刀”功能最强大也最危险。通过chrome.scripting.executeScriptAPI 实现。可以获取页面全局变量、操作非标准组件、进行复杂计算。例如run_javascript(return window.userProfile.name)。这套工具的设计非常巧妙它将复杂的“操作网页”任务分解成了AI模型可以理解和调用的标准化函数。模型只需要学会在何时、以何种参数调用哪个工具就能完成复杂的多步任务。3. 从零开始的详细部署与配置指南纸上得来终觉浅绝知此事要躬行。下面我带大家走一遍完整的安装、配置和初步使用的流程过程中我会穿插一些容易踩坑的地方和我个人的调试心得。3.1 环境准备浏览器与磁盘空间浏览器要求必须是Chrome 或基于 Chromium 的新版 Edge版本 113 以上并且确保WebGPU功能已启用。这是硬性条件因为模型推理依赖 WebGPU 进行硬件加速。检查 WebGPU在浏览器地址栏输入chrome://flags或edge://flags搜索 “WebGPU”确认其状态为 “Enabled”。通常现代版本默认已开启。实操心得如果你在后续步骤中遇到模型加载失败首先回来检查这里。我曾有一次在某个Chrome测试版中遇到WebGPU支持不稳定的情况退回稳定版后问题消失。磁盘空间根据你选择的模型版本需要预留500MB 到 1.5GB的缓存空间。E2B 模型约500MB适合大多数任务响应速度更快。E4B 模型约1.5GB能力更强上下文长度更长128K但加载和推理速度会稍慢。注意这个空间是在第一次加载模型时用于缓存模型文件后续使用无需重复下载但会一直占用。3.2 源码构建与加载扩展项目使用pnpm作为包管理器构建则基于WXT框架一个优秀的、基于 Vite 的浏览器扩展开发框架。# 1. 克隆项目代码 git clone repository-url cd gemma-gem # 2. 安装依赖 pnpm install # 如果网络环境不佳transformers.js 相关依赖可能下载较慢请保持耐心。 # 3. 执行开发构建 pnpm build关键解读pnpm build命令执行的是开发构建它会保留console.log等调试信息并生成 source map方便我们排查问题。构建输出目录是.output/chrome-mv3-dev/。接下来是加载未打包的扩展打开 Chrome进入chrome://extensions/。打开右上角的“开发者模式”开关。点击“加载已解压的扩展程序”按钮。在弹出的文件选择器中导航到你的项目目录选择.output/chrome-mv3-dev/这个文件夹注意是文件夹不是里面的某个文件。加载成功后你应该能在扩展列表里看到 “Gemma Gem”并且浏览器工具栏如果扩展有图标或页面右下角会出现它的图标。踩坑记录第一次加载时我遇到了服务工作者启动失败的错误。检查控制台发现是某个模块导入问题。这是因为 WXT 在开发模式下使用了一些特殊的 HMR热更新逻辑。解决方法是在chrome://extensions/页面找到 Gemma Gem点击“刷新”图标或先禁用再启用通常就能解决初次加载的运行时问题。3.3 首次使用与模型加载访问任意一个网页比如https://news.ycombinator.com。留意页面右下角应该会出现一个闪烁或带有加载状态的宝石图标。点击该图标会弹出聊天界面。此时界面会显示“Loading model…”之类的提示。这是最关键的一步首次加载模型需要从 Hugging Face 下载数百MB的模型文件。下载速度取决于你的网络。你可以在离屏文档的控制台看到详细的下载进度。模型加载完成后聊天输入框会变为可用状态。如何选择模型点击聊天窗口标题栏的齿轮图标进入设置。在 “Model” 下拉框中可以在Gemma 4 E2B和Gemma 4 E4B之间切换。切换后需要重新加载模型。个人建议初次使用或硬件性能一般集成显卡、内存小于16GB的用户优先选择 E2B 模型。它的速度优势非常明显对于网页内容理解、简单操作等任务完全够用。E4B 模型更适合需要极强推理能力或处理超长页面文本接近10万字的场景。4. 实战应用与你的网页AI助手深度协作现在助手已经就绪。我们来试试它能做什么。以下是一些我实测过的、能体现其价值的场景。4.1 场景一快速理解与总结复杂页面任务打开一篇长的技术博客或产品文档让 Gemma Gem 帮你总结。你的提问“用三点总结这篇文章的主要观点。”助手的工作流调用read_page_content获取页面全文。模型在本地分析文本识别核心段落和论点。生成结构化的摘要并返回。我的体验对于纯文本文章总结效果相当不错速度也快E2B模型下仅需几秒。它避免了你自己滚动筛选信息的麻烦。4.2 场景二自动化表单填写与交互任务在一个联系表单页面自动填写信息并提交。你的提问“帮我在这个表单里填一下信息名字写‘Test User’邮箱写‘testexample.com’在‘问题类型’下拉框选‘Technical Support’在消息框里写‘Hello, I have a question about the API.’然后点击提交按钮。”助手的工作流调用read_page_content理解页面结构识别出各个输入框、下拉框和按钮。依次调用type_text工具向对应的选择器如input[name\name\]填入指定文本。对于下拉框它可能需要调用run_javascript来设置select元素的value或触发change事件。最后调用click_element点击提交按钮。注意事项这个场景的成功率高度依赖于AI能否正确识别出元素的选择器。对于结构良好、使用标准HTML标签的表单成功率很高。但对于使用复杂前端框架如React、Vue生成的自定义组件选择器可能难以预测可能导致操作失败。这时你可以通过更精确的指令来引导它比如“找到那个旁边有‘Your Name’标签的输入框”。4.3 场景三提取结构化数据任务从一个商品列表页面提取所有商品名称和价格。你的提问“这个页面上列出了哪些产品把它们的名字和价格整理成一个表格。”助手的工作流read_page_content获取列表区域HTML。模型分析HTML结构识别出重复的模式如每个商品项的div类名。它可能会尝试调用run_javascript来执行更精确的数据提取例如return Array.from(document.querySelectorAll(.product-item)).map(item ({name: item.querySelector(.name).innerText, price: item.querySelector(.price).innerText}))。将提取到的数据组织成Markdown表格格式返回给你。实操心得这是体现其“智能体”能力的高级场景。它需要将自然语言指令转化为具体的DOM操作和数据处理逻辑。实测中对于具有清晰CSS类名的列表它能很好地完成任务。如果页面结构混乱你可能需要先让它“滚动页面”加载更多内容或者分区域进行提取。4.4 高级设置与技巧开启“思考”过程在设置中打开 “Thinking” 选项。这会让模型在回复时先输出其内部的推理链类似 CoT, Chain-of-Thought。这对于调试复杂指令、理解AI为何做出某个决策非常有帮助。限制迭代次数“Max iterations” 设置可以防止AI陷入无限的工具调用循环。如果AI在一个任务上反复调用工具却无进展达到迭代上限后会自动停止并报错。站点禁用如果你在某些网站如网银、内部系统不希望它运行可以点击“Disable on this site”。这个设置会按域名永久保存。上下文管理“Clear context” 会清空当前页面的对话历史。注意模型本身的会话是基于页面隔离的你刷新页面或跳到新页面就是一个新的会话。5. 开发、调试与问题排查实录如果你不仅仅想使用还想深入了解、修改或为这个项目做贡献那么开发与调试技能就至关重要了。5.1 本地开发流程项目使用pnpm脚本管理pnpm build开发构建包含详细日志和 source map。pnpm build:prod生产构建代码被压缩除错误外的日志被静默。如果你想提交到 Chrome 应用商店需要用这个命令打包。开发时的热重载WXT 框架支持一定程度的热重载。当你修改了content-script或offscreen的代码并保存后有时需要手动刷新扩展在chrome://extensions页面点击刷新或刷新目标网页才能生效。服务工作者的更新则通常需要重启浏览器或使用“更新”按钮。5.2 多维度调试日志查看所有日志都带有[Gemma Gem]前缀方便过滤。根据你想调试的部分需要打开不同的开发者工具服务工作者日志这是消息流转的中心。打开chrome://extensions。找到 Gemma Gem点击其卡片下的“Inspect views: service worker”链接。这会打开一个专属的开发者工具窗口显示服务工作者的console输出。在这里你可以看到所有消息的收发记录、截图和JS执行命令的触发情况。离屏文档日志最最重要这里是AI大脑的“思维过程”。同样在chrome://extensions页面点击“Inspect views: offscreen.html”。这个控制台是宝藏。你会看到模型加载进度从HF下载到WebGPU编译到最终就绪。每次对话的完整提示词构造系统指令、用户消息、工具定义、历史记录。模型生成的原始输出包括它决定调用哪个工具、参数是什么的JSON。工具调用的请求和返回结果。Token 消耗统计。这对于理解模型性能和成本虽然是本地但也有计算开销很有帮助。内容脚本日志这是“手”和“眼睛”的动作记录。在你运行 Gemma Gem 的普通网页上直接按 F12 打开开发者工具。在 Console 面板中你就能看到来自内容脚本的日志比如read_page_content读取到了什么、click_element尝试点击了哪个选择器、是否成功等。万能检查器chrome://inspect/#other这个页面列出了浏览器中所有可调试的上下文包括扩展的服务工作者、离屏文档、以及每个标签页的内容脚本。如果你找不到上述某个视图来这里准没错。5.3 常见问题与解决方案速查表我在深度使用和测试过程中遇到了不少问题这里整理成表方便大家快速排查。问题现象可能原因排查步骤与解决方案宝石图标不出现1. 扩展未成功加载。2. 内容脚本注入失败。3. 当前页面被禁用。1. 检查chrome://extensions确认扩展已启用且无错误。2. 刷新页面。3. 检查该站点的设置是否被禁用。模型加载失败或卡住1. WebGPU 不支持或未启用。2. 网络问题无法从 Hugging Face 下载模型。3. 浏览器内存/显存不足。1. 确认chrome://flags中 WebGPU 为 Enabled。2. 查看离屏文档控制台看是否有网络错误。可尝试科学上网或使用国内镜像需修改代码。3. 关闭其他标签页尤其是占用大量GPU的页面游戏、视频。尝试使用更小的 E2B 模型。AI回复“我无法执行此操作”或工具调用失败1. 页面结构复杂AI无法定位元素。2. 工具执行时发生JavaScript错误。3. 跨域限制某些操作在特定网站被禁止。1. 打开“Thinking”模式看AI的推理链判断它选择的选择器是否正确。可尝试更精确的指令如“点击那个蓝色的、文字是‘Submit’的按钮”。2. 查看内容脚本或服务工作者的控制台看工具执行时是否有报错。3. 这是浏览器安全策略通常无法绕过。操作结果不符合预期如点错按钮AI识别元素有误。1. 使用read_page_content工具让AI先告诉你它看到的页面结构确认其“视野”是否准确。2. 结合take_screenshot如果支持让AI从视觉上辅助判断但当前版本可能未深度集成此功能。3. 这是当前技术的局限性复杂动态页面的元素识别仍是挑战。扩展突然停止响应1. 服务工作者被浏览器休眠。2. 离屏文档因内存占用过高崩溃。1. 尝试在chrome://extensions页面刷新扩展。2. 重启浏览器。离屏文档崩溃后通常需要刷新页面或重启扩展才能恢复。生产构建后功能异常生产构建移除了console.log某些依赖调试信息的逻辑出错。检查代码中是否有类似if (debug) console.log(...)但debug变量在生产环境未正确设置的情况。使用pnpm build开发构建进行对比测试。5.4 性能优化与进阶思考模型缓存首次加载慢之后快。模型文件会存储在浏览器的 IndexedDB 中。如果你清除了浏览器数据需要重新下载。内存占用运行 E4B 模型时Chrome 进程的内存占用会显著增加可能增加2-3GB。确保你的设备有足够的内存。代理与网络由于需要从huggingface.co下载模型网络环境至关重要。如果遇到下载问题可以考虑在开发时修改agent/model-backend.ts等文件中的模型加载路径指向本地文件或可访问的镜像但这需要一定的工程能力。独立化的 Agent 层项目作者将agent/目录设计为无依赖的这意味着你可以将这套“工具定义-模型调用-循环执行”的智能体逻辑轻松移植到其他前端或Node.js环境中只需实现对应的ModelBackend和ToolExecutor接口即可。这是一个非常优雅的设计。这个项目将前沿的本地大模型与实用的浏览器自动化能力相结合打开了一扇新的大门。它不仅仅是另一个聊天机器人而是一个真正能“动手”的本地智能体。虽然目前在复杂网页的精准操作上还有提升空间但其隐私保护、零成本、低延迟的优势非常突出。对于开发者而言它的架构清晰易于学习和二次开发对于普通用户它则是一个强大而安全的网页理解和自动化助手。随着 WebGPU 的普及和模型效率的提升这类完全在边缘设备上运行的智能应用未来可期。