Architecture

架构总览

本页介绍 AI Helper 的整体架构、核心数据流、项目结构、技术栈与状态管理设计，面向准备深入理解或二次开发的读者。

← 返回 Wiki 首页 · 相关内容：核心功能 · 代理服务

---

五层架构

项目采用 五层架构，各层通过 Chrome Extension API 的消息通道通信：

┌──────────────────────────────────────────────────────────────┐
│                   Side Panel (UI 层)                          │
│  side_panel.html + src/side_panel/*.js                        │
│  对话管理 | 多会话标签页 | Markdown/Mermaid 渲染 | 工具面板    │
│  提示词管理 | 划词问答 | 输入历史 | 执行日志 | 澄清/确认对话框 │
│  UI 原型预览 | 质量评估展示 | 消息目录 (TOC) | 会话归档       │
│  多助手管理 | Token 统计面板 | Agent 选择器 | @ Agent/网页切换  │
│  图片识别输入 | 图片标注编辑 | 文件上传提取 | 会话导出/导入    │
│  技能选择器 (Skill Tab) | MCP 服务选择器 (MCP Tab)            │
│  聊天导出 (Word/PDF) | 断点续接 | 消息复制                    │
│  工作目录管理 | 文件预览 | 消息搜索 | 消息收藏                │
└──────────────┬──────────────────────────────┬────────────────┘
               │  chrome.runtime.sendMessage   │
               ▼                               ▼
┌──────────────────────────┐    ┌──────────────────────────────┐
│   Background Service      │    │     Options Page (配置层)      │
│   Worker (核心逻辑层)      │    │  options.html + src/options/   │
│                          │    │  API Key/模型/工具/ReAct参数   │
│  src/background/          │    │  反思系统/对话配置/工具栏      │
│  ├── index.js (消息路由)   │    │  Agent 配对连接管理           │
│  ├── react-loop.js (ReAct) │    │  工具箱 (MCP服务 + Skill管理) │
│  ├── react-reflection.js   │    └──────────────────────────────┘
│  ├── tool-executor.js      │
│  ├── tool-preselector.js   │    ┌──────────────────────────────┐
│  ├── local-agent-client.js │    │   代理服务 (可选层)           │
│  ├── config.js             │    │  agent/ (Node.js 独立进程)    │
│  ├── state.js              │    │  HTTP REST + WebSocket       │
│  ├── agent-dispatcher.js   │    │  文件读写 | 命令执行 | 搜索   │
│  ├── stream-controller.js  │    │  Skill 系统 | MCP 协议扩展   │
│  └── token-recorder.js     │    │  路径沙箱 | 安全分级          │
└──────────────┬─────────────┘    │  文件上传 API                │
               │                   └──────────────────────────────┘
               │  chrome.tabs.sendMessage
               ▼
┌──────────────────────────────────────────────────────────────┐
│              Content Script (页面工具执行层)                    │
│  src/content/*.js (注入到用户浏览网页)                         │
│  ├── index.js (消息路由, 页面工具)                             │
│  ├── page-tools.js (页面内容提取, 无障碍树, Markdown 转换)     │
│  ├── page-interaction.js (可交互元素查询)                      │
│  ├── interaction-tools.js (交互操作, 语音合成, 取色器)         │
│  ├── advanced-tools.js (视频控制, 性能审计, Shadow DOM, 截图)  │
│  ├── shadow-dom-utils.js (Shadow DOM 递归穿透 + iframe)       │
│  └── selection-toolbar.js (划词浮动工具栏)                     │
└──────────────────────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│              Offscreen Document (辅助能力层)                    │
│  src/offscreen/ (剪贴板操作支持)                               │
│  └── offscreen.js (copy/paste_from_clipboard 的 MV3 兼容实现) │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                   Storage (数据持久化层)                        │
│  src/storage/                                                 │
│  ├── db.js (IndexedDB 封装，事务重试、自动迁移、v6 多连接管理) │
│  ├── session-store.js (会话存储适配器)                         │
│  └── token-store.js (Token 统计存储)                          │
└──────────────────────────────────────────────────────────────┘

---

核心数据流

用户输入 → Side Panel (选择 Agent, 可选图片/文件附件, 可选 Skill/MCP, 可选 @网页上下文)
  → chrome.runtime.sendMessage('CALL_API')
    → Background: MCP 工具注入 → 工具预筛选 → ReAct 推理循环
      → Token 预算管理 → 上下文压力监测 → Token 统计记录
      → LLM API 调用 (OpenAI 兼容, 带重试和指数退避, 流式响应 + DeepSeek thinking)
        → 如需工具: 工具确认检查（敏感操作）→ 执行工具
          ├── Background 直接执行（标签页管理、书签搜索等）
          ├── 委派 Content Script（页面交互、内容提取等）
          ├── 委派本地 Agent（文件读写、命令执行、MCP 工具等）
          └── Offscreen 文档（剪贴板读写）
        → 工具级反思 → 结果缓存 → 反馈给 LLM
      → 子任务拆解与并行执行（plan_task 集成，支持 Agent 子任务分派）
      → Checkpoint 断点保存 → 后置反思：多维度质量评估 → 合格/修订/重试
    → chrome.runtime.sendMessage('API_COMPLETE')
    → 任务结果上报 → Background 可见性判定 → 桌面通知（发起任务的侧边栏不可见时弹出）
  → Side Panel: Markdown 渲染, Mermaid 图表渲染, 质量评估展示, Token 统计更新

语音输入链路（旁路，不进推理循环）

侧边栏 🎤 → getUserMedia → AudioWorklet (voice-capture-worklet.js) → 16kHz PCM 分片
  → chrome.runtime.connect({name:'asr'}) 端口
    → Background: 持 Bearer Token 开 WebSocket /ws/asr/:sessionId（侧边栏不碰 token）
      → Agent asr/session.js: 上行 start / audio / stop / cancel
        下行 ready / partial（流式草稿，节流 150ms）/ endpoint / final / error
        → stop 定稿: asr/offline-pool.js 在 worker 线程跑 ONNX 推理
          （不占 Agent 主线程事件循环，会话名额先归还，final 帧稍后补发）
  → Side Panel: 草稿写进输入框，不自动发送

录音条、门控（依赖 × 模型 × 开关）与重采样兜底都在 voice-input.js，不走 CALL_API，因此不会触发工具调用与反思流程。

---

项目结构

ai-helper/
├── agent/                               # 代理服务（Node.js 独立进程）
│   ├── bin/agent.js                     # CLI 启动脚本
│   ├── src/
│   │   ├── server.js                    # HTTP + WebSocket 服务端
│   │   ├── executor.js                  # 命令执行引擎（流式/阻塞）
│   │   ├── security.js                  # 路径沙箱 + 命令安全分级
│   │   ├── config.js                    # Agent 配置（磁盘持久化）
│   │   ├── auth.js                      # 配对认证（6 位动态码）
│   │   ├── search.js                    # 文件/内容搜索（fd/rg 加速）
│   │   ├── logger.js                    # 结构化日志
│   │   ├── trash.js                     # 文件回收站（软删除 + 7 天清理）
│   │   ├── skill/                       # Skill 系统
│   │   ├── mcp/                         # MCP 协议支持
│   │   └── asr/                         # 语音识别（本地 STT）
│   │       ├── routes.js                # /api/asr/* HTTP 端点
│   │       ├── session.js               # WebSocket 会话（/ws/asr/:sessionId）
│   │       ├── engine.js / offline-pool.js / offline-worker.js  # 流式与定稿推理（worker 线程）
│   │       ├── model-pack.js / model-catalog.js / model-download.js  # 模型包校验与下载
│   │       └── detect.js / install.js / config.js  # 依赖检测、安装、配置
│   └── package.json
├── icons/                               # 扩展图标
├── libs/                                # 第三方依赖（CDN/local 引入）
│   ├── marked.min.js                    # Markdown 渲染引擎
│   ├── mermaid.min.js                   # Mermaid 图表渲染引擎
│   ├── qrcode.min.js                    # 二维码生成库
│   ├── pdf.worker.min.js                # PDF.js Worker
│   ├── html2canvas.min.js               # HTML Canvas 截图库
│   ├── jspdf.min.js                     # jsPDF PDF 生成库
│   └── github-markdown-light.min.css    # GitHub 风格 Markdown 样式
├── scripts/                             # 构建工具脚本
│   ├── fix-build.js                     # 修复 @crxjs/vite-plugin 打包产物
│   ├── silent-build.js                  # 静默构建（CI 友好）
│   ├── generate-icons.js                # 图标生成脚本
│   ├── deploy-pages.sh                  # Pages 部署脚本
│   └── split-tools.cjs                  # 工具定义拆分脚本
├── src/
│   ├── background/                      # Background Service Worker（核心逻辑层）
│   │   ├── index.js                     # 入口：消息路由、会话管理、Agent 健康监测
│   │   ├── react-loop.js                # ReAct 推理循环（核心引擎，含三级反思）
│   │   ├── react-reflection.js          # 三级反思系统
│   │   ├── context-summarizer.js        # 上下文增量摘要
│   │   ├── context-compactor.js         # 手动压缩：上下文摘要生成
│   │   ├── tool-executor.js             # 工具注册、执行调度、MCP 动态注入
│   │   ├── tool-preselector.js          # 工具预筛选
│   │   ├── local-agent-client.js        # 本地 Agent HTTP/WebSocket 通信
│   │   ├── agent-dispatcher.js          # Agent 子任务分发器
│   │   ├── stream-controller.js         # 流式响应控制器（SSE + DeepSeek thinking）
│   │   ├── token-recorder.js            # Token 使用统计记录器
│   │   ├── scheduler.js                 # 定时任务调度引擎
│   │   ├── notifier.js                  # 桌面通知中心（完成 / 定时任务 / 交互提醒）
│   │   ├── panel-visibility.js          # 发起实例可见性判定（通知防打扰）
│   │   ├── config.js / state.js         # 配置读写 / 多会话取消控制
│   │   └── tools/                       # 工具定义分目录
│   ├── content/                         # 页面注入脚本（页面工具执行层）
│   │   ├── index.js                     # 入口：消息路由分发
│   │   ├── page-tools.js / page-extract.js
│   │   ├── page-interaction.js / interaction-tools.js
│   │   ├── advanced-tools.js            # 视频、性能审计、Shadow DOM、截图
│   │   ├── shadow-dom-utils.js          # Shadow DOM 递归穿透 + 同源 iframe
│   │   └── selection-toolbar.js         # 划词浮动工具栏
│   ├── offscreen/                       # Offscreen 文档（剪贴板操作）
│   ├── side_panel/                      # 侧边栏 UI（UI 层）
│   │   ├── index.js                     # 入口：事件绑定、配置、快捷键
│   │   ├── chat-manager.js / chat-streaming.js
│   │   ├── chat-panels.js / chat-resume.js / chat-export.js / chat-copy.js
│   │   ├── markdown-render.js / tool-panel.js / prompt-manager.js
│   │   ├── agent-manager.js / agent-store.js / agent-at-selector.js
│   │   ├── page-selector.js / token-stats-panel.js
│   │   ├── session-manager.js / session-manager-ui.js
│   │   ├── clarify-dialog.js / confirm-dialog.js / interaction-gate.js / ui-prototype.js
│   │   ├── message-toc.js / input-history.js / image-preview.js
│   │   ├── file-extract.js / skill-selector.js / export-import.js
│   │   ├── execution-log-render.js / workspace-manager.js / workspace-panel.js
│   │   ├── voice-input.js / voice-capture-worklet.js  # 语音输入：录音、WS 流式、草稿插入
│   │   ├── bookmark-manager.js / bookmark-panel.js / search-panel.js
│   │   ├── schedule-panel.js / context-indicator.js / completion-feedback.js
│   │   └── state.js                     # 全局状态管理（Proxy 双导出模式）
│   ├── options/                         # 扩展选项页（配置层）
│   │   ├── index.js / config-manager.js / config-io.js
│   │   ├── toolbar-config.js / toolbox-config.js / toolbox-shared.js
│   │   ├── toolbox-mcp.js / toolbox-skills.js / toolbox-rag.js
│   │   ├── knowledge-panel.js / save-bar.js / constants.js
│   ├── storage/                         # IndexedDB 持久化层
│   │   ├── db.js / session-store.js / token-store.js
│   ├── config/constants.js              # Storage 键名、消息类型等
│   └── shared/                          # 共享模块
│       ├── tools.js                     # 工具分类、温度预设
│       ├── utils.js / token-counter.js / logger.js
│       └── agent-defaults.js            # 内置 Agent 定义和模板
├── manifest.json                        # Chrome 扩展配置（Manifest V3）
├── side_panel.html                      # 侧边栏 HTML
├── options.html                         # 选项页 HTML
├── vite.config.js / package.json
└── README.md

---

技术栈

技术	说明
Vite + @crxjs/vite-plugin	构建工具链，ES Module，开发 HMR
Manifest V3	最新 Chrome 扩展协议
Service Worker	后台进程，API 调用和工具执行
Side Panel API	Chrome 114+ 侧边栏
Content Script	页面注入，DOM 操作
Offscreen Document	MV3 剪贴板操作兼容层
IndexedDB	会话 / 原型 / Token 统计 / 收藏 / 定时任务持久化
chrome.storage.local	配置存储、Agent 定义存储
chrome.storage.session	跨重启消息恢复、后台任务持久化
chrome.debugger API	CDP 截图 / PDF 导出 / 高级页面调试
OpenAI Compatible API	LLM 调用（含 Vision），默认 DeepSeek V4，支持流式响应
marked.js	Markdown 渲染引擎
mermaid.js	图表渲染引擎
QRCode.js	二维码生成（Canvas 降级）
pdfjs-dist	PDF 文件文本提取
mammoth.js	Word .docx 文件文本提取
SheetJS (xlsx)	Excel .xlsx/.xls 文件文本提取
Web Speech API	文本语音合成
EyeDropper API	取色器
Navigation / Performance API	性能审计
Node.js (Agent)	本地文件 / 命令服务、Skill 系统、MCP 协议、本地知识库（RAG）
WebSocket (Agent)	命令输出实时流
MCP Protocol	Model Context Protocol，扩展第三方工具

---

状态管理设计

双导出 Proxy 模式

src/side_panel/state.js 采用独特的双导出 Proxy 模式：

// 两种导入方式指向同一数据
import state from './state.js';              // state.messageHistory
import { messageHistory } from './state.js'; // 直接解构

通过 Proxy 的 getter / setter 代理到顶层 let 绑定，确保所有模块共享同一份状态，无需引入任何框架。支持 80+ 个状态字段，包括图片输入、文件附件、技能选择、MCP 服务选择等。

数据持久化策略

数据类型	存储位置	说明
扩展配置	chrome.storage.local	API Key、ReAct 参数、模型、图片识别等
对话会话	IndexedDB (ai-helper-db)	活跃会话 + 归档会话
UI 原型	IndexedDB	按会话关联
工具栏配置	chrome.storage.local	工具列表、排序、域名屏蔽
输入历史	chrome.storage.local	去重自动管理
跨重启消息	chrome.storage.session	SW 重启恢复、后台任务持久化

IndexedDB 数据库设计

ai-helper-db (v6)，八个对象存储：

Store	用途
sessions	活跃会话（索引：updatedAt）
activeSession	当前活跃会话 ID
archivedSessions	已归档会话（索引：createdAt）
uiPrototypes	UI 原型（索引：createdAt, sessionId）
tokenStats	Token 使用统计（索引：timestamp, sessionId）
reactCheckpoints	ReAct Checkpoint 断点（索引：updatedAt；7 天 TTL 自动过期）
bookmarks	消息收藏（索引：sessionId, createdAt）
scheduledTasks	定时任务（索引：nextRunAt, enabled）

支持自动从事务失败恢复及旧版 chrome.storage.local 自动迁移。

---

设计要点

• 无框架 UI：侧边栏与选项页均为原生 JS + Proxy 状态管理，包体小、启动快。
• MV3 兼容：通过 Offscreen Document 解决 MV3 下剪贴板 API 不可用的问题；通过 Keepalive 端口监测 Service Worker 静默重启并自动恢复。
• 健壮性：工具执行、API 调用均带超时、重试与取消控制；后台任务状态持久化到 chrome.storage.session。
• 可扩展：工具定义分目录组织，MCP 工具动态注入，Skill 系统支持热插拔。