@blueking/chat-x 0.0.45-beta.6 → 0.0.45-beta.8

package/dist/mcp/generated/docs/scroll-btn.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ScrollBtn 为底部浮动操作提供统一胶囊外壳（圆角、阴影），具体图标与行为由插槽与父级决定。 常由 MessageContainer 用于「返回底部」与「停止生成」等场景。
+停止生成或返回底部等滚动/状态按钮。 源码位置：src/components/ai-buttons/scroll-btn/scroll-btn.vue。
 
 ### 关联组件
 - **message-container** — 消息列表底部固定区挂载滚动与停止按钮
@@ -10,8 +10,13 @@ ScrollBtn 为底部浮动操作提供统一胶囊外壳（圆角、阴影），
 <!-- FULL DOC -->
 
 # ScrollBtn 滚动按钮
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：辅助组件
+- **源码位置**：`src/components/ai-buttons/scroll-btn/scroll-btn.vue`
+- **能力域**：工具与反馈
+- **能力说明**：停止生成或返回底部等滚动/状态按钮。
+
+> **能力域**：工具与反馈
 
 聊天容器底部浮动操作按钮的外壳组件，提供统一的胶囊样式（圆角 26px、高 24px、阴影），内容完全由插槽定制。
 
@@ -152,4 +157,4 @@ div.ai-scroll-btn（flex，gap: 4px，width: fit-content，min-width: 84px，hei
 
 ## 关联组件
 
-- [MessageContainer](../molecular/message-container.md) — 底部固定区集成
+- [MessageContainer](/components/setup/message-container) — 底部固定区集成

package/dist/mcp/generated/docs/selection-footer.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-SelectionFooter 为消息多选（如分享）提供底部操作栏：全选、取消与确认，并反映选中数量与 loading。 由 ChatContainer 在对应模式下自动挂载，业务一般无需单独引用。
+消息多选/分享模式下的底部操作栏。 源码位置：src/components/selection-footer/selection-footer.vue。
 
 ### 关联组件
 - **chat-container** — 多选/分享模式由容器渲染底部栏
@@ -11,8 +11,13 @@ SelectionFooter 为消息多选（如分享）提供底部操作栏：全选、
 <!-- FULL DOC -->
 
 # SelectionFooter 选择操作栏
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：辅助组件
+- **源码位置**：`src/components/selection-footer/selection-footer.vue`
+- **能力域**：输入交互
+- **能力说明**：消息多选/分享模式下的底部操作栏。
+
+> **能力域**：输入交互
 
 消息多选模式下的底部操作栏，提供全选、取消和确认操作。由 `ChatContainer` 在分享模式下自动渲染，通常不需要单独使用。
 
@@ -71,5 +76,5 @@ SelectionFooter 为消息多选（如分享）提供底部操作栏：全选、
 
 ## 关联组件
 
-- [ChatContainer](../molecular/chat-container.md) — 分享模式挂载
-- [MessageContainer](../molecular/message-container.md) — 多选与消息列表
+- [ChatContainer](/components/setup/chat-container) — 分享模式挂载
+- [MessageContainer](/components/setup/message-container) — 多选与消息列表

package/dist/mcp/generated/docs/selection-question.md

@@ -0,0 +1,91 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。 源码位置：src/components/ai-questions/selection-question.vue。
+
+### 关联组件
+- **user-question-card** — 选择类问题交互请使用实际可渲染的问题卡片组件
+- **user-question-option** — 单个选项行由实际问题组件渲染
+- **interrupt-message** — HITL 中断消息由 InterruptMessage 分发到具体问题组件
+
+---
+<!-- FULL DOC -->
+
+# SelectionQuestion 选择问题占位
+
+> **能力域**：辅助能力
+
+`SelectionQuestion` 当前只是保留在源码目录中的空文件，占位路径为 `src/components/ai-questions/selection-question.vue`。它没有模板、脚本、样式、props、emits、slots 或任何选择交互能力。
+
+本文档保留该条目，是为了明确它不是当前可用的问题选择组件，避免业务误接入。
+
+## 源码事实
+
+- **源码位置**：`src/components/ai-questions/selection-question.vue`
+- **文件大小**：`0` 字节
+- **能力说明**：源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。
+
+## 当前状态
+
+| 项目     | 状态 |
+| -------- | ---- |
+| 模板     | 无   |
+| 脚本逻辑 | 无   |
+| 样式     | 无   |
+| Props    | 无   |
+| Emits    | 无   |
+| Slots    | 无   |
+| Expose   | 无   |
+
+## 不可用示例
+
+下面的写法不会产生选择题 UI，也不会发出确认事件：
+
+```vue
+<template>
+  <!-- 不建议使用：当前组件为空文件 -->
+  <SelectionQuestion />
+</template>
+```
+
+## 推荐替代
+
+选择类用户问题请走中断消息链路，由已实现的组件负责展示选项和处理确认：
+
+```vue
+<template>
+  <UserQuestionCard
+    :content="content"
+    @confirm="handleConfirm"
+  />
+</template>
+```
+
+相关文档：
+
+- [UserQuestionCard](../agent/user-question-card.md) — 用户问题中断交互面板。
+- [UserQuestionOption](../agent/user-question-option.md) — 用户问题选项行。
+- [InterruptMessage](../agent/interrupt-message.md) — 中断消息分发入口。
+
+## API
+
+### Props
+
+- 无。
+
+### Emits
+
+- 无。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 使用建议
+
+- 不建议在业务中使用该组件。
+- 如果后续补齐实现，需要同步更新本文档的示例、选择交互事件、API 与关联组件。

package/dist/mcp/generated/docs/shortcut-btn.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ShortcutBtn 渲染单个快捷指令入口，封装图标解析与「按钮 / 下拉菜单项」两种布局，并暴露根元素供父级测量。 由 ShortcutBtns、AiSelection、ChatInput 内部复用；含 components 的快捷指令可无默认图标。 通过 click 事件传出当前 Shortcut，append 槽常用于关闭按钮。
+单个快捷指令按钮，支持默认/append 插槽和 expose focus。 源码位置：src/components/ai-shortcut/shortcut-btn/shortcut-btn.vue。
 
 ### 关联组件
 - **shortcut-btns** — 快捷指令横向列表中作为单项渲染
@@ -12,8 +12,13 @@ ShortcutBtn 渲染单个快捷指令入口，封装图标解析与「按钮 /
 <!-- FULL DOC -->
 
 # ShortcutBtn 快捷指令按钮
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：输入交互
+- **源码位置**：`src/components/ai-shortcut/shortcut-btn/shortcut-btn.vue`
+- **能力域**：输入交互
+- **能力说明**：单个快捷指令按钮，支持默认/append 插槽和 expose focus。
+
+> **能力域**：输入交互
 
 单个快捷指令的渲染单元，封装图标选择逻辑和两种布局模式（按钮 / 菜单项）。
 
@@ -197,6 +202,6 @@ interface Shortcut {
 
 ## 关联组件
 
-- [ShortcutBtns](./shortcut-btns.md) — 快捷指令列表容器
-- [AiSelection](../molecular/ai-selection.md) — 划词浮窗内使用
-- [ChatInput](../molecular/chat-input.md) — 已选快捷指令展示
+- [ShortcutBtns](/components/input/shortcut-btns) — 快捷指令列表容器
+- [AiSelection](/components/input/ai-selection) — 划词浮窗内使用
+- [ChatInput](/components/input/chat-input) — 已选快捷指令展示

package/dist/mcp/generated/docs/shortcut-btns.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ShortcutBtns 横向展示快捷指令按钮组，按容器宽度动态计算可见数量，溢出收入「更多」下拉。 默认由 ChatInput 嵌入附件槽；选中含 components 的指令后需配合 ShortcutRender 展示表单。 通过 selectShortcut 等与外层同步当前快捷指令。
+快捷指令列表入口，内部组合多个 ShortcutBtn。 源码位置：src/components/ai-shortcut/shortcut-btns/shortcut-btns.vue。
 
 ### 关联组件
 - **shortcut-btn** — 列表中每一项由 ShortcutBtn 渲染
@@ -12,8 +12,13 @@ ShortcutBtns 横向展示快捷指令按钮组，按容器宽度动态计算可
 <!-- FULL DOC -->
 
 # ShortcutBtns 快捷指令按钮组
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：输入交互
+- **源码位置**：`src/components/ai-shortcut/shortcut-btns/shortcut-btns.vue`
+- **能力域**：输入交互
+- **能力说明**：快捷指令列表入口，内部组合多个 ShortcutBtn。
+
+> **能力域**：输入交互
 
 快捷指令按钮列表，内置**响应式溢出收起**：根据容器实际宽度动态计算可见数量，超出部分自动收入"更多"下拉菜单。
 
@@ -259,6 +264,6 @@ interface BaseShortcutComponent<T> {
 
 ## 关联组件
 
-- [ShortcutBtn](./shortcut-btn.md) — 列表项原子组件
-- [ChatInput](../molecular/chat-input.md) — 默认嵌入输入框底部
-- [ShortcutRender](../molecular/shortcut-render.md) — 表单类快捷指令的表单渲染
+- [ShortcutBtn](/components/input/shortcut-btn) — 列表项基础组件
+- [ChatInput](/components/input/chat-input) — 默认嵌入输入框底部
+- [ShortcutRender](/components/input/shortcut-render) — 表单类快捷指令的表单渲染

package/dist/mcp/generated/docs/shortcut-render.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ShortcutRender 将 Shortcut.components 声明渲染为 bkui-vue Form，支持多种控件与两列网格、必填校验及提交/取消。 通常由 ChatContainer 等布局挂载在输入区旁，formModel 与快捷指令回填联动。 与 Shortcut、ShortcutBtn 等共享同一套快捷指令数据模型。
+渲染快捷指令 components 表单并回传确认数据。 源码位置：src/components/ai-shortcut/shortcut-render/shortcut-render.vue。
 
 ### 关联组件
 - **shortcut-btn** — 与快捷指令 Shortcut 元数据一致，表单提交前在列表中选中入口
@@ -12,8 +12,13 @@ ShortcutRender 将 Shortcut.components 声明渲染为 bkui-vue Form，支持多
 <!-- FULL DOC -->
 
 # ShortcutRender 快捷指令渲染器
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：输入交互
+- **源码位置**：`src/components/ai-shortcut/shortcut-render/shortcut-render.vue`
+- **能力域**：输入交互
+- **能力说明**：渲染快捷指令 components 表单并回传确认数据。
+
+> **能力域**：输入交互
 
 快捷指令表单渲染组件，将 `Shortcut.components` 配置自动渲染为可交互表单（基于 bkui-vue 的 `Form`），支持 8 种控件类型、两列网格布局、必填校验和内置提交/取消操作。
 
@@ -417,6 +422,6 @@ interface BaseShortcutComponent {
 
 ## 关联组件
 
-- [ShortcutBtn](../atomic/shortcut-btn.md) — 与 Shortcut 数据模型一致的入口按钮
-- [ChatInput](./chat-input.md) — 输入区与快捷指令流程联动
-- [ChatContainer](./chat-container.md) — 顶层布局中挂载快捷表单
+- [ShortcutBtn](/components/input/shortcut-btn) — 与 Shortcut 数据模型一致的入口按钮
+- [ChatInput](/components/input/chat-input) — 输入区与快捷指令流程联动
+- [ChatContainer](/components/setup/chat-container) — 顶层布局中挂载快捷表单

package/dist/mcp/generated/docs/simple-table.md

@@ -0,0 +1,103 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+FlowAgent 节点详情中的轻量表格展示组件。 源码位置：src/components/chat-content/flow-agent-content/simple-table.vue。
+
+### 关联组件
+- **flow-agent-node-detail** — 节点详情中用于展示输入参数、插件输出定义和结构化输出
+- **detail-section** — 通常放在详情分段容器内使用
+
+---
+<!-- FULL DOC -->
+
+# 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/dist/mcp/generated/docs/text-content.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-TextContent 用 Vue 文本插值渲染纯文本气泡，不解析 HTML，适合简单提示与用户/助手纯文案。 需要 Markdown、代码块或公式时应改用 MarkdownContent 等富文本组件。
+渲染纯文本内容。 源码位置：src/components/chat-content/text-content/text-content.vue。
 
 ### 关联组件
 - **markdown-content** — 需要富文本时的替代方案
@@ -11,8 +11,13 @@ TextContent 用 Vue 文本插值渲染纯文本气泡，不解析 HTML，适合
 <!-- FULL DOC -->
 
 # TextContent 文本内容
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：辅助组件
+- **源码位置**：`src/components/chat-content/text-content/text-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染纯文本内容。
+
+> **能力域**：内容渲染
 
 纯文本气泡组件，使用 Vue 文本插值渲染 `content`，天然防 XSS。
 
@@ -70,5 +75,5 @@ div.text-content
 
 ## 关联组件
 
-- [MarkdownContent](./markdown-content.md) — 富文本替代
-- [UserMessage](../molecular/user-message.md) — 用户消息气泡
+- [MarkdownContent](/components/rendering/markdown-content) — 富文本替代
+- [UserMessage](/components/message/user-message) — 用户消息气泡

package/dist/mcp/generated/docs/theme.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-说明通过 SCSS 变量（尺寸、颜色、z-index）与 CSS 类覆盖（chat-input、用户/助手消息、shortcut-btns、ai-markdown-body、tool-btn 等）自定义主题。 含渐变边框 mixin、ai-markdown-fade-in 与弹窗过渡。暗色示例通过根 class 切换。组件随包引入样式，业务侧按需覆写。
+说明通过 SCSS 变量（尺寸、颜色、z-index）、字号主题 CSS 变量（data-ai-size 切换 small/normal）与 CSS 类覆盖自定义主题。 ChatContainer.size 控制根节点 data-ai-size；浮层同步 document.body.dataset.aiSize。含渐变边框 mixin、骨架屏类 ai-skeleton-element 等。
 
 ### 关联组件
 - **chat-container** — 整体布局与侧栏
@@ -26,6 +26,51 @@
 import { ChatInput, MessageContainer } from '@blueking/chat-x';
 ```
 
+## 字号主题
+
+组件库通过根节点 `[data-ai-size]` 切换两档字号主题，内部组件统一引用 CSS 变量（均带兜底值，无 provider 时退回 `small`）。
+
+### 切换方式
+
+| 方式 | 说明 |
+| ---- | ---- |
+| `ChatContainer` 的 `size` prop | 推荐。根节点 `.ai-chat-container` 设置 `data-ai-size`；同时通过 `useGlobalConfig` 注入 `size` 供逻辑层读取 |
+| 手动设置 `data-ai-size` | 在任意祖先元素上设置 `data-ai-size="small"` 或 `data-ai-size="normal"`，后代继承 CSS 变量 |
+| `document.body.dataset.aiSize` | `ChatContainer` 会自动同步，供 Tippy / Teleport 等挂载到 `body` 的浮层继承字号变量；容器卸载时清理 |
+
+```vue
+<template>
+  <ChatContainer v-model="input" :messages="messages" size="normal" />
+</template>
+```
+
+### CSS 变量
+
+定义于 `src/styles/size-theme.scss`，随 `global.scss` 自动引入：
+
+| 变量名 | `small`（默认） | `normal` | 说明 |
+| ------ | --------------- | -------- | ---- |
+| `--ai-font-size` | `12px` | `14px` | 基准字号 |
+| `--ai-line-height` | `20px` | `24px` | 标准行高 |
+| `--ai-line-height-compact` | `20px` | `22px` | 紧凑行高 |
+| `--ai-spacing-comfortable` | `8px` | `12px` | 舒适间距（如消息气泡水平内边距） |
+| `--ai-icon-size` | `16px` | `20px` | 标准图标尺寸 |
+| `--ai-icon-size-sm` | `16px` | `18px` | 小号图标尺寸 |
+
+组件样式中统一使用 `var(--ai-font-size, 12px)` 等形式引用，保证无 `data-ai-size` 时仍退回 small 档位。
+
+```scss
+// 示例：在自定义样式中复用字号主题变量
+.my-custom-panel {
+  font-size: var(--ai-font-size, 12px);
+  line-height: var(--ai-line-height, 20px);
+}
+```
+
+### 骨架屏
+
+全局类 `.ai-skeleton-element` 用于加载占位（如 FlowAgent 节点详情、UserFeedback 原因列表）。可通过 `.skeleton-element-lg` 修饰尺寸。详见各业务组件文档中的加载态说明。
+
 ## SCSS 变量
 
 组件库使用以下 SCSS 变量，可以在项目中覆盖：
@@ -383,6 +428,7 @@ $selection-z-index: $shortcut-menu-z-index + 1;
 
 ## 关联组件
 
-- [ChatContainer](../components/molecular/chat-container.md) — 布局与主题根节点
-- [ChatInput](../components/molecular/chat-input.md) — 输入区变量与类名
-- [MessageContainer](../components/molecular/message-container.md) — 消息列表区域
+- [ChatContainer](../components/setup/chat-container) — 布局与字号主题根节点（`size` prop）
+- [useGlobalConfig](../composables/use-global-config) — 注入 `size` 供后代读取
+- [ChatInput](../components/input/chat-input) — 输入区变量与类名
+- [MessageContainer](../components/setup/message-container) — 消息列表区域

package/dist/mcp/generated/docs/tool-approval-card.md

@@ -0,0 +1,164 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+渲染 AIDevToolApproval 中断的审批信息与取消操作；outcome.success 回显时以 readonly 只读展示。 源码位置：src/components/chat-message/interrupt-message/tool-approval-card.vue。
+
+### 关联组件
+- **interrupt-message** — InterruptMessageRender 按 reason 派发渲染
+
+---
+<!-- FULL DOC -->
+
+# ToolApprovalCard 审批卡片
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/interrupt-message/tool-approval-card.vue`
+- **能力域**：Agent 能力
+- **能力说明**：渲染 AIDevToolApproval 中断的审批信息与取消操作；`readonly` 时用于 outcome.success 只读回显。
+
+> **能力域**：Agent 能力
+
+AI Dev 第三方工具审批（`InterruptReason.AIDevToolApproval`）专用卡片，由 [InterruptMessageRender](/components/agent/interrupt-message) 按 `reason` 动态挂载。
+
+> **通常不需要单独引入**；仅在需要独立预览卡片样式时使用。
+
+## 渲染结构
+
+```
+ToolApprovalCard
+├── 标题栏：左侧色条 + 单据标题 + 复制图标 + 状态徽章（评审中/已通过/已拒绝/已撤销等）
+├── 字段区：单据编号、提交时间
+├── 处理人：当前处理人（overflow-tips 省略）
+└── 操作区：查看单据详情（新窗口打开 url）、取消审批（仅 pending / draft 且非 readonly）
+```
+
+`readonly` 为 `true` 时用于 `outcome.success` 结果回显：隐藏「取消审批」按钮，不接受审批取消交互。通常由 [InterruptMessageRender](/components/agent/interrupt-message) 内部传入，业务侧无需手动设置。
+
+状态徽章样式：
+
+| `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）
+
+`outcome.success` 时 [InterruptMessageRender](/components/agent/interrupt-message) 会将 `AIDevToolApprovalResume.payload.metadata` 还原为 `interrupt` 形态，并以 `readonly` 挂载本组件：
+
+```vue
+<ToolApprovalCard
+  :interrupt="approvedInterrupt"
+  readonly
+/>
+```
+
+**渲染效果**（待审批态下 readonly 不展示「取消审批」）
+
+## API
+
+### Props
+
+| 属性名            | 类型                         | 默认值 | 说明                                         |
+| ----------------- | ---------------------------- | ------ | -------------------------------------------- |
+| interrupt         | `AIDevToolApprovalInterrupt` | —      | **必填**，含 `metadata.ticket`               |
+| onInterruptResume | `OnInterruptResume`          | —      | 取消审批时触发，签名为 `(payload, interrupt)`，payload 为 `{ operation: InterruptResumeOperation.ApprovalCancel, payload: { interrupt_id } }` |
+| readonly          | `boolean`                    | —      | 只读回显态（`outcome.success` 结果回显）：隐藏取消审批按钮，不接受交互 |
+
+### Events / Slots / Expose
+
+无。打开链接、复制剪贴板在组件内部完成；取消审批通过 `onInterruptResume({ operation: InterruptResumeOperation.ApprovalCancel, 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/dist/mcp/generated/docs/tool-btn.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ToolBtn 为消息工具栏提供单个操作入口：内置常用 id 与 SVG 图标映射、Tippy 提示、激活与禁用态。 通常由 MessageTools 遍历配置渲染；DeleteTool 也可将其作为删除触发的视觉入口。
+工具栏图标按钮。 源码位置：src/components/ai-buttons/tool-btn/tool-btn.vue。
 
 ### 关联组件
 - **message-tools** — 父级组装多个工具按钮与交互
@@ -11,8 +11,13 @@ ToolBtn 为消息工具栏提供单个操作入口：内置常用 id 与 SVG 图
 <!-- FULL DOC -->
 
 # ToolBtn 工具按钮
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：工具与反馈
+- **源码位置**：`src/components/ai-buttons/tool-btn/tool-btn.vue`
+- **能力域**：工具与反馈
+- **能力说明**：工具栏图标按钮。
+
+> **能力域**：工具与反馈
 
 消息工具栏中的单个操作按钮，内置 SVG 图标映射、Tippy 悬浮提示、激活态与禁用态，通常由 `MessageTools` 管理，一般不需要手动使用。
 
@@ -281,5 +286,5 @@ type ToolIcons =
 
 ## 关联组件
 
-- [MessageTools](../molecular/message-tools.md) — 工具栏容器
-- [DeleteTool](../molecular/delete-tool.md) — 删除确认内嵌触发
+- [MessageTools](/components/feedback/message-tools) — 工具栏容器
+- [DeleteTool](/components/feedback/delete-tool) — 删除确认内嵌触发