Page Assist 本地AI扩展故障排除指南：从环境配置到日常使用

Page Assist 本地AI扩展故障排除指南：从环境配置到日常使用

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

一、环境依赖故障排除

1.1 Bun运行时安装失败

现象描述

执行bun install命令后终端显示command not found: bun，或出现EACCES: permission denied错误提示，无法继续项目依赖安装。

根因分析

Bun作为JavaScript运行时环境，需要正确配置系统环境变量（环境变量 - 系统查找程序的路径清单）才能被终端识别，权限不足或路径未添加会导致安装失败。

解决方案

1. 执行官方安装命令：

   curl -fsSL https://bun.sh/install | bash

2. 🔍 检查环境变量配置：

   echo $PATH | grep "$HOME/.bun/bin"

3. 若未找到路径，手动添加环境变量：

   echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc source ~/.bashrc

4. ✅ 验证安装结果：

   bun --version

补充：Linux/macOS系统若提示权限问题，可在命令前添加sudo；Windows系统需使用管理员模式运行PowerShell。

预防策略

安装完成后立即执行bun --version验证，确保输出类似1.0.25的版本号。建议将Bun更新命令添加到系统维护脚本：

# 添加到crontab或维护脚本 bun upgrade

经验总结

保持Bun版本在1.0.0以上可避免多数兼容性问题，定期执行bun doctor检查运行环境健康状态。

1.2 Ollama服务启动异常

现象描述

执行ollama run llama2后显示Error: could not connect to Ollama server，或服务启动后几秒自动终止。

根因分析

Ollama需要系统资源支持（至少4GB内存），端口冲突或数据目录权限问题会导致服务启动失败。

解决方案

1. 检查服务状态：

   systemctl status ollama # Linux系统 # 或 brew services list | grep ollama # macOS系统

2. ⚠️ 手动启动服务并查看日志：

   ollama serve > ollama.log 2>&1 & tail -f ollama.log

3. 检查端口占用情况：

   netstat -tulpn | grep 11434

4. 若端口冲突，修改配置文件：

   # 创建配置文件 mkdir -p ~/.ollama echo "OLLAMA_HOST=0.0.0.0:11435" > ~/.ollama/config

预防策略

设置Ollama开机自启：

# Linux系统 sudo systemctl enable ollama # macOS系统 brew services start ollama

经验总结

Ollama数据目录建议保留至少20GB空闲空间，模型文件默认存储在~/.ollama/models目录。

二、扩展加载故障排除

2.1 Chrome扩展加载失败

现象描述

在Chrome扩展页面加载解压后的扩展时，出现"程序包无效"错误，或加载后扩展图标不显示。

根因分析

扩展未正确编译或manifest.json配置错误，Chrome的严格安全策略会拒绝加载不符合规范的扩展。

解决方案

1. 确保已完成项目构建：

   cd /path/to/page-assist bun run build

2. 📌 重要提示：检查构建输出目录：

   ls -la build/ | grep manifest.json

3. 开启Chrome开发者模式：

   • 访问chrome://extensions/
   • 开启右上角"开发者模式"开关
   • 点击"加载已解压的扩展程序"
   • 选择项目的build目录

4. 检查扩展错误日志：

   • 在扩展页面点击"错误"链接
   • 或访问chrome://extensions/errors查看详细日志

预防策略

每次代码修改后执行：

bun run build && echo "Build completed successfully"

经验总结

开发环境建议使用bun run dev命令，实现代码修改自动编译和扩展热重载。

2.2 扩展功能无响应

现象描述

扩展成功加载，但点击图标无反应，或侧边栏打开后显示空白页面。

根因分析

扩展后台服务未正确启动，或内容脚本与页面权限冲突。

解决方案

1. 检查扩展后台页面：

   • 访问chrome://extensions/
   • 找到Page Assist扩展，点击"服务工作线程"链接

2. 查看控制台错误：

   • 在后台页面按F12打开开发者工具
   • 切换到Console标签查看错误信息

3. 重新加载扩展：

   • 在扩展页面点击"重新加载"按钮
   • 或使用快捷键Ctrl+R（Windows/Linux）或Cmd+R（macOS）

预防策略

定期清理Chrome扩展缓存：

# Linux/macOS系统 rm -rf ~/.config/google-chrome/Default/Extensions/[扩展ID]

经验总结

遇到功能异常时，先尝试在无痕模式下测试，排除其他扩展冲突可能。

三、功能使用故障排除

3.1 快捷键无法唤醒侧边栏

现象描述

按下设置的快捷键后无任何反应，或触发了系统其他功能而非Page Assist侧边栏。

根因分析

快捷键组合与系统或其他应用冲突，Chrome扩展快捷键优先级较低。

解决方案

1. 访问Chrome快捷键设置页面：

   • 在地址栏输入chrome://extensions/shortcuts

2. 🔍 检查冲突快捷键：

   • 找到Page Assist扩展的"切换侧边栏"命令
   • 查看当前快捷键是否显示"冲突"提示

3. 重新设置快捷键：

   • 点击快捷键输入框
   • 按下新组合（推荐Ctrl+Shift+L或Alt+P）
   • 确保无冲突提示后点击"确定"

预防策略

创建快捷键测试脚本：

# 保存为test-shortcut.sh xdotool key "ctrl+shift+l" # Linux系统测试命令

经验总结

避免使用单一修饰键（如仅Ctrl或Alt），优先选择Ctrl+Shift+字母组合减少冲突。

3.2 本地模型无法加载

现象描述

在扩展设置中选择模型后，聊天时显示"模型加载失败"，或生成内容一直处于加载状态。

根因分析

模型文件损坏、Ollama服务未运行，或模型名称与本地实际安装的不一致。

解决方案

1. 检查已安装模型：

   ollama list

2. 确保模型名称匹配：

   补充：扩展中选择的模型名称必须与ollama list输出完全一致

3. 重新拉取模型：

   ollama pull llama2 # 以llama2为例

4. 测试模型可用性：

   ollama run llama2 "hello"

预防策略

创建模型状态检查脚本：

#!/bin/bash # 保存为check-models.sh models=("llama2" "mistral" "gemma") for model in "${models[@]}"; do if ! ollama list | grep -q "$model"; then echo "Missing model: $model, pulling now..." ollama pull "$model" fi done

经验总结

大模型首次加载较慢属正常现象，建议先通过终端测试模型基本功能再在扩展中使用。

四、系统兼容性参考

4.1 最低系统要求

4.2 常见错误代码对照表

五、进阶使用技巧

5.1 依赖版本批量检查

创建版本检查脚本check-dependencies.sh：

#!/bin/bash echo "Bun version: $(bun --version)" echo "Ollama version: $(ollama --version)" echo "Node version: $(node --version)" echo "Chrome version: $(google-chrome --version | cut -d ' ' -f 3)"

添加执行权限并运行：

chmod +x check-dependencies.sh ./check-dependencies.sh

5.2 扩展日志实时监控

使用tail命令监控扩展日志：

# 查找扩展ID chrome-extensions list | grep "Page Assist" | awk '{print $1}' # 监控日志 tail -f ~/.config/google-chrome/Default/Extensions/[扩展ID]/[版本]/background.log

通过以上故障排除指南，您应该能够解决Page Assist扩展从环境配置到日常使用过程中的大部分问题。如遇到特殊情况，建议先查看项目的官方文档或在社区寻求帮助。

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