@blueking/chat-x 0.0.4 → 0.0.6

package/dist/mcp/generated/docs/message-tools.md

@@ -0,0 +1,376 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+MessageTools 渲染 AI 消息底部工具区：左侧消息工具（复制、引用、重建等），右侧更新工具；点赞/踩会弹出 UserFeedback 收集原因。 工具 id 为 delete 时用 DeleteTool 替代普通 ToolBtn 做二次确认；其余操作通过 onAction 异步解析或直出。
+
+### 关联组件
+- **tool-btn** — 普通工具项由 ToolBtn 渲染
+- **user-feedback** — like/unlike 时弹出反馈表单
+- **delete-tool** — id 为 delete 时替换为带确认的删除按钮
+
+---
+<!-- FULL DOC -->
+
+# MessageTools 消息工具栏
+
+> **层级**：分子组件 · **功能域**：工具与反馈
+
+AI 消息的操作工具栏组件，由**左侧消息工具区**和**右侧更新工具区**两部分组成，中间以分隔线分隔。仅 `like` / `unlike` 按钮会弹出反馈表单（`UserFeedback`），其余按钮直接触发 `onAction`。
+
+## 组件结构
+
+```
+┌─────────────────────────────────────────────────────┐
+│  .message-tools-container                           │
+│  ┌─────────────────────┐  │  ┌───────────────────┐ │
+│  │  messageTools        │  │  │  updateTools      │ │
+│  │  copy cite rebuild…  │  │  │  like unlike del  │ │
+│  └─────────────────────┘  │  └───────────────────┘ │
+│             左侧区域      分隔线   右侧区域          │
+└─────────────────────────────────────────────────────┘
+```
+
+- 分隔线（`.ai-divider`）仅在 `updateTools` 非空时显示
+- `updateTools` 中 `id` 为 `like` / `unlike` 的按钮被 `Tippy` 弹窗包裹，点击后展示 `UserFeedback` 反馈表单
+- `updateTools` 中 `id` 为 `delete` 的按钮使用 `DeleteTool` 组件，点击后展示**确认删除弹窗**（含"删除"/"取消"按钮），确认后触发 `onAction`
+- `updateTools` 中其他按钮直接触发 `onAction`，不弹表单
+- `messageTools` 中 `id` 为 `delete` 的按钮同样使用 `DeleteTool` 组件弹确认框
+
+## 基础用法
+
+```vue
+<template>
+  <MessageTools
+    :on-action="handleAction"
+    @feedback="handleFeedback"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  // like / unlike 必须返回 Promise<string[]>，作为反馈表单的选项
+  const handleAction = async (tool: IToolBtn) => {
+    if (tool.id === 'like' || tool.id === 'unlike') {
+      return ['回答准确', '信息全面', '表达清晰', '解决了问题'];
+    }
+  };
+
+  // 用户在反馈表单点击"提交"后触发
+  const handleFeedback = (tool: IToolBtn, reasonList: string[], otherReason: string) => {
+    console.log('反馈:', tool.id, reasonList, otherReason);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 反馈交互流程
+
+点赞（`like`）和不满意（`unlike`）按钮的完整交互流程：
+
+```
+用户点击 like/unlike
+        │
+        ▼
+调用 onAction(tool)（显示 loading 状态）
+        │
+        ▼
+onAction 返回 string[]（反馈选项列表）
+        │
+        ▼
+弹出 UserFeedback 表单（显示选项）
+        │
+   ┌────┴────┐
+取消         提交
+  │           │
+关闭弹窗     emit('feedback', tool, reasonList, otherReason)
+             │
+             ▼
+          按钮切换为激活图标（activeLike / activeUnLike）
+          ↑ 再次点击同一按钮 → 取消激活并关闭弹窗（不触发 feedback）
+```
+
+**图标切换说明**：
+
+| 状态         | `like` 按钮图标          | `like` Tooltip   | `unlike` 按钮图标          | `unlike` Tooltip |
+| ------------ | ------------------------ | ---------------- | -------------------------- | ---------------- |
+| 未提交       | `like`（空心）           | 原始 description | `unlike`（空心）           | 原始 description |
+| 已提交点赞   | `activeLike`（实心填充） | 取消满意         | `unlike`（空心）           | 原始 description |
+| 已提交不满意 | `like`（空心）           | 原始 description | `activeUnLike`（实心填充） | 取消不满意       |
+
+> 激活态下 tooltip 内容自动切换为"取消满意"/"取消不满意"，用于提示用户再次点击可取消评价。
+
+## 默认工具列表
+
+### messageTools（左侧）
+
+```typescript
+const CONST_MESSAGE_TOOLS = [
+  { id: 'copy', name: '复制', description: '复制' },
+  { id: 'cite', name: '引用', description: '引用' },
+  { id: 'rebuild', name: '重新生成', description: '重新生成' },
+  { id: 'share', name: '分享', description: '分享' },
+];
+```
+
+### updateTools（右侧）
+
+```typescript
+const CONST_UPDATE_TOOLS = [
+  { id: 'like', name: '点赞', description: '点赞' },
+  { id: 'unlike', name: '不满意', description: '不满意' },
+  { id: 'delete', name: '删除', description: '删除' },
+];
+```
+
+> **注意**：`delete` 在 `updateTools` 中**不弹反馈表单**，而是弹出确认删除弹窗（`DeleteTool`）。用户确认后才触发 `onAction`，取消则不触发。
+
+## 内置图标 ID
+
+`ToolBtn` 会根据 `tool.id` 自动匹配图标，支持以下 ID：
+
+| ID             | 图标说明                             |
+| -------------- | ------------------------------------ |
+| `copy`         | 复制                                 |
+| `cite`         | 引用                                 |
+| `rebuild`      | 重新生成                             |
+| `share`        | 分享                                 |
+| `like`         | 点赞（空心）                         |
+| `unlike`       | 不满意（空心）                       |
+| `delete`       | 删除                                 |
+| `edit`         | 编辑                                 |
+| `activeLike`   | 点赞已激活（实心，由组件内部使用）   |
+| `activeUnLike` | 不满意已激活（实心，由组件内部使用） |
+
+> ID 不在列表中时，按钮显示 `tool.name` 文本。
+
+## 仅显示消息工具（不含反馈）
+
+将 `updateTools` 设为空数组可去掉右侧反馈按钮和分隔线：
+
+```vue
+<template>
+  <MessageTools
+    :message-tools="messageTools"
+    :update-tools="[]"
+    :on-action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  const messageTools: IToolBtn[] = [
+    { id: 'copy', name: '复制', description: '复制' },
+    { id: 'cite', name: '引用', description: '引用' },
+  ];
+
+  const handleAction = async (tool: IToolBtn) => {
+    console.log('操作:', tool.id);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 自定义工具列表
+
+`messageTools` 和 `updateTools` 均可完全替换：
+
+```vue
+<template>
+  <MessageTools
+    :message-tools="customMessageTools"
+    :update-tools="customUpdateTools"
+    :on-action="handleAction"
+    @feedback="handleFeedback"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  const customMessageTools: IToolBtn[] = [
+    { id: 'copy', name: '复制', description: '复制消息内容' },
+    { id: 'rebuild', name: '重新生成', description: '重新生成回答' },
+    { id: 'custom-action', name: '自定义', description: '自定义操作' }, // 无图标，显示文本
+  ];
+
+  // like / unlike 仍会触发反馈弹窗；delete 弹确认框，确认后触发 onAction
+  const customUpdateTools: IToolBtn[] = [
+    { id: 'like', name: '有帮助', description: '这个回答对我有帮助' },
+    { id: 'unlike', name: '没帮助', description: '这个回答没有帮助' },
+    { id: 'delete', name: '删除', description: '删除消息' },
+  ];
+
+  const handleAction = async (tool: IToolBtn) => {
+    if (tool.id === 'like' || tool.id === 'unlike') {
+      return ['回答准确', '信息全面', '表达清晰', '解决了问题'];
+    }
+    console.log('操作:', tool.id);
+  };
+
+  const handleFeedback = (tool: IToolBtn, reasonList: string[], otherReason: string) => {
+    console.log('反馈:', tool.id, reasonList, otherReason);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 工具栏状态控制
+
+`messageToolsStatus` 控制工具栏整体状态：
+
+| 值          | 效果                                                                   |
+| ----------- | ---------------------------------------------------------------------- |
+| `undefined` | 默认，按钮正常可点击，hover 有 tooltip                                 |
+| `disabled`  | 按钮显示但不可点击，tooltip 不显示，反馈弹窗无法打开                   |
+| `hidden`    | `MessageContainer` 检测到此值时不渲染 `MessageTools`（组件自身不处理） |
+
+> `hidden` 由 `MessageContainer` 在外部用 `v-if` 判断，`MessageTools` 本身不感知该值。
+
+**禁用状态**
+
+```vue
+<template>
+  <MessageTools
+    :message-tools-status="MessageToolsStatus.Disabled"
+    :on-action="handleAction"
+    @feedback="handleFeedback"
+  />
+</template>
+```
+
+## 自定义 Tippy 配置
+
+反馈弹窗的 `Tippy` 默认配置如下，可通过 `tippyOptions` 覆盖：
+
+```typescript
+// 内部默认值
+{
+  arrow: false,
+  interactive: true,
+  offset: [0, 6],
+  theme: 'ai-chat-box-light light',
+  trigger: 'click',
+  appendTo: () => document.body,
+}
+```
+
+```vue
+<template>
+  <MessageTools
+    :on-action="handleAction"
+    :tippy-options="tippyOptions"
+    @feedback="handleFeedback"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  const tippyOptions = {
+    placement: 'top', // 弹窗方向
+    offset: [0, 12], // 偏移量
+    appendTo: () => document.querySelector('#my-container') || document.body,
+  };
+
+  const handleAction = async (tool: IToolBtn) => {
+    if (tool.id === 'like' || tool.id === 'unlike') {
+      return ['回答准确', '信息全面'];
+    }
+  };
+  const handleFeedback = (tool: IToolBtn, reasonList: string[], otherReason: string) => {
+    console.log('反馈:', tool.id, reasonList);
+  };
+</script>
+```
+
+> **注意**：`content`、`theme`、`getReferenceClientRect`、`triggerTarget` 四个选项由组件内部管理，不可通过 `tippyOptions` 覆盖。
+
+## 在 MessageContainer 中的使用
+
+`MessageContainer` 在每个 Assistant 消息组底部自动渲染 `MessageTools`，无需手动引入：
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :message-status="messageStatus"
+    :message-tools-status="messageToolsStatus"
+    :on-agent-action="handleAgentAction"
+    :on-agent-feedback="handleAgentFeedback"
+    @stop-streaming="handleStopStreaming"
+  />
+</template>
+
+<script setup lang="ts">
+  import { computed, ref } from 'vue';
+  import { MessageContainer, MessageStatus, MessageToolsStatus, type Message, type IToolBtn } from '@blueking/chat-x';
+
+  const messageStatus = ref(MessageStatus.Complete);
+
+  // 流式输出时禁用工具栏，避免误操作
+  const messageToolsStatus = computed(() =>
+    messageStatus.value === MessageStatus.Streaming ? MessageToolsStatus.Disabled : undefined,
+  );
+
+  // copy 操作由 MessageContainer 内部自动处理（无需在此实现）
+  const handleAgentAction = async (tool: IToolBtn, messages: Message[]) => {
+    if (tool.id === 'like' || tool.id === 'unlike') {
+      return ['回答准确', '信息全面', '表达清晰'];
+    }
+  };
+
+  const handleAgentFeedback = (tool: IToolBtn, messages: Message[], reasonList: string[], otherReason: string) => {
+    console.log('反馈提交:', tool.id, reasonList, otherReason);
+  };
+
+  const handleStopStreaming = () => {
+    messageStatus.value = MessageStatus.Stop;
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名             | 类型                                                                                                     | 默认值                | 说明                                                                                                                                 |
+| ------------------ | -------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| messageTools       | `IToolBtn[]`                                                                                             | `CONST_MESSAGE_TOOLS` | 左侧工具列表                                                                                                                         |
+| updateTools        | `IToolBtn[]`                                                                                             | `CONST_UPDATE_TOOLS`  | 右侧工具列表（`like`/`unlike` 弹反馈表单，`delete` 弹确认框，其他直接触发 `onAction`）                                               |
+| messageToolsStatus | `MessageToolsStatus`                                                                                     | —                     | 工具栏状态：`disabled` 禁用按钮和弹窗                                                                                                |
+| onAction           | `(tool: IToolBtn, content?: UserMessage['content'], docSchema?: TagSchema) => Promise<string[] \| void>` | —                     | 工具操作回调；`like`/`unlike` 需返回 `string[]` 作为反馈选项；`delete` 确认后触发；`content`、`docSchema` 为可选参数，供上层扩展使用 |
+| tippyOptions       | `AITippyProps`                                                                                           | —                     | 覆盖反馈弹窗和删除确认弹窗的默认配置；可覆盖 `placement` 等                                                                          |
+
+### Events
+
+| 事件名   | 参数                                                          | 触发时机                                   |
+| -------- | ------------------------------------------------------------- | ------------------------------------------ |
+| feedback | `(tool: IToolBtn, reasonList: string[], otherReason: string)` | 用户在反馈表单点击"提交"后触发（not 取消） |
+
+## 类型定义
+
+```typescript
+import { MessageToolsStatus, type IToolBtn } from '@blueking/chat-x';
+
+interface IToolBtn {
+  id: string; // 工具唯一标识；与 ToolIconsMap 匹配时显示内置图标，否则显示 name 文本
+  name: string; // 工具名称，无对应图标时显示；也用作 tooltip fallback
+  description: string; // tooltip 文本
+}
+
+enum MessageToolsStatus {
+  Disabled = 'disabled', // 禁用：按钮显示但不可点击，弹窗不打开
+  Hidden = 'hidden', // 隐藏：由 MessageContainer 外部 v-if 控制，组件本身不处理
+}
+```
+
+## 关联组件
+
+- [ToolBtn](../atomic/tool-btn.md) — 单项工具按钮
+- [UserFeedback](./user-feedback.md) — 点赞/踩反馈面板
+- [DeleteTool](./delete-tool.md) — 删除二次确认