@blueking/chat-x 0.0.10 → 0.0.12
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 +494 -0
- package/dist/mcp/generated/index.json +1 -1
- package/package.json +3 -2
- package/readme.md +0 -0
package/README.md
ADDED
|
@@ -0,0 +1,494 @@
|
|
|
1
|
+
# @blueking/chat-x
|
|
2
|
+
|
|
3
|
+
蓝鲸智云 AI Chat 组件库 —— 基于 Vue 3 + TypeScript，遵循 [AG-UI（Agent-User Interaction Protocol）](https://docs.ag-ui.com/) 协议规范，为 AI Agent 和人类开发者共同设计的对话 UI 组件库。
|
|
4
|
+
|
|
5
|
+
提供符合 AG-UI 协议的标准化消息模型、流式消息渲染、Markdown 内容展示、代码高亮、LaTeX 公式、Mermaid 图表、快捷指令、划词选择等一站式 AI 对话能力，并内置 MCP Server 让 AI IDE 直接查询组件文档。
|
|
6
|
+
|
|
7
|
+
## 特性
|
|
8
|
+
|
|
9
|
+
- **AG-UI 协议支持** — 基于 [AG-UI](https://docs.ag-ui.com/) 开放协议规范构建消息类型系统，标准化 AI Agent 与用户界面之间的交互，支持流式事件、工具调用、多角色消息等协议能力
|
|
10
|
+
- **AI 优先设计** — 每个组件携带结构化元数据和 AI 专用摘要（aiSummary），内置 MCP Server 让 Cursor 等 AI IDE 通过标准协议直接查询文档
|
|
11
|
+
- **流式渲染** — 原生支持 AI 响应的实时流式输出，逐字渲染并自动补全未闭合的 Markdown 语法
|
|
12
|
+
- **20+ 消息角色** — 覆盖 User、Assistant、Tool、Reasoning、Activity、Info、Loading 等全部 AI 对话场景，支持 `declare global` 零侵入扩展自定义角色
|
|
13
|
+
- **多级内容管线** — `ContentRender → MarkdownContent → CodeContent / LatexContent / MermaidContent`，按 token 类型自动分发，支持 180+ 语言代码高亮
|
|
14
|
+
- **渐进式组合** — 最小组合 `ChatInput + MessageContainer`，完整方案 `ChatContainer` 一行搞定，原子 / 分子分层设计，按需引入
|
|
15
|
+
- **快捷指令与斜杠命令** — 内置 `/` 和 `@` 触发的命令系统，支持文本、数字、下拉、复选等表单组件
|
|
16
|
+
- **划词选择** — `AiSelection` 监听页面文本选中，弹出快捷操作浮窗
|
|
17
|
+
- **图片与文件** — 文件上传、图片展示、全屏预览、多图管理，内置下载与错误重试
|
|
18
|
+
- **类型安全** — 完整的 TypeScript 类型定义，泛型 + 全局类型扩展
|
|
19
|
+
|
|
20
|
+
## 安装
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# pnpm（推荐）
|
|
24
|
+
pnpm add @blueking/chat-x
|
|
25
|
+
|
|
26
|
+
# npm
|
|
27
|
+
npm install @blueking/chat-x
|
|
28
|
+
|
|
29
|
+
# yarn
|
|
30
|
+
yarn add @blueking/chat-x
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### 前置依赖
|
|
34
|
+
|
|
35
|
+
| 依赖 | 最低版本 | 说明 |
|
|
36
|
+
| ---------- | -------- | --------------------- |
|
|
37
|
+
| `vue` | 3.5+ | Vue 3 Composition API |
|
|
38
|
+
| `bkui-vue` | 2.x | 蓝鲸 UI 基础组件库 |
|
|
39
|
+
|
|
40
|
+
## 快速开始
|
|
41
|
+
|
|
42
|
+
### 方式一：ChatContainer 一站式方案（推荐）
|
|
43
|
+
|
|
44
|
+
`ChatContainer` 封装了 `MessageContainer`、`ChatInput`、`ShortcutBtns`、`ShortcutRender`、`ExecutionSummary` 等子组件，内部自动完成消息分组、快捷指令渲染、执行摘要等逻辑。
|
|
45
|
+
|
|
46
|
+
````vue
|
|
47
|
+
<template>
|
|
48
|
+
<div class="chat-page">
|
|
49
|
+
<ChatContainer
|
|
50
|
+
:messages="messages"
|
|
51
|
+
:on-agent-action="handleAgentAction"
|
|
52
|
+
:on-send-message="handleSendMessage"
|
|
53
|
+
:on-stop-sending="handleStopSending"
|
|
54
|
+
:prompts="prompts"
|
|
55
|
+
:shortcuts="shortcuts"
|
|
56
|
+
@update:model-value="val => (userInput = val)"
|
|
57
|
+
/>
|
|
58
|
+
</div>
|
|
59
|
+
</template>
|
|
60
|
+
|
|
61
|
+
<script setup lang="ts">
|
|
62
|
+
import { ref as deepRef, shallowRef } from 'vue';
|
|
63
|
+
import {
|
|
64
|
+
ChatContainer,
|
|
65
|
+
MessageRole,
|
|
66
|
+
MessageStatus,
|
|
67
|
+
type IToolBtn,
|
|
68
|
+
type Message,
|
|
69
|
+
type Shortcut,
|
|
70
|
+
type TagSchema,
|
|
71
|
+
type UserMessage,
|
|
72
|
+
} from '@blueking/chat-x';
|
|
73
|
+
|
|
74
|
+
const messages = deepRef<Message[]>([]);
|
|
75
|
+
const userInput = shallowRef<string | TagSchema>('');
|
|
76
|
+
const prompts = shallowRef(['帮我写一段代码', '解释这段报错', '总结这篇文档']);
|
|
77
|
+
const shortcuts = shallowRef<Shortcut[]>([
|
|
78
|
+
{ id: 'ask', name: '问问小鲸', description: '向 AI 助手提问' },
|
|
79
|
+
{ id: 'code-review', name: '代码审查', description: '让 AI 审查你的代码' },
|
|
80
|
+
]);
|
|
81
|
+
|
|
82
|
+
const handleSendMessage = async (content: UserMessage['content'], docSchema: TagSchema) => {
|
|
83
|
+
messages.value.push({
|
|
84
|
+
id: `user_${Date.now()}`,
|
|
85
|
+
messageId: `user_${Date.now()}`,
|
|
86
|
+
role: MessageRole.User,
|
|
87
|
+
content,
|
|
88
|
+
status: MessageStatus.Complete,
|
|
89
|
+
});
|
|
90
|
+
userInput.value = '';
|
|
91
|
+
|
|
92
|
+
const aiMessage: Message = {
|
|
93
|
+
id: `ai_${Date.now()}`,
|
|
94
|
+
messageId: `ai_${Date.now()}`,
|
|
95
|
+
role: MessageRole.Assistant,
|
|
96
|
+
content: '',
|
|
97
|
+
status: MessageStatus.Streaming,
|
|
98
|
+
};
|
|
99
|
+
messages.value.push(aiMessage);
|
|
100
|
+
|
|
101
|
+
// 替换为实际 SSE / WebSocket 调用
|
|
102
|
+
const reply = '这是一个 **Markdown** 回复。\n\n```javascript\nconsole.log("Hello!");\n```';
|
|
103
|
+
for (const char of reply) {
|
|
104
|
+
await new Promise(r => setTimeout(r, 20));
|
|
105
|
+
aiMessage.content += char;
|
|
106
|
+
}
|
|
107
|
+
aiMessage.status = MessageStatus.Complete;
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
const handleStopSending = async () => {
|
|
111
|
+
const last = messages.value.at(-1);
|
|
112
|
+
if (last) last.status = MessageStatus.Stop;
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
const handleAgentAction = async (tool: IToolBtn) => {
|
|
116
|
+
if (tool.id === 'like') return ['回答准确', '信息全面', '表达清晰'];
|
|
117
|
+
if (tool.id === 'unlike') return ['信息错误', '回答不相关', '解释不清楚'];
|
|
118
|
+
};
|
|
119
|
+
</script>
|
|
120
|
+
|
|
121
|
+
<style scoped>
|
|
122
|
+
.chat-page {
|
|
123
|
+
display: flex;
|
|
124
|
+
height: 100vh;
|
|
125
|
+
background: #fff;
|
|
126
|
+
}
|
|
127
|
+
</style>
|
|
128
|
+
````
|
|
129
|
+
|
|
130
|
+
### 方式二：自定义组合（进阶）
|
|
131
|
+
|
|
132
|
+
如需完全控制布局，可单独使用 `MessageContainer` + `ChatInput` + `useMessageGroup`。
|
|
133
|
+
|
|
134
|
+
```vue
|
|
135
|
+
<template>
|
|
136
|
+
<div class="chat-page">
|
|
137
|
+
<MessageContainer
|
|
138
|
+
:messages="messages"
|
|
139
|
+
:message-groups="messageGroups"
|
|
140
|
+
:on-agent-action="handleAgentAction"
|
|
141
|
+
/>
|
|
142
|
+
<ChatInput
|
|
143
|
+
:model-value="userInput"
|
|
144
|
+
:on-send-message="handleSendMessage"
|
|
145
|
+
:on-stop-sending="handleStopSending"
|
|
146
|
+
@update:model-value="val => (userInput = val)"
|
|
147
|
+
/>
|
|
148
|
+
</div>
|
|
149
|
+
</template>
|
|
150
|
+
|
|
151
|
+
<script setup lang="ts">
|
|
152
|
+
import { computed, ref as deepRef, shallowRef } from 'vue';
|
|
153
|
+
import {
|
|
154
|
+
ChatInput,
|
|
155
|
+
MessageContainer,
|
|
156
|
+
MessageRole,
|
|
157
|
+
MessageStatus,
|
|
158
|
+
useMessageGroup,
|
|
159
|
+
type Message,
|
|
160
|
+
type TagSchema,
|
|
161
|
+
type UserMessage,
|
|
162
|
+
} from '@blueking/chat-x';
|
|
163
|
+
|
|
164
|
+
const messages = deepRef<Message[]>([]);
|
|
165
|
+
const userInput = shallowRef<string | TagSchema>('');
|
|
166
|
+
|
|
167
|
+
const { messageGroups } = useMessageGroup({
|
|
168
|
+
messages: computed(() => messages.value),
|
|
169
|
+
selectedUserMessages: deepRef(undefined),
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
const handleSendMessage = async (content: UserMessage['content']) => {
|
|
173
|
+
messages.value.push({
|
|
174
|
+
id: `user_${Date.now()}`,
|
|
175
|
+
messageId: `user_${Date.now()}`,
|
|
176
|
+
role: MessageRole.User,
|
|
177
|
+
content,
|
|
178
|
+
status: MessageStatus.Complete,
|
|
179
|
+
});
|
|
180
|
+
userInput.value = '';
|
|
181
|
+
// ...发送 AI 请求并流式追加响应
|
|
182
|
+
};
|
|
183
|
+
|
|
184
|
+
const handleStopSending = async () => {
|
|
185
|
+
const last = messages.value.at(-1);
|
|
186
|
+
if (last) last.status = MessageStatus.Stop;
|
|
187
|
+
};
|
|
188
|
+
|
|
189
|
+
const handleAgentAction = async () => {};
|
|
190
|
+
</script>
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
## AG-UI 协议
|
|
194
|
+
|
|
195
|
+
`@blueking/chat-x` 的消息类型系统基于 [AG-UI（Agent@blueking/chat-x@0.0.10-User Interaction Protocol）](https://docs.ag-ui.com/) 协议规范构建。AG-UI 是一个开放的、轻量级的、基于事件的协议，标准化了 AI Agent 后端与用户前端之间的实时双向通信。
|
|
196
|
+
|
|
197
|
+
### 协议栈定位
|
|
198
|
+
|
|
199
|
+
AG-UI 与 MCP、A2A 构成互补的三层 Agent 协议栈：
|
|
200
|
+
|
|
201
|
+
```
|
|
202
|
+
┌─────────────────────────────────────────┐
|
|
203
|
+
│ 用户界面 (Frontend) │
|
|
204
|
+
└──────────────────┬──────────────────────┘
|
|
205
|
+
│ AG-UI — Agent ↔ 用户交互
|
|
206
|
+
┌──────────────────┴──────────────────────┐
|
|
207
|
+
│ AI Agent (Backend) │
|
|
208
|
+
├──────────────────┬──────────────────────┤
|
|
209
|
+
│ MCP — Agent ↔ 工具/数据 │ A2A — Agent ↔ Agent │
|
|
210
|
+
└──────────────────┴──────────────────────┘
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
- **AG-UI**：连接 Agent 与用户界面，处理消息流、状态同步、工具调用展示
|
|
214
|
+
- **MCP**：连接 Agent 与工具/数据源
|
|
215
|
+
- **A2A**：协调分布式 Agent 间的通信
|
|
216
|
+
|
|
217
|
+
### chat-x 中的 AG-UI 实现
|
|
218
|
+
|
|
219
|
+
组件库在 `src/ag-ui/types/` 中实现了 AG-UI 协议的核心类型定义：
|
|
220
|
+
|
|
221
|
+
| 模块 | 对应协议能力 | 说明 |
|
|
222
|
+
| ---------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
|
|
223
|
+
| `MessageRole` | 消息角色标识 | 22 种角色枚举，覆盖 User、Assistant、Tool、Reasoning、Activity 等全部 Agent 对话场景 |
|
|
224
|
+
| `MessageStatus` | 运行生命周期 | Pending → Streaming → Complete / Error / Stop，对应 AG-UI 的 Run Lifecycle 事件 |
|
|
225
|
+
| `MessageContentType` | 内容类型分发 | Text、Binary、Function、FlowAgent、KnowledgeRag 等，驱动多级内容渲染管线 |
|
|
226
|
+
| `ToolCall` / `FunctionCall` | 工具调用 | 标准化的工具调用结构，包含函数名、参数、描述，`ToolMessage` 通过 `toolCallId` 关联执行结果 |
|
|
227
|
+
| `BaseMessage<Role, Content>` | 消息基础模型 | 泛型消息基类，按 `role` 判别联合类型，支持 `declare global` 零侵入扩展 |
|
|
228
|
+
| `ContentMap` | 内容类型映射 | 按 `MessageContentType` 映射到具体内容结构，同样支持全局类型扩展 |
|
|
229
|
+
|
|
230
|
+
所有组件（`MessageRender`、`ContentRender`、`ChatInput` 等）均基于这套 AG-UI 类型系统进行消息分发和渲染，确保前端 UI 与 Agent 后端的交互遵循统一的协议规范。
|
|
231
|
+
|
|
232
|
+
## 核心概念
|
|
233
|
+
|
|
234
|
+
### 消息角色（MessageRole）
|
|
235
|
+
|
|
236
|
+
| 类别 | 角色 | 说明 |
|
|
237
|
+
| -------- | ------------------------------------ | ---------------------------------------------------- |
|
|
238
|
+
| 核心对话 | `User`、`Assistant` | 用户消息和 AI 回复 |
|
|
239
|
+
| AI 能力 | `Tool`、`Reasoning`、`Activity` | 工具调用结果、推理过程、活动（知识库/流程/引用文档） |
|
|
240
|
+
| 系统 | `System`、`Info`、`Guide`、`Loading` | 系统消息、信息提示、引导、加载 |
|
|
241
|
+
| 控制 | `Pause`、`Placeholder`、`Hidden*` | 暂停、占位、隐藏系列 |
|
|
242
|
+
| 模板 | `Template*` | 预设对话模板系列 |
|
|
243
|
+
|
|
244
|
+
通过 `declare global { interface AIBluekingMessageMap }` 注册自定义消息角色，类型自动合并到 `Message` 联合中。
|
|
245
|
+
|
|
246
|
+
### 消息状态（MessageStatus）
|
|
247
|
+
|
|
248
|
+
```
|
|
249
|
+
Pending → Streaming → Complete / Error / Stop
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
| 状态 | 说明 |
|
|
253
|
+
| ----------- | ---------- |
|
|
254
|
+
| `Pending` | 等待响应 |
|
|
255
|
+
| `Streaming` | 流式输出中 |
|
|
256
|
+
| `Complete` | 已完成 |
|
|
257
|
+
| `Error` | 出错 |
|
|
258
|
+
| `Stop` | 已停止 |
|
|
259
|
+
| `Success` | 成功 |
|
|
260
|
+
| `Disabled` | 已禁用 |
|
|
261
|
+
|
|
262
|
+
### 消息结构（Message）
|
|
263
|
+
|
|
264
|
+
```typescript
|
|
265
|
+
import { MessageRole, MessageStatus, type Message } from '@blueking/chat-x';
|
|
266
|
+
|
|
267
|
+
const message: Message = {
|
|
268
|
+
id: 'msg-1',
|
|
269
|
+
messageId: 1001,
|
|
270
|
+
role: MessageRole.User,
|
|
271
|
+
content: '你好，请介绍一下蓝鲸智云',
|
|
272
|
+
status: MessageStatus.Complete,
|
|
273
|
+
};
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## 组件一览
|
|
277
|
+
|
|
278
|
+
### 消息展示
|
|
279
|
+
|
|
280
|
+
| 组件 | 说明 |
|
|
281
|
+
| ------------------ | -------------------------------------------------------------------- |
|
|
282
|
+
| `ChatContainer` | 完整对话布局（推荐入口），封装消息分组、快捷指令、执行摘要、多选分享 |
|
|
283
|
+
| `MessageContainer` | 消息列表容器 |
|
|
284
|
+
| `MessageRender` | 单条消息渲染器，按 role 分发到具体消息组件 |
|
|
285
|
+
|
|
286
|
+
### 输入交互
|
|
287
|
+
|
|
288
|
+
| 组件 | 说明 |
|
|
289
|
+
| ---------------- | ----------------------------------------------- |
|
|
290
|
+
| `ChatInput` | 聊天输入框，支持 `/` Prompt、`@` 资源、文件上传 |
|
|
291
|
+
| `AiSelection` | AI 划词选择浮窗 |
|
|
292
|
+
| `ShortcutBtns` | 快捷指令按钮组（空对话引导） |
|
|
293
|
+
| `ShortcutRender` | 快捷指令表单渲染器 |
|
|
294
|
+
|
|
295
|
+
### 内容渲染
|
|
296
|
+
|
|
297
|
+
| 组件 | 说明 |
|
|
298
|
+
| ----------------- | ----------------------------------------- |
|
|
299
|
+
| `ContentRender` | 内容渲染器（按内容类型分发） |
|
|
300
|
+
| `MarkdownContent` | Markdown 渲染（内含代码、公式、图表分发） |
|
|
301
|
+
| `CodeContent` | 代码块高亮（180+ 语言） |
|
|
302
|
+
| `LatexContent` | LaTeX 公式渲染（KaTeX） |
|
|
303
|
+
| `MermaidContent` | Mermaid 图表渲染 |
|
|
304
|
+
|
|
305
|
+
### 文件与图片
|
|
306
|
+
|
|
307
|
+
| 组件 | 说明 |
|
|
308
|
+
| ------------------- | -------------------------------- |
|
|
309
|
+
| `AiImage` | 图片展示（加载状态、错误重试） |
|
|
310
|
+
| `ImagePreview` | 图片全屏预览（缩放、旋转、下载） |
|
|
311
|
+
| `ImagePreviewGroup` | 多图预览管理（provide/inject） |
|
|
312
|
+
|
|
313
|
+
### 工具与反馈
|
|
314
|
+
|
|
315
|
+
| 组件 | 说明 |
|
|
316
|
+
| --------------------- | -------------------------------------- |
|
|
317
|
+
| `MessageTools` | 消息工具栏（复制、引用、点赞、分享等） |
|
|
318
|
+
| `MessageUserFeedback` | 用户反馈组件 |
|
|
319
|
+
| `ToolCallRender` | 工具调用卡片渲染 |
|
|
320
|
+
| `ExecutionSummary` | 执行摘要侧栏 |
|
|
321
|
+
|
|
322
|
+
### 辅助组件
|
|
323
|
+
|
|
324
|
+
| 组件 | 说明 |
|
|
325
|
+
| ------------------ | ------------ |
|
|
326
|
+
| `ScrollBtn` | 返回底部按钮 |
|
|
327
|
+
| `ToolBtn` | 工具按钮 |
|
|
328
|
+
| `ShortcutBtn` | 快捷指令按钮 |
|
|
329
|
+
| `AnimationText` | 流式动画文本 |
|
|
330
|
+
| `HighlightKeyword` | 关键词高亮 |
|
|
331
|
+
| `SelectionFooter` | 多选操作栏 |
|
|
332
|
+
| `MessageLoading` | 消息加载动画 |
|
|
333
|
+
|
|
334
|
+
## Composables 组合式函数
|
|
335
|
+
|
|
336
|
+
| Composable | 说明 |
|
|
337
|
+
| ------------------------ | --------------------------------------------------------------------- |
|
|
338
|
+
| `useMessageGroup` | 将 `Message[]` 转为 `MessageGroup[]`（分组、Tool 注入、Loading 追加） |
|
|
339
|
+
| `useContainerScroll` | 消息容器自动滚动管理 |
|
|
340
|
+
| `useClipboard` | 剪贴板操作 |
|
|
341
|
+
| `useAnimationText` | 文本流式动画 |
|
|
342
|
+
| `useCommandSelection` | 斜杠命令选择 |
|
|
343
|
+
| `useMenuKeydown` | 菜单键盘导航 |
|
|
344
|
+
| `useObserverVisibleList` | IntersectionObserver 可见列表监听 |
|
|
345
|
+
| `useParentScrolling` | 父容器滚动检测 |
|
|
346
|
+
| `useGlobalConfig` | 全局配置注入 |
|
|
347
|
+
|
|
348
|
+
## 类型导入
|
|
349
|
+
|
|
350
|
+
```typescript
|
|
351
|
+
import type {
|
|
352
|
+
Message,
|
|
353
|
+
UserMessage,
|
|
354
|
+
AssistantMessage,
|
|
355
|
+
ReasoningMessage,
|
|
356
|
+
ToolMessage,
|
|
357
|
+
InfoMessage,
|
|
358
|
+
LoadingMessage,
|
|
359
|
+
ActivityMessage,
|
|
360
|
+
GuideMessage,
|
|
361
|
+
SystemMessage,
|
|
362
|
+
Shortcut,
|
|
363
|
+
ShortcutComponent,
|
|
364
|
+
IToolBtn,
|
|
365
|
+
TagSchema,
|
|
366
|
+
InputContent,
|
|
367
|
+
UploadFile,
|
|
368
|
+
ImageItem,
|
|
369
|
+
IAiSlashMenuItem,
|
|
370
|
+
IAiSlashGroupItem,
|
|
371
|
+
} from '@blueking/chat-x';
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
## 常量导入
|
|
375
|
+
|
|
376
|
+
```typescript
|
|
377
|
+
import {
|
|
378
|
+
MessageRole,
|
|
379
|
+
MessageStatus,
|
|
380
|
+
MessageContentType,
|
|
381
|
+
CONST_MESSAGE_TOOLS, // AI 消息默认工具：复制、引用、重新生成、分享
|
|
382
|
+
CONST_USER_MESSAGE_TOOLS, // 用户消息默认工具：复制、引用、编辑、删除
|
|
383
|
+
CONST_UPDATE_TOOLS, // 更新工具：点赞、不满意、删除
|
|
384
|
+
} from '@blueking/chat-x';
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
## 架构概览
|
|
388
|
+
|
|
389
|
+
```
|
|
390
|
+
ChatContainer ← 一站式对话布局
|
|
391
|
+
├── MessageContainer ← 消息列表容器
|
|
392
|
+
│ ├── MessageRender × N ← 按 role 分发渲染
|
|
393
|
+
│ │ ├── UserMessage ← 用户消息
|
|
394
|
+
│ │ ├── AssistantMessage ← AI 回复
|
|
395
|
+
│ │ │ ├── ContentRender ← 内容分发
|
|
396
|
+
│ │ │ │ └── MarkdownContent ← Markdown 解析
|
|
397
|
+
│ │ │ │ ├── CodeContent ← 代码高亮
|
|
398
|
+
│ │ │ │ ├── LatexContent ← LaTeX 公式
|
|
399
|
+
│ │ │ │ └── MermaidContent ← 图表
|
|
400
|
+
│ │ │ └── ToolcallRender × N ← 工具调用卡片
|
|
401
|
+
│ │ ├── ReasoningMessage ← 推理过程
|
|
402
|
+
│ │ ├── ActivityMessage ← 活动消息
|
|
403
|
+
│ │ └── LoadingMessage ← 加载动画
|
|
404
|
+
│ ├── MessageTools ← 消息工具栏
|
|
405
|
+
│ └── ScrollBtn ← 返回底部
|
|
406
|
+
├── ShortcutBtns ← 快捷指令引导
|
|
407
|
+
├── ShortcutRender ← 快捷指令表单
|
|
408
|
+
├── ChatInput ← 输入区
|
|
409
|
+
│ ├── AiSlashEditor ← 富文本编辑器（/ @ 触发）
|
|
410
|
+
│ └── InputAttachment ← 文件附件
|
|
411
|
+
└── SelectionFooter ← 多选操作栏
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
**数据流**：`ChatInput → onSendMessage → 业务层 API → AG-UI Message[] 写入 → useMessageGroup 分组 → MessageContainer 按 role 分发渲染`
|
|
415
|
+
|
|
416
|
+
## 扩展
|
|
417
|
+
|
|
418
|
+
### 自定义消息类型
|
|
419
|
+
|
|
420
|
+
通过 TypeScript 声明合并扩展消息角色，在 `MessageRender` 的默认 slot 中渲染自定义组件：
|
|
421
|
+
|
|
422
|
+
```typescript
|
|
423
|
+
declare global {
|
|
424
|
+
interface AIBluekingMessageMap {
|
|
425
|
+
chart: BaseMessage<'chart', { type: string; data: unknown[] }>;
|
|
426
|
+
}
|
|
427
|
+
}
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
### 工具栏定制
|
|
431
|
+
|
|
432
|
+
通过 `onAgentAction` / `onUserAction` 回调处理工具按钮点击，`messageToolsStatus` 控制按钮的禁用/隐藏，`like`/`unlike` 返回反馈原因数组。
|
|
433
|
+
|
|
434
|
+
### 主题定制
|
|
435
|
+
|
|
436
|
+
CSS 变量 + `useGlobalConfig` 统一调整全局展示配置。
|
|
437
|
+
|
|
438
|
+
## MCP Server
|
|
439
|
+
|
|
440
|
+
`@blueking/chat-x` 内置 MCP Server，供 AI IDE（如 Cursor）通过标准协议查询组件文档。
|
|
441
|
+
|
|
442
|
+
### 配置
|
|
443
|
+
|
|
444
|
+
在 Cursor 的 `.cursor/mcp.json` 中添加：
|
|
445
|
+
|
|
446
|
+
```json
|
|
447
|
+
{
|
|
448
|
+
"mcpServers": {
|
|
449
|
+
"chat-x": {
|
|
450
|
+
"command": "npx",
|
|
451
|
+
"args": ["@blueking/chat-x"]
|
|
452
|
+
}
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
### 可用工具
|
|
458
|
+
|
|
459
|
+
| 工具 | 说明 |
|
|
460
|
+
| ------------------- | ------------------------------------------- |
|
|
461
|
+
| `list_components` | 列出所有组件，支持按 domain / category 过滤 |
|
|
462
|
+
| `get_component_doc` | 获取指定组件文档，含 AI 摘要 |
|
|
463
|
+
| `search_docs` | 关键词搜索文档 |
|
|
464
|
+
|
|
465
|
+
## 依赖说明
|
|
466
|
+
|
|
467
|
+
| 依赖 | 版本 | 说明 |
|
|
468
|
+
| ------------ | -------- | --------------------- |
|
|
469
|
+
| vue | ^3.5.24 | Vue 3 核心库 |
|
|
470
|
+
| bkui-vue | 2.x | 蓝鲸 UI 组件库 |
|
|
471
|
+
| highlight.js | ^11.11.1 | 代码高亮（180+ 语言） |
|
|
472
|
+
| katex | ^0.16.27 | LaTeX 公式渲染 |
|
|
473
|
+
| mermaid | ^11.12.2 | 图表渲染 |
|
|
474
|
+
| dompurify | ^3.3.1 | HTML 安全过滤 |
|
|
475
|
+
|
|
476
|
+
## 浏览器兼容性
|
|
477
|
+
|
|
478
|
+
支持所有现代浏览器，不支持 IE：
|
|
479
|
+
|
|
480
|
+
| Chrome | Firefox | Safari | Edge |
|
|
481
|
+
| ------ | ------- | ------ | ------ |
|
|
482
|
+
| 最新版 | 最新版 | 最新版 | 最新版 |
|
|
483
|
+
|
|
484
|
+
## 文档
|
|
485
|
+
|
|
486
|
+
完整文档基于 VitePress 构建，本地启动：
|
|
487
|
+
|
|
488
|
+
```bash
|
|
489
|
+
pnpm wiki:dev
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
## 许可证
|
|
493
|
+
|
|
494
|
+
[MIT](../../LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@blueking/chat-x",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.12",
|
|
4
4
|
"description": "",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"scripts": {
|
|
@@ -37,7 +37,8 @@
|
|
|
37
37
|
},
|
|
38
38
|
"types": "dist/index.d.ts",
|
|
39
39
|
"files": [
|
|
40
|
-
"dist"
|
|
40
|
+
"dist",
|
|
41
|
+
"README.md"
|
|
41
42
|
],
|
|
42
43
|
"keywords": [],
|
|
43
44
|
"author": "",
|
package/readme.md
DELETED
|
File without changes
|