最近，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場景。