agent-configs 1.0.0

package/skills/bk-chat-x/references/components-api.md

@@ -0,0 +1,340 @@
+# 组件 API 详细参考
+
+## ChatInput 聊天输入框
+
+### Props
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| modelValue | `string \| TagSchema` | - | 输入框的值，支持 v-model |
+| cite | `string` | `''` | 引用内容，支持 v-model:cite |
+| messageStatus | `MessageStatus` | - | 消息状态，控制发送按钮状态 |
+| placeholder | `string` | 见下方 | 输入框占位符 |
+| prompts | `string[]` | `[]` | Prompt 列表，输入 `/` 触发 |
+| resources | `IAiSlashMenuItem[]` | `[]` | 资源列表，输入 `@` 触发 |
+| shortcuts | `Shortcut[]` | `[]` | 快捷指令列表 |
+| shortcutId | `string` | - | 当前选中的快捷指令 ID |
+| onSendMessage | `(value: string, docSchema: TagSchema) => Promise<void>` | - | 发送消息回调 |
+| onStopSending | `() => Promise<void>` | - | 停止发送回调 |
+
+**默认占位符：**
+```
+输入 "/" 唤出 Prompt
+输入 "@" 唤出工具
+通过 Shift + Enter 进行换行输入
+```
+
+### Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| select-shortcut | `(shortcut: Shortcut, text?: string)` | 选择快捷指令 |
+| delete-shortcut | - | 删除当前快捷指令 |
+
+### Slots
+
+| 插槽名 | 说明 |
+|--------|------|
+| top | 输入框容器顶部 |
+| input-header | 输入框头部，默认显示引用 |
+| attachment | 附件区域 |
+| send-icon | 发送按钮图标 |
+
+### 键盘快捷键
+
+| 快捷键 | 说明 |
+|--------|------|
+| `Enter` | 发送消息 |
+| `Shift + Enter` | 换行 |
+| `/` | 唤出 Prompt 列表 |
+| `@` | 唤出资源列表 |
+| `↑` / `↓` | 菜单导航 |
+| `Esc` | 关闭菜单 |
+
+---
+
+## MessageContainer 消息容器
+
+### Props
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| messages | `Message[]` | - | **必填**，消息列表 |
+| messageStatus | `MessageStatus` | - | 当前消息状态 |
+| enableSelection | `boolean` | `false` | 是否启用多选模式 |
+| onAgentAction | `(tool: IToolBtn) => Promise<string[] \| void>` | - | AI 消息工具操作回调 |
+| onUserAction | `(tool: IToolBtn) => Promise<void>` | - | 用户消息工具操作回调 |
+
+### v-model
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| selectedMessages | `Message[]` | 选中的消息列表 |
+
+### Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| stopStreaming | - | 点击停止按钮 |
+
+### Slots
+
+| 插槽名 | 参数 | 说明 |
+|--------|------|------|
+| default | `{ message: Message }` | 自定义消息渲染 |
+
+### 消息分组规则
+
+- 连续的 AI 消息（Assistant、Reasoning、Tool）分为一组
+- 每个用户消息单独一组
+- 启用多选时，选中用户消息会自动关联 AI 回复
+
+---
+
+## MessageRender 消息渲染器
+
+### Props
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| message | `Partial<Message>` | - | **必填**，消息对象 |
+| onAction | `(tool: IToolBtn) => Promise<void>` | - | 工具操作回调 |
+
+### Slots
+
+| 插槽名 | 参数 | 说明 |
+|--------|------|------|
+| default | `{ content: string, status: MessageStatus }` | 自定义 Assistant 消息内容 |
+
+### 消息类型映射
+
+| MessageRole | 渲染组件 |
+|-------------|----------|
+| `User` | UserMessage |
+| `Assistant` | AssistantMessage |
+| `Reasoning` | ReasoningMessage |
+| `Tool` | ToolMessage |
+| `Info` | InfoMessage |
+| `Activity` | ActivityMessage |
+
+---
+
+## ContentRender 内容渲染器
+
+### Props
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| content | `string \| Record<string, unknown>[]` | - | **必填**，内容 |
+| status | `MessageStatus` | - | 消息状态 |
+| type | `ContentType` | - | 内容类型 |
+
+### 内容类型
+
+| 类型 | 条件 | 渲染组件 |
+|------|------|----------|
+| Text | `typeof content === 'string'` | MarkdownContent |
+| Reference | `Array.isArray(content)` | ReferenceContent |
+
+### Markdown 支持
+
+- **基础语法**：标题、加粗、斜体、链接、图片
+- **扩展语法**：表格、任务列表
+- **代码高亮**：支持 180+ 种语言
+- **LaTeX 公式**：`$...$` 行内，`$$...$$` 块级
+- **Mermaid 图表**：流程图、时序图、甘特图
+
+---
+
+## AiSelection AI 划词选择
+
+### Props
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| visible | `boolean` | - | 控制显示 (v-model:visible) |
+| shortcuts | `Shortcut[]` | `[{ id: 'ask-whale', name: '问问小鲸' }]` | 快捷指令列表 |
+| maxShortcutCount | `number` | `3` | 最多显示数量 |
+| offset | `number` | `10` | 弹窗垂直间距 |
+
+### Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| selectShortcut | `(shortcut: Shortcut, text: string)` | 选择快捷指令 |
+| selectionChange | `(text: string)` | 选区文本变化 |
+
+### Slots
+
+| 插槽名 | 参数 | 说明 |
+|--------|------|------|
+| default | `{ shortcuts: Shortcut[] }` | 自定义弹窗内容 |
+
+---
+
+## ShortcutRender 快捷指令表单
+
+### Props
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| name | `string` | - | 快捷指令名称 |
+| components | `ShortcutComponent[]` | - | 表单组件配置 |
+| formModel | `Record<string, unknown>` | - | 表单初始值 |
+| description | `string` | - | 描述 |
+
+### Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| close | - | 点击关闭按钮 |
+| submit | `(formModel: Record<string, unknown>)` | 表单提交 |
+
+---
+
+## ShortcutBtns 快捷指令按钮组
+
+### Props
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| shortcuts | `Shortcut[]` | - | 快捷指令列表 |
+
+### Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| selectShortcut | `(shortcut: Shortcut)` | 选择快捷指令 |
+
+---
+
+## 类型定义
+
+### Message 消息
+
+```typescript
+interface BaseMessage<T extends MessageType, C = string> {
+  id: string;                    // 客户端唯一 ID
+  messageId: number | string;    // 服务端返回 ID
+  role: T;                       // 消息角色
+  content: C;                    // 消息内容
+  status: MessageStatus;         // 消息状态
+  name?: string;                 // 名称
+  property?: {
+    extra?: {
+      cite: string | { title: string; data: { key: string; value: string }[] };
+      command: string;
+      context: Record<string, any>[];
+      shortcut?: Shortcut;
+    };
+  };
+}
+
+// 具体消息类型
+type UserMessage = BaseMessage<MessageRole.User, InputContent[] | string>;
+
+interface AssistantMessage extends BaseMessage<MessageRole.Assistant> {
+  toolCalls?: ToolCall[];
+}
+
+interface ReasoningMessage extends BaseMessage<MessageRole.Reasoning, string[]> {
+  duration?: number;  // 推理耗时 (毫秒)
+}
+
+interface ToolMessage extends BaseMessage<MessageRole.Tool, string> {
+  toolCallId: string;  // 对应 toolCalls[].id
+  duration: number;    // 执行耗时
+  error?: string;
+}
+
+interface ActivityMessage extends BaseMessage<MessageRole.Activity, Record<string, unknown>[]> {
+  activityType: string;
+}
+
+type InfoMessage = BaseMessage<MessageRole.Info, string>;
+```
+
+### ToolCall 工具调用
+
+```typescript
+type ToolCall = {
+  id: string;
+  type: MessageContentType.Function;
+  function: {
+    name: string;
+    arguments: string;
+    description?: string;
+  };
+};
+```
+
+### IToolBtn 工具按钮
+
+```typescript
+interface IToolBtn {
+  id: 'copy' | 'cite' | 'rebuild' | 'share' | 'like' | 'unlike' | 'edit' | 'delete';
+  name: string;
+  description: string;
+}
+```
+
+### TagSchema 输入标签结构
+
+```typescript
+type TagSchema = Array<Array<{
+  type: 'text' | 'tag';
+  text?: string;
+  data?: {
+    type: string;
+    label: string;
+    value: string;
+  };
+}>>;
+```
+
+### IAiSlashMenuItem 资源菜单项
+
+```typescript
+interface IAiSlashMenuItem {
+  id: string;
+  name: string;
+  type: string;
+  [key: string]: any;
+}
+```
+
+---
+
+## 常量
+
+```typescript
+// 默认 AI 消息工具
+const CONST_MESSAGE_TOOLS: IToolBtn[] = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'cite', name: '引用', description: '引用' },
+  { id: 'rebuild', name: '重新生成', description: '重新生成' },
+  { id: 'share', name: '分享', description: '分享' },
+];
+
+// 默认用户消息工具
+const CONST_USER_MESSAGE_TOOLS: IToolBtn[] = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'cite', name: '引用', description: '引用' },
+  { id: 'edit', name: '编辑', description: '编辑' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+
+// 反馈工具
+const CONST_UPDATE_TOOLS: IToolBtn[] = [
+  { id: 'like', name: '点赞', description: '点赞' },
+  { id: 'unlike', name: '不满意', description: '不满意' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+
+// Z-Index 层级
+const CHAT_Z_INDEX = 9999;
+const EDITOR_Z_INDEX = 10000;
+const EDITOR_MENU_Z_INDEX = 10001;
+const SHORTCUT_MENU_Z_INDEX = 10002;
+const SELECTION_Z_INDEX = 10003;
+```

package/skills/bk-chat-x/references/examples.md

@@ -0,0 +1,386 @@
+# 完整示例
+
+## AI 聊天页面完整实现
+
+```vue
+<template>
+  <div class="chat-page">
+    <!-- 快捷指令 (空消息时显示) -->
+    <ShortcutBtns
+      v-if="messages.length === 0"
+      :shortcuts="shortcuts"
+      @select-shortcut="handleSelectShortcut"
+    />
+    
+    <!-- 消息列表 -->
+    <MessageContainer
+      v-else
+      :messages="messages"
+      :message-status="messageStatus"
+      :on-agent-action="handleAgentAction"
+      :on-user-action="handleUserAction"
+      @stop-streaming="handleStopStreaming"
+    />
+    
+    <!-- 快捷指令表单 (与 ChatInput 互斥) -->
+    <ShortcutRender
+      v-if="selectedShortcut?.components?.length"
+      v-bind="selectedShortcut"
+      @close="handleCloseShortcut"
+      @submit="handleSubmitShortcut"
+    />
+    
+    <!-- 输入框 -->
+    <ChatInput
+      v-else
+      v-model="userInput"
+      v-model:cite="citeContent"
+      :message-status="messageStatus"
+      :shortcuts="shortcuts"
+      :shortcut-id="selectedShortcut?.id"
+      :on-send-message="handleSendMessage"
+      :on-stop-sending="handleStopSending"
+      @select-shortcut="handleSelectShortcut"
+      @delete-shortcut="handleDeleteShortcut"
+    />
+    
+    <!-- 划词选择 -->
+    <AiSelection
+      v-model:visible="aiSelectionVisible"
+      :shortcuts="shortcuts"
+      @select-shortcut="handleSelectShortcut"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  ChatInput,
+  MessageContainer,
+  ShortcutBtns,
+  ShortcutRender,
+  AiSelection,
+  MessageRole,
+  MessageStatus,
+  type Message,
+  type Shortcut,
+  type IToolBtn,
+  type TagSchema,
+} from '@blueking/chat-x';
+
+// 状态
+const messages = ref<Message[]>([]);
+const userInput = ref<string | TagSchema>('');
+const citeContent = ref('');
+const messageStatus = ref(MessageStatus.Complete);
+const selectedShortcut = ref<Shortcut | null>(null);
+const aiSelectionVisible = ref(false);
+
+// 快捷指令配置
+const shortcuts = ref<Shortcut[]>([
+  { id: 'ask', name: '问问小鲸' },
+  {
+    id: 'translate',
+    name: '翻译',
+    components: [
+      {
+        type: 'select',
+        key: 'targetLang',
+        name: '目标语言',
+        props: { options: [{ label: '英文', value: 'en' }] }
+      },
+      { type: 'textarea', key: 'content', name: '内容', fillBack: true }
+    ]
+  },
+]);
+
+// 发送消息
+const handleSendMessage = async (value: string, docSchema: TagSchema) => {
+  if (!value.trim()) return;
+  
+  const userMsgId = Date.now().toString();
+  const assistantMsgId = (Date.now() + 1).toString();
+  
+  // 添加用户消息
+  messages.value.push({
+    id: userMsgId,
+    messageId: userMsgId,
+    role: MessageRole.User,
+    content: value,
+    status: MessageStatus.Complete,
+    property: citeContent.value ? { extra: { cite: citeContent.value } } : undefined,
+  });
+  
+  // 清空输入
+  userInput.value = '';
+  citeContent.value = '';
+  
+  // 添加 AI 消息占位
+  messages.value.push({
+    id: assistantMsgId,
+    messageId: assistantMsgId,
+    role: MessageRole.Assistant,
+    content: '',
+    status: MessageStatus.Pending,
+  });
+  
+  messageStatus.value = MessageStatus.Streaming;
+  
+  try {
+    // 调用 AI API 并流式更新
+    const response = await callAIAPI(value);
+    const lastMsg = messages.value[messages.value.length - 1];
+    
+    for await (const chunk of response) {
+      lastMsg.content += chunk;
+      lastMsg.status = MessageStatus.Streaming;
+    }
+    
+    lastMsg.status = MessageStatus.Complete;
+    messageStatus.value = MessageStatus.Complete;
+  } catch (error) {
+    const lastMsg = messages.value[messages.value.length - 1];
+    lastMsg.status = MessageStatus.Error;
+    lastMsg.content = '请求失败，请重试';
+    messageStatus.value = MessageStatus.Error;
+  }
+};
+
+// 停止发送
+const handleStopSending = async () => {
+  messageStatus.value = MessageStatus.Stop;
+  const lastMsg = messages.value[messages.value.length - 1];
+  if (lastMsg) lastMsg.status = MessageStatus.Stop;
+};
+
+// 停止流式
+const handleStopStreaming = () => {
+  handleStopSending();
+};
+
+// AI 消息操作
+const handleAgentAction = async (tool: IToolBtn) => {
+  if (tool.id === 'like') return ['回答准确', '信息全面'];
+  if (tool.id === 'unlike') return ['信息错误', '回答不相关'];
+};
+
+// 用户消息操作
+const handleUserAction = async (tool: IToolBtn) => {
+  console.log('用户操作:', tool.id);
+};
+
+// 快捷指令
+const handleSelectShortcut = (shortcut: Shortcut, text?: string) => {
+  selectedShortcut.value = shortcut;
+  if (text) userInput.value = text;
+};
+
+const handleDeleteShortcut = () => {
+  selectedShortcut.value = null;
+};
+
+const handleCloseShortcut = () => {
+  selectedShortcut.value = null;
+};
+
+const handleSubmitShortcut = (formModel: Record<string, unknown>) => {
+  console.log('提交:', formModel);
+  selectedShortcut.value = null;
+};
+
+// 模拟 AI API
+async function* callAIAPI(prompt: string) {
+  const response = `这是对 "${prompt}" 的回复`;
+  for (const char of response) {
+    await new Promise(r => setTimeout(r, 30));
+    yield char;
+  }
+}
+</script>
+
+<style scoped>
+.chat-page {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  padding: 16px;
+}
+</style>
+```
+
+## 流式消息处理
+
+```typescript
+// 创建流式消息
+const createStreamMessage = () => {
+  const msgId = Date.now().toString();
+  
+  messages.value.push({
+    id: msgId,
+    messageId: msgId,
+    role: MessageRole.Assistant,
+    content: '',
+    status: MessageStatus.Pending,
+  });
+  
+  return messages.value[messages.value.length - 1];
+};
+
+// 更新流式消息
+const updateStreamMessage = (msg: Message, chunk: string) => {
+  msg.content += chunk;
+  msg.status = MessageStatus.Streaming;
+};
+
+// 完成流式消息
+const completeStreamMessage = (msg: Message) => {
+  msg.status = MessageStatus.Complete;
+  messageStatus.value = MessageStatus.Complete;
+};
+
+// 使用示例
+const streamMessage = createStreamMessage();
+messageStatus.value = MessageStatus.Streaming;
+
+for await (const chunk of aiStream) {
+  updateStreamMessage(streamMessage, chunk);
+}
+
+completeStreamMessage(streamMessage);
+```
+
+## 推理过程消息
+
+```typescript
+// 添加推理消息
+messages.value.push({
+  id: 'reasoning-1',
+  messageId: 'reasoning-1',
+  role: MessageRole.Reasoning,
+  content: [
+    '分析用户问题...',
+    '检索相关知识...',
+    '组织回答内容...',
+  ],
+  status: MessageStatus.Complete,
+  duration: 3500,  // 推理耗时 (毫秒)
+});
+```
+
+## 工具调用消息
+
+```typescript
+// AI 消息带工具调用
+messages.value.push({
+  id: 'assistant-1',
+  messageId: 'assistant-1',
+  role: MessageRole.Assistant,
+  content: '我来帮你查询天气...',
+  status: MessageStatus.Complete,
+  toolCalls: [
+    {
+      id: 'call_weather',
+      type: MessageContentType.Function,
+      function: {
+        name: 'get_weather',
+        arguments: '{"city": "北京"}',
+        description: '查询天气',
+      },
+    },
+  ],
+});
+
+// 工具调用结果
+messages.value.push({
+  id: 'tool-1',
+  messageId: 'tool-1',
+  role: MessageRole.Tool,
+  content: '{"temperature": 25, "weather": "晴天"}',
+  status: MessageStatus.Complete,
+  toolCallId: 'call_weather',
+  duration: 1200,
+});
+```
+
+## 引用消息
+
+```typescript
+// 用户消息带引用
+messages.value.push({
+  id: 'user-1',
+  messageId: 'user-1',
+  role: MessageRole.User,
+  content: '解释一下这段话',
+  status: MessageStatus.Complete,
+  property: {
+    extra: {
+      cite: '这里是引用的文本内容...',
+      // 或结构化引用
+      // cite: {
+      //   title: '引用标题',
+      //   type: 'structured',
+      //   data: [
+      //     { key: '来源', value: 'xxx文档' },
+      //   ],
+      // },
+    },
+  },
+});
+```
+
+## 自定义消息类型
+
+```typescript
+// 1. 声明自定义消息类型
+declare global {
+  interface AIBluekingMessageMap {
+    flow: BaseMessage<'flow', FlowContent>;
+    chart: BaseMessage<'chart', ChartData>;
+  }
+}
+
+// 2. 创建自定义消息组件
+// FlowMessage.vue
+<template>
+  <div class="flow-message">
+    <div v-for="step in content.steps" :key="step.id">
+      {{ step.name }}
+    </div>
+  </div>
+</template>
+
+// 3. 在 MessageContainer 中使用
+<MessageContainer :messages="messages">
+  <template #default="{ message }">
+    <FlowMessage v-if="message.role === 'flow'" :content="message.content" />
+    <ChartMessage v-else-if="message.role === 'chart'" :content="message.content" />
+    <MessageRender v-else :message="message" />
+  </template>
+</MessageContainer>
+```
+
+## 消息多选导出
+
+```typescript
+// 启用多选
+const enableSelection = ref(true);
+const selectedMessages = ref<Message[]>([]);
+
+// 导出选中消息
+const exportMessages = () => {
+  const exportData = selectedMessages.value.map(msg => ({
+    role: msg.role,
+    content: msg.content,
+    timestamp: msg.messageId,
+  }));
+  
+  // 下载为 JSON
+  const blob = new Blob([JSON.stringify(exportData, null, 2)], { type: 'application/json' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = 'chat-export.json';
+  a.click();
+};
+```