Page Assist实战排障指南：从环境搭建到功能调优的全流程解决方案

Page Assist是一款允许用户在浏览器中直接与本地AI模型交互的扩展工具，通过侧边栏即可实现网页内容的智能辅助。本文将帮助开发者和普通用户解决从安装配置到日常使用中的各类技术问题，提升工具使用体验。

环境配置问题：本地AI服务启动失败

场景化问题描述

在终端执行bun run dev启动开发服务器后，页面提示"无法连接到本地AI服务"，Ollama服务状态显示为红色未运行状态，同时浏览器控制台出现"net::ERR_CONNECTION_REFUSED"错误。

技术原理解析

Page Assist依赖两个核心服务：Bun作为JavaScript运行时环境负责扩展程序的构建与运行，Ollama提供本地AI模型的管理与推理能力。当这两个服务任何一个未能正确启动或配置，都会导致扩展无法正常工作。Bun需要正确设置环境变量（Environment Variables）才能被系统识别，而Ollama则需要后台服务持续运行以提供API接口。

阶梯式解决方案

初级解决步骤

🛠️ 检查Bun安装状态

# 验证Bun是否正确安装
bun --version
# 若未显示版本号，执行安装命令
curl -fsSL https://bun.sh/install | bash
# 手动添加环境变量（Linux/macOS）
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

🛠️ 验证Ollama服务状态

# 检查Ollama服务状态
systemctl status ollama  # Linux系统
# 或
brew services list | grep ollama  # macOS系统

# 若服务未运行，手动启动
ollama serve &
# 验证模型是否已拉取
ollama list
# 若为空，拉取默认模型
ollama pull llama3

进阶解决步骤

🛠️ 网络端口冲突排查

# 检查Ollama默认端口是否被占用
netstat -tulpn | grep 11434
# 若被占用，修改Ollama配置文件
nano ~/.ollama/config.json
# 添加端口配置
{
  "port": 11435
}
# 重启Ollama服务
systemctl restart ollama

可视化预防方案

检查项目	验证方法	状态指示
Bun环境变量	echo $PATH包含~/.bun/bin	✅ 路径存在
Ollama服务	curl http://localhost:11434/api/version返回版本信息	✅ 响应200
模型可用性	ollama list显示至少一个模型	✅ 模型列表非空
网络连接	telnet localhost 11434能建立连接	✅ 连接成功

[!TIP] 知识扩展：Ollama采用客户端-服务器架构，服务端在本地11434端口提供REST API，Page Assist通过WebSocket与其通信。若服务启动但无法连接，可检查防火墙设置是否阻止了端口访问。

替代方案

1. Docker容器化部署：使用Docker Compose一键启动Bun和Ollama服务，避免环境依赖冲突
2. 手动指定服务地址：在扩展设置中手动输入Ollama服务地址，适用于远程部署场景
3. 使用预编译版本：下载项目release页面的预编译扩展包，跳过本地构建步骤

新手常见误区

错误操作	正确做法
未启动Ollama直接使用扩展	先执行ollama serve启动服务
修改配置后未重启服务	配置变更后执行systemctl restart ollama
使用普通用户权限安装系统服务	Linux系统需用sudo权限安装Ollama服务
同时启动多个Ollama实例	确保只有一个Ollama服务实例在运行

扩展加载问题：Chrome扩展安装失败

场景化问题描述

在Chrome浏览器的扩展管理页面，选择"加载已解压的扩展程序"并指向项目的dist目录后，页面顶部出现红色错误提示："无法加载扩展程序"，未提供具体错误原因，扩展图标未出现在工具栏中。

技术原理解析

Chrome扩展加载失败通常与扩展清单文件（manifest.json）密切相关。v3版本的扩展清单有严格的格式要求，包括正确的权限声明、服务工作线程配置和资源路径定义。此外，Chrome的安全策略要求扩展必须在开发者模式下加载，且代码必须通过基本的安全检查，如没有明显的恶意代码或资源引用错误。

阶梯式解决方案

初级解决步骤

🛠️ 启用开发者模式并正确加载

1. 打开Chrome浏览器，访问chrome://extensions
2. 右上角开启"开发者模式"开关（蓝色表示已开启）
3. 点击"加载已解压的扩展程序"按钮
4. 导航至项目根目录下的dist文件夹（确保已执行bun run build生成该目录）
5. 点击"选择文件夹"完成加载

🛠️ 检查构建输出

# 重新构建项目并观察输出
bun run build
# 检查是否有错误信息
# 若出现"manifest.json: Invalid JSON"错误
cat dist/manifest.json | jq .
# 修复JSON格式错误后重新构建

进阶解决步骤

🔍 诊断清单文件问题

# 安装Chrome扩展验证工具
npm install -g chrome-extension-manifest-validator
# 验证清单文件
chrome-extension-manifest-validator dist/manifest.json

🛠️ 修复常见清单错误

// 正确的manifest.json结构示例
{
  "manifest_version": 3,
  "name": "Page Assist",
  "version": "1.0.0",
  "permissions": ["activeTab", "storage", "scripting"],
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/16.png",
      "48": "icons/48.png",
      "128": "icons/128.png"
    }
  },
  "background": {
    "service_worker": "background.js"
  },
  "side_panel": {
    "default_path": "sidepanel.html"
  }
}

可视化预防方案

扩展加载前检查清单

• [ ] manifest.json文件存在于dist目录中
• [ ] manifest_version设置为3
• [ ] 所有声明的权限都是必要的
• [ ] 图标文件路径正确且文件存在
• [ ] service_worker文件路径正确

[!TIP] 知识扩展：Chrome扩展v3相比v2有重大架构变化，最大的区别是用service_worker替代了background page，并且对权限管理更加严格。如果从旧版迁移项目，需要重点检查background配置和权限声明部分。

替代方案

1. 使用开发工具调试：通过chrome://extensions页面的"背景页"链接打开开发者工具，查看控制台错误信息
2. 创建测试配置：复制一份manifest.json作为manifest-dev.json，简化配置进行测试
3. 使用浏览器隐身模式：在隐身窗口中加载扩展，排除其他扩展冲突影响

新手常见误区

错误操作	正确做法
直接加载源代码目录	必须加载bun run build生成的dist目录
忽略构建错误	构建过程中的警告和错误需要全部解决
清单文件中使用相对路径	所有资源路径应基于dist目录的相对路径
同时加载多个版本的扩展	确保只加载一个版本的Page Assist扩展

功能使用问题：AI响应缓慢或无结果

场景化问题描述

在浏览器侧边栏输入问题后，页面显示"正在思考..."状态超过30秒仍无响应，扩展控制台显示"请求超时"错误，而Ollama服务日志显示"context size exceeded"警告信息。

技术原理解析

AI模型响应缓慢通常涉及三个关键因素：模型性能、系统资源和上下文长度。本地运行的AI模型受限于计算机硬件配置，特别是CPU/GPU性能和内存容量。当对话历史过长导致上下文窗口（Context Window）溢出时，模型会拒绝处理或大幅降低响应速度。Page Assist默认使用的上下文管理策略可能未针对长对话进行优化。

阶梯式解决方案

初级解决步骤

🛠️ 优化模型选择

1. 打开Page Assist设置页面
2. 导航至"模型设置"选项卡
3. 选择更小尺寸的模型（如从llama3:70b切换到llama3:8b）
4. 点击"应用"保存设置
5. 重启扩展使更改生效

🛠️ 清理对话历史

# 清除存储的对话历史（Linux/macOS）
rm -rf ~/.config/page-assist/chat-history
# 重启扩展

进阶解决步骤

🔍 系统资源监控

# 监控CPU和内存使用情况
top -o %CPU
# 查看Ollama进程资源占用
ps aux | grep ollama

🛠️ 调整模型参数

1. 打开Ollama配置文件

nano ~/.ollama/config.json

2. 添加性能优化配置

{
  "num_ctx": 4096,
  "num_thread": 4,
  "num_gpu": 1
}

3. 重启Ollama服务

systemctl restart ollama

可视化预防方案

对话管理最佳实践

1. 每轮对话控制在5-8轮以内
2. 单条消息长度不超过500字符
3. 定期清理不需要的对话历史
4. 根据硬件配置选择合适模型：
   • 4GB内存：选择7B参数模型
   • 8GB内存：选择13B参数模型
   • 16GB以上内存：可尝试70B参数模型

[!TIP] 知识扩展：上下文窗口是指AI模型能够同时处理的文本总量，通常以tokens为单位（1token≈4个字符）。当超过模型设定的num_ctx值时，模型会截断或忽略部分输入。合理设置此参数需要在性能和上下文容量间找到平衡。

替代方案

1. 启用流式响应：在设置中开启"流式输出"选项，先看到部分结果再等待完整响应
2. 使用模型量化版本：选择Q4或Q5量化级别的模型，减少内存占用
3. 配置缓存策略：启用对话缓存功能，避免重复处理相同问题
4. 调整温度参数：降低temperature值（如0.5）减少模型思考时间

新手常见误区

错误操作	正确做法
始终使用最大模型	根据硬件配置选择合适规模的模型
一次性输入超长文本	将长文本拆分为多个短消息发送
同时运行多个AI应用	确保Page Assist使用时关闭其他AI工具
忽略系统资源限制	监控资源使用，避免内存不足导致崩溃

快捷键配置问题：自定义快捷键无效

场景化问题描述

在Chrome扩展快捷键设置页面自定义了Ctrl+Shift+L作为Page Assist的激活快捷键，但按下后无任何反应，同时在浏览器地址栏输入时出现意外的文本插入，怀疑快捷键冲突但无法确定冲突来源。

技术原理解析

Chrome扩展的快捷键属于全局范围，可能与浏览器内置功能、其他扩展或系统级快捷键冲突。Chrome的快捷键系统采用优先级机制，内置功能快捷键通常优先于扩展快捷键。此外，某些快捷键组合可能被操作系统保留，导致扩展无法捕获。Page Assist的快捷键处理逻辑需要正确注册到Chrome的commands API，并在background service worker中正确响应。

阶梯式解决方案

初级解决步骤

🛠️ 重新配置快捷键

1. 在Chrome地址栏输入chrome://extensions/shortcuts
2. 找到Page Assist扩展
3. 点击"激活侧边栏"对应的快捷键输入框
4. 按下新的快捷键组合（推荐Alt+P或Ctrl+Shift+Period）
5. 点击页面空白处保存设置

🛠️ 检查冲突快捷键

1. 打开Chrome设置页面chrome://settings/
2. 搜索"快捷键"
3. 查看"浏览器快捷键"部分，确认新设置的快捷键未被占用
4. 检查已安装的其他扩展是否使用相同快捷键

进阶解决步骤

🔍 诊断快捷键事件

1. 打开扩展的background service worker调试页面
2. 在控制台输入以下代码监听快捷键事件：

chrome.commands.onCommand.addListener((command) => {
  console.log('Command triggered:', command);
});

3. 按下设置的快捷键，观察控制台是否有事件输出

🛠️ 修改快捷键定义

1. 编辑项目中的manifest.json文件

{
  "commands": {
    "toggle-sidebar": {
      "suggested_key": {
        "default": "Ctrl+Shift+P",
        "mac": "Command+Shift+P"
      },
      "description": "Toggle Page Assist sidebar"
    }
  }
}

2. 重新构建并加载扩展

可视化预防方案

快捷键设置检查表

• [ ] 避免使用Chrome默认快捷键（如Ctrl+T新建标签页）
• [ ] 优先使用Ctrl+Shift+字母或Alt+Shift+字母组合
• [ ] 确保快捷键在不同操作系统下都能工作
• [ ] 设置后在多个网页中测试有效性
• [ ] 记录已设置的快捷键，避免遗忘

[!TIP] 知识扩展：Chrome扩展的快捷键系统不支持所有可能的键组合。某些特殊键如F1-F12通常保留给系统使用，而Ctrl+N、Ctrl+W等属于浏览器核心功能快捷键，扩展无法覆盖。最佳实践是选择包含三个修饰键的组合。

替代方案

1. 使用扩展图标：点击Chrome工具栏中的Page Assist图标激活侧边栏
2. 自定义上下文菜单：在扩展设置中启用右键菜单选项
3. 地址栏命令：在地址栏输入pa然后按Tab键快速激活
4. 手势控制：如果使用支持手势的浏览器，可以设置鼠标手势激活

新手常见误区

错误操作	正确做法
使用单个修饰键+字母	使用至少两个修饰键（如Ctrl+Shift+字母）
设置与系统冲突的快捷键	先在系统设置中检查快捷键占用情况
忽略操作系统差异	Windows使用Ctrl键，macOS使用Command键
设置后未测试不同页面	在多个网站和不同页面状态下测试快捷键

通过本文介绍的系统化排障方法，您应该能够解决Page Assist从安装到使用过程中的大部分常见问题。记住，本地AI工具的性能和稳定性很大程度上依赖于系统环境配置和硬件资源，合理调整设置和使用习惯将带来更好的体验。如果遇到本文未覆盖的问题，可以查阅项目的官方文档或提交issue获取帮助。