@fv-ui/ai-chat

@fv-ui/ai-chat

基于 Vue 3 + Element Plus 的 AI 对话组件库,复刻 element-plus-x 与 open-webui 对话框:从底层气泡、发送框、Markdown 渲染,到上层的对话整框(<FvAiChat>)、分支树消息、Artifacts 预览,一次给全。

• 14 个基础组件(Bubble/Sender/Markdown/Thinking/...)自由拼装
• 对话应用层整框 <FvAiChat>:顶栏模型多选、消息列表、分支切换、Artifacts 面板、发送停止一体化
• 树形消息模型(同构 open-webui):一条提问可挂多个模型回答,分支可切换、可重生成
• ChatAdapter 适配器协议:内置 OpenAI 兼容实现,可替换自研后端/Ollama
• 流式打字机、思考链折叠、KaTeX/代码高亮(Prism)开箱即用

安装

pnpm add @fv-ui/ai-chat

peerDependencies:vue ^3.4.0、element-plus ^2.7.0、@element-plus/icons-vue ^2.3.0。

快速开始

// main.ts —— 需要先引入 element-plus(组件库依赖其组件与暗色变量)
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).use(ElementPlus).mount('#app')

<!-- App.vue -->
<script setup lang="ts">
import { FvAiChat } from '@fv-ui/ai-chat'
import '@fv-ui/ai-chat/dist/style.css'
</script>

<template>
  <FvAiChat
    title="AI 助手"
    base-url="https://api.deepseek.com/v1"
    api-key="sk-xxx"
    model="deepseek-chat"
    style="height: 600px"
  />
</template>

<FvAiChat> 未传 adapter 时,用 baseURL/apiKey/model 构造内置 OpenAIAdapter(走 /chat/completions,SSE 流式)。两个都缺省时发送会报"未配置 adapter 或 baseURL"。

Vite 项目必读:排除依赖预打包

内置头像/欢迎页 GIF 在 es 产物中以 new URL(..., import.meta.url) 按需引用。Vite dev server 默认把依赖交给 esbuild 预打包(optimizeDeps),而预打包不会复制该类资产——GIF 404 不显示(已知限制 vitejs/vite#8427)。需在 vite.config.ts 排除预打包,让本包走源码 ESM 管线:

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    // @fv-ui/ai-chat:es 产物内置 GIF 以 new URL(..., import.meta.url) 引用,
    // esbuild 预打包不复制该类资产(vitejs/vite#8427),须排除预打包走源码 ESM 管线
    exclude: ['@fv-ui/ai-chat']
  }
})

说明:仅 Vite dev 需要;生产 build 走 Rollup 管线会自动把 GIF 复制进产物并重写路径,不受影响。UMD(<script> 直用 lib/index.js)不涉及。

基础组件层 API

FvMarkdown

Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。

Typewriter

打字机输出,支持续打/重打/雾化遮罩。

Bubble

单条气泡(内部按需挂载 Typewriter/Markdown)。

BubbleList

气泡列表 + 吸底/回底按钮。

Sender

输入发送框。

MentionSender

带 @提及 的 Sender(键盘 ↑↓ 导航 / Enter 确认 / Esc 关闭)。

事件:update:modelValue / change / submit / cancel / trigger / recording-change / paste-file / update:triggerPopoverVisible / show-at-dialog(弹层显隐);其余 props/事件经 $attrs 透传给 Sender,slot 经 forwardedSlots 显式转发(header/footer/prefix/action-list/trigger)。

EditorSender

富文本标签编辑器(contenteditable),open-webui 风格标签芯片。

Thinking

思考链折叠面板。

ThoughtChain

思维链步骤条。text 步(kind: 'text')为「正在思考/思考完成」标题行 + 可折叠 description 滚动区(默认收起;展开时 ElScrollbar 限高 269px,流式期间自动滚底;内容被滚动裁掉的方向在上/下缘渲染 35px 渐隐条 scroll-edge-fade-top / scroll-edge-fade-bottom,贴顶/贴底各自隐藏);工具步 kind: 'tool' 为普通步骤行。

Welcome

空态欢迎页。icon/name/description 均未传时显示内置品牌默认欢迎(「你好，我是 Gizmo」问候高亮 + IP 形象动图 + 默认描述),逐 prop 独立覆盖。

结构:图标区(DOM 序在前)+ 主列(.fv-welcome-main:文案列 + 建议区);纵排图标居中显示在文案上方;横排主列为唯一文档流内容(左对齐),吉祥物浮层悬于文案右上(经 flex order 排到主列右侧)——建议区与文案同列,不会把吉祥物顶高。

CSS 变量

Prompts

建议 prompt 网格。

FilesCard

单个文件卡片。文档模式按扩展名自动映射设计稿类型图标(f-*.svg):xlsx/xls/csv 等表格→excel、pdf→pdf、pptx/ppt→ppt、docx/doc/wps→word、txt/md/json/log 等文本→txt,未命中回落通用 file 图标;图标 fill=currentColor 随主题色走。

Attachments

附件选择与列表(v-model)。

Conversations

会话列表(按 group 分组)。

FvBlobHalo

blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内联 SVG 8 个 blob(每色一组正体 + alt 淡体),path 以 d: path() 关键帧在形状配方间连续变形(蠕变),每个色团各自异速旋转,全部居中叠放:中心混色、随转动流动;第 4 槽位是高光位(fill 走径向渐变,中心实色 → 向外透明渐大,模拟高光柔光)。FvAiChatLauncher 内嵌同款效果;亦可独立用在任意需要氛围光的场景(装饰背景、头像/卡片区光效等)。无定位(inline-flex 占位,pointer-events: none),挂载位置与层叠由使用方决定。

<FvBlobHalo :size="88" :opacity="0.8" :colors="['#ff8c42', '#fcaf58', '#f9c784', '#ffffff']" />

说明:

• 第 4 槽位为「高光位」:fill 用径向渐变(中心 100% 实色 → 半径 50% 处浓度 mid(默认 .45)→ 边缘全透明),自带「中心实、向外透明渐大」的高光过渡;mid 越小淡出越快;其余槽位彩团平涂色 + blur(叠色饱满)
• 色板槽位有内置「角色」:第 1 色大清晰(主题位,scale .8)、第 2/3 色更小更快(辅色位,.78/.76)、第 4 色即高光位(.62);槽位对象 scale 可按色覆盖缩放
• 按色调透明度/缩放::colors="[null, { color: '#ff0000', opacity: 1, scale: 0.6 }]"(对象槽位;缺省项回落内置)
• 默认色板中的 AI 紫可用 CSS 变量 --fv-blob-purple/--fv-blob-purple-2 覆盖(无需传 colors)
• prefers-reduced-motion 下自动停动
• d: path() 变形仅 Chromium 支持,其他内核形状静止在初始形(旋转照常);path 带初始 d 兜底可渲染

FvSvgIcon

通用 SVG 图标(FvSvgIcon,基础组件):按 name 引用库内 assests/icons/<name>.svg,以 ?raw 源文本内联渲染(v-html)——svg 吃 CSS 继承,fill="currentColor" 强制覆写,颜色随文字色/亮暗主题/hover 态走(这是不用 <img src> 的原因:外部文档吃不到 currentColor)。换图标只替换 assests/icons/ 里的 svg 文件,代码零改动;新增图标丢文件进目录即自动可用(构建期 glob 收集)。svg 文件内的 width/height(设计稿常见 width="200")与硬编码 fill/class 会被剥除,统一由组件控制尺寸;viewBox 保留。

<FvSvgIcon name="maximize" :size="18" />

另导出 iconRegistry(Record<string, string>,name → svg 源文本映射),可查询可用图标名或取源文本自行处理。

对话应用层 API

AiChat

对话整框:顶栏(标题+模型多选)、消息区(空态 Welcome/Prompts)、输入区(Sender)、可选 Artifacts 面板。

v-model:messages 半受控语义:外部 messages 仅在 setup 时一次性深拷贝灌入(用于恢复历史);组件内部每次变更全量上抛 update:messages(同帧去抖),父组件需经 v-model 回写维持单向数据流;父组件后续直接改 prop 不会回灌生效。

AiMessages

消息列表(空态渲染 Welcome,建议快捷条经 Welcome #suggestions 插槽渲染在文案下方),吸底滚动。

AiMessage

单条消息(Markdown 正文 + 思考链折叠 + 附件 + 操作区)。

用户消息操作区:恒渲染复制按钮,默认透明,鼠标移上消息(或键盘聚焦)时浮现(open-webui 交互)。

AiArtifacts

Artifacts 预览面板(iframe 沙箱,从消息 html / svg 代码块提取)。

AiSessionSidebar

可收起的会话侧栏(FvAiSessionSidebar):品牌行 + 新对话 + 未归档/已归档 tab + 搜索 + 会话列表。新建仅切草稿态(DRAFT_SESSION_ID 哨兵,不发 service.create);列表触底分页加载;菜单内置重命名/删除(确认弹窗)与归档/恢复(service.archive 未实现时自动隐藏)。通常与 FvAiChatPanel 并排使用,由宿主编排(选中会话 → 传 Panel 的 sessionId;session-created/round-complete → 调 refresh 刷列表)。

<script setup lang="ts">
import { ref } from 'vue'
import { FvAiSessionSidebar, DRAFT_SESSION_ID } from '@fv-ui/ai-chat'
import type { FvAiSessionService } from '@fv-ui/ai-chat'

const service: FvAiSessionService = { /* 宿主胶水,见下节 */ } as FvAiSessionService
const activeId = ref(DRAFT_SESSION_ID)
const collapsed = ref(false)
const sidebarRef = ref()
</script>

<template>
  <FvAiSessionSidebar
    ref="sidebarRef"
    :service="service"
    :active-id="activeId"
    v-model:collapsed="collapsed"
    @select="(id) => (activeId = id)"
    @new-chat="() => (activeId = DRAFT_SESSION_ID)"
    @removed="(id) => id === activeId && (activeId = DRAFT_SESSION_ID)"
  />
</template>

AiChatPanel

对话面板(FvAiChatPanel,无头设计:会话状态/标题由侧栏表达,面板只承担对话):内嵌 FvAiChat + 会话历史加载 + 草稿懒创建。「加载更早」按钮悬浮消息区顶部(仅已拉详情且贴顶时出现),按 seq 游标向前翻页合并。

<script setup lang="ts">
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { FvAiChatPanel, FvCommonAdapter, DRAFT_SESSION_ID } from '@fv-ui/ai-chat'
import type { FvAiSessionService } from '@fv-ui/ai-chat'

const service: FvAiSessionService = { /* 宿主胶水,见下节 */ } as FvAiSessionService
const adapter = FvCommonAdapter({ baseURL: '/api', sessionId: () => sessionId.value })
const sessionId = ref<string>(DRAFT_SESSION_ID)
const panelRef = ref()
</script>

<template>
  <FvAiChatPanel
    ref="panelRef"
    :service="service"
    :adapter="adapter"
    :session-id="sessionId"
    style="height: 600px"
    @session-created="(id) => (sessionId = id)"
    @error="(err) => ElMessage.error(err.message)"
  />
</template>

Props 按用途分四组:

数据(会话/聊天接入):

展示(透传 FvAiChat):

功能(附件/评价钩子,透传 FvAiChat;草稿态懒创建由面板包装层承担):

布局(限宽,CSS 变量注入):

AiChatWidget

悬浮对话面板(FvAiChatWidget):Teleport 到 body,双形态——drawer 抽屉(默认:贴 position 侧全屏高,offsetTop/offsetBottom 各自留白)/ floating 悬窗(独立窗口,高度默认视口高 - 上下留白 - 80,可拖 header 自由移动,整窗限视口内不出界);宽度可经拖拽手柄调整(minWidthmaxWidth,默认 450640px;抽屉仅内缘一个手柄,悬窗左右两缘均可调,拖左缘时窗口同步平移、右缘不动),拖拽落定经 localStorage 记忆(storageKey 自定义)。头部左侧「头像 + AI 名称」(默认内置品牌头像),右侧图标按钮均带 tooltip:「历史会话 + 新对话 + 模式切换 + 最大化 + 关闭」(模式切换按钮默认隐藏,showModeToggle 开启;隐藏时仍可拖 header 超 100px 转悬窗、悬窗贴边吸附回抽屉);点历史会话图标在对话区覆盖式下拉(层挂在 body 内,header 露出不遮挡;顶部「返回」工具条收层,内嵌 FvConversations:「今天/以往」分组 + hover 菜单重命名/删除 + 触底分页,打开即拉取,点行切会话);主体内嵌 FvAiChatPanel(常规态 welcomeLayout 固定 vertical、centerWelcome 固定 false 窄宽形态:欢迎页贴上、输入区贴底,建议列表为 FAQ 式行列表——行间细分隔线、行尾箭头指示、hover 底色对称淡入淡出)。最大化(maximizable,默认 true;关闭按钮左侧按钮,亦经 toggleMaximize() 编程式切换):inset 0 占满视口的覆盖态,退出后回到进入前的 drawer/floating 原形态;最大化态头部收敛(头像/标题/历史/新对话/模式切换隐藏,标识由侧栏品牌行承担,仅留还原/关闭;关闭面板即退出最大化,再开回常规形态),FvAiSessionSidebar 升为根级全高覆盖(选中/新建/删除/搜索/归档全能力,service/locale/品牌透传;默认收起为 44px 悬浮窄条、可展开 260px,对话区经 padding-left 让位/收回),Panel 欢迎页转横排 + 垂直居中,限宽三参回库默认 1160/1200/780px 聚焦中栏,建议列表转大屏胶囊横排;拖拽/调宽/头部按钮随态禁用。面板底带主色角部微光渐变(科技感,亮暗两态;暗色下透明度升档 + 边框调亮 + 投影加深,面板与同色系页面背景可分层)。会话编排收在内部:草稿哨兵起步、session-created 换真实 id 并刷历史列表、round-complete 延时 2.5s 刷列表。关闭保活(keepAlive,默认 true):关闭仅隐藏(v-show),实例/对话树原样保留,再开不重渲染、不重拉历史。

<script setup lang="ts">
import { ref } from 'vue'
import { FvAiChatWidget, FvAiChatLauncher, FvCommonAdapter } from '@fv-ui/ai-chat'
import type { FvAiSessionService } from '@fv-ui/ai-chat'

const service: FvAiSessionService = { /* 宿主胶水,见下节 */ } as FvAiSessionService
const adapter = FvCommonAdapter({ baseURL: '/api' })
const open = ref(false) // 两个 v-model 接同一 ref
</script>

<template>
  <FvAiChatLauncher v-model="open" position="right" />
  <FvAiChatWidget
    v-model="open"
    :service="service"
    :adapter="adapter"
    title="AI 助手"
    position="right"
  />
</template>

注:Panel 的 welcomeLayout 在 Widget 内常规态固定为 vertical、centerWelcome 固定为 false(欢迎页贴上、输入区贴底),限宽三参(messagesMaxWidth 等)固定为 'none',均不透传;最大化态自动切为 horizontal + 居中 + 限宽回库默认;消息头像经 --fv-msg-avatar-size 固定 38px(库默认 50px)。

| Ref | 说明 | | --- | --- | --- | | open() / close() | 编程式开合(与 v-model 等价) | | toggleMode() | 编程式切换 drawer/floating 形态(与头部模式按钮等价) | | toggleMaximize() | 编程式切换最大化(与头部最大化按钮等价:最大化 ⇄ 还原为进入前形态) | | newChat() | 新建对话(与头部「新对话」按钮等价:切草稿;已在草稿则重播欢迎页) | | switchToPrevious() | 切回上一次对话(来路栈回退,浏览器后退式;栈空回落历史列表首条真实会话);返回 boolean 表示是否切换成功 | | refresh() | 刷新当前会话(透传 Panel.refresh:重新拉 detail 并重建视图;草稿态 no-op) |

AiChatLauncher

悬浮入口按钮(FvAiChatLauncher):blob 光晕(内嵌 FvBlobHalo 基础组件:主题色 + AI 紫 + 浅紫 + 白色四色色团,d: path() 变形 + 异速旋转,全部居中叠放混色;光晕约 1.6 倍按钮径。暗色下紫系压暗、白层变黑层;无白色图标底,头像直接铺满圆心)。与 FvAiChatWidget 组合时宿主把两个 v-model 接到同一 ref;亦可独立控任意目标。双形态:floating(默认)贴角悬浮;floating: false 文档流内联,可嵌进顶栏/卡片/按钮组;interactive: false 渲染为非交互 <span>(光晕照常动),可作纯展示图标引用。中间图标优先级:#icon 插槽 > iconComponent 组件 > icon 图片 URL > 内置品牌头像(内联 fvai-avatar.svg 矢量图,支持眼神跟随:eyeTrack(默认 true)下指针进入约 6 倍按钮径范围时眼睛朝指针方向偏移,离开回正,reduced-motion 降级;自定义 icon/插槽替换后自动失效);halo 对象整体透传内嵌 FvBlobHalo(色板/缩放/透明度/转速/暂停)。

<FvAiChatLauncher v-model="open" placement="bottom-right" :size="48" />

<!-- 内联非交互小图标(顶栏引用) -->
<FvAiChatLauncher :interactive="false" :floating="false" :size="32" />

<!-- 光晕调参 -->
<FvAiChatLauncher v-model="open" :halo="{ colors: ['#ff8c42', '#fcaf58', '#f9c784', '#fff'], rotateDuration: 15 }" />

FvAiSessionService(会话数据服务)

会话数据服务接口:宿主实现后经 prop 注入 FvAiSessionSidebar / FvAiChatPanel / FvAiChatWidget。库内不内置网络实现;错误提示(toast)由宿主胶水层统一承担(库对 service 失败:侧栏静默、面板空态重建)。

import { DRAFT_SESSION_ID } from '@fv-ui/ai-chat'
import type { FvAiSessionService, FvAiSessionPage, FvAiMessagePage } from '@fv-ui/ai-chat'

/** 草稿会话哨兵:进入模块/新建/删除当前会话即切草稿态,不调 service.create;
 *  首条消息发出时由 FvAiChatPanel 懒创建 service.create 后上抛 session-created 换真实 id */
DRAFT_SESSION_ID // '__draft__'

interface FvAiSessionService {
  /** 会话列表(分页,updatedTime DESC;status 筛选与 keyword 搜索正交同传) */
  list(q: { pageNum: number; pageSize: number; status?: 'ACTIVE' | 'ARCHIVED'; keyword?: string }): Promise<FvAiSessionPage>
  /** 新建会话,返回新会话 id */
  create(): Promise<string>
  /** 会话详情消息(尾部 limit 条,seq 升序) */
  detail(sessionId: string, limit?: number): Promise<FvCommonMessage[]>
  /** 加载更早消息(beforeSeq 游标) */
  history(sessionId: string, beforeSeq: number, limit?: number): Promise<FvAiMessagePage>
  /** 重命名 */
  rename(args: { sessionId: string; title: string }): Promise<void>
  /** 删除 */
  remove(sessionId: string): Promise<void>
  /** 归档/恢复(可选;未实现时侧栏隐藏归档 tab 与菜单项) */
  archive?(args: { sessionId: string; archived: boolean }): Promise<void>
}

// 归一化形状(宿主 IPage 格式由胶水转换)
interface FvAiSessionPage { items: FvCommonSessionItem[]; hasMore: boolean }
interface FvAiMessagePage { messages: FvCommonMessage[]; hasMore: boolean }

宿主胶水示例(det-oms 风格:list/create/detail/history/rename/remove 转发到宿主 httpRequest,并把后端 IPage 归一化为 { items, hasMore };错误 toast 由胶水层承担):

import { ElMessage } from 'element-plus'
import type { FvAiSessionService } from '@fv-ui/ai-chat'

/** 宿主统一请求封装(JSON 返回;非 2xx/业务错误码直接 reject) */
declare function httpRequest<T>(url: string, data?: unknown): Promise<T>

export const sessionService: FvAiSessionService = {
  async list(q) {
    const page = await httpRequest('/ai-chat/session/list', q) // IPage<T>
    return { items: page.records, hasMore: page.current * page.size < page.total }
  },
  create: () => httpRequest<{ id: string }>('/ai-chat/session/create').then((r) => r.id),
  detail: (sessionId, limit = 100) =>
    httpRequest('/ai-chat/session/detail', { sessionId, limit }),
  history: async (sessionId, beforeSeq, limit = 50) => {
    const page = await httpRequest('/ai-chat/session/history', { sessionId, beforeSeq, limit })
    return { messages: page.records, hasMore: page.records.length >= limit }
  },
  rename: (args) => httpRequest('/ai-chat/session/rename', args),
  remove: (sessionId) => httpRequest('/ai-chat/session/remove', { sessionId })
}

// 错误 toast:胶水层统一承担(库对 service 失败静默)
// httpRequest 内部 catch → ElMessage.error(后端 message 文案)后 reject

mapHistoryToNodes / sessionToConversationItem(历史回放映射)

src/core/historyMapper.ts 导出的两个纯映射函数(Fv 系后端消息行 → MessageNode 树 / FvConversations 项),独立使用时的签名:

import { mapHistoryToNodes, sessionToConversationItem, type AiChatT } from '@fv-ui/ai-chat'

/** 后端消息行(seq 升序)→ MessageNode 树(历史回放状态机):
 *  user 行 → user 节点;assistant 中间轮 + tool 结果行按 toolCallId 配对
 *  累积进本轮最终 assistant 的 toolSteps;GENERATING → 「回复生成中断」灰条;
 *  FAILED/INTERRUPTED → error 态;附件/评价/追问建议一并还原 */
function mapHistoryToNodes(messages: FvCommonMessage[], t?: AiChatT): MessageNode[]

/** 会话列表项 → FvConversations item(key=id;group 仅作归档兜底分组,
 *  展示分组由消费方按「今天/以往」覆写) */
function sessionToConversationItem(s: FvCommonSessionItem, t?: AiChatT): {
  key: string; label: string; group?: string; disabled?: boolean
}

t 参数为翻译函数((key: string, named?: Record<string, string>) => string,vue-i18n t 的结构子类型):文案 key 为库 locale historyMapper 分组的中文原文(如「回复生成中断」「用时 {s}」);缺省回落库内 locale(传入组件 locale 即随语言切换,无需自己拼 t)。带 named 占位参数时做 {name} 简单插值,未知占位符原样保留。

FvAiChatPanel 内部已按上述口径注入 t 后调用;仅独立使用该函数时需要关心。

人工验证点(文档站)

• 历史会话下拉覆盖层(Widget 头部时钟图标:仅遮对话区不遮 header、返回按钮收层、分组列表、打开即拉取、点行切会话)
• 炫光动画帧率(Launcher conic 旋转 + 光晕 breathing,低端机不掉帧)
• 窄宽欢迎页布局(Widget 内 welcomeLayout=vertical,输入区/建议条不溢出)
• 暗色主题下面板与按钮观感(theme=dark 下 Widget/Launcher 颜色对比)

Composables

useChat(options)

聊天编排:发送 → 流式回填 → 队列/重生成/续写。

import { useChat, zhCN, en, ko, vi, zhHK } from '@fv-ui/ai-chat' // 内置语言包(可换成自建包)

const lang = ref<'zh-CN' | 'en' | 'ko' | 'vi' | 'zh-HK'>('zh-CN')

const LOCALES = { 'zh-CN': zhCN, en, ko, vi, 'zh-HK': zhHK }

const chat = useChat({
  adapter: () => OpenAIAdapter({ baseURL, apiKey }), // 实例或工厂;工厂每次 send 惰性取用
  models: () => selectedModels.value,                // 数组或工厂;多模型并行生成兄弟分支
  initial: { messages, currentId },                  // 恢复会话
  onToolEvent: (ev) => { /* Fv 系通用 tool{status},展示「正在查询库存…」*/ },
  // 语言包工厂:返回 LocaleMessages 包对象(内置包或自建包),非语言名字符串
  locale: () => LOCALES[lang.value]
})
// chat: { send, stop, regenerate, continueGenerate, enqueue, queue, isLoading,
//         msgs, messages, currentId, chain }

• send(text, files?):生成中调用被拒;多模型时各模型一个 assistant 节点并发回填
• stop():中止全部在途请求,在途节点置 done(保留半截内容)
• regenerate(messageId?):回退焦点到父节点重发生成新分支(旧回答保留)
• continueGenerate(messageId?):以既有内容为前缀续写,增量追加到同一节点
• enqueue(text, files?):生成中入队,完成后自动 flush 队首
• onToolEvent:适配器 onTool 回调的透传挂点(如 FvCommonAdapter 的 tool{status} 事件)
• locale:语言包工厂 () => LocaleMessages,惰性取用(与 adapter/models 工厂同语义);影响附件 system prompt、工具用时、续写 prompt 等发给后端的文案,缺省读全局设置,见国际化

FvCommonAdapter(config)

Fv 系后端通用聊天适配器(/api/ai-chat/*):六事件 SSE 协议(message_start / tool / delta / reasoning / message_end / error),POST /ai-chat/message/send。适用于 Fv 各项目组返回此结构的后端。会话管理(列表/归档/删除等)由消费方直接调后端,不经此适配器。

const adapter = FvCommonAdapter({
  baseURL: '/api',                                     // 或 https://host
  headers: () => ({ Authorization: 'Bearer ' + token }), // 惰性取用
  sessionId: () => currentSessionId.value,             // 工厂:切换会话后下一次 send 生效
  errorMessages: { 90602: '已有进行中的对话' }           // 业务码 → 文案映射(可选)
})

• 同步段失败(Content-Type 非 text/event-stream)按 JSON 错误 {code,message} 走 onError;命中 errorMessages 时用映射文案(带 code 的 FvCommonError)
• message_end 的 messageId(最终文本行 id)经 onBackendMessageId 回填到 MessageNode.backendId——多轮工具循环下与 message_start 的首轮 id 不同,UI 落库/对账以它为准
• tool 事件经 onTool → useChat.onToolEvent → AiChat @tool-event 上抛,消费方展示「正在查询库存…」等中间态
• 追问建议(V58+):suggestions 事件(流式收尾 0..1 次,最后一个 delta 后、message_end 前,载荷 {items: string[]})经可选 onSuggestions 上抛,useChat 回写 MessageNode.suggestions,AiMessage 对带 suggestions 的 assistant 消息渲染追问(默认纵向列表样式——顶部灰色分隔线 + 加粗「追问」标题、条目 100% 宽下划线分隔字号随正文,followupStyle='chips' 切回横向气泡;正文打字效果完成后才渲染,流式事件到达不显示,历史消息同样渲染,不再限链尾);开关关闭/模型未产出/中断/失败无此事件;历史恢复用导出的 parseSuggestions(raw) 安全解析 FvCommonMessage.suggestions(JSON 数组原文透传,脏数据按无建议)
• 消息评价(V58+):FvCommonMessage.feedback(LIKE/DISLIKE,未评价/旧数据恒 null)、feedbackComment(附言 ≤500 字)、feedbackTime(评价落库时间)三字段同款容错;历史恢复由消费方映射为 MessageNode.feedback 灌入展示;评价提交走独立端点(POST /message/feedback),不经本适配器——接 AiChat 的 feedbackHandler 钩子即可
• 附件快照(1.4.1+):user 行 FvCommonMessage.attachments(id/originalName/type/suffix/sizeBytes/downloadUrl,旧数据/无附件恒 null),历史回放映射 MessageNode.files 渲染(图片缩略图 + 文档 FilesCard 卡片,卡片右上 28px 下载按钮 hover 浮现可下载;downloadUrl 需鉴权取流时配 resolveFileUrl 钩子,下载/预览均走解析后地址)
• 配套 DTO 类型:FvCommonSessionItem / FvCommonMessage / FvCommonSessionDetail / FvCommonMessagePage(消费方直接调会话管理端点时用)

useMessages(initial?)

树形消息状态中枢(响应式包装 createMessageTree)。

返回:messages(全量节点表)、currentId、chain(当前链 computed)、add、remove、edit、appendContent、navigate(id?, dir?)、setCurrent(id)、setStorage(adapter)、load()、flush()、toJSON()。绑定存储后树变更自动去抖(150ms)落盘。

useXStream()

SSE 流消费:startStream({ readableStream, transformStream? })、cancel()、data: Ref<SSEEvent[]>、error、isLoading。内部完成 \r\n/跨 chunk 边界归一化。

useSend() / XRequest

useSend():send({ url, method?, headers?, body?, transformStream?, onChunk? })(SSE data 为 JSON 且含 content 字段时逐块回调)、abort()、loading、error。在飞行守卫:上一个 send 未结束时新 send 被忽略。

XRequest(url, options):Promise 化,resolve 累计全文。

useRecord()

语音录制 + 实时转写:start() / stop() / isRecording / text / audioUrl / error。SpeechRecognition 不可用时降级为仅录音。

自定义 ChatAdapter

实现 ChatAdapter 接口即可接入任意后端(自研网关、Ollama、非 OpenAI 协议):

import type { ChatAdapter } from '@fv-ui/ai-chat'

const myAdapter: ChatAdapter = {
  async send(req, handlers) {
    // req: { messages: [{ role, content }], model?, stream?, signal? }
    try {
      const res = await fetch('/api/chat', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(req),
        signal: req.signal
      })
      if (!res.ok) { handlers.onError(new Error(`HTTP ${res.status}`)); return }
      // 流式:自行逐块解析,回调增量
      handlers.onDelta('一段正文')
      handlers.onReasoning('一段思考链') // 可选
      handlers.onUsage({ prompt_tokens: 10, completion_tokens: 20 }) // 可选
      handlers.onDone() // 正常结束必须调用
    } catch (e) {
      if (req.signal?.aborted) return // 主动中止不算错误
      handlers.onError(e instanceof Error ? e : new Error(String(e)))
    }
  },
  abort