最近，Hugging Face團隊發佈了一個基於Transformers.js和Gemma 4 E2B的Chrome擴展演示，旨在幫助用户瀏覽網頁。在構建過程中，他們遇到了Manifest V3運行時、模型加載和消息傳遞方面的實際挑戰，並分享了寶貴的經驗。
目標讀者與構建內容 本指南面向希望在Chrome擴展中運行本地AI功能的開發者，尤其是面臨Manifest V3約束的場景。最終架構包括一個後台服務工作線程（託管模型）、一個側邊欄聊天UI，以及一個用於頁面操作的內容腳本。
MV3架構設計
擴展的manifest.json定義了三個入口點：後台服務工作線程（background.js）、側邊欄（sidebar.html）和內容腳本（content.js）。後台作為控制平面，負責代理生命週期、模型初始化和工具執行；側邊欄處理用户交互；內容腳本負責DOM提取和頁面高亮。這種分離避免了重複加載模型，保持了UI響應性，並遵守Chrome的安全邊界。
所有消息通過類型化的枚舉進行通信，後台是唯一的協調器。典型的請求流程是：側邊欄發送AGENT_GENERATE_TEXT，後台追加消息並運行推理，然後通過MESSAGES_UPDATE更新側邊欄。
Transformers.js集成
擴展使用了兩個模型角色：gemma-4-E2B-it-ONNX用於文本生成（q4f16量化），all-MiniLM-L6-v2-ONNX用於生成嵌入向量（fp32）。所有推理在後台運行，避免了多個標籤頁重複加載模型。緩存位於擴展源下，所有會話共享。模型生命週期包括檢查/初始化（帶進度反饋），完成後複用實例。權限方面請求了sidePanel、storage、scripting、tabs和主機權限，以支持頁面操作。
代理與工具執行循環
工具調用基於變換器格式，模型輸出特殊標記指示工具調用。項目通過歸一化層和解析器將模型輸出轉換為確定性執行。Agent.runAgent循環將內部模型消息與用户可見的聊天消息分離：用户輸入添加到chatMessages，流式生成助手回覆，解析工具調用並執行，結果反饋回模型，重複直至無工具調用。
數據持久化
狀態按生命週期分割：會話狀態保存在後台內存中，工具偏好使用chrome.storage.local，語義歷史向量使用IndexedDB，提取的頁面內容緩存在後台。
構建與打包 使用Vite的多入口構建，確保每個運行時對應一個工件，並放在manifest期望的位置。
總結 清晰的關注點分離是項目的核心：後台擁有狀態和模型執行，UI界面保持輕薄，內容腳本處理頁面訪問。相同的架構可以擴展到彈出式、側邊欄甚至混合UI場景。