Page Assist 本地AI浏览器扩展：技术架构解析与部署优化指南

【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist

Page Assist 是一款开源的浏览器扩展，为开发者提供了在浏览器侧边栏中直接与本地运行的AI模型交互的能力。该项目基于TypeScript和React构建，支持Ollama、Chrome AI（Gemini Nano）以及任何OpenAI API兼容的本地AI服务。通过其模块化架构，Page Assist实现了跨浏览器兼容性、本地模型集成和实时网页内容分析等核心功能。

技术挑战：本地AI模型集成与跨浏览器兼容性

根本原因分析

Page Assist面临的主要技术挑战源于其双重架构设计：一方面需要处理浏览器扩展的安全沙箱限制，另一方面要兼容多种本地AI模型的API接口。在src/models/index.ts中，我们可以看到项目通过抽象层来统一处理不同AI提供商的接口差异。

// 模型工厂模式实现 import { ChatChromeAI } from "./ChatChromeAi" import { ChatOllama } from "./ChatOllama" import { ChatGoogleAI } from "./ChatGoogleAI" import { CustomChatOpenAI } from "./CustomChatOpenAI"

CORS（跨源资源共享）问题是本地AI集成中最常见的障碍。当浏览器扩展尝试访问本地运行的Ollama服务时，由于安全策略限制，会触发跨域请求错误。项目在wxt.config.ts中通过配置不同的权限集来解决这一问题：

// Chrome MV3权限配置 const chromeMV3Permissions = [ "storage", "sidePanel", "activeTab", "scripting", "declarativeNetRequest", // ...其他权限 ] // Firefox MV2权限配置（需要更宽松的策略） const firefoxMV2Permissions = [ "storage", "activeTab", "scripting", "unlimitedStorage", "http://*/*", "https://*/*", "file://*/*" ]

优化方案

方案一：动态URL重写机制

Page Assist通过src/libs/runtime.ts中的URL重写功能，自动处理本地服务的CORS问题。当检测到请求目标是本地地址时，系统会自动添加必要的请求头：

// 自动URL重写逻辑 export const urlRewriteRuntime = (url: string) => { if (url.includes('127.0.0.1') || url.includes('localhost')) { return { headers: { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS' } } } return null }

方案二：多模型适配器模式

项目采用适配器设计模式，在src/models/目录下为每个AI提供商实现了专门的适配器：

src/models/ ├── ChatChromeAi.ts # Chrome AI集成 ├── ChatOllama.ts # Ollama本地模型 ├── ChatGoogleAI.ts # Google AI服务 ├── CustomChatOpenAI.ts # 自定义OpenAI兼容端点 └── ChatTypes.ts # 统一类型定义

每个适配器都实现了统一的接口，确保不同的AI服务可以无缝切换。这种设计使得添加新的AI提供商变得简单，只需实现相应的适配器类即可。

技术挑战：构建系统与浏览器兼容性

根本原因分析

Page Assist使用WXT作为构建工具，这是一个专门为浏览器扩展开发的构建框架。在package.json中，我们可以看到项目针对不同浏览器的构建配置：

{ "scripts": { "dev": "cross-env TARGET=chrome wxt", "dev:firefox": "cross-env TARGET=firefox wxt -b firefox", "dev:edge": "cross-env TARGET=chrome wxt -b edge", "build:chrome": "cross-env TARGET=chrome wxt build", "build:firefox": "cross-env TARGET=firefox wxt build -b firefox" } }

不同浏览器扩展API的差异导致了构建配置的复杂性。Chrome使用Manifest V3，而Firefox仍然支持Manifest V2，这要求项目维护两套入口点配置：

entries/ # Chrome/Edge入口点 ├── background.ts ├── options/ └── sidepanel/ entries-firefox/ # Firefox入口点 ├── background.ts ├── options/ └── sidepanel/

优化方案

方案一：条件编译与构建优化

在wxt.config.ts中，项目通过环境变量动态调整配置：

export default defineConfig({ entrypointsDir: process.env.TARGET === "firefox" ? "entries-firefox" : "entries", manifest: { browser_specific_settings: process.env.TARGET === "firefox" ? { gecko: { id: "page-assist@nazeem" } } : undefined, permissions: process.env.TARGET === "firefox" ? firefoxMV2Permissions : chromeMV3Permissions } })

方案二：渐进式功能降级策略

对于不支持某些API的浏览器（如Opera和Arc），Page Assist实现了功能降级机制。侧边栏功能在这些浏览器中不可用，但Web UI功能仍然保持完整：

// 浏览器兼容性检查 const isSidebarSupported = () => { const unsupportedBrowsers = ['opera', 'arc'] const userAgent = navigator.userAgent.toLowerCase() return !unsupportedBrowsers.some(browser => userAgent.includes(browser)) }

技术挑战：本地数据存储与向量检索

根本原因分析

Page Assist需要处理大量的本地数据存储，包括聊天记录、知识库文档和向量嵌入。项目使用Dexie.js作为IndexedDB的封装，在src/db/dexie/目录下实现了复杂的数据模型：

src/db/dexie/ ├── schema.ts # 数据库模式定义 ├── chat.ts # 聊天记录管理 ├── knowledge.ts # 知识库存储 ├── vector.ts # 向量数据管理 └── migration.ts # 数据库迁移

向量检索功能通过LangChain集成实现，支持本地文档的语义搜索。在src/libs/PageAssistVectorStore.ts中，项目实现了自定义的向量存储方案。

优化方案

方案一：分层存储架构

项目采用分层存储策略，将不同类型的数据存储在不同的IndexedDB表中：

// 数据库模式定义示例 export const dbSchema = { chats: '++id, title, createdAt, updatedAt', messages: '++id, chatId, role, content, createdAt', knowledge: '++id, name, type, content, embeddings', vectors: '++id, knowledgeId, vector, metadata' }

方案二：增量向量化处理

对于大型文档，Page Assist实现了增量向量化处理机制。文档被分割成适当大小的块，每个块独立进行向量化，避免内存溢出：

// 文档分块处理逻辑 export const processDocumentChunks = async (document: Document) => { const chunkSize = 1000 // 字符数 const overlap = 200 // 重叠字符数 const chunks = splitText(document.content, chunkSize, overlap) const embeddings = await generateEmbeddings(chunks) return chunks.map((chunk, index) => ({ content: chunk, embedding: embeddings[index], metadata: { documentId: document.id, chunkIndex: index } })) }

部署优化工作流程

以下是Page Assist项目从开发到生产的完整部署流程：

关键配置检查点

1. AI模型连接验证：确保Ollama服务在http://127.0.0.1:11434运行，或相应调整自定义URL配置
2. 浏览器权限确认：检查扩展是否获得必要的API权限，特别是sidePanel和scripting权限
3. 存储配额管理：IndexedDB存储限制为浏览器配额，大型知识库需要分批次处理
4. 跨浏览器测试：在不同浏览器中验证核心功能，特别是侧边栏和快捷键功能

通过理解Page Assist的技术架构和优化方案，开发者可以更高效地部署和维护这一本地AI浏览器扩展，充分利用其模块化设计和跨平台兼容性优势。

【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist