AIChat聊天助手：把 AI 助手“嵌进”你的业务系统——流式对话、上下文引用与可扩展消息卡片的一站式组件

六月的可乐
0 阅读7分钟

AIChat聊天助手：把 AI 助手“嵌进”你的业务系统——流式对话、上下文引用与可扩展消息卡片的一站式组件

关键词：AI 聊天组件、悬浮球 AI 助手、Vue ChatPanel、SSE 流式响应、上下文引用、AI 消息插入编辑器、Markdown 自定义组件渲染、语音输入、语音播报、对话历史管理

在企业后台、在线编辑器、简历/招聘系统、内容生产平台这类“用户边做边问”的产品里，AI 能力的落地往往卡在两点：

  • 体验复杂度：流式输出、停止生成、历史记录、主题、移动端适配、语音/图片等多模态交互。
  • 业务耦合度：AI 输出要能“回写”到业务（插入编辑器/表单），复杂信息要能用结构化 UI 呈现（卡片/轮播/二维码），无法解决的问题要能进入人工闭环（工单）。

ai-suspended-ball-chat 的目标是把这套“产品级 AI 交互底座”封装成一套可配置组件：

  • SuspendedBallChat：悬浮球形态，全站随处唤起。
  • ChatPanel：独立面板形态，适合工作台/侧栏固定区域集成。

先看效果图（图）

AI Suspended Ball Chat UI

一句话定位：它不是“聊天 UI”，而是 AI 产品交互底座

很多团队一开始会把 AI 助手理解成“一个对话框”。但真实落地时，成本大头不在输入输出，而在“围绕对话的产品能力”：

  • 请求体验：普通请求与 SSE 流式输出并存，支持停止生成。
  • 会话管理：对话历史本地存储、最大条数、清空与状态获取。
  • 多模态交互：图片上传、语音输入、语音播报。
  • 业务联动：把 AI 回复内容插入到业务编辑器；工单提交进入人工闭环。
  • 结构化呈现：在 Markdown 对话流里渲染卡片/轮播/二维码等自定义组件。

这就是为什么它更像一套“AI 交互基础设施”，而不是单纯的 Chat UI。

核心特色

  • 双模式请求：普通 JSON 与 SSE 流式响应（enable-streaming）。
  • 上下文引用：支持引用页面中（或上传）的文本作为对话上下文（supported-custom-context / enable-context）。
  • 历史记录管理：本地存储、最大条数控制（enable-local-storage / max-history-count）。
  • 语音与多模态：语音输入、语音播报、图片上传（可配置开关）。
  • 获取 AI 消息（回写业务）：把 AI 回复插入到你的编辑器/表单/应用（enable-insert-message + clickAssistantMsgCallback）。
  • 工单反馈闭环：遇到 AI 无法解决的问题，用户可直接提交工单（show-feedback-button + onFeedbackSubmit）。
  • 对话流自定义组件渲染：Markdown 占位符 + 后端下发配置，实现“对话 + 卡片/轮播/二维码”的混合表达。
  • 高可配置 + TypeScript 类型完善：适配不同业务风格与接口协议。

架构设计（图）：三层分离 + 多扩展点

不谈实现细节，从概念架构看，它把 AI 助手拆成三层：展示层、会话编排层、连接器层。这样做的目的，是让你用 配置与回调就能完成业务适配。

flowchart TB
  U[用户] -->|点击悬浮球/打开面板| UI[UI 展示层\nSuspendedBallChat / ChatPanel]
  UI -->|输入文本/语音/图片| Orchestrator[会话编排层\n消息队列/流式状态/历史存储/上下文引用]
  Orchestrator -->|普通请求/流式 SSE| Connector[连接器层\n请求封装/协议适配\ncustom-request-config]
  Connector --> Backend[你的后端 / 网关 / 模型服务]

  Backend -->|JSON 或 SSE 数据块| Connector
  Connector --> Orchestrator
  Orchestrator -->|渲染 Markdown + 自定义组件| UI

  Orchestrator -->|callbacks 事件| Biz[业务侧\n埋点/权限/审计/工单系统/编辑器回写]
  • 展示层：承载入口形态（悬浮球/面板）、主题样式与响应式交互。
  • 会话编排层：管理消息、流式生命周期、历史记录、上下文引用等“产品能力”。
  • 连接器层：对齐普通 JSON 与 SSE 协议，通过 custom-request-config 适配鉴权、header、参数加工。

流式对话链路（图）：SSE 增量输出如何形成“可感知的生成体验”

你不需要在前端重复造“打字机 + 结束标识 + 停止按钮”这套机制，组件把它抽象成统一能力。对后端要求是：持续发送 JSON 数据块，以 \n\n 分隔，并用 is_end 告知结束。

sequenceDiagram
  autonumber
  participant User as 用户
  participant UI as 组件 UI
  participant API as 后端接口

  User->>UI: 发送消息
  UI->>API: 发起请求（enable-streaming=true）
  API-->>UI: data: {code:0,result:"...",is_end:false}
  UI-->>User: 增量渲染（流式输出中）
  API-->>UI: data: {code:0,result:"...",is_end:false}
  UI-->>User: 持续追加渲染
  API-->>UI: data: {code:0,result:"",is_end:true}
  UI-->>User: 结束态（可播报/可插入/可反馈）

结构化消息呈现（图）：在 Markdown 中渲染“卡片/轮播/二维码”等自定义组件

现实业务中，“长回答”经常带来阅读负担，而结构化 UI 能把关键信息变成可点击、可跳转、可复用的操作入口。

组件支持一种占位符语法：在 Markdown 正文里写 [[~n]]，同时后端下发编号 n 对应的组件配置（流式或非流式都支持）。

flowchart LR
  M["Markdown 文本<br/>这里是正文... [[~1]] ... [[~2]]"] --> P["占位符解析<br/>定位挂载点"]
  C["customComponents 配置<br/>或 SSE custom-component 数据块"] --> B["组件工厂/渲染器"]
  P --> R["渲染结果：<br/>正文 + 卡片/轮播/二维码等"]
  B --> R

适合的业务表达：

  • 推荐列表（产品/课程/文章/招聘岗位）用卡片呈现，点击直达。
  • 图片对比（前后效果、压缩对比、修复对比）用图片对比组件呈现。
  • 多张图/多步骤引导用轮播呈现。
  • 二维码把结果“投送”到移动端或企业微信。 在这里插入图片描述

两种入口形态（图）：悬浮球 vs 面板

同一套能力，提供不同入口形态，解决“全站可用”和“工作台固定承载”的产品差异。

flowchart TB
  subgraph Entry[入口形态]
    A[ SuspendedBallChat\n悬浮球：随处唤起 ]
    B[ ChatPanel\n面板：固定区域承载 ]
  end

  A --> S[同一套会话能力\n流式/历史/上下文/多模态/回调]
  B --> S

业务场景案例（图文结合）

场景 1：AI 简历助手（信息密集型表单）

问题本质：用户在填写“项目经历/技能描述/自我评价”时，需要即时润色与结构化建议。

组件价值点：

  • 上下文引用：把当前页面已填写内容作为上下文，提高回答贴合度。
  • 回写能力：用户一键把 AI 回复插入到对应表单项。
  • 工单闭环：遇到合规/敏感/个性化强的问题，直接提交人工工单。
flowchart LR
  F[简历表单输入] -->|引用上下文| AI[AI 对话组件]
  AI --> R[生成：要点 + 改写建议]
  R -->|插入| F
  R -->|不满意/需人工| T[工单提交]

图（体验链接）：

体验地址: luckycola.com.cn/public/resu…

在这里插入图片描述

场景 2：AI 编程助手（在线编辑器/IDE 类 Web 应用）

问题本质：用户需要“边写边问”，最怕等待、最需要可直接落地的代码/解释/链接。

组件价值点：

  • SSE 流式输出：降低等待焦虑，增强生成可感知性。
  • 消息插入编辑器：把 AI 回复直接写回代码区，提升闭环效率。
  • 结构化组件渲染：用卡片/轮播呈现参考链接、依赖建议、可复用片段。

图（体验链接）：

体验地址: luckycola.com.cn/public/dist…

在这里插入图片描述

场景 3：运营/内容生产（图文混排、多模态）

  • 图片上传：生成标题/摘要/标签/脚本，或识别图中信息。
  • 语音输入：移动端口述需求更高效。
  • 主题/样式自定义：用 CSS 变量快速贴合品牌后台。

这类场景最重要的是“降低输入成本”和“提升输出可用性”。

落地建议：先跑通闭环，再做体验增强

  • 第 1 阶段（MVP）

    • 普通 JSON 请求
    • 开启本地历史（避免刷新丢失）
    • 接上 callbacks 做埋点与错误监控

  • 第 2 阶段（体验升级）

    • 切换 SSE 流式
    • 增加停止生成、错误码映射与重试策略
    • 增加语音/图片（按业务开关）

  • 第 3 阶段（业务表达能力）

    • 上下文引用（页面内容/文件）
    • 自定义组件渲染（把关键行动点结构化）
    • 工单反馈闭环（AI 不确定时转人工）

性能与工程化：包体积与加载时机要提前规划

由于组件支持代码高亮、数学公式等能力，包体积可能偏大。推荐按需加载（动态导入/路由懒加载/Suspense/工厂函数模式），把组件的加载时机放到“用户真的需要 AI 助手”的那一刻。

适用边界：什么时候推荐使用它

  • 推荐

    • 需要“可嵌入、可配置、可扩展”的 AI 助手入口
    • 强依赖流式输出、历史管理、多模态与业务闭环
    • 希望用协议对齐任意模型服务，而不是绑定单一平台

  • 不太适合

    • 只要一个极简对话框、且不需要流式/历史/扩展渲染
    • 完全不接受样式覆盖/变量方案，要求深度重做 UI 体系

结语：把 AI 体验沉淀成“组件资产”，而不是“项目负担”

ai-suspended-ball-chat 的核心价值不在“能聊天”，而在于把 AI 产品化过程中最容易重复造轮子的部分沉淀下来：

  • 体验层：流式、语音、图片、主题、响应式
  • 状态层：历史与会话管理、可停止与可恢复
  • 业务层：插入消息、工单闭环、结构化卡片渲染
  • 工程层：TS 类型、可配置回调、按需加载建议与版本差异说明

如果你要在多个业务线推广 AI 助手入口，把它作为“统一 AI 交互底座”会更可控：体验一致、协议一致、扩展一致，后续迭代也更像升级基础设施，而不是到处救火。

avatar
文章
阅读
粉丝