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

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

@@ -0,0 +1,233 @@
+# ContentRender 内容渲染器
+
+> 能力域：内容渲染 ｜ 导入：`import { ContentRender } from '@blueking/chat-x'` ｜ since 1.0.0
+
+按 MessageContentType 分发 Markdown、文本、引用、键值、图片等内容。 源码位置：src/components/chat-content/content-render/content-render.vue。
+
+**关联**：markdown-content（文本类 Markdown 正文的默认渲染实现）、reference-content（引用文档数组类型的列表渲染）、assistant-message（AI 回复中默认通过本组件渲染正文）
+
+---
+
+# ContentRender 内容渲染器
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/content-render/content-render.vue`
+- **能力域**：内容渲染
+- **能力说明**：按 MessageContentType 分发 Markdown、文本、引用、键值、图片等内容。
+
+> **能力域**：内容渲染
+
+消息内容渲染分发组件，根据 `content` 的 JavaScript 类型自动选择渲染方式：字符串 → `MarkdownContent`（Markdown 渲染），数组 → `ReferenceContent`（引用列表）。
+
+## 渲染管线
+
+```
+ContentRender
+├── typeof content === 'string'  →  MarkdownContent（Markdown 渲染）
+│   └── status === 'error'       →  CommonErrorContent（红色错误图标 + 文本）
+├── Array.isArray(content)       →  ReferenceContent（引用文档列表）
+└── 其他                         →  undefined（不渲染，可通过 slot 自定义）
+```
+
+> **注意**：渲染类型由 `content` 的 JavaScript 类型决定（字符串 vs 数组），`type` prop 仅当传入 `MessageContentType.Text` 时才强制走 `MarkdownContent`，通常不需要显式传递。
+
+## 基础用法（Markdown 文本）
+
+字符串内容自动渲染为 Markdown：
+
+```vue
+<template>
+  <ContentRender
+    :content="content"
+    :status="status"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ContentRender, MessageStatus } from '@blueking/chat-x';
+
+  const content = '这是一段 **Markdown** 内容，支持 `代码`、**加粗**、*斜体* 等语法。';
+  const status = MessageStatus.Complete;
+</script>
+```
+
+**渲染效果**
+
+## Markdown 语法支持
+
+`MarkdownContent` 内置了完整的 Markdown 解析能力，使用 `markdown-it` + 多个插件：
+
+### 常用语法（代码、列表、表格）
+
+### 扩展语法
+
+| 语法                  | 效果           | 插件                      |
+| --------------------- | -------------- | ------------------------- |
+| `++文字++`            | 下划线（新增） | markdown-it-ins           |
+| `==文字==`            | 高亮标注       | markdown-it-mark          |
+| `^上标^`              | 上标           | markdown-it-sup           |
+| `~下标~`              | 下标           | markdown-it-sub           |
+| `[^1]` / `[^1]: 内容` | 脚注           | markdown-it-footnote      |
+| `- [x] 任务`          | 任务列表       | markdown-it-task-checkbox |
+
+### LaTeX 数学公式
+
+行内公式 `$...$` 和块级公式 `$$...$$`，由 `katex` 渲染：
+
+```vue
+<ContentRender content="行内公式：$E = mc^2$" status="complete" />
+```
+
+### Mermaid 图表
+
+代码块语言标识为 `mermaid` 时，由 `MermaidContent` 专门渲染：
+
+## 消息状态
+
+`status` 只传递给 `MarkdownContent`，对 `ReferenceContent` 无效。
+
+| `status`    | 渲染行为                                                          |
+| ----------- | ----------------------------------------------------------------- |
+| `complete`  | 正常渲染完整 Markdown                                             |
+| `streaming` | 自动补全未闭合的 Markdown 语法（代码块、列表等），节流解析（5ms） |
+| `pending`   | 同 `complete`（按当前内容渲染）                                   |
+| `error`     | 渲染为 `CommonErrorContent`（红色错误图标 + `content` 文本）      |
+| `stop`      | 同 `complete`                                                     |
+
+**错误状态示例**
+
+## 引用文档列表
+
+`content` 传入 `ReferenceDocumentContent[]` 数组时，自动渲染为 `ReferenceContent`（引用文档列表）：
+
+```vue
+<template>
+  <ContentRender :content="referenceContent" />
+</template>
+
+<script setup lang="ts">
+  import { ContentRender, type ReferenceDocumentContent } from '@blueking/chat-x';
+
+  const referenceContent: ReferenceDocumentContent[] = [
+    {
+      name: 'Vue 3 官方文档',
+      url: 'https://vuejs.org',
+      originFile: 'vue3-guide.md', // 有 originFile 时显示预览和跳转图标
+    },
+    {
+      name: 'TypeScript 手册',
+      url: 'https://www.typescriptlang.org',
+      originFile: '', // 无 originFile 时不显示操作图标
+    },
+  ];
+</script>
+```
+
+**渲染效果**（悬停条目查看图标，有 `originFile` 的条目显示预览和跳转图标）
+
+### ReferenceContent 图标显示规则
+
+| 条件                           | 显示图标                                     |
+| ------------------------------ | -------------------------------------------- |
+| 始终                           | 文档图标（红色）                             |
+| `url` 和 `originFile` 均不为空 | 预览图标（悬停可见）                         |
+| `url` 和 `originFile` 均不为空 | 跳转图标（悬停可见，打开 `originFile` 链接） |
+
+无 `originFile` 时只显示文档图标（点击文档名跳转 `url`）：
+
+## 自定义渲染（默认插槽）
+
+默认插槽接收 `{ content }` 参数（原始 `content` prop 值），替换整个内容渲染：
+
+```vue
+<template>
+  <ContentRender
+    :content="content"
+    :status="status"
+  >
+    <template #default="{ content }">
+      <div class="custom-content">
+        <h3>自定义渲染</h3>
+        <pre>{{ JSON.stringify(content, null, 2) }}</pre>
+      </div>
+    </template>
+  </ContentRender>
+</template>
+
+<script setup lang="ts">
+  import { ContentRender } from '@blueking/chat-x';
+
+  const content = '自定义内容，由 slot 接管渲染。';
+  const status = 'complete';
+</script>
+```
+
+**渲染效果**
+
+## API
+
+### Props
+
+| 属性名  | 类型                                   | 必填 | 说明                                                                                      |
+| ------- | -------------------------------------- | ---- | ----------------------------------------------------------------------------------------- |
+| content | `string \| ReferenceDocumentContent[]` | ✅   | 内容数据，字符串走 Markdown 渲染，数组走引用文档列表渲染                                  |
+| status  | `MessageStatus`                        | -    | 消息状态，只影响 Markdown 渲染（`error` 时渲染错误样式，`streaming` 时补全语法）          |
+| type    | `ContentType`                          | -    | 内容类型提示，传入 `MessageContentType.Text` 可强制走 MarkdownContent；通常不需要显式传递 |
+
+### Slots
+
+| 插槽名     | 参数                                   | 说明                                                                          |
+| ---------- | -------------------------------------- | ----------------------------------------------------------------------------- |
+| codeHeader | `{ language: string; token: Token[] }` | 代码块头部自定义操作区域，透传给 MarkdownContent → CodeContent 的 header 插槽 |
+| default    | `{ content: ContentMap[T] }`           | 自定义渲染，接收原始 content prop 值，替换全部默认逻辑                        |
+
+## 流式渲染机制
+
+`streaming` 状态下，`MarkdownContent` 有以下优化：
+
+1. **语法自动补全**：`completeMarkdownSyntax` 在解析前补全未闭合的代码块、列表等，避免渲染异常
+2. **节流解析**：`parseMarkdownContent` 节流 5ms（leading + trailing），大幅降低流式输入时的解析开销
+3. **不完整状态保护**：当正在输入 LaTeX 命令（如 `$\fra...`）时保持之前的渲染结果，避免闪烁
+4. **CSS contain 性能隔离**：`.ai-markdown-content` 使用 `contain: layout style`，`.ai-markdown-body` 使用 `contain: content`，减少重排影响范围
+5. **自动滚动**：每个 token 挂载后触发 `toScrollBottom()`（节流 100ms），与 `MessageContainer` 配合实现流式自动滚动
+
+## 类型定义
+
+```typescript
+import { MessageContentType, MessageStatus } from '@blueking/chat-x';
+
+// 引用文档内容
+type ReferenceDocumentContent = {
+  name: string; // 显示名称（为空时该条目被过滤，不渲染）
+  url: string; // 文档访问地址（点击文档名跳转）
+  originFile: string; // 原始文件地址（非空时显示预览和跳转图标）
+};
+
+// 内容类型（ContentType = keyof ContentMap）
+enum MessageContentType {
+  Text = 'text', // 字符串，Markdown 渲染
+  ReferenceDocument = 'reference_document', // ReferenceDocumentContent[]，引用列表
+  Binary = 'binary',
+  Function = 'function',
+  KeyValue = 'key_value',
+  KnowledgeRag = 'knowledge_rag',
+  Other = 'other',
+}
+```
+
+> `MessageStatus` 完整取值见 [常量枚举](../../types/constants)；本组件主要关心 `error`（错误内容）与流式相关状态。
+
+## 使用场景
+
+- **AI 文本回复渲染**：`AssistantMessage` 内部用 `ContentRender` 渲染 AI 回复内容，`status` 配合流式响应
+- **知识库引用展示**：`ActivityMessage` 内部用 `ContentRender` 渲染引用文档列表
+- **代码展示**：Markdown 代码块由 `CodeContent` 自动高亮（Atom One Dark 主题，支持 180+ 语言）
+- **数学公式**：行内 `$...$` 和块级 `$$...$$`，由 KaTeX 渲染
+- **流程图**：Mermaid 代码块自动渲染为 SVG 图表
+- **自定义渲染**：通过 slot 接管渲染，实现表格、图表等自定义内容展示
+
+## 关联组件
+
+- [MarkdownContent](/components/rendering/markdown-content) — 字符串 Markdown 正文
+- [ReferenceContent](/components/rendering/reference-content) — 引用文档数组
+- [AssistantMessage](/components/message/assistant-message) — assistant 消息中默认使用

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

@@ -0,0 +1,191 @@
+# DeleteTool 删除确认按钮
+
+> 能力域：工具与反馈 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+消息删除二次确认工具。 源码位置：src/components/message-tools/delete-tool/delete-tool.vue。
+
+**关联**：tool-btn（删除图标与触发入口）、message-tools（delete 工具 id 时自动采用本组件）
+
+---
+
+# DeleteTool 删除确认按钮
+## 源码事实
+
+- **源码位置**：`src/components/message-tools/delete-tool/delete-tool.vue`
+- **能力域**：工具与反馈
+- **能力说明**：消息删除二次确认工具。
+
+> **能力域**：工具与反馈
+
+删除操作的二次确认组件。点击删除图标后弹出确认弹窗，用户需再次点击"删除"按钮才会触发 `confirm` 事件，防止误删。内部由 `ToolBtn`（触发按钮）+ `Tippy`（确认弹窗）组合实现。
+
+> **提示**：此组件通常**不需要手动使用**，`MessageTools` 在工具列表中检测到 `id === 'delete'` 时会自动使用此组件替换普通 `ToolBtn`。
+
+## 组件结构
+
+```
+Tippy（trigger='click'，interactive，appendTo=body）
+  │
+  ├── ToolBtn（触发按钮，id/name/description/disabled 透传）
+  │
+  └── #content: div.ai-delete-confirm（width: 280px）
+        ├── .ai-delete-confirm__title   "确认删除该回答？"（16px, bold）
+        ├── .ai-delete-confirm__desc    "删除操作无法撤回，请谨慎操作！"
+        └── .ai-delete-confirm__actions（justify-content: flex-end，gap: 8px）
+              ├── Button（theme="danger", size="small"）→ 点击触发 confirm + 关闭弹窗
+              └── Button（size="small"）→ 点击触发 cancel + 关闭弹窗
+
+disabled=true 时：Tippy onShow 返回 false，弹窗不打开
+```
+
+## 基础用法
+
+```vue
+<template>
+  <DeleteTool
+    id="delete"
+    name="删除"
+    description="删除消息"
+    @confirm="handleConfirm"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup lang="ts">
+  import { DeleteTool } from '@blueking/chat-x';
+
+  const handleConfirm = () => {
+    console.log('用户确认删除，执行删除操作');
+  };
+
+  const handleCancel = () => {
+    console.log('用户取消删除');
+  };
+</script>
+```
+
+## 禁用状态
+
+`disabled=true` 时，点击按钮不弹出确认弹窗：
+
+```vue
+<template>
+  <DeleteTool
+    id="delete"
+    name="删除"
+    description="删除消息"
+    :disabled="true"
+    @confirm="handleConfirm"
+  />
+</template>
+```
+
+## 在 MessageTools 中的自动使用
+
+`MessageTools` 在渲染工具列表时，若检测到 `tool.id === 'delete'`，会自动使用 `DeleteTool` 替换普通 `ToolBtn`，无需手动配置：
+
+```vue
+<template>
+  <MessageTools
+    :update-tools="updateTools"
+    :on-action="handleAction"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+  // delete 会自动使用 DeleteTool 渲染，点击弹确认框，确认后 onAction 触发
+  const updateTools: IToolBtn[] = [
+    { id: 'like', name: '点赞', description: '点赞' },
+    { id: 'unlike', name: '不满意', description: '不满意' },
+    { id: 'delete', name: '删除', description: '删除消息' },
+  ];
+
+  const handleAction = async (tool: IToolBtn) => {
+    if (tool.id === 'delete') {
+      // 只有用户在弹窗中点击"删除"确认后，才会走到这里
+      console.log('执行删除:', tool.id);
+    }
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型                                                                       | 必填 | 默认值 | 说明                                                                 |
+| ------------ | -------------------------------------------------------------------------- | ---- | ------ | -------------------------------------------------------------------- |
+| id           | `string`                                                                   | 是   | —      | 按钮标识，传 `"delete"` 时显示删除图标                               |
+| name         | `string`                                                                   | 否   | —      | 按钮名称，`id` 无对应图标时作为文本内容渲染                          |
+| description  | `string`                                                                   | 否   | —      | `ToolBtn` 的 tooltip 文本；`disabled=true` 时不显示                  |
+| disabled     | `boolean`                                                                  | 否   | —      | 禁用态；`true` 时点击不弹出确认弹窗，`ToolBtn` 同步禁用              |
+| tippyOptions | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | 否   | —      | 覆盖确认弹窗（`Tippy`）的默认配置；可覆盖 `placement`、`appendTo` 等 |
+
+### Events
+
+| 事件名  | 参数 | 触发时机                           |
+| ------- | ---- | ---------------------------------- |
+| confirm | —    | 用户在确认弹窗点击"删除"按钮后触发 |
+| cancel  | —    | 用户在确认弹窗点击"取消"按钮后触发 |
+
+## 类型定义
+
+```typescript
+import type { IToolBtn } from '@blueking/chat-x';
+import type { TippyOptions } from 'vue-tippy';
+
+export type DeleteToolProps = IToolBtn & {
+  disabled?: boolean;
+  tippyOptions?: Partial<Omit<TippyOptions, 'getReferenceClientRect' | 'triggerTarget'>>;
+};
+```
+
+## 样式说明
+
+确认弹窗（`.ai-delete-confirm`）样式：
+
+```scss
+.ai-delete-confirm {
+  width: 280px;
+  padding: 16px;
+  font-size: 12px;
+  color: #4d4f56;
+  background: #fff;
+  border: 1px solid #dcdee5;
+  box-shadow: 0 2px 6px 0 #0000001a;
+
+  &__title {
+    margin-bottom: 6px;
+    font-size: 16px;
+    font-weight: 600;
+    line-height: 22px;
+    color: #313238;
+  }
+
+  &__desc {
+    margin-bottom: 16px;
+    line-height: 20px;
+  }
+
+  &__actions {
+    display: flex;
+    gap: 8px;
+    justify-content: flex-end;
+  }
+}
+```
+
+## 注意事项
+
+1. **确认才触发**：`confirm` 事件只在用户点击弹窗内"删除"按钮后触发；直接点击 `ToolBtn` 触发器不会触发任何业务事件
+2. **`disabled` 双重保障**：`disabled=true` 时，`ToolBtn` 的 JS 层拦截 click，且 `Tippy` 的 `onShow` 返回 `false`，弹窗不会弹出
+3. **弹窗挂载至 body**：默认 `appendTo: () => document.body`，避免被父容器 `overflow: hidden` 裁剪
+4. **组件卸载自动关闭**：`onUnmounted` 时调用 `hide()` 关闭弹窗，防止组件销毁后弹窗残留
+5. **`MessageTools` 自动处理**：通常不需要直接使用此组件，`MessageTools` 会在 `id === 'delete'` 时自动替换
+
+## 关联组件
+
+- [ToolBtn](/components/feedback/tool-btn) — 触发按钮
+- [MessageTools](/components/feedback/message-tools) — 工具栏中 delete 替换入口

package/skills/blueking-chat-x/references/components/desc-panel.md

@@ -0,0 +1,162 @@
+# DescPanel 描述面板
+
+> 能力域：内容渲染 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+将文本或 JSON 内容降级为可读描述面板。 源码位置：src/components/tool-call/desc-panel/desc-panel.vue。
+
+**关联**：toolcall-render（工具调用详情中渲染描述与参数）、tool-message（工具返回内容同样由 DescPanel 承载）、highlight-keyword（键值与文本匹配关键词高亮）
+
+---
+
+# DescPanel 描述面板
+## 源码事实
+
+- **源码位置**：`src/components/tool-call/desc-panel/desc-panel.vue`
+- **能力域**：内容渲染
+- **能力说明**：将文本或 JSON 内容降级为可读描述面板。
+
+> **能力域**：内容渲染
+
+工具调用（ToolCall）详情面板的描述区域组件，主要用于 `ToolcallRender` 内部的折叠面板中。
+
+将 `desc` 字符串尝试解析为 JSON，解析成功且结果为对象/数组时以键值对列表渲染，否则作为纯文本展示。
+
+## 组件结构
+
+```
+.ai-toolcall-desc（flex column，padding: 0 16px，max-height: 300px，overflow-y: auto，
+                  font-size: 12px，line-height: 20px，color: #4d4f56，background: #f5f7fa，radius: 2px）
+├── .desc-title（sticky top: 0，flex + gap 4px，padding: 12px 0 4px，加粗，背景同面板）
+│     ├── {{ title }}
+│     └── .desc-copy（v-if desc；CopyIcon 14×14，margin-left: auto，默认 visibility: hidden）
+└── .desc-panel（flex column，gap: 4px，padding-bottom: 12px）
+      ├── [JSON 对象/数组] v-for 逐项渲染 .desc-panel-item
+      │     ├── .desc-label  → HighlightKeyword(key) + 半角冒号
+      │     └── .desc-value → HighlightKeyword(值的文本或 JSON 字符串)，`word-break: break-all`
+      └── [非 JSON / 解析失败] HighlightKeyword(data)，`word-break: break-all`
+```
+
+面板整体限高 **300px**，超出后内部滚动，`.desc-title` 吸顶不动。纵向留白由标题的 `padding-top` 与内容区的 `padding-bottom` 承担（容器自身不设上下 padding），避免标题吸顶时上方留白漏出滚动内容。
+
+> **说明**：键值与纯文本均通过 `HighlightKeyword` 展示，长内容依赖换行与面板宽度展示，**不再**使用 `v-overflow-tips` 悬停气泡。
+
+## 复制原始内容
+
+`desc` 有值时，标题右侧渲染复制按钮（`.desc-copy`），默认 `visibility: hidden`，鼠标移入面板后显示，图标默认 `#979ba5`、hover `#3a84ff`：
+
+```typescript
+// 复制的是原始 desc 字符串，而非解析后的展示内容，便于粘贴后二次使用
+const handleCopy = () => {
+  if (props.desc) {
+    copy(props.desc);
+  }
+};
+```
+
+复制能力来自 [useClipboard](/composables/use-clipboard)，复制结果的成功/失败提示由该 composable 统一处理。`desc` 为空时按钮不渲染。
+
+## desc 解析规则
+
+`data` 是一个 computed，逻辑如下：
+
+```typescript
+const data = computed(() => {
+  try {
+    return JSON.parse(props.desc || ''); // desc 为 undefined/''/null 时 parse('') 会抛出
+  } catch {
+    return props.desc; // 解析失败，原样返回字符串
+  }
+});
+```
+
+模板通过 `typeof data === 'object'` 分支渲染：
+
+| desc 值            | JSON.parse 结果 | typeof 结果 | 渲染方式                 |
+| ------------------ | --------------- | ----------- | ------------------------ |
+| `'{"a":1}'`        | `{ a: 1 }`      | `'object'`  | 键值对列表               |
+| `'[1,2,3]'`        | `[1, 2, 3]`     | `'object'`  | 索引键值对（0:、1:、2:） |
+| `'{}'`             | `{}`            | `'object'`  | 键值对列表（0 行）       |
+| `'"hello"'`        | `"hello"`       | `'string'`  | 纯文本                   |
+| `'42'`             | `42`            | `'number'`  | 纯文本                   |
+| `'普通文本'`       | 解析抛出        | —           | 纯文本（原始字符串）     |
+| `''` / `undefined` | 解析抛出        | —           | 纯文本（空白）           |
+
+> **嵌套对象**：值本身是对象时，文本区域通过 `JSON.stringify(value)` 展示完整 JSON（`HighlightKeyword` + `word-break: break-all`），不再使用悬停 tooltip。
+
+## 基础用法：JSON 参数
+
+```vue
+<template>
+  <DescPanel
+    title="工具调用参数"
+    desc='{"query": "天气查询", "city": "北京", "unit": "celsius"}'
+  />
+</template>
+
+<script setup lang="ts">
+  import { DescPanel } from '@blueking/chat-x';
+</script>
+```
+
+## 纯文本描述
+
+`desc` 不是合法 JSON 时作为纯文本渲染：
+
+```vue
+<template>
+  <DescPanel
+    title="执行说明"
+    desc="正在查询北京的实时天气，请稍候..."
+  />
+</template>
+```
+
+## JSON 数组
+
+JSON 数组同样被视为 `object`，以数组索引（`0:`、`1:`…）作为键渲染：
+
+```vue
+<template>
+  <DescPanel
+    title="文件列表"
+    desc='["report.pdf", "data.csv", "readme.md"]'
+  />
+</template>
+```
+
+## 嵌套 JSON
+
+嵌套对象的值在文本区域直接渲染为 `JSON.stringify(value)` 字符串，便于在面板内换行阅读：
+
+```vue
+<template>
+  <DescPanel
+    title="API 配置"
+    desc='{"endpoint": "/api/search", "headers": {"Authorization": "Bearer xxx", "Content-Type": "application/json"}, "timeout": 5000}'
+  />
+</template>
+```
+
+## 无 desc
+
+`desc` 为可选，不传时面板仅显示标题，内容区域为空，复制按钮也不渲染：
+
+## API
+
+### Props
+
+| 属性名 | 类型     | 必填 | 说明                                                                                |
+| ------ | -------- | ---- | ----------------------------------------------------------------------------------- |
+| title  | `string` | ✓    | 面板标题，始终渲染在顶部（吸顶）                                                    |
+| desc   | `string` | —    | 描述内容；尝试 `JSON.parse`，成功且为 `object` 类型时渲染键值对列表，否则渲染纯文本；有值时才渲染复制按钮 |
+
+## 使用场景
+
+`DescPanel` 主要由 `ToolcallRender` 在展开的详情面板中使用，渲染两块内容：**描述**（`function.description`）与**参数**（`function.arguments`）；工具返回结果则由 `ToolMessage` 再包一层 `DescPanel`（标题「返回内容」）展示。通常不需要手动引入，如需独立使用，直接传入 `title` 和 `desc` 即可。
+
+## 关联组件
+
+- [ToolcallRender](/components/agent/toolcall-render) — 主要使用场景
+- [ToolMessage](/components/message/tool-message) — 工具返回内容面板
+- [HighlightKeyword](/components/helper/highlight-keyword) — 键值高亮
+- [useClipboard](/composables/use-clipboard) — 复制按钮能力来源

package/skills/blueking-chat-x/references/components/detail-section.md

@@ -0,0 +1,91 @@
+# DetailSection 详情分段
+
+> 能力域：Agent 能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+FlowAgent 节点详情中的标题/内容分段容器。 源码位置：src/components/chat-content/flow-agent-content/detail-section.vue。
+
+**关联**：flow-agent-node-detail（节点详情中用于承载基础信息、输入参数、输出参数等区块）、simple-table（常作为分段内容展示结构化参数表格）
+
+---
+
+# DetailSection 详情分段
+
+> **能力域**：Agent 能力
+
+`DetailSection` 是 FlowAgent 节点详情页中的轻量分段容器，用于给一组相关信息提供统一标题样式。组件自身只负责渲染标题和默认插槽，不处理数据格式、折叠、空态或表格逻辑。
+
+通常不需要单独接入，主要由 `FlowAgentNodeDetail` 内部组合使用。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/flow-agent-content/detail-section.vue`
+- **能力说明**：FlowAgent 节点详情中的标题/内容分段容器。
+
+## 核心能力
+
+- **统一标题样式**：标题前带蓝色竖条，标题文本使用详情页统一字号与字重
+- **内容完全透传**：通过默认插槽承载任意内容，如基础信息表单、`SimpleTable` 或自定义说明
+- **无内部状态**：不维护折叠、加载、选择等状态，适合作为详情页布局基础块
+
+## 基础用法
+
+```vue
+<template>
+  <DetailSection title="基础信息">
+    <div class="info-row">节点名称：采集主机指标</div>
+  </DetailSection>
+</template>
+
+<script setup lang="ts">
+  import DetailSection from '@blueking/chat-x/src/components/chat-content/flow-agent-content/detail-section.vue';
+</script>
+```
+
+**渲染效果**
+
+## 搭配 SimpleTable
+
+`DetailSection` 最常见的用法是包裹结构化内容，由外层负责分段标题，内部组件负责数据展示。
+
+```vue
+<template>
+  <DetailSection title="输入参数">
+    <SimpleTable
+      :columns="columns"
+      :data="data"
+    />
+  </DetailSection>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名 | 类型     | 必填 | 默认值 | 说明     |
+| ------ | -------- | ---- | ------ | -------- |
+| title  | `string` | 是   | —      | 分段标题 |
+
+### Emits
+
+- 无。
+
+### Slots
+
+| 插槽名  | 说明             |
+| ------- | ---------------- |
+| default | 分段主体展示内容 |
+
+### Expose
+
+- 无。
+
+## 使用建议
+
+- 用于详情页内部的短分段，不建议作为通用卡片或页面 Section 使用。
+- 内容空态应由插槽内组件自行处理，`DetailSection` 不会主动显示空态。
+
+## 关联组件
+
+- [FlowAgentNodeDetail](./flow-agent-node-detail.md) — 节点详情主体。
+- [SimpleTable](./simple-table.md) — 分段内常用的轻量表格。