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

package/skills/blueking-chat-x/references/components/questions-container.md

@@ -0,0 +1,85 @@
+# QuestionsContainer 问题容器占位
+
+> 能力域：辅助能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。 源码位置：src/components/ai-questions/questions-container.vue。
+
+**关联**：user-question-card（用户问题中断交互请使用实际可渲染的问题卡片组件）、user-question-option（用户问题选项行由实际中断组件承载）、interrupt-message（HITL 中断消息由 InterruptMessage 分发到具体问题组件）
+
+---
+
+# QuestionsContainer 问题容器占位
+
+> **能力域**：辅助能力
+
+`QuestionsContainer` 当前只是保留在源码目录中的空文件，占位路径为 `src/components/ai-questions/questions-container.vue`。它没有模板、脚本、样式、props、emits、slots 或任何渲染行为。
+
+本文档保留该条目，是为了在组件总览和 MCP 文档检索中明确说明：它不是当前可用能力。
+
+## 源码事实
+
+- **源码位置**：`src/components/ai-questions/questions-container.vue`
+- **文件大小**：`0` 字节
+- **能力说明**：源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。
+
+## 当前状态
+
+| 项目     | 状态 |
+| -------- | ---- |
+| 模板     | 无   |
+| 脚本逻辑 | 无   |
+| 样式     | 无   |
+| Props    | 无   |
+| Emits    | 无   |
+| Slots    | 无   |
+| Expose   | 无   |
+
+## 不可用示例
+
+下面的写法不会产生任何可见 UI，也不会承载问题列表逻辑：
+
+```vue
+<template>
+  <!-- 不建议使用：当前组件为空文件 -->
+  <QuestionsContainer />
+</template>
+```
+
+## 推荐替代
+
+如果要展示用户问题中断或选项交互，请使用已经实现的中断消息组件链路：
+
+```vue
+<template>
+  <InterruptMessage :message="message" />
+</template>
+```
+
+或在具体场景中使用：
+
+- [InterruptMessage](../agent/interrupt-message.md) — 中断消息分发入口。
+- [UserQuestionCard](../agent/user-question-card.md) — 用户问题中断交互面板。
+- [UserQuestionOption](../agent/user-question-option.md) — 用户问题选项行。
+
+## API
+
+### Props
+
+- 无。
+
+### Emits
+
+- 无。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 使用建议
+
+- 不建议在业务中使用该组件。
+- 如果后续补齐实现，需要同步更新本文档的能力说明、示例、API 与关联组件。

package/skills/blueking-chat-x/references/components/reasoning-message.md

@@ -0,0 +1,232 @@
+# ReasoningMessage 推理消息
+
+> 能力域：消息系统 ｜ 未从包入口导出：内部组件（入口的同名导出是 TS 类型，不是组件） ｜ since 0.0.20
+
+渲染推理过程，覆盖加载、错误与 Markdown 内容展示。 源码位置：src/components/chat-message/reasoning-message/reasoning-message.vue。
+
+**关联**：message-render（由 MessageRender 在 role 为 reasoning 时创建）、assistant-message（推理结束后通常紧跟 Assistant 的正式回复）、markdown-content（内容区通过 Markdown 渲染推理文本）
+
+---
+
+# ReasoningMessage 推理消息
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/reasoning-message/reasoning-message.vue`
+- **能力域**：消息系统
+- **能力说明**：渲染推理过程，覆盖加载、错误与 Markdown 内容展示。
+
+> **导出说明**：`ReasoningMessage` **未**从包入口导出（入口同名是 TS interface）。消费方经 `MessageRender` / `MessageContainer` 使用。下文 `ReasoningMessageComp` 为文档站内部示例。
+
+AI 思维链（Chain-of-Thought）推理过程展示组件。由**可点击标题栏**和**内容区域**组成，内容区支持 Markdown 渲染。`duration` 传入后自动折叠一次，用户可随时点击标题展开/收起。
+
+## 组件结构
+
+```
+┌─────────────────────────────────────────────────┐
+│  .ai-reasoning-message-title（可点击，toggle 折叠）│
+│  ┌──────┐  标题文案（思考中/已思考完成/思考失败）  ▶ │
+│  │ 加载图标│                               折叠图标 │
+│  └──────┘                                        │
+└─────────────────────────────────────────────────┘
+▼ 展开时显示（v-show）
+┌─────────────────────────────────────────────────┐
+│  .ai-reasoning-message-content                  │
+│  <MarkdownContent> × content.length              │
+│  （Error 时改为 CommonErrorContent）              │
+│  .ai-markdown-body { color: #979ba5 }（灰色文字）   │
+└─────────────────────────────────────────────────┘
+```
+
+## 基础用法
+
+```vue
+<template>
+  <MessageRender :message="message" />
+</template>
+
+<script setup lang="ts">
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: '1',
+    messageId: '1',
+    role: MessageRole.Reasoning,
+    status: MessageStatus.Complete,
+    content: ['让我分析一下这个问题...', '首先需要考虑以下几个方面...'],
+  };
+</script>
+```
+
+**渲染效果**
+
+## 状态与视觉效果
+
+| `status`                       | 标题文案           | 加载图标      | 标题 CSS 类   |
+| ------------------------------ | ------------------ | ------------- | ------------- |
+| `pending` / `streaming` / 其他 | 思考中             | `AiLoading` ✓ | `is-thinking` |
+| `complete` / `success`         | 已思考完成（耗时） | 无            | `is-complete` |
+| `error`                        | 思考失败           | 无            | `is-error`    |
+
+> **说明**：`streaming` 通过 `switch` 的 `default` 分支显示"思考中"，与 `pending` 效果相同。
+
+### 思考中（pending / streaming）
+
+### 完成状态（带耗时）
+
+`duration` 传入后：
+
+1. 标题显示"已思考完成 (耗时：x.xs)"
+2. **自动折叠一次**（watch 触发后 `stop()`，后续不再自动折叠）
+3. 用户点击标题可重新展开
+
+### 错误状态（error）
+
+`status: 'error'` 时，标题显示"思考失败"，内容区改为 `CommonErrorContent` 渲染（将 `content` 数组 join `\n` 后传入）：
+
+## 折叠控制
+
+### 自动折叠机制
+
+组件内部 watch `duration` prop（`{ immediate: true }`）：
+
+- 当 `duration` **首次变为真值**时，将 `collapsed` 设为 `true` 并停止 watcher
+- **一次性行为**：watcher 停止后，后续 `duration` 变化不再触发自动折叠
+
+```typescript
+// 组件内部逻辑（简化）
+const { stop } = watch(
+  () => props.duration,
+  async duration => {
+    if (duration) {
+      collapsed.value = true;
+      await nextTick();
+      stop?.(); // 停止 watcher，后续 duration 变化不再自动折叠
+    }
+  },
+  { immediate: true },
+);
+```
+
+### 手动控制折叠状态
+
+通过 `v-model:collapsed` 从外部读取或设置折叠状态：
+
+```vue
+<!-- 文档站内部示例：组件本体支持 v-model:collapsed；消费方一般经 MessageRender 渲染 -->
+<template>
+  <button @click="collapsed = !collapsed">
+    {{ collapsed ? '展开推理' : '收起推理' }}
+  </button>
+  <ReasoningMessageComp
+    v-model:collapsed="collapsed"
+    :content="content"
+    :status="status"
+    :duration="duration"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MessageStatus } from '@blueking/chat-x';
+
+  const collapsed = ref(false);
+  const status = MessageStatus.Complete;
+  const duration = 2800;
+  const content = ['经过分析，结论如下...', '具体原因是...'];
+</script>
+```
+
+## 在 MessageContainer 中使用
+
+`MessageContainer` 会自动将 `role: 'reasoning'` 的消息渲染为 `ReasoningMessage`，无需手动引入：
+
+```vue
+<script setup lang="ts">
+  import { MessageRole, MessageStatus, type Message } from '@blueking/chat-x';
+
+  const messages = [
+    {
+      id: '1',
+      messageId: '1',
+      role: MessageRole.User,
+      content: '如何实现 TypeScript 中的深拷贝？',
+      status: MessageStatus.Complete,
+    },
+    {
+      id: '2',
+      messageId: '2',
+      role: MessageRole.Reasoning,
+      content: [
+        '用户问的是 TypeScript 深拷贝，需要考虑几种常见方案...',
+        'JSON.parse/stringify 有局限性（函数、循环引用等）...',
+        'structuredClone 是更现代的选择，但需要注意兼容性...',
+      ],
+      status: MessageStatus.Complete,
+      duration: 2800, // 毫秒，传入后自动折叠
+    },
+    {
+      id: '3',
+      messageId: '3',
+      role: MessageRole.Assistant,
+      content: 'TypeScript 中实现深拷贝有以下几种方式...',
+      status: MessageStatus.Complete,
+    },
+  ];
+</script>
+```
+
+## API
+
+### Props
+
+组件 Props 继承自 `Partial<ReasoningMessage>`：
+
+| 属性名    | 类型                 | 说明                                                                           |
+| --------- | -------------------- | ------------------------------------------------------------------------------ |
+| content   | `string \| string[]` | 推理内容；字符串数组时每项独立渲染为 `MarkdownContent`；字符串时自动包装为数组 |
+| status    | `MessageStatus`      | 消息状态，决定标题文案、加载图标和 CSS 类                                      |
+| duration  | `number`             | 推理耗时（毫秒）；传入后标题追加耗时信息，并**触发一次自动折叠**               |
+| id        | `number \| string`   | 消息 ID（接收但不使用）                                                        |
+| messageId | `number \| string`   | 消息唯一标识（接收但不使用）                                                   |
+
+### v-model
+
+| 属性名    | 类型      | 默认值  | 说明                                                       |
+| --------- | --------- | ------- | ---------------------------------------------------------- |
+| collapsed | `boolean` | `false` | 内容折叠状态；`duration` 首次传入时组件内部自动设为 `true` |
+
+### 状态说明
+
+| `status`           | 标题文案                             | 加载图标 | 标题背景        |
+| ------------------ | ------------------------------------ | -------- | --------------- |
+| `pending`          | 思考中                               | ✓        | `#f0f1f5`       |
+| `streaming` / 其他 | 思考中（default 分支）               | ✓        | `#f0f1f5`       |
+| `complete`         | 已思考完成（含 duration 则追加耗时） | ✗        | `#f0f1f5`       |
+| `success`          | 已思考完成（同 complete）            | ✗        | `#f0f1f5`       |
+| `error`            | 思考失败                             | ✗        | `#fff0f0`（红） |
+
+## 类型定义
+
+```typescript
+import { MessageRole, MessageStatus, type ReasoningMessage } from '@blueking/chat-x';
+
+// ReasoningMessage 继承自 BaseMessage<MessageRole.Reasoning, string[]>
+interface ReasoningMessage {
+  id: string | number;
+  messageId: string | number;
+  role: MessageRole.Reasoning; // 'reasoning'
+  status: MessageStatus;
+  content: string[]; // TS 类型为 string[]，组件内部实际兼容 string
+  duration?: number; // 推理耗时（毫秒）
+  name?: string;
+}
+```
+
+> `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。本组件完成态识别 `complete` / `success`（与标题文案表一致）。
+
+## 关联组件
+
+- [MessageRender](/components/message/message-render) — reasoning 角色由其实例化
+- [AssistantMessage](/components/message/assistant-message) — 推理后常接正式回答
+- [MarkdownContent](/components/rendering/markdown-content) — 推理正文 Markdown 渲染

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

@@ -0,0 +1,135 @@
+# ReferenceContent 引用来源
+
+> 能力域：内容渲染 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+渲染引用文档/来源列表。 源码位置：src/components/chat-content/reference-content/reference-content.vue。
+
+**关联**：content-render（ReferenceDocument 类型内容路由到本组件）、activity-message（知识库等活动场景内嵌引用列表）
+
+---
+
+# ReferenceContent 引用文档内容
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/reference-content/reference-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：渲染引用文档/来源列表。
+
+> **能力域**：内容渲染
+
+引用文档列表渲染基础组件，用于展示 AI 回复中引用的参考文档，每项包含文档图标、标题、预览与跳转操作。
+
+主要由 `ActivityMessage`（知识库问答场景）和 `ContentRender`（`reference_document` 类型内容）内部使用。
+
+## 组件结构
+
+```
+<template>（无根元素，Fragment 模式）
+  v-for item in links（过滤 name 为空 → 映射为 { title, url, originFileUrl }）
+    │
+    div.ai-reference-item（flex，height: 28px，padding: 0 12px，color: #3a84ff）
+      ├── DocLinkIcon（color="#D66F6B"，.ai-doc-link-icon，始终可见）
+      ├── span.ai-reference-item-title（flex: 1，ellipsis，font-size: 12px）
+      │     @click → url && gotoLink(url, event)
+      │     （XSS 安全：{{ item.title }} 文本插值）
+      ├── [v-if url && originFileUrl] PreviewIcon（.ai-common-icon）
+      │     v-tippy: "预览内容"
+      │     @click → gotoLink(url, event)
+      │     默认 display: none，hover 父容器后 display: flex
+      └── [v-if url && originFileUrl] TargetIcon（.ai-common-icon）
+            v-tippy: "跳转详情"
+            @click → gotoLink(originFileUrl, event)
+            默认 display: none，hover 父容器后 display: flex
+
+gotoLink(url, event):
+  event.stopPropagation() + event.preventDefault()
+  window.open(url, '_blank', 'noopener,noreferrer')
+```
+
+> **`v-for` key**：使用 `item.title`（即 `name`）作为 `:key`，同一组 `content` 中 `name` 须唯一，否则触发 Vue 重复 key 警告。
+
+## 图标可见性规则
+
+| 图标                      | 始终显示 | 显示条件（数据层）                | 显示条件（交互层） |
+| ------------------------- | -------- | --------------------------------- | ------------------ |
+| `DocLinkIcon`（红色书签） | ✓        | 无条件                            | 无条件             |
+| `PreviewIcon`（预览）     | —        | `url` 与 `originFileUrl` 均为真值 | 仅在 hover 时出现  |
+| `TargetIcon`（跳转）      | —        | `url` 与 `originFileUrl` 均为真值 | 仅在 hover 时出现  |
+
+即：只有 `url` 没有 `originFileUrl`（或反之），两个操作图标均不渲染。
+
+## 基础用法
+
+```vue
+<template>
+  <ReferenceContent :content="references" />
+</template>
+
+<script setup lang="ts">
+  import { ReferenceContent } from '@blueking/chat-x';
+  import type { ReferenceDocumentContent } from '@blueking/chat-x';
+
+  const references: ReferenceDocumentContent[] = [
+    { name: '蓝鲸 PaaS 平台文档', url: 'https://bk.tencent.com', originFile: '' },
+    { name: '组件库使用指南', url: 'https://bk.tencent.com/docs', originFile: '' },
+  ];
+</script>
+```
+
+## 含预览与跳转（url + originFile）
+
+同时提供 `url` 和 `originFile` 时，hover 后出现预览图标和跳转图标：
+
+## 混合场景：过滤与图标差异
+
+`name` 为空的项被过滤不渲染；`originFile` 为空时不显示 `PreviewIcon` / `TargetIcon`：
+
+```typescript
+const refs = [
+  { name: '有预览和跳转', url: 'https://…/preview', originFile: 'https://…/origin' }, // 两图标
+  { name: '仅有 url', url: 'https://…/only', originFile: '' }, // 无图标
+  { name: '', url: 'https://…/filtered', originFile: '' }, // 被过滤
+];
+// 实际渲染 2 条，第 3 条因 name='' 被过滤
+```
+
+## API
+
+### Props
+
+| 属性名  | 类型                         | 必填 | 说明                                          |
+| ------- | ---------------------------- | ---- | --------------------------------------------- |
+| content | `ReferenceDocumentContent[]` | ✓    | 引用文档列表；`name` 为空的项会被过滤，不渲染 |
+
+### 类型定义
+
+```typescript
+export type ReferenceDocumentContent = {
+  name: string; // 文档标题（用作列表展示文本，也作为 v-for :key）
+  url: string; // 预览链接：标题点击、PreviewIcon 点击时打开
+  originFile: string; // 原始文件链接：TargetIcon 点击时打开；为空则不渲染两个操作图标
+};
+```
+
+## 使用场景
+
+`ReferenceContent` 在两处被内部使用：
+
+**1. `ActivityMessage`（知识库问答）**
+
+```typescript
+// content 为 ReferenceDocumentContent[] 数组时直接传入
+<ReferenceContent :content="Array.isArray(content) ? content : content?.referenceDocument || []" />
+```
+
+**2. `ContentRender`（content 类型路由）**
+
+```typescript
+// type === MessageContentType.ReferenceDocument 且 content 为数组时
+h(ReferenceContent, { content: props.content as ReferenceDocumentContent[] });
+```
+
+## 关联组件
+
+- [ContentRender](/components/rendering/content-render) — 内容类型分发
+- [ActivityMessage](/components/message/activity-message) — 活动消息内引用

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

@@ -0,0 +1,109 @@
+# ReferenceDocContent 引用文档活动
+
+> 能力域：Agent 能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+渲染引用文档类活动内容，复用 ActivityLayout 与 ReferenceContent。 源码位置：src/components/chat-content/reference-doc-content/reference-doc-content.vue。
+
+**关联**：activity-message（非 knowledge_rag / flow_agent 活动默认可分发为引用文档活动）、activity-layout（提供可折叠的活动容器外壳）、reference-content（渲染引用文档列表）
+
+---
+
+# ReferenceDocContent 引用文档活动
+
+> **能力域**：Agent 能力
+
+`ReferenceDocContent` 用于渲染“引用 N 篇资料作为参考”这类活动消息。组件基于 `ActivityLayout` 提供折叠外壳，并将文档数组交给 `ReferenceContent` 展示。
+
+通常不需要直接使用，`ActivityMessage` 会在引用文档活动场景中分发到本组件。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/reference-doc-content/reference-doc-content.vue`
+- **能力说明**：渲染引用文档类活动内容，复用 ActivityLayout 与 ReferenceContent。
+
+## 核心能力
+
+- **数量标题**：根据 `content.length` 生成标题，中文为“引用 N 篇资料作为参考”
+- **文档图标**：标题区域固定展示文档图标，不随消息状态变化
+- **可折叠内容**：通过 `v-model:collapsed` 控制引用列表展开/收起，默认展开
+- **引用列表复用**：文档展示、hover 操作图标、链接打开规则均由 `ReferenceContent` 负责
+
+## 基础用法
+
+```vue
+<template>
+  <ReferenceDocContent
+    v-model:collapsed="collapsed"
+    :content="docs"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import ReferenceDocContent from '@blueking/chat-x/src/components/chat-content/reference-doc-content/reference-doc-content.vue';
+  import type { ReferenceDocumentContent } from '@blueking/chat-x';
+
+  const collapsed = ref(false);
+
+  const docs: ReferenceDocumentContent[] = [
+    { name: '蓝鲸 Agent 接入指南', url: 'https://example.com/agent', originFile: 'https://example.com/docs/agent' },
+    { name: '主机巡检操作手册', url: 'https://example.com/host-check', originFile: 'https://example.com/docs/host-check' },
+  ];
+</script>
+```
+
+**渲染效果**
+
+## 空引用
+
+当 `content` 为空或未传入时，标题数量显示为 `0`，引用列表为空。
+
+## 折叠状态
+
+## API
+
+### Props
+
+| 属性名     | 类型                         | 必填 | 默认值 | 说明                                   |
+| ---------- | ---------------------------- | ---- | ------ | -------------------------------------- |
+| content    | `ReferenceDocumentContent[]` | 否   | —      | 引用文档列表                           |
+| messageUid | `string`                     | 否   | —      | 所属消息唯一标识，当前组件暂未直接使用 |
+
+### Models
+
+| 名称      | 类型      | 默认值  | 说明             |
+| --------- | --------- | ------- | ---------------- |
+| collapsed | `boolean` | `false` | 活动内容是否折叠 |
+
+### Emits
+
+- 无显式 emits；`v-model:collapsed` 会产生 `update:collapsed`。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 类型定义
+
+```typescript
+export type ReferenceDocumentContent = {
+  name: string;       // 文档标题
+  originFile: string; // 原始文件链接，存在时 ReferenceContent 显示跳转操作
+  url: string;        // 预览链接或标题点击链接
+};
+```
+
+## 使用建议
+
+- 只负责引用文档活动外壳；如果只需要纯引用列表，请直接使用 [ReferenceContent](../rendering/reference-content.md)。
+- 文档条目的过滤与操作图标规则以 `ReferenceContent` 为准，`ReferenceDocContent` 不重复处理。
+
+## 关联组件
+
+- [ActivityMessage](../message/activity-message.md) — 活动消息分发入口。
+- [ActivityLayout](../helper/activity-layout.md) — 折叠活动外壳。
+- [ReferenceContent](../rendering/reference-content.md) — 引用来源列表。

package/skills/blueking-chat-x/references/components/resource-icon.md

@@ -0,0 +1,98 @@
+# ResourceIcon 资源图标
+
+> 能力域：辅助能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 0.0.51
+
+ResourceIcon 统一渲染资源图标：icon 为字符串按 img 加载（加载失败回退内置图标）、 为 Vue 组件直接渲染、缺省时按 type 查内置图标表（artifact 交给 FileIcon 按文件名后缀推导， 未登记类型回退 ModuleIcon）；尺寸由 --ai-icon-size 控制，默认 16px。 源码位置：src/components/resource-icon/resource-icon.vue。
+
+**关联**：input-menu-panel（菜单条目左侧图标）、mention-tag（输入框与消息中的资源标签图标）、model-selector（模型选择器的触发器与选项图标）、file-icon（artifact 类型委托给 FileIcon 按后缀推导）
+
+---
+
+# ResourceIcon 资源图标
+
+> **能力域**：辅助能力
+
+## 源码事实
+
+- **源码位置**：`src/components/resource-icon/resource-icon.vue`
+- **内置图标表**：`file` → `FileUploadIcon`、`mcp` → `McpIcon`、`tool` → `ToolIcon`、`knowledgebase` / `doc` → `KnowledgeBaseIcon`、`prompt` → `PromptIcon`
+- **特殊分支**：`artifact` 走 [FileIcon](/components/helper/file-icon) 按 `name` 的文件后缀推导
+- **最终兜底**：以上都不命中时渲染 `ModuleIcon`（田字格）
+
+## 渲染优先级
+
+```
+icon 有值？
+├── 字符串 → <img :src="icon">
+│             └── onerror → 降级到「按 type 兜底」
+└── Vue 组件 → <component :is="icon">
+icon 缺省
+├── type === 'artifact' → FileIcon（按 name 后缀）
+├── type 命中内置图标表 → 对应内置图标
+└── 其他 → ModuleIcon
+```
+
+`icon` 变化时会重置失效标记，换成新的 URL 会重新尝试加载。
+
+::: info 内部组件
+本组件不在包入口导出，由菜单、标签与模型选择器内部使用。内置图标（`McpIcon` / `ToolIcon` / `KnowledgeBaseIcon` / `PromptIcon` / `ModuleIcon` / `FileUploadIcon` / `ImageUploadIcon`）从包入口导出，可单独使用，见 [Icons 图标](/icons/)。
+:::
+
+## 用法
+
+```vue
+<template>
+  <!-- 远程图标 -->
+  <ResourceIcon icon="https://example.com/tool.png" name="天气查询" type="tool" />
+  <!-- Vue 组件图标 -->
+  <ResourceIcon :icon="McpIcon" name="database-server" type="mcp" />
+  <!-- 按类型兜底 -->
+  <ResourceIcon name="API 接口文档" type="knowledgebase" />
+  <ResourceIcon name="写文章" type="prompt" />
+  <!-- 会话产物按后缀推导 -->
+  <ResourceIcon name="巡检报告.pdf" type="artifact" />
+</template>
+
+<script setup lang="ts">
+  import { McpIcon } from '@blueking/chat-x';
+</script>
+```
+
+**渲染效果**（均未传 `icon`，展示按类型兜底的结果）
+
+## 控制尺寸
+
+容器宽高与 `font-size` 都取 `var(--ai-icon-size, 16px)`，图片以 `object-fit: contain` 填充并带 2px 圆角。需要改尺寸时覆盖该变量，不要直接改 svg：
+
+```vue
+<template>
+  <span style="--ai-icon-size: 24px">
+    <ResourceIcon name="巡检报告.pdf" type="artifact" />
+  </span>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名 | 类型                    | 必填 | 说明                                                     |
+| ------ | ----------------------- | ---- | -------------------------------------------------------- |
+| icon   | `Component \| string`   | -    | 图标 URL 或 Vue 组件；缺省时按 `type` 回退               |
+| name   | `string`                | ✅   | 资源名称；`type` 为 `artifact` 时据此推导文件类型图标    |
+| type   | `string`                | ✅   | 资源类型，决定兜底图标                                   |
+
+### Emits / Slots / Expose
+
+- 无。
+
+## 扩展新类型
+
+新增类型只需在组件内的 `TYPE_FALLBACK_ICONS` 表里补一行，不必往模板加分支。`model` 等未登记的类型会落到 `ModuleIcon`，因此 [ModelSelector](/components/input/model-selector) 在模型没有 `icon` 时不会缺图。
+
+## 关联组件
+
+- [InputMenuPanel](/components/input/input-menu-panel) — 菜单条目图标
+- [MentionTag](/components/rendering/mention-tag) — 资源标签图标
+- [ModelSelector](/components/input/model-selector) — 模型图标
+- [FileIcon](/components/helper/file-icon) — `artifact` 类型的实际渲染者