@fv-ui/ai-chat 1.4.2 → 1.5.1

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
@@ -405,6 +405,7 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
405
405
  | size | number \| string | 0 | 文件大小(字节自动格式化为 B/KB/MB;字符串原样展示;0 不显示) |
406
406
  | url | string | '' | 图片地址(image 模式缩略图) |
407
407
  | status | 'loading' \| 'success' \| 'error' | 'success' | loading spinner / error 红边 |
408
+ | errorText | string | '' | 失败原因红字(error 态展示于卡片下方,超宽截断 title 全文) |
408
409
  | imageSize | string | '' | 缩略图尺寸(width/height 同值) |
409
410
  | onDelete | () => void | — | 删除按钮回调 |
410
411
  | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
@@ -424,6 +425,8 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
424
425
  | tip | string | '' | 内联提示文案 |
425
426
  | count | number | 0 | 最大附件数(超出走 @exceed;0 不限) |
426
427
  | beforeUpload | (file) => boolean \| Promise<boolean> | — | 上传前校验,返回 false 拦截 |
428
+ | upload | (file, item) => Promise\<Partial\<AttachmentItem\> \| undefined \| void\> \| ... | — | 上传钩子(先传后发):选文件即调——入列即 loading,成功返回附件描述(含服务端附件 id)回填列表项置 success,失败(抛错/resolve 错误文案串)置 error 带失败原因(可重传再走钩子);缺省不调(纯本地待发列表,入列直接 success) |
429
+ | disabled | boolean | false | 整体禁用(触发按钮不可点;生成中锁定输入场景,单飞行闸语义) |
427
430
  | layout | 'inline' \| 'triggerOnly' \| 'listOnly' | 'inline' | 布局:inline 回形针+列表+提示一行;triggerOnly 只渲染回形针按钮;listOnly 只渲染文件列表(拆分布局供整框组合:按钮进操作栏、列表进输入区上方) |
428
431
  | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
429
432
 
@@ -432,6 +435,7 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
432
435
  | update:modelValue / change | 列表变化(全量数组) |
433
436
  | exceed | (file) 超出 count |
434
437
  | delete | (item) 删除某项 |
438
+ | uploaded | (item, result?) 上传钩子落定(单项):成功回填后的列表项 + 上传结果;失败时 result 为 undefined(失败原因在 item.errMessage,FilesCard 红字展示) |
435
439
 
436
440
  | Slot | 说明 |
437
441
  | --- | --- |
@@ -518,6 +522,9 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
518
522
  | allowAttachments | boolean | false | 开启输入区附件上传(回形针在操作栏左侧与提交按钮同行,已选列表在输入框上方;只传附件不输文字也可提交) |
519
523
  | accept | string | '' | 附件 input accept 属性(透传 Attachments),如 'image/*' |
520
524
  | attachmentLimit | number | 0 | 附件数量上限(0 不限,超限走 @attachment-exceed) |
525
+ | uploadAttachment | (file, item) => Promise\<Partial\<AttachmentItem\> \| string \| undefined \| void\> \| ... | undefined | 附件上传钩子(先传后发):选文件即调,成功返回附件描述(id/name/type 等回填列表项,id 随发送进入 adapter 的 user 消息 files);返回错误文案串/抛错置 error 可重传。缺省不调(附件仅本地待发展示,不落服务端);上传中(loading 项)提交按钮禁用拒发,error 残留项不随发送 |
526
+ | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子(鉴权取流):消息气泡渲染附件 url 前调用,返回可直渲地址(如 JWT fetch 换 blob objectURL);缺省原样使用 url(blob/dataURL/公开地址)。远端 url 解析结果组件内按 url 缓存 + 在途去重;解析失败回落原 url 不阻塞渲染 |
527
+ | 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 取消评价(附言一并清空);👍↔👎 任意切换,后一次整体覆盖前一次(含附言);提交中按钮禁用防连点 |
521
528
  | theme | 'light' \| 'dark' \| 'auto' | 'light' | 主题(向 html 注入/移除 dark class) |
522
529
  | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(解析后注入整框后代) |
523
530
 
@@ -533,6 +540,10 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
533
540
  | error | (err, message?) 生成出错 |
534
541
  | branch-change | (dir, message) 分支切换 |
535
542
  | attachment-exceed | (file) 附件超过 attachmentLimit 上限 |
543
+ | attachment-uploaded | (item, { ok, message? }) 附件上传钩子落定(allowAttachments + uploadAttachment 场景):ok=false 时 message 为失败原因,宿主可 toast/埋点 |
544
+ | message-file-click | (file, message) 点击消息气泡附件 chips:默认行为——图片类经 resolveFileUrl 解析后打开内置 ElImageViewer 放大(同消息多图轮播),文档类无内置行为,宿主接此事件自行下载 |
545
+ | feedback-change | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR') 评价提交成功(乐观落定后触发;message.feedback 已更新),宿主可埋点/联动 |
546
+ | feedback-error | (message: string) 评价提交失败(钩子 reject/返回错误文案;乐观更新已回滚,message 为错误文案) |
536
547
  | scroll | (event) 消息区滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
537
548
 
538
549
  | Slot | 说明 |
@@ -597,11 +608,16 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
597
608
  | showTime | boolean | true | 显示消息时间(透传 AiMessage;时间源 createdTime 优先,缺省回落 createdAt。助手消息生成中不显示,打完字后才显示) |
598
609
  | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传 AiMessage) |
599
610
  | autoCollapse | boolean | true | 正文出完自动收起思考链(透传 AiMessage;status 落 done 且正文打完才收;error 不收) |
611
+ | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子(透传 AiMessage;鉴权取流换可直渲地址,见 AiChat) |
612
+ | feedbackHandler | (message, action, comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子(透传 AiMessage;语义见 AiChat,缺省不渲染 👍/👎) |
600
613
  | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
601
614
 
602
615
  | Event | 说明 |
603
616
  | --- | --- |
604
617
  | select / copy / regenerate / branch-change | 建议选中 / 复制 / 重生成 / 分支切换,载荷同 AiChat |
618
+ | followup-select | (item, message) 点击追问建议 chip(透传 AiMessage,载荷同 AiChat) |
619
+ | message-file-click | (file, message) 点击消息附件 chips(透传 AiMessage;图片类默认打开内置放大预览,文档类宿主自行下载) |
620
+ | feedback-change / feedback-error | 评价提交成功(message, action)/ 失败(错误文案;透传 AiMessage,语义见 AiChat) |
605
621
  | scroll | (event) 滚动容器滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
606
622
 
607
623
  | Slot | 说明 |
@@ -653,6 +669,8 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
653
669
  | showTime | boolean | true | 显示消息时间(操作区按钮之后;时间源:message.createdTime(秒级/毫秒级时间戳或 ISO 字符串自动识别)优先,缺省回落 message.createdAt;两者皆无则不渲染。助手消息 SSE 生成中不显示,正文打完字(未启用打字机则落定)后才显示;error 即显;user 消息恒显示) |
654
670
  | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传消息与已归一为 ms 的时间戳;缺省 'YYYY-MM-DD HH:mm',本机时区) |
655
671
  | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(透传 Markdown/Typewriter;命中语言的代码块右上角注入按钮,点击行为由消费方事件委托实现) |
672
+ | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子:渲染附件 url 前调用,返回可直渲地址(如 JWT fetch 换 blob objectURL);缺省原样使用 url(blob/dataURL/公开地址),远端地址解析结果按 url 缓存 + 在途去重,失败回落原 url |
673
+ | feedbackHandler | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR', comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子:仅 assistant 最终回答行(role=assistant 且 status=done,error/中断/生成中不渲染)渲染 👍/👎,缺省不渲染按钮。点击 👍 直接提交,点击 👎 弹附言层(≤500 字可跳过),再次点击当前态按钮发 CLEAR;乐观更新——先翻转 message.feedback 再调钩子,失败回滚并经 feedback-error 上抛,成功经 feedback-change 上抛;返回 resolved 即成功,返回错误文案串/抛错均视为失败 |
656
674
  | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
657
675
 
658
676
  > 用户消息操作区:恒渲染复制按钮,默认透明,鼠标移上消息(或键盘聚焦)时浮现(open-webui 交互)。
@@ -661,6 +679,10 @@ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
661
679
  | --- | --- |
662
680
  | copy / regenerate / branch-change | (message) / (message) / (dir, message) |
663
681
  | followup-select | (item, message) 点击追问建议 chip(item 为建议文本;仅链尾 assistant 消息渲染 chips,status 落 done 后可点;AiChat 内部已接住转 send,直接用 AiMessage 时的消费方需自行接管发送) |
682
+ | file-click | (file, message) 点击附件 chips:图片类默认打开内置 ElImageViewer 放大(同消息多图轮播,url 经 resolveFileUrl 解析);文档类无内置行为,宿主接此事件自行下载 |
683
+ | feedback-change | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR') 评价提交成功(乐观落定后触发;message.feedback 已更新,宿主可埋点/联动) |
684
+ | feedback-error | (message: string) 评价提交失败(钩子 reject/返回错误文案;乐观更新已回滚,message 为错误文案) |
685
+ | typing | 打字机输出中(流式期间节奏性触发) |
664
686
 
665
687
  | Slot | 说明 |
666
688
  | --- | --- |
@@ -744,6 +766,8 @@ const adapter = FvCommonAdapter({
744
766
  - `message_end` 的 `messageId`(最终文本行 id)经 `onBackendMessageId` 回填到 `MessageNode.backendId`——多轮工具循环下与 `message_start` 的首轮 id 不同,UI 落库/对账以它为准
745
767
  - `tool` 事件经 `onTool` → `useChat.onToolEvent` → `AiChat @tool-event` 上抛,消费方展示「正在查询库存…」等中间态
746
768
  - 追问建议(V58+):`suggestions` 事件(流式收尾 0..1 次,最后一个 delta 后、message_end 前,载荷 `{items: string[]}`)经可选 `onSuggestions` 上抛,`useChat` 回写 `MessageNode.suggestions`,AiMessage 在链尾消息渲染追问 chips;开关关闭/模型未产出/中断/失败无此事件;历史恢复用导出的 `parseSuggestions(raw)` 安全解析 `FvCommonMessage.suggestions`(JSON 数组原文透传,脏数据按无建议)
769
+ - 消息评价(V58+):`FvCommonMessage.feedback`(LIKE/DISLIKE,未评价/旧数据恒 null)、`feedbackComment`(附言 ≤500 字)、`feedbackTime`(评价落库时间)三字段同款容错;历史恢复由消费方映射为 `MessageNode.feedback` 灌入展示;评价提交走独立端点(POST /message/feedback),不经本适配器——接 `AiChat` 的 `feedbackHandler` 钩子即可
770
+ - 附件快照(1.4.1+):user 行 `FvCommonMessage.attachments`(id/originalName/type/suffix/sizeBytes/downloadUrl,旧数据/无附件恒 null),历史回放映射 `MessageNode.files` 渲染 chips(downloadUrl 需鉴权取流时配 `resolveFileUrl` 钩子)
747
771
  - 配套 DTO 类型:`FvCommonSessionItem` / `FvCommonMessage` / `FvCommonSessionDetail` / `FvCommonMessagePage`(消费方直接调会话管理端点时用)
748
772
 
749
773
  ### useMessages(initial?)
@@ -879,12 +903,12 @@ configureLocale(jaJP)
879
903
  | welcome | greetingPrefix / greetingName / description | 你好,我是 ␣ / Gizmo / 我可以帮你查询数据、分析问题、生成报表、以及执行系统操作,让生产管理更高效。 | Hello, I am ␣ / Gizmo / I can help you query data, analyze problems, generate reports, and perform system operations... |
880
904
  | sender | clear / stop / send / speech / recordCancel / recordConfirm / micUnavailable / inputPlaceholder | 清空 / 停止 / 发送 / 语音输入 / 取消录音 / 确认录音 / 无法访问麦克风 / 输入你的问题,查询数据、分析问题或生成报表… | Clear / Stop / Send / Voice input / Cancel recording / Confirm recording / Microphone unavailable / Ask a question — query data, analyze problems, or generate reports… |
881
905
  | editorSender | clear / stop / send / inputPlaceholder / selectTagTitle / loading / tagTip | 清空 / 停止 / 发送 / 请输入 / 选择标签 / 加载中… / 填写内容后回车确认 | Clear / Stop / Send / Type something... / Select a tag / Loading... / Type and press Enter to confirm |
882
- | attachments | add / retry | 添加附件 / 重传 | Add attachment / Retry |
906
+ | attachments | add / retry / uploading | 添加附件 / 重传 / 上传中… | Add attachment / Retry / Uploading… |
883
907
  | filesCard | remove | 删除 | Remove |
884
908
  | conversations | menuLabel / rename / delete / renameTitle / renamePrompt / renamePlaceholder / deleteTitle / deleteConfirm | 会话操作 / 重命名 / 删除 / 重命名会话 / 请输入新的会话名称 / 请输入名称 / 删除会话 / 确定删除会话「{label}」吗?... | Conversation actions / Rename / Delete / Rename conversation / Enter a new conversation name / Enter a name / Delete conversation / Delete "{label}"? ... |
885
909
  | scroll | toBottom | 滚动到底部 | Scroll to bottom |
886
910
  | aiChat | modelPlaceholder / adapterMissing / generateFailed / exportUser / exportAssistant | 模型 / 未配置 adapter 或 baseURL / 生成失败 / 你 / 助手 | Model / Neither adapter nor baseURL is configured / Generation failed / You / Assistant |
887
- | aiMessage | copy / regenerate / prevBranch / nextBranch / defaultUserName / defaultAssistantName / querying / queried / generateFailed / loadingPhrases | 复制 / 重新生成 / 上一分支 / 下一分支 / 你 / Gizmo / 正在查询 / 已查询 / 生成失败 / [正在思考…, 正在整理思路…, 正在生成回答…] | Copy / Regenerate / Previous branch / Next branch / You / Gizmo / Querying / Queried / Generation failed / [Thinking..., Organizing thoughts..., Generating your answer...] |
911
+ | aiMessage | copy / regenerate / prevBranch / nextBranch / defaultUserName / defaultAssistantName / querying / queried / generateFailed / followups / loadingPhrases / feedback.{like, dislike, dislikeTitle, dislikePlaceholder, submit, skip, failed, cleared} | 复制 / 重新生成 / 上一分支 / 下一分支 / 你 / Gizmo / 正在查询 / 已查询 / 生成失败 / 追问建议 / [正在思考…, 正在整理思路…, 正在生成回答…] / 点赞 / 点踩 / 告诉 AI 哪里不好 / 补充具体原因,帮助 AI 改进(选填) / 提交 / 跳过 / 评价提交失败 / 已取消评价 | Copy / Regenerate / Previous branch / Next branch / You / Gizmo / Querying / Queried / Generation failed / Follow-up suggestions / [Thinking..., Organizing thoughts..., Generating your answer...] / Like / Dislike / Tell the AI what went wrong / Add details to help the AI improve (optional) / Submit / Skip / Failed to submit feedback / Feedback removed |
888
912
  | aiArtifacts | copy / download / fullscreen / close | 复制 / 下载 / 全屏 / 关闭 | Copy / Download / Fullscreen / Close |
889
913
  | chat | fileTag / fileImageTag / filesSystemPrompt / toolDuration / continuePrompt | [附件] {name} / (图片) / 用户随消息提供了以下文件:\n{files} / 用时 {s} / 请基于以上内容继续完成回答... | [File] {name} / ␣(image) / The user provided... / Took {s} / Continue completing... |
890
914
  | errors | requestFailed / sessionIdMissing / noBody / generateFailed / recordUnsupported / speechError | 请求失败 / 缺少 sessionId(...) / 响应无 body / 生成失败 / 当前环境不支持音频录制 / 语音识别错误: {error} | Request failed / sessionId is missing... / Response has no body / Generation failed / Audio recording... / Speech recognition error: {error} |
@@ -973,7 +997,7 @@ A:FvMarkdown 依赖浏览器 `window`(DOMPurify 消毒),不支持服务端首渲
973
997
 
974
998
  ## 类型与导出
975
999
 
976
- 包入口导出全部组件、`useChat`/`useMessages`/`useXStream`/`useSend`/`XRequest`/`useRecord`、`OpenAIAdapter`、`FvCommonAdapter`(+ `FvCommonError` 及配套 DTO 类型)、`createMessageTree`、`createLocalStorageAdapter`/`createMemoryAdapter`、`createSSEParser`、`configureLocale`/`zhCN`/`enUS`(国际化)及全部公共类型(`MessageNode`、`ChatAdapter`、`ChatFile`、`MessageUsage`、`SSEEvent`、`LocaleMessages`、`LocaleInput`、`DeepPartialLocale` 等),消费方:
1000
+ 包入口导出全部组件、`useChat`/`useMessages`/`useXStream`/`useSend`/`XRequest`/`useRecord`、`OpenAIAdapter`、`FvCommonAdapter`(+ `FvCommonError` 及配套 DTO 类型)、`parseSuggestions`(追问建议 JSON 安全解析)、`createMessageTree`、`createLocalStorageAdapter`/`createMemoryAdapter`、`createSSEParser`、`configureLocale`/`zhCN`/`enUS`(国际化)及全部公共类型(`MessageNode`、`ChatAdapter`、`ChatFile`、`MessageFeedback`、`FeedbackHandler`、`MessageUsage`、`SSEEvent`、`LocaleMessages`、`LocaleInput`、`DeepPartialLocale` 等),消费方:
977
1001
 
978
1002
  ```ts
979
1003
  import { FvAiChat, OpenAIAdapter, useChat } from '@fv-ui/ai-chat'