Page Assist：基于本地大模型的浏览器AI助手，实现隐私安全的网页交互

1. 项目概述：一个能与网页对话的本地AI助手

如果你和我一样，对AI助手既爱又恨——爱它的便利，恨它背后那说不清道不明的数据隐私和持续不断的订阅费用——那么今天聊的这个开源项目，你可能会非常感兴趣。它叫Page Assist，本质上是一个浏览器扩展，但它做的不是广告拦截或密码管理，而是把一个功能完整的、运行在你自己电脑上的AI大模型，直接“嵌入”到你的浏览器侧边栏里。

想象一下这个场景：你正在浏览一篇长达几十页的技术文档，想快速找到某个API的调用示例。传统做法是Ctrl+F搜索关键词，然后在一堆结果里翻找。而有了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的功能可以清晰地分为三个层次，理解它们有助于我们后续的配置和问题排查。

1. 侧边栏聊天（Sidebar Chat）：这是最常用的功能。一个固定在浏览器右侧的可折叠面板，提供了一个类似ChatGPT的聊天界面。你可以在这里进行普通的对话，也可以一键切换到“与当前网页聊天”模式。在此模式下，扩展会自动将当前页面的文本内容作为上下文提供给AI模型，使得你的提问能基于页面内容得到精准回答。

2. 独立Web界面（Web UI）：点击扩展图标或在新建标签页中打开的一个全功能聊天界面。它比侧边栏空间更大，更适合进行长时间的、复杂的对话或代码编写。你可以把它看作一个本地的、迷你版的ChatGPT网页客户端。

3. 本地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是整个系统的核心，必须先安装并运行起来。

1. 下载与安装：

   • 访问 Ollama官网 ，根据你的操作系统（Windows/macOS/Linux）下载安装包。
   • 安装过程非常简单，一路下一步即可。安装完成后，Ollama服务会自动在后台运行。

2. 拉取并运行你的第一个模型： 打开终端（Windows上是PowerShell或CMD，macOS/Linux是Terminal），输入以下命令拉取一个模型。对于初次尝试，建议从较小的、性能不错的模型开始，例如llama3.2:1b（仅10亿参数，对硬件要求极低）或qwen2.5:0.5b。

   # 拉取并运行Llama 3.2 1B模型 ollama run llama3.2:1b

   首次运行会从网上下载模型文件，速度取决于你的网络。下载完成后，你会进入一个交互式命令行界面，可以直接测试模型是否正常工作，输入“Hello”看看它是否回应。

3. 验证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模型。

1. 点击浏览器工具栏上的Page Assist图标，它会打开Web UI。或者使用快捷键Ctrl+Shift+L(Windows/Linux) /Cmd+Shift+L(Mac) 直接打开。
2. 在Web UI的右下角，找到并点击设置（齿轮）图标。
3. 在设置面板中，找到“AI Provider”或“后端配置”相关区域。
4. 将“API Base URL”修改为http://localhost:11434。这就是Ollama默认的API地址。
5. 在“模型”下拉菜单中，你应该能看到之前在Ollama中拉取的模型（如llama3.2:1b）。选择它。
6. 通常不需要修改API密钥（留空即可），因为Ollama本地服务默认不需要认证。
7. 点击“保存”或“测试连接”。如果配置正确，页面通常会提示连接成功，或者你可以直接在聊天框发送一条消息测试。

配置验证与常见问题：

• 连接失败：首先确保Ollama正在运行（终端里ollama run命令未退出，或服务在后台运行）。然后在浏览器中再次访问http://localhost:11434/api/tags确认API可达。
• 模型列表为空：检查API Base URL是否正确，并确保Ollama中至少有一个模型已拉取（通过ollama list命令查看）。
• 防火墙或端口冲突：极少数情况下，系统防火墙可能阻止了浏览器扩展访问本地11434端口。需要检查防火墙设置，允许本地回环（localhost）通信。

4. 深度使用技巧与高效工作流

配置完成后，Page Assist就变成了一个生产力利器。下面分享一些超越基础使用的技巧和高效工作流。

4.1 掌握核心交互方式：快捷键与模式切换

依赖鼠标点按效率太低，记住这几个核心快捷键能极大提升体验：

“与网页聊天”模式详解： 这是Page Assist的杀手级功能。当你在阅读一个网页时，按下Ctrl+E，侧边栏的标题会提示“Chatting with [网页标题]”。此时，你提出的任何问题，AI都会基于当前打开的整个网页的内容来回答。例如：

• “总结这篇文章的要点。”
• “列出本文提到的所有工具名称。”
• “根据文中的步骤，为我生成一个检查清单。”
• “将这一段技术描述翻译成中文。”

这个模式的工作原理是，扩展通过内容脚本抓取了当前页面的document.body.innerText或经过处理的纯净文本，并将其作为系统提示词的一部分发送给AI模型。因此，对于内容非常长的页面（如超长文档或论坛帖子），响应可能会稍慢，因为上下文很长。

4.2 针对不同场景的模型使用策略

不同的任务适合不同的模型，你可以在Ollama中安装多个模型，并在Page Assist设置中随时切换。

1. 快速信息提取与总结：使用小参数模型（如llama3.2:1b）。它们速度极快，对于从网页中提取事实、总结段落足够用，能提供几乎即时的反馈。
2. 复杂分析与创意写作：切换到更大的模型（如llama3.1:8b）。当你需要AI进行推理、对比、生成结构化的内容或代码时，更大模型的逻辑能力和创造力优势明显。
3. 编程辅助：专门使用在代码上训练过的模型，如codellama:7b或deepseek-coder:6.7b。这些模型对代码语法、逻辑和生成更有把握，在侧边栏里帮你解释代码片段、生成函数或调试错误时更加得心应手。

切换模型的小技巧：你可以在Web UI的设置里保存多个“配置预设”，给它们起名为“快速总结”、“深度分析”、“编程助手”，然后根据任务一键切换，比每次都去下拉菜单选模型要快得多。

4.3 提升“与网页聊天”准确性的技巧

有时AI的回答可能未能精准抓住网页内容，可以通过优化提问（Prompt）来解决：

• 指令要具体：不要问“这篇文章讲什么？”，而是问“用三个要点总结这篇文章的核心观点”。
• 指定格式：“将网页中提到的所有产品名称和其价格以表格形式列出。”
• 结合上下文：可以先让AI总结，然后基于总结继续追问细节。例如：“好的，根据你刚才的总结，关于‘XXX技术’的部分，作者提到的最大挑战是什么？”
• 处理复杂页面：对于充斥着导航栏、广告、评论区的页面，AI可能会抓取到无关文本。可以尝试先滚动到核心内容区域，再激活聊天模式。更彻底的办法是使用浏览器的“阅读模式”（如果有），然后在阅读模式页面下使用Page Assist，获取的文本会更纯净。

5. 常见问题排查与进阶配置

即使按照步骤操作，也可能会遇到一些问题。这里是我在长期使用中遇到的一些典型情况及其解决方法。

5.1 连接与响应问题排查表

5.2 使用其他本地AI后端（LM Studio示例）

除了Ollama，你也可以使用LM Studio。它的优点是提供了非常友好的图形界面来管理和加载模型。

1. 安装并运行LM Studio：从官网下载安装，启动后从Hub下载你想要的模型。
2. 在LM Studio中加载并启动服务器：在“本地服务器”标签页，选择你加载的模型，然后点击“启动服务器”。LM Studio会在http://localhost:1234/v1提供一个兼容OpenAI API的端点。
3. 配置Page Assist：在设置中，将“API Base URL”修改为http://localhost:1234/v1。在“模型”栏，通常需要手动输入LM Studio中当前加载的模型名称（LM Studio的API可能会自动列出）。
4. 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频道看看是否有类似讨论。由于项目迭代较快，开发分支的代码可能和稳定版有差异。