Page Assist 故障排除手册：从环境配置到功能调优的实战指南

Page Assist 是一款能够让用户在 Chrome 浏览器中直接与本地 AI 模型进行交互的扩展工具，它可以在用户浏览任意网页时随时调出侧边栏进行 AI 互动。本手册将针对 Page Assist 在使用过程中可能出现的各类技术问题，从问题诊断、根源解析、解决方案到预防策略，为您提供全面且实用的故障排除方案，助力您顺利使用该工具。

目录导航

• 启动失败：Bun 或 Ollama 服务进程未运行
• 扩展加载失败：manifest 验证错误
• 功能异常：快捷键无响应或冲突

启动失败：Bun 或 Ollama 服务进程未运行

问题诊断

在尝试启动 Page Assist 时，工具无任何响应，或在终端中出现服务启动失败的错误提示，无法正常调用本地 AI 模型进行交互。

根源解析

Bun 作为 JavaScript 运行环境，Ollama 作为本地 AI 模型的管理工具，二者是 Page Assist 正常运行的核心依赖。启动失败通常是由于二者之一未正确安装、服务未启动，或者环境变量（PATH：系统查找可执行文件的路径列表）配置不当，导致系统无法找到相关可执行文件。

[原理图解] 展示 Bun 与 Ollama 的进程通信机制：Bun 负责运行扩展的 JavaScript 代码，Ollama 管理本地 AI 模型的加载与运行，二者通过进程间通信实现数据交互，为 Page Assist 提供 AI 能力支持。

解决方案

Bun 环境配置

1. 前提条件：确保系统满足 Bun 的安装要求（可参考官方文档了解具体系统版本支持情况）。
2. 操作指令：前往 Bun 官网，获取对应系统的安装命令，在终端中执行。例如 Linux 或 macOS 系统可使用 curl -fsSL https://bun.sh/install | bash 命令进行安装。
3. 验证方法：安装完成后，重启终端，输入 bun --version，若能显示出版本号，则说明 Bun 安装成功。

Ollama 环境配置

1. 前提条件：确认系统符合 Ollama 的安装条件，Windows 用户需注意系统权限相关设置。
2. 操作指令：访问 Ollama 官网，根据系统版本下载并安装 Ollama。安装完成后，系统会自动尝试启动服务，也可在终端中输入 ollama serve 手动启动服务。
3. 验证方法：在终端输入 ollama --version，若显示版本信息，则 Ollama 安装成功。

环境变量检查

1. 前提条件：已安装 Bun 和 Ollama。
2. 操作指令：在终端输入 echo $PATH，查看输出中是否包含 Bun 的安装路径（一般为 ~/.bun/bin）和 Ollama 的相关路径。
3. 验证方法：若路径未包含，需手动将其添加到环境变量中。例如，在 Linux 系统中，可编辑 ~/.bashrc 或 ~/.zshrc 文件，添加 export PATH="$HOME/.bun/bin:$PATH" 等类似语句，然后执行 source ~/.bashrc 或 source ~/.zshrc 使配置生效。

⚠️ 关键操作：安装过程中若遇到权限问题，Linux/macOS 用户可在命令前添加 sudo，Windows 用户需以管理员身份打开终端。

诊断命令集

• 检查 Bun 安装路径：echo $PATH | grep bun
• 检查 Ollama 服务状态：systemctl status ollama（Linux 系统）或 sc query ollama（Windows 系统）
• 验证 Bun 版本：bun --version
• 验证 Ollama 版本：ollama --version

进阶技巧

• 可以使用 bun doctor 命令检查 Bun 的安装和配置情况，获取详细的诊断报告。
• 对于 Ollama，可通过 ollama logs 查看服务运行日志，以便排查启动过程中的具体错误。

避坑指南

• 安装前仔细阅读官方文档中的系统要求，避免在不支持的系统版本上安装。
• 安装完成后，务必按照上述验证方法确认 Bun 和 Ollama 均能正常运行，避免后续使用中出现问题。

扩展加载失败：manifest 验证错误

问题诊断

在 Chrome 浏览器中加载 Page Assist 扩展时，浏览器提示“无法加载扩展程序”或“清单文件无效”等错误信息，导致扩展无法正常安装。

根源解析

扩展加载失败通常是由于未开启 Chrome 的开发者模式，或者选择了错误的扩展目录，也可能是扩展的配置文件 manifest.json 存在语法错误或格式不符合 Chrome 扩展的要求。

解决方案

开启开发者模式

1. 前提条件：已安装 Chrome 浏览器。
2. 操作指令：打开 Chrome 浏览器，在地址栏输入 chrome://extensions/ 进入扩展管理页面，将页面右上角的“开发者模式”开关打开（开关变为蓝色即表示开启）。
3. 验证方法：开启后，扩展管理页面会出现“加载已解压的扩展程序”等按钮。

编译并选择正确目录

1. 前提条件：已获取 Page Assist 项目源码（仓库地址：https://gitcode.com/GitHub_Trending/pa/page-assist），并安装了 Bun 环境。
2. 操作指令：在项目根目录下运行 bun run build 命令，生成 build 目录。然后在 Chrome 扩展管理页面点击“加载已解压的扩展程序”按钮，选择生成的 build 目录。
3. 验证方法：若扩展成功加载，在扩展管理页面会显示 Page Assist 的相关信息。

检查 manifest.json 文件

1. 前提条件：扩展加载失败，且已确认开发者模式开启和目录选择正确。
2. 操作指令：使用代码编辑器（如 VS Code）打开 build 目录下的 manifest.json 文件，检查是否有语法错误（如红色波浪线提示）。
3. 验证方法：修复语法错误后，重新加载扩展，观察是否能成功加载。

⚠️ 关键操作：manifest.json 文件的格式需严格遵循 Chrome 扩展的规范，可参考 Chrome 开发者文档中的相关说明进行检查和修改。

诊断命令集

• 检查 build 目录是否存在：ls -l build（Linux/macOS）或 dir build（Windows）
• 验证 manifest.json 格式：可使用在线 JSON 验证工具对文件内容进行验证。

进阶技巧

• 在项目开发过程中，可使用 bun run dev 命令启动开发模式，实时监控代码变化并自动重新编译，便于及时发现和解决 manifest.json 等配置文件的问题。

避坑指南

• 每次修改项目代码后，都应重新运行 bun run build 命令，确保 build 目录中的文件为最新版本。
• 加载扩展前，确认 build 目录中存在 manifest.json 文件，且文件名正确无误。

功能异常：快捷键无响应或冲突

问题诊断

按下 Page Assist 的快捷键后，侧边栏未弹出，或触发了其他软件的功能，导致无法正常调出 Page Assist 进行使用。

根源解析

Chrome 扩展的快捷键是全局生效的，容易与系统自带快捷键、其他软件的快捷键发生冲突。此外，快捷键可能未正确设置或被禁用，也会导致无响应的情况。

解决方案

访问快捷键设置页面

1. 前提条件：已在 Chrome 浏览器中安装 Page Assist 扩展。
2. 操作指令：在 Chrome 地址栏输入 chrome://extensions/shortcuts，进入扩展快捷键设置页面。
3. 验证方法：页面中会显示已安装扩展的快捷键设置情况。

修改冲突快捷键

1. 前提条件：在快捷键设置页面找到 Page Assist 扩展。
2. 操作指令：点击 Page Assist 扩展对应的快捷键输入框，按下新的快捷键组合（如 Ctrl+Shift+P），注意避免与其他快捷键冲突（输入框下方会提示是否冲突）。
3. 验证方法：设置完成后，打开一个新网页，按下新设置的快捷键，检查 Page Assist 侧边栏是否能正常弹出。

💡 专家建议：设置快捷键时，尽量选择 Ctrl+Shift+字母 或 Alt+Shift+字母 这样的组合，相对不容易与系统或其他软件的快捷键冲突。

诊断命令集

• 查看 Chrome 扩展快捷键：在 chrome://extensions/shortcuts 页面手动查找 Page Assist 的快捷键设置。

进阶技巧

• 可以在 Chrome 浏览器的设置中，搜索“快捷键”，查看系统和浏览器本身的快捷键设置，以便更好地选择不冲突的 Page Assist 快捷键。

避坑指南

• 选择快捷键时，回想自己常用软件的快捷键组合，尽量避开，减少冲突概率。
• 可将设置好的快捷键记录下来，方便后续使用时查阅。

问题排查流程图

开始
│
├─ 遇到问题
│
├─ 判断问题类型
│   ├─ 启动失败
│   │   ├─ 检查 Bun 是否安装成功（运行 bun --version）
│   │   ├─ 检查 Ollama 是否安装成功（运行 ollama --version）
│   │   ├─ 检查环境变量配置（运行 echo $PATH | grep bun 和 echo $PATH | grep ollama）
│   │   └─ 根据检查结果修复问题（重新安装或配置环境变量）
│   │
│   ├─ 扩展加载失败
│   │   ├─ 检查是否开启开发者模式（访问 chrome://extensions/）
│   │   ├─ 检查是否编译生成 build 目录（运行 ls -l build 或 dir build）
│   │   ├─ 检查 manifest.json 是否有语法错误（使用编辑器查看）
│   │   └─ 根据检查结果修复问题（开启开发者模式、重新编译或修复 manifest.json）
│   │
│   └─ 快捷键异常
│       ├─ 访问 chrome://extensions/shortcuts 查看快捷键设置
│       ├─ 检查是否有快捷键冲突
│       └─ 修改为不冲突的快捷键
│
└─ 问题解决

相关资源

• 官方文档：docs/index.md
• 常见问题解答：docs/connection-issue.md
• 社区支持：可在项目相关交流平台参与讨论，获取帮助和分享经验