@fv-ui/ai-chat 1.11.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,11 +1,13 @@
1
1
  # @fv-ui/ai-chat
2
2
 
3
- ![version](https://img.shields.io/badge/version-1.0.0-blue)
3
+ ![version](https://img.shields.io/badge/version-1.11.1-blue)
4
4
  ![vue](https://img.shields.io/badge/vue-%5E3.4.0-brightgreen)
5
5
  ![element-plus](https://img.shields.io/badge/element--plus-%5E2.7.0-blue)
6
6
 
7
7
  基于 Vue 3 + Element Plus 的 AI 对话组件库,复刻 element-plus-x 与 open-webui 对话框:从底层气泡、发送框、Markdown 渲染,到上层的对话整框(`<FvAiChat>`)、分支树消息、Artifacts 预览,一次给全。
8
8
 
9
+ > 分层:纯逻辑(消息树/适配器协议/SSE 解析/编排 composables/语言包)抽在 [`@fv-ui/ai-chat-core`](../ai-chat-core)(零 EP/零 DOM/零 fetch,平台能力经 PlatformBridge 注入);本包为 Web UI 层,入口默认注入 web 桥,公共 API 全部经 core re-export。
10
+
9
11
  - 14 个基础组件(Bubble/Sender/Markdown/Thinking/...)自由拼装
10
12
  - 对话应用层整框 `<FvAiChat>`:顶栏模型多选、消息列表、分支切换、Artifacts 面板、发送停止一体化
11
13
  - 树形消息模型(同构 open-webui):一条提问可挂多个模型回答,分支可切换、可重生成
@@ -69,6 +71,20 @@ export default defineConfig({
69
71
 
70
72
  说明:仅 Vite **dev** 需要;生产 `build` 走 Rollup 管线会自动把 GIF 复制进产物并重写路径,不受影响。UMD(`<script>` 直用 `lib/index.js`)不涉及。
71
73
 
74
+ ### 浏览器 `<script>` 直用(UMD)
75
+
76
+ `lib/index.js` 为 UMD 单文件,自包含 `@fv-ui/ai-chat-core`(纯逻辑层已内联,1.11.1 起不再要求页面预挂 `FvAiChatCore`/`FvAiChatCorePlatformWeb` 全局);页面仍需先引入 peerDeps:
77
+
78
+ ```html
79
+ <script src="https://unpkg.com/vue@3"></script>
80
+ <script src="https://unpkg.com/element-plus"></script>
81
+ <script src="https://unpkg.com/@element-plus/icons-vue"></script>
82
+ <script src="/path/to/@fv-ui/ai-chat/lib/index.js"></script>
83
+ <link rel="stylesheet" href="/path/to/@fv-ui/ai-chat/dist/style.css">
84
+ ```
85
+
86
+ 全局变量:`window.FvAiChat`(组件/composable/类型值)。
87
+
72
88
  ## 基础组件层 API
73
89
 
74
90
  ### FvMarkdown
@@ -451,7 +467,7 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
451
467
 
452
468
  ### Conversations
453
469
 
454
- 会话列表(按 group 分组)。
470
+ 会话列表(按 group 分组)。列表超长(>2×virtualThreshold)且显式传入 `virtual-disabled="false"` 时启用虚拟滚动,按行高裁剪视口外行;缺省关闭——消费方把滚动交给外层容器(如 el-scrollbar)时根节点不滚动,scroll 事件永不触发,虚拟化会永久截断列表。启用须保证组件根自身可滚动(或 height 受限)。
455
471
 
456
472
  | Prop | 类型 | 默认 | 说明 |
457
473
  | --- | --- | --- | --- |
@@ -459,12 +475,19 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
459
475
  | active | string \| number(v-model:active) | undefined | 当前激活会话 key |
460
476
  | showBuiltInMenuType | 'hover' \| 'always' | 'hover' | 内置菜单按钮显隐方式 |
461
477
  | groupable | (a, b) => number | — | 分组排序比较器(缺省保持插入顺序) |
478
+ | loading | boolean | false | 下一页加载中(loading 时触底不再触发 load-more) |
479
+ | hasMore | boolean | false | 是否还有更早分页(缺省 false 不触发 load-more) |
480
+ | rowHeight | number | 32 | 行高(虚拟滚动按 行数×行高 计算总高与窗口) |
481
+ | virtualThreshold | number | 8 | 视口上下各多渲染的缓冲行数 |
482
+ | virtualDisabled | boolean | true | 虚拟滚动开关(opt-in;缺省关闭。外部滚动容器接管时根节点不滚,scroll 永不触发,虚拟化会截断列表;启用须保证根自身可滚动) |
462
483
  | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
463
484
 
464
485
  | Event | 说明 |
465
486
  | --- | --- |
466
487
  | update:active / change | 选中会话(key / item) |
467
488
  | menu-command | ({ item, command: 'rename'/'delete', value? }) 菜单指令;rename 确认后带新名称 |
489
+ | load-more | 滚动到底且 hasMore && !loading 时触发(组件根节点自身滚动;外层接管滚动时由消费方自行判定触底) |
490
+ | update:selectedKeys | 多选模式已选 key 集合(v-model:selectedKeys) |
468
491
 
469
492
  | Slot | 说明 |
470
493
  | --- | --- |
@@ -855,6 +878,12 @@ const sidebarRef = ref()
855
878
  | brandName | string | 'Gizmo' | 品牌名称 |
856
879
  | brandIcon | string | 内置品牌头像 | 品牌徽章图片 URL(默认内置 fvai-avatar.svg) |
857
880
  | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
881
+ | searchContent | boolean | true | 启用内容搜索(弹窗形态,搜索标题+会话内容;service.search 未实现时自动降级为原输入框标题搜索) |
882
+ | searchPlaceholder | string | '' | 列表搜索框 placeholder(仅未启用内容搜索的输入框形态) |
883
+ | searchContentPlaceholder | string | '' | 内容搜索弹窗输入框 placeholder(缺省回落 locale.sessionSidebar.contentPlaceholder) |
884
+ | searchHistoryEnabled | boolean | true | 是否启用搜索历史功能(点击选中搜索结果时才记录;localStorage 持久化,最多 10 条,去重) |
885
+ | searchHistoryKey | string | 'fv-ai-search-history' | 搜索历史 localStorage 存储 key(多实例/多业务场景可自定义隔离) |
886
+ | searchHistoryPinned | boolean | false | 搜索历史是否常驻弹窗底部(true 常驻;false 仅输入为空时展示在结果区上方) |
858
887
 
859
888
  | Event | 说明 |
860
889
  | --- | --- |
@@ -875,6 +904,51 @@ const sidebarRef = ref()
875
904
  | refresh() | 静默刷新列表(不打 loading 遮罩;供父层在懒创建落库/首轮回复完成后调,刷新标题/活跃时间) |
876
905
  | reload() | 重载首页列表(与内部首载同路径) |
877
906
 
907
+ ### AiSearchModal
908
+
909
+ 内容搜索弹窗(FvAiSearchModal):侧栏/悬浮窗共用的独立组件,一般经 AiSessionSidebar 的搜索入口唤起,也可单独使用。输入防抖 400ms 检索,标题命中 + 会话内容命中分组展示;点击选中结果上抛事件给宿主。
910
+
911
+ ```vue
912
+ <script setup lang="ts">
913
+ import { ref } from 'vue'
914
+ import { FvAiSearchModal } from '@fv-ui/ai-chat'
915
+ import type { FvAiSessionService } from '@fv-ui/ai-chat'
916
+
917
+ const service: FvAiSessionService = { /* 宿主胶水,见下节 */ } as FvAiSessionService
918
+ const visible = ref(false)
919
+ </script>
920
+
921
+ <template>
922
+ <FvAiSearchModal
923
+ v-model="visible"
924
+ :service="service"
925
+ @select="(s, kw) => console.log('标题命中', s, kw)"
926
+ @content-select="(hit, kw) => console.log('内容命中', hit, kw)"
927
+ />
928
+ </template>
929
+ ```
930
+
931
+ | Prop | 类型 | 默认 | 说明 |
932
+ | --- | --- | --- | --- |
933
+ | v-model | boolean | (必填) | 弹窗显隐 |
934
+ | service | FvAiSessionService | (必填) | 会话数据服务(search/list 必填;search 未实现时调用方不应挂载) |
935
+ | pageSize | number | 20 | 内容分页大小 |
936
+ | locale | LocaleInput | undefined | 语言配置 |
937
+ | placeholder | string | '' | 输入框占位(缺省回落 locale.sessionSidebar.contentPlaceholder) |
938
+ | searchHistoryEnabled | boolean | true | 是否启用搜索历史功能(点击选中搜索结果时才记录;localStorage 持久化,最多 10 条,去重) |
939
+ | searchHistoryKey | string | 'fv-ai-search-history' | 搜索历史 localStorage 存储 key |
940
+ | searchHistoryPinned | boolean | false | 搜索历史是否常驻弹窗底部(true 常驻;false 仅输入为空时展示) |
941
+
942
+ | Event | 说明 |
943
+ | --- | --- |
944
+ | update:modelValue | (v: boolean) 弹窗显隐同步 |
945
+ | select | (session: FvCommonSessionItem, keyword: string) 标题命中(会话行)点击 |
946
+ | content-select | (hit: FvAiSearchHit, keyword: string) 内容命中点击 |
947
+
948
+ | Ref | 说明 |
949
+ | --- | --- |
950
+ | reset() | 清空输入与结果(宿主在「退出搜索状态」时调用) |
951
+
878
952
  ### AiChatPanel
879
953
 
880
954
  对话面板(FvAiChatPanel,无头设计:会话状态/标题由侧栏表达,面板只承担对话):内嵌 FvAiChat + 会话历史加载 + 草稿懒创建。「加载更早」按钮悬浮消息区顶部(仅已拉详情且贴顶时出现),按 seq 游标向前翻页合并。
@@ -1123,14 +1197,32 @@ interface FvAiSessionService {
1123
1197
  create(): Promise<string>
1124
1198
  /** 会话详情消息(尾部 limit 条,seq 升序) */
1125
1199
  detail(sessionId: string, limit?: number): Promise<FvCommonMessage[]>
1126
- /** 加载更早消息(beforeSeq 游标) */
1127
- history(sessionId: string, beforeSeq: number, limit?: number): Promise<FvAiMessagePage>
1200
+ /**
1201
+ * 历史消息翻页(游标形态;q 兼容旧数字签名,等价 { cursor: q, direction: 'earlier' }):
1202
+ * - earlier(cursor):加载更早,取比首行 seq 早的 limit 条(游标 → 后端 beforeSeq)
1203
+ * - later(cursor):加载更新,取比末行 seq 新的 limit 条(游标 → 后端 afterSeq)
1204
+ * 游标取返回窗口边界行 seq(勿算术翻页);hasMore=false 即对应方向到头。
1205
+ * 首屏定位(锚不在 detail 窗口)走 historyAround(aroundSeq),勿用本方法
1206
+ *
1207
+ * 宿主实现经 normalizeHistoryQuery(q, limit) 归一化后按 direction 分流
1208
+ * beforeSeq/afterSeq;**AiChatPanel 消费侧约定**:earlier 传数字(兼容已发布
1209
+ * 的旧宿主实现),later 传游标对象
1210
+ */
1211
+ history(
1212
+ sessionId: string,
1213
+ q: { cursor: number; direction: 'earlier' | 'later'; limit?: number } | number,
1214
+ limit?: number
1215
+ ): Promise<FvAiMessagePage>
1128
1216
  /** 重命名 */
1129
1217
  rename(args: { sessionId: string; title: string }): Promise<void>
1130
1218
  /** 删除 */
1131
1219
  remove(sessionId: string): Promise<void>
1132
1220
  /** 归档/恢复(可选;未实现时侧栏隐藏归档 tab 与菜单项) */
1133
1221
  archive?(args: { sessionId: string; archived: boolean }): Promise<void>
1222
+ /** 内容搜索(可选;未实现时侧栏自动降级为纯标题搜索) */
1223
+ search?(q: { keyword: string; pageNum: number; pageSize: number }): Promise<FvAiSearchPage>
1224
+ /** 以锚点为中心开窗(可选;定位锚不在 detail 窗口时由面板调用) */
1225
+ historyAround?(sessionId: string, aroundSeq: number, limit?: number): Promise<FvAiAroundPage>
1134
1226
  }
1135
1227
 
1136
1228
  // 归一化形状(宿主 IPage 格式由胶水转换)
@@ -1142,6 +1234,7 @@ interface FvAiMessagePage { messages: FvCommonMessage[]; hasMore: boolean }
1142
1234
 
1143
1235
  ```ts
1144
1236
  import { ElMessage } from 'element-plus'
1237
+ import { normalizeHistoryQuery } from '@fv-ui/ai-chat'
1145
1238
  import type { FvAiSessionService } from '@fv-ui/ai-chat'
1146
1239
 
1147
1240
  /** 宿主统一请求封装(JSON 返回;非 2xx/业务错误码直接 reject) */
@@ -1155,8 +1248,16 @@ export const sessionService: FvAiSessionService = {
1155
1248
  create: () => httpRequest<{ id: string }>('/ai-chat/session/create').then((r) => r.id),
1156
1249
  detail: (sessionId, limit = 100) =>
1157
1250
  httpRequest('/ai-chat/session/detail', { sessionId, limit }),
1158
- history: async (sessionId, beforeSeq, limit = 50) => {
1159
- const page = await httpRequest('/ai-chat/session/history', { sessionId, beforeSeq, limit })
1251
+ history: async (sessionId, q) => {
1252
+ // 旧签名宿主可只认数字 beforeSeq 入参(等价 { cursor: beforeSeq, direction: 'earlier' });
1253
+ // 新版消费方始终传 { cursor, direction, limit? } 游标对象,勿算术翻页
1254
+ const { cursor, direction, limit = 50 } = normalizeHistoryQuery(q)
1255
+ const page = await httpRequest('/ai-chat/session/history', {
1256
+ sessionId,
1257
+ beforeSeq: direction === 'earlier' ? cursor : undefined,
1258
+ afterSeq: direction === 'later' ? cursor : undefined,
1259
+ limit
1260
+ })
1160
1261
  return { messages: page.records, hasMore: page.records.length >= limit }
1161
1262
  },
1162
1263
  rename: (args) => httpRequest('/ai-chat/session/rename', args),
@@ -1169,7 +1270,7 @@ export const sessionService: FvAiSessionService = {
1169
1270
 
1170
1271
  ### mapHistoryToNodes / sessionToConversationItem(历史回放映射)
1171
1272
 
1172
- `src/core/historyMapper.ts` 导出的两个纯映射函数(Fv 系后端消息行 → MessageNode 树 / FvConversations 项),独立使用时的签名:
1273
+ `@fv-ui/ai-chat-core` 的 historyMapper 模块导出的两个纯映射函数(Fv 系后端消息行 → MessageNode 树 / FvConversations 项;经 `@fv-ui/ai-chat` 包出口 re-export,亦可直接 `import ... from '@fv-ui/ai-chat-core'`),独立使用时的签名:
1173
1274
 
1174
1275
  ```ts
1175
1276
  import { mapHistoryToNodes, sessionToConversationItem, type AiChatT } from '@fv-ui/ai-chat'
@@ -1262,7 +1363,7 @@ const adapter = FvCommonAdapter({
1262
1363
 
1263
1364
  ### useXStream()
1264
1365
 
1265
- SSE 流消费:`startStream({ readableStream, transformStream? })`、`cancel()`、`data: Ref<SSEEvent[]>`、`error`、`isLoading`。内部完成 `\r\n`/跨 chunk 边界归一化。
1366
+ SSE 流消费:`startStream({ stream | readableStream, transformStream?, decodeText? })`、`cancel()`、`data: Ref<SSEEvent[]>`、`error`、`isLoading`。`readableStream` 为基线期 API 形参的兼容别名(与 `stream` 二选一,同时给时 `stream` 优先);web 端直接把 `ReadableStream<Uint8Array>` 传入即可(自带 `[Symbol.asyncIterator]` 既是字节源),uni-app 端传 async generator(直接产 string 不经解码)。内部完成 `\r\n`/跨 chunk 边界归一化与流末多字节残码冲刷。
1266
1367
 
1267
1368
  ### useSend() / XRequest
1268
1369