1. 项目概述一个能与网页对话的本地AI助手如果你和我一样对AI助手既爱又恨——爱它的便利恨它背后那说不清道不明的数据隐私和持续不断的订阅费用——那么今天聊的这个开源项目你可能会非常感兴趣。它叫Page Assist本质上是一个浏览器扩展但它做的不是广告拦截或密码管理而是把一个功能完整的、运行在你自己电脑上的AI大模型直接“嵌入”到你的浏览器侧边栏里。想象一下这个场景你正在浏览一篇长达几十页的技术文档想快速找到某个API的调用示例。传统做法是CtrlF搜索关键词然后在一堆结果里翻找。而有了Page Assist你只需要在侧边栏里问一句“这篇文档里关于‘用户认证’的代码示例在哪里”它就能基于你当前打开的整个网页内容给你一个精准的段落引用和总结。更妙的是这一切处理都发生在你的本地对话内容、网页数据都不会离开你的电脑。这就是Page Assist的核心价值将本地大模型的强大推理能力无缝集成到你的日常网页浏览体验中同时牢牢守住隐私的底线。这个项目适合所有对隐私敏感、希望拥有可控AI能力的开发者、研究者和重度信息处理者。无论你是想用本地模型辅助编程、快速消化长文、翻译外文资料还是单纯不想把聊天记录交给第三方Page Assist都提供了一个极其优雅的解决方案。接下来我将带你从设计思路到实操细节完整拆解这个项目并分享我在深度使用和测试中积累的一手经验。2. 核心设计思路与技术选型解析2.1 为什么是“浏览器扩展” “本地AI”Page Assist的架构选择非常精准地切中了当前AI应用的几个痛点。首先浏览器是我们获取信息的核心入口大部分知识工作都围绕网页展开。将AI助手直接放在浏览器里避免了频繁在应用间切换的割裂感实现了“在哪看就在哪问”的无缝体验。其次依赖本地AI模型如通过Ollama运行彻底解决了云端服务的三大问题数据隐私、网络延迟和使用成本。你的所有对话历史和被分析的网页内容都只在你的设备内存和本地AI服务之间流转。从技术实现上看浏览器扩展特别是Manifest V3提供了强大的能力它可以注入侧边栏Sidebar、拥有独立的弹出页面Popup、后台脚本Service Worker以及内容脚本Content Scripts来与网页DOM交互。Page Assist巧妙地利用了这些能力侧边栏作为常驻的聊天主界面不影响主网页浏览。内容脚本用于获取当前网页的完整HTML内容这是实现“与网页对话”功能的基础。后台脚本管理扩展的状态、快捷键监听以及与本地AI服务如Ollama的通信。这种架构使得扩展本身非常轻量主要承担UI渲染和通信中转的角色而计算密集型的模型推理则交给专门的本地AI服务进程各司其职效率很高。2.2 核心功能模块拆解Page Assist的功能可以清晰地分为三个层次理解它们有助于我们后续的配置和问题排查。侧边栏聊天Sidebar Chat这是最常用的功能。一个固定在浏览器右侧的可折叠面板提供了一个类似ChatGPT的聊天界面。你可以在这里进行普通的对话也可以一键切换到“与当前网页聊天”模式。在此模式下扩展会自动将当前页面的文本内容作为上下文提供给AI模型使得你的提问能基于页面内容得到精准回答。独立Web界面Web UI点击扩展图标或在新建标签页中打开的一个全功能聊天界面。它比侧边栏空间更大更适合进行长时间的、复杂的对话或代码编写。你可以把它看作一个本地的、迷你版的ChatGPT网页客户端。本地AI服务桥接Local AI Provider Bridge这是项目的“引擎”。扩展本身不包含AI模型它需要通过HTTP API与后端的AI服务通信。Page Assist设计上兼容多种后端Ollama这是目前最主流、体验最好的选择。Ollama负责在本地拉取、运行和管理各种大语言模型如Llama 3、Mistral、Qwen等。兼容OpenAI API的端点例如LM Studio、llamafile、text-generation-webui等工具提供的API。这给了用户极大的灵活性几乎可以使用任何能在本地以OpenAI API格式提供服务的模型。Chrome内置的Gemini Nano这是一个比较新的特性直接调用Chrome浏览器内置的轻量级模型无需安装任何额外服务但能力相对有限。提示对于绝大多数用户我强烈推荐使用Ollama作为后端。它的安装、模型管理拉取、运行极为简单社区活跃且与Page Assist的集成度最高稳定性最好。3. 从零开始的完整安装与配置指南纸上得来终觉浅绝知此事要躬行。下面我将以最常用的Chrome/Edge浏览器 Ollama后端组合为例带你完成一次从零开始的完整部署。我会补充官方文档中未提及的细节和避坑点。3.1 第一步安装并配置Ollama本地AI引擎Ollama是整个系统的核心必须先安装并运行起来。下载与安装访问 Ollama官网 根据你的操作系统Windows/macOS/Linux下载安装包。安装过程非常简单一路下一步即可。安装完成后Ollama服务会自动在后台运行。拉取并运行你的第一个模型 打开终端Windows上是PowerShell或CMDmacOS/Linux是Terminal输入以下命令拉取一个模型。对于初次尝试建议从较小的、性能不错的模型开始例如llama3.2:1b仅10亿参数对硬件要求极低或qwen2.5:0.5b。# 拉取并运行Llama 3.2 1B模型 ollama run llama3.2:1b首次运行会从网上下载模型文件速度取决于你的网络。下载完成后你会进入一个交互式命令行界面可以直接测试模型是否正常工作输入“Hello”看看它是否回应。验证API服务 Ollama在安装后默认会在http://localhost:11434提供一个兼容OpenAI API的接口。打开你的浏览器访问http://localhost:11434/api/tags。如果看到返回了JSON格式的模型列表例如包含你刚拉取的llama3.2:1b说明Ollama服务运行正常。{ models: [ { name: llama3.2:1b, modified_at: 2024-..., size: 600000000, digest: ... } ] }关键点请记住这个地址localhost:11434和端口下一步配置Page Assist时会用到。实操心得模型选择建议入门/低配置电脑从llama3.2:1b或qwen2.5:0.5b开始响应速度飞快内存占用小。平衡性能与资源llama3.2:3b或mistral:7b是很好的折中选择在8GB内存的电脑上也能流畅运行智能程度显著提升。追求更强能力如果你的电脑有16GB以上内存可以尝试llama3.1:8b或qwen2.5:7b。一个常见误区不是模型越大越好。过大的模型会导致响应缓慢影响交互体验。先从小的开始根据需求升级。3.2 第二步安装Page Assist浏览器扩展你有两种安装方式从官方商店安装最简单或手动构建安装适合开发者或想体验最新版。方式一从官方商店安装推荐这是最省事的方法。根据你的浏览器点击对应的链接Chrome/Edge/Brave等Chromium内核浏览器前往 Chrome 网上应用店 点击“添加至Chrome”。Firefox前往 Firefox 附加组件商店 点击“添加到Firefox”。安装后你的浏览器工具栏会出现Page Assist的图标一个类似聊天气泡的图标。方式二从源码手动构建安装如果你想体验最新的开发版功能或者有意参与贡献可以手动构建。# 1. 克隆代码仓库 git clone https://github.com/n4ze3m/page-assist.git cd page-assist # 2. 安装依赖项目使用Bun也可用npm bun install # 或 npm install # 3. 构建扩展 bun run build # 构建产物会生成在 build 目录下构建完成后在浏览器中打开扩展管理页面chrome://extensions开启“开发者模式”点击“加载已解压的扩展程序”选择刚才生成的build目录即可。3.3 第三步关键配置——连接扩展与本地AI服务安装好扩展只是完成了第一步现在需要告诉Page Assist去哪里找你的AI模型。点击浏览器工具栏上的Page Assist图标它会打开Web UI。或者使用快捷键CtrlShiftL(Windows/Linux) /CmdShiftL(Mac) 直接打开。在Web UI的右下角找到并点击设置齿轮图标。在设置面板中找到“AI Provider”或“后端配置”相关区域。将“API Base URL”修改为http://localhost:11434。这就是Ollama默认的API地址。在“模型”下拉菜单中你应该能看到之前在Ollama中拉取的模型如llama3.2:1b。选择它。通常不需要修改API密钥留空即可因为Ollama本地服务默认不需要认证。点击“保存”或“测试连接”。如果配置正确页面通常会提示连接成功或者你可以直接在聊天框发送一条消息测试。配置验证与常见问题连接失败首先确保Ollama正在运行终端里ollama run命令未退出或服务在后台运行。然后在浏览器中再次访问http://localhost:11434/api/tags确认API可达。模型列表为空检查API Base URL是否正确并确保Ollama中至少有一个模型已拉取通过ollama list命令查看。防火墙或端口冲突极少数情况下系统防火墙可能阻止了浏览器扩展访问本地11434端口。需要检查防火墙设置允许本地回环localhost通信。4. 深度使用技巧与高效工作流配置完成后Page Assist就变成了一个生产力利器。下面分享一些超越基础使用的技巧和高效工作流。4.1 掌握核心交互方式快捷键与模式切换依赖鼠标点按效率太低记住这几个核心快捷键能极大提升体验操作快捷键 (Windows/Linux)快捷键 (Mac)使用场景打开/关闭侧边栏CtrlShiftYCmdShiftY在任何网页快速呼出助手提问打开独立Web UICtrlShiftLCmdShiftL需要大窗口进行长对话或编程时侧边栏内新建聊天CtrlShiftOCmdShiftO快速清空当前上下文开始新话题侧边栏内聚焦输入框ShiftEscShiftEsc无论侧边栏在何状态直接开始打字侧边栏内切换网页聊天模式CtrlECmdE最关键的功能在当前页面和普通聊天间切换“与网页聊天”模式详解 这是Page Assist的杀手级功能。当你在阅读一个网页时按下CtrlE侧边栏的标题会提示“Chatting with [网页标题]”。此时你提出的任何问题AI都会基于当前打开的整个网页的内容来回答。例如“总结这篇文章的要点。”“列出本文提到的所有工具名称。”“根据文中的步骤为我生成一个检查清单。”“将这一段技术描述翻译成中文。”这个模式的工作原理是扩展通过内容脚本抓取了当前页面的document.body.innerText或经过处理的纯净文本并将其作为系统提示词的一部分发送给AI模型。因此对于内容非常长的页面如超长文档或论坛帖子响应可能会稍慢因为上下文很长。4.2 针对不同场景的模型使用策略不同的任务适合不同的模型你可以在Ollama中安装多个模型并在Page Assist设置中随时切换。快速信息提取与总结使用小参数模型如llama3.2:1b。它们速度极快对于从网页中提取事实、总结段落足够用能提供几乎即时的反馈。复杂分析与创意写作切换到更大的模型如llama3.1:8b。当你需要AI进行推理、对比、生成结构化的内容或代码时更大模型的逻辑能力和创造力优势明显。编程辅助专门使用在代码上训练过的模型如codellama:7b或deepseek-coder:6.7b。这些模型对代码语法、逻辑和生成更有把握在侧边栏里帮你解释代码片段、生成函数或调试错误时更加得心应手。切换模型的小技巧你可以在Web UI的设置里保存多个“配置预设”给它们起名为“快速总结”、“深度分析”、“编程助手”然后根据任务一键切换比每次都去下拉菜单选模型要快得多。4.3 提升“与网页聊天”准确性的技巧有时AI的回答可能未能精准抓住网页内容可以通过优化提问Prompt来解决指令要具体不要问“这篇文章讲什么”而是问“用三个要点总结这篇文章的核心观点”。指定格式“将网页中提到的所有产品名称和其价格以表格形式列出。”结合上下文可以先让AI总结然后基于总结继续追问细节。例如“好的根据你刚才的总结关于‘XXX技术’的部分作者提到的最大挑战是什么”处理复杂页面对于充斥着导航栏、广告、评论区的页面AI可能会抓取到无关文本。可以尝试先滚动到核心内容区域再激活聊天模式。更彻底的办法是使用浏览器的“阅读模式”如果有然后在阅读模式页面下使用Page Assist获取的文本会更纯净。5. 常见问题排查与进阶配置即使按照步骤操作也可能会遇到一些问题。这里是我在长期使用中遇到的一些典型情况及其解决方法。5.1 连接与响应问题排查表问题现象可能原因排查步骤与解决方案侧边栏无法打开或打开后空白1. 扩展未正确加载2. 与其他扩展冲突1. 进入chrome://extensions/确保Page Assist已启用。2. 尝试在无痕模式下测试默认禁用大部分扩展如果正常则存在扩展冲突需逐一禁用其他扩展排查。发送消息后一直显示“思考中…”或超时1. Ollama服务未运行2. API地址配置错误3. 模型未加载或内存不足1. 终端运行ollama list检查服务状态用ollama run 模型名重启。2. 检查Page Assist设置中的API URL是否为http://localhost:11434。3. 尝试换一个更小的模型或检查系统内存占用。能连接但回答内容完全无关或胡说八道1. 模型文件损坏2. 系统提示词被意外修改1. 在Ollama中重新拉取模型ollama pull 模型名。2. 检查Page Assist设置中是否有自定义的“系统指令”System Prompt恢复为默认或清空。“与网页聊天”模式获取的内容不对1. 页面是动态加载SPA2. 内容脚本被页面策略阻止1. 尝试刷新页面后等待几秒再使用该功能。2. 对于一些特殊网站如使用严格CSP的此功能可能受限这是浏览器安全策略限制。快捷键冲突或无响应1. 快捷键被其他应用或扩展占用2. 浏览器快捷键设置未同步1. 访问chrome://extensions/shortcuts可以查看和重新分配Page Assist的快捷键。2. 确保没有全局软件如剪贴板工具、翻译软件占用了相同快捷键。5.2 使用其他本地AI后端LM Studio示例除了Ollama你也可以使用LM Studio。它的优点是提供了非常友好的图形界面来管理和加载模型。安装并运行LM Studio从官网下载安装启动后从Hub下载你想要的模型。在LM Studio中加载并启动服务器在“本地服务器”标签页选择你加载的模型然后点击“启动服务器”。LM Studio会在http://localhost:1234/v1提供一个兼容OpenAI API的端点。配置Page Assist在设置中将“API Base URL”修改为http://localhost:1234/v1。在“模型”栏通常需要手动输入LM Studio中当前加载的模型名称LM Studio的API可能会自动列出。API密钥如果LM Studio设置了密钥需要在Page Assist中填写否则留空。注意LM Studio的API路径和模型名称传递方式可能与Ollama略有不同如果遇到问题需要查阅LM Studio的API文档。总体而言Ollama的集成更简单、更稳定是首选。5.3 隐私与数据安全再确认这是很多人选择Page Assist的首要原因。从原理上分析其隐私性网络请求当配置为本地AI提供商Ollama/LM Studio时所有HTTP请求的地址都是localhost或127.0.0.1这意味着数据只在你的电脑内部循环没有出站网络连接。你可以在浏览器开发者工具的“网络”选项卡中核实这一点。数据存储聊天记录、设置等数据默认存储在浏览器的本地存储IndexedDB/LocalStorage中。你可以通过浏览器的“开发者工具” - “应用” - “存储”中找到并查看虽然内容是加密或编码的。清除浏览器数据时会一并清除。开源审计项目代码完全开源在GitHub任何人都可以审查其代码确认没有隐藏的数据收集或上传逻辑。这是建立信任的基石。因此只要你正确配置了本地AI后端并确保其运行在你信任的设备上你的对话内容隐私就是有保障的。6. 开发与定制如果你是一名开发者Page Assist是开源项目这为开发者提供了巨大的定制空间。如果你觉得某些功能不满足需求可以尝试自己动手。运行开发环境git clone https://github.com/n4ze3m/page-assist.git cd page-assist bun install bun dev运行bun dev会启动一个开发服务器并监视文件变化。你可以在浏览器中加载dist目录开发模式下的输出目录作为解压的扩展实现实时热重载方便调试。主要技术栈与目录结构前端框架基于Vite构建使用React TypeScript。UI组件库是Shadcn/ui风格现代。核心通信使用Tauri的invoke机制虽然主体是浏览器扩展但部分架构借鉴了Tauri在扩展前端UI和后端Service Worker之间通信。与AI服务通信前端通过标准的Fetch API调用配置的AI提供商端点。关键目录src/background: 后台服务脚本管理状态和核心逻辑。src/content: 内容脚本负责注入页面和抓取网页文本。src/pages: 包含Popup弹出页、Sidebar侧边栏和独立Web UI的代码。src/components: 可复用的React组件。如何添加一个新AI提供商 如果你希望接入一个官方尚未支持的AI服务比如某个特定的云服务或新型本地API你需要研究如何在代码中增加一个新的“提供商适配器”。通常需要修改src/lib/ai-providers相关的文件实现该提供商特定的API调用格式和错误处理逻辑然后在UI的设置下拉菜单中注册这个新选项。这需要一定的TypeScript和HTTP客户端编程经验。给开发者的建议在贡献代码或提交Issue前先到项目的GitHub Discussions或Discord频道看看是否有类似讨论。由于项目迭代较快开发分支的代码可能和稳定版有差异。