@blueking/bkui-knowledge 0.0.1-beta.14 → 0.0.1-beta.15

package/knowledge/skills/chat-x-ccontribute/references/QA.md

@@ -0,0 +1,117 @@
+# 常见问题 Q&A
+
+## Q: 如何添加新的消息类型？
+
+1. 在 `src/types/` 扩展 `MessageRole` 枚举
+2. 创建新的消息组件
+3. 在 `MessageRender` 中添加渲染逻辑
+
+详细步骤见 [development-workflow.md](development-workflow.md) 中的"添加新消息类型"部分。
+
+## Q: 如何自定义工具按钮？
+
+```typescript
+import { CONST_MESSAGE_TOOLS, type IToolBtn } from '@blueking/chat-x';
+
+// 自定义工具按钮
+const customTools: IToolBtn[] = [
+  ...CONST_MESSAGE_TOOLS,
+  {
+    id: 'custom',
+    name: '自定义',
+    description: '自定义操作',
+  },
+];
+```
+
+## Q: 如何处理流式消息？
+
+```typescript
+// 1. 创建 pending 状态的消息
+const message = { status: MessageStatus.Pending, content: '' };
+messages.push(message);
+
+// 2. 流式更新内容
+for await (const chunk of stream) {
+  message.content += chunk;
+  message.status = MessageStatus.Streaming;
+}
+
+// 3. 完成
+message.status = MessageStatus.Complete;
+```
+
+## Q: 组件样式如何调试？
+
+1. 使用浏览器开发者工具检查元素
+2. 检查 CSS 选择器优先级
+3. 检查 scoped 样式是否正确
+4. 使用 Vue DevTools 调试组件状态
+
+## Q: 如何添加新的翻译文本？
+
+在 `src/lang/lang.ts` 中添加：
+
+```typescript
+const LANG_MAP: Record<string, string> = {
+  新文本: 'New Text',
+  // ...
+};
+```
+
+使用时：
+
+```typescript
+import { t } from '@blueking/chat-x';
+const label = t('新文本'); // 自动根据语言返回
+```
+
+## Q: 如何在 Playground 中调试？
+
+使用 `playground/` 目录进行开发调试：
+
+```vue
+<!-- playground/App.vue -->
+<template>
+  <ChatInput
+    v-model="input"
+    :on-send-message="handleSend"
+  />
+  <MessageContainer :messages="messages" />
+</template>
+```
+
+**步骤**：
+
+1. 修改 `playground/App.vue` 添加测试代码
+2. 运行 `pnpm --filter @blueking/chat-x dev`
+3. 在浏览器中打开 http://localhost:5173
+4. 参考 `playground/mock.ts` 创建测试消息数据
+
+## Q: Composable 使用示例
+
+### 常用 Composables
+
+```typescript
+import {
+  useClipboard, // 剪贴板操作
+  useContainerScrollProvider, // 滚动控制（Provider）
+  useContainerScrollConsumer, // 滚动控制（Consumer）
+  useAnimationText, // 文本动画
+  useMenuKeydown, // 菜单键盘事件
+  useGlobalConfig, // 全局配置
+} from '@blueking/chat-x';
+```
+
+### 使用示例
+
+```typescript
+// 剪贴板
+const { copy } = useClipboard();
+await copy('复制的内容');
+
+// 滚动控制（在容器组件中）
+const containerRef = useTemplateRef<HTMLElement>('container');
+const bottomRef = useTemplateRef<HTMLElement>('bottom');
+const { isScrollBottom, toScrollBottom } = useContainerScrollProvider(containerRef, bottomRef);
+```

package/knowledge/skills/chat-x-ccontribute/references/component-api.md

@@ -0,0 +1,434 @@
+# 组件 API 参考
+
+## 组件设计原则
+
+### 原子设计方法论
+
+组件按复杂度分为两层：
+
+**原子组件（Atomic）**：最基础的 UI 单元
+
+- `ScrollBtn` - 滚动按钮
+- `ToolBtn` - 工具按钮
+- `ShortcutBtn` - 快捷指令按钮
+- `MarkdownContent` - Markdown 内容
+- `CodeContent` - 代码块
+- `MermaidContent` - Mermaid 图表
+- `LatexContent` - LaTeX 公式
+
+**分子组件（Molecular）**：由原子组件组合而成
+
+- `ChatInput` - 聊天输入框
+- `MessageContainer` - 消息容器
+- `MessageRender` - 消息渲染器
+- `ContentRender` - 内容渲染器
+- `AiSelection` - AI 选择弹窗
+- `ShortcutRender` - 快捷指令渲染器
+
+### 组件层级关系
+
+```
+MessageContainer
+├── MessageRender
+│   ├── UserMessage → MessageTools → ContentRender
+│   ├── AssistantMessage → ContentRender → MarkdownContent
+│   ├── ReasoningMessage
+│   ├── ToolMessage
+│   └── InfoMessage
+└── ScrollBtn
+
+ChatInput
+├── AiSlashInput → AiSlashMenu
+└── InputAttachment
+```
+
+---
+
+## 核心组件
+
+### ChatInput
+
+聊天输入框组件。
+
+**Props**
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| modelValue | `string \| TagSchema` | - | 输入框值，支持 v-model |
+| cite | `string` | `''` | 引用内容，v-model:cite |
+| messageStatus | `MessageStatus` | - | 消息状态 |
+| placeholder | `string` | - | 占位符 |
+| prompts | `string[]` | `[]` | Prompt 列表（`/` 触发） |
+| resources | `IAiSlashMenuItem[]` | `[]` | 资源列表（`@` 触发） |
+| onSendMessage | `(value, docSchema) => Promise<void>` | - | 发送回调 |
+| onStopSending | `() => Promise<void>` | - | 停止回调 |
+
+**Slots**
+
+| 插槽 | 说明 |
+|------|------|
+| top | 容器顶部 |
+| input-header | 输入框头部（默认显示引用） |
+| attachment | 附件区域 |
+| send-icon | 发送按钮图标 |
+
+**示例**
+
+```vue
+<template>
+  <ChatInput
+    v-model="input"
+    v-model:cite="cite"
+    :message-status="status"
+    :prompts="prompts"
+    :resources="resources"
+    :on-send-message="handleSend"
+    :on-stop-sending="handleStop"
+  >
+    <template #attachment>
+      <button @click="uploadFile">📎 上传</button>
+    </template>
+  </ChatInput>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ChatInput, MessageStatus, type TagSchema } from '@blueking/chat-x';
+
+const input = ref('');
+const cite = ref('');
+const status = ref(MessageStatus.Complete);
+const prompts = ref(['帮我写文章', '解释代码']);
+const resources = ref([{ id: 'file', name: '文件', type: 'file' }]);
+
+const handleSend = async (value: string, docSchema: TagSchema) => {
+  status.value = MessageStatus.Streaming;
+  // ... API 调用
+  status.value = MessageStatus.Complete;
+};
+
+const handleStop = async () => {
+  status.value = MessageStatus.Stop;
+};
+</script>
+```
+
+---
+
+### MessageContainer
+
+消息列表容器。
+
+**Props**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| messages | `Message[]` | **必填**，消息列表 |
+| messageStatus | `MessageStatus` | 当前消息状态 |
+| onAgentAction | `(tool: IToolBtn) => Promise<string[] \| void>` | AI 消息工具回调 |
+| onUserAction | `(tool: IToolBtn) => Promise<void>` | 用户消息工具回调 |
+
+**Events**
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| stopStreaming | - | 点击停止按钮 |
+
+**Slots**
+
+| 插槽 | 参数 | 说明 |
+|------|------|------|
+| default | `{ message }` | 自定义消息渲染 |
+
+**工具操作返回值**
+
+```typescript
+const handleAgentAction = async (tool: IToolBtn) => {
+  switch (tool.id) {
+    case 'copy':
+      // 复制由组件内部处理
+      break;
+    case 'like':
+      // 返回满意原因列表
+      return ['回答准确', '信息全面'];
+    case 'unlike':
+      // 返回不满意原因列表
+      return ['信息错误', '不相关'];
+    case 'rebuild':
+      // 重新生成
+      await regenerateMessage(tool.messageId);
+      break;
+  }
+};
+```
+
+---
+
+### ContentRender
+
+内容渲染器，自动识别并渲染不同类型内容。
+
+**Props**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| content | `string \| InputContent[]` | 渲染内容 |
+| isStreaming | `boolean` | 是否流式输出中 |
+
+**支持的内容类型**
+
+- 纯文本
+- Markdown
+- 代码块
+- LaTeX 公式
+- Mermaid 图表
+- 图片
+
+---
+
+### ShortcutBtns
+
+快捷指令按钮组。
+
+**Props**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| shortcuts | `Shortcut[]` | 快捷指令列表 |
+
+**Events**
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| selectShortcut | `Shortcut` | 选择快捷指令 |
+
+**Shortcut 类型**
+
+```typescript
+interface Shortcut {
+  id: string;
+  name: string;
+  description?: string;
+  components?: ShortcutComponent[]; // 表单组件
+}
+
+interface ShortcutComponent {
+  type: 'select' | 'textarea' | 'input';
+  key: string;
+  name: string;
+  fillBack?: boolean; // 是否填充回输入框
+  props?: Record<string, any>;
+}
+```
+
+---
+
+### AiSelection
+
+AI 划词选择弹窗。
+
+**Props**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| visible | `boolean` | 显示状态，v-model:visible |
+| shortcuts | `Shortcut[]` | 快捷指令列表 |
+
+**Events**
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| selectShortcut | `Shortcut, selectedText` | 选择快捷指令 |
+
+---
+
+## 原子组件
+
+### ToolBtn
+
+工具按钮。
+
+```vue
+<ToolBtn :tool="{ id: 'copy', name: '复制' }" @click="handleClick" />
+```
+
+### ScrollBtn
+
+滚动按钮。
+
+```vue
+<ScrollBtn @click="scrollToBottom">返回底部</ScrollBtn>
+```
+
+### MarkdownContent
+
+Markdown 渲染组件。
+
+```vue
+<MarkdownContent :content="markdownText" :is-streaming="false" />
+```
+
+### CodeContent
+
+代码块渲染组件（自动高亮）。
+
+```vue
+<CodeContent :code="codeString" language="typescript" />
+```
+
+### LatexContent
+
+LaTeX 公式渲染。
+
+```vue
+<LatexContent formula="E = mc^2" />
+```
+
+### MermaidContent
+
+Mermaid 图表渲染。
+
+```vue
+<MermaidContent :code="mermaidCode" />
+```
+
+---
+
+## 完整页面示例
+
+```vue
+<template>
+  <div class="chat-page">
+    <!-- 快捷指令（无消息时显示） -->
+    <ShortcutBtns
+      v-if="!messages.length"
+      :shortcuts="shortcuts"
+      @select-shortcut="handleShortcut"
+    />
+    
+    <!-- 消息列表 -->
+    <MessageContainer
+      v-else
+      :messages="messages"
+      :message-status="status"
+      :on-agent-action="handleAgentAction"
+      :on-user-action="handleUserAction"
+      @stop-streaming="handleStop"
+    />
+    
+    <!-- 输入框 -->
+    <ChatInput
+      v-model="input"
+      :message-status="status"
+      :prompts="prompts"
+      :on-send-message="handleSend"
+      :on-stop-sending="handleStop"
+    />
+    
+    <!-- 划词选择 -->
+    <AiSelection
+      v-model:visible="selectionVisible"
+      :shortcuts="selectionShortcuts"
+      @select-shortcut="handleSelection"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  ChatInput,
+  MessageContainer,
+  ShortcutBtns,
+  AiSelection,
+  MessageStatus,
+  MessageRole,
+  type Message,
+  type Shortcut,
+  type IToolBtn,
+  type TagSchema,
+} from '@blueking/chat-x';
+
+const input = ref('');
+const status = ref(MessageStatus.Complete);
+const messages = ref<Message[]>([]);
+const selectionVisible = ref(false);
+
+const shortcuts = ref<Shortcut[]>([
+  { id: 'ask', name: '问问小鲸' },
+  { id: 'code', name: '代码审查' },
+]);
+
+const selectionShortcuts = ref<Shortcut[]>([
+  { id: 'explain', name: '解释' },
+  { id: 'translate', name: '翻译' },
+]);
+
+const prompts = ref(['帮我写文章', '解释代码']);
+
+const handleSend = async (value: string, docSchema: TagSchema) => {
+  // 添加用户消息
+  messages.value.push({
+    id: Date.now().toString(),
+    messageId: Date.now(),
+    role: MessageRole.User,
+    content: value,
+    status: MessageStatus.Complete,
+  });
+  
+  // 添加 AI 消息占位
+  const aiMessage: Message = {
+    id: (Date.now() + 1).toString(),
+    messageId: Date.now() + 1,
+    role: MessageRole.Assistant,
+    content: '',
+    status: MessageStatus.Pending,
+  };
+  messages.value.push(aiMessage);
+  
+  // 模拟流式响应
+  status.value = MessageStatus.Streaming;
+  const response = '这是 AI 的回复...';
+  for (const char of response) {
+    await new Promise(r => setTimeout(r, 30));
+    aiMessage.content += char;
+    aiMessage.status = MessageStatus.Streaming;
+  }
+  
+  aiMessage.status = MessageStatus.Complete;
+  status.value = MessageStatus.Complete;
+};
+
+const handleStop = async () => {
+  status.value = MessageStatus.Stop;
+  const lastMsg = messages.value.at(-1);
+  if (lastMsg) lastMsg.status = MessageStatus.Stop;
+};
+
+const handleAgentAction = async (tool: IToolBtn) => {
+  if (tool.id === 'like') return ['准确', '清晰'];
+  if (tool.id === 'unlike') return ['错误', '不相关'];
+};
+
+const handleUserAction = async (tool: IToolBtn) => {
+  console.log('User action:', tool.id);
+};
+
+const handleShortcut = (shortcut: Shortcut) => {
+  input.value = shortcut.name + ': ';
+};
+
+const handleSelection = (shortcut: Shortcut, text: string) => {
+  input.value = `${shortcut.name}：${text}`;
+};
+</script>
+
+<style scoped>
+.chat-page {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  padding: 16px;
+}
+</style>
+```