@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/components/simple-table.md

@@ -0,0 +1,101 @@
+# SimpleTable 简易表格
+
+> 能力域：Agent 能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+FlowAgent 节点详情中的轻量表格展示组件。 源码位置：src/components/chat-content/flow-agent-content/simple-table.vue。
+
+**关联**：flow-agent-node-detail（节点详情中用于展示输入参数、插件输出定义和结构化输出）、detail-section（通常放在详情分段容器内使用）
+
+---
+
+# SimpleTable 简易表格
+
+> **能力域**：Agent 能力
+
+`SimpleTable` 是 FlowAgent 节点详情中的轻量只读表格，用于展示参数名、参数值、插件输出定义等结构化信息。组件只根据 `columns` 和 `data` 渲染表格，不提供排序、筛选、分页或编辑能力。
+
+通常不需要单独使用，主要由 `FlowAgentNodeDetail` 内部组合。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/flow-agent-content/simple-table.vue`
+- **能力说明**：FlowAgent 节点详情中的轻量表格展示组件。
+
+## 核心能力
+
+- **列驱动渲染**：通过 `columns` 决定表头、字段读取 key 和单元格换行策略
+- **空值兜底**：单元格值为 `null` 或 `undefined` 时显示 `--`，`0` 会正常显示为 `0`
+- **空数据占位**：`data` 为空数组时渲染一行 `--`，`colspan` 等于列数
+- **长文本换行**：列配置 `breakAll: true` 后，该列单元格添加 `is-break-all` 样式，适合展示 JSON 或长字符串
+
+## 基础用法
+
+```vue
+<template>
+  <SimpleTable
+    :columns="columns"
+    :data="data"
+  />
+</template>
+
+<script setup lang="ts">
+  import SimpleTable from '@blueking/chat-x/src/components/chat-content/flow-agent-content/simple-table.vue';
+
+  const columns = [
+    { key: 'key', label: '参数名' },
+    { breakAll: true, key: 'value', label: '参数值' },
+  ];
+
+  const data = [
+    { key: 'bk_host_id', value: '10001' },
+    { key: 'metadata', value: '{"source":"cmdb","scope":"production"}' },
+  ];
+</script>
+```
+
+**渲染效果**
+
+## 空数据
+
+当 `data.length === 0` 时，组件渲染一行居中的 `--`，用于表示当前分段没有可展示数据。
+
+## API
+
+### Props
+
+| 属性名  | 类型                     | 必填 | 默认值 | 说明                         |
+| ------- | ------------------------ | ---- | ------ | ---------------------------- |
+| columns | `SimpleTableColumn[]`    | 是   | —      | 表格列配置                   |
+| data    | `Record<string, unknown>[]` | 是 | —      | 表格行数据，按列 `key` 取值 |
+
+### Emits
+
+- 无。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 类型定义
+
+```typescript
+export interface SimpleTableColumn {
+  breakAll?: boolean; // 是否对该列单元格启用 word-break: break-all
+  key: string;        // 从 data 行对象中读取的字段名
+  label: string;      // 表头文案
+}
+```
+
+## 使用建议
+
+- 适合详情面板中的短表格，不适合承载复杂数据表能力。
+- 需要展示对象值时，建议在传入前先序列化为字符串；`FlowAgentNodeDetail` 内部会对对象值执行 `JSON.stringify`。
+
+## 关联组件
+
+- [FlowAgentNodeDetail](./flow-agent-node-detail.md) — 节点详情主体。
+- [DetailSection](./detail-section.md) — 表格常放置在详情分段内。

package/skills/blueking-chat-x/references/components/text-content.md

@@ -0,0 +1,80 @@
+# TextContent 文本内容
+
+> 能力域：内容渲染 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+渲染纯文本内容。 源码位置：src/components/chat-content/text-content/text-content.vue。
+
+**关联**：markdown-content（需要富文本时的替代方案）、user-message（用户消息中纯文本内容展示）、mention-text（文档含资源标签时的替代渲染）
+
+---
+
+# TextContent 文本内容
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/text-content/text-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染纯文本内容。
+
+> **能力域**：内容渲染
+
+纯文本气泡组件，使用 Vue 文本插值渲染 `content`，天然防 XSS。
+
+## 组件结构
+
+```
+div.ai-text-content
+  display: flex; width: fit-content
+  padding: 8px 12px; border-radius: 4px
+  background-color: #e1ecff（浅蓝色气泡）
+  word-break: break-all（无空格长文本按字符换行）
+  white-space: pre-wrap（保留 \n 换行与连续空格）
+  │
+  └── {{ content }}（文本插值，HTML 标签不被解析）
+```
+
+> **换行说明**：内容来自输入框，多行文本以 `\n` 承载，因此组件带 `white-space: pre-wrap`——`\n` 会渲染为视觉换行，连续空格与空行也会保留，无需在外层额外加样式。
+
+## 基础用法
+
+```vue
+<template>
+  <TextContent content="这是一条纯文本消息" />
+</template>
+
+<script setup lang="ts">
+  import { TextContent } from '@blueking/chat-x';
+</script>
+```
+
+## 长文本与多行
+
+`word-break: break-all` 确保无空格的长字符串（如 URL、哈希值）也能在容器内正常换行；`white-space: pre-wrap` 让 `\n` 直接生效：
+
+## XSS 安全
+
+`content` 使用 `{{ }}` 文本插值渲染，HTML 标签会被转义，不会执行脚本：
+
+## API
+
+### Props
+
+| 属性名  | 类型     | 必填 | 说明                                           |
+| ------- | -------- | ---- | ---------------------------------------------- |
+| content | `string` | 是   | 要显示的文本内容；空字符串时气泡仍渲染，无内容 |
+
+## 使用场景
+
+`TextContent` 为极简的文本气泡，适用于**不需要 Markdown 渲染**的纯文本展示场景。如需富文本，使用 `MarkdownContent` 组件。
+
+| 场景                              | 推荐组件          |
+| --------------------------------- | ----------------- |
+| 纯文本气泡（用户消息、简单提示）  | `TextContent`     |
+| 含 `@` 资源标签的用户消息         | `MentionText`     |
+| 含 Markdown / 代码块 / 公式的内容 | `MarkdownContent` |
+| 工具调用结果描述                  | `DescPanel`       |
+
+## 关联组件
+
+- [MarkdownContent](/components/rendering/markdown-content) — 富文本替代
+- [MentionText](/components/rendering/mention-text) — 含资源标签文档的渲染
+- [UserMessage](/components/message/user-message) — 用户消息气泡

package/skills/blueking-chat-x/references/components/tool-approval-card.md

@@ -0,0 +1,183 @@
+# ToolApprovalCard 工具审批卡片
+
+> 能力域：Agent 能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+渲染 AIDevToolApproval 中断的审批信息与取消/刷新操作；readonly prop 可用于纯只读展示（outcome.success 回显已改为可交互，不再使用 readonly）。 源码位置：src/components/chat-message/interrupt-message/tool-approval-card.vue。
+
+**关联**：interrupt-message（InterruptMessageRender 按 reason 派发渲染）
+
+---
+
+# ToolApprovalCard 审批卡片
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/interrupt-message/tool-approval-card.vue`
+- **能力域**：Agent 能力
+- **能力说明**：渲染 AIDevToolApproval 中断的审批信息与取消操作；`readonly` prop 用于纯只读展示（outcome.success 回显已改为可交互，不再传入 `readonly`）。
+
+> **能力域**：Agent 能力
+
+AI Dev 第三方工具审批（`InterruptReason.AIDevToolApproval`）专用卡片，由 [InterruptMessageRender](/components/agent/interrupt-message) 按 `reason` 动态挂载。
+
+> **通常不需要单独引入**；仅在需要独立预览卡片样式时使用。
+
+## 渲染结构
+
+```
+ToolApprovalCard
+├── 标题栏：左侧色条 + 单据标题 + 复制图标 + 状态徽章（审批中/已通过/已拒绝/已撤销等）
+├── 字段区：单据编号、提交时间
+├── 处理人：仅 `pending` / `draft` 时展示当前处理人（overflow-tips 省略）
+└── 操作区：查看单据详情（新窗口打开 url）、取消审批（仅 pending / draft 且非 readonly；点击后 loading 防重复提交；分享只读渲染下禁用）
+```
+
+**标题栏刷新图标**（仅 `pending` / `draft` 且非 `readonly` 时展示，复制图标右侧）：取消审批为后端轮询、状态无法实时返回，用户可点击刷新图标主动拉取单据最新状态，`hover` 显示 tooltip「刷新单据状态」。刷新做 **2s 冷却节流**（冷却中图标置灰不可点）；点击「取消审批」也会触发一次 2s 冷却，即取消后需间隔 2s 才能继续刷新。分享只读渲染下刷新图标禁用。
+
+操作区第二个按钮的形态随状态变化（`readonly` 时整体隐藏）：
+
+- **待审批（`pending` / `draft`）**：展示「取消审批」按钮；点击后按钮进入 **loading** 并禁用防重复提交（同步 resume 无法获知结果）。
+- **终态（`approved` / `rejected` / `cancelled` / `revoked` / `expired` / `abandoned`）**：保留「取消审批」按钮但**置灰禁用**，`hover` 显示当前状态无法取消的原因；`cancelled` / `revoked` 态按钮文案为「已取消审批」。
+
+置灰按钮的 tooltip 文案映射：
+
+| `ticket.status`       | 文案                       |
+| --------------------- | -------------------------- |
+| `approved`            | 该单据已通过，无法取消     |
+| `rejected`            | 该单据已被拒绝，无法取消   |
+| `cancelled`、`revoked` | 单据已取消审批             |
+| 其它终态（`expired`、`abandoned`） | 当前状态无法取消审批 |
+
+`readonly` 为 `true` 时用于纯只读展示：隐藏刷新图标与第二个操作按钮（取消 / 置灰取消均不展示），不接受交互。注：`outcome.success` 结果回显自 [InterruptMessageRender](/components/agent/interrupt-message) 起已改为**可交互**挂载（`readonly: false`），不再传入 `readonly`；该 prop 仍保留供纯只读预览场景使用。
+
+分享只读渲染模式（注入的 `RenderMode.Share`）下，操作按钮与刷新图标**保持可见但禁用**（区别于 `readonly` 的直接隐藏），避免在分享回显场景误触发。该渲染模式由 [ChatContainer](/components/setup/chat-container) 等容器通过 `useRenderModeProvider` 注入，组件内部经 `useRenderModeInject` 读取，业务侧无需手动设置。
+
+取消审批与刷新均为同步 `onInterruptResume`，组件无法在回调内获知请求结果：取消点击后按钮立即进入 loading 防止重复取消；刷新做 2s 冷却节流供用户轮询最新状态；待后台刷新使卡片卸载/重建后交互态随实例销毁。
+
+状态徽章样式：
+
+| `ticket.status`                         | 视觉     |
+| --------------------------------------- | -------- |
+| `pending`、`draft`                      | 蓝色审批中 |
+| `approved`                              | 绿色通过 |
+| `rejected`、`cancelled`、`expired`、`abandoned` | 红色终态 |
+| `revoked`                               | 橙色已撤销 |
+
+## 基础用法（待审批）
+
+> `ToolApprovalCard` 为 `InterruptMessageRender` 内部子组件，**未从 `@blueking/chat-x` 包入口导出**。业务侧通过构造 `InterruptMessage` 触发渲染即可；下方为类型与数据结构参考。
+
+```vue
+<template>
+  <!-- 业务侧推荐：由 MessageRender / MessageContainer 自动渲染 -->
+  <InterruptMessageRender
+    :content="interruptMessage.content"
+    role="interrupt"
+    :status="interruptMessage.status"
+    :on-interrupt-resume="handleInterruptResume"
+  />
+</template>
+
+<script setup lang="ts">
+  import {
+    InterruptMessageRender,
+    APPROVAL_STATUS,
+    InterruptReason,
+    MessageRole,
+    MessageStatus,
+    type InterruptMessage,
+    type AIDevToolApprovalInterrupt,
+  } from '@blueking/chat-x';
+
+  const interrupt: AIDevToolApprovalInterrupt = {
+    id: 'interrupt_1',
+    reason: InterruptReason.AIDevToolApproval,
+    toolCallId: 'tool_call_1',
+    metadata: {
+      ticket: {
+        approvers: ['张三', '李四'],
+        sn: 'REV-2026-04-24-001',
+        status: APPROVAL_STATUS.PENDING,
+        submit_time: '2026-04-24 14:30:15',
+        title: '算法方案评审单',
+        url: 'https://example.com/tickets/001',
+      },
+    },
+  };
+
+  const interruptMessage: InterruptMessage = {
+    id: 'msg_1',
+    messageId: 'msg_1',
+    role: MessageRole.Interrupt,
+    status: MessageStatus.Pending,
+    content: {
+      outcome: { type: 'interrupt', interrupts: [interrupt] },
+    },
+  };
+
+  const handleInterruptResume = async (payload, interrupt) => {
+    console.log(payload, interrupt.id);
+  };
+</script>
+```
+
+**渲染效果**（文档站直接挂载 `ToolApprovalCard` 预览卡片 UI）
+
+## 已通过 / 已拒绝 / 已撤销
+
+```vue
+<div>
+  <InterruptMessageRender
+    :content="{ outcome: { type: 'interrupt', interrupts: [approvedInterrupt] } }"
+    role="interrupt"
+  />
+  <InterruptMessageRender
+    :content="{ outcome: { type: 'interrupt', interrupts: [rejectedInterrupt] } }"
+    role="interrupt"
+  />
+  <InterruptMessageRender
+    :content="{ outcome: { type: 'interrupt', interrupts: [revokedInterrupt] } }"
+    role="interrupt"
+  />
+</div>
+```
+
+**渲染效果**
+
+## 只读展示（readonly）
+
+`readonly` 用于纯只读展示审批单：隐藏刷新图标与「取消审批」按钮，不接受任何交互。注：`outcome.success` 结果回显自 [InterruptMessageRender](/components/agent/interrupt-message) 起已改为**可交互**挂载（不再传 `readonly`），此处仅演示 `readonly` prop 本身的效果：
+
+```vue
+<ToolApprovalCard
+  :interrupt="approvedInterrupt"
+  readonly
+/>
+```
+
+**渲染效果**（待审批态下 readonly 不展示刷新图标与「取消审批」按钮）
+
+## API
+
+### Props
+
+| 属性名            | 类型                         | 默认值 | 说明                                         |
+| ----------------- | ---------------------------- | ------ | -------------------------------------------- |
+| interrupt         | `AIDevToolApprovalInterrupt` | —      | **必填**，含 `metadata.ticket`               |
+| onInterruptResume | `OnInterruptResume`          | —      | 取消审批 / 刷新时触发，签名为 `(payload, interrupt)`，payload 为 `{ operation, payload: { interrupt_id } }`，`operation` 取 `InterruptResumeOperation.ApprovalCancel`（取消）或 `InterruptResumeOperation.ApprovalRefresh`（刷新），两者 payload 结构一致 |
+| readonly          | `boolean`                    | —      | 纯只读展示：隐藏取消 / 刷新按钮，不接受交互（`outcome.success` 回显已改为可交互，框架内部不再传入） |
+
+### Events / Slots / Expose
+
+无。打开链接、复制剪贴板在组件内部完成；取消审批通过 `onInterruptResume({ operation: InterruptResumeOperation.ApprovalCancel, payload: { interrupt_id: interrupt.id } }, interrupt)`、刷新单据通过 `onInterruptResume({ operation: InterruptResumeOperation.ApprovalRefresh, payload: { interrupt_id: interrupt.id } }, interrupt)` 通知业务侧处理。
+
+## 依赖
+
+- `bkui-vue`：`Button`、`Loading`
+- `useClipboard` — 复制单据
+- `v-overflow-tips` — 处理人超长省略
+
+## 关联组件
+
+- [InterruptMessage 中断消息](/components/agent/interrupt-message)
+- [中断类型 Interrupt](../../types/interrupt.md)
+- [常量枚举 Constants](../../types/constants.md) — `APPROVAL_STATUS`、`APPROVAL_STATUS_MAP`

package/skills/blueking-chat-x/references/components/tool-btn.md

@@ -0,0 +1,317 @@
+# ToolBtn 工具按钮
+
+> 能力域：工具与反馈 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+工具栏图标按钮。 源码位置：src/components/ai-buttons/tool-btn/tool-btn.vue。
+
+**关联**：message-tools（父级组装多个工具按钮与交互）、delete-tool（删除确认场景内嵌为触发控件）
+
+---
+
+# ToolBtn 工具按钮
+## 源码事实
+
+- **源码位置**：`src/components/ai-buttons/tool-btn/tool-btn.vue`
+- **能力域**：工具与反馈
+- **能力说明**：工具栏图标按钮。
+
+> **能力域**：工具与反馈
+
+消息工具栏中的单个操作按钮，内置 SVG 图标映射、Tippy 悬浮提示、激活态与禁用态，通常由 `MessageTools` 管理，一般不需要手动使用。
+
+## 组件结构
+
+```
+div.ai-tool-btn（v-tippy，flex，min-width: 20px，height: 20px，border-radius: 4px）
+  color: #a8aab2; background: transparent
+  active=true  → .is-active（color: var(--ai-tool-btn-active-color)）
+  disabled=true → .is-disabled（color: #979ba5; cursor: not-allowed）
+  :not(.is-disabled):hover → color: #4d4f56; background: #eaebf0
+  │
+  └── <slot>（默认内容，可完全自定义；优先级最高）
+        ├── [icon] → <component :is="icon" />（自定义图标组件/VNode，优先级高于内置图标）
+        ├── [id && id in ToolIconsMap] → <component :is="ToolIconsMap[id]" />（内置 SVG 图标）
+        └── [其他] → <div>{{ name }}</div>（文本回退，XSS 安全）
+
+Tippy：content=description, theme='ai-chat-box', disabled=true 时 onShow 返回 false 不显示
+click 事件：disabled=true 时被 JS 拦截，不触发 emit
+
+激活色（CSS 变量 --ai-tool-btn-active-color）：
+  id === 'like' 或 'activeLike' → #3a84ff（蓝色）
+  其他 id（如 'unlike'、'delete'） → #E71818（红色）
+```
+
+## 预置图标（ToolIconsMap）
+
+| id             | 说明           | 备注                     |
+| -------------- | -------------- | ------------------------ |
+| `copy`         | 复制           |                          |
+| `cite`         | 引用           |                          |
+| `rebuild`      | 重新生成       |                          |
+| `share`        | 分享           |                          |
+| `like`         | 点赞（空心）   | 配合 `activeLike` 使用   |
+| `unlike`       | 不满意（空心） | 配合 `activeUnLike` 使用 |
+| `delete`       | 删除           |                          |
+| `edit`         | 编辑           |                          |
+| `activeLike`   | 点赞（实心）   | 激活态填充图标           |
+| `activeUnLike` | 不满意（实心） | 激活态填充图标           |
+
+> 未传入 `id`、或 `id` 不在上表时，组件渲染 `<div>{{ name }}</div>` 作为文本回退。也可通过默认插槽完全自定义按钮内容（如全屏图标），此时可不传 `id`。
+
+## 基础用法
+
+```vue
+<template>
+  <div style="display: flex; gap: 6px;">
+    <ToolBtn
+      id="copy"
+      name="复制"
+      description="复制消息内容"
+      @click="handleClick"
+    />
+    <ToolBtn
+      id="cite"
+      name="引用"
+      description="引用此消息"
+      @click="handleClick"
+    />
+    <ToolBtn
+      id="rebuild"
+      name="重新生成"
+      description="重新生成回答"
+      @click="handleClick"
+    />
+    <ToolBtn
+      id="share"
+      name="分享"
+      description="分享消息"
+      @click="handleClick"
+    />
+    <ToolBtn
+      id="like"
+      name="点赞"
+      description="对此回答满意"
+      @click="handleClick"
+    />
+    <ToolBtn
+      id="unlike"
+      name="不满意"
+      description="对此回答不满意"
+      @click="handleClick"
+    />
+    <ToolBtn
+      id="edit"
+      name="编辑"
+      description="编辑消息"
+      @click="handleClick"
+    />
+    <ToolBtn
+      id="delete"
+      name="删除"
+      description="删除消息"
+      @click="handleClick"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ToolBtn } from '@blueking/chat-x';
+  import type { IToolBtn } from '@blueking/chat-x';
+
+  const handleClick = (data: IToolBtn & { active?: boolean; disabled?: boolean }, event: MouseEvent) => {
+    console.log('点击了:', data.id, data.name);
+  };
+</script>
+```
+
+## 激活态与图标切换（点赞/踩）
+
+`active` 只控制 `.is-active` 背景高亮，不自动切换图标。若需要填充图标，需在 `:id` 绑定中主动切换 `activeLike` / `activeUnLike`：
+
+```vue
+<template>
+  <div style="display: flex; gap: 6px;">
+    <!-- 切换 id 实现图标填充 -->
+    <ToolBtn
+      :id="activeId === 'like' ? 'activeLike' : 'like'"
+      name="点赞"
+      description="点赞"
+      :active="activeId === 'like'"
+      @click="toggleActive"
+    />
+    <ToolBtn
+      :id="activeId === 'unlike' ? 'activeUnLike' : 'unlike'"
+      name="不满意"
+      description="不满意"
+      :active="activeId === 'unlike'"
+      @click="toggleActive"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ToolBtn } from '@blueking/chat-x';
+  import type { IToolBtn } from '@blueking/chat-x';
+
+  const activeId = ref<string | null>(null);
+
+  const toggleActive = (data: IToolBtn) => {
+    // 规范化 id（activeLike → like）后再比较
+    const baseId = data.id.replace(/^active/, '').replace(/^./, c => c.toLowerCase());
+    activeId.value = activeId.value === baseId ? null : baseId;
+  };
+</script>
+```
+
+## 禁用状态
+
+`disabled=true` 时：JS 拦截 click 不触发事件 + Tippy 的 `onShow` 返回 `false` 不显示 tooltip：
+
+```vue
+<template>
+  <div style="display: flex; gap: 6px; align-items: center;">
+    <ToolBtn
+      id="copy"
+      name="复制"
+      description="复制"
+      :disabled="isDisabled"
+      @click="handleClick"
+    />
+    <ToolBtn
+      id="edit"
+      name="编辑"
+      description="编辑"
+      :disabled="isDisabled"
+      @click="handleClick"
+    />
+    <button @click="isDisabled = !isDisabled">{{ isDisabled ? '启用' : '禁用' }}</button>
+  </div>
+</template>
+```
+
+## 未知 ID 的文本回退
+
+`id` 不在 `ToolIconsMap` 时渲染 `name` 文本，适用于自定义扩展场景：
+
+## 自定义图标（icon 属性）
+
+当内置 `ToolIconsMap` 未覆盖所需图标时，可通过 `icon` 传入自定义图标组件或 VNode（如业务新增的「保存」按钮）。`icon` 的渲染优先级高于内置图标，因此即便 `id` 命中内置图标，也会以 `icon` 为准。
+
+```vue
+<template>
+  <ToolBtn
+    id="save"
+    name="保存"
+    description="保存该回答"
+    :icon="DownloadIcon"
+    @click="handleClick"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ToolBtn, DownloadIcon } from '@blueking/chat-x';
+</script>
+```
+
+> 优先级从高到低：默认插槽 `>` `icon` 属性 `>` 内置 `ToolIconsMap[id]` `>` `name` 文本回退。
+
+## 自定义插槽内容
+
+通过默认插槽可完全替换内置图标/文本，适用于预置 `ToolIconsMap` 未覆盖的图标场景（如侧栏全屏按钮）：
+
+```vue
+<template>
+  <ToolBtn
+    description="全屏"
+    :tippy-options="{ content: '全屏' }"
+    @click="handleFullScreen"
+  >
+    <FullScreenIcon />
+  </ToolBtn>
+</template>
+
+<script setup lang="ts">
+  import { ToolBtn, FullScreenIcon } from '@blueking/chat-x';
+
+  const handleFullScreen = () => {
+    // 进入全屏逻辑
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型                                                                       | 必填 | 默认值 | 说明                                                                                                               |
+| ------------ | -------------------------------------------------------------------------- | ---- | ------ | ------------------------------------------------------------------------------------------------------------------ |
+| id           | `(string & {}) \| ToolIcons`                                               | 否   | —      | 按钮标识；命中 `ToolIconsMap` 时渲染对应 SVG 图标，否则渲染 `name` 文本；支持业务自定义任意字符串（如 `save`）      |
+| name         | `string`                                                                   | 否   | —      | 按钮名称；`id` 无对应图标时作为文本内容渲染                                                                        |
+| description  | `string`                                                                   | 否   | —      | Tippy tooltip 内容；`disabled=true` 时不显示 tooltip                                                               |
+| icon         | `Component \| VNode`                                                        | 否   | —      | 自定义图标组件或 VNode；优先级高于内置 `ToolIconsMap[id]`，低于默认插槽                                             |
+| active       | `boolean`                                                                  | 否   | —      | 激活态；`true` 时追加 `.is-active`（字色由 `id` 决定：`like`/`activeLike` 为蓝色 `#3a84ff`，其他为红色 `#E71818`） |
+| disabled     | `boolean`                                                                  | 否   | —      | 禁用态；`true` 时追加 `.is-disabled`，阻止 click 事件，隐藏 tooltip                                                |
+| tippyOptions | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | 否   | —      | 自定义 Tippy 配置，与内部默认配置合并；可用于控制 `content`、`appendTo`、`placement` 等                            |
+
+### Events
+
+| 事件名 | 参数                                                                             | 说明                                                                                        |
+| ------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| click  | `(data: IToolBtn & { active?: boolean; disabled?: boolean }, event: MouseEvent)` | 点击时触发；`data` 为组件当前全量 props（含 `active`/`disabled`）；`disabled=true` 时不触发 |
+
+### Slots
+
+| 插槽名  | 说明                                                                                       |
+| ------- | ------------------------------------------------------------------------------------------ |
+| default | 按钮内容；传入时替换默认的图标/文本渲染逻辑，常用于自定义 SVG 图标（如全屏、退出全屏按钮） |
+
+## 类型定义
+
+```typescript
+import type { Component, VNode } from 'vue';
+
+// 来自 @blueking/chat-x 导出
+interface IToolBtn {
+  id?: (string & {}) | ToolIcons; // 内置 ID 保留自动补全，同时允许业务自定义任意字符串（如 'save'）
+  name?: string;
+  description?: string;
+  icon?: Component | VNode; // 自定义图标，优先级高于内置 ToolIconsMap
+  hidden?: boolean; // 按 id 合并时隐藏该按钮（如 { id: 'share', hidden: true } 移除内置项）
+  triggerSelection?: boolean; // 标记点击后进入多选态（复用 share 选择流程），确认走 confirmShare
+}
+
+// ToolBtn 完整 Props
+type ToolBtnProps = IToolBtn & {
+  active?: boolean;
+  disabled?: boolean;
+  tippyOptions?: Partial<Omit<TippyOptions, 'getReferenceClientRect' | 'triggerTarget'>>;
+};
+
+// 预置 ID 枚举
+type ToolIcons =
+  | 'copy'
+  | 'cite'
+  | 'rebuild'
+  | 'share'
+  | 'like'
+  | 'unlike'
+  | 'delete'
+  | 'edit'
+  | 'activeLike'
+  | 'activeUnLike';
+```
+
+## 注意事项
+
+1. **`click` 事件的 `data` 参数**是组件的完整 props 对象（含 `active`、`disabled`），并非单纯的 `IToolBtn`
+2. **`activeLike` / `activeUnLike`**：是单独的填充版图标 ID，并非 `active=true` 时自动切换，需要手动在 `:id` 绑定中控制
+3. **根元素是 `<div>` 而非 `<button>`**：没有原生按钮语义，键盘无障碍访问需外部额外处理
+4. **`description` 可选**：不传时 tooltip 内容为 `undefined`，Tippy 不显示提示
+5. **`disabled` 的 CSS**：`pointer-events: hover` 为无效 CSS 值（应为 `none`），鼠标事件实际由 JS 层拦截，CSS 层仍可触发 hover 样式
+6. **`tippyOptions` 优先级**：`tippyOptions` 中的配置会覆盖内部默认值（包括 `content`、`theme`），但 `onShow` 始终保留内部逻辑（禁用时不显示）。`getReferenceClientRect`、`triggerTarget` 两个字段被 Omit 排除，不可通过此 prop 覆盖；`content` 已可通过 `tippyOptions.content` 覆盖
+
+## 关联组件
+
+- [MessageTools](/components/feedback/message-tools) — 工具栏容器
+- [DeleteTool](/components/feedback/delete-tool) — 删除确认内嵌触发