Page Assist 本地AI助手使用指南：从环境搭建到功能使用的常见问题解决方法

Page Assist 是一款能够让你在 Chrome 浏览器中直接与本地 AI 模型进行交互的扩展工具，无论你正在浏览什么网页，都能随时调出侧边栏与 AI 展开对话。不过，在初次使用时，可能会遇到一些问题，别担心！本指南将帮助你解决那些常见问题。

环境准备类问题

开发环境搭建失败？快速搞定 Bun 与 Ollama 安装

现象描述

按照教程安装依赖时，Bun 命令无法使用，或者 Ollama 启动失败，终端出现大量错误提示。

原因拆解

Bun 是 JavaScript 运行环境，就像 AI 模型的专属快递员，负责把指令送到正确的地方；Ollama 则是本地 AI 模型的“管家”，管理着模型的运行。安装失败通常是因为系统环境变量（系统找到程序位置的路标）配置不当，或者安装步骤缺失。

阶梯式解决方案

1. 安装 Bun

   • 操作指令：前往 Bun 官网，获取对应系统的安装命令，在终端中执行。例如 Linux 或 macOS 用户一般运行 curl -fsSL https://bun.sh/install | bash。
   • 预期结果：终端显示安装进度，最终提示安装成功。

2. 检查 Bun 路径

   • 操作指令：安装完成后，重启终端，输入 echo $PATH。
   • 预期结果：输出内容中包含 Bun 的安装路径，通常为 ~/.bun/bin。若未包含，需手动将其添加到环境变量。

3. 安装 Ollama

   • 操作指令：访问 Ollama 官网，选择合适的系统版本下载安装。Windows 用户注意在安装过程中若弹出防火墙允许提示，需点击“允许”。
   • 预期结果：软件成功安装到系统中。

4. 启动 Ollama 服务

   • 操作指令：安装完成后，系统会自动启动服务，也可在终端输入 ollama serve 手动启动。
   • 预期结果：终端显示“server started on port 11434”。

5. 验证安装

   • 操作指令：在终端分别输入 bun --version 和 ollama --version。
   • 预期结果：能显示出各自的版本号。

预防贴士

⚠️ 安装过程中若遇到权限问题，Linux/macOS 用户可在命令前加 sudo，Windows 用户需用管理员身份打开终端。安装前查看系统要求，Bun 和 Ollama 对系统版本有要求，过旧的系统可能不支持。安装完成后，先按上述方法验证，避免后续出现问题难以排查。

功能启用类问题

扩展加载出错？解决 Chrome 无法加载扩展的问题

现象描述

在 Chrome 中加载 Page Assist 扩展时，没有反应或弹出错误窗口提示“无法加载扩展程序”，且未说明具体原因。

原因拆解

最常见的原因是未开启 Chrome 的开发者模式，或者选择了错误的加载文件夹，也有可能是扩展的配置文件 manifest.json 存在错误。

阶梯式解决方案

1. 开启开发者模式

   • 操作指令：打开 Chrome 浏览器，在地址栏输入 chrome://extensions/ 进入扩展页面，将页面右上角的“开发者模式”开关打开，开关变为蓝色即开启成功。
   • 预期结果：扩展页面显示出“加载已解压的扩展程序”等开发者相关按钮。

2. 生成扩展目录

   • 操作指令：Page Assist 项目需要先编译生成 build 目录。若尚未编译，在项目根目录运行 bun run build 命令。
   • 预期结果：项目根目录下生成 build 目录。

3. 加载扩展

   • 操作指令：点击扩展页面上的“加载已解压的扩展程序”按钮，在文件选择窗口中找到项目的 build 目录并选中。
   • 预期结果：扩展成功加载到 Chrome 浏览器中。

4. 检查 manifest 文件

   • 操作指令：若加载失败，用编辑器打开 build 目录中的 manifest.json 文件，查看是否有语法错误提示。
   • 预期结果：文件中无红色波浪线等语法错误提示。

预防贴士

💡 每次修改代码后，重新运行 bun run build 命令，确保 build 目录里的文件是最新的。加载扩展前，确认 build 目录中有 manifest.json 文件，且文件名正确。

日常使用类问题

快捷键没反应？解决 Page Assist 快捷键冲突问题

现象描述

按教程中的快捷键想调出 Page Assist 侧边栏，却没有任何反应，或者打开了浏览器的其他功能，甚至启动了其他软件。

原因拆解

Chrome 扩展的快捷键是全局的，容易与系统自带或其他软件的快捷键冲突。例如 Page Assist 默认的快捷键可能与输入法、截图工具的快捷键相同。

阶梯式解决方案

1. 打开快捷键设置页面

   • 操作指令：在 Chrome 地址栏输入 chrome://extensions/shortcuts，进入扩展快捷键设置页面。
   • 预期结果：显示所有扩展的快捷键设置情况。

2. 找到 Page Assist 扩展

   • 操作指令：在该页面中向下翻找，找到 Page Assist 扩展，其旁边会显示当前的快捷键设置。
   • 预期结果：清晰看到 Page Assist 扩展的当前快捷键。

3. 修改冲突的快捷键

   • 操作指令：点击要修改的快捷键输入框，按下新的快捷键组合（如 Ctrl+Shift+P），注意查看输入框下方是否有“与其他扩展冲突”的提示，若有则更换。
   • 预期结果：设置新的无冲突快捷键。

4. 测试新快捷键

   • 操作指令：设置完成后，打开一个新的网页，按下新设置的快捷键。
   • 预期结果：Page Assist 侧边栏成功弹出。

预防贴士

📌 设置快捷键时，尽量使用 Ctrl+Shift+字母 或者 Alt+Shift+字母 这样的组合，不容易与系统快捷键冲突。可以将设置好的快捷键记录下来，避免遗忘。

问题自查清单

问题类型	关键验证步骤
环境准备类	1. 执行 bun --version 查看 Bun 版本 2. 执行 ollama --version 查看 Ollama 版本 3. 检查环境变量中是否包含 Bun 安装路径
功能启用类	1. 确认 Chrome 开发者模式已开启 2. 检查 build 目录是否存在且包含 manifest.json 文件 3. 重新编译项目生成最新 build 目录
日常使用类	1. 在 chrome://extensions/shortcuts 中检查快捷键设置 2. 测试新设置的快捷键能否调出侧边栏

希望这份指南能帮助你顺利使用 Page Assist！如果遇到其他问题，可以查阅项目的官方文档，或者在社区与其他用户交流。祝你使用愉快！