Page Assist 本地AI交互功能故障实战解决方案

【免费下载链接】page-assist Use your locally running AI models to assist you in your web browsing 项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist

Page Assist作为一款支持本地AI模型的浏览器扩展，让用户能在网页浏览时随时调用侧边栏进行AI交互。本文将围绕安装配置、扩展加载和快捷键使用三大核心问题，通过"问题定位→故障排除→预防方案"的系统化框架，帮助用户快速解决使用过程中的技术难题，全面提升Page Assist的使用体验。

一、Bun与Ollama环境配置失败问题

问题定位

当用户执行项目依赖安装命令时，终端出现"Bun: command not found"或Ollama启动后进程立即退出的现象，导致Page Assist无法正常运行本地AI模型。

故障排除

排查流程图解

检查系统兼容性 → 验证安装命令 → 配置环境变量 → 服务状态检测 → 版本验证

分步操作

1. 🔍 系统兼容性检查
   确认操作系统符合要求：Bun支持macOS 12+、Linux kernel 5.6+；Ollama要求Windows 10+、macOS 11+或Linux x86_64。

2. ✅ Bun安装与配置

   curl -fsSL https://bun.sh/install | bash  # 使用官方脚本安装Bun
   source ~/.bashrc  # 刷新环境变量
   echo $PATH | grep "$HOME/.bun/bin"  # 验证Bun路径已添加
   

3. ✅ Ollama服务部署

   # Linux系统示例
   curl -fsSL https://ollama.com/install.sh | sh
   systemctl start ollama  # 启动服务
   systemctl enable ollama  # 设置开机自启
   

4. 🔍 版本验证

   bun --version  # 应输出1.0.0+版本号
   ollama --version  # 应输出0.1.20+版本号
   

预防方案

检查项	推荐配置	验证命令
系统版本	Ubuntu 20.04+/macOS 12+/Win10+	lsb_release -a/sw_vers
依赖状态	Bun ≥1.0.0, Ollama ≥0.1.20	bun -v && ollama -v
环境变量	包含~/.bun/bin	echo $PATH | grep bun
服务状态	Ollama服务运行中	systemctl status ollama

延伸阅读：项目环境配置文档可参考 docs/setup.md

二、Chrome扩展加载失败问题

问题定位

当用户在Chrome扩展页面加载Page Assist时，出现"无法加载扩展程序"错误提示，或加载后扩展图标不显示，侧边栏无法调出。

故障排除

排查流程图解

开启开发者模式 → 确认构建产物 → 验证manifest文件 → 重新加载扩展

分步操作

1. 🔍 启用开发者模式
   打开Chrome浏览器，访问chrome://extensions/，开启右上角"开发者模式"开关，此时页面会显示"加载已解压的扩展程序"按钮。

2. ✅ 构建项目文件

   git clone https://gitcode.com/GitHub_Trending/pa/page-assist  # 克隆仓库
   cd page-assist
   bun install  # 安装依赖
   bun run build  # 生成构建文件
   

3. 🔍 验证构建结果
   检查项目根目录下是否生成build文件夹，且该文件夹中包含manifest.json文件：

   ls build/manifest.json  # 应显示文件路径
   

4. ✅ 加载扩展程序
   点击"加载已解压的扩展程序"，选择项目的build目录。如出现清单错误，可使用JSON验证工具检查manifest.json语法。

预防方案

检查项	推荐配置	验证方法
构建状态	build目录存在且完整	ls build | wc -l ≥20
清单文件	符合Chrome扩展v3标准	无JSON语法错误
开发模式	已启用	Chrome扩展页面开关为蓝色
Node版本	≥18.0.0	node -v

延伸阅读：扩展开发指南可参考 docs/extension-dev.md

三、快捷键功能失效问题

问题定位

当用户按下预设快捷键（如Ctrl+Shift+P）时，Page Assist侧边栏未弹出，或触发了其他应用程序的功能，导致无法正常调用扩展。

故障排除

排查流程图解

访问快捷键设置 → 检查冲突 → 重新配置 → 测试验证

分步操作

1. 🔍 进入快捷键设置
   在Chrome地址栏输入chrome://extensions/shortcuts，直接访问扩展快捷键管理页面。

2. ✅ 修改冲突快捷键
   找到Page Assist扩展，点击快捷键输入框，按下新的组合键（推荐使用Ctrl+Shift+[字母]格式）。系统会自动提示"与其他扩展冲突"的警告。

3. 🔍 测试快捷键功能
   打开任意网页，按下新设置的快捷键，验证侧边栏是否弹出。若仍无反应，可在Chrome任务管理器（Shift+Esc）中检查扩展进程是否运行。

预防方案

检查项	推荐配置	验证方法
快捷键组合	Ctrl+Shift+字母	无系统/应用冲突
扩展状态	已启用	Chrome扩展页面显示"已启用"
进程状态	Page Assist进程运行中	Chrome任务管理器查看
浏览器版本	Chrome ≥110.0	chrome://version

延伸阅读：快捷键配置详情可参考 docs/shortcuts.md

通过以上系统化的故障排除方案，用户可以有效解决Page Assist在安装配置、扩展加载和快捷键使用过程中的常见问题。建议在使用前参照预防方案中的环境检查清单进行预处理，以确保扩展功能的稳定运行。如遇到其他技术问题，可查阅项目文档或社区讨论获取支持。

【免费下载链接】page-assist Use your locally running AI models to assist you in your web browsing 项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist