Page Assist 新手问题排查指南本地 AI 浏览器扩展 3 大高频故障快速修复【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assistPage Assist 是一款开源浏览器扩展把本地 AI 模型Ollama、LM Studio 等装进每个网页的侧边栏和独立 Web UI让你在浏览时随时与模型对话、直接提问当前页面内容。本文面向刚接触浏览器扩展 本地模型的新手集中解决最容易卡住人的几类故障全部对照项目真实行为编写。问题地图环境自检动手编译前必查的 6 项清单高频故障一bun install报command not found依赖装不上高频故障二Chrome 提示无法加载扩展程序高频故障三Ollama 返回 403侧边栏发不出消息高频故障四快捷键CtrlShiftY失灵环境自检编译 Page Assist 前必查的 6 项清单先花两分钟过一遍这份清单后面四个章节里八成问题都能提前避开。✅源码已获取执行下面的命令后目录里应能看到README.md和docs/文件夹。git clone https://gitcode.com/GitHub_Trending/pa/page-assist✅构建工具可用运行bun --version能输出版本号。没有 Bun 也没关系项目 README.md 明确允许用npm替代。✅本地模型服务正常ollama list至少列出一个模型服务默认监听11434端口。✅端口无其他进程抢占lsof -i :11434Windows 可用netstat -ano的输出应指向 ollama 进程。✅浏览器在支持名单内对照 docs/browser-support.mdChrome、Brave、Firefox、Edge 等完整支持侧边栏Opera、Arc 只能使用 Web UI。✅磁盘空间充足模型文件较大建议至少预留 10GB 可用空间。高频故障一bun install 报 command not found一键修复安装屏幕上的症状在项目目录敲下bun install终端立刻回一句bun: command not found或者安装命令看似跑完实际没有生成依赖目录后续编译全线报错。为什么会卡在这里终端找不到 Bun多半是它没装或者装了但可执行路径~/.bun/bin不在PATH环境变量里。Bun 装完后旧终端窗口不会自动刷新PATH这是新手最容易忽略的细节。修复步骤先运行bun --version判断情况输出版本号说明只是 PATH 问题关掉终端重开一个窗口即可没有任何输出则说明根本没装。未安装 Bun 时按 README.md 中 Prerequisites 给出的官方安装方式装上然后重开终端再跑安装命令。嫌麻烦可以直接换 npm项目官方支持bun install # Bun 不可用时改用 npm install安装完依赖后顺手把版本号再核对一遍确认构建链路通畅bun --version与ollama --version都应有输出。怎么算修好了终端依次输出 Bun 版本号和 Ollama 版本号node_modules目录已生成再没有红色报错。高频故障二Chrome 提示无法加载扩展程序最快排查方法你会看到什么在chrome://extensions页面点加载已解压的扩展程序后页面顶部弹出红色报错内容多为清单文件无效或无法找到 manifest.json。背后的原因Chrome 只认编译产物。两个高频诱因一是选错了目录把项目根目录或源码目录当成了扩展目录二是改过代码但没重新编译build目录里还是旧的、甚至根本不完整的文件。逐步修复重新编译生成最新的扩展产物bun run build ls build确认build目录里存在manifest.json等核心文件。这一步的意义在于加载目录之前先证明文件真的在。回到chrome://extensions确认右上角开发者模式已开启点加载已解压的扩展程序只选build目录不要选项目根目录。Firefox 用户路径不同about:addons→ 扩展 → 管理扩展 → 加载临时附加组件直接选build目录下的manifest.json文件注意是文件不是目录。成功标准浏览器工具栏出现 Page Assist 图标扩展页面里没有红色错误条侧边栏能正常打开。高频故障三Ollama 返回 403侧边栏无法回复报错长什么样发消息后侧边栏提示Direct connection error直连失败或回复里带着403错误。更完整的报错截图说明见 docs/connection-issue.md。根因浏览器跨域拦截浏览器扩展和本地 Ollama 属于不同来源Origin默认会被 CORS跨域资源共享策略拦截。Page Assist 内置了请求头改写来绕过它但该改写只对http://127.0.0.1:*和http://localhost:*生效Ollama 跑在别的地址或端口时就会失手。两条修复路线路线 A在 Page Assist 里改推荐先试点工具栏扩展图标 → 设置 → Ollama Settings 选项卡。展开 Advanced Ollama URL Configuration。打开 Enable or Disable Custom Origin URLOllama 用默认端口就保持原值换过端口才改 URL。点 Save 保存让扩展按正确来源重写请求头。路线 B在系统层面放开 Ollama 的来源限制然后重启 Ollama 服务export OLLAMA_ORIGINS*macOS 用launchctl setenv OLLAMA_ORIGINS *Windows 则在系统环境变量中新建OLLAMA_ORIGINS值填*。 注意副作用CORS 改写本身可能弄坏个别网站如 Intel 驱动助手页。若你恰好遇到这种情况按 docs/extensions-causing-issue-other-websites.md 关闭Automatic Ollama CORS Fix再配合路线 B 解决 403。确认解决重新发送一条消息模型逐字给出回复不再出现 403 或连接失败提示。高频故障四快捷键 CtrlShiftY 失灵重新绑定教程按了没反应时的表现在任意网页按下CtrlShiftY毫无反应或者触发的是系统截图、输入法切换。右键菜单里的 Open Page Assist Sidebar 还能用说明扩展本身是好的问题出在按键上。原因在哪快捷键注册是全局的系统、输入法切换键或其他扩展都可能先把它抢走浏览器快捷键页面里也可能残留旧配置。默认键位说明见 docs/shortcuts.md。重新绑定Chromium 系浏览器打开chrome://extensions/shortcutsFirefox 走about:addons→ 设置 → 管理扩展快捷键。这个页面集中展示每个扩展占用的按键冲突一眼可见。找到 Page Assist点 Open Sidebar 对应的输入框按下新组合键。优先选CtrlShift字母一类与系统常用键撞车概率最低。到任意网页按新按键实测一次。顺手测一下CtrlShiftL打开 Web UI两个键位都通才算完整。 修键位前先确认扩展状态正常右键网页选 Open Page Assist Sidebar能弹出侧边栏再动手改快捷键可以排除扩展本身挂了这个干扰项。验证通过新按键一按侧边栏从页面边缘滑出旧按键不再误触发其他功能。辅助工具箱排查 Page Assist 问题常用的小工具bun doctorBun 内置诊断自动检查安装完整性与 PATH 配置故障一的起手式。lsof -i :11434查看 Ollama 默认端口被谁占用配合kill结束冲突进程。ollama list/ollama ps前者确认模型已下载后者确认模型已加载进内存。chrome://extensions/shortcuts浏览器自带的快捷键管理页可视化查看按键占用无需第三方工具。VS Code直接打开build/manifest.jsonJSON 语法错误如多余的逗号会显示红色波浪线。求助渠道Issue 模板与社区支持提交 Issue 前先搜一遍项目仓库的 Issue 区经常已有人踩过同样的坑搜索关键词建议带上浏览器名和报错原文如 403 Ollama。日志里如含 API 密钥请先打码再贴。建议的 Issue 格式[标题] 浏览器 一句话症状例如Edge 侧边栏发送消息返回 403 [环境] - 系统与版本 - 浏览器与版本 - Page Assist 来源商店安装 / 源码编译附版本号 - 本地模型服务Ollama / LM Studio / 其他地址与端口 [出现时机] 首次安装即有 / 某次更新后出现 / 一直存在 [已尝试的修复] 对照本指南做到第几章第几步 [截图或报错原文]社区支持方式官方文档仓库内 docs/ 目录按功能分章如 docs/providers/ollama.md 讲 Ollama 多实例配置docs/sidebar/ 讲侧边栏的三种打开方式。Issue 区仓库 Issues 提交 bug 与功能请求维护者会响应并标记状态。Discord 社群README.md 顶部提供了入口适合实时交流。Discussions 讨论区提问与经验交流回复通常比 Issue 更快。【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
