Page Assist 扩展工具常见问题解决指南

🔍 环境配置 | 依赖安装失败

问题定位

当你在终端执行bun install命令时，屏幕突然出现大量红色错误信息，或者输入ollama run llama2后提示"command not found"，这意味着基础依赖未正确安装。

技术原理

Bun作为JavaScript运行时，类似餐厅的厨房设备；Ollama作为本地AI管理工具，如同模型的"仓库管理员"，二者缺一不可。

根因剖析

• 系统环境变量未包含工具路径（就像通讯录里没存对方电话）
• 安装过程中网络中断导致文件损坏
• 操作系统版本不兼容（如Windows 7不支持最新Ollama）

解决方案

方案A：官方脚本安装

• [ ] 【目标】安装Bun

  • 【操作】终端执行curl -fsSL https://bun.sh/install | bash
  • 【验证】输入bun --version显示版本号（如1.0.25）

• [ ] 【目标】安装Ollama

  • 【操作】访问Ollama官网下载对应系统安装包
  • 【验证】终端输入ollama --version显示版本信息

方案B：包管理器安装（替代方案）

• [ ] macOS用户可使用brew install bun ollama
• [ ] Ubuntu用户可使用apt install bun ollama

预防方案

新手自查清单

• [ ] 检查系统版本是否满足要求（Bun需macOS 10.15+/Linux kernel 5.6+）
• [ ] 安装后执行echo $PATH确认包含~/.bun/bin
• [ ] 验证ollama serve命令能正常启动服务
• [ ] 检查防火墙是否允许Ollama网络连接

⚠️ 反常识提示：安装Ollama时不要关闭终端，成功后会自动启动服务，关闭终端会终止服务进程

进阶技巧

- 使用`bun doctor`命令诊断Bun安装问题 - Ollama服务启动失败时，可尝试`ollama serve --debug`查看详细日志 - 日志文件路径：Linux/macOS在`~/.ollama/logs`，Windows在`C:\Users\用户名\.ollama\logs`

🔌 扩展加载 | Chrome提示"无法加载"

问题定位

当你在Chrome扩展页面点击"加载已解压的扩展程序"，选择项目文件夹后，右上角突然弹出红色警告，提示"无法加载扩展程序"，且没有详细原因说明。

技术原理

Chrome扩展需要通过manifest.json文件声明权限和配置，如同产品说明书，格式错误会导致无法识别。

根因剖析

• 未开启开发者模式（相当于没给Chrome"调试许可"）
• 选择了源代码目录而非编译后的build目录
• manifest.json文件存在语法错误或版本不兼容

解决方案

• [ ] 【目标】开启开发者模式

  • 【操作】访问chrome://extensions/，开启右上角"开发者模式"开关
  • 【验证】页面出现"加载已解压的扩展程序"按钮

• [ ] 【目标】生成编译文件

  • 【操作】在项目根目录执行bun run build
  • 【验证】项目目录下生成build文件夹，内含manifest.json

• [ ] 【目标】加载扩展

  • 【操作】点击"加载已解压的扩展程序"，选择项目的build目录
  • 【验证】扩展栏出现Page Assist图标，无错误提示

预防方案

新手自查清单

• [ ] 确认build目录存在且包含manifest.json
• [ ] 检查manifest.json是否有JSON语法错误（可使用在线JSON验证工具）
• [ ] 每次代码修改后重新执行bun run build
• [ ] 确保扩展ID未被其他扩展占用

⚠️ 反常识提示：manifest.json中的"version"字段必须符合语义化版本规范（如"1.0.0"而非"1.0"）

进阶技巧

- 使用`bun run dev`启动开发模式，自动监测代码变化并重新编译 - Chrome扩展错误可在`chrome://extensions/`页面点击"错误"查看详情 - manifest.json v3版本要求更严格，注意权限声明格式

⌨️ 交互冲突 | 快捷键无响应

问题定位

当你在浏览网页时按下Alt+P想调出Page Assist侧边栏，结果要么毫无反应，要么打开了浏览器的打印界面，这表明快捷键发生冲突。

技术原理

Chrome扩展快捷键采用全局注册机制，如同抢占地盘，后注册的快捷键会覆盖先注册的。

根因剖析

• 快捷键组合与系统或其他扩展冲突
• 快捷键未正确生效（常见于Linux系统）
• Chrome快捷键设置被重置

解决方案

• [ ] 【目标】访问快捷键设置

  • 【操作】在Chrome地址栏输入chrome://extensions/shortcuts
  • 【验证】进入扩展快捷键管理页面

• [ ] 【目标】修改Page Assist快捷键

  • 【操作】找到Page Assist扩展，点击快捷键输入框，按下Ctrl+Shift+P
  • 【验证】输入框显示新的快捷键组合，无"冲突"提示

• [ ] 【目标】测试新快捷键

  • 【操作】打开任意网页，按下新设置的快捷键
  • 【验证】Page Assist侧边栏成功弹出

预防方案

新手自查清单

• [ ] 选择Ctrl+Shift+字母组合（冲突概率较低）
• [ ] 避免使用单个功能键（如F1-F12）
• [ ] 测试快捷键时关闭其他可能冲突的软件
• [ ] 定期检查快捷键设置是否被系统更新重置

⚠️ 反常识提示：Windows系统中Ctrl+Shift+P可能与Chrome开发者工具冲突，可改用Ctrl+Shift+K

进阶技巧

- 使用`chrome://extensions/shortcuts`页面的搜索功能快速定位扩展 - 复杂快捷键可使用AutoHotkey（Windows）或Automator（macOS）自定义 - 部分系统需要重启Chrome才能使快捷键设置生效

问题速解流程图

开始解决问题
    │
    ├─→ 安装问题 ───→ 检查Bun/Ollama版本 ───→ 重新安装
    │       │           │
    │       └─→ 检查环境变量 ───→ 添加路径到PATH
    │
    ├─→ 扩展加载问题 ─→ 开启开发者模式 ───→ 加载build目录
    │               │
    │               └─→ 检查manifest.json ─→ 修复语法错误
    │
    └─→ 快捷键问题 ─→ 访问shortcuts页面 ─→ 修改冲突快捷键
                    │
                    └─→ 测试新快捷键 ─→ 验证功能
                            
问题解决

社区支持渠道

• 项目Issue跟踪：提交详细问题描述和复现步骤
• 开发者讨论区：分享使用经验和解决方案
• 常见问题库：查阅其他用户遇到的类似问题

祝您使用Page Assist愉快！这款工具能让您在浏览网页时随时与本地AI模型互动，提升信息处理效率。