AI Helper 文档中心

主题

Side Panel 界面架构 ​

本文引用的源码文件

本文引用的文件

更新摘要 ​

变更内容

  • 优化侧边栏输入区域布局，提升单行输入体验的紧凑性
  • 调整输入框内边距从 12px→8px，减少垂直空间占用
  • 降低文本域最小高度从 42px→34px，实现更紧凑的单行显示
  • 收紧容器间距从 12px→10px，优化整体视觉密度
  • 新增一体化容器设计，支持响应式工具栏和动态布局适配

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与可维护性
  8. 故障排查指南
  9. 结论
  10. 附录：扩展指南

引言 ​

Side Panel 是 Chrome 扩展侧边栏的 UI 层，负责聊天输入、会话管理、消息渲染、工具面板、主题与国际化、上下文压缩提示、执行日志与质量评估等。它通过 chrome.runtime.sendMessage 与 Background Service Worker 通信，Background 再调度本地 Agent（Node.js）完成 ReAct 推理、工具执行、记忆与 RAG 检索，并将流式结果回推到 Side Panel 进行增量渲染。

本文件面向开发者与维护者，系统性说明 Side Panel 的设计模式、状态管理、消息通信、工具面板集成、主题与 i18n、响应式与可访问性，并给出扩展新 UI 组件的实践路径。

项目结构 ​

Side Panel 采用"入口聚合 + 职责拆分"的组织方式：

  • 入口与装配：index.js 负责初始化主题、i18n、全局状态、各子模块事件绑定与跨模块协作。
  • 状态中心：state.js 提供集中式运行时状态，并通过 getter/setter 暴露给各模块。
  • 聊天管理：chat-manager.js 负责会话加载/保存、消息历史、知识库上下文、错误映射、子任务过滤等。
  • 流式输出：chat-streaming.js 负责流式 DOM 创建、增量 Markdown 渲染、滚动控制、思考过程折叠与筛选。
  • 全屏阅读：message-fullscreen.js 提供沉浸式阅读体验，使用节点迁移而非克隆，支持键盘快捷键和导出功能。
  • 会话存储：session-manager.js 封装 IndexedDB 会话读写，并提供"完成待查看"标记持久化。
  • 工具面板：tool-panel.js 负责内置工具、RAG 动态工具、MCP 服务级开关、分类搜索与全选逻辑。
  • 常量与预设：constants.js 导出工具分类、RAG 工具 ID 全集与温度预设。
  • 主题与 i18n：shared/theme.css/js 提供 CSS Token 与主题切换；shared/i18n.js 提供多语言查表与订阅刷新。
  • 样式系统：styles.css 定义完整的 UI 样式，包括优化的输入区域布局和响应式设计。
graph TB
A["side_panel/index.js<br/>入口装配"] --> B["side_panel/state.js<br/>全局状态"]
A --> C["side_panel/chat-manager.js<br/>聊天管理"]
A --> D["side_panel/chat-streaming.js<br/>流式渲染"]
A --> E["side_panel/message-fullscreen.js<br/>全屏阅读"]
A --> F["side_panel/session-manager.js<br/>会话存储"]
A --> G["side_panel/tool-panel.js<br/>工具面板"]
G --> H["background/tool-executor.js<br/>RAG 工具注册"]
C --> I["background/stream-controller.js<br/>流式控制器"]
I --> J["background/react-loop.js<br/>ReAct 循环"]
A --> K["shared/theme.js / theme.css<br/>主题 Token"]
A --> L["shared/i18n.js<br/>多语言"]
A --> M["side_panel/styles.css<br/>样式系统"]

图示来源

章节来源

核心组件 ​

  • 全局状态 state.js：集中管理活跃会话、模型参数、工具启用列表、Agent 平台信息、图片/文件附件、上下文压缩记录、执行状态等，并通过 getter/setter 触发 UI 更新事件。
  • 聊天管理 chat-manager.js：会话加载/保存、消息历史恢复、知识库上下文构建、API 错误文案本地化、子任务状态分类与过滤、书签与分叉会话等。
  • 流式输出 chat-streaming.js：流式消息容器、增量 Markdown 渲染、智能滚动、思考过程折叠与节点筛选、Token 统计弹窗、执行日志与反思展示。
  • 全屏阅读 message-fullscreen.js：沉浸式阅读体验、节点迁移方案、键盘快捷键（Alt+F、Alt+双击）、导出功能集成、智能滚动行为、会话 DOM 快照保护。
  • 会话管理 session-manager.js：IndexedDB 会话 CRUD、"完成待查看"标记持久化、归档/恢复、导入/导出、复制会话。
  • 工具面板 tool-panel.js：内置工具、RAG 动态工具、MCP 服务级开关、分类搜索、全选/取消全选、角标计数、Agent 限制横幅。
  • 常量 constants.js：工具分类顺序、RAG 工具 ID 全集、温度预设。
  • 主题 theme.js/theme.css：CSS Token 体系、light/dark/system 三态、防闪烁、订阅通知。
  • 国际化 i18n.js：t(key, params)、initI18n、applyI18n、registerTranslations、storage.onChanged 跨环境同步。
  • 样式系统 styles.css：一体化容器设计、优化输入区域布局、响应式工具栏、主题变量应用。

章节来源

架构总览 ​

Side Panel 作为 MV3 扩展的 UI 层，承担用户交互与数据呈现；Background 负责 ReAct 推理、工具调度、记忆与 RAG；Agent 提供文件系统、命令执行、技能与 MCP 能力。消息通道包括：

  • Side Panel → Background：CALL_API、DIRECT_SEND、FILL_SIDEPANEL_INPUT、RAG_SEARCH 等。
  • Background → Side Panel：STREAM_START/STREAM_CHUNK/STREAM_TOOL_RESULT/API_COMPLETE 等。
  • Background ↔ Agent：HTTP REST + WebSocket（本地代理端点）。
sequenceDiagram
participant U as "用户"
participant SP as "Side Panel"
participant BG as "Background"
participant AG as "Agent(本地)"
participant LLM as "大模型 API"
U->>SP : "输入问题/选择工具/附加文件"
SP->>BG : "发送 CALL_API/DIRECT_SEND"
BG->>AG : "调度 ReAct 循环/工具执行/RAG"
AG->>LLM : "调用模型接口(支持流式)"
LLM-->>AG : "返回 token 流/工具调用"
AG-->>BG : "工具结果/观察提示/完成信号"
BG-->>SP : "STREAM_START/STREAM_CHUNK/STREAM_TOOL_RESULT"
SP->>SP : "增量渲染 Markdown/Mermaid/思考过程"
BG-->>SP : "API_COMPLETE"
SP->>SP : "更新 Token 统计/书签/会话持久化"

图示来源

详细组件分析 ​

聊天管理系统（会话、消息历史、流式响应、上下文压缩） ​

  • 会话生命周期：首次打开自动创建默认会话；加载历史时恢复 activeSessionId、messageHistory、contextCompaction、模型/温度、Agent 绑定等；清空会话会归档当前会话并重置 UI。
  • 消息历史维护：从 IndexedDB 恢复 HTML 或文本内容；对含 executionLog 的消息检测是否被修订；恢复后统一绑定执行日志与反思徽章委托；渲染 Mermaid 与代码复制按钮；渲染上下文压缩分隔条。
  • 流式响应处理：chat-streaming.js 维护按 sessionId 隔离的流式元素与累积内容；支持智能滚动、思考过程折叠、节点筛选、Token 统计弹窗；在 Background 推送 STREAM_* 时增量更新 DOM。
  • 上下文压缩：state.activeCompaction 与会话级 contextCompaction 同步；auto-compaction 在发送前根据阈值触发压缩；context-indicator 计算占用并显示进度条。
flowchart TD
Start(["进入聊天管理"]) --> LoadSessions["加载会话列表"]
LoadSessions --> HasActive{"存在活跃会话?"}
HasActive --> |是| RestoreState["恢复会话状态<br/>模型/温度/Agent/MCP排除列表"]
RestoreState --> RenderMessages["恢复消息历史<br/>HTML/文本/执行日志"]
RenderMessages --> BindDelegates["绑定执行日志/反思徽章委托"]
BindDelegates --> RenderMermaid["渲染 Mermaid/代码复制"]
RenderMermaid --> RenderCompaction["渲染上下文压缩分隔条"]
RenderCompaction --> CheckCheckpoint["检查未清理 checkpoint"]
CheckCheckpoint --> End(["完成"])
HasActive --> |否| CreateDefault["创建默认会话"]
CreateDefault --> RenderTabs["渲染会话标签"]
RenderTabs --> End

图示来源

章节来源

全屏阅读功能（沉浸式体验、节点迁移、键盘快捷键） ​

新增 全屏阅读功能为 AI 助手回答提供了沉浸式的阅读体验，采用创新的节点迁移方案而非克隆，确保事件监听和流式更新的完整性。

  • 节点迁移方案：将真实 DOM 节点移入全屏覆盖层，退出时按占位锚点归位。选择迁移而非克隆的原因包括：事件监听随节点保留、表格工具条/代码复制/展开折叠等交互零损失、流式输出中打开时展示的是活节点、新 token 直接呈现在全屏视图无需同步逻辑。
  • 键盘快捷键：支持 Alt+F 快速切换最后一条助手消息全屏、Alt+双击消息区进入全屏、Esc 退出全屏。在全屏模式下，Esc 键优先消费并阻断传播，避免误触其他快捷键面板。
  • 导出功能集成：头栏集成完整的导出菜单，支持 Word、PDF、图片、Markdown 格式导出，与消息 footer 的导出功能保持一致。
  • 智能滚动行为：全屏 body 作为新的滚动容器，内容增高时自动滚到底部；当用户上滚超过阈值时暂停跟随，提升阅读体验。
  • 会话 DOM 快照保护：全屏期间拒绝返回缓存 innerHTML，避免会话 DOM 缓存丢失内容的问题。
flowchart TD
UserAction["用户操作"] --> AltF["Alt+F 快捷键"]
UserAction --> AltDouble["Alt+双击消息"]
UserAction --> FooterBtn["Footer 全屏按钮"]
AltF --> OpenFullscreen["打开全屏模式"]
AltDouble --> OpenFullscreen
FooterBtn --> OpenFullscreen
OpenFullscreen --> NodeMigration["节点迁移至覆盖层"]
NodeMigration --> OverlayShow["显示覆盖层"]
OverlayShow --> StreamFollow["启动流式跟随滚动"]
StreamFollow --> ReadingExperience["沉浸式阅读体验"]
ReadingExperience --> ExportOptions["导出选项"]
ExportOptions --> CloseFullscreen["关闭全屏"]
CloseFullscreen --> NodeReturn["节点归位到原位置"]
NodeReturn --> ScrollRestore["恢复主列表滚动位置"]

图示来源

章节来源

工具面板集成方案（注册、动态加载、用户交互） ​

  • 工具来源：
    • 内置工具：BUILTIN_TOOLS_UI（来自 background/constants.js），由 side_panel/constants.js 重导出。
    • RAG 动态工具：Background 在 ragEnabled=true 且 Agent 支持 RAG 时动态注册，并同步到 chrome.storage.local.ragTools。
    • MCP 工具：按服务分组，服务级开关（deny-list）控制开放/关闭；助手编辑器可排除服务。
  • 用户交互：
    • 分类搜索、折叠、全选/取消全选、角标计数。
    • 工具预筛选与敏感操作确认开关状态实时反映在工具栏配置按钮右上角。
    • Agent 限定时显示横幅，并在 Agent 离线时隐藏依赖代理的工具。
  • 状态同步：
    • storage.onChanged 监听 mcpTools/ragTools/mcpEnabled/skillsEnabled 等键变化，实时更新弹窗与工具栏。
    • getAgentFilteredTools 结合 activeAgentToolIds、globalSkillsEnabled、agentPlatform.connected 过滤可见工具。
classDiagram
class ToolPanel {
+openToolsPopup()
+renderToolsPopupList()
+getVisibleTools()
+updateCategoryBadges()
+toggleMcpService(serverId, open)
}
class State {
+enabledTools
+currentCategory
+currentSearch
+mcpClosedServers
+collapsedCategories
+activeAgentToolIds
}
class Constants {
+BUILTIN_TOOLS
+CATEGORY_ORDER
+RAG_TOOL_IDS
}
ToolPanel --> State : "读取/写入"
ToolPanel --> Constants : "使用"

图示来源

章节来源

主题系统与国际化支持（Token、亮暗切换、多语言渲染） ​

  • 主题系统：
    • theme.js 维护 preference（light/dark/system）与 resolved（light/dark），通过 document.documentElement.setAttribute('data-theme', ...) 驱动 CSS 变量翻转。
    • theme.css 定义完整 Token 体系（表面、文本、品牌、边框、状态、Toast、浮层阴影等），并按 data-theme="dark" 覆盖暗色值；Markdown 在暗色下逐类覆盖以保证可读性。
    • initTheme 监听 matchMedia 与 chrome.storage.onChanged，实现系统主题跟随与跨环境同步；顶层缓存 appThemeResolved 防止闪烁。
  • 国际化：
    • i18n.js 提供 t(key, params) 插值、initI18n 初始化语言偏好、applyI18n 填充 data-i18n/data-i18n-placeholder/data-i18n-title/data-i18n-aria-label。
    • registerTranslations 允许各模块按需追加翻译；storage.onChanged 跨环境同步语言变更。
    • Side Panel 内多处使用 t(...) 渲染工具描述、消息状态、对话框文案等。
flowchart TD
Init["initTheme/initI18n"] --> ReadStorage["读取 appTheme/language"]
ReadStorage --> ApplyTheme["设置 data-theme"]
ApplyTheme --> CSSVars["CSS Token 生效"]
Init --> DetectLang["检测浏览器语言/用户偏好"]
DetectLang --> SetLang["setLanguage(persist)"]
SetLang --> NotifySubs["通知订阅者刷新文案"]
NotifySubs --> ApplyI18n["applyI18n 填充 DOM"]

图示来源

章节来源

用户界面组件的职责分离（输入框、消息列表、工具选择器） ​

  • 输入框与工具栏：index.js 中初始化记忆限制下拉、模型选择、Agent 指示、划词浮动菜单、输入历史、Prompt 管理等；工具栏按钮与工具面板联动。
  • 消息列表：chat-manager.js 负责 addMessage/addContextBubble/addLoadingMessage/removeLoadingMessage/clearSelectedContext 等；chat-streaming.js 负责流式消息容器与增量更新。
  • 工具选择器：tool-panel.js 提供 open/close/render/update 系列函数；skill-selector/page-selector/agent-at-selector/file-at-selector 等提供上下文选择能力，与聊天上下文气泡联动。
graph LR
Input["输入框/工具栏<br/>index.js"] --> ChatMgr["聊天管理<br/>chat-manager.js"]
Input --> ToolPanel["工具面板<br/>tool-panel.js"]
ChatMgr --> Stream["流式渲染<br/>chat-streaming.js"]
SkillSel["技能/页面/Agent/文件选择器"] --> ChatMgr

图示来源

章节来源

输入区域优化设计（紧凑布局、响应式适配） ​

更新 侧边栏输入区域经过精心优化，实现了更加紧凑的单行输入体验，同时保持了良好的用户体验和功能完整性。

  • 一体化容器设计：采用 .input-container 作为统一的输入区域容器，支持 flexbox 布局，包含引用指示器、文本域和底部工具行的完整结构。
  • 优化内边距：文本域内边距从 12px 调整为 8px，减少了垂直空间占用，使单行输入更加紧凑。
  • 降低最小高度：文本域最小高度从 42px 降至 34px，实现了更自然的单行显示效果。
  • 收紧容器间距：容器间距从 12px 调整为 10px，提升了整体视觉密度和空间利用率。
  • 响应式工具栏：支持图标模式和完整模式之间的自适应切换，在小屏幕设备上自动简化显示。
  • 焦点状态优化：使用 :focus-within 伪类实现容器级别的焦点视觉反馈，提供更好的用户体验。
flowchart TD
Container[".input-container<br/>一体化容器"] --> Indicators["引用指示器<br/>selection/page/knowledge/mcp/skill"]
Container --> Textarea["文本域<br/>padding: 8px 4px<br/>min-height: 34px"]
Container --> BottomRow["底部工具行<br/>gap: 6px"]
BottomRow --> LeftGroup["左侧工具组<br/>添加/记忆/工具/划词"]
BottomRow --> RightGroup["右侧工具组<br/>Agent/温度/发送"]
Text --> CompactLayout["紧凑布局<br/>单行高度优化"]
CompactLayout --> BetterUX["更好的用户体验"]

图示来源

章节来源

依赖关系分析 ​

  • Side Panel 内部依赖：
    • index.js 聚合 state、utils、i18n、theme、各子模块（chat-manager、tool-panel、skill-selector、page-selector、agent-at-selector、file-at-selector、image-helpers、markdown-render、prompt-manager、session-manager-ui 等）。
    • chat-manager.js 依赖 session-manager、execution-log-render、export-import、image-preview、file-extract、skill-selector、bookmark-manager、artifacts-manager、chat-copy、chat-streaming、chat-resume、panel-context、token-counter、context-usage 等。
    • message-fullscreen.js 依赖 logger、i18n，并与 chat-manager、chat-streaming 集成。
  • 外部依赖：
    • Background：stream-controller 负责流式协议封装；react-loop 负责 ReAct 循环与工具结果回推；tool-executor 负责 RAG 工具动态注册与 storage 同步。
    • Shared：theme/i18n/logger/utils/token-counter/context-usage 等公共库。
graph TB
Index["index.js"] --> CM["chat-manager.js"]
Index --> TP["tool-panel.js"]
Index --> MF["message-fullscreen.js"]
Index --> ST["state.js"]
CM --> CS["chat-streaming.js"]
CM --> SM["session-manager.js"]
CM --> TC["token-counter.js"]
CM --> CU["context-usage.js"]
MF --> I18N["i18n.js"]
TP --> CT["constants.js"]
CM --> BGSC["background/stream-controller.js"]
BGSC --> BGR["background/react-loop.js"]
TP --> BGTE["background/tool-executor.js"]
ST --> SCSS["styles.css"]

图示来源

章节来源

性能与可维护性 ​

  • 首屏体积优化：chat-export 的 docx 依赖改为按需 import，避免拖入 side_panel 首屏 chunk（PERF-05）。
  • 流式渲染节流：chat-streaming.js 使用 requestAnimationFrame 与 _isProgramScroll/_userScrolledUp 区分程序滚动与用户滚动，避免高频 DOM 更新导致卡顿。
  • 状态隔离：按 sessionId 隔离流式元素与累积内容，防止多会话并行串台。
  • 存储异步：会话加载/保存使用 IndexedDB 适配器，避免阻塞 UI；completedSessionIds 持久化到 chrome.storage.local。
  • 主题防闪烁：theme.js 顶层同步读取 localStorage 镜像 appThemeResolved，先落 data-theme，再异步读取 chrome.storage.local 覆盖。
  • 全屏阅读性能：节点迁移方案避免克隆开销，事件监听随节点保留，流式更新无需同步逻辑，提升整体性能。
  • 输入区域性能：一体化容器设计减少 DOM 层级，优化后的内边距和间距提升渲染性能，响应式适配避免不必要的重排重绘。

[本节为通用指导，不直接分析具体文件]

故障排查指南 ​

  • 侧边栏未打开时的直接发送：
    • Content Script 通过 DIRECT_SEND 将文本与选中内容存入 chrome.storage.session.pendingDirectSend，Background 打开侧边栏后推送消息；若侧边栏未就绪，消息暂存等待加载。
  • 流式输出中断：
    • Background stream-controller 在 finishReason=length 时标记 truncated；tool_calls 完成后发送 STREAM_TOOL_RESULT；若连接异常，Side Panel 显示重试提示。
  • RAG 工具不可用：
    • Background tool-executor.loadRagTools 检查 ragEnabled 与 Agent RAG 可用性，失败则卸载 RAG 工具并清空 storage.ragTools；Side Panel tool-panel.js 监听 ragTools 变化刷新 UI。
  • 主题与语言不同步：
    • theme.js 与 i18n.js 均监听 chrome.storage.onChanged，确保跨环境同步；若出现闪烁或文案未刷新，检查 initTheme/initI18n 是否在启动时调用。
  • 全屏阅读功能异常：
    • 检查 message-fullscreen.js 是否正确初始化 initMessageFullscreen()。
    • 验证键盘事件监听是否正确绑定，特别是 Alt+F 和 Esc 键处理。
    • 确认节点迁移过程中锚点注释是否正确插入和清理。
    • 检查会话 DOM 快照保护机制是否正常工作。
  • 输入区域显示异常：
    • 检查 .input-container 容器的 padding 和 gap 属性是否正确应用。
    • 验证 textarea 的 min-height 和 padding 值是否符合预期（34px 和 8px 4px）。
    • 确认响应式工具栏的降级逻辑是否正常工作。
    • 检查焦点状态的视觉反馈是否正常显示。

章节来源

结论 ​

Side Panel 以清晰的职责分层与模块化组织，实现了聊天管理、流式渲染、全屏阅读、工具面板、主题与 i18n 的协同工作。通过 Background 与 Agent 的双进程架构，扩展了文件读写、命令执行、长期记忆与 RAG 能力。新增的全屏阅读功能通过创新的节点迁移方案，提供了沉浸式的阅读体验，同时保持了事件监听和流式更新的完整性。优化的输入区域设计通过一体化容器、紧凑布局和响应式适配，显著提升了用户的输入体验和界面美观度。文档提供了扩展新 UI 组件的路径：在 index.js 中装配模块、在 state.js 中声明状态、在 chat-manager/chat-streaming 中接入消息流、在 tool-panel 中注册工具项，并使用 theme.css Token 与 i18n.t 保证主题与多语言一致性。

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

附录：扩展指南 ​

  • 新增 UI 组件步骤：
    1. 在 src/side_panel 下新建模块文件，定义组件逻辑与事件绑定。
    2. 在 src/side_panel/state.js 中添加必要状态字段，并通过 getter/setter 暴露。
    3. 在 src/side_panel/index.js 中 import 并初始化模块，绑定 DOM 事件。
    4. 如需与聊天流程交互，在 chat-manager.js 中暴露方法供其他模块调用。
    5. 如需流式更新，参考 chat-streaming.js 的 addStreamingMessage/updateStreamingMessage 模式。
    6. 使用 theme.css Token 与 i18n.t 渲染文案，确保亮暗主题与多语言一致。
    7. 如为新工具，需在 background/tool-executor.js 注册 handler，并在 side_panel/tool-panel.js 中参与分类与勾选逻辑。
  • 全屏阅读功能扩展要点：
    1. 使用节点迁移而非克隆，确保事件监听和流式更新正常工作。
    2. 实现键盘快捷键支持，如 Alt+F、Alt+双击、Esc 等。
    3. 集成导出功能，复用现有的 exportAssistantMessageTo* 方法。
    4. 处理会话 DOM 快照保护，避免全屏期间的缓存问题。
    5. 实现智能滚动行为，支持用户手动滚动和自动跟随。
  • 输入区域扩展要点：
    1. 遵循一体化容器设计规范，使用 .input-container 作为统一容器。
    2. 保持紧凑布局原则，合理设置 padding 和 min-height 值。
    3. 实现响应式适配，支持图标模式和完整模式的自动切换。
    4. 使用 CSS Token 确保主题一致性，避免硬编码颜色值。
    5. 测试焦点状态和键盘导航的可访问性。
  • 示例路径（仅路径引用，不含代码内容）：

章节来源