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

package/knowledge/skills/chat-x-custom-component/references/type-extension.md

@@ -0,0 +1,373 @@
+# 类型扩展参考
+
+本文档详细说明如何在 `@blueking/chat-x` 中扩展消息类型系统。
+
+## 类型扩展机制
+
+Chat-X 使用 TypeScript 的 `declare global` 实现类型扩展，允许用户添加自定义消息类型而无需修改库源码。
+
+### 核心接口
+
+```typescript
+// 来自 @blueking/chat-x/src/ag-ui/types/messages.ts
+
+// 消息类型映射（可扩展）
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-empty-interface
+  interface AIBluekingMessageMap {}
+}
+
+// 完整的消息映射（内置 + 用户扩展）
+export type MessageMap = AIBluekingMessageMap & {
+  [MessageRole.Activity]: ActivityMessage;
+  [MessageRole.Assistant]: AssistantMessage;
+  [MessageRole.User]: UserMessage;
+  // ... 其他内置类型
+};
+
+// 消息类型 = 映射的所有键
+export type MessageType = keyof MessageMap;
+
+// 消息联合类型
+export type Message = MessageMap[MessageType];
+```
+
+## 扩展方式
+
+### 方式 1：在入口文件中扩展
+
+```typescript
+// main.ts 或 types.ts
+import { type BaseMessage } from '@blueking/chat-x';
+
+// 定义内容类型
+interface ChartContent {
+  chartType: 'line' | 'bar' | 'pie';
+  data: Record<string, any>;
+  title?: string;
+}
+
+interface TableContent {
+  columns: { key: string; title: string }[];
+  rows: Record<string, any>[];
+}
+
+// 全局类型扩展
+declare global {
+  interface AIBluekingMessageMap {
+    chart: BaseMessage<'chart', ChartContent>;
+    table: BaseMessage<'table', TableContent>;
+  }
+}
+
+// 导出类型以便其他模块使用
+export type { ChartContent, TableContent };
+```
+
+### 方式 2：使用独立类型文件
+
+```typescript
+// types/custom-messages.d.ts
+import { type BaseMessage } from '@blueking/chat-x';
+
+declare global {
+  interface AIBluekingMessageMap {
+    custom: BaseMessage<'custom', CustomContent>;
+  }
+  
+  interface AIBluekingContentMap {
+    custom: {
+      type: 'custom';
+      data: CustomContent;
+    };
+  }
+}
+
+interface CustomContent {
+  id: string;
+  name: string;
+  content: string;
+}
+
+export {};
+```
+
+**注意**：`.d.ts` 文件末尾需要 `export {}` 使其成为模块。
+
+### 方式 3：在 Vue 组件中扩展
+
+```vue
+<script setup lang="ts">
+import { type BaseMessage } from '@blueking/chat-x';
+
+// 在 script 顶部声明
+declare global {
+  interface AIBluekingMessageMap {
+    custom: BaseMessage<'custom', CustomContent>;
+  }
+}
+
+interface CustomContent {
+  value: string;
+}
+
+// 组件逻辑...
+</script>
+```
+
+## 内容类型扩展
+
+除了消息类型，还可以扩展内容渲染类型：
+
+```typescript
+// 扩展 ContentRender 支持的内容类型
+declare global {
+  interface AIBluekingContentMap {
+    // 自定义图表内容
+    chart: {
+      type: 'chart';
+      data: {
+        chartType: string;
+        options: Record<string, any>;
+      };
+    };
+    
+    // 自定义卡片内容
+    card: {
+      type: 'card';
+      data: {
+        title: string;
+        description: string;
+        image?: string;
+      };
+    };
+  }
+}
+```
+
+## 常用内容类型模板
+
+### 图表内容
+
+```typescript
+interface ChartContent {
+  chartType: 'line' | 'bar' | 'pie' | 'treemap' | 'scatter';
+  data: {
+    labels?: string[];
+    datasets: Array<{
+      name: string;
+      values: number[];
+      color?: string;
+    }>;
+  };
+  title?: string;
+  subtitle?: string;
+  options?: {
+    legend?: boolean;
+    tooltip?: boolean;
+    animation?: boolean;
+  };
+}
+```
+
+### 表格内容
+
+```typescript
+interface TableContent {
+  columns: Array<{
+    key: string;
+    title: string;
+    width?: number | string;
+    sortable?: boolean;
+    align?: 'left' | 'center' | 'right';
+  }>;
+  rows: Array<Record<string, any>>;
+  pagination?: {
+    current: number;
+    pageSize: number;
+    total: number;
+  };
+}
+```
+
+### 卡片列表内容
+
+```typescript
+interface CardListContent {
+  items: Array<{
+    id: string;
+    title: string;
+    description?: string;
+    image?: string;
+    link?: string;
+    tags?: string[];
+    meta?: Record<string, any>;
+  }>;
+  layout?: 'grid' | 'list';
+  columns?: number;
+}
+```
+
+### 表单内容
+
+```typescript
+interface FormContent {
+  fields: Array<{
+    key: string;
+    label: string;
+    type: 'text' | 'number' | 'select' | 'textarea' | 'checkbox' | 'radio';
+    required?: boolean;
+    placeholder?: string;
+    default?: any;
+    options?: Array<{ label: string; value: any }>;
+    rules?: Array<{ validator: (value: any) => boolean; message: string }>;
+  }>;
+  submitText?: string;
+  cancelText?: string;
+}
+```
+
+### 确认对话框内容
+
+```typescript
+interface ConfirmContent {
+  title: string;
+  message: string;
+  confirmText?: string;
+  cancelText?: string;
+  type?: 'info' | 'warning' | 'error' | 'success';
+}
+```
+
+## 类型工具函数
+
+### 创建类型安全的消息
+
+```typescript
+import { type BaseMessage, MessageStatus } from '@blueking/chat-x';
+
+// 泛型消息创建函数
+function createMessage<
+  R extends string,
+  C = string
+>(
+  role: R,
+  content: C,
+  options?: Partial<Omit<BaseMessage<R, C>, 'role' | 'content'>>
+): BaseMessage<R, C> {
+  return {
+    id: crypto.randomUUID(),
+    messageId: crypto.randomUUID(),
+    role,
+    content,
+    status: MessageStatus.Complete,
+    ...options,
+  };
+}
+
+// 使用示例
+const chartMessage = createMessage('chart', {
+  chartType: 'bar',
+  data: { datasets: [] },
+});
+```
+
+### 类型守卫
+
+```typescript
+import { type Message } from '@blueking/chat-x';
+
+// 类型守卫：检查是否为特定角色的消息
+function isMessageOfRole<R extends string>(
+  message: Message,
+  role: R
+): message is Message & { role: R } {
+  return message.role === role;
+}
+
+// 使用示例
+if (isMessageOfRole(message, 'chart')) {
+  // message.content 现在是 ChartContent 类型
+  console.log(message.content.chartType);
+}
+```
+
+## 注意事项
+
+1. **类型声明位置**：`declare global` 必须在模块（有 import/export）中使用
+2. **类型覆盖**：同名接口会自动合并，确保 key 不冲突
+3. **泛型约束**：`BaseMessage<R, C>` 中 R 必须是 `MessageType` 的有效值
+4. **IDE 支持**：扩展后需重启 TypeScript 服务以更新类型提示
+
+## 完整示例
+
+```typescript
+// types/custom-messages.ts
+import { type BaseMessage, MessageStatus } from '@blueking/chat-x';
+
+// ============ 内容类型定义 ============
+
+export interface ChartContent {
+  chartType: 'line' | 'bar' | 'pie';
+  data: Record<string, any>;
+  title?: string;
+}
+
+export interface TableContent {
+  columns: Array<{ key: string; title: string }>;
+  rows: Array<Record<string, any>>;
+}
+
+export interface CodeBlockContent {
+  language: string;
+  code: string;
+  filename?: string;
+  highlight?: number[];
+}
+
+// ============ 全局类型扩展 ============
+
+declare global {
+  interface AIBluekingMessageMap {
+    chart: BaseMessage<'chart', ChartContent>;
+    table: BaseMessage<'table', TableContent>;
+    codeBlock: BaseMessage<'codeBlock', CodeBlockContent>;
+  }
+  
+  interface AIBluekingContentMap {
+    chart: { type: 'chart'; data: ChartContent };
+    table: { type: 'table'; data: TableContent };
+    codeBlock: { type: 'codeBlock'; data: CodeBlockContent };
+  }
+}
+
+// ============ 消息创建辅助函数 ============
+
+export function createChartMessage(
+  content: ChartContent,
+  options?: Partial<BaseMessage<'chart', ChartContent>>
+): BaseMessage<'chart', ChartContent> {
+  return {
+    id: crypto.randomUUID(),
+    messageId: crypto.randomUUID(),
+    role: 'chart',
+    content,
+    status: MessageStatus.Complete,
+    ...options,
+  };
+}
+
+export function createTableMessage(
+  content: TableContent,
+  options?: Partial<BaseMessage<'table', TableContent>>
+): BaseMessage<'table', TableContent> {
+  return {
+    id: crypto.randomUUID(),
+    messageId: crypto.randomUUID(),
+    role: 'table',
+    content,
+    status: MessageStatus.Complete,
+    ...options,
+  };
+}
+```

package/knowledge/skills/chat-x-unit-test/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: chat-x-unit-test
+description: 帮助开发者为 Vue 3 组件编写单元测试。当用户需要添加单元测试时使用。
+---
+
+# Vue 组件单元测试指南
+
+## 测试规范
+
+测试文件与组件同目录，命名为 `组件名.spec.ts`。
+
+## 运行测试
+
+```bash
+pnpm --filter @blueking/chat-x test              # 所有测试
+npx vitest run src/components/your-component     # 指定目录
+```
+
+## 基础模板
+
+```typescript
+import { defineComponent, h } from 'vue';
+import { type VueWrapper, mount } from '@vue/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import YourComponent from './your-component.vue';
+
+vi.mock('vue-tippy', () => ({ /* ... */ }));
+
+describe('YourComponent', () => {
+  let wrapper: VueWrapper;
+
+  beforeEach(() => { vi.clearAllMocks(); });
+  afterEach(() => { wrapper?.unmount(); });
+
+  it('应该正确渲染', () => {
+    wrapper = mount(YourComponent);
+    expect(wrapper.find('.your-component').exists()).toBe(true);
+  });
+});
+```
+
+## 测试分类
+
+- 渲染测试：组件正确渲染
+- Props 测试：属性传递和响应
+- 事件测试：emit 事件
+- Slot 测试：插槽内容
+
+## 同步更新原则
+
+修改组件代码时必须同步更新测试用例。
+
+---
+
+## 📦 可用资源
+
+- `skill://chat-x-unit-test/references/mock-patterns.md`
+- `skill://chat-x-unit-test/references/test-qa.md`
+- `skill://chat-x-unit-test/references/test-strategies.md`