Page Assist 本地AI助手：常见技术问题全解

🔧 依赖安装失败：本地环境配置问题

问题现象

尝试启动Page Assist时，终端显示"Bun: command not found"或"Ollama service not running"错误，扩展无法正常加载。

根因解析

Page Assist依赖两个核心工具：Bun（JavaScript运行环境，类似Node.js）和Ollama（本地AI模型管理工具）。安装失败通常源于系统路径配置错误或安装步骤不完整。

解决方案

路径一：手动安装与配置

⚠️ 必看：安装前确保系统满足最低要求（Bun需glibc 2.28+，Ollama支持Windows 10+、macOS 11+、Linux内核5.4+）

1. 安装Bun

   # Linux/macOS系统
   curl -fsSL https://bun.sh/install | bash
   
   # Windows系统（PowerShell管理员模式）
   iwr https://bun.sh/install.ps1 -useb | iex
   

2. 验证Bun安装 🔍 检查：重启终端后执行以下命令

   bun --version  # 应显示类似 1.0.25 的版本号
   echo $PATH     # Linux/macOS需包含 ~/.bun/bin
   echo %PATH%    # Windows需包含 %USERPROFILE%\.bun\bin
   

3. 安装Ollama

   • Linux: curl https://ollama.ai/install.sh | sh
   • macOS: 从官网下载.dmg安装包
   • Windows: 从官网下载.exe安装程序

4. 启动Ollama服务

   # Linux/macOS
   ollama serve &  # &符号表示后台运行
   
   # Windows（PowerShell）
   Start-Service ollama
   

路径二：使用包管理器安装

💡 技巧：包管理器安装可自动处理依赖关系和环境变量

操作系统	包管理器命令
Ubuntu/Debian	sudo apt install bun ollama
Fedora/RHEL	sudo dnf install bun ollama
macOS (Homebrew)	brew install bun ollama
Windows (Chocolatey)	choco install bun ollama

预防策略

1. 安装前运行系统更新命令（sudo apt update/brew update等）
2. 创建专用项目目录，避免权限问题
3. 使用版本管理工具记录环境配置（如.env文件）

用户自测清单

• [ ] bun --version 能正常显示版本号
• [ ] ollama --version 能正常显示版本号
• [ ] ollama list 能显示已安装的模型列表
• [ ] 重启终端后命令依然可用
• [ ] 非root用户无需sudo也能运行命令

问题速查流程图

开始 -> 运行bun --version? -> 否:检查环境变量 -> 是:运行ollama --version? -> 否:重启Ollama服务 -> 是:问题解决

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

问题现象

在Chrome扩展页面加载解压后的扩展时，出现"清单文件无效"或"无法加载扩展"错误提示，扩展图标未显示。

根因解析

Chrome扩展加载失败主要有三类原因：未开启开发者模式、构建文件缺失或损坏、manifest.json配置错误。其中manifest.json是扩展的配置核心，包含权限声明和功能定义。

解决方案

路径一：标准构建与加载流程

⚠️ 必看：扩展开发模式仅用于测试，生产环境需通过Chrome商店安装

1. 构建项目文件

   # 克隆项目仓库
   git clone https://gitcode.com/GitHub_Trending/pa/page-assist
   
   # 进入项目目录
   cd page-assist
   
   # 安装依赖并构建
   bun install
   bun run build  # 生成build目录
   

2. 配置Chrome扩展

   1. 打开Chrome浏览器，访问chrome://extensions/
   2. 开启右上角"开发者模式"开关
   3. 点击"加载已解压的扩展程序"
   4. 选择项目目录下的build文件夹

路径二：故障排除方案

🔍 检查：如果标准流程失败，尝试以下步骤

1. 验证构建输出

   # 检查build目录是否存在
   ls -la build/
   
   # 确认manifest.json存在且格式正确
   cat build/manifest.json | jq .  # 需要安装jq工具
   

2. 修复常见manifest问题

   • 检查manifest_version是否为3（Chrome扩展最新标准）
   • 确保permissions字段包含必要权限（如"activeTab"、"storage"）
   • 验证content_scripts路径是否正确指向构建后的文件

预防策略

1. 使用版本控制跟踪manifest.json变更
2. 每次代码修改后重新执行bun run build
3. 定期清理浏览器缓存和扩展数据

用户自测清单

• [ ] build目录下存在manifest.json文件
• [ ] manifest.json中"name"和"version"字段正确
• [ ] 扩展加载后在扩展管理页面显示为"已启用"
• [ ] 浏览器右上角能看到Page Assist图标
• [ ] 点击图标能打开扩展菜单

问题速查流程图

开始 -> 开启开发者模式? -> 否:开启开关 -> 是:执行bun run build? -> 否:运行构建命令 -> 是:选择build目录? -> 否:检查目录路径 -> 是:问题解决

⌨️ 功能快捷键失效：系统冲突问题

问题现象

按下设置的快捷键后无任何反应，或触发了其他程序功能，Page Assist侧边栏无法调出。

根因解析

Chrome扩展快捷键采用全局注册机制，容易与系统快捷键、其他应用快捷键或输入法热键冲突。特别是默认快捷键可能与浏览器自带功能（如Ctrl+Shift+P调出命令菜单）冲突。

解决方案

路径一：修改扩展快捷键

💡 技巧：选择包含三个修饰键的组合（如Ctrl+Shift+Alt+字母）可大幅降低冲突概率

1. 打开Chrome快捷键设置页面：chrome://extensions/shortcuts
2. 在扩展列表中找到"Page Assist"
3. 点击需要修改的快捷键输入框
4. 按下新的快捷键组合（推荐使用Ctrl+Shift+Alt+Q）
5. 点击页面空白处保存设置

路径二：创建自定义命令

对于频繁使用的功能，可创建自定义命令替代快捷键：

1. 打开Chrome扩展选项页面
2. 进入"高级设置"
3. 找到"自定义命令"部分
4. 为常用功能（如"打开侧边栏"）设置命令别名
5. 通过扩展内搜索框输入命令触发功能

跨平台适配指南

操作步骤	Windows	macOS	Linux
打开快捷键设置	chrome://extensions/shortcuts	同上	同上
推荐快捷键组合	Ctrl+Shift+Alt+Q	Cmd+Shift+Alt+Q	Ctrl+Shift+Alt+Q
系统冲突检查	任务管理器→性能→热键	系统设置→键盘→快捷键	系统设置→键盘→快捷键
输入法冲突解决	切换至系统默认输入法	关闭搜狗/百度输入法快捷键	禁用ibus框架快捷键

预防策略

1. 设置快捷键时先在文本编辑器中测试是否会触发其他功能
2. 记录已使用的快捷键组合，避免重复设置
3. 对不同功能设置分级快捷键（常用功能用简单组合）

用户自测清单

• [ ] 新快捷键在无痕模式下也能使用
• [ ] 切换不同输入法时快捷键依然有效
• [ ] 快捷键在不同网站页面下保持一致
• [ ] 快捷键不会触发浏览器其他功能
• [ ] 扩展设置页面显示新快捷键已保存

问题速查流程图

开始 -> 打开快捷键设置页 -> 找到Page Assist扩展 -> 修改冲突快捷键 -> 测试新快捷键 -> 仍冲突? -> 是:选择更复杂组合 -> 否:问题解决

📊 常见错误代码速查表

错误代码	可能原因	解决方案	适用版本
ENOENT	构建目录不存在	执行bun run build	所有版本
EACCES	权限不足	使用sudo或修改目录权限	所有版本
404	模型文件未找到	运行ollama pull llama3	v1.2.0+
MANIFEST_ERROR	配置文件错误	检查manifest.json语法	v2.0.0+
CONNECTION_REFUSED	Ollama未启动	执行ollama serve	所有版本
500	模型加载失败	检查模型文件完整性	v1.5.0+

👥 社区支持资源导航

问题反馈渠道

• 项目Issue跟踪：通过项目仓库提交bug报告
• 社区讨论区：参与开发者论坛交流使用经验
• 常见问题库：查阅项目文档中的Troubleshooting章节

学习资源

• 官方文档：docs/index.md
• 视频教程：项目文档中的"入门指南"章节
• 示例配置：src/examples/目录下的配置样例

贡献指南

• 代码贡献：CONTRIBUTING.md
• 翻译支持：参与本地化工作，提交语言文件
• 测试反馈：帮助测试预发布版本，提供使用反馈