@fv-ui/ai-chat 1.10.3 → 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 +148 -11
- package/dist/index.d.ts +894 -2117
- package/dist/style.css +1 -1
- package/es/index.mjs +8133 -3685
- package/lib/index.js +8169 -3701
- package/package.json +81 -80
package/README.md
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
# @fv-ui/ai-chat
|
|
2
2
|
|
|
3
|
-

|
|
4
4
|

|
|
5
5
|

|
|
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
|
| --- | --- |
|
|
@@ -575,6 +598,8 @@ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内
|
|
|
575
598
|
| uploadAttachment | (file, item) => Promise\<Partial\<AttachmentItem\> \| string \| undefined \| void\> \| ... | undefined | 附件上传钩子(先传后发):选文件即调,成功返回附件描述(id/name/type 等回填列表项,id 随发送进入 adapter 的 user 消息 files);返回错误文案串/抛错置 error 可重传。缺省不调(附件仅本地待发展示,不落服务端);上传中(loading 项)提交按钮禁用拒发,error 残留项不随发送 |
|
|
576
599
|
| resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子(鉴权取流):消息气泡渲染附件 url 前调用,返回可直渲地址(如 JWT fetch 换 blob objectURL);缺省原样使用 url(blob/dataURL/公开地址)。远端 url 解析结果组件内按 url 缓存 + 在途去重;解析失败回落原 url 不阻塞渲染 |
|
|
577
600
|
| feedbackHandler | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR', comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子(透传 AiMessages→AiMessage;仅 assistant 最终回答行渲染 👍/👎,缺省不渲染按钮)。消费方在此接后端评价端点(如 Fv 系 POST /message/feedback):resolved 即成功;返回错误文案串/抛错触发 feedback-error(乐观更新已回滚);action=CLEAR 取消评价(comment 忽略)。交互语义:点击 👍 直接提交(不弹附言),点击 👎 弹**居中附言弹窗**(textarea ≤500 字 + 提交/跳过),再次点击当前态按钮发 CLEAR 取消评价(附言一并清空);👍↔👎 任意切换,后一次整体覆盖前一次(含附言);提交中按钮禁用防连点 |
|
|
601
|
+
| actionCardOption | ActionCardOption | undefined | 写操作确认卡(V59+「预案-确认-执行」):SSE action_card 事件由 adapter 上抛后库内就地建卡(anchorId 指向生成轮 assistant,卡片渲染在对应回答下方;anchorId 缺省/未命中回落消息流末尾,0..N 张),确认/取消经 execute 走消费方带外端点(非 SSE);**缺省或未带 execute 即整特性关闭**——卡片不渲染、SSE 事件被容错丢弃(无执行器的待确认卡按钮禁用是纯负担)。历史回放卡经 actionCards prop 由宿主自行控制,不受此开关影响。ActionCardOption = { execute?(card, kind): Promise\<ActionCardResult \| void\> —— 抛错的 Error 可携带 actionStatus: 'invalid'/'expired'/'failed' 提示驱动卡片按语义转终态,无提示(会话忙/网络超时)退回待确认可重试 }。终态落定通知走组件 @action-card-settled 事件(单一通道,无 onSettled 回调) |
|
|
602
|
+
| actionCards | MessageNode[] | undefined | 初始确认卡列表(历史回放恢复,一次性深拷贝灌入,半受控与 messages 同语义——运行期更换 prop 不生效):卡片独立于消息树——action.anchorId 指向所属 assistant 消息 id 时锚定渲染在其下,缺省/锚已删除回落消息流末尾,锚在其它分支的卡隐藏不渲染(切回原分支自然恢复)。与流式 SSE 建卡合并渲染;clearMessages 整框重置会一并清空(流式卡与初始卡同库内清) |
|
|
578
603
|
| theme | 'light' \| 'dark' \| 'auto' | 'light' | 主题(向 html 注入/移除 dark class) |
|
|
579
604
|
| locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(解析后注入整框后代) |
|
|
580
605
|
|
|
@@ -597,6 +622,8 @@ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内
|
|
|
597
622
|
| feedback-error | (message: string) 评价提交失败(钩子 reject/返回错误文案;乐观更新已回滚,message 为错误文案) |
|
|
598
623
|
| scroll | (event) 消息区滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
|
|
599
624
|
| refresh-suggestions | () 空态建议区「换一批」点击(AiMessages 层实现并上抛;消费方监听后自行更换建议数据) |
|
|
625
|
+
| tool-event | (ev: { toolName, status: 'start' \| 'done' }) 工具调用轨迹事件(经 adapter 的 onTool 回调上抛;展示「正在查询库存…」等中间态) |
|
|
626
|
+
| action-card-settled | (info: { card: ActionCardPayload; status: 'success' \| 'failed' \| 'cancelled' \| 'expired' \| 'invalid'; result? }) 写操作确认卡终态落定(V59+;库内已把终态写回卡片节点):成功/失败/已取消/已过期/已失效;expired 含本地倒计时归零预判,invalid/failed 含执行器抛错 actionStatus 提示;宿主可 toast/埋点/刷新(网络层超时断线时不上抛,结果以刷新历史为准)。终态联动唯一通道,ActionCardOption 无 onSettled 回调 |
|
|
600
627
|
|
|
601
628
|
| Slot | 说明 |
|
|
602
629
|
| --- | --- |
|
|
@@ -625,7 +652,7 @@ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内
|
|
|
625
652
|
| stop() | 停止生成(保留半截内容,静默收口不发 complete/error) |
|
|
626
653
|
| regenerate(messageId?) | 重生成(缺省链尾 assistant) |
|
|
627
654
|
| appendToMessage(id, text) | 向指定消息追加文本 |
|
|
628
|
-
| clearMessages() |
|
|
655
|
+
| clearMessages() | 清空消息树与全部确认卡(流式建卡 + actionCards 初始卡一并清空) |
|
|
629
656
|
| exportTxt() | 导出当前链为纯文本 |
|
|
630
657
|
| openArtifact(key) | 程序化打开某个 artifact |
|
|
631
658
|
| expandThoughtChains() / collapseThoughtChains() | 全部展开/折叠当前链上消息的思考链(user 消息、无思考链消息、单 item 平铺形态不受控) |
|
|
@@ -668,6 +695,8 @@ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内
|
|
|
668
695
|
| resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子(透传 AiMessage;鉴权取流换可直渲地址,见 AiChat) |
|
|
669
696
|
| followupStyle | 'list' \| 'chips' | 'list' | 追问建议展示样式(透传 AiMessage;默认 'list' 纵向列表——顶部灰色分隔线 + 加粗「追问」标题(字号/颜色随正文)、条目 100% 宽下划线分隔字号随正文;'chips' 旧横向气泡,见 AiChat)。**正文打字效果完成后才渲染**(流式 suggestions 事件到达不显示) |
|
|
670
697
|
| feedbackHandler | (message, action, comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子(透传 AiMessage;语义见 AiChat,缺省不渲染 👍/👎) |
|
|
698
|
+
| actionCardExecutor | MessageActionCardExecutor | undefined | 写操作确认卡执行器(透传 AiMessage→ActionCard,仅 role='action' 节点消费;execute(card, kind) → Promise\<ActionCardResult \| void\>,抛错可带 actionStatus 提示) |
|
|
699
|
+
| actionCards | MessageNode[] | [] | 在途确认卡(流式 SSE 建卡 + 历史回放灌入):action.anchorId 命中当前链消息的渲染在所属 assistant 下(多轮写操作各自贴在对应回答下方),缺省/锚已删除回落消息流末尾,**锚在其它分支的卡隐藏不渲染**(切回原分支自然恢复) |
|
|
671
700
|
| locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
|
|
672
701
|
|
|
673
702
|
| Event | 说明 |
|
|
@@ -678,6 +707,7 @@ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内
|
|
|
678
707
|
| feedback-change / feedback-error | 评价提交成功(message, action)/ 失败(错误文案;透传 AiMessage,语义见 AiChat) |
|
|
679
708
|
| scroll | (event) 滚动容器滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
|
|
680
709
|
| refresh-suggestions | () 空态建议区「换一批」点击(消费方监听后自行更换建议数据) |
|
|
710
|
+
| action-card-settled | (info: { card: ActionCardPayload; status: Exclude\<ActionCardStatus, 'pending' \| 'loading'\>; result?: ActionCardResult }) 写操作确认卡终态落定(透传 AiMessage;库内已把终态写回卡片节点,宿主可 toast/埋点/刷新) |
|
|
681
711
|
|
|
682
712
|
| Slot | 说明 |
|
|
683
713
|
| --- | --- |
|
|
@@ -736,6 +766,7 @@ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内
|
|
|
736
766
|
| resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子:渲染附件 url 前调用,返回可直渲地址(如 JWT fetch 换 blob objectURL);缺省原样使用 url(blob/dataURL/公开地址),远端地址解析结果按 url 缓存 + 在途去重,失败回落原 url |
|
|
737
767
|
| feedbackHandler | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR', comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子:仅 assistant 最终回答行(role=assistant 且 status=done,error/中断/生成中不渲染)渲染 👍/👎,缺省不渲染按钮。点击 👍 直接提交,点击 👎 弹**居中附言弹窗**(ElDialog,textarea ≤500 字 + 提交/跳过,点遮罩/ESC 关闭草稿保留、再点 👎 复填),再次点击当前态按钮发 CLEAR;乐观更新——先翻转 message.feedback 再调钩子,失败回滚并经 feedback-error 上抛,成功经 feedback-change 上抛;返回 resolved 即成功,返回错误文案串/抛错均视为失败。**弹窗标题/占位可自定义**(语言包 `aiMessage.feedback.dislikeTitle`/`dislikePlaceholder`;标题 `{name}` 占位渲染时替换为 assistantName,空串回落 defaultAssistantName) |
|
|
738
768
|
| locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
|
|
769
|
+
| actionCardExecutor | MessageActionCardExecutor | undefined | 写操作确认卡执行器(仅 message.role='action' 节点消费):execute(card, kind) → Promise\<ActionCardResult \| void\>——resolve 带 result 落终态(success 布尔分流,cancel 恒「已取消」);无返回值退回待确认(结果由消费方另行回灌);reject 的 Error 携带 actionStatus('invalid'/'expired'/'failed')按语义转终态,无提示退回待确认可重试。终态写回节点并上抛 action-card-settled |
|
|
739
770
|
|
|
740
771
|
> 用户消息操作区:恒渲染复制按钮,默认透明,鼠标移上消息(或键盘聚焦)时浮现(open-webui 交互)。
|
|
741
772
|
|
|
@@ -747,6 +778,7 @@ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内
|
|
|
747
778
|
| feedback-change | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR') 评价提交成功(乐观落定后触发;message.feedback 已更新,宿主可埋点/联动) |
|
|
748
779
|
| feedback-error | (message: string) 评价提交失败(钩子 reject/返回错误文案;乐观更新已回滚,message 为错误文案) |
|
|
749
780
|
| typing | 打字机输出中(流式期间节奏性触发) |
|
|
781
|
+
| action-card-settled | (info: { card: ActionCardPayload; status: Exclude\<ActionCardStatus, 'pending' \| 'loading'\>; result?: ActionCardResult }) 写操作确认卡终态落定(库内已把终态写回消息节点;expired 为本地倒计时归零预判,宿主可 toast/埋点/刷新) |
|
|
750
782
|
|
|
751
783
|
| Slot | 说明 |
|
|
752
784
|
| --- | --- |
|
|
@@ -763,6 +795,31 @@ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内
|
|
|
763
795
|
| message | 当前消息节点(computed) |
|
|
764
796
|
| expandThoughtChain() / collapseThoughtChain() | 展开/折叠本条消息的思考链(user 消息、无思考链、单 item 平铺形态调用无效) |
|
|
765
797
|
|
|
798
|
+
### ActionCard(FvAiActionCard)
|
|
799
|
+
|
|
800
|
+
写操作确认卡(Fv 系 V59+「预案-确认-执行」)。两种形态:**待确认卡**(预案摘要 + 取消/确认执行按钮 + 过期倒计时,确认必须用户主动点击,倒计时归零仅转「已过期未执行」UI 终态,绝不自动执行——客户端时钟可能漂移,最终权威是点击后服务端的 30019)与**终态只读卡**(成功/失败/已取消/已过期/已失效,展示 result.message,失败附「重新描述需求」引导,无重试入口;detail 经原生 details 折叠默认收起)。通常不直接使用:AiMessage 内部渲染 role=action 节点,确认/取消走消费方注入的 `actionCardOption.execute` 钩子(带外独立 HTTP 端点,非 SSE;confirm 服务端内调最坏 ~30s,读超时须 ≥35s 由消费方请求层保证)。
|
|
801
|
+
|
|
802
|
+
| Prop | 类型 | 默认 | 说明 |
|
|
803
|
+
| --- | --- | --- | --- |
|
|
804
|
+
| card | ActionCardPayload | (必填) | 卡片载荷(confirmToken/action/planSummary/expiresAt,SSE action_card 事件 / 历史 plan 行原样透传) |
|
|
805
|
+
| status | ActionCardStatus | 'pending' | 卡片状态:待确认 pending / 执行中 loading / 成功 success / 失败 failed / 已取消 cancelled / 已过期 expired / 已失效 invalid |
|
|
806
|
+
| result | ActionCardResult | undefined | 终态执行结果(成功概要/失败原因原文/取消回执 + 可折叠明细 detail) |
|
|
807
|
+
| execute | ActionCardExecutor | undefined | 确认/取消执行器 (kind) => Promise\<ActionCardResult \| void\>;缺省待确认卡按钮禁用(纯只读展示)。reject 的 Error 可携带 actionStatus 提示驱动卡片按语义转终态,无提示退回待确认可重试 |
|
|
808
|
+
| locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象 |
|
|
809
|
+
|
|
810
|
+
| Event | 说明 |
|
|
811
|
+
| --- | --- |
|
|
812
|
+
| finish | (status: Exclude\<ActionCardStatus, 'pending' \| 'loading'\>) 终态落定(成功/失败/已取消/已过期/已失效),宿主可埋点/联动 |
|
|
813
|
+
|
|
814
|
+
| Slot | 说明 |
|
|
815
|
+
| --- | --- |
|
|
816
|
+
| default | 整体替换卡片内容(作用域 { card, status, result, execute };execute 为确认/取消回调) |
|
|
817
|
+
| icon | 头部状态图标单独自定义(作用域 { card, status, result };缺省内置齿轮/对勾/叉/时钟,终态语义色) |
|
|
818
|
+
| title | 头部标题单独自定义(作用域 { card, status, result };缺省语言包「待确认的操作」/终态文案) |
|
|
819
|
+
| summary | 预案摘要单独自定义(作用域 { card, status, result };缺省服务端预检实查文案原样渲染——前端不解析、不加工、不请求补充数据) |
|
|
820
|
+
| actions | 待确认/执行中操作区单独自定义(作用域 { card, status, execute, executing };缺省取消/确认按钮) |
|
|
821
|
+
| result | 终态结果区单独自定义(作用域 { card, status, result };缺省成功概要/失败原因原文 + 可折叠明细 + 失败引导) |
|
|
822
|
+
|
|
766
823
|
### AiArtifacts
|
|
767
824
|
|
|
768
825
|
Artifacts 预览面板(iframe 沙箱,从消息 ```html / ```svg 代码块提取)。
|
|
@@ -821,6 +878,12 @@ const sidebarRef = ref()
|
|
|
821
878
|
| brandName | string | 'Gizmo' | 品牌名称 |
|
|
822
879
|
| brandIcon | string | 内置品牌头像 | 品牌徽章图片 URL(默认内置 fvai-avatar.svg) |
|
|
823
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 仅输入为空时展示在结果区上方) |
|
|
824
887
|
|
|
825
888
|
| Event | 说明 |
|
|
826
889
|
| --- | --- |
|
|
@@ -841,6 +904,51 @@ const sidebarRef = ref()
|
|
|
841
904
|
| refresh() | 静默刷新列表(不打 loading 遮罩;供父层在懒创建落库/首轮回复完成后调,刷新标题/活跃时间) |
|
|
842
905
|
| reload() | 重载首页列表(与内部首载同路径) |
|
|
843
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
|
+
|
|
844
952
|
### AiChatPanel
|
|
845
953
|
|
|
846
954
|
对话面板(FvAiChatPanel,无头设计:会话状态/标题由侧栏表达,面板只承担对话):内嵌 FvAiChat + 会话历史加载 + 草稿懒创建。「加载更早」按钮悬浮消息区顶部(仅已拉详情且贴顶时出现),按 seq 游标向前翻页合并。
|
|
@@ -1089,14 +1197,32 @@ interface FvAiSessionService {
|
|
|
1089
1197
|
create(): Promise<string>
|
|
1090
1198
|
/** 会话详情消息(尾部 limit 条,seq 升序) */
|
|
1091
1199
|
detail(sessionId: string, limit?: number): Promise<FvCommonMessage[]>
|
|
1092
|
-
/**
|
|
1093
|
-
|
|
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>
|
|
1094
1216
|
/** 重命名 */
|
|
1095
1217
|
rename(args: { sessionId: string; title: string }): Promise<void>
|
|
1096
1218
|
/** 删除 */
|
|
1097
1219
|
remove(sessionId: string): Promise<void>
|
|
1098
1220
|
/** 归档/恢复(可选;未实现时侧栏隐藏归档 tab 与菜单项) */
|
|
1099
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>
|
|
1100
1226
|
}
|
|
1101
1227
|
|
|
1102
1228
|
// 归一化形状(宿主 IPage 格式由胶水转换)
|
|
@@ -1108,6 +1234,7 @@ interface FvAiMessagePage { messages: FvCommonMessage[]; hasMore: boolean }
|
|
|
1108
1234
|
|
|
1109
1235
|
```ts
|
|
1110
1236
|
import { ElMessage } from 'element-plus'
|
|
1237
|
+
import { normalizeHistoryQuery } from '@fv-ui/ai-chat'
|
|
1111
1238
|
import type { FvAiSessionService } from '@fv-ui/ai-chat'
|
|
1112
1239
|
|
|
1113
1240
|
/** 宿主统一请求封装(JSON 返回;非 2xx/业务错误码直接 reject) */
|
|
@@ -1121,8 +1248,16 @@ export const sessionService: FvAiSessionService = {
|
|
|
1121
1248
|
create: () => httpRequest<{ id: string }>('/ai-chat/session/create').then((r) => r.id),
|
|
1122
1249
|
detail: (sessionId, limit = 100) =>
|
|
1123
1250
|
httpRequest('/ai-chat/session/detail', { sessionId, limit }),
|
|
1124
|
-
history: async (sessionId,
|
|
1125
|
-
|
|
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
|
+
})
|
|
1126
1261
|
return { messages: page.records, hasMore: page.records.length >= limit }
|
|
1127
1262
|
},
|
|
1128
1263
|
rename: (args) => httpRequest('/ai-chat/session/rename', args),
|
|
@@ -1135,7 +1270,7 @@ export const sessionService: FvAiSessionService = {
|
|
|
1135
1270
|
|
|
1136
1271
|
### mapHistoryToNodes / sessionToConversationItem(历史回放映射)
|
|
1137
1272
|
|
|
1138
|
-
|
|
1273
|
+
`@fv-ui/ai-chat-core` 的 historyMapper 模块导出的两个纯映射函数(Fv 系后端消息行 → MessageNode 树 / FvConversations 项;经 `@fv-ui/ai-chat` 包出口 re-export,亦可直接 `import ... from '@fv-ui/ai-chat-core'`),独立使用时的签名:
|
|
1139
1274
|
|
|
1140
1275
|
```ts
|
|
1141
1276
|
import { mapHistoryToNodes, sessionToConversationItem, type AiChatT } from '@fv-ui/ai-chat'
|
|
@@ -1186,7 +1321,7 @@ const chat = useChat({
|
|
|
1186
1321
|
locale: () => LOCALES[lang.value]
|
|
1187
1322
|
})
|
|
1188
1323
|
// chat: { send, stop, regenerate, continueGenerate, enqueue, queue, isLoading,
|
|
1189
|
-
// msgs, messages, currentId, chain }
|
|
1324
|
+
// actionCards, clearActionCards, msgs, messages, currentId, chain }
|
|
1190
1325
|
```
|
|
1191
1326
|
|
|
1192
1327
|
- `send(text, files?)`:生成中调用被拒;多模型时各模型一个 assistant 节点并发回填
|
|
@@ -1195,11 +1330,12 @@ const chat = useChat({
|
|
|
1195
1330
|
- `continueGenerate(messageId?)`:以既有内容为前缀续写,增量追加到同一节点
|
|
1196
1331
|
- `enqueue(text, files?)`:生成中入队,完成后自动 flush 队首
|
|
1197
1332
|
- `onToolEvent`:适配器 `onTool` 回调的透传挂点(如 FvCommonAdapter 的 tool{status} 事件)
|
|
1333
|
+
- `actionCards` / `clearActionCards()`:写操作确认卡(V59+)——SSE `action_card` 事件就地建 role=action 节点挂 `actionCards`(0..N 张,anchorId 回填生成轮节点;传入 `initialActionCards` 历史回放一次性深拷贝灌入);`clearActionCards()` 清空全部(整框重置联动)。终态写回节点,通知经 AiChat `@action-card-settled` 事件上抛
|
|
1198
1334
|
- `locale`:语言包工厂 `() => LocaleMessages`,惰性取用(与 adapter/models 工厂同语义);影响附件 system prompt、工具用时、续写 prompt 等发给后端的文案,缺省读全局设置,见[国际化](#国际化i18n)
|
|
1199
1335
|
|
|
1200
1336
|
### FvCommonAdapter(config)
|
|
1201
1337
|
|
|
1202
|
-
Fv 系后端通用聊天适配器(`/api/ai-chat/*`)
|
|
1338
|
+
Fv 系后端通用聊天适配器(`/api/ai-chat/*`):八事件 SSE 协议(`message_start` / `tool` / `delta` / `reasoning` / `suggestions` / `action_card` / `message_end` / `error`),POST `/ai-chat/message/send`。适用于 Fv 各项目组返回此结构的后端。会话管理(列表/归档/删除等)由消费方直接调后端,不经此适配器。
|
|
1203
1339
|
|
|
1204
1340
|
```ts
|
|
1205
1341
|
const adapter = FvCommonAdapter({
|
|
@@ -1215,6 +1351,7 @@ const adapter = FvCommonAdapter({
|
|
|
1215
1351
|
- `tool` 事件经 `onTool` → `useChat.onToolEvent` → `AiChat @tool-event` 上抛,消费方展示「正在查询库存…」等中间态
|
|
1216
1352
|
- 追问建议(V58+):`suggestions` 事件(流式收尾 0..1 次,最后一个 delta 后、message_end 前,载荷 `{items: string[]}`)经可选 `onSuggestions` 上抛,`useChat` 回写 `MessageNode.suggestions`,AiMessage 对带 suggestions 的 assistant 消息渲染追问(默认纵向列表样式——顶部灰色分隔线 + 加粗「追问」标题、条目 100% 宽下划线分隔字号随正文,`followupStyle='chips'` 切回横向气泡;**正文打字效果完成后才渲染**,流式事件到达不显示,历史消息同样渲染,不再限链尾);开关关闭/模型未产出/中断/失败无此事件;历史恢复用导出的 `parseSuggestions(raw)` 安全解析 `FvCommonMessage.suggestions`(JSON 数组原文透传,脏数据按无建议)
|
|
1217
1353
|
- 消息评价(V58+):`FvCommonMessage.feedback`(LIKE/DISLIKE,未评价/旧数据恒 null)、`feedbackComment`(附言 ≤500 字)、`feedbackTime`(评价落库时间)三字段同款容错;历史恢复由消费方映射为 `MessageNode.feedback` 灌入展示;评价提交走独立端点(POST /message/feedback),不经本适配器——接 `AiChat` 的 `feedbackHandler` 钩子即可
|
|
1354
|
+
- 写操作确认卡(V59+):`action_card` 事件(message_end 前 0..N 次,与正文渲染互不阻塞;载荷四键 `confirmToken`/`action`/`planSummary`/`expiresAt`,脏帧经 `sanitizeActionCard` 容错丢弃)经可选 `onActionCard` 上抛,`useChat` 就地建 role=action 节点挂 `actionCards` 渲染;确认/取消走消费方带外端点(接 `AiChat` 的 `actionCardOption` 钩子),终态落定经 `@action-card-settled` 事件上抛;历史回放用导出的 `resolveActionHistoryPairing`(plan 工具行 ↔ action 结果行按 confirmToken 配对)+ `buildPlanRowAnchorMap`(plan tool 行 → 本轮最终 assistant 行锚定映射)恢复终态卡
|
|
1218
1355
|
- 附件快照(1.4.1+):user 行 `FvCommonMessage.attachments`(id/originalName/type/suffix/sizeBytes/downloadUrl,旧数据/无附件恒 null),历史回放映射 `MessageNode.files` 渲染(图片缩略图 + 文档 FilesCard 卡片,卡片右上 28px 下载按钮 hover 浮现可下载;downloadUrl 需鉴权取流时配 `resolveFileUrl` 钩子,下载/预览均走解析后地址)
|
|
1219
1356
|
- 配套 DTO 类型:`FvCommonSessionItem` / `FvCommonMessage` / `FvCommonSessionDetail` / `FvCommonMessagePage`(消费方直接调会话管理端点时用)
|
|
1220
1357
|
|
|
@@ -1226,7 +1363,7 @@ const adapter = FvCommonAdapter({
|
|
|
1226
1363
|
|
|
1227
1364
|
### useXStream()
|
|
1228
1365
|
|
|
1229
|
-
SSE 流消费:`startStream({ readableStream, transformStream? })`、`cancel()`、`data: Ref<SSEEvent[]>`、`error`、`isLoading
|
|
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 边界归一化与流末多字节残码冲刷。
|
|
1230
1367
|
|
|
1231
1368
|
### useSend() / XRequest
|
|
1232
1369
|
|