技术拆解-AI可视增强分析助手

内容为 AI 基于AI 可视增强分析助手的源码生成。

AI 可视增强分析助手 - 完整项目架构文档

经验教训

明确定义接口并提前编写好单元测试

这次联调测试接口，耗费的时间太长了。

单元测试这个，得搞成基建，合作型项目太重要了。

比如我让 AI 写的整理博客的代码，就是测试先行，能大幅度提升整体的开发效率和确定性。

POC 项目技术架构越简单越好，别尝试新技术

比如这次的 POC 项目，后端尝试了使用 Spring AI，根本没必要。
写 Chrome 插件其实也没啥必要。
Next.js 全栈直接搞定。这个得沉淀下，搞成基建，保证下次没新东西需要琢磨，技术上全部都是确定性的内容。

别搞一些耗时太长的内容

比如故事线，耗费了大量时间在这个组件上，性价比不高。

坐一起能极大提升效率

这种项目，沟通讨论的频率极高，坐一起能极大提升效率。

后端接口做好 mock 数据

特别是模型的输出接口，巨慢无比，开发阶段不 mock，调试前端效率极低！

逻辑和数据请求写在 content script 中

content script 负责逻辑和数据请求，background script 只负责消息转发。

这样能保证控制台和 network 能很方便的查看和调试你的程序，提升开发效率。

🎯 项目概述

AI 可视增强分析助手是一个智能的 Chrome 浏览器扩展项目，专注于网页文本的智能分析和可视化增强。该项目通过选中网页文本，自动调用后端 AI 服务，生成多种形式的可视化内容，为用户提供无缝的网页阅读和分析体验。

系统组成

  • 前端: Chrome 浏览器扩展，基于 React + TypeScript + Vite 构建
  • 后端: 独立的 AI 可视化服务（单独项目，本文档专注前端部分）

核心能力

  • 🧠 智能文本选择: 自动识别网页文本选择，触发分析工具栏
  • 📊 多样化可视化: 支持图表、思维导图、NTV 富文本、故事线、金融拓展等多种形式
  • 🔄 实时流式处理: 提供实时的 AI 分析反馈和工具执行状态
  • 🌐 无缝网页集成: 与任意网页内容无缝集成的用户体验
  • 🎯 高亮交互: 支持可视化结果的智能高亮和关联显示

🏗️ Chrome 扩展架构

前端架构图

graph TB
    subgraph "网页环境"
        WP[网页内容]
        SEL[文本选择]
    end

    subgraph "Content Scripts"
        CU[content-ui]
        TB[ToolBar组件]
        CS[content script]
    end

    subgraph "Chrome扩展核心"
        BG[Background Script]
        SP[Side Panel]
        PU[Popup界面]
    end

    subgraph "Side Panel主界面"
        AP[Analysis Panel]
        SR[Stream Request]
        AM[Answer Message]
        QM[Query Message]
        TM[Tools Message]
    end

    subgraph "可视化渲染层"
        RI[Renderer Item]
        CR[Chart Renderer]
        NR[NTV Renderer]
        MR[Mermaid Renderer]
        STR[Storyline Renderer]
        TIR[TextInfo Renderer]
        HR[HTML Renderer]
    end

    subgraph "后端AI服务"
        API[AI分析API]
        TOOL[工具执行API]
        HIGH[高亮API]
    end

    WP --> SEL
    SEL --> CU
    CU --> TB
    TB --> BG
    BG --> SP
    SP --> AP
    AP --> SR
    SR --> API
    API --> AM
    AM --> RI
    RI --> CR
    RI --> NR
    RI --> MR
    RI --> STR
    RI --> TIR
    RI --> HR

    AP --> TOOL
    AP --> HIGH

技术栈详情

层级 技术选择 版本信息
核心框架 React + TypeScript React 19.1.0
构建工具 Vite + Turbo + pnpm Vite 7.0.3
开发语言 TypeScript 5.8.3
可视化库 @antv/ava-react, AIGCDataVis @antv/ava-react 3.3.2
HTTP 客户端 axios + 流式请求处理 axios 1.10.0
UI 框架 Antd + Tailwind CSS 最新版本
包管理 pnpm workspace + turbo pnpm 10.11.0
代码质量 ESLint + Prettier + Husky 最新版本

🚀 前端架构详解

Chrome 扩展项目结构

实际项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
ai-vis-analyzer/
├── chrome-extension/           # 扩展配置和清单
│   ├── manifest.ts            # 扩展清单配置
│   └── src/background/        # 后台脚本
├── pages/                     # 扩展页面组件
│   ├── content-ui/            # 网页内容交互UI
│   │   └── src/matches/all/
│   │       ├── App.tsx        # 文本选择监听主组件
│   │       └── ToolBar.tsx    # 浮动分析工具栏
│   ├── side-panel/            # 主分析界面
│   │   └── src/
│   │       ├── components/
│   │       │   ├── analysis-panel/  # 分析面板核心
│   │       │   ├── base-visual-item/ # 可视化组件库
│   │       │   └── rendererItem/    # 渲染器分发
│   │       └── lib/
│   │           ├── streamRequest.ts  # 流式请求处理
│   │           └── analyzeChat.ts   # AI对话分析
│   ├── popup/                 # 扩展弹窗界面
│   ├── content/               # 内容脚本
│   ├── devtools/              # 开发者工具
│   └── options/               # 设置页面
└── packages/                  # 共享包系统
    ├── shared/                # 通用工具和组件
    ├── ui/                    # UI组件库
    ├── storage/               # 存储系统
    ├── i18n/                  # 国际化支持
    ├── hmr/                   # 热更新
    ├── dev-utils/             # 开发工具
    ├── vite-config/           # Vite配置
    └── zipper/                # 打包工具

核心业务流程

flowchart TD
    A[用户在网页选择文本] --> B[content-ui/App.tsx监听mouseup事件]
    B --> C{文本是否选中?}
    C -->|是| D[显示ToolBar浮动工具栏]
    C -->|否| E[隐藏工具栏]
    D --> F[用户配置分析选项]
    F --> G[点击增强分析按钮]
    G --> H[chrome.runtime.sendMessage发送消息]
    H --> I[background script接收并转发]
    I --> J[side-panel打开并接收消息]
    J --> K[AnalysisPanel设置query并开始分析]
    K --> L[StreamRequest发起流式请求]

    subgraph "AI分析阶段"
        L --> M[thinking阶段: 流式思考过程]
        M --> N[tools阶段: 工具选择分析]
        N --> O[execute阶段: 并行执行多个工具]
    end

    O --> P[解析工具执行结果]
    P --> Q[RendererItem分发到具体渲染器]
    Q --> R[显示最终可视化结果]

    subgraph "高亮交互"
        R --> S[用户选择可视化内容]
        S --> T[发送高亮请求]
        T --> U[更新相关可视化高亮状态]
    end

消息传递机制

sequenceDiagram
    participant User as 用户
    participant ContentUI as content-ui/App.tsx
    participant ToolBar as ToolBar组件
    participant Background as Background Script
    participant SidePanel as Analysis Panel
    participant Backend as 后端AI服务

    User->>ContentUI: 选择网页文本
    ContentUI->>ContentUI: handleSelection()触发
    ContentUI->>ToolBar: 显示浮动工具栏
    User->>ToolBar: 配置分析选项并点击增强分析
    ToolBar->>Background: chrome.runtime.sendMessage(OPEN_SIDE_PANEL)
    Background->>SidePanel: 转发消息和选中文本
    SidePanel->>SidePanel: 接收消息设置query

    Note over SidePanel,Backend: 三阶段AI分析流程
    SidePanel->>Backend: StreamRequest(chat) - thinking阶段
    Backend-->>SidePanel: 流式返回思考过程
    SidePanel->>Backend: StreamRequest(analyze_tools) - tools阶段
    Backend-->>SidePanel: 返回工具选择结果
    SidePanel->>Backend: executeTool() - execute阶段
    Backend-->>SidePanel: 并行执行多个工具返回结果

    SidePanel->>SidePanel: 解析并渲染可视化结果
    Note over User,SidePanel: 高亮交互功能
    User->>SidePanel: 选择可视化内容文本
    SidePanel->>Backend: highlightTool()请求
    Backend-->>SidePanel: 返回高亮关联信息
    SidePanel->>User: 更新界面高亮显示

前端核心功能模块

1. Content-UI 模块 (文本选择监听)

核心文件: pages/content-ui/src/matches/all/App.tsx

主要功能:

  • 监听网页文本选择事件 (mouseup)
  • 计算浮动工具栏位置
  • 管理选中文本状态

关键实现:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const handleSelection = () => {
  const selection = window.getSelection();
  if (!selection || selection.isCollapsed) {
    setActivated(false);
    return;
  }

  const text = selection.toString();
  const range = selection.getRangeAt(0);
  const rect = range.getBoundingClientRect();

  setSelectedText(text);
  setActivated(true);
  setPosition({
    top: rect.top - 50 + window.scrollY,
    left: rect.left + window.scrollX,
  });
};

2. ToolBar 模块 (分析配置工具栏)

核心文件: pages/content-ui/src/matches/all/ToolBar.tsx

支持的工具选项:

  • 思维导图 (mermaid): 结构化图表生成
  • 故事线 (storyTelling): 时间线可视化
  • 数值增强 (generateNTV): NTV 富文本格式
  • 问句可视化 (queryToVis): 查询结果图表
  • 数据可视化 (dataToVis): 数据图表生成
  • 文生卡片 (textToCard): 信息卡片展示
  • 金融拓展 (FinancialRAG): 金融领域增强

消息发送机制:

1
2
3
4
5
6
7
8
9
10
const handleEnhanceClick = () => {
  chrome?.runtime?.sendMessage({
    type: 'OPEN_SIDE_PANEL',
    text: selectedText,
    config: {
      intent: selectedKnowledge, // 知识库选择
      tools: selectedEnhancements, // 工具选择
    },
  });
};

3. Analysis Panel 模块 (主分析界面)

核心文件: pages/side-panel/src/components/analysis-panel/index.tsx

核心功能特性:

  • 三阶段分析流程: thinking → tools → execute
  • 实时状态管理: 加载状态、步骤状态、工具执行状态
  • 高亮交互: 支持选中文本的智能高亮显示
  • 防抖处理: 300ms 防抖延迟优化用户体验

可视化类型接口:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
export interface IVisualization {
  toolId: string;
  type:
    | 'chart'
    | 'table'
    | 'text'
    | 'custom'
    | 'nvt'
    | 'mermaid'
    | 'thinking'
    | 'textToCard'
    | 'storyline'
    | 'financialRag';
  config?: unknown;
  data?: unknown;
  insights?: string[];
  confidence?: number;
}

4. 可视化渲染系统

核心文件: pages/side-panel/src/components/rendererItem/index.tsx

渲染器架构:

graph TD
    subgraph "渲染分发层"
        RI[RendererItem]
    end

    subgraph "具体渲染器实现"
        CR[ChartRenderer]
        NR[NvtRenderer]
        MR[MermaidRenderer]
        STR[StorylineRenderer]
        TIR[TextInfoRenderer]
        CTR[ChatThinking]
        HR[HtmlRenderer]
    end

    subgraph "外部可视化库"
        AIGC[AIGCDataVis]
        AVA[@antv/ava-react]
        MERM[mermaid]
    end

    RI --> CR
    RI --> NR
    RI --> MR
    RI --> STR
    RI --> TIR
    RI --> CTR
    RI --> HR

    CR --> AIGC
    NR --> AVA
    MR --> MERM

支持的可视化类型:

类型 渲染器 功能描述 外部依赖
chart ChartRenderer 数据图表渲染 AIGCDataVis
nvt NvtRenderer NTV 富文本显示 @antv/ava-react
mermaid MermaidRenderer 流程图、思维导图 mermaid
storyline StorylineRenderer 故事线时间轴 自定义实现
textToCard TextInfoRenderer 信息卡片展示 自定义实现
financialRag HtmlRenderer 金融扩展内容 HTML 渲染
thinking ChatThinking AI 思考过程 自定义实现

渲染器选择逻辑:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
const RendererItem = ({ type, data }: RendererItemProps) => {
  switch (type) {
    case 'chart':
      return <ChartRenderer option={data} />;
    case 'nvt':
      return <NvtRenderer spec={data as NarrativeTextSpec} />;
    case 'mermaid':
      return <MermaidRenderer data={data as string} />;
    case 'storyline':
      return <StorylineRenderer data={data as StoryData} />;
    case 'textToCard':
      return <TextInformationVisualRenderer data={data as string} />;
    case 'financialRag':
      return <HtmlRenderer html={data as string} />;
    case 'thinking':
      return <ChatThinking data={data} />;
    default:
      return null;
  }
};

5. 流式请求处理系统

核心文件: pages/side-panel/src/lib/streamRequest.ts

主要特性:

  • 基于 @microsoft/fetch-event-source 实现
  • 支持自定义回调函数 (start, success, error, close)
  • 自动 JSON 解析处理
  • 支持流式和非流式响应

关键实现:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
class StreamRequest {
  startRequest(url: string, params: Record<string, unknown>) {
    fetchEventSource(url, {
      method: this._method,
      headers: this._headers,
      body: JSON.stringify(params),
      onmessage: (event) => {
        if (this._isParse && isJSON(event.data)) {
          const data = JSON.parse(event.data);
          this.successHandler(data);
        } else {
          this.successHandler(event.data);
        }
      },
      onopen: this.startHandler,
      onerror: this.errorHandler,
      onclose: this.closeHandler,
    });
  }
}

前端存储和状态管理

Chrome 扩展存储系统

核心文件: packages/storage/lib/base/base.ts

主要特性:

  • 支持 Chrome Local Storage 和 Session Storage
  • 实时状态同步 (liveUpdate)
  • 自动序列化/反序列化
  • React hooks 集成 (useStorage)

存储类型配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 支持的存储类型
enum StorageEnum {
  Local = 'local',
  Session = 'session',
}

// 创建存储实例
const storage = createStorage<ThemeStateType>(
  'theme-storage-key',
  { theme: 'light', isLight: true },
  {
    storageEnum: StorageEnum.Local,
    liveUpdate: true,
  }
);

React 状态集成:

1
2
// 在组件中使用存储
const [data, setData] = useStorage(storage);

状态管理架构

主要状态类型:

  • 聊天历史: 用户查询、AI 响应、工具执行状态
  • 可视化结果: 按会话 ID 组织的可视化数据映射
  • 高亮状态: 当前高亮的工具 ID 列表
  • UI 状态: 加载状态、步骤状态、折叠状态

状态更新模式:

1
2
3
4
5
6
7
8
9
10
11
12
13
// 会话ID到可视化数据的映射
const [sessionIdAndVisualizationMap, setSessionIdAndVisualizationMap] =
  useState<Record<string, IVisualization[]>>({});

// 会话ID到文本工具映射
const [sessionIdAndTextToolMap, setSessionIdAndTextToolMap] = useState<
  Record<string, ITextAndTool[]>
>({});

// 高亮工具列表
const [highlightToolList, setHighlightToolList] = useState<
  { toolId: string; insight?: unknown[] }[]
>([]);

📡 API 接口集成

后端服务端点

实际 API 地址: https://rtahz.10jqka.com.cn/new-vis-server/

主要接口:

端点 功能 用途
/agent/chat AI 对话分析 thinking 阶段流式思考
/agent/analyze_tools 工具分析 tools 阶段识别需要的工具
/agent/tool_execute 工具执行 execute 阶段并行执行工具
/vis/vis_highlight 高亮分析 可视化内容关联高亮

请求配置:

1
2
3
4
5
6
7
8
9
// axios客户端配置
const apiClient = axios.create({
  baseURL: '', // 由具体请求URL指定
  timeout: 600000, // 10分钟超时
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`, // Bearer token认证
  },
});

流式请求处理流程

三阶段处理模式:

  1. Thinking 阶段 (/agent/chat):

    • 流式返回 AI 思考过程
    • 实时更新思考内容到界面
    • 完成后触发 tools 阶段

  2. Tools 阶段 (/agent/analyze_tools):

    • 分析并返回需要执行的工具列表
    • 解析工具调用参数
    • 准备并行执行

  3. Execute 阶段 (/agent/tool_execute):

    • 并行执行多个工具
    • 实时更新工具执行状态
    • 解析并渲染可视化结果

🎨 用户交互体验

完整用户流程

journey
    title AI可视增强分析用户体验流程
    section 文本选择
      用户浏览网页: 5: 用户
      选中感兴趣文本: 5: 用户
      浮动工具栏出现: 4: 系统
    section 分析配置
      选择知识库类型: 4: 用户
      配置分析工具: 4: 用户
      点击增强分析: 5: 用户
    section AI分析过程
      side-panel打开: 4: 系统
      显示思考过程: 3: 系统
      工具选择分析: 3: 系统
      并行执行工具: 2: 系统
    section 结果展示
      可视化结果渲染: 5: 系统
      高亮交互支持: 4: 系统
      用户查看分析: 5: 用户