Page Assist：本地AI驱动的浏览器增强工具全攻略

🌟 核心价值：重新定义网页交互体验

Page Assist 作为开源浏览器扩展，将本地AI模型的强大能力直接融入你的浏览体验。这款工具突破传统交互边界，通过侧边栏与Web UI双界面设计，让你在任何网页都能即时调用Ollama、Chrome AI等本地模型，实现无需数据上传的隐私安全型AI交互。

💡 核心优势解析：

• 本地优先架构：所有对话与数据处理均在本地完成，杜绝隐私泄露风险
• 多模型兼容：无缝对接Ollama、LM Studio等主流本地AI服务，支持OpenAI API兼容端点
• 全场景适配：侧边栏交互+独立Web UI双模式，满足快速查询与深度对话不同需求
• 零成本启动：完全开源免费，无需订阅费用即可享用AI增强浏览体验

🚀 快速上手：5分钟启动本地AI助手

环境准备清单

在开始前，请确保你的系统已安装以下工具：

• Bun：JavaScript运行时环境（替代Node.js）
• Ollama：本地AI模型管理工具
• Git：版本控制工具（用于克隆代码库）

安装部署流程

🔍 基础安装三步法：

1. 获取源代码

git clone https://gitcode.com/GitHub_Trending/pa/page-assist
cd page-assist

2. 安装依赖包

bun install
# 若Bun安装失败，可替换为npm：npm install

3. 构建扩展程序

bun run build
# 构建产物将生成在dist目录下

💡 浏览器加载指南：

• Chrome/Edge：访问chrome://extensions → 启用开发者模式 → 加载已解压的扩展程序 → 选择build目录
• Firefox：访问about:addons → 进入扩展管理 → 临时加载附加组件 → 选择build/manifest.json文件

新手必知：首次使用配置

1. 模型准备：通过Ollama安装至少一个模型（推荐从llama2或mistral开始）

   ollama pull llama2
   

2. 基本快捷键：

   • Ctrl+Shift+Y：打开侧边栏（任意网页可用）
   • Ctrl+Shift+L：启动独立Web UI
   • Shift+Esc：快速聚焦输入框

3. 隐私设置：首次启动后建议进入设置页面，确认"本地存储优先"选项已启用，确保数据不会上传云端

🛠️ 深度解析：核心配置与工作原理

关键配置文件详解

package.json：项目命脉

功能定位：项目元数据与构建脚本核心

核心作用：

• 定义依赖项版本与开发工具链
• 提供标准化构建命令入口
• 声明浏览器兼容性信息

参数调整示例：

{
  "scripts": {
    "dev": "wxt dev --target=chrome",  // 开发模式仅构建Chrome版本
    "build:firefox": "wxt build --target=firefox"  // 单独构建Firefox版本
  }
}

💡 实用提示：若需针对特定浏览器优化，可修改scripts部分添加目标平台参数

wxt.config.ts：扩展框架配置

功能定位：WXT框架的核心配置文件

核心作用：

• 指定源代码目录与输出路径
• 配置浏览器特定构建选项
• 管理扩展权限与资源访问策略

参数调整示例：

export default defineConfig({
  srcDir: 'src',
  outDir: 'dist',
  manifest: {
    permissions: ['activeTab', 'storage', 'scripting']  // 精简必要权限
  }
})

🔍 重点关注：manifest配置段直接影响扩展功能权限，修改时需谨慎测试兼容性

工作流程解析

Page Assist采用模块化架构设计，核心工作流程包括：

1. 用户交互层：通过src/entries/目录下的入口文件响应浏览器事件
2. 业务逻辑层：在src/chain/中实现AI对话流程控制，如chat-with-website.ts处理网页内容分析
3. 数据处理层：src/loader/目录下的各类加载器负责解析不同格式文件（PDF、CSV等）
4. 存储层：使用src/db/模块管理本地对话历史与知识库数据

💡 架构优势：这种分层设计使功能扩展变得简单，例如添加新的文件类型支持，只需在loader目录新增对应解析器

❓ 常见问题与解决方案

连接问题排查

Ollama连接失败（403错误）

症状：发送消息时出现CORS相关错误提示

解决方案：

1. 环境变量法（推荐）：

   # Linux/MacOS终端执行
   export OLLAMA_ORIGINS="*"
   # 之后重启Ollama服务
   

2. 配置修改法：

   • 打开扩展设置 → Ollama配置 → 高级选项
   • 启用"自定义源URL" → 保持默认值http://127.0.0.1:11434
   • 保存设置后等待30秒使配置生效

扩展加载失败

可能原因：

• 浏览器版本过低（需Chrome 100+或Firefox 102+）
• 构建过程出错（检查终端输出的错误信息）
• 开发者模式未启用（部分浏览器默认禁用）

快速修复：尝试删除node_modules目录后重新执行bun install && bun run build

性能优化建议

1. 模型选择：低配设备建议使用7B参数模型（如mistral:7b）
2. 内存管理：在src/utils/memory-embeddings.ts中调整缓存大小
3. 后台限制：在浏览器扩展管理中禁用"允许在隐身模式下运行"可减少资源占用

📚 进阶资源

官方文档库

• 完整功能说明：docs/index.md
• 快捷键大全：docs/shortcuts.md
• 模型配置指南：docs/providers/ollama.md

开发资源

• 贡献指南：CONTRIBUTING.md
• API接口文档：src/models/ChatTypes.ts
• 组件库示例：src/components/Common/

💡 学习路径建议：新手可从修改提示词模板开始（位于src/data/prompt-templates.ts），逐步尝试添加自定义模型支持

📝 许可证信息

本项目采用MIT许可证开源，详细条款参见LICENCE文件。你可以自由使用、修改和分发本软件，但需保留原作者版权声明。

---

通过Page Assist，你不仅获得了一个浏览器扩展，更拥有了一个可定制的本地AI交互平台。无论是学术研究、内容创作还是日常浏览，这款工具都能成为你高效工作的得力助手。现在就启动本地AI，体验新一代智能浏览方式吧！