Page Assist 本地AI浏览器扩展问题速解手册

Page Assist 是一款能让你在 Chrome 浏览器中直接与本地 AI 模型交互的扩展工具，通过侧边栏即可随时调用 AI 能力辅助网页浏览。本文针对新手用户在环境配置、功能使用和操作过程中可能遇到的典型问题，提供系统化的排查与解决方案，帮助你快速掌握工具使用技巧。

环境配置问题：本地AI模型连接失败排查

问题现象

安装 Page Assist 后，尝试启动本地 AI 对话时提示"模型连接失败"，或侧边栏显示"无法访问 Ollama 服务"错误。

核心原因

本地 AI 服务（Ollama）未正确安装或启动，或应用权限配置不当导致无法建立连接。Ollama 是管理本地 AI 模型的服务程序——类似于 AI 模型的"管家"，负责加载和运行模型文件。

解决方案

1. 检查 Ollama 服务状态

   • 操作指令：在终端输入 ollama serve
   • 预期结果：显示"starting server on http://127.0.0.1:11434"表示服务正常启动

2. 验证模型安装情况

   • 操作指令：运行 ollama list
   • 预期结果：显示已安装的模型列表，如"llama3:latest"

3. 测试 API 连接性

   • 操作指令：执行 curl http://localhost:11434/api/tags
   • 预期结果：返回包含已安装模型信息的 JSON 响应

4. 配置 Page Assist 连接设置

   • 操作路径：扩展设置 → 模型 → Ollama 配置
   • 验证内容：确保"服务地址"设置为 http://localhost:11434

验证步骤

1. 重启 Chrome 浏览器
2. 打开 Page Assist 侧边栏
3. 发送测试消息"你好"
4. 预期结果：收到 AI 回复，无连接错误提示

预防方案

• 安装 Ollama 后将其设置为开机自启动服务
• 定期执行 ollama pull <model-name> 更新模型文件
• 避免同时运行占用大量端口的其他本地服务

问题速查表

常见错误代码	对应原因	修复命令
ECONNREFUSED	Ollama 服务未启动	ollama serve
404 Not Found	模型未安装	ollama pull llama3
Connection timeout	端口被占用	lsof -i :11434 查找占用进程

功能异常问题：浏览器扩展加载失败处理

问题现象

在 Chrome 扩展页面加载 Page Assist 时，出现"无法加载扩展程序"错误，或扩展图标显示为灰色不可用状态。

核心原因

扩展未正确编译生成构建文件，或 Chrome 浏览器安全设置阻止了未签名扩展的加载。manifest.json 文件——扩展的"身份证"，包含了扩展的基本信息和权限声明，如果格式错误会直接导致加载失败。

解决方案

1. 编译项目生成构建文件

   • 操作指令：在项目根目录执行 bun run build
   • 预期结果：生成 build 目录，包含 manifest.json 文件

2. 启用 Chrome 开发者模式

   • 操作路径：Chrome 地址栏输入 chrome://extensions/
   • 操作指令：开启右上角"开发者模式"开关
   • 预期结果：页面显示"加载已解压的扩展程序"按钮

3. 正确加载扩展目录

   • 操作指令：点击"加载已解压的扩展程序"，选择项目的 build 目录
   • 预期结果：扩展列表中出现 Page Assist，图标为彩色可用状态

4. 检查 manifest 文件格式

   • 操作指令：使用 VS Code 打开 build/manifest.json
   • 验证内容：确保 JSON 格式正确，无语法错误（无红色波浪线提示）

验证步骤

1. 在 Chrome 工具栏找到 Page Assist 图标
2. 点击图标查看是否显示功能菜单
3. 打开任意网页，尝试使用快捷键调出侧边栏
4. 预期结果：扩展功能正常，无错误提示

预防方案

• 修改代码后执行 bun run build 重新编译
• 定期清理 Chrome 扩展缓存（chrome://settings/clearBrowserData）
• 保持项目依赖更新：bun update

问题速查表

常见错误代码	对应原因	修复命令
清单文件无效	manifest.json 语法错误	修复 JSON 格式错误
缺少必要权限	扩展权限配置不足	检查 manifest 中的"permissions"字段
版本不兼容	Chrome 版本过低	升级 Chrome 到 100+ 版本

操作冲突问题：快捷键无响应解决方案

问题现象

按下设置的快捷键后 Page Assist 侧边栏未弹出，或触发了其他应用程序的功能，如截图工具或系统快捷操作。

核心原因

快捷键组合与系统或其他应用程序存在冲突，或 Chrome 扩展快捷键未正确生效。Chrome 扩展的快捷键是全局性质的——在浏览器任何标签页中都能触发，因此容易与系统级快捷键冲突。

解决方案

1. 访问 Chrome 快捷键设置

   • 操作路径：地址栏输入 chrome://extensions/shortcuts
   • 预期结果：显示所有扩展的快捷键配置页面

2. 修改 Page Assist 快捷键

   • 操作步骤：
     1. 找到 Page Assist 扩展
     2. 点击"激活扩展"对应的快捷键输入框
     3. 按下新的快捷键组合（推荐 Ctrl+Shift+P）
     4. 确保无"与其他扩展冲突"提示

3. 验证快捷键有效性

   • 操作指令：在任意网页按下新设置的快捷键
   • 预期结果：Page Assist 侧边栏从右侧滑出

4. 排查系统快捷键冲突

   • 操作步骤：
     1. 打开系统设置 → 键盘 → 快捷键
     2. 搜索新设置的快捷键组合
     3. 修改或禁用冲突的系统快捷键

验证步骤

1. 打开多个不同类型的网页（文档、视频、新闻等）
2. 在每个页面测试快捷键功能
3. 检查是否在所有页面都能正常调出侧边栏
4. 预期结果：100% 触发成功率，无冲突现象

预防方案

• 选择 Ctrl+Shift+字母 组合作为扩展快捷键
• 避免使用系统常用快捷键（如 Ctrl+S、Ctrl+P）
• 记录已设置的快捷键在便签工具中

问题速查表

常见错误代码	对应原因	修复命令
无响应	快捷键未设置	在 chrome://extensions/shortcuts 配置
触发其他功能	快捷键冲突	更换为 Ctrl+Shift+[字母] 组合
间歇性失效	焦点问题	点击页面空白处后重试快捷键

问题自查流程图

decisionDiagram
    start --> 问题类型{选择问题类型}
    问题类型 -->|环境配置| 环境问题{模型是否启动?}
    环境问题 -->|是| 环境问题2{模型列表是否显示?}
    环境问题 -->|否| 解决方案1[运行 ollama serve]
    环境问题2 -->|是| 环境问题3[测试 API 连接]
    环境问题2 -->|否| 解决方案2[运行 ollama pull 模型名]
    环境问题3 -->|成功| 配置问题[检查扩展设置]
    环境问题3 -->|失败| 解决方案3[检查防火墙设置]
    
    问题类型 -->|功能异常| 扩展问题{是否开启开发者模式?}
    扩展问题 -->|否| 解决方案4[开启开发者模式]
    扩展问题 -->|是| 扩展问题2{build 目录是否存在?}
    扩展问题2 -->|否| 解决方案5[运行 bun run build]
    扩展问题2 -->|是| 扩展问题3[检查 manifest 格式]
    
    问题类型 -->|操作冲突| 快捷键问题{是否显示冲突提示?}
    快捷键问题 -->|是| 解决方案6[更换快捷键组合]
    快捷键问题 -->|否| 快捷键问题2[测试其他网页]
    快捷键问题2 -->|部分有效| 解决方案7[检查页面焦点]
    快捷键问题2 -->|完全无效| 解决方案8[重新配置快捷键]
    
    解决方案1 --> 验证步骤
    解决方案2 --> 验证步骤
    解决方案3 --> 验证步骤
    配置问题 --> 验证步骤
    解决方案4 --> 验证步骤
    解决方案5 --> 验证步骤
    扩展问题3 --> 验证步骤
    解决方案6 --> 验证步骤
    解决方案7 --> 验证步骤
    解决方案8 --> 验证步骤
    
    验证步骤 -->|问题解决| 结束[完成修复]
    验证步骤 -->|仍有问题| 文档[查阅官方文档]
    文档 --> 结束

通过以上系统化的问题排查流程，大多数 Page Assist 使用问题都能得到有效解决。如果遇到复杂问题，建议参考项目文档中的详细故障排除指南，或在社区讨论区寻求帮助。