Chrome 扩展核心

本文引用的源码文件

本文引用的文件

引言

本文件面向 Chrome 扩展（Manifest V3）与本地 Agent 双进程架构，聚焦以下目标：

Service Worker 生命周期、保活机制、事件监听与消息路由。
Side Panel 界面架构、聊天管理、工具面板集成与用户交互流程。
Content Scripts 注入机制、页面访问权限、消息路由表与异步工具处理。
Offscreen Document 的作用与剪贴板兼容层实现。
MV3 最佳实践、跨上下文通信示例、常见陷阱与解决方案。

本项目为双进程架构：Chrome 扩展端（Manifest V3，src/ 目录，版本 2.3.1）+ 独立本地代理端 Agent（Node.js，agent/src/server.js 入口，npm 包名 ai-helper-agent，版本 2.3.1）。两端版本号始终保持同步；扩展端通过本地 HTTP/WebSocket 调用 Agent 的文件读写、命令执行、长期记忆与 RAG 能力。Agent 源码修改后必须重启进程新接口才生效。

项目结构

扩展采用 MV3 Service Worker 作为 background，Side Panel 作为主 UI，Content Scripts 注入到网页，Offscreen Document 提供剪贴板兼容能力。关键入口如下：

manifest.json：声明 MV3、Service Worker、Side Panel、Content Scripts、权限与快捷键。
src/background/index.js：Service Worker 入口，负责保活、侧边栏控制、消息路由、ReAct 循环调度、通知与自动恢复。
src/side_panel/index.js：Side Panel 入口，聚合聊天、工具面板、工作区、书签、技能选择等模块。
src/side_panel/chat-manager.js：聊天会话、流式输出、执行日志、任务恢复、上下文压缩等核心逻辑。
src/content/index.js：Content Script 入口，统一消息路由表与异步工具处理。
src/offscreen/offscreen.html + offscreen.js：Offscreen 文档与剪贴板兼容层。
src/background/tool-executor.js：工具定义、执行、MCP/RAG/Skill 加载与执行编排。
src/background/local-agent-client.js：与本地 Agent 的 HTTP/WebSocket 客户端封装。
src/shared/logger.js 与 src/shared/i18n.js：通用日志与国际化基础设施。

graph TB
A["manifest.json<br/>MV3 清单"] --> B["background/index.js<br/>Service Worker 入口"]
A --> C["side_panel/index.js<br/>侧边栏入口"]
A --> D["content/index.js<br/>内容脚本入口"]
A --> E["offscreen/offscreen.html<br/>Offscreen 文档"]
B --> F["tool-executor.js<br/>工具执行与 MCP/RAG"]
B --> G["local-agent-client.js<br/>本地 Agent 客户端"]
C --> H["chat-manager.js<br/>聊天与会话管理"]
I["shared/logger.js<br/>日志"] -.-> B
I -.-> C
I -.-> D
J["shared/i18n.js<br/>国际化"] -.-> B
J -.-> C
J -.-> D

图表来源

章节来源

manifest.json#L1-L76

核心组件

Service Worker（background/index.js）
- 保活：通过 keepalive port 与 Side Panel 长连接，防止 SW 空闲被终止。
- 侧边栏控制：open/close/toggle，支持全局模式与 tab-specific 模式，窗口分组整理。
- 消息路由：集中分发 CALL_API、RESUME_REACT、GET_MCP_TOOLS、RAG_*、截图等消息。
- ReAct 循环：reactLoop/callApiNonStream，工具预筛选、子任务计划、流式输出。
- 自动恢复：基于 checkpoint 的闹钟唤醒与续跑，耗尽时通知人工介入。
- 通知与可见性：按发起实例身份判定面板是否可见，避免误弹或漏弹。
Side Panel（side_panel/index.js + chat-manager.js）
- 配置与主题：i18n、主题 Token、模型选择、温度/TopP 设置。
- 聊天管理：会话持久化、流式渲染、执行日志、反思评估、导出导入。
- 工具面板：内置工具、MCP、Skill、RAG 工具展示与开关。
- 工作区与书签：工作区文件、书签管理、搜索、跳转。
- 交互流程：发送消息、划词问答、截图、引用知识库、技能注入。
Content Scripts（content/index.js）
- 消息路由表：HANDLERS Map，O(1) 查找，分类页面读取、交互、提取、媒体、异步工具。
- 异步处理：ASYNC_HANDLERS Set 标记需保持通道开放的异步工具。
- 顶层帧限制：TOP_FRAME_ONLY_TYPES 避免 iframe 响应覆盖。
- 区域截图：在页面上创建遮罩层与选择框，返回矩形坐标。
Offscreen Document（offscreen.html + offscreen.js）
- 剪贴板兼容：优先 navigator.clipboard，失败回退 execCommand copy/paste。
- i18n 文案：复制成功/失败、粘贴失败的提示。
工具执行与 Agent 客户端（tool-executor.js + local-agent-client.js）
- 工具定义与执行：内置工具、MCP、RAG、Skill、快照编排、截图下载。
- Agent 客户端：配对、健康检查、HTTP/WebSocket 请求、可达性缓存、多代理切换。
共享基础设施（logger.js + i18n.js）
- 日志：DEBUG/INFO/WARN/ERROR 分级输出。
- 国际化：t(key, params)、语言检测、订阅刷新、注册翻译字典。

章节来源

架构总览

扩展端与 Agent 端的通信契约是架构核心：扩展端经本地 HTTP/WebSocket 端点调用 Agent 的文件读写、命令执行、长期记忆与 RAG 能力。Service Worker 作为中央调度器，协调 Side Panel、Content Scripts、Offscreen Document 与 Agent 客户端。

sequenceDiagram
participant SP as "Side Panel"
participant BG as "Background (Service Worker)"
participant CS as "Content Script"
participant OD as "Offscreen Document"
participant AG as "Local Agent Client"
participant AGT as "Agent 服务"
SP->>BG : "CALL_API / RESUME_REACT / GET_MCP_TOOLS / RAG_*"
BG->>AG : "HTTP/WebSocket 请求配对、文件、命令、MCP、RAG"
AG->>AGT : "调用 Agent API"
AGT-->>AG : "返回结果"
AG-->>BG : "结果/错误"
BG-->>SP : "API_COMPLETE / STREAM_* / API_ERROR"
CS->>BG : "CAPTURE_TAB_FROM_PAGE / CAPTURE_REGION_FROM_PAGE"
BG->>CS : "START_REGION_SELECTION"
CS-->>BG : "矩形坐标"
BG->>OD : "COPY_TO_CLIPBOARD / PASTE_FROM_CLIPBOARD"
OD-->>BG : "剪贴板操作结果"

图表来源

详细组件分析

Service Worker 生命周期与保活机制

保活端口：Side Panel 通过 chrome.runtime.connect 建立 keepalive port，SW 维护端口映射，重连时检测 SW 重启并通知前端。
自动恢复：chrome.alarms 定时触发 auto-resume，扫描 checkpoint 并恢复 ReAct 循环，耗尽时通知人工介入。
侧边栏状态镜像：_openPanelsByWindow、_activeTabByWindow、_lastFocusedWindowId 同步维护面板打开状态与活跃 tab，确保快捷键 toggle 在用户手势栈内完成。
作用域模式：global 与 tab-specific 两种模式，tab-specific 模式下对显式打开的 tab 做 per-tab 启用，并可选将 tab 归入 AI Helper 分组。

flowchart TD
Start(["SW 启动"]) --> InitI18n["初始化国际化"]
InitI18n --> RehydrateAlarms["重建定时任务闹钟"]
RehydrateAlarms --> AutoResume["注册自动恢复处理器"]
AutoResume --> CleanupCheckpoints["清理过期 checkpoint"]
CleanupCheckpoints --> KeepalivePorts["注册 keepalive 端口监听"]
KeepalivePorts --> SidePanelControl["侧边栏控制与状态镜像"]
SidePanelControl --> MessageRouter["消息路由表"]
MessageRouter --> End(["就绪"])

图表来源

章节来源

Side Panel 界面架构与聊天管理

入口聚合：side_panel/index.js 引入主题、状态、常量、工具函数、聊天管理、工具面板、工作区、书签、技能选择等模块。
聊天管理：chat-manager.js 负责会话持久化、流式输出、执行日志、反思评估、任务恢复、上下文压缩、图片预览、文件提取等。
用户交互：发送消息、划词问答、截图、引用知识库、技能注入、模型选择、温度/TopP 设置。
配置监听：storage.onChanged 监听自动压缩、摘要存入记忆、记忆限制等配置变更，实时更新 UI。

classDiagram
class ChatManager {
+sendMessage()
+clearChatHistory()
+showExportDialog()
+hideExportDialog()
+performExport()
+initExportDialogEvents()
+triggerImportDialog()
+handleImportFile()
+showModal()
+hideModal()
+loadChatHistory()
+saveChatHistory()
+addMessage()
+addContextBubble()
+addLoadingMessage()
+removeLoadingMessage()
+callApi()
+clearSelectedContext()
+triggerSelectionSearch()
+fillSidePanelInput()
+directSend()
+restorePendingSessionsFromStorage()
+restoreMessageFromHtml()
+bindExecutionLogDelegate()
+bindReflectionBadgeDelegate()
+rebindAllMessages()
+editAndResendMessage()
+compressAndAttachImage()
+openImagePreview()
+initImagePreviewOverlay()
+cancelStreamingTask()
+reconnectStreamingElement()
+_checkForAbandonedCheckpoint()
+setMessageTimestampVisible()
}
class State {
+chatConfig
+currentModel
+selectedContextText
+quotedContextText
+pendingCallApiSessionIds
}
class ToolPanel {
+openToolsPopup()
+closeToolsPopup()
+renderToolsPopupList()
+getVisibleTools()
+updateAllCategoryCounts()
+updateCategoryBadges()
+updateToolsPopupTitle()
+saveToolsFromPopup()
+updateToolsToggleState()
+updateToolsConfigIndicators()
+setVisibleMcpServicesOpen()
+refreshToolPopupIfOpen()
+applyRagToolIntroduction()
+getValidToolIdUniverse()
}
ChatManager --> State : "使用"
ChatManager --> ToolPanel : "集成"

图表来源

章节来源

Content Scripts 注入机制与消息路由

注入方式：manifest.json 声明 content_scripts，匹配所有 URL，注入 qrcode/marked 库与 index.js，CSS 样式全局注入。
消息路由表：HANDLERS Map 按 message.type 分发，分类页面读取、交互、提取、媒体、异步工具。
异步处理：ASYNC_HANDLERS Set 标记需 return true 保持通道开放的工具，Promise.resolve(result).then(sendResponse)。
顶层帧限制：TOP_FRAME_ONLY_TYPES 避免 iframe 响应覆盖主页面内容。
区域截图：startRegionSelection 创建遮罩层与选择框，返回矩形坐标。

flowchart TD
Load["Content Script 加载"] --> RegisterHandlers["注册 HANDLERS Map"]
RegisterHandlers --> OnMessage["chrome.runtime.onMessage.addListener"]
OnMessage --> CheckTopFrame{"顶层帧？"}
CheckTopFrame --> |否| Skip["跳过 TOP_FRAME_ONLY_TYPES"]
CheckTopFrame --> |是| FindHandler["查找 handler"]
FindHandler --> IsAsync{"异步工具？"}
IsAsync --> |是| AsyncFlow["Promise.then(sendResponse)"]
IsAsync --> |否| SyncFlow["sendResponse(result)"]
AsyncFlow --> End(["结束"])
SyncFlow --> End

图表来源

章节来源

Offscreen Document 与剪贴板兼容层

作用：提供浏览器剪贴板 API 的兼容层，优先使用 navigator.clipboard，失败回退到 execCommand copy/paste。
实现：offscreen.js 监听 COPY_TO_CLIPBOARD 与 PASTE_FROM_CLIPBOARD 消息，返回成功/失败结果与 i18n 文案。
HTML 结构：offscreen.html 包含隐藏 textarea 用于兼容剪贴板操作。

sequenceDiagram
participant BG as "Background"
participant OD as "Offscreen Document"
BG->>OD : "COPY_TO_CLIPBOARD / PASTE_FROM_CLIPBOARD"
OD->>OD : "navigator.clipboard.writeText/readText"
OD->>OD : "execCommand('copy'/'paste') 回退"
OD-->>BG : "{success, message/text/error}"

图表来源

章节来源

工具执行与 Agent 客户端

工具执行：tool-executor.js 定义内置工具、MCP、RAG、Skill、快照编排、截图下载等，支持并行、确认、超时、审计日志。
Agent 客户端：local-agent-client.js 封装 HTTP/WebSocket 请求，支持配对、健康检查、可达性缓存、多代理切换、文件上传、Skill Prompt 获取。
消息路由：background/index.js 中 GET_MCP_TOOLS、RELOAD_MCP_TOOLS、RAG_LIST_COLLECTIONS、RAG_SEARCH 等消息转发至 Agent 客户端。

graph TB
BG["Background 消息路由"] --> TE["tool-executor.js"]
TE --> LC["local-agent-client.js"]
LC --> AG["Agent 服务"]
BG --> AG

图表来源

章节来源

依赖关系分析

Service Worker 依赖：
- state.js：keepalive 端口管理、取消标志、最后操作 tab。
- config.js：存储配置、聊天配置。
- tool-executor.js：工具加载、MCP/RAG 工具、命令取消。
- react-loop.js：ReAct 循环、非流式 API 调用。
- scheduler.js：定时任务闹钟恢复。
- detach-window.js：脱离窗口状态恢复。
- notifier.js：通知与面板断开提醒。
- panel-visibility.js：面板可见性判定。
- local-agent-client.js：Agent 客户端。
- db.js：checkpoint 存取。
- auto-resume.js：自动恢复策略。
- context-compactor.js / compaction-memory.js：上下文压缩与记忆沉淀。
- logger.js / i18n.js：日志与国际化。
Side Panel 依赖：
- theme.js：主题 Token。
- state.js：侧边栏状态。
- constants.js：内置工具、预设模式。
- utils.js：工具函数、系统提示、API 参数。
- token-counter.js：Token 计数与上下文窗口。
- session-manager.js：会话持久化。
- agent-manager.js：Agent 管理。
- skill-selector.js：技能选择。
- tool-panel.js：工具面板。
- workspace-panel.js：工作区面板。
- bookmark-manager.js：书签管理。
- markdown-render.js：Markdown 渲染。
- image-helpers.js：图片辅助。
- chat-manager.js：聊天管理。
- chat-streaming.js：流式输出。
- chat-resume.js：任务恢复。
- execution-log-render.js：执行日志渲染。
- artifacts-manager.js：产物管理。
- page-selector.js：页面选择。
- agent-at-selector.js：知识库选择。
- panel-context.js：面板上下文。
- logger.js / i18n.js：日志与国际化。
Content Scripts 依赖：
- page-tools.js：页面文本、HTML、选区、剪贴板、高亮。
- page-interaction.js：元素查询、快照采集、滚动、交互。
- page-extract.js：元数据、链接、表单、图片、搜索、iframe 内容。
- interaction-tools.js：点击、填充、滚动、等待、键盘输入、文件上传、存储管理、下拉选择、文本点击。
- advanced-tools.js：二维码生成、CSS 注入、完成度校验。
- shadow-dom-utils.js：Shadow DOM 选区。
- selection-toolbar.js：选中文本浮动工具栏。
- i18n.js：国际化。
Offscreen Document 依赖：
- i18n.js：国际化文案。

graph TB
BG["background/index.js"] --> STATE["state.js"]
BG --> CONFIG["config.js"]
BG --> TOOL_EXEC["tool-executor.js"]
BG --> REACT_LOOP["react-loop.js"]
BG --> SCHEDULER["scheduler.js"]
BG --> DETACH["detach-window.js"]
BG --> NOTIFIER["notifier.js"]
BG --> PANEL_VIS["panel-visibility.js"]
BG --> AG_CLIENT["local-agent-client.js"]
BG --> DB["db.js"]
BG --> AUTO_RESUME["auto-resume.js"]
BG --> COMPACT_CTX["context-compactor.js"]
BG --> COMPACT_MEM["compaction-memory.js"]
BG --> LOGGER["logger.js"]
BG --> I18N["i18n.js"]
SP["side_panel/index.js"] --> THEME["theme.js"]
SP --> SP_STATE["state.js"]
SP --> CONSTANTS["constants.js"]
SP --> UTILS["utils.js"]
SP --> TOKEN_COUNTER["token-counter.js"]
SP --> SESSION_MGR["session-manager.js"]
SP --> AGENT_MGR["agent-manager.js"]
SP --> SKILL_SEL["skill-selector.js"]
SP --> TOOL_PANEL["tool-panel.js"]
SP --> WORKSPACE["workspace-panel.js"]
SP --> BOOKMARK_MGR["bookmark-manager.js"]
SP --> MARKDOWN["markdown-render.js"]
SP --> IMAGE_HELP["image-helpers.js"]
SP --> CHAT_MGR["chat-manager.js"]
SP --> CHAT_STREAM["chat-streaming.js"]
SP --> CHAT_RESUME["chat-resume.js"]
SP --> EXEC_LOG["execution-log-render.js"]
SP --> ARTIFACTS["artifacts-manager.js"]
SP --> PAGE_SEL["page-selector.js"]
SP --> AGENT_AT["agent-at-selector.js"]
SP --> PANEL_CTX["panel-context.js"]
SP --> LOGGER
SP --> I18N
CS["content/index.js"] --> PAGE_TOOLS["page-tools.js"]
CS --> PAGE_INTER["page-interaction.js"]
CS --> PAGE_EXTRACT["page-extract.js"]
CS --> INTER_TOOLS["interaction-tools.js"]
CS --> ADV_TOOLS["advanced-tools.js"]
CS --> SHADOW_DOM["shadow-dom-utils.js"]
CS --> SEL_TOOLBAR["selection-toolbar.js"]
CS --> I18N
OD["offscreen/offscreen.js"] --> I18N

图表来源

章节来源

性能与内存优化

Service Worker 保活：keepalive port 防止 SW 空闲被终止，减少频繁重建成本。
消息截断：MAX_LOG_ENTRIES_FOR_MSG 限制 executionLog 大小，避免 64MiB 限制。
工具缓存：mcpToolsCache 与 skillPromptsCache 减少网络请求。
自动恢复：checkpoint 机制避免重复执行，子任务级 subtaskProgress 防重放。
侧边栏状态镜像：同步镜像避免异步查询破坏手势上下文，减少竞态。
内容脚本异步处理：ASYNC_HANDLERS Set 精确标记异步工具，避免不必要的通道保持。
Offscreen 剪贴板兼容：navigator.clipboard 优先，execCommand 回退，提升兼容性。
日志级别：logger.js 支持 DEBUG/INFO/WARN/ERROR 分级，便于调试与性能监控。
国际化：i18n.js 支持运行时语言切换与订阅刷新，避免硬编码文案。

[本节为一般性指导，不直接分析具体文件]

故障排查指南

Service Worker 终止恢复：
- 现象：SW 被系统回收，API 调用中断。
- 排查：检查 keepalive port 是否重连，SW_RESTARTED 消息是否发送，checkpoint 是否存在。
- 解决：确保 Side Panel 保持连接，手动触发 RESUME_REACT 或等待自动恢复。
侧边栏无法打开/关闭：
- 现象：快捷键 toggle 无效，open/close 失败。
- 排查：检查 _openPanelsByWindow 镜像是否正确，手势上下文是否保留，Chrome 版本是否支持 sidePanel.close。
- 解决：确保在用户手势栈内调用 open/close，必要时回退到 window.close。
消息路由失败：
- 现象：Side Panel 发送 CALL_API 无响应。
- 排查：检查 background/index.js 消息路由表是否包含对应 type，sender.tab 是否存在。
- 解决：确保消息类型正确，异步消息返回 true 保持通道开放。
Content Scripts 注入失败：
- 现象：Content Script 未加载，消息路由表为空。
- 排查：检查 manifest.json content_scripts 配置，isExtensionValid() 是否返回 true。
- 解决：确保扩展已启用，URL 匹配规则正确。
Offscreen 剪贴板操作失败：
- 现象：COPY_TO_CLIPBOARD/PASTE_FROM_CLIPBOARD 返回失败。
- 排查：检查 navigator.clipboard 是否可用，execCommand 是否成功。
- 解决：确保 Offscreen Document 已创建，权限 clipboardRead/clipboardWrite 已授予。
Agent 客户端连接失败：
- 现象：GET_MCP_TOOLS/RAG_SEARCH 失败。
- 排查：检查 Agent 服务是否运行，配对是否成功，可达性缓存状态。
- 解决：重启 Agent 服务，重新配对，检查网络权限。

章节来源

结论

本 Chrome 扩展核心以 MV3 Service Worker 为中心，结合 Side Panel、Content Scripts 与 Offscreen Document，构建了完整的 AI 助手生态。Service Worker 负责保活、消息路由与 ReAct 循环调度；Side Panel 提供丰富的用户交互与聊天管理；Content Scripts 实现页面操作与信息提取；Offscreen Document 提供剪贴板兼容能力。通过工具执行与 Agent 客户端，扩展端与本地 Agent 紧密协作，实现文件读写、命令执行、长期记忆与 RAG 能力。遵循 MV3 最佳实践，注意 Service Worker 生命周期、跨上下文通信与内存管理，可有效避免常见陷阱，提升扩展稳定性与性能。

[本节为总结性内容，不直接分析具体文件]

消息流与工具调用

RAG 数据处理管道

工具面板集成

聊天管理系统

主题与国际化系统

UI 组件库

Markdown 渲染引擎

Chrome 扩展核心

目录

引言

项目结构

核心组件

架构总览

详细组件分析

Service Worker 生命周期与保活机制

Side Panel 界面架构与聊天管理

Content Scripts 注入机制与消息路由

Offscreen Document 与剪贴板兼容层

工具执行与 Agent 客户端

依赖关系分析

性能与内存优化

故障排查指南

结论

Markdown 渲染引擎

Chrome 扩展核心 ​

目录 ​

引言 ​

项目结构 ​

核心组件 ​

架构总览 ​

详细组件分析 ​

Service Worker 生命周期与保活机制 ​

Side Panel 界面架构与聊天管理 ​

Content Scripts 注入机制与消息路由 ​

Offscreen Document 与剪贴板兼容层 ​

工具执行与 Agent 客户端 ​

依赖关系分析 ​

性能与内存优化 ​

故障排查指南 ​

结论 ​

Chrome 扩展核心

目录

引言

项目结构

核心组件

架构总览

详细组件分析

Service Worker 生命周期与保活机制

Side Panel 界面架构与聊天管理

Content Scripts 注入机制与消息路由

Offscreen Document 与剪贴板兼容层

工具执行与 Agent 客户端

依赖关系分析

性能与内存优化

故障排查指南

结论