@fv-ui/ai-chat 0.14.1 → 1.1.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,915 +1,951 @@
1
- # @fv-ui/ai-chat
2
-
3
- ![version](https://img.shields.io/badge/version-0.1.0-blue)
4
- ![vue](https://img.shields.io/badge/vue-%5E3.4.0-brightgreen)
5
- ![element-plus](https://img.shields.io/badge/element--plus-%5E2.7.0-blue)
6
-
7
- 基于 Vue 3 + Element Plus 的 AI 对话组件库,复刻 element-plus-x 与 open-webui 对话框:从底层气泡、发送框、Markdown 渲染,到上层的对话整框(`<FvAiChat>`)、分支树消息、Artifacts 预览,一次给全。
8
-
9
- - 14 个基础组件(Bubble/Sender/Markdown/Thinking/...)自由拼装
10
- - 对话应用层整框 `<FvAiChat>`:顶栏模型多选、消息列表、分支切换、Artifacts 面板、发送停止一体化
11
- - 树形消息模型(同构 open-webui):一条提问可挂多个模型回答,分支可切换、可重生成
12
- - `ChatAdapter` 适配器协议:内置 OpenAI 兼容实现,可替换自研后端/Ollama
13
- - 流式打字机、思考链折叠、KaTeX/代码高亮(Prism)开箱即用
14
-
15
- ## 安装
16
-
17
- ```bash
18
- pnpm add @fv-ui/ai-chat
19
- ```
20
-
21
- peerDependencies:`vue ^3.4.0`、`element-plus ^2.7.0`、`@element-plus/icons-vue ^2.3.0`。
22
-
23
- ## 快速开始
24
-
25
- ```ts
26
- // main.ts —— 需要先引入 element-plus(组件库依赖其组件与暗色变量)
27
- import ElementPlus from 'element-plus'
28
- import 'element-plus/dist/index.css'
29
- import { createApp } from 'vue'
30
- import App from './App.vue'
31
-
32
- createApp(App).use(ElementPlus).mount('#app')
33
- ```
34
-
35
- ```vue
36
- <!-- App.vue -->
37
- <script setup lang="ts">
38
- import { FvAiChat } from '@fv-ui/ai-chat'
39
- import '@fv-ui/ai-chat/dist/style.css'
40
- </script>
41
-
42
- <template>
43
- <FvAiChat
44
- title="AI 助手"
45
- base-url="https://api.deepseek.com/v1"
46
- api-key="sk-xxx"
47
- model="deepseek-chat"
48
- style="height: 600px"
49
- />
50
- </template>
51
- ```
52
-
53
- `<FvAiChat>` 未传 `adapter` 时,用 `baseURL`/`apiKey`/`model` 构造内置 `OpenAIAdapter`(走 `/chat/completions`,SSE 流式)。两个都缺省时发送会报"未配置 adapter 或 baseURL"。
54
-
55
- ## 基础组件层 API
56
-
57
- ### FvMarkdown
58
-
59
- Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
60
-
61
- | Prop | 类型 | 默认 | 说明 |
62
- | --- | --- | --- | --- |
63
- | content | string | —(必填) | Markdown 源文本 |
64
- | mdPlugins | PluginWithParams[] | — | 额外 markdown-it 插件 |
65
- | highlight | (str, lang) => string | 内置 Prism | 自定义代码高亮 |
66
- | isTyping | boolean | — | 打字机模式样式钩子(透传占位) |
67
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
68
-
69
- | Ref | 说明 |
70
- | --- | --- |
71
- | getHtml() | 取当前渲染后的 HTML 字符串 |
72
-
73
- ### Typewriter
74
-
75
- 打字机输出,支持续打/重打/雾化遮罩。
76
-
77
- | Prop | 类型 | 默认 | 说明 |
78
- | --- | --- | --- | --- |
79
- | content | string | —(必填) | 全文(流式时增量传入,子集扩展自动续打) |
80
- | isMarkdown | boolean | false | 走 FvMarkdown 渲染(此时 suffix 不追加) |
81
- | isFog | boolean \| { bgColor?; width? } | false | 打字中尾部雾化遮罩 |
82
- | typing | boolean \| { step?; interval?; suffix? } | false | 开启打字机;对象形态可配步长/间隔/光标后缀 |
83
- | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(isMarkdown 模式透传 Markdown) |
84
- | locale | LocaleInput | undefined | 语言包(透传内嵌 Markdown 的代码块「预览」按钮文案) |
85
-
86
- | Event | 说明 |
87
- | --- | --- |
88
- | start / writing / finish | 开始打字 / 每次推进 / 全部打完 |
89
-
90
- | Ref | 说明 |
91
- | --- | --- |
92
- | interrupt() / continue() / restart() / destroy() | 暂停 / 继续 / 重打 / 重置清空 |
93
- | renderedContent / isTyping / progress | 已输出文本 / 是否打字中 / 进度 0-1 |
94
-
95
- ### Bubble
96
-
97
- 单条气泡(内部按需挂载 Typewriter/Markdown)。
98
-
99
- | Prop | 类型 | 默认 | 说明 |
100
- | --- | --- | --- | --- |
101
- | content | string | '' | 气泡内容 |
102
- | placement | 'start' \| 'end' | 'start' | start 靠左 / end 靠右 |
103
- | loading | boolean | false | 加载态(三点动画,可被 #loading 覆盖) |
104
- | typing | boolean \| TypingConfig | false | 打字机模式(透传 Typewriter) |
105
- | isMarkdown | boolean | false | 内容按 Markdown 渲染 |
106
- | isFog | boolean \| { bgColor?; width? } | false | 雾化(自定义气泡背景时传 bgColor) |
107
- | variant | 'filled' \| 'borderless' \| 'outlined' \| 'shadow' | 'filled' | 气泡样式 |
108
- | shape | 'round' \| 'corner' | 'round' | 圆角 / 方角 |
109
- | avatar | string | '' | 头像图片地址 |
110
- | avatarSize | ElAvatar size \| number | '' | 头像尺寸 |
111
- | avatarGap | string | '12px' | 头像与内容间距 |
112
- | avatarShape | 'circle' \| 'square' | 'circle' | 头像形状 |
113
- | avatarIcon | Component | — | 头像图标(与 avatar 冲突时优先) |
114
- | avatarSrcSet / avatarAlt | string | '' / '' | 头像 srcSet/alt |
115
- | avatarFit | 'fill' \| 'contain' \| 'cover' \| 'none' \| 'scale-down' | 'cover' | 头像填充方式(el-avatar fit) |
116
- | noPadding | boolean | false | 内容区去内边距 |
117
- | noStyle | boolean | false | 去气泡样式(透明/无框/无阴影) |
118
-
119
- | Event | 说明 |
120
- | --- | --- |
121
- | avatar-error | 头像加载失败 |
122
- | start / writing / finish | typing 模式下的打字机事件透传 |
123
-
124
- | Slot | 说明 |
125
- | --- | --- |
126
- | avatar / header / content / loading / footer | 自定义头像 / 头部 / 内容(优先于 content prop)/ 加载态 / 底部 |
127
-
128
- | Ref | 说明 |
129
- | --- | --- |
130
- | interrupt / continue / restart / destroy | Typewriter 方法转发(非 typing 模式为 no-op) |
131
- | renderedContent / isTyping / progress | Typewriter 状态转发 |
132
- | twInstance | 内部 Typewriter 原始实例(BubbleList @complete 透传用) |
133
-
134
- ### BubbleList
135
-
136
- 气泡列表 + 吸底/回底按钮。
137
-
138
- | Prop | 类型 | 默认 | 说明 |
139
- | --- | --- | --- | --- |
140
- | list | BubbleListItemProps[] | [] | 列表项(Bubble props + 必填 key) |
141
- | maxHeight | string | '' | 滚动容器最大高度(如 '350px'/'60vh') |
142
- | alwaysShowScrollbar | boolean | false | 始终显示滚动条 |
143
- | showBackButton | boolean | true | 是否显示回底按钮 |
144
- | backButtonThreshold | number | 80 | 距底超过该像素显示回底按钮 |
145
- | btnLoading | boolean | false | 回底按钮加载态 |
146
- | btnColor | string | '' | 回底按钮颜色(el-button color) |
147
- | backButtonPosition | { bottom?; left? } | {} | 回底按钮位置偏移 |
148
- | btnIconSize | number | 16 | 回底按钮图标尺寸 |
149
- | triggerIndices | 'only-last' \| 'all' \| number[] | 'only-last' | @complete 触发索引 |
150
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
151
-
152
- | Event | 说明 |
153
- | --- | --- |
154
- | complete | (typewriterInstance, index) 打字完成(按 triggerIndices 过滤后上抛) |
155
-
156
- | Slot | 说明 |
157
- | --- | --- |
158
- | avatar / header / content / loading / footer | 透传给每个 Bubble,作用域 { item, index } |
159
-
160
- | Ref | 说明 |
161
- | --- | --- |
162
- | scrollToTop() / scrollToBottom() / scrollToBubble(index) | 滚动控制 |
163
-
164
- ### Sender
165
-
166
- 输入发送框。
167
-
168
- | Prop | 类型 | 默认 | 说明 |
169
- | --- | --- | --- | --- |
170
- | modelValue | string(v-model) | '' | 输入值(缺省内部自持) |
171
- | placeholder | string | '' | 占位文案 |
172
- | autosize | { minRows?; maxRows? } | {} | 自增高(行高 22px) |
173
- | submitType | 'enter' \| 'shiftEnter' \| 'cmdOrCtrlEnter' \| 'altEnter' | 'enter' | 提交按键模式 |
174
- | loading | boolean | false | 加载态(发送键变停止键,输入区禁用) |
175
- | disabled | boolean | false | 禁用(阻断提交) |
176
- | readOnly | boolean | false | 只读 |
177
- | clearable | boolean | false | 显示清空按钮 |
178
- | round | boolean | true | 主按钮(发送/停止)为圆形(element-plus circle;false 时方按钮,停止键光带沿方框流转) |
179
- | shadow | boolean | false | 输入区阴影效果(浮起感,聚焦时加深) |
180
- | inputWidth | string | '' | 输入区宽度(variant=default 时有效) |
181
- | variant | 'default' \| 'updown' | 'default' | default 同排 / updown 上输入下操作栏 |
182
- | submitBtnDisabled | boolean | false | 附加禁用发送按钮 |
183
- | triggerStrings | string[] | [] | 指令触发串(光标前命中弹指令框) |
184
- | triggerPopoverVisible | boolean(v-model:triggerPopoverVisible) | false | 指令弹框显隐 |
185
- | triggerPopoverWidth / triggerPopoverLeft | string | '' | 指令弹框宽度 / left 偏移 |
186
- | triggerPopoverOffset | number | 0 | 弹框距触发字符偏移量 |
187
- | triggerPopoverPlacement | ElPopover placement | 'top-start' | 弹框位置 |
188
- | allowSpeech | boolean | false | 开启语音输入:麦克风按钮 → 录音条(波形+时长,Esc 取消)→ 确认后转写文本插入光标处;浏览器 SpeechRecognition 实时转写 |
189
- | allowEmptySubmit | boolean | false | 允许空内容提交(附件场景:只发文件不输文字) |
190
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
191
-
192
- | Event | 说明 |
193
- | --- | --- |
194
- | update:modelValue / change | 输入值变化 |
195
- | submit | (value) 提交(提交后内部清空) |
196
- | cancel | 点击停止按钮 |
197
- | trigger | (keyword, visible) 命中指令串 |
198
- | recording-change | 语音录制状态变化(预留) |
199
- | paste-file | (file) 粘贴文件 |
200
- | update:triggerPopoverVisible | 指令弹框显隐同步 |
201
-
202
- | Slot | 说明 |
203
- | --- | --- |
204
- | header / footer | 头部/底部(配合 ref.openHeader/closeHeader) |
205
- | prefix | 输入区前缀 |
206
- | action-list | 自定义操作区(存在时隐藏内置按钮) |
207
- | action-left | 操作栏左侧附加区(与提交按钮同行靠左,如附件回形针) |
208
- | trigger | 指令弹框内容(作用域 { keyword }) |
209
-
210
- | Ref | 说明 |
211
- | --- | --- |
212
- | submit() / cancel() / clear() | 提交 / 停止 / 清空 |
213
- | focus(pos?) / blur() | pos: 'all' 全选 \| 'start' 头 \| 'end' 尾(缺省 end) |
214
- | openHeader() / closeHeader() | 显隐 #header 插槽 |
215
-
216
- ### MentionSender
217
-
218
- 带 @提及 的 Sender(键盘 ↑↓ 导航 / Enter 确认 / Esc 关闭)。
219
-
220
- | Prop | 类型 | 默认 | 说明 |
221
- | --- | --- | --- | --- |
222
- | modelValue | string(v-model) | '' | 输入值 |
223
- | userList | MentionUserInfo[] | [] | @ 触发的候选用户(id/name/avatar/pinyin) |
224
- | customTrigger | MentionCustomTrigger[] | [] | 自定义触发组 { dialogTitle, prefix, tagList } |
225
- | asyncMatchFun | (search) => Promise<MentionUserInfo[]> | — | 异步候选(存在时防抖 300ms,后端过滤) |
226
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(候选加载文案);内嵌 Sender 的文案经祖先注入(如 AiChat)或全局设置生效 |
227
-
228
- 事件:`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)。
229
-
230
- | Ref | 说明 |
231
- | --- | --- |
232
- | submit / cancel / clear / focus / blur / openHeader / closeHeader | Sender 方法转发 |
233
- | setUserTag(userId) | 光标处程序化插入 @用户 |
234
- | setCustomTag(prefix, id) | 光标处插入自定义触发标签 |
235
-
236
- ### EditorSender
237
-
238
- 富文本标签编辑器(contenteditable),open-webui 风格标签芯片。
239
-
240
- | Prop | 类型 | 默认 | 说明 |
241
- | --- | --- | --- | --- |
242
- | placeholder | string | '' | 占位文案 |
243
- | device | 'pc' \| 'h5' | 'pc' | 设备形态(仅影响样式) |
244
- | autoFocus | boolean | false | 挂载后聚焦到末尾 |
245
- | variant | 'default' \| 'updown' | 'default' | 布局形态 |
246
- | userList | EditorUser[] | [] | @ 候选用户 |
247
- | customTrigger | EditorCustomTrigger[] | [] | 自定义触发组 |
248
- | selectList | EditorSelectGroup[] | [] | 选择标签分组(openSelectDialog 弹窗数据) |
249
- | maxLength | number | 0 | 纯文本最大长度(0 不限;性能开销大,仅显式开启) |
250
- | submitType | 'enter' \| 'shiftEnter' | 'enter' | 提交按键模式 |
251
- | customStyle | Record<string, any> | {} | 根节点自定义样式 |
252
- | loading | boolean | false | 加载态(发送键变停止键) |
253
- | disabled | boolean | false | 禁用 |
254
- | clearable | boolean | false | 显示清空按钮 |
255
- | headerAnimationTimer | number | 300 | 头部过渡时长(ms) |
256
- | asyncMatchFun | (search) => Promise<EditorUser[]> | — | 异步 @ 候选(防抖 300ms) |
257
- | customDialog | boolean | false | 选择标签不自弹内置弹窗,仅上抛 show-select-dialog |
258
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
259
-
260
- | Event | 说明 |
261
- | --- | --- |
262
- | submit / change | (SubmitResult) SubmitResult = { text, html, tags: { userTags, selectTags, inputTags, customTags } } |
263
- | cancel | 点击停止按钮 |
264
- | show-at-dialog / show-select-dialog / show-tag-dialog | 各弹层显隐 |
265
-
266
- | Slot | 说明 |
267
- | --- | --- |
268
- | header / footer / prefix / action-list | 同 Sender |
269
- | tag-tip | 输入标签 tip 弹层内容(作用域 { nodeId }) |
270
-
271
- | Ref | 说明 |
272
- | --- | --- |
273
- | getCurrentValue() | 取 { text, html, tags } |
274
- | focusToStart() / focusToEnd() / blur() / selectAll() / clear() | 光标与清空 |
275
- | setText(text) / setHtml(html) / setMixTags(rows) | 程序化写入 |
276
- | setUserTag(id) / setCustomTag(prefix, id) / setInputTag(id, name) / setSelectTag(list) | 插入各类标签 |
277
- | customSetUser(user) / customSetTag(tag) | 外部直传对象插入(不经列表查表) |
278
- | updateSelectTag(method, options) | 选择标签更新:'insertTag'/'updateTagValue'/'deleteTag'/'updateTagStyle' |
279
- | openSelectDialog() / openTipTag(nodeId?) / closeTipTag() | 弹窗控制 |
280
- | openHeader() / closeHeader() | 显隐 #header |
281
- | chat / opNode(method, options) / chatState() | 底层文档模型:chat.insert/update/delete/append;opNode 按方法名分发 |
282
-
283
- ### Thinking
284
-
285
- 思考链折叠面板。
286
-
287
- | Prop | 类型 | 默认 | 说明 |
288
- | --- | --- | --- | --- |
289
- | modelValue | boolean(v-model) | false | 展开/收起 |
290
- | content | string | '' | 思考内容(常配合 #content 插槽嵌 FvMarkdown) |
291
- | status | 'start' \| 'thinking' \| 'end' \| 'error' | 'start' | 思考状态 |
292
- | disabled | boolean | false | 禁用切换 |
293
- | autoCollapse | boolean | false | status 变为 end 时自动收起 |
294
- | hideHeader | boolean | false | 隐藏折叠头(单 item 链平铺形态):不渲染切换按钮,内容区常驻展开 |
295
- | buttonWidth | string | '' | 切换按钮区宽度 |
296
- | maxWidth | string | '' | 内容区最大宽度 |
297
- | color / backgroundColor | string | '' | 前景色 / 背景色 |
298
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
299
-
300
- | Event | 说明 |
301
- | --- | --- |
302
- | update:modelValue | 展开/收起同步 |
303
-
304
- | Slot | 说明 |
305
- | --- | --- |
306
- | status-icon / label / arrow | 自定义状态图标 / 文案 / 箭头 |
307
- | content / error | 思考内容 / error 态内容 |
308
-
309
- | Ref | 说明 |
310
- | --- | --- |
311
- | modelValue / toggle() | 展开状态 / 手动切换 |
312
-
313
- ### ThoughtChain
314
-
315
- 思维链步骤条。text 步(kind: 'text')为「正在思考/思考完成」标题行 + 可折叠 description 滚动区(默认收起;展开时 ElScrollbar 限高 269px,流式期间自动滚底;内容被滚动裁掉的方向在上/下缘渲染 35px 渐隐条 `scroll-edge-fade-top` / `scroll-edge-fade-bottom`,贴顶/贴底各自隐藏);工具步 kind: 'tool' 为普通步骤行。
316
-
317
- | CSS 变量 | 默认 | 说明 |
318
- | --- | --- | --- |
319
- | --fv-chain-edge-fade-color | var(--el-bg-color) | text 步滚动区上/下缘渐隐条颜色(默认跟随页面底色,暗色模式经 element-plus 变量自动适配;思考链叠在非底色卡片上时可覆盖) |
320
-
321
- | Prop | 类型 | 默认 | 说明 |
322
- | --- | --- | --- | --- |
323
- | items | ThoughtChainItem[] | [] | 步骤项 { key, title?, status?: 'pending'/'success'/'loading'/'error', icon?, description?, kind?: 'tool'/'text', typing?, closed? } |
324
- | direction | 'vertical' \| 'horizontal' | 'vertical' | 排列方向 |
325
- | collapsible | boolean | false | 工具步长文案展开/收起(超 3 行截断 + 行尾「展开」) |
326
- | showDuration | boolean | false | 显示工具步用时 description(text 步 description 不受影响) |
327
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
328
-
329
- | Slot | 说明 |
330
- | --- | --- |
331
- | content | 覆盖默认 title/description(作用域 { item, index }) |
332
-
333
- ### Welcome
334
-
335
- 空态欢迎页。icon/name/description 均未传时显示内置品牌默认欢迎(「你好,我是 FVAI」问候高亮 + IP 形象动图 + 默认描述),逐 prop 独立覆盖。
336
-
337
- | Prop | 类型 | 默认 | 说明 |
338
- | --- | --- | --- | --- |
339
- | icon | string \| Component | '' | 图标(字符串为图片地址;未传渲染内置品牌动图:横排=欢迎吉祥物大图,纵排=待机动图) |
340
- | name | string | '' | 名称(未传回落内置问候语「你好,我是 FVAI」) |
341
- | description | string | '' | 描述(纯文本;未传回落内置默认描述) |
342
- | layout | 'vertical' \| 'horizontal' | 'vertical' | 布局:vertical 纵排(形象在上,待机动图)/ horizontal 横排(文案左对齐,欢迎吉祥物浮层悬于文案右上,空态欢迎形态,原型 .intro 同构) |
343
- | locale | LocaleInput | undefined | 语言包(内置欢迎文案) |
344
-
345
- | Slot | 说明 |
346
- | --- | --- |
347
- | icon / name / description | 覆盖对应区块 |
348
-
349
- ### CSS 变量
350
-
351
- | CSS 变量 | 默认 | 说明 |
352
- | --- | --- | --- |
353
- | --fv-welcome-icon-size | 纵排 96px | 内置品牌动图尺寸(纵排;横排吉祥物固定 108px×scale1.8 对齐原型) |
354
- | --fv-welcome-max-width | 860px | 空态欢迎块宽度(AiMessages 空态轴线,对齐原型 .welcome;文案/吉祥物/快捷条共用) |
355
- | --fv-welcome-desc-max-width | 590px | 横排描述文字最大宽度(原型 .intro p) |
356
-
357
- ### Prompts
358
-
359
- 建议 prompt 网格。
360
-
361
- | Prop | 类型 | 默认 | 说明 |
362
- | --- | --- | --- | --- |
363
- | prompts | PromptItem[] | [] | 建议项 { key(必填), label?, description?, icon?(EP 图标名字符串或组件), disabled? } |
364
- | title | string | '' | 网格标题 |
365
-
366
- | Event | 说明 |
367
- | --- | --- |
368
- | select | (item) 点击(disabled 项不触发) |
369
-
370
- | Slot | 说明 |
371
- | --- | --- |
372
- | default | 覆盖整卡(作用域 { item, index }) |
373
-
374
- ### FilesCard
375
-
376
- 单个文件卡片。文档模式按扩展名自动映射类型图标:pdf/doc/txt→文档、xls/csv→图表、ppt→演示、mp4→胶片、mp3→耳机、zip→文件夹、html/url→链接、apk→手机、exe→芯片,未命中回落通用文档图标。
377
-
378
- | Prop | 类型 | 默认 | 说明 |
379
- | --- | --- | --- | --- |
380
- | name | string | '' | 文件名 |
381
- | fileType | 'image' \| 'file' | 'file' | image 渲染缩略图,file 渲染文档图标卡 |
382
- | size | number \| string | 0 | 文件大小(字节自动格式化为 B/KB/MB;字符串原样展示;0 不显示) |
383
- | url | string | '' | 图片地址(image 模式缩略图) |
384
- | status | 'loading' \| 'success' \| 'error' | 'success' | loading spinner / error 红边 |
385
- | imageSize | string | '' | 缩略图尺寸(width/height 同值) |
386
- | onDelete | () => void | — | 删除按钮回调 |
387
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
388
-
389
- | Slot | 说明 |
390
- | --- | --- |
391
- | image | 覆盖图片区(默认 url 缩略图,无 url 渲染 Picture 占位) |
392
-
393
- ### Attachments
394
-
395
- 附件选择与列表(v-model)。
396
-
397
- | Prop | 类型 | 默认 | 说明 |
398
- | --- | --- | --- | --- |
399
- | modelValue | object[](v-model) | [] | 附件列表(项含 uid/name/size/url/fileType/status/raw) |
400
- | accept | string | '' | input accept,如 'image/*' |
401
- | tip | string | '' | 内联提示文案 |
402
- | count | number | 0 | 最大附件数(超出走 @exceed;0 不限) |
403
- | beforeUpload | (file) => boolean \| Promise<boolean> | — | 上传前校验,返回 false 拦截 |
404
- | layout | 'inline' \| 'triggerOnly' \| 'listOnly' | 'inline' | 布局:inline 回形针+列表+提示一行;triggerOnly 只渲染回形针按钮;listOnly 只渲染文件列表(拆分布局供整框组合:按钮进操作栏、列表进输入区上方) |
405
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
406
-
407
- | Event | 说明 |
408
- | --- | --- |
409
- | update:modelValue / change | 列表变化(全量数组) |
410
- | exceed | (file) 超出 count |
411
- | delete | (item) 删除某项 |
412
-
413
- | Slot | 说明 |
414
- | --- | --- |
415
- | list-item | 覆盖项渲染(作用域 { item, index }) |
416
- | list-thumb | 覆盖图片缩略图(作用域 { item, index }) |
417
-
418
- | Ref | 说明 |
419
- | --- | --- |
420
- | openSelect() | 程序化打开文件选择 |
421
- | retry(item) | error 项重新置为 loading(上传逻辑由外部接线) |
422
-
423
- ### Conversations
424
-
425
- 会话列表(按 group 分组)。
426
-
427
- | Prop | 类型 | 默认 | 说明 |
428
- | --- | --- | --- | --- |
429
- | items | ConversationItem[] | [] | 会话项 { key(必填), label(必填), group?, disabled? } |
430
- | active | string \| number(v-model:active) | undefined | 当前激活会话 key |
431
- | showBuiltInMenuType | 'hover' \| 'always' | 'hover' | 内置菜单按钮显隐方式 |
432
- | groupable | (a, b) => number | — | 分组排序比较器(缺省保持插入顺序) |
433
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
434
-
435
- | Event | 说明 |
436
- | --- | --- |
437
- | update:active / change | 选中会话(key / item) |
438
- | menu-command | ({ item, command: 'rename'/'delete', value? }) 菜单指令;rename 确认后带新名称 |
439
-
440
- | Slot | 说明 |
441
- | --- | --- |
442
- | group-title | 分组标题(作用域 { group }) |
443
- | item | 覆盖行内容(作用域 { item, active }) |
444
- | menu | 覆盖菜单项(默认重命名/删除;作用域 { item }) |
445
-
446
- | Ref | 说明 |
447
- | --- | --- |
448
- | handleMenuCommand({ item, command }) | 程序化触发菜单指令转发(纯转发,同步上抛 menu-command) |
449
- | renamePrompt(key) | 弹重命名输入框,确认后上抛 menu-command |
450
- | deleteConfirm(key) | 弹删除确认框,确认后上抛 menu-command |
451
-
452
- ## 对话应用层 API
453
-
454
- ### AiChat
455
-
456
- 对话整框:顶栏(标题+模型多选)、消息区(空态 Welcome/Prompts)、输入区(Sender)、可选 Artifacts 面板。
457
-
458
- | Prop | 类型 | 默认 | 说明 |
459
- | --- | --- | --- | --- |
460
- | model | string | '' | 默认模型(未传 models 时作为单模型) |
461
- | models | string[] | [] | 可选模型列表(有值时顶栏多选选择器) |
462
- | baseURL | string | '' | OpenAI 兼容服务地址(未传 adapter 时构造 OpenAIAdapter) |
463
- | apiKey | string | '' | 服务密钥 |
464
- | adapter | ChatAdapter | undefined | 聊天适配器(与 baseURL 二选一,优先) |
465
- | messages | MessageNode[](v-model:messages) | undefined | 消息链(半受控,见下) |
466
- | title | string | '' | 顶栏标题(同时作空态欢迎页名称;未传时欢迎页显示内置默认问候「你好,我是 FVAI」) |
467
- | showHeader | boolean | false | 显示顶栏(标题 + 模型选择器;models 多选选择器在顶栏内,需开启才可见) |
468
- | centerWelcome | boolean | true | 空态居中:未开始对话时欢迎内容与输入区整体垂直居中,首条消息后输入区恢复固定底部 |
469
- | showScrollButton | boolean | true | 显示滚到底部悬浮按钮(透传 AiMessages;距底超过 scrollButtonThreshold 时出现) |
470
- | scrollButtonThreshold | number | 100 | 滚到底部悬浮按钮显示阈值(px,透传 AiMessages) |
471
- | scrollThreshold | number | 100 | 用户上滚免打扰阈值(px,透传 AiMessages):距底不超过该值视为「钉在底部」,流式期间自动跟随滚动;调小可恢复更灵敏的跟随 |
472
- | showUserAvatar | boolean | true | 显示用户头像(false 时用户消息不渲染头像;助手头像不受影响) |
473
- | showUserName | boolean | true | 显示用户名称(false 时用户消息不渲染头部名称行;助手名称不受影响) |
474
- | showAssistantAvatar | boolean | true | 显示助手头像(false 时助手消息不渲染头像;用户头像不受影响) |
475
- | showAssistantName | boolean | true | 显示助手名称(false 时助手消息不渲染头部名称行;用户名称不受影响) |
476
- | userAvatar | string | '' | 用户头像图片 URL(空串回落内置图标;`user-avatar` 插槽优先) |
477
- | assistantAvatar | string | '' | 助手头像图片 URL(传入完全覆盖不分状态;空串按状态回落内置 GIF:thinking=fvai-thinking.gif,done/error=fvai-idle.gif;`assistant-avatar` 插槽优先) |
478
- | userName | string | '' | 用户名称(空串回落「你」;`user-name` 插槽优先) |
479
- | assistantName | string | '' | 助手名称(空串回落「小维」;`assistant-name` 插槽优先) |
480
- | placeholder | string | '' | 输入框占位 |
481
- | toolStepLabel | (toolName) => string | undefined | 工具名 → 步骤展示名(透传 useChat toolStepLabel) |
482
- | typing | boolean \| { step?; interval? } | false | 打字机(透传 AiMessages;仅 assistant 流式期间逐字平滑打出,落定/历史消息整段渲染) |
483
- | collapsible | boolean | false | 思考链工具步长文案展开/收起(透传 ThoughtChain;超 3 行截断 + 行尾「展开/收起」) |
484
- | showDuration | boolean | false | 显示工具步用时 description(透传 ThoughtChain;默认关闭) |
485
- | senderShadow | boolean | true | 输入区阴影效果(透传 Sender 的 shadow) |
486
- | suggestions | AiChatSuggestion[] | [] | 空态建议列表(Prompts 项,key 必填;空态快捷条为胶囊形态,description 不显示) |
487
- | features | AiChatFeatures | {} | 特性开关 { artifacts?, tts?, queue?, continueGenerate?, fullscreenEditor? }(当前仅 artifacts 生效);artifacts 传 `true` 用默认配置,传对象 `{ width?, minWidth?, maxWidth?, autoOpen?, codeBlockTrigger? }` 自定义:宽度三参控面板尺寸(默认 420px/360px/60%),autoOpen(默认 true)检测到代码块自动弹面板,codeBlockTrigger(默认 true)在消息 html/svg 代码块右上角显示「预览」按钮、点击打开对应面板 |
488
- | allowAttachments | boolean | false | 开启输入区附件上传(回形针在操作栏左侧与提交按钮同行,已选列表在输入框上方;只传附件不输文字也可提交) |
489
- | accept | string | '' | 附件 input accept 属性(透传 Attachments),如 'image/*' |
490
- | attachmentLimit | number | 0 | 附件数量上限(0 不限,超限走 @attachment-exceed) |
491
- | theme | 'light' \| 'dark' \| 'auto' | 'light' | 主题(向 html 注入/移除 dark class) |
492
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(解析后注入整框后代) |
493
-
494
- **v-model:messages 半受控语义**:外部 `messages` 仅在 setup 时一次性深拷贝灌入(用于恢复历史);组件内部每次变更全量上抛 `update:messages`(同帧去抖),父组件需经 v-model 回写维持单向数据流;父组件后续直接改 prop **不会**回灌生效。
495
-
496
- | Event | 说明 |
497
- | --- | --- |
498
- | update:messages | (MessageNode[]) 全量消息链(去抖后) |
499
- | send | (text, files?) 用户发送(allowAttachments 开启时 files 为降维后的 ChatFile[]) |
500
- | message-complete | (message) 链尾 assistant 生成完成 |
501
- | error | (err, message?) 生成出错 |
502
- | branch-change | (dir, message) 分支切换 |
503
- | attachment-exceed | (file) 附件超过 attachmentLimit 上限 |
504
-
505
- | Slot | 说明 |
506
- | --- | --- |
507
- | message-avatar / message-actions | 透传给 AiMessages(作用域见 AiMessage;message-avatar 优先于细分头像插槽) |
508
- | user-avatar / assistant-avatar | 自定义用户/助手头像(assistant-avatar 作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于同名 props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
509
- | user-name / assistant-name | 自定义用户/助手名称(作用域 { message },优先于同名 props) |
510
- | empty | 覆盖空态整区 |
511
- | scroll-button | 自定义滚到底部悬浮按钮整块(作用域 { scrollToBottom, awayFromBottom };覆盖后内置按钮与显隐逻辑均由插槽内容接管) |
512
- | scroll-button-icon | 仅自定义悬浮按钮图标内容(按钮本体/显隐不变) |
513
- | sender-prefix | 输入区前缀 |
514
-
515
- | Ref | 说明 |
516
- | --- | --- |
517
- | sendMessage(text, files?) | 程序化发送 |
518
- | stop() | 停止生成(保留半截内容,静默收口不发 complete/error) |
519
- | regenerate(messageId?) | 重生成(缺省链尾 assistant) |
520
- | appendToMessage(id, text) | 向指定消息追加文本 |
521
- | clearMessages() | 清空消息树 |
522
- | exportTxt() | 导出当前链为纯文本 |
523
- | openArtifact(key) | 程序化打开某个 artifact |
524
-
525
- ### AiMessages
526
-
527
- 消息列表(空态渲染 Welcome + Prompts),吸底滚动。
528
-
529
- | Prop | 类型 | 默认 | 说明 |
530
- | --- | --- | --- | --- |
531
- | messages | MessageNode[] | —(必填) | 当前链消息(根 → 焦点) |
532
- | nodes | Record<string, MessageNode> | {} | 全量节点表(分支计算需查父 childrenIds) |
533
- | icon | string \| Component | '' | 空态欢迎页图标 |
534
- | name | string | '' | 空态欢迎页名称 |
535
- | description | string | '' | 空态欢迎页描述 |
536
- | suggestions | AiMessagesSuggestion[] | [] | 空态建议列表 |
537
- | suggestionsTitle | string | '' | 空态建议区标题 |
538
- | scrollThreshold | number | 100 | 用户上滚免打扰阈值(px):距底不超过该值视为「钉在底部」,流式期间自动跟随滚动 |
539
- | showScrollButton | boolean | true | 显示滚到底部悬浮按钮(空态不渲染) |
540
- | scrollButtonThreshold | number | 100 | 距底超过该值(px)才显示滚到底部悬浮按钮 |
541
- | showActions | boolean | true | 显示消息操作按钮(复制/重生成) |
542
- | showBranchSwitch | boolean | true | 显示分支切换器 |
543
- | showUserAvatar | boolean | true | 显示用户头像(助手头像不受影响) |
544
- | showUserName | boolean | true | 显示用户名称(助手名称不受影响) |
545
- | showAssistantAvatar | boolean | true | 显示助手头像(用户头像不受影响) |
546
- | showAssistantName | boolean | true | 显示助手名称(用户名称不受影响) |
547
- | userAvatar | string | '' | 用户头像图片 URL(透传 AiMessage) |
548
- | assistantAvatar | string | '' | 助手头像图片 URL(透传 AiMessage;传入完全覆盖不分状态,空串按状态回落内置 GIF) |
549
- | userName | string | '' | 用户名称(透传 AiMessage) |
550
- | assistantName | string | '' | 助手名称(透传 AiMessage;空串回落「小维」) |
551
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
552
-
553
- | Event | 说明 |
554
- | --- | --- |
555
- | select / copy / regenerate / branch-change | 建议选中 / 复制 / 重生成 / 分支切换,载荷同 AiChat |
556
-
557
- | Slot | 说明 |
558
- | --- | --- |
559
- | empty | 覆盖空态整区 |
560
- | scroll-button | 自定义滚到底部悬浮按钮整块(作用域 { scrollToBottom, awayFromBottom };覆盖后内置按钮与显隐逻辑均由插槽内容接管) |
561
- | scroll-button-icon | 仅自定义悬浮按钮图标内容(按钮本体/显隐不变) |
562
- | message-avatar / message-actions | 透传给每条 AiMessage(message-avatar 优先于细分头像插槽) |
563
- | user-avatar / assistant-avatar | 自定义用户/助手头像(assistant-avatar 作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于同名 props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
564
- | user-name / assistant-name | 自定义用户/助手名称(作用域 { message },优先于同名 props) |
565
-
566
- | CSS 变量 | 默认 | 说明 |
567
- | --- | --- | --- |
568
- | --fv-messages-max-width | none | 滚动内容最大宽度;超出部分左右居中(内层 `.fv-messages-inner`,配合 `margin: 0 auto`) |
569
-
570
- | Ref | 说明 |
571
- | --- | --- |
572
- | scrollToBottom(smooth?) / scrollToTop() | 滚动控制 |
573
-
574
- ### AiMessage
575
-
576
- 单条消息(Markdown 正文 + 思考链折叠 + 附件 + 操作区)。
577
-
578
- | Prop | 类型 | 默认 | 说明 |
579
- | --- | --- | --- | --- |
580
- | message | MessageNode | —(必填) | 消息节点 |
581
- | branch | AiMessageBranchInfo | undefined | 分支元数据 { count, index };缺省视为单分支 |
582
- | showActions | boolean | true | 显示复制/重生成(仅 assistant) |
583
- | showBranchSwitch | boolean | true | 显示分支切换器(branch.count > 1 时) |
584
- | showUserAvatar | boolean | true | 显示用户头像(false 时用户消息不渲染头像块) |
585
- | showUserName | boolean | true | 显示用户名称(false 时用户消息不渲染头部名称行) |
586
- | showAssistantAvatar | boolean | true | 显示助手头像(false 时助手消息不渲染头像块) |
587
- | showAssistantName | boolean | true | 显示助手名称(false 时助手消息不渲染头部名称行) |
588
- | userAvatar | string | '' | 用户头像图片 URL(空串回落内置图标) |
589
- | assistantAvatar | string | '' | 助手头像图片 URL(传入完全覆盖不分状态;空串按状态回落内置 GIF:thinking=fvai-thinking.gif,done/error=fvai-idle.gif) |
590
- | userName | string | '' | 用户名称(空串回落「你」) |
591
- | assistantName | string | '' | 助手名称(空串回落「小维」) |
592
-
593
- > 用户消息操作区:恒渲染复制按钮,默认透明,鼠标移上消息(或键盘聚焦)时浮现(open-webui 交互)。
594
- | autoCollapse | boolean | true | Thinking autoCollapse 透传 |
595
- | typing | boolean \| { step?; interval? } | false | 打字机(透传 Typewriter;仅 assistant 流式期间生效,落定/历史消息整段渲染) |
596
- | collapsible | boolean | false | 思考链工具步长文案展开/收起开关(透传 ThoughtChain) |
597
- | showDuration | boolean | false | 显示工具步用时 description(透传 ThoughtChain;默认关闭) |
598
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
599
-
600
- | Event | 说明 |
601
- | --- | --- |
602
- | copy / regenerate / branch-change | (message) / (message) / (dir, message) |
603
-
604
- | Slot | 说明 |
605
- | --- | --- |
606
- | message-avatar | 自定义头像(作用域 { message };优先于细分头像插槽,两条角色消息均生效) |
607
- | user-avatar | 自定义用户头像(无作用域;优先于 userAvatar props) |
608
- | assistant-avatar | 自定义助手头像(作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于 assistantAvatar props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
609
- | user-name | 自定义用户名称(作用域 { message };优先于 userName props) |
610
- | assistant-name | 自定义助手名称(作用域 { message };优先于 assistantName props) |
611
- | message-files | 自定义附件渲染(作用域 { message, files }) |
612
- | message-actions | 自定义操作区(作用域 { message }) |
613
-
614
- | Ref | 说明 |
615
- | --- | --- |
616
- | message | 当前消息节点(computed) |
617
-
618
- ### AiArtifacts
619
-
620
- Artifacts 预览面板(iframe 沙箱,从消息 ```html / ```svg 代码块提取)。
621
-
622
- | Prop | 类型 | 默认 | 说明 |
623
- | --- | --- | --- | --- |
624
- | artifacts | AiArtifactItem[] | [] | artifact 列表 { key(必填), type: 'html'/'svg', content, title? } |
625
- | activeKey | string | '' | 当前展示的 key;为空时面板隐藏 |
626
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
627
-
628
- | Event | 说明 |
629
- | --- | --- |
630
- | close / change | 关闭 / 切换(key) |
631
- | navigate | (href) iframe 内点击外链被拦截上抛 |
632
-
633
- | Ref | 说明 |
634
- | --- | --- |
635
- | open(key) / close() | 程序化显隐 |
636
-
637
- ## Composables
638
-
639
- ### useChat(options)
640
-
641
- 聊天编排:发送 → 流式回填 → 队列/重生成/续写。
642
-
643
- ```ts
644
- import { useChat, zhCN, enUS } from '@fv-ui/ai-chat' // zhCN/enUS:内置语言包(可换成自建包)
645
-
646
- const lang = ref<'zh-CN' | 'en-US'>('zh-CN')
647
-
648
- const chat = useChat({
649
- adapter: () => OpenAIAdapter({ baseURL, apiKey }), // 实例或工厂;工厂每次 send 惰性取用
650
- models: () => selectedModels.value, // 数组或工厂;多模型并行生成兄弟分支
651
- initial: { messages, currentId }, // 恢复会话
652
- onToolEvent: (ev) => { /* Fv 系通用 tool{status},展示「正在查询库存…」*/ },
653
- // 语言包工厂:返回 LocaleMessages 包对象(zhCN/enUS 或自建包),非语言名字符串
654
- locale: () => (lang.value === 'en-US' ? enUS : zhCN)
655
- })
656
- // chat: { send, stop, regenerate, continueGenerate, enqueue, queue, isLoading,
657
- // msgs, messages, currentId, chain }
658
- ```
659
-
660
- - `send(text, files?)`:生成中调用被拒;多模型时各模型一个 assistant 节点并发回填
661
- - `stop()`:中止全部在途请求,在途节点置 done(保留半截内容)
662
- - `regenerate(messageId?)`:回退焦点到父节点重发生成新分支(旧回答保留)
663
- - `continueGenerate(messageId?)`:以既有内容为前缀续写,增量追加到同一节点
664
- - `enqueue(text, files?)`:生成中入队,完成后自动 flush 队首
665
- - `onToolEvent`:适配器 `onTool` 回调的透传挂点(如 FvCommonAdapter 的 tool{status} 事件)
666
- - `locale`:语言包工厂 `() => LocaleMessages`,惰性取用(与 adapter/models 工厂同语义);影响附件 system prompt、工具用时、续写 prompt 等发给后端的文案,缺省读全局设置,见[国际化](#国际化i18n)
667
-
668
- ### FvCommonAdapter(config)
669
-
670
- Fv 系后端通用聊天适配器(`/api/ai-chat/*`):六事件 SSE 协议(`message_start` / `tool` / `delta` / `reasoning` / `message_end` / `error`),POST `/ai-chat/message/send`。适用于 Fv 各项目组返回此结构的后端。会话管理(列表/归档/删除等)由消费方直接调后端,不经此适配器。
671
-
672
- ```ts
673
- const adapter = FvCommonAdapter({
674
- baseURL: '/api', // 或 https://host
675
- headers: () => ({ Authorization: 'Bearer ' + token }), // 惰性取用
676
- sessionId: () => currentSessionId.value, // 工厂:切换会话后下一次 send 生效
677
- errorMessages: { 90602: '已有进行中的对话' } // 业务码 → 文案映射(可选)
678
- })
679
- ```
680
-
681
- - 同步段失败(Content-Type 非 `text/event-stream`)按 JSON 错误 `{code,message}` 走 `onError`;命中 `errorMessages` 时用映射文案(带 `code` 的 `FvCommonError`)
682
- - `message_end` 的 `messageId`(最终文本行 id)经 `onBackendMessageId` 回填到 `MessageNode.backendId`——多轮工具循环下与 `message_start` 的首轮 id 不同,UI 落库/对账以它为准
683
- - `tool` 事件经 `onTool` → `useChat.onToolEvent` → `AiChat @tool-event` 上抛,消费方展示「正在查询库存…」等中间态
684
- - 配套 DTO 类型:`FvCommonSessionItem` / `FvCommonMessage` / `FvCommonSessionDetail` / `FvCommonMessagePage`(消费方直接调会话管理端点时用)
685
-
686
- ### useMessages(initial?)
687
-
688
- 树形消息状态中枢(响应式包装 `createMessageTree`)。
689
-
690
- 返回:`messages`(全量节点表)、`currentId`、`chain`(当前链 computed)、`add`、`remove`、`edit`、`appendContent`、`navigate(id?, dir?)`、`setCurrent(id)`、`setStorage(adapter)`、`load()`、`flush()`、`toJSON()`。绑定存储后树变更自动去抖(150ms)落盘。
691
-
692
- ### useXStream()
693
-
694
- SSE 流消费:`startStream({ readableStream, transformStream? })`、`cancel()`、`data: Ref<SSEEvent[]>`、`error`、`isLoading`。内部完成 `\r\n`/跨 chunk 边界归一化。
695
-
696
- ### useSend() / XRequest
697
-
698
- `useSend()`:`send({ url, method?, headers?, body?, transformStream?, onChunk? })`(SSE data 为 JSON 且含 content 字段时逐块回调)、`abort()`、`loading`、`error`。在飞行守卫:上一个 send 未结束时新 send 被忽略。
699
-
700
- `XRequest(url, options)`:Promise 化,resolve 累计全文。
701
-
702
- ### useRecord()
703
-
704
- 语音录制 + 实时转写:`start()` / `stop()` / `isRecording` / `text` / `audioUrl` / `error`。SpeechRecognition 不可用时降级为仅录音。
705
-
706
- ## 自定义 ChatAdapter
707
-
708
- 实现 `ChatAdapter` 接口即可接入任意后端(自研网关、Ollama、非 OpenAI 协议):
709
-
710
- ```ts
711
- import type { ChatAdapter } from '@fv-ui/ai-chat'
712
-
713
- const myAdapter: ChatAdapter = {
714
- async send(req, handlers) {
715
- // req: { messages: [{ role, content }], model?, stream?, signal? }
716
- try {
717
- const res = await fetch('/api/chat', {
718
- method: 'POST',
719
- headers: { 'content-type': 'application/json' },
720
- body: JSON.stringify(req),
721
- signal: req.signal
722
- })
723
- if (!res.ok) { handlers.onError(new Error(`HTTP ${res.status}`)); return }
724
- // 流式:自行逐块解析,回调增量
725
- handlers.onDelta('一段正文')
726
- handlers.onReasoning('一段思考链') // 可选
727
- handlers.onUsage({ prompt_tokens: 10, completion_tokens: 20 }) // 可选
728
- handlers.onDone() // 正常结束必须调用
729
- } catch (e) {
730
- if (req.signal?.aborted) return // 主动中止不算错误
731
- handlers.onError(e instanceof Error ? e : new Error(String(e)))
732
- }
733
- },
734
- abort() {
735
- // 中止全部在途请求
736
- }
737
- }
738
-
739
- // 用法
740
- <FvAiChat title="AI" :adapter="myAdapter" />
741
- ```
742
-
743
- 一次 `send` 对应一次完整生成:持续回调 `onDelta` 增量,最后必须 `onDone()` 或 `onError()`;`stop()` 时组件会调 `abort()`。
744
-
745
- 持久化可选 `StorageAdapter`(`get/set/remove`,async),内置 `createLocalStorageAdapter()`(localStorage 不可用时自动降级内存)与 `createMemoryAdapter()`;经 `useMessages().setStorage()` 绑定。
746
-
747
- ## 主题定制
748
-
749
- 组件样式基于 Element Plus CSS 变量,覆盖 EP 变量即完成主题定制:
750
-
751
- ```scss
752
- // 全局或局部覆盖(需在引入 dist/style.css 之后)
753
- :root {
754
- --el-color-primary: #7c3aed;
755
- }
756
- ```
757
-
758
- 高级定制可直接 `@use` 源 SCSS 入口:
759
-
760
- ```scss
761
- @use '@fv-ui/ai-chat/src/styles/index.scss' with (
762
- // scss 变量(若组件有定义)
763
- );
764
- ```
765
-
766
- > 源码 SCSS 入口仅供源码依赖场景;npm 消费方推荐使用构建产物 `dist/style.css` + CSS 变量覆盖。
767
-
768
- ## 国际化(i18n)
769
-
770
- 内置 `zh-CN`(默认,零配置)与 `en-US` 两份语言包;所有组件文案(按钮 aria/tooltip、状态文案、MessageBox、错误提示、发给模型的续写 prompt)均从语言包读取。
771
-
772
- ### 全局设置(推荐)
773
-
774
- ```ts
775
- import { configureLocale } from '@fv-ui/ai-chat'
776
-
777
- configureLocale('en-US') // 整库切英文;configureLocale('zh-CN') 切回
778
- ```
779
-
780
- ### 组件级 prop
781
-
782
- 每个含文案的组件都有 `locale` prop,两种形态:
783
-
784
- ```vue
785
- <!-- 整包切换(优先级最高) -->
786
- <FvAiChat locale="en-US" ... />
787
-
788
- <!-- 部分覆盖:在当前生效语言上深合并,只改指定文案 -->
789
- <FvAiChat :locale="{ aiMessage: { regenerate: '重答' }, sender: { send: 'GO' } }" ... />
790
- ```
791
-
792
- 解析优先级:**组件 prop > 祖先 `<FvAiChat>` 注入 > 全局设置**。`<FvAiChat>` 会把解析结果注入整框后代(Sender/消息区/Artifacts 等),后代组件的 `locale` prop 仍可局部覆盖;单独使用基础组件(FvSender/FvConversations...)时 prop 缺省则读全局。
793
-
794
- ### 自建完整语言包
795
-
796
- ```ts
797
- import { configureLocale, zhCN, type LocaleMessages } from '@fv-ui/ai-chat'
798
-
799
- const jaJP: LocaleMessages = {
800
- ...zhCN,
801
- common: { ...zhCN.common, send: '送信', copy: 'コピー' },
802
- aiMessage: { ...zhCN.aiMessage, defaultAssistantName: 'アシスタント' }
803
- // 未覆盖的 key 自动回落 zh-CN 值;建议展开全部 key 覆盖
804
- }
805
- configureLocale(jaJP)
806
- ```
807
-
808
- `configureLocale` 的对象形态是**完整语言包**(定基准);组件 `locale` prop 的对象形态是**部分覆盖**(在基准上微调),两者语义有意不同。
809
-
810
- ### 语言包 key 一览
811
-
812
- | 分组 | key | zh-CN | en-US |
813
- | --- | --- | --- | --- |
814
- | common | copy / delete / confirm / cancel / retry / close / preview / clear / stop / send / download / fullscreen / collapse / expand | 复制 / 删除 / 确定 / 取消 / 重传 / 关闭 / 预览 / 清空 / 停止 / 发送 / 下载 / 全屏 / 收起 / 展开 | Copy / Delete / OK / Cancel / Retry / Close / Preview / Clear / Stop / Send / Download / Fullscreen / Collapse / Expand |
815
- | thinking | start / thinking / end / error / endWithTools / thinkingItem / thoughtDoneItem | 开始思考 / 思考中... / 思考完成 / 思考遇到问题 / 思考完成,共调用了 {n} 次工具 / 正在思考 / 思考完成 | Thinking / Thinking... / Thought complete / Something went wrong / Thought complete, {n} tool calls made / Thinking / Thought complete |
816
- | welcome | greetingPrefix / greetingName / description | 你好,我是 ␣ / FVAI / 我可以帮你查询数据、分析问题、生成报表、以及执行系统操作,让生产管理更高效。 | Hello, I am ␣ / FVAI / I can help you query data, analyze problems, generate reports, and perform system operations... |
817
- | sender | clear / stop / send / speech / recordCancel / recordConfirm / micUnavailable | 清空 / 停止 / 发送 / 语音输入 / 取消录音 / 确认录音 / 无法访问麦克风 | Clear / Stop / Send / Voice input / Cancel recording / Confirm recording / Microphone unavailable |
818
- | editorSender | clear / stop / send / inputPlaceholder / selectTagTitle / loading / tagTip | 清空 / 停止 / 发送 / 请输入 / 选择标签 / 加载中… / 填写内容后回车确认 | Clear / Stop / Send / Type something... / Select a tag / Loading... / Type and press Enter to confirm |
819
- | attachments | add / retry | 添加附件 / 重传 | Add attachment / Retry |
820
- | filesCard | remove | 删除 | Remove |
821
- | 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}"? ... |
822
- | scroll | toBottom | 滚动到底部 | Scroll to bottom |
823
- | aiChat | modelPlaceholder / adapterMissing / generateFailed / exportUser / exportAssistant | 模型 / 未配置 adapter 或 baseURL / 生成失败 / 你 / 助手 | Model / Neither adapter nor baseURL is configured / Generation failed / You / Assistant |
824
- | aiMessage | copy / regenerate / prevBranch / nextBranch / defaultUserName / defaultAssistantName / querying / queried / generateFailed / loadingPhrases | 复制 / 重新生成 / 上一分支 / 下一分支 / 你 / 小维 / 正在查询␣ / 已查询␣ / 生成失败 / [正在思考…, 正在整理思路…, 正在生成回答…] | Copy / Regenerate / Previous branch / Next branch / You / Assistant / Querying␣ / Queried␣ / Generation failed / [Thinking..., Organizing thoughts..., Generating your answer...] |
825
- | aiArtifacts | copy / download / fullscreen / close | 复制 / 下载 / 全屏 / 关闭 | Copy / Download / Fullscreen / Close |
826
- | chat | fileTag / fileImageTag / filesSystemPrompt / toolDuration / continuePrompt | [附件] {name} / (图片) / 用户随消息提供了以下文件:\n{files} / 用时 {s} / 请基于以上内容继续完成回答... | [File] {name} / ␣(image) / The user provided... / Took {s} / Continue completing... |
827
- | 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} |
828
-
829
- 占位符 `{label}`/`{name}`/`{files}`/`{s}`/`{n}`/`{error}` 由组件在渲染/构造时替换。`querying`/`queried` 中英文值尾部均带一个空格(与工具名直接拼接,显示为「已查询 xxx」),覆盖时请保留所需间距。`welcome.greetingPrefix` 尾部空格同理(与 greetingName 拼接)。`aiMessage.loadingPhrases` 为生成中占位的轮换文案数组(进入占位立即显示第一条,此后每 3s 轮换循环);覆盖时数组**整体替换**(deepMerge 不合并数组叶子),传空数组则只显示 spinner 无文案。
830
-
831
- ### 与 vue-i18n 共存
832
-
833
- 本库不依赖 vue-i18n。若项目已在用,把 LocaleMessages 挂进 vue-i18n messages 后引用其值传 prop 即可桥接:
834
-
835
- ```vue
836
- <FvAiChat :locale="$tm('fvAiChat')" /> <!-- $tm 返回 fvAiChat 节点的对象作为语言包传入 -->
837
- ```
838
-
839
- ### 已落库数据不回溯
840
-
841
- 语言切换只影响之后的渲染与请求;已写入消息树的工具用时(`用时 1.2s`)、历史 error 文案保持产生时的语言。
842
-
843
- ## 暗色模式
844
-
845
- `<FvAiChat theme="dark">` 或 `theme="auto"`(跟随 `prefers-color-scheme`):组件向 `<html>` 注入/移除 `dark` class,配合 element-plus 的暗色变量生效:
846
-
847
- ```ts
848
- // main.ts 引入 EP 暗色变量
849
- import 'element-plus/theme-chalk/dark/css-vars.css'
850
- ```
851
-
852
- ```vue
853
- <FvAiChat theme="auto" ... />
854
- ```
855
-
856
- 注意:组件卸载时会移除 `html.dark`(单实例假设);多实例并用暗色需自行管理 class。
857
-
858
- ## Prism 主题引入
859
-
860
- 代码高亮默认配色由组件样式提供;要换成其他 Prism 主题,在 `dist/style.css` 之后引入覆盖:
861
-
862
- ```ts
863
- import '@fv-ui/ai-chat/dist/style.css'
864
- import '@fv-ui/ai-chat/styles/prism-tomorrow.min.css'
865
- ```
866
-
867
- 内置主题:`prism`(默认)、`prism-coy`、`prism-dark`、`prism-funky`、`prism-okaidia`、`prism-solarizedlight`、`prism-tomorrow`、`prism-twilight`。
868
-
869
- ## FAQ
870
-
871
- **Q:页面是白屏/样式错乱?**
872
- A:确认已引入 `element-plus/dist/index.css` 与 `@fv-ui/ai-chat/dist/style.css`,且 `app.use(ElementPlus)`。
873
-
874
- **Q:`<FvAiChat>` 发送报"未配置 adapter 或 baseURL"?**
875
- A:`adapter` 与 `baseURL` 至少传一个。
876
-
877
- **Q:外层改了 `v-model:messages` 为什么界面没变?**
878
- A:半受控语义:外部 messages 只在初始灌入一次,后续界面变化全量上抛 `update:messages`,请经 v-model 回写而不是直接改源数组。
879
-
880
- **Q:多模型怎么用?**
881
- A:`<FvAiChat model="a" :models="['a', 'b']">` 顶栏出现多选,选中的多个模型并行生成,回答互为分支可切换。
882
-
883
- **Q:`features` 里的 tts/queue/continueGenerate/fullscreenEditor?**
884
- A:接口已预留,当前版本仅 `artifacts` 生效,其余待后续版本接线。
885
-
886
- **Q:KaTeX 公式没渲染?**
887
- A:FvMarkdown 内置 `@vscode/markdown-it-katex`,确认公式语法正确即可;无需额外引入。
888
-
889
- **Q:Nuxt/SSR 环境首渲染报错 "DOMPurify 不可用:当前环境无 window"?**
890
- A:FvMarkdown 依赖浏览器 `window`(DOMPurify 消毒),不支持服务端首渲染。Nuxt 下请用 `<ClientOnly>` 包裹(或客户端挂载后再渲染):
891
-
892
- ```vue
893
- <ClientOnly>
894
- <FvAiChat ... />
895
- </ClientOnly>
896
- ```
897
-
898
- ## 已知限制与 Roadmap
899
-
900
- 以下能力数据层已就绪,组合 UI 待后续版本接线(v0.2 计划):
901
-
902
- - **消息列表懒加载**:`useMessages` 数据面支持分页注入,`AiMessages` 暂全量渲染;超长对话建议自行分页。
903
- - **消息操作条**:当前内置复制/重新生成;编辑/删除/继续生成/朗读请经 `useChat`(`editMessage`/`removeMessage`/`continueGenerate`)或 `#message-actions` 插槽自建入口。
904
- - **队列卡片**:`useChat.enqueue` 可用,`features.queue` 展示 UI 待接线。
905
- - **语音输入**:`Sender` 的 `allowSpeech` 依赖浏览器 `SpeechRecognition`(Chrome/Edge 可用,Firefox 不支持转写,降级为仅录音、确认后无文本);录音/波形需要 HTTPS 或 localhost 环境。
906
- - **多实例暗色互斥**:`theme` 采用单写者假设,多实例同屏请自行管理 `html.dark`。
907
-
908
- ## 类型与导出
909
-
910
- 包入口导出全部组件、`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` 等),消费方:
911
-
912
- ```ts
913
- import { FvAiChat, OpenAIAdapter, useChat } from '@fv-ui/ai-chat'
914
- import type { MessageNode, ChatAdapter } from '@fv-ui/ai-chat'
915
- ```
1
+ # @fv-ui/ai-chat
2
+
3
+ ![version](https://img.shields.io/badge/version-1.0.0-blue)
4
+ ![vue](https://img.shields.io/badge/vue-%5E3.4.0-brightgreen)
5
+ ![element-plus](https://img.shields.io/badge/element--plus-%5E2.7.0-blue)
6
+
7
+ 基于 Vue 3 + Element Plus 的 AI 对话组件库,复刻 element-plus-x 与 open-webui 对话框:从底层气泡、发送框、Markdown 渲染,到上层的对话整框(`<FvAiChat>`)、分支树消息、Artifacts 预览,一次给全。
8
+
9
+ - 14 个基础组件(Bubble/Sender/Markdown/Thinking/...)自由拼装
10
+ - 对话应用层整框 `<FvAiChat>`:顶栏模型多选、消息列表、分支切换、Artifacts 面板、发送停止一体化
11
+ - 树形消息模型(同构 open-webui):一条提问可挂多个模型回答,分支可切换、可重生成
12
+ - `ChatAdapter` 适配器协议:内置 OpenAI 兼容实现,可替换自研后端/Ollama
13
+ - 流式打字机、思考链折叠、KaTeX/代码高亮(Prism)开箱即用
14
+
15
+ ## 安装
16
+
17
+ ```bash
18
+ pnpm add @fv-ui/ai-chat
19
+ ```
20
+
21
+ peerDependencies:`vue ^3.4.0`、`element-plus ^2.7.0`、`@element-plus/icons-vue ^2.3.0`。
22
+
23
+ ## 快速开始
24
+
25
+ ```ts
26
+ // main.ts —— 需要先引入 element-plus(组件库依赖其组件与暗色变量)
27
+ import ElementPlus from 'element-plus'
28
+ import 'element-plus/dist/index.css'
29
+ import { createApp } from 'vue'
30
+ import App from './App.vue'
31
+
32
+ createApp(App).use(ElementPlus).mount('#app')
33
+ ```
34
+
35
+ ```vue
36
+ <!-- App.vue -->
37
+ <script setup lang="ts">
38
+ import { FvAiChat } from '@fv-ui/ai-chat'
39
+ import '@fv-ui/ai-chat/dist/style.css'
40
+ </script>
41
+
42
+ <template>
43
+ <FvAiChat
44
+ title="AI 助手"
45
+ base-url="https://api.deepseek.com/v1"
46
+ api-key="sk-xxx"
47
+ model="deepseek-chat"
48
+ style="height: 600px"
49
+ />
50
+ </template>
51
+ ```
52
+
53
+ `<FvAiChat>` 未传 `adapter` 时,用 `baseURL`/`apiKey`/`model` 构造内置 `OpenAIAdapter`(走 `/chat/completions`,SSE 流式)。两个都缺省时发送会报"未配置 adapter 或 baseURL"。
54
+
55
+ ## 基础组件层 API
56
+
57
+ ### FvMarkdown
58
+
59
+ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
60
+
61
+ | Prop | 类型 | 默认 | 说明 |
62
+ | --- | --- | --- | --- |
63
+ | content | string | —(必填) | Markdown 源文本 |
64
+ | mdPlugins | PluginWithParams[] | — | 额外 markdown-it 插件 |
65
+ | highlight | (str, lang) => string | 内置 Prism | 自定义代码高亮 |
66
+ | isTyping | boolean | — | 打字机模式样式钩子(透传占位) |
67
+ | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(fence 原始 lang 命中列表时注入预览按钮,点击行为由消费方事件委托实现) |
68
+ | tableToolbar | boolean | true | 表格工具栏:表格上方注入复制(复制表格 markdown 源文本)/下载(导出 CSV,带 BOM)单图标按钮 |
69
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
70
+
71
+ | Ref | 说明 |
72
+ | --- | --- |
73
+ | getHtml() | 取当前渲染后的 HTML 字符串 |
74
+
75
+ ### Typewriter
76
+
77
+ 打字机输出,支持续打/重打/雾化遮罩。
78
+
79
+ | Prop | 类型 | 默认 | 说明 |
80
+ | --- | --- | --- | --- |
81
+ | content | string | —(必填) | 全文(流式时增量传入,子集扩展自动续打) |
82
+ | isMarkdown | boolean | false | 走 FvMarkdown 渲染(此时 suffix 不追加) |
83
+ | isFog | boolean \| { bgColor?; width? } | false | 打字中尾部雾化遮罩 |
84
+ | typing | boolean \| { step?; interval?; suffix? } | false | 开启打字机;对象形态可配步长/间隔/光标后缀 |
85
+ | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(isMarkdown 模式透传 Markdown) |
86
+ | locale | LocaleInput | undefined | 语言包(透传内嵌 Markdown 的代码块「预览」按钮文案) |
87
+
88
+ | Event | 说明 |
89
+ | --- | --- |
90
+ | start / writing / finish | 开始打字 / 每次推进 / 全部打完 |
91
+
92
+ | Ref | 说明 |
93
+ | --- | --- |
94
+ | interrupt() / continue() / restart() / destroy() | 暂停 / 继续 / 重打 / 重置清空 |
95
+ | renderedContent / isTyping / progress | 已输出文本 / 是否打字中 / 进度 0-1 |
96
+
97
+ ### Bubble
98
+
99
+ 单条气泡(内部按需挂载 Typewriter/Markdown)。
100
+
101
+ | Prop | 类型 | 默认 | 说明 |
102
+ | --- | --- | --- | --- |
103
+ | content | string | '' | 气泡内容 |
104
+ | placement | 'start' \| 'end' | 'start' | start 靠左 / end 靠右 |
105
+ | loading | boolean | false | 加载态(三点动画,可被 #loading 覆盖) |
106
+ | typing | boolean \| TypingConfig | false | 打字机模式(透传 Typewriter) |
107
+ | isMarkdown | boolean | false | 内容按 Markdown 渲染 |
108
+ | isFog | boolean \| { bgColor?; width? } | false | 雾化(自定义气泡背景时传 bgColor) |
109
+ | variant | 'filled' \| 'borderless' \| 'outlined' \| 'shadow' | 'filled' | 气泡样式 |
110
+ | shape | 'round' \| 'corner' | 'round' | 圆角 / 方角 |
111
+ | avatar | string | '' | 头像图片地址 |
112
+ | avatarSize | ElAvatar size \| number | '' | 头像尺寸 |
113
+ | avatarGap | string | '12px' | 头像与内容间距 |
114
+ | avatarShape | 'circle' \| 'square' | 'circle' | 头像形状 |
115
+ | avatarIcon | Component | — | 头像图标(与 avatar 冲突时优先) |
116
+ | avatarSrcSet / avatarAlt | string | '' / '' | 头像 srcSet/alt |
117
+ | avatarFit | 'fill' \| 'contain' \| 'cover' \| 'none' \| 'scale-down' | 'cover' | 头像填充方式(el-avatar fit) |
118
+ | noPadding | boolean | false | 内容区去内边距 |
119
+ | noStyle | boolean | false | 去气泡样式(透明/无框/无阴影) |
120
+
121
+ | Event | 说明 |
122
+ | --- | --- |
123
+ | avatar-error | 头像加载失败 |
124
+ | start / writing / finish | typing 模式下的打字机事件透传 |
125
+
126
+ | Slot | 说明 |
127
+ | --- | --- |
128
+ | avatar / header / content / loading / footer | 自定义头像 / 头部 / 内容(优先于 content prop)/ 加载态 / 底部 |
129
+
130
+ | Ref | 说明 |
131
+ | --- | --- |
132
+ | interrupt / continue / restart / destroy | Typewriter 方法转发(非 typing 模式为 no-op) |
133
+ | renderedContent / isTyping / progress | Typewriter 状态转发 |
134
+ | twInstance | 内部 Typewriter 原始实例(BubbleList @complete 透传用) |
135
+
136
+ ### BubbleList
137
+
138
+ 气泡列表 + 吸底/回底按钮。
139
+
140
+ | Prop | 类型 | 默认 | 说明 |
141
+ | --- | --- | --- | --- |
142
+ | list | BubbleListItemProps[] | [] | 列表项(Bubble props + 必填 key) |
143
+ | maxHeight | string | '' | 滚动容器最大高度(如 '350px'/'60vh') |
144
+ | alwaysShowScrollbar | boolean | false | 始终显示滚动条 |
145
+ | showBackButton | boolean | true | 是否显示回底按钮 |
146
+ | backButtonThreshold | number | 80 | 距底超过该像素显示回底按钮 |
147
+ | btnLoading | boolean | false | 回底按钮加载态 |
148
+ | btnColor | string | '' | 回底按钮颜色(el-button color) |
149
+ | backButtonPosition | { bottom?; left? } | {} | 回底按钮位置偏移 |
150
+ | btnIconSize | number | 16 | 回底按钮图标尺寸 |
151
+ | triggerIndices | 'only-last' \| 'all' \| number[] | 'only-last' | @complete 触发索引 |
152
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
153
+
154
+ | Event | 说明 |
155
+ | --- | --- |
156
+ | complete | (typewriterInstance, index) 打字完成(按 triggerIndices 过滤后上抛) |
157
+
158
+ | Slot | 说明 |
159
+ | --- | --- |
160
+ | avatar / header / content / loading / footer | 透传给每个 Bubble,作用域 { item, index } |
161
+
162
+ | Ref | 说明 |
163
+ | --- | --- |
164
+ | scrollToTop() / scrollToBottom() / scrollToBubble(index) | 滚动控制 |
165
+
166
+ ### Sender
167
+
168
+ 输入发送框。
169
+
170
+ | Prop | 类型 | 默认 | 说明 |
171
+ | --- | --- | --- | --- |
172
+ | modelValue | string(v-model) | '' | 输入值(缺省内部自持) |
173
+ | placeholder | string | '' | 占位文案(缺省回落语言包 sender.inputPlaceholder) |
174
+ | autosize | { minRows?; maxRows? } | { minRows: 3, maxRows: 7 } | 自增高(行高 22px;默认 3 行起步,内容多时自动加高至最多 7 行后内部滚动;显式传 {} 退回固定单行) |
175
+ | submitType | 'enter' \| 'shiftEnter' \| 'cmdOrCtrlEnter' \| 'altEnter' | 'enter' | 提交按键模式 |
176
+ | loading | boolean | false | 加载态(发送键变停止键,输入区禁用) |
177
+ | disabled | boolean | false | 禁用(阻断提交) |
178
+ | readOnly | boolean | false | 只读 |
179
+ | clearable | boolean | false | 显示清空按钮 |
180
+ | round | boolean | true | 主按钮(发送/停止)为圆形(element-plus circle;false 时方按钮,停止键光带沿方框流转) |
181
+ | shadow | boolean | false | 输入区阴影效果(浮起感,聚焦时加深) |
182
+ | inputWidth | string | '' | 输入区宽度(variant=default 时有效) |
183
+ | variant | 'default' \| 'updown' | 'default' | default 同排 / updown 上输入下操作栏 |
184
+ | submitBtnDisabled | boolean | false | 附加禁用发送按钮 |
185
+ | triggerStrings | string[] | [] | 指令触发串(光标前命中弹指令框) |
186
+ | triggerPopoverVisible | boolean(v-model:triggerPopoverVisible) | false | 指令弹框显隐 |
187
+ | triggerPopoverWidth / triggerPopoverLeft | string | '' | 指令弹框宽度 / left 偏移 |
188
+ | triggerPopoverOffset | number | 0 | 弹框距触发字符偏移量 |
189
+ | triggerPopoverPlacement | ElPopover placement | 'top-start' | 弹框位置 |
190
+ | allowSpeech | boolean | false | 开启语音输入:麦克风按钮 → 录音条(波形+时长,Esc 取消)→ 确认后转写文本插入光标处;浏览器 SpeechRecognition 实时转写 |
191
+ | allowEmptySubmit | boolean | false | 允许空内容提交(附件场景:只发文件不输文字) |
192
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
193
+
194
+ | Event | 说明 |
195
+ | --- | --- |
196
+ | update:modelValue / change | 输入值变化 |
197
+ | submit | (value) 提交(提交后内部清空) |
198
+ | cancel | 点击停止按钮 |
199
+ | trigger | (keyword, visible) 命中指令串 |
200
+ | recording-change | 语音录制状态变化(预留) |
201
+ | paste-file | (file) 粘贴文件 |
202
+ | update:triggerPopoverVisible | 指令弹框显隐同步 |
203
+
204
+ | Slot | 说明 |
205
+ | --- | --- |
206
+ | header / footer | 头部/底部(配合 ref.openHeader/closeHeader) |
207
+ | prefix | 输入区前缀 |
208
+ | action-list | 自定义操作区(存在时隐藏内置按钮) |
209
+ | action-left | 操作栏左侧附加区(与提交按钮同行靠左,如附件回形针) |
210
+ | trigger | 指令弹框内容(作用域 { keyword }) |
211
+
212
+ | Ref | 说明 |
213
+ | --- | --- |
214
+ | submit() / cancel() / clear() | 提交 / 停止 / 清空 |
215
+ | focus(pos?) / blur() | pos: 'all' 全选 \| 'start' 头 \| 'end' 尾(缺省 end) |
216
+ | openHeader() / closeHeader() | 显隐 #header 插槽 |
217
+
218
+ ### MentionSender
219
+
220
+ 带 @提及 的 Sender(键盘 ↑↓ 导航 / Enter 确认 / Esc 关闭)。
221
+
222
+ | Prop | 类型 | 默认 | 说明 |
223
+ | --- | --- | --- | --- |
224
+ | modelValue | string(v-model) | '' | 输入值 |
225
+ | userList | MentionUserInfo[] | [] | @ 触发的候选用户(id/name/avatar/pinyin) |
226
+ | customTrigger | MentionCustomTrigger[] | [] | 自定义触发组 { dialogTitle, prefix, tagList } |
227
+ | asyncMatchFun | (search) => Promise<MentionUserInfo[]> | — | 异步候选(存在时防抖 300ms,后端过滤) |
228
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(候选加载文案);内嵌 Sender 的文案经祖先注入(如 AiChat)或全局设置生效 |
229
+
230
+ 事件:`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)。
231
+
232
+ | Ref | 说明 |
233
+ | --- | --- |
234
+ | submit / cancel / clear / focus / blur / openHeader / closeHeader | Sender 方法转发 |
235
+ | setUserTag(userId) | 光标处程序化插入 @用户 |
236
+ | setCustomTag(prefix, id) | 光标处插入自定义触发标签 |
237
+
238
+ ### EditorSender
239
+
240
+ 富文本标签编辑器(contenteditable),open-webui 风格标签芯片。
241
+
242
+ | Prop | 类型 | 默认 | 说明 |
243
+ | --- | --- | --- | --- |
244
+ | placeholder | string | '' | 占位文案 |
245
+ | device | 'pc' \| 'h5' | 'pc' | 设备形态(仅影响样式) |
246
+ | autoFocus | boolean | false | 挂载后聚焦到末尾 |
247
+ | variant | 'default' \| 'updown' | 'default' | 布局形态 |
248
+ | userList | EditorUser[] | [] | @ 候选用户 |
249
+ | customTrigger | EditorCustomTrigger[] | [] | 自定义触发组 |
250
+ | selectList | EditorSelectGroup[] | [] | 选择标签分组(openSelectDialog 弹窗数据) |
251
+ | maxLength | number | 0 | 纯文本最大长度(0 不限;性能开销大,仅显式开启) |
252
+ | submitType | 'enter' \| 'shiftEnter' | 'enter' | 提交按键模式 |
253
+ | customStyle | Record<string, any> | {} | 根节点自定义样式 |
254
+ | loading | boolean | false | 加载态(发送键变停止键) |
255
+ | disabled | boolean | false | 禁用 |
256
+ | clearable | boolean | false | 显示清空按钮 |
257
+ | headerAnimationTimer | number | 300 | 头部过渡时长(ms) |
258
+ | asyncMatchFun | (search) => Promise<EditorUser[]> | — | 异步 @ 候选(防抖 300ms) |
259
+ | customDialog | boolean | false | 选择标签不自弹内置弹窗,仅上抛 show-select-dialog |
260
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
261
+
262
+ | Event | 说明 |
263
+ | --- | --- |
264
+ | submit / change | (SubmitResult) SubmitResult = { text, html, tags: { userTags, selectTags, inputTags, customTags } } |
265
+ | cancel | 点击停止按钮 |
266
+ | show-at-dialog / show-select-dialog / show-tag-dialog | 各弹层显隐 |
267
+
268
+ | Slot | 说明 |
269
+ | --- | --- |
270
+ | header / footer / prefix / action-list | 同 Sender |
271
+ | tag-tip | 输入标签 tip 弹层内容(作用域 { nodeId }) |
272
+
273
+ | Ref | 说明 |
274
+ | --- | --- |
275
+ | getCurrentValue() | 取 { text, html, tags } |
276
+ | focusToStart() / focusToEnd() / blur() / selectAll() / clear() | 光标与清空 |
277
+ | setText(text) / setHtml(html) / setMixTags(rows) | 程序化写入 |
278
+ | setUserTag(id) / setCustomTag(prefix, id) / setInputTag(id, name) / setSelectTag(list) | 插入各类标签 |
279
+ | customSetUser(user) / customSetTag(tag) | 外部直传对象插入(不经列表查表) |
280
+ | updateSelectTag(method, options) | 选择标签更新:'insertTag'/'updateTagValue'/'deleteTag'/'updateTagStyle' |
281
+ | openSelectDialog() / openTipTag(nodeId?) / closeTipTag() | 弹窗控制 |
282
+ | openHeader() / closeHeader() | 显隐 #header |
283
+ | chat / opNode(method, options) / chatState() | 底层文档模型:chat.insert/update/delete/append;opNode 按方法名分发 |
284
+
285
+ ### Thinking
286
+
287
+ 思考链折叠面板。
288
+
289
+ | Prop | 类型 | 默认 | 说明 |
290
+ | --- | --- | --- | --- |
291
+ | modelValue | boolean(v-model) | false | 展开/收起 |
292
+ | content | string | '' | 思考内容(常配合 #content 插槽嵌 FvMarkdown) |
293
+ | status | 'start' \| 'thinking' \| 'end' \| 'error' | 'start' | 思考状态 |
294
+ | disabled | boolean | false | 禁用切换 |
295
+ | autoCollapse | boolean | false | status 变为 end 时自动收起 |
296
+ | hideHeader | boolean | false | 隐藏折叠头(单 item 链平铺形态):不渲染切换按钮,内容区常驻展开 |
297
+ | buttonWidth | string | '' | 切换按钮区宽度 |
298
+ | maxWidth | string | '' | 内容区最大宽度 |
299
+ | color / backgroundColor | string | '' | 前景色 / 背景色 |
300
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
301
+
302
+ | Event | 说明 |
303
+ | --- | --- |
304
+ | update:modelValue | 展开/收起同步 |
305
+
306
+ | Slot | 说明 |
307
+ | --- | --- |
308
+ | status-icon / label / arrow | 自定义状态图标 / 文案 / 箭头 |
309
+ | content / error | 思考内容 / error 态内容 |
310
+
311
+ | Ref | 说明 |
312
+ | --- | --- |
313
+ | modelValue / toggle() | 展开状态 / 手动切换 |
314
+
315
+ ### ThoughtChain
316
+
317
+ 思维链步骤条。text 步(kind: 'text')为「正在思考/思考完成」标题行 + 可折叠 description 展开区(默认收起;展开时整体撑开不限高——单条消息内部不分页,滚动交给外层消息列表);工具步 kind: 'tool' 为普通步骤行。
318
+
319
+ | Prop | 类型 | 默认 | 说明 |
320
+ | --- | --- | --- | --- |
321
+ | items | ThoughtChainItem[] | [] | 步骤项 { key, title?, status?: 'pending'/'success'/'loading'/'error', icon?, description?, kind?: 'tool'/'text', typing?, closed? } |
322
+ | direction | 'vertical' \| 'horizontal' | 'vertical' | 排列方向 |
323
+ | collapsible | boolean | false | 工具步长文案展开/收起(超 3 行截断 + 行尾「展开」) |
324
+ | showDuration | boolean | false | 显示工具步用时 description(text 步 description 不受影响) |
325
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
326
+
327
+ | Slot | 说明 |
328
+ | --- | --- |
329
+ | content | 覆盖默认 title/description(作用域 { item, index }) |
330
+
331
+ ### Welcome
332
+
333
+ 空态欢迎页。icon/name/description 均未传时显示内置品牌默认欢迎(「你好,我是 FVAI」问候高亮 + IP 形象动图 + 默认描述),逐 prop 独立覆盖。
334
+
335
+ 结构:图标区(DOM 序在前)+ 主列(`.fv-welcome-main`:文案列 + 建议区);纵排图标居中显示在文案上方;横排主列为唯一文档流内容(左对齐),吉祥物浮层悬于文案右上(经 flex order 排到主列右侧)——建议区与文案同列,不会把吉祥物顶高。
336
+
337
+ | Prop | 类型 | 默认 | 说明 |
338
+ | --- | --- | --- | --- |
339
+ | icon | string \| Component | '' | 图标(字符串为图片地址;未传渲染内置品牌欢迎动图,横排/纵排同图,仅尺寸不同:横排大图 108px×scale1.8,纵排 96px) |
340
+ | name | string | '' | 名称(未传回落内置问候语「你好,我是 FVAI」) |
341
+ | description | string | '' | 描述(纯文本;未传回落内置默认描述) |
342
+ | layout | 'vertical' \| 'horizontal' | 'vertical' | 布局:vertical 纵排(吉祥物居中在文案上方)/ horizontal 横排(文案左对齐,欢迎吉祥物浮层悬于文案右上,空态欢迎形态,原型 .intro 同构) |
343
+ | locale | LocaleInput | undefined | 语言包(内置欢迎文案) |
344
+
345
+ | Slot | 说明 |
346
+ | --- | --- |
347
+ | icon / name / description | 覆盖对应区块 |
348
+ | suggestions | 建议区(AiMessages 在此渲染 Prompts 快捷条;横排时与文案同列靠左) |
349
+
350
+ ### CSS 变量
351
+
352
+ | CSS 变量 | 默认 | 说明 |
353
+ | --- | --- | --- |
354
+ | --fv-welcome-icon-size | 纵排 96px | 内置品牌动图尺寸(纵排;横排吉祥物固定 108px×scale1.8 对齐原型) |
355
+ | --fv-welcome-max-width | 780px | 空态欢迎块宽度(AiMessages 空态轴线;文案/吉祥物/快捷条共用。AiChat 整框内空态时与输入区同轴,回落 --fv-empty-max-width;独立使用 AiMessages 时为 780px,可覆盖) |
356
+ | --fv-welcome-desc-max-width | 590px | 横排描述文字最大宽度(原型 .intro p) |
357
+
358
+ ### Prompts
359
+
360
+ 建议 prompt 网格。
361
+
362
+ | Prop | 类型 | 默认 | 说明 |
363
+ | --- | --- | --- | --- |
364
+ | prompts | PromptItem[] | [] | 建议项 { key(必填), label?, description?, icon?(EP 图标名字符串或组件), disabled? } |
365
+ | title | string | '' | 网格标题 |
366
+ | wrap | boolean | true | 换行模式(默认 true 自动换行;false 不换行,超出部分横向滚动) |
367
+
368
+ | Event | 说明 |
369
+ | --- | --- |
370
+ | select | (item) 点击(disabled 项不触发) |
371
+
372
+ | Slot | 说明 |
373
+ | --- | --- |
374
+ | default | 覆盖整卡(作用域 { item, index }) |
375
+
376
+ ### FilesCard
377
+
378
+ 单个文件卡片。文档模式按扩展名自动映射类型图标:pdf/doc/txt→文档、xls/csv→图表、ppt→演示、mp4→胶片、mp3→耳机、zip→文件夹、html/url→链接、apk→手机、exe→芯片,未命中回落通用文档图标。
379
+
380
+ | Prop | 类型 | 默认 | 说明 |
381
+ | --- | --- | --- | --- |
382
+ | name | string | '' | 文件名 |
383
+ | fileType | 'image' \| 'file' | 'file' | image 渲染缩略图,file 渲染文档图标卡 |
384
+ | size | number \| string | 0 | 文件大小(字节自动格式化为 B/KB/MB;字符串原样展示;0 不显示) |
385
+ | url | string | '' | 图片地址(image 模式缩略图) |
386
+ | status | 'loading' \| 'success' \| 'error' | 'success' | loading spinner / error 红边 |
387
+ | imageSize | string | '' | 缩略图尺寸(width/height 同值) |
388
+ | onDelete | () => void | — | 删除按钮回调 |
389
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
390
+
391
+ | Slot | 说明 |
392
+ | --- | --- |
393
+ | image | 覆盖图片区(默认 url 缩略图,无 url 渲染 Picture 占位) |
394
+
395
+ ### Attachments
396
+
397
+ 附件选择与列表(v-model)。
398
+
399
+ | Prop | 类型 | 默认 | 说明 |
400
+ | --- | --- | --- | --- |
401
+ | modelValue | object[](v-model) | [] | 附件列表(项含 uid/name/size/url/fileType/status/raw) |
402
+ | accept | string | '' | input accept,如 'image/*' |
403
+ | tip | string | '' | 内联提示文案 |
404
+ | count | number | 0 | 最大附件数(超出走 @exceed;0 不限) |
405
+ | beforeUpload | (file) => boolean \| Promise<boolean> | — | 上传前校验,返回 false 拦截 |
406
+ | layout | 'inline' \| 'triggerOnly' \| 'listOnly' | 'inline' | 布局:inline 回形针+列表+提示一行;triggerOnly 只渲染回形针按钮;listOnly 只渲染文件列表(拆分布局供整框组合:按钮进操作栏、列表进输入区上方) |
407
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
408
+
409
+ | Event | 说明 |
410
+ | --- | --- |
411
+ | update:modelValue / change | 列表变化(全量数组) |
412
+ | exceed | (file) 超出 count |
413
+ | delete | (item) 删除某项 |
414
+
415
+ | Slot | 说明 |
416
+ | --- | --- |
417
+ | list-item | 覆盖项渲染(作用域 { item, index }) |
418
+ | list-thumb | 覆盖图片缩略图(作用域 { item, index }) |
419
+
420
+ | Ref | 说明 |
421
+ | --- | --- |
422
+ | openSelect() | 程序化打开文件选择 |
423
+ | retry(item) | error 项重新置为 loading(上传逻辑由外部接线) |
424
+
425
+ ### Conversations
426
+
427
+ 会话列表(按 group 分组)。
428
+
429
+ | Prop | 类型 | 默认 | 说明 |
430
+ | --- | --- | --- | --- |
431
+ | items | ConversationItem[] | [] | 会话项 { key(必填), label(必填), group?, disabled? } |
432
+ | active | string \| number(v-model:active) | undefined | 当前激活会话 key |
433
+ | showBuiltInMenuType | 'hover' \| 'always' | 'hover' | 内置菜单按钮显隐方式 |
434
+ | groupable | (a, b) => number | — | 分组排序比较器(缺省保持插入顺序) |
435
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
436
+
437
+ | Event | 说明 |
438
+ | --- | --- |
439
+ | update:active / change | 选中会话(key / item) |
440
+ | menu-command | ({ item, command: 'rename'/'delete', value? }) 菜单指令;rename 确认后带新名称 |
441
+
442
+ | Slot | 说明 |
443
+ | --- | --- |
444
+ | group-title | 分组标题(作用域 { group }) |
445
+ | item | 覆盖行内容(作用域 { item, active }) |
446
+ | menu | 覆盖菜单项(默认重命名/删除;作用域 { item }) |
447
+
448
+ | Ref | 说明 |
449
+ | --- | --- |
450
+ | handleMenuCommand({ item, command }) | 程序化触发菜单指令转发(纯转发,同步上抛 menu-command) |
451
+ | renamePrompt(key) | 弹重命名输入框,确认后上抛 menu-command |
452
+ | deleteConfirm(key) | 弹删除确认框,确认后上抛 menu-command |
453
+
454
+ ## 对话应用层 API
455
+
456
+ ### AiChat
457
+
458
+ 对话整框:顶栏(标题+模型多选)、消息区(空态 Welcome/Prompts)、输入区(Sender)、可选 Artifacts 面板。
459
+
460
+ | Prop | 类型 | 默认 | 说明 |
461
+ | --- | --- | --- | --- |
462
+ | model | string | '' | 默认模型(未传 models 时作为单模型) |
463
+ | models | string[] | [] | 可选模型列表(有值时顶栏多选选择器) |
464
+ | baseURL | string | '' | OpenAI 兼容服务地址(未传 adapter 时构造 OpenAIAdapter) |
465
+ | apiKey | string | '' | 服务密钥 |
466
+ | adapter | ChatAdapter | undefined | 聊天适配器(与 baseURL 二选一,优先) |
467
+ | messages | MessageNode[](v-model:messages) | undefined | 消息链(半受控,见下) |
468
+ | title | string | '' | 顶栏标题(同时作空态欢迎页名称;未传时欢迎页显示内置默认问候「你好,我是 FVAI」) |
469
+ | showHeader | boolean | false | 显示顶栏(标题 + 模型选择器;models 多选选择器在顶栏内,需开启才可见) |
470
+ | centerWelcome | boolean | true | 空态居中:未开始对话时欢迎内容与输入区整体垂直居中,首条消息后输入区恢复固定底部 |
471
+ | showScrollButton | boolean | true | 显示滚到底部悬浮按钮(透传 AiMessages;距底超过 scrollButtonThreshold 时出现) |
472
+ | scrollButtonThreshold | number | 100 | 滚到底部悬浮按钮显示阈值(px,透传 AiMessages) |
473
+ | scrollThreshold | number | 100 | 用户上滚免打扰阈值(px,透传 AiMessages):距底不超过该值视为「钉在底部」,流式期间自动跟随滚动;调小可恢复更灵敏的跟随 |
474
+ | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;false 时用户消息不渲染头像;助手头像不受影响) |
475
+ | showUserName | boolean | false | 显示用户名称(默认隐藏;false 时用户消息不渲染头部名称行;助手名称不受影响) |
476
+ | showAssistantAvatar | boolean | true | 显示助手头像(false 时助手消息不渲染头像;用户头像不受影响) |
477
+ | showAssistantName | boolean | false | 显示助手名称(默认隐藏;false 时助手消息不渲染头部名称行;用户名称不受影响) |
478
+ | userAvatar | string | '' | 用户头像图片 URL(空串回落内置图标;`user-avatar` 插槽优先) |
479
+ | assistantAvatar | string | '' | 助手头像图片 URL(传入完全覆盖不分状态;空串按状态回落内置 GIF:thinking=fvai-thinking.gif,done/error=fvai-idle.gif;`assistant-avatar` 插槽优先) |
480
+ | assistantAvatarScale | number | 1 | 助手头像缩放系数(默认 1 不缩放;亦可用 CSS 变量 --fv-msg-avatar-scale 覆盖,prop 优先) |
481
+ | avatarCircle | boolean | true | 头像圆形模式(默认 true:圆角 50%;false 回落默认圆角;亦可用 CSS 变量 --fv-msg-avatar-radius 直接覆盖圆角取值,变量优先于开关) |
482
+ | userName | string | '' | 用户名称(空串回落「你」;`user-name` 插槽优先) |
483
+ | assistantName | string | '' | 助手名称(空串回落「小维」;`assistant-name` 插槽优先) |
484
+ | placeholder | string | '' | 输入框占位(缺省回落语言包 sender.inputPlaceholder:zh「输入你的问题,查询数据、分析问题或生成报表…」) |
485
+ | senderAutosize | { minRows?; maxRows? } | { minRows: 3, maxRows: 7 } | 输入区自增高(透传 Sender autosize;默认 3 行起步,内容多时自动加高至最多 7 行后内部滚动) |
486
+ | toolStepLabel | (toolName) => string | undefined | 工具名 → 步骤展示名(透传 useChat toolStepLabel) |
487
+ | typing | boolean \| { step?; interval? } | false | 打字机(透传 AiMessages;仅 assistant 流式期间逐字平滑打出,落定/历史消息整段渲染) |
488
+ | collapsible | boolean | false | 思考链工具步长文案展开/收起(透传 ThoughtChain;超 3 行截断 + 行尾「展开/收起」) |
489
+ | showDuration | boolean | false | 显示工具步用时 description(透传 ThoughtChain;默认关闭) |
490
+ | showTime | boolean | true | 显示消息时间(操作区按钮之后;时间源:`message.createdTime`——Fv 系后端直灌,秒级/毫秒级时间戳或 ISO 字符串自动识别——优先,缺省回落 `message.createdAt`) |
491
+ | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传消息与已归一为 ms 的时间戳;缺省 'YYYY-MM-DD HH:mm',本机时区) |
492
+ | senderShadow | boolean | true | 输入区阴影效果(透传 Sender 的 shadow) |
493
+ | suggestions | AiChatSuggestion[] | [] | 空态建议列表(Prompts 项,key 必填;空态快捷条为胶囊形态,description 不显示) |
494
+ | suggestionsWrap | boolean | true | 空态建议换行模式(true 自动换行;false 不换行,超出横向滚动) |
495
+ | features | AiChatFeatures | {} | 特性开关 { artifacts?, tts?, queue?, continueGenerate?, fullscreenEditor? }(当前仅 artifacts 生效);artifacts 传 `true` 用默认配置,传对象 `{ width?, minWidth?, maxWidth?, autoOpen?, codeBlockTrigger? }` 自定义:宽度三参控面板尺寸(默认 420px/360px/60%),autoOpen(默认 true)检测到代码块自动弹面板,codeBlockTrigger(默认 true)在消息 html/svg 代码块右上角显示「预览」按钮、点击打开对应面板 |
496
+ | allowAttachments | boolean | false | 开启输入区附件上传(回形针在操作栏左侧与提交按钮同行,已选列表在输入框上方;只传附件不输文字也可提交) |
497
+ | accept | string | '' | 附件 input accept 属性(透传 Attachments),如 'image/*' |
498
+ | attachmentLimit | number | 0 | 附件数量上限(0 不限,超限走 @attachment-exceed) |
499
+ | theme | 'light' \| 'dark' \| 'auto' | 'light' | 主题(向 html 注入/移除 dark class) |
500
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(解析后注入整框后代) |
501
+
502
+ **v-model:messages 半受控语义**:外部 `messages` 仅在 setup 时一次性深拷贝灌入(用于恢复历史);组件内部每次变更全量上抛 `update:messages`(同帧去抖),父组件需经 v-model 回写维持单向数据流;父组件后续直接改 prop **不会**回灌生效。
503
+
504
+ | Event | 说明 |
505
+ | --- | --- |
506
+ | update:messages | (MessageNode[]) 全量消息链(去抖后) |
507
+ | send | (text, files?) 用户发送(allowAttachments 开启时 files 为降维后的 ChatFile[]) |
508
+ | suggestion-select | (item) 点击空态建议项(先于 send 触发;label 为空的项不发) |
509
+ | message-complete | (message) 链尾 assistant 生成完成 |
510
+ | error | (err, message?) 生成出错 |
511
+ | branch-change | (dir, message) 分支切换 |
512
+ | attachment-exceed | (file) 附件超过 attachmentLimit 上限 |
513
+ | scroll | (event) 消息区滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
514
+
515
+ | Slot | 说明 |
516
+ | --- | --- |
517
+ | message-avatar / message-actions | 透传给 AiMessages(作用域见 AiMessage;message-avatar 优先于细分头像插槽) |
518
+ | user-avatar / assistant-avatar | 自定义用户/助手头像(assistant-avatar 作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于同名 props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
519
+ | user-name / assistant-name | 自定义用户/助手名称(作用域 { message },优先于同名 props) |
520
+ | welcome-name / welcome-description / welcome-icon | 单独配置欢迎页主标题/描述/吉祥物(转发 Welcome 同名插槽;优先于 title 等默认文案) |
521
+ | welcome-suggestions | 单独配置欢迎页建议区(整体替换默认 Prompts 快捷条;建议渲染在文案下方与文案同列) |
522
+ | empty | 覆盖空态整区 |
523
+ | scroll-button | 自定义滚到底部悬浮按钮整块(作用域 { scrollToBottom, awayFromBottom };覆盖后内置按钮与显隐逻辑均由插槽内容接管) |
524
+ | scroll-button-icon | 仅自定义悬浮按钮图标内容(按钮本体/显隐不变) |
525
+ | sender-prefix | 输入区前缀 |
526
+
527
+ | CSS 变量 | 默认 | 说明 |
528
+ | --- | --- | --- |
529
+ | --fv-empty-max-width | 780px | 空态(welcome 态)轴线最大宽度:欢迎块/快捷条与输入区(Sender)共用同轴线,宽屏居中;仅空态生效,首条消息后恢复全宽 |
530
+ | --fv-msg-avatar-size | 50px | 消息头像块边长(宽高同值;内置图标字号随块尺寸自适应) |
531
+ | --fv-msg-avatar-radius | 50%(avatarCircle 默认开) | 消息头像圆角(avatarCircle=false 时回落默认圆角;直接赋值可自定义任意圆角,优先于开关) |
532
+ | --fv-msg-avatar-scale | 1 | 助手头像缩放系数(默认 1 不缩放;放大可裁掉图片四周留白;assistantAvatarScale prop 优先于此变量) |
533
+
534
+ | Ref | 说明 |
535
+ | --- | --- |
536
+ | sendMessage(text, files?) | 程序化发送 |
537
+ | stop() | 停止生成(保留半截内容,静默收口不发 complete/error) |
538
+ | regenerate(messageId?) | 重生成(缺省链尾 assistant) |
539
+ | appendToMessage(id, text) | 向指定消息追加文本 |
540
+ | clearMessages() | 清空消息树 |
541
+ | exportTxt() | 导出当前链为纯文本 |
542
+ | openArtifact(key) | 程序化打开某个 artifact |
543
+ | expandThoughtChains() / collapseThoughtChains() | 全部展开/折叠当前链上消息的思考链(user 消息、无思考链消息、单 item 平铺形态不受控) |
544
+ | scrollTo(options) | 消息区滚动到指定位置(options 同原生 ScrollToOptions,如 { top: 0, behavior: 'smooth' };也可传 number) |
545
+
546
+ ### AiMessages
547
+
548
+ 消息列表(空态渲染 Welcome,建议快捷条经 Welcome #suggestions 插槽渲染在文案下方),吸底滚动。
549
+
550
+ | Prop | 类型 | 默认 | 说明 |
551
+ | --- | --- | --- | --- |
552
+ | messages | MessageNode[] | —(必填) | 当前链消息(根 → 焦点) |
553
+ | nodes | Record<string, MessageNode> | {} | 全量节点表(分支计算需查父 childrenIds) |
554
+ | icon | string \| Component | '' | 空态欢迎页图标 |
555
+ | name | string | '' | 空态欢迎页名称 |
556
+ | description | string | '' | 空态欢迎页描述 |
557
+ | suggestions | AiMessagesSuggestion[] | [] | 空态建议列表 |
558
+ | suggestionsTitle | string | '' | 空态建议区标题 |
559
+ | suggestionsWrap | boolean | true | 空态建议换行模式(true 自动换行;false 不换行,超出横向滚动) |
560
+ | scrollThreshold | number | 100 | 用户上滚免打扰阈值(px):距底不超过该值视为「钉在底部」,流式期间自动跟随滚动 |
561
+ | showScrollButton | boolean | true | 显示滚到底部悬浮按钮(空态不渲染) |
562
+ | scrollButtonThreshold | number | 100 | 距底超过该值(px)才显示滚到底部悬浮按钮 |
563
+ | showActions | boolean | true | 显示消息操作按钮(复制/重生成) |
564
+ | showBranchSwitch | boolean | true | 显示分支切换器 |
565
+ | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;助手头像不受影响) |
566
+ | showUserName | boolean | false | 显示用户名称(默认隐藏;助手名称不受影响) |
567
+ | showAssistantAvatar | boolean | true | 显示助手头像(用户头像不受影响) |
568
+ | showAssistantName | boolean | false | 显示助手名称(默认隐藏;用户名称不受影响) |
569
+ | userAvatar | string | '' | 用户头像图片 URL(透传 AiMessage) |
570
+ | assistantAvatar | string | '' | 助手头像图片 URL(透传 AiMessage;传入完全覆盖不分状态,空串按状态回落内置 GIF) |
571
+ | assistantAvatarScale | number | 1 | 助手头像缩放系数(透传 AiMessage;默认 1 不缩放) |
572
+ | userName | string | '' | 用户名称(透传 AiMessage) |
573
+ | assistantName | string | '' | 助手名称(透传 AiMessage;空串回落「小维」) |
574
+ | showTime | boolean | true | 显示消息时间(透传 AiMessage;时间源 createdTime 优先,缺省回落 createdAt) |
575
+ | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传 AiMessage) |
576
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
577
+
578
+ | Event | 说明 |
579
+ | --- | --- |
580
+ | select / copy / regenerate / branch-change | 建议选中 / 复制 / 重生成 / 分支切换,载荷同 AiChat |
581
+ | scroll | (event) 滚动容器滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
582
+
583
+ | Slot | 说明 |
584
+ | --- | --- |
585
+ | empty | 覆盖空态整区 |
586
+ | welcome-name / welcome-description / welcome-icon | 单独配置欢迎页主标题/描述/吉祥物(转发 Welcome 同名插槽) |
587
+ | welcome-suggestions | 单独配置欢迎页建议区(整体替换默认 Prompts 快捷条) |
588
+ | scroll-button | 自定义滚到底部悬浮按钮整块(作用域 { scrollToBottom, awayFromBottom };覆盖后内置按钮与显隐逻辑均由插槽内容接管) |
589
+ | scroll-button-icon | 仅自定义悬浮按钮图标内容(按钮本体/显隐不变) |
590
+ | message-avatar / message-actions | 透传给每条 AiMessage(message-avatar 优先于细分头像插槽) |
591
+ | user-avatar / assistant-avatar | 自定义用户/助手头像(assistant-avatar 作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于同名 props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
592
+ | user-name / assistant-name | 自定义用户/助手名称(作用域 { message },优先于同名 props) |
593
+
594
+ | CSS 变量 | 默认 | 说明 |
595
+ | --- | --- | --- |
596
+ | --fv-messages-max-width | none | 滚动内容最大宽度;超出部分左右居中(内层 `.fv-messages-inner`,配合 `margin: 0 auto`) |
597
+
598
+ | Ref | 说明 |
599
+ | --- | --- |
600
+ | scrollTo(options) | 滚动到指定位置(options 同原生 ScrollToOptions,也可传 number) |
601
+ | scrollToBottom(smooth?) / scrollToTop() | 滚动控制 |
602
+ | expandThoughtChains() / collapseThoughtChains() | 全部展开/折叠当前链上消息的思考链 |
603
+
604
+ ### AiMessage
605
+
606
+ 单条消息(Markdown 正文 + 思考链折叠 + 附件 + 操作区)。
607
+
608
+ | Prop | 类型 | 默认 | 说明 |
609
+ | --- | --- | --- | --- |
610
+ | message | MessageNode | —(必填) | 消息节点 |
611
+ | branch | AiMessageBranchInfo | undefined | 分支元数据 { count, index };缺省视为单分支 |
612
+ | showActions | boolean | true | 显示复制/重生成(仅 assistant) |
613
+ | showBranchSwitch | boolean | true | 显示分支切换器(branch.count > 1 时) |
614
+ | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;false 时用户消息不渲染头像块) |
615
+ | showUserName | boolean | false | 显示用户名称(默认隐藏;false 时用户消息不渲染头部名称行) |
616
+ | showAssistantAvatar | boolean | true | 显示助手头像(false 时助手消息不渲染头像块) |
617
+ | showAssistantName | boolean | false | 显示助手名称(默认隐藏;false 时助手消息不渲染头部名称行) |
618
+ | userAvatar | string | '' | 用户头像图片 URL(空串回落内置图标) |
619
+ | assistantAvatar | string | '' | 助手头像图片 URL(传入完全覆盖不分状态;空串按状态回落内置 GIF:thinking=fvai-thinking.gif,done/error=fvai-idle.gif) |
620
+ | assistantAvatarScale | number | 1 | 助手头像缩放系数(默认 1 不缩放;CSS 变量 --fv-msg-avatar-scale 同效,prop 优先) |
621
+ | avatarCircle | boolean | true | 头像圆形模式(透传 AiMessage;默认 true:圆角 50%;--fv-msg-avatar-radius 变量优先于开关) |
622
+ | userName | string | '' | 用户名称(空串回落「你」) |
623
+ | assistantName | string | '' | 助手名称(空串回落「小维」) |
624
+ | autoCollapse | boolean | true | Thinking autoCollapse 透传 |
625
+ | typing | boolean \| { step?; interval? } | false | 打字机(透传 Typewriter;仅 assistant 流式期间生效,落定/历史消息整段渲染) |
626
+ | collapsible | boolean | false | 思考链工具步长文案展开/收起开关(透传 ThoughtChain) |
627
+ | showDuration | boolean | false | 显示工具步用时 description(透传 ThoughtChain;默认关闭) |
628
+ | showTime | boolean | true | 显示消息时间(操作区按钮之后;时间源:message.createdTime(秒级/毫秒级时间戳或 ISO 字符串自动识别)优先,缺省回落 message.createdAt;两者皆无则不渲染) |
629
+ | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传消息与已归一为 ms 的时间戳;缺省 'YYYY-MM-DD HH:mm',本机时区) |
630
+ | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(透传 Markdown/Typewriter;命中语言的代码块右上角注入按钮,点击行为由消费方事件委托实现) |
631
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
632
+
633
+ > 用户消息操作区:恒渲染复制按钮,默认透明,鼠标移上消息(或键盘聚焦)时浮现(open-webui 交互)。
634
+
635
+ | Event | 说明 |
636
+ | --- | --- |
637
+ | copy / regenerate / branch-change | (message) / (message) / (dir, message) |
638
+
639
+ | Slot | 说明 |
640
+ | --- | --- |
641
+ | message-avatar | 自定义头像(作用域 { message };优先于细分头像插槽,两条角色消息均生效) |
642
+ | user-avatar | 自定义用户头像(无作用域;优先于 userAvatar props) |
643
+ | assistant-avatar | 自定义助手头像(作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于 assistantAvatar props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
644
+ | user-name | 自定义用户名称(作用域 { message };优先于 userName props) |
645
+ | assistant-name | 自定义助手名称(作用域 { message };优先于 assistantName props) |
646
+ | message-files | 自定义附件渲染(作用域 { message, files }) |
647
+ | message-actions | 自定义操作区(作用域 { message }) |
648
+
649
+ | Ref | 说明 |
650
+ | --- | --- |
651
+ | message | 当前消息节点(computed) |
652
+ | expandThoughtChain() / collapseThoughtChain() | 展开/折叠本条消息的思考链(user 消息、无思考链、单 item 平铺形态调用无效) |
653
+
654
+ ### AiArtifacts
655
+
656
+ Artifacts 预览面板(iframe 沙箱,从消息 ```html / ```svg 代码块提取)。
657
+
658
+ | Prop | 类型 | 默认 | 说明 |
659
+ | --- | --- | --- | --- |
660
+ | artifacts | AiArtifactItem[] | [] | artifact 列表 { key(必填), type: 'html'/'svg', content, title? } |
661
+ | activeKey | string | '' | 当前展示的 key;为空时面板隐藏 |
662
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
663
+
664
+ | Event | 说明 |
665
+ | --- | --- |
666
+ | close / change | 关闭 / 切换(key) |
667
+ | navigate | (href) iframe 内点击外链被拦截上抛 |
668
+
669
+ | Ref | 说明 |
670
+ | --- | --- |
671
+ | open(key) / close() | 程序化显隐 |
672
+
673
+ ## Composables
674
+
675
+ ### useChat(options)
676
+
677
+ 聊天编排:发送 → 流式回填 → 队列/重生成/续写。
678
+
679
+ ```ts
680
+ import { useChat, zhCN, enUS } from '@fv-ui/ai-chat' // zhCN/enUS:内置语言包(可换成自建包)
681
+
682
+ const lang = ref<'zh-CN' | 'en-US'>('zh-CN')
683
+
684
+ const chat = useChat({
685
+ adapter: () => OpenAIAdapter({ baseURL, apiKey }), // 实例或工厂;工厂每次 send 惰性取用
686
+ models: () => selectedModels.value, // 数组或工厂;多模型并行生成兄弟分支
687
+ initial: { messages, currentId }, // 恢复会话
688
+ onToolEvent: (ev) => { /* Fv 系通用 tool{status},展示「正在查询库存…」*/ },
689
+ // 语言包工厂:返回 LocaleMessages 包对象(zhCN/enUS 或自建包),非语言名字符串
690
+ locale: () => (lang.value === 'en-US' ? enUS : zhCN)
691
+ })
692
+ // chat: { send, stop, regenerate, continueGenerate, enqueue, queue, isLoading,
693
+ // msgs, messages, currentId, chain }
694
+ ```
695
+
696
+ - `send(text, files?)`:生成中调用被拒;多模型时各模型一个 assistant 节点并发回填
697
+ - `stop()`:中止全部在途请求,在途节点置 done(保留半截内容)
698
+ - `regenerate(messageId?)`:回退焦点到父节点重发生成新分支(旧回答保留)
699
+ - `continueGenerate(messageId?)`:以既有内容为前缀续写,增量追加到同一节点
700
+ - `enqueue(text, files?)`:生成中入队,完成后自动 flush 队首
701
+ - `onToolEvent`:适配器 `onTool` 回调的透传挂点(如 FvCommonAdapter 的 tool{status} 事件)
702
+ - `locale`:语言包工厂 `() => LocaleMessages`,惰性取用(与 adapter/models 工厂同语义);影响附件 system prompt、工具用时、续写 prompt 等发给后端的文案,缺省读全局设置,见[国际化](#国际化i18n)
703
+
704
+ ### FvCommonAdapter(config)
705
+
706
+ Fv 系后端通用聊天适配器(`/api/ai-chat/*`):六事件 SSE 协议(`message_start` / `tool` / `delta` / `reasoning` / `message_end` / `error`),POST `/ai-chat/message/send`。适用于 Fv 各项目组返回此结构的后端。会话管理(列表/归档/删除等)由消费方直接调后端,不经此适配器。
707
+
708
+ ```ts
709
+ const adapter = FvCommonAdapter({
710
+ baseURL: '/api', // 或 https://host
711
+ headers: () => ({ Authorization: 'Bearer ' + token }), // 惰性取用
712
+ sessionId: () => currentSessionId.value, // 工厂:切换会话后下一次 send 生效
713
+ errorMessages: { 90602: '已有进行中的对话' } // 业务码 → 文案映射(可选)
714
+ })
715
+ ```
716
+
717
+ - 同步段失败(Content-Type 非 `text/event-stream`)按 JSON 错误 `{code,message}` 走 `onError`;命中 `errorMessages` 时用映射文案(带 `code` 的 `FvCommonError`)
718
+ - `message_end` 的 `messageId`(最终文本行 id)经 `onBackendMessageId` 回填到 `MessageNode.backendId`——多轮工具循环下与 `message_start` 的首轮 id 不同,UI 落库/对账以它为准
719
+ - `tool` 事件经 `onTool` → `useChat.onToolEvent` → `AiChat @tool-event` 上抛,消费方展示「正在查询库存…」等中间态
720
+ - 配套 DTO 类型:`FvCommonSessionItem` / `FvCommonMessage` / `FvCommonSessionDetail` / `FvCommonMessagePage`(消费方直接调会话管理端点时用)
721
+
722
+ ### useMessages(initial?)
723
+
724
+ 树形消息状态中枢(响应式包装 `createMessageTree`)。
725
+
726
+ 返回:`messages`(全量节点表)、`currentId`、`chain`(当前链 computed)、`add`、`remove`、`edit`、`appendContent`、`navigate(id?, dir?)`、`setCurrent(id)`、`setStorage(adapter)`、`load()`、`flush()`、`toJSON()`。绑定存储后树变更自动去抖(150ms)落盘。
727
+
728
+ ### useXStream()
729
+
730
+ SSE 流消费:`startStream({ readableStream, transformStream? })`、`cancel()`、`data: Ref<SSEEvent[]>`、`error`、`isLoading`。内部完成 `\r\n`/跨 chunk 边界归一化。
731
+
732
+ ### useSend() / XRequest
733
+
734
+ `useSend()`:`send({ url, method?, headers?, body?, transformStream?, onChunk? })`(SSE data 为 JSON 且含 content 字段时逐块回调)、`abort()`、`loading`、`error`。在飞行守卫:上一个 send 未结束时新 send 被忽略。
735
+
736
+ `XRequest(url, options)`:Promise 化,resolve 累计全文。
737
+
738
+ ### useRecord()
739
+
740
+ 语音录制 + 实时转写:`start()` / `stop()` / `isRecording` / `text` / `audioUrl` / `error`。SpeechRecognition 不可用时降级为仅录音。
741
+
742
+ ## 自定义 ChatAdapter
743
+
744
+ 实现 `ChatAdapter` 接口即可接入任意后端(自研网关、Ollama、非 OpenAI 协议):
745
+
746
+ ```ts
747
+ import type { ChatAdapter } from '@fv-ui/ai-chat'
748
+
749
+ const myAdapter: ChatAdapter = {
750
+ async send(req, handlers) {
751
+ // req: { messages: [{ role, content }], model?, stream?, signal? }
752
+ try {
753
+ const res = await fetch('/api/chat', {
754
+ method: 'POST',
755
+ headers: { 'content-type': 'application/json' },
756
+ body: JSON.stringify(req),
757
+ signal: req.signal
758
+ })
759
+ if (!res.ok) { handlers.onError(new Error(`HTTP ${res.status}`)); return }
760
+ // 流式:自行逐块解析,回调增量
761
+ handlers.onDelta('一段正文')
762
+ handlers.onReasoning('一段思考链') // 可选
763
+ handlers.onUsage({ prompt_tokens: 10, completion_tokens: 20 }) // 可选
764
+ handlers.onDone() // 正常结束必须调用
765
+ } catch (e) {
766
+ if (req.signal?.aborted) return // 主动中止不算错误
767
+ handlers.onError(e instanceof Error ? e : new Error(String(e)))
768
+ }
769
+ },
770
+ abort() {
771
+ // 中止全部在途请求
772
+ }
773
+ }
774
+
775
+ // 用法
776
+ <FvAiChat title="AI" :adapter="myAdapter" />
777
+ ```
778
+
779
+ 一次 `send` 对应一次完整生成:持续回调 `onDelta` 增量,最后必须 `onDone()` 或 `onError()`;`stop()` 时组件会调 `abort()`。
780
+
781
+ 持久化可选 `StorageAdapter`(`get/set/remove`,async),内置 `createLocalStorageAdapter()`(localStorage 不可用时自动降级内存)与 `createMemoryAdapter()`;经 `useMessages().setStorage()` 绑定。
782
+
783
+ ## 主题定制
784
+
785
+ 组件样式基于 Element Plus CSS 变量,覆盖 EP 变量即完成主题定制:
786
+
787
+ ```scss
788
+ // 全局或局部覆盖(需在引入 dist/style.css 之后)
789
+ :root {
790
+ --el-color-primary: #7c3aed;
791
+ }
792
+ ```
793
+
794
+ 高级定制可直接 `@use` 源 SCSS 入口:
795
+
796
+ ```scss
797
+ @use '@fv-ui/ai-chat/src/styles/index.scss' with (
798
+ // scss 变量(若组件有定义)
799
+ );
800
+ ```
801
+
802
+ > 源码 SCSS 入口仅供源码依赖场景;npm 消费方推荐使用构建产物 `dist/style.css` + CSS 变量覆盖。
803
+
804
+ ## 国际化(i18n)
805
+
806
+ 内置 `zh-CN`(默认,零配置)与 `en-US` 两份语言包;所有组件文案(按钮 aria/tooltip、状态文案、MessageBox、错误提示、发给模型的续写 prompt)均从语言包读取。
807
+
808
+ ### 全局设置(推荐)
809
+
810
+ ```ts
811
+ import { configureLocale } from '@fv-ui/ai-chat'
812
+
813
+ configureLocale('en-US') // 整库切英文;configureLocale('zh-CN') 切回
814
+ ```
815
+
816
+ ### 组件级 prop
817
+
818
+ 每个含文案的组件都有 `locale` prop,两种形态:
819
+
820
+ ```vue
821
+ <!-- 整包切换(优先级最高) -->
822
+ <FvAiChat locale="en-US" ... />
823
+
824
+ <!-- 部分覆盖:在当前生效语言上深合并,只改指定文案 -->
825
+ <FvAiChat :locale="{ aiMessage: { regenerate: '重答' }, sender: { send: 'GO' } }" ... />
826
+ ```
827
+
828
+ 解析优先级:**组件 prop > 祖先 `<FvAiChat>` 注入 > 全局设置**。`<FvAiChat>` 会把解析结果注入整框后代(Sender/消息区/Artifacts 等),后代组件的 `locale` prop 仍可局部覆盖;单独使用基础组件(FvSender/FvConversations...)时 prop 缺省则读全局。
829
+
830
+ ### 自建完整语言包
831
+
832
+ ```ts
833
+ import { configureLocale, zhCN, type LocaleMessages } from '@fv-ui/ai-chat'
834
+
835
+ const jaJP: LocaleMessages = {
836
+ ...zhCN,
837
+ common: { ...zhCN.common, send: '送信', copy: 'コピー' },
838
+ aiMessage: { ...zhCN.aiMessage, defaultAssistantName: 'アシスタント' }
839
+ // 未覆盖的 key 自动回落 zh-CN 值;建议展开全部 key 覆盖
840
+ }
841
+ configureLocale(jaJP)
842
+ ```
843
+
844
+ `configureLocale` 的对象形态是**完整语言包**(定基准);组件 `locale` prop 的对象形态是**部分覆盖**(在基准上微调),两者语义有意不同。
845
+
846
+ ### 语言包 key 一览
847
+
848
+ | 分组 | key | zh-CN | en-US |
849
+ | --- | --- | --- | --- |
850
+ | common | copy / delete / confirm / cancel / retry / close / preview / clear / stop / send / download / fullscreen / collapse / expand | 复制 / 删除 / 确定 / 取消 / 重传 / 关闭 / 预览 / 清空 / 停止 / 发送 / 下载 / 全屏 / 收起 / 展开 | Copy / Delete / OK / Cancel / Retry / Close / Preview / Clear / Stop / Send / Download / Fullscreen / Collapse / Expand |
851
+ | thinking | start / thinking / end / error / endWithTools / thinkingItem / thoughtDoneItem | 开始思考 / 思考中... / 思考完成 / 思考遇到问题 / 思考完成,使用 {n} 个工具 / 正在思考 / 思考完成 | Thinking / Thinking... / Thought complete / Something went wrong / Thought complete, used {n} tools / Thinking / Thought complete |
852
+ | welcome | greetingPrefix / greetingName / description | 你好,我是 ␣ / FVAI / 我可以帮你查询数据、分析问题、生成报表、以及执行系统操作,让生产管理更高效。 | Hello, I am ␣ / FVAI / I can help you query data, analyze problems, generate reports, and perform system operations... |
853
+ | 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… |
854
+ | editorSender | clear / stop / send / inputPlaceholder / selectTagTitle / loading / tagTip | 清空 / 停止 / 发送 / 请输入 / 选择标签 / 加载中… / 填写内容后回车确认 | Clear / Stop / Send / Type something... / Select a tag / Loading... / Type and press Enter to confirm |
855
+ | attachments | add / retry | 添加附件 / 重传 | Add attachment / Retry |
856
+ | filesCard | remove | 删除 | Remove |
857
+ | 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}"? ... |
858
+ | scroll | toBottom | 滚动到底部 | Scroll to bottom |
859
+ | aiChat | modelPlaceholder / adapterMissing / generateFailed / exportUser / exportAssistant | 模型 / 未配置 adapter 或 baseURL / 生成失败 / 你 / 助手 | Model / Neither adapter nor baseURL is configured / Generation failed / You / Assistant |
860
+ | aiMessage | copy / regenerate / prevBranch / nextBranch / defaultUserName / defaultAssistantName / querying / queried / generateFailed / loadingPhrases | 复制 / 重新生成 / 上一分支 / 下一分支 / 你 / 小维 / 正在查询 / 已查询 / 生成失败 / [正在思考…, 正在整理思路…, 正在生成回答…] | Copy / Regenerate / Previous branch / Next branch / You / Assistant / Querying / Queried / Generation failed / [Thinking..., Organizing thoughts..., Generating your answer...] |
861
+ | aiArtifacts | copy / download / fullscreen / close | 复制 / 下载 / 全屏 / 关闭 | Copy / Download / Fullscreen / Close |
862
+ | chat | fileTag / fileImageTag / filesSystemPrompt / toolDuration / continuePrompt | [附件] {name} / (图片) / 用户随消息提供了以下文件:\n{files} / 用时 {s} / 请基于以上内容继续完成回答... | [File] {name} / ␣(image) / The user provided... / Took {s} / Continue completing... |
863
+ | 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} |
864
+
865
+ 占位符 `{label}`/`{name}`/`{files}`/`{s}`/`{n}`/`{error}` 由组件在渲染/构造时替换。`querying`/`queried` 与工具名拼接时由组件显式补一个空格(显示为「正在查询 xxx」),词条本身不含尾随空格,覆盖时无需保留间距。`welcome.greetingPrefix` 保留尾随空格(与 greetingName 直接拼接,高亮 span 交界处)。`aiMessage.loadingPhrases` 为生成中占位的轮换文案数组(进入占位立即显示第一条,此后每 3s 轮换循环);覆盖时数组**整体替换**(deepMerge 不合并数组叶子),传空数组则只显示 spinner 无文案。
866
+
867
+ ### 与 vue-i18n 共存
868
+
869
+ 本库不依赖 vue-i18n。若项目已在用,把 LocaleMessages 挂进 vue-i18n messages 后引用其值传 prop 即可桥接:
870
+
871
+ ```vue
872
+ <FvAiChat :locale="$tm('fvAiChat')" /> <!-- $tm 返回 fvAiChat 节点的对象作为语言包传入 -->
873
+ ```
874
+
875
+ ### 已落库数据不回溯
876
+
877
+ 语言切换只影响之后的渲染与请求;已写入消息树的工具用时(`用时 1.2s`)、历史 error 文案保持产生时的语言。
878
+
879
+ ## 暗色模式
880
+
881
+ `<FvAiChat theme="dark">` 或 `theme="auto"`(跟随 `prefers-color-scheme`):组件向 `<html>` 注入/移除 `dark` class,配合 element-plus 的暗色变量生效:
882
+
883
+ ```ts
884
+ // main.ts 引入 EP 暗色变量
885
+ import 'element-plus/theme-chalk/dark/css-vars.css'
886
+ ```
887
+
888
+ ```vue
889
+ <FvAiChat theme="auto" ... />
890
+ ```
891
+
892
+ 注意:组件卸载时会移除 `html.dark`(单实例假设);多实例并用暗色需自行管理 class。
893
+
894
+ ## Prism 主题引入
895
+
896
+ 代码高亮默认配色由组件样式提供;要换成其他 Prism 主题,在 `dist/style.css` 之后引入覆盖:
897
+
898
+ ```ts
899
+ import '@fv-ui/ai-chat/dist/style.css'
900
+ import '@fv-ui/ai-chat/styles/prism-tomorrow.min.css'
901
+ ```
902
+
903
+ 内置主题:`prism`(默认)、`prism-coy`、`prism-dark`、`prism-funky`、`prism-okaidia`、`prism-solarizedlight`、`prism-tomorrow`、`prism-twilight`。
904
+
905
+ ## FAQ
906
+
907
+ **Q:页面是白屏/样式错乱?**
908
+ A:确认已引入 `element-plus/dist/index.css` 与 `@fv-ui/ai-chat/dist/style.css`,且 `app.use(ElementPlus)`。
909
+
910
+ **Q:`<FvAiChat>` 发送报"未配置 adapter 或 baseURL"?**
911
+ A:`adapter` 与 `baseURL` 至少传一个。
912
+
913
+ **Q:外层改了 `v-model:messages` 为什么界面没变?**
914
+ A:半受控语义:外部 messages 只在初始灌入一次,后续界面变化全量上抛 `update:messages`,请经 v-model 回写而不是直接改源数组。
915
+
916
+ **Q:多模型怎么用?**
917
+ A:`<FvAiChat model="a" :models="['a', 'b']">` 顶栏出现多选,选中的多个模型并行生成,回答互为分支可切换。
918
+
919
+ **Q:`features` 里的 tts/queue/continueGenerate/fullscreenEditor?**
920
+ A:接口已预留,当前版本仅 `artifacts` 生效,其余待后续版本接线。
921
+
922
+ **Q:KaTeX 公式没渲染?**
923
+ A:FvMarkdown 内置 `@vscode/markdown-it-katex`,确认公式语法正确即可;无需额外引入。
924
+
925
+ **Q:Nuxt/SSR 环境首渲染报错 "DOMPurify 不可用:当前环境无 window"?**
926
+ A:FvMarkdown 依赖浏览器 `window`(DOMPurify 消毒),不支持服务端首渲染。Nuxt 下请用 `<ClientOnly>` 包裹(或客户端挂载后再渲染):
927
+
928
+ ```vue
929
+ <ClientOnly>
930
+ <FvAiChat ... />
931
+ </ClientOnly>
932
+ ```
933
+
934
+ ## 已知限制与 Roadmap
935
+
936
+ 以下能力数据层已就绪,组合 UI 待后续版本接线(v0.2 计划):
937
+
938
+ - **消息列表懒加载**:`useMessages` 数据面支持分页注入,`AiMessages` 暂全量渲染;超长对话建议自行分页。
939
+ - **消息操作条**:当前内置复制/重新生成;编辑/删除/继续生成/朗读请经 `useChat`(`editMessage`/`removeMessage`/`continueGenerate`)或 `#message-actions` 插槽自建入口。
940
+ - **队列卡片**:`useChat.enqueue` 可用,`features.queue` 展示 UI 待接线。
941
+ - **语音输入**:`Sender` 的 `allowSpeech` 依赖浏览器 `SpeechRecognition`(Chrome/Edge 可用,Firefox 不支持转写,降级为仅录音、确认后无文本);录音/波形需要 HTTPS 或 localhost 环境。
942
+ - **多实例暗色互斥**:`theme` 采用单写者假设,多实例同屏请自行管理 `html.dark`。
943
+
944
+ ## 类型与导出
945
+
946
+ 包入口导出全部组件、`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` 等),消费方:
947
+
948
+ ```ts
949
+ import { FvAiChat, OpenAIAdapter, useChat } from '@fv-ui/ai-chat'
950
+ import type { MessageNode, ChatAdapter } from '@fv-ui/ai-chat'
951
+ ```