@blueking/chat-x 0.0.49-beta.1 → 0.0.49-beta.11

package/dist/mcp/generated/docs/file-artifact-panel.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-汇总当前会话所有 AssistantMessage 的 artifacts，支持关键词搜索、列表选中与下载； 预览区委托 ArtifactPreviewHost：按类型走 text_from_download（html / markdown / md / txt / json） 或 preview_url_iframe（其余类型）；download_url / preview_url 经 onArtifactClick 异步获取。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。
+汇总当前会话所有 AssistantMessage 的 artifacts（按 outputId 去重），支持关键词搜索、列表选中与下载； 预览区委托 ArtifactPreviewHost：由 resolveFileKind 把扩展名归入 code / markdown / html / text / image / binary 六类， 前四类走 text_from_download 拉正文（code 交给 highlight.js 高亮），image / binary 走 preview_url； download_url / preview_url 经 onArtifactClick 每次异步获取（无 URL 缓存，并发去重）； 预览重载键为 outputId:type；重试再次调用 load() 重新取链。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。
 
 ### 关联组件
 - **assistant-message** — 文件产物来源于 AssistantMessage.property.artifacts
@@ -22,16 +22,17 @@
 
 > **导出说明**：内部侧栏面板组件，**通常不直接使用**；由 `ChatContainer` 在「文件产物」Tab 内自动挂载。预览加载与渲染为同目录下 `artifact-preview/` 内部实现，不单独导出。
 
-点击 AI 回复中的[文件卡片](/components/message/assistant-message)后，`ChatContainer` 侧栏会弹出固定的「文件产物」Tab，聚合展示当前会话**所有** `AssistantMessage` 的文件产物，并命中被点击的文件进行预览。
+点击 AI 回复中的[文件卡片](/components/message/assistant-message)后，`ChatContainer` 侧栏会弹出固定的「文件产物」Tab，聚合展示当前会话**所有** `AssistantMessage` 的文件产物（按 `outputId` 去重），并命中被点击的文件进行预览。
 
 面板左侧为可搜索的文件列表，右侧为预览区。通常不需要直接使用，由 `ChatContainer` 在侧栏内自动渲染。
 
 ## 核心能力
 
-- **会话级聚合**：拍平当前会话所有 `AssistantMessage.property.artifacts`，统一在一个列表内展示
-- **唯一命中**：同一会话可能出现多个消息 + 同名文件，文件名不可作唯一键，统一用 `messageUid#消息内下标#outputId` 生成全局唯一 id
+- **会话级聚合**：拍平当前会话所有 `AssistantMessage.property.artifacts`，以 `outputId` 去重后统一在一个列表内展示
+- **唯一命中**：以 `outputId` 作为会话内唯一键（同 `outputId` 视为同一文件）；文件名可能重复，不可作唯一键
 - **关键词搜索**：按文件名实时过滤列表
-- **异步取链**：`AIFileInfo` 本身不含 `url` / `previewUrl`，通过 `ChatContainer` 的 `onArtifactClick` 按 `outputId` 缓存获取 `download_url` / `preview_url`
+- **整块空态**：`artifacts` 为空时不渲染列表与预览区，整块展示 bkui `Exception`「暂无数据」（Tab 常驻，无数据也可正常打开侧栏）
+- **异步取链**：`AIFileInfo` 本身不含 `url` / `previewUrl`，通过 `ChatContainer` 的 `onArtifactClick` 按 `outputId` 获取 `download_url` / `preview_url`（TTL 8 分钟缓存；预览重试会 `force` 刷新）
 - **职责拆分**：
   - **面板本身**：列表、搜索、预览头（文件名 / 图标 / 下载）
   - **`ArtifactPreviewHost`**：按策略加载正文或预览 URL，分派到对应 renderer；展示 loading / empty / error（含重试）
@@ -54,12 +55,12 @@
 
 <script setup lang="ts">
   import { shallowRef } from 'vue'
-  import { buildArtifactId, useArtifactPreviewProvider } from '@blueking/chat-x'
+  import { useArtifactPreviewProvider } from '@blueking/chat-x'
   import type { AIFileInfo, SessionArtifact } from '@blueking/chat-x'
   // 内部组件：仅文档 / 调试；业务请用 ChatContainer 自动挂载
   import FileArtifactPanel from './message-artifacts/file-artifact-panel.vue'
 
-  const files: AIFileInfo[] = [
+  const sessionArtifacts: SessionArtifact[] = [
     { name: '周报.html', outputId: 'a-html', size: 10240, type: 'html' },
     { name: '说明.md', outputId: 'a-md', size: 8192, type: 'md' },
     { name: '纪要.txt', outputId: 'a-txt', size: 4096, type: 'txt' },
@@ -67,12 +68,6 @@
     { name: '立项.pdf', outputId: 'a-pdf', size: 204800, type: 'pdf' },
   ]
 
-  const sessionArtifacts: SessionArtifact[] = files.map((file, index) => ({
-    ...file,
-    artifactId: buildArtifactId('msg-1', index, file.outputId),
-    messageUid: 'msg-1',
-  }))
-
   useArtifactPreviewProvider({
     getOnArtifactClick: () => async file => {
       // 文本类返回可 fetch 的 download_url；iframe 类返回 preview_url
@@ -82,7 +77,7 @@
     onOpen: () => {},
   })
 
-  const activeArtifactId = shallowRef(sessionArtifacts[0].artifactId)
+  const activeArtifactId = shallowRef(sessionArtifacts[0].outputId)
   const handleSelect = (id: string) => {
     activeArtifactId.value = id
   }
@@ -160,47 +155,55 @@
 
 ```
 ArtifactFileCard（点击文件卡片）
-  └─ useArtifactPreviewConsumer().openPreview({ file, index, messageUid })
+  └─ useArtifactPreviewConsumer().openPreview({ file })
        └─ useArtifactPreviewProvider（ChatContainer 内）
-            ├─ 记录命中文件 activeArtifactId
+            ├─ 记录命中文件 activeArtifactId = file.outputId
             └─ onOpen → addCustomTab('file-artifact') 展开并选中侧栏 Tab
                  └─ FileArtifactPanel
-                      ├─ 列表 @select → setActiveArtifactId
+                      ├─ 列表 @select → setActiveArtifactId(outputId)
                       ├─ 下载 → resolveArtifactUrls + triggerArtifactDownload
                       └─ ArtifactPreviewHost
                            ├─ useArtifactPreviewLoader（策略 + fetch / 取链，防竞态）
                            └─ HtmlPreview | MarkdownPreview | TxtPreview | UrlIframePreview
+
+容器初始化
+  └─ ensureCustomTab('file-artifact') 常驻挂上（不展开侧栏）；因 order:-1 排在首位，
+     未主动切换过 Tab 时会成为默认选中面板；无产物时由面板展示整块空态
 ```
 
 - 文件卡片通过 `useArtifactPreviewConsumer` 注入预览上下文，无 Provider 时卡片不可点击（兜底 `undefined`）
 - `ChatContainer` 通过 `useArtifactPreviewProvider` 提供上下文，并把「打开侧栏 Tab」这一副作用以 `onOpen` 注入，保持 composable 职责单一
-- 侧栏「文件产物」Tab 固定不可关闭，`order: -1` 排在「执行情况」之前；会话切换或无文件产物时自动移除
+- 侧栏「文件产物」Tab 固定不可关闭，`order: -1` 排在「执行情况」之前；**常驻不随产物有无增删**，无产物时由面板展示整块空态
 
-## 唯一 id 规则
+## 唯一键规则
 
-同一会话可能存在多个 `AssistantMessage`，且不同消息里可能有同名文件，因此**文件名不可作为唯一键**。统一由 `buildArtifactId` 生成：
+会话内以 **`outputId`** 作为文件产物唯一键：
 
-```typescript
-import { buildArtifactId } from '@blueking/chat-x';
+- 同一 `outputId` 在多条消息中出现时，聚合列表去重并保留最后一次出现的文件信息
+- `activeId`、列表 `:key`、`select` 事件参数均使用 `outputId`
+- 文件名可能重复，**不可**作为唯一键
 
-// messageUid#消息内下标#outputId
-buildArtifactId('msg-a', 2, 'output-9'); // => 'msg-a#2#output-9'
-```
+## 预览机制
 
-Provider 侧聚合与文件卡片侧透传必须使用同一规则，保证命中一致。
+预览分两步：先由 `resolveFileKind(type, name)`（`src/utils/file-type.ts`）把扩展名归入六个**分类**，再由 `getArtifactPreviewStrategy` 查表得到 **加载方式** 与 **渲染器**。面板与 Host 都不写死具体扩展名分支，后台新增文件类型时只需在分类表里补一行。
 
-## 预览机制
+| 分类 | 覆盖扩展名 | load | 取链字段 | renderer |
+| ---- | ---------- | ---- | -------- | -------- |
+| `code` | `py` `js` `mjs` `cjs` `ts` `tsx` `jsx` `vue` `go` `rs` `rb` `java` `kt` `swift` `c` `h` `cpp` `hpp` `cs` `php` `lua` `r` `scala` `dart` `sh` `bash` `zsh` `ps1` `sql` `css` `scss` `less` `json` `jsonc` `yaml` `yml` `toml` `ini` `cfg` `conf` `env` `xml` `tex` `Dockerfile` `Makefile` `gitignore` `dockerignore` `editorconfig` | `text_from_download` | `download_url` → `fetch` 正文 | `CodePreview`（highlight.js 高亮） |
+| `markdown` | `md` `markdown` | `text_from_download` | 同上 | `MarkdownPreview`（`MarkdownContent`） |
+| `html` | `html` `htm` | `text_from_download` | 同上 | `HtmlPreview`（`<iframe srcdoc>`） |
+| `text` | `txt` `rst` | `text_from_download` | 同上 | `TxtPreview`（`<pre>`） |
+| `image` | `png` `jpg` `jpeg` `svg` | `preview_url` | `preview_url` | `ImagePreview`（`<img>`，`object-fit: contain`） |
+| `binary` | `pdf` `docx` `xlsx` `xlsm` `xls` `pptx` `csv` `tsv`，以及**所有未登记的扩展名** | `preview_url` | `preview_url` | `UrlIframePreview`（`<iframe src>`，一般为后台转好的 PDF） |
 
-预览由内部 `getArtifactPreviewStrategy(type)` 决定 **加载方式** 与 **渲染器**；面板不直接写死类型分支。
+关于类型解析：
 
-| 文件类型 | load | 取链字段 | renderer |
-| -------- | ---- | -------- | -------- |
-| `html` | `text_from_download` | `download_url` → `fetch` 正文 | `HtmlPreview`（`<iframe srcdoc>`） |
-| `markdown` / `md` | `text_from_download` | 同上 | `MarkdownPreview`（`MarkdownContent`） |
-| `txt` / `json` | `text_from_download` | 同上 | `TxtPreview`（`<pre>`） |
-| 其余（如 `pdf` / `jpg`） | `preview_url_iframe` | `preview_url` | `UrlIframePreview`（`<iframe src>`，一般为后台转好的 PDF） |
+- `AIFileInfo.type` 为**扩展名字符串**（如 `'pdf'` / `'py'`）或无扩展名的文件名（如 `'Dockerfile'`），大小写不敏感
+- `type` 缺省时回退 `name` 推断；`报告.final.xlsx` 取 `xlsx`，`.gitignore` 取 `gitignore`
+- `md` 为后台扩展名别名，与 `markdown` 等价，共用 Markdown 直渲染
+- 未登记的扩展名一律落入 `binary` 走后台预览，前端不会因为新类型报错
 
-> `md`（`AIFileType.Md`）为后台扩展名别名，与 `markdown`（`AIFileType.Markdown`）等价，共用 Markdown 直渲染。
+`CodePreview` 的语言由扩展名映射到 highlight.js（`vue → xml`、`tsx → typescript`、`env / cfg / conf → ini` 等，其余交给 hljs 自身别名表，识别不了则按 `plaintext` 转义输出）。单文件超过 300KB 时跳过高亮直接转义，避免同步解析阻塞主线程。
 
 ### 加载态
 
@@ -211,7 +214,14 @@ Provider 侧聚合与文件卡片侧透传必须使用同一规则，保证命
 | `empty` | 「暂无可预览的文件」（无文件 / 未传 `onArtifactClick` / 缺所需 URL） |
 | `error` | 「预览加载失败」+ 重试按钮 |
 
-切换文件时 `useArtifactPreviewLoader` 用 `loadSeq` + `AbortController` 中断上一次 `fetch`，避免竞态覆盖。下载图标仍由面板用 bkui `Loading` spin 单独表达。
+### 重载与取链约定
+
+- **重载键**：`ArtifactPreviewHost` 以 `` `${outputId}:${type}` `` 监听文件变化；`outputId` 或 `type` 任一变化会重新 `load()`，仅改文件名等其它字段不会
+- **取链**：`resolveArtifactUrls(file)` 每次重新调用 `onArtifactClick`；同文件进行中的请求会复用（并发去重）
+- **重试**：错误态点击重试再次走 `load()`，重新取链并加载
+- **竞态**：切换文件时 `useArtifactPreviewLoader` 用 `loadSeq` + `AbortController` 中断上一次 `fetch`，避免过期结果覆盖最新内容
+
+下载图标仍由面板用 bkui `Loading` spin 单独表达。
 
 ## 内部结构（不导出）
 
@@ -220,29 +230,33 @@ message-artifacts/
 ├── file-artifact-panel.vue          # 列表 + 下载头 + 挂载 Host
 └── artifact-preview/
     ├── artifact-preview-host.vue    # 状态机 UI + 分派 renderer
-    ├── preview-strategy.ts          # getArtifactPreviewStrategy
+    ├── preview-strategy.ts          # getArtifactPreviewStrategy（分类 → 策略查表）
     ├── use-artifact-preview-loader.ts
     └── renderers/
+        ├── code-preview.vue
         ├── html-preview.vue
+        ├── image-preview.vue
         ├── markdown-preview.vue
         ├── txt-preview.vue
         └── url-iframe-preview.vue
 ```
 
+分类表与扩展名归一化在 `src/utils/file-type.ts`（导出 `AIFileKind` / `resolveFileKind` / `normalizeFileExtension`），与[文件图标](/components/helper/file-icon)共用同一份解析入口。
+
 ## API
 
 ### Props
 
 | 属性名    | 类型                | 必填 | 说明                                   |
 | --------- | ------------------- | ---- | -------------------------------------- |
-| activeId  | `string`            | ✓    | 当前命中的文件 id（`messageUid#index#outputId`） |
-| artifacts | `SessionArtifact[]` | ✓    | 当前会话全部文件产物                   |
+| activeId  | `string`            | ✓    | 当前命中的文件 `outputId`              |
+| artifacts | `SessionArtifact[]` | ✓    | 当前会话全部文件产物（已按 `outputId` 去重） |
 
 ### Events
 
 | 事件名 | 参数              | 说明                       |
 | ------ | ----------------- | -------------------------- |
-| select | `(id: string)`    | 列表内切换选中文件，参数为文件 `artifactId` |
+| select | `(id: string)`    | 列表内切换选中文件，参数为文件 `outputId` |
 
 ### Slots / Expose
 
@@ -253,20 +267,20 @@ message-artifacts/
 ```typescript
 import type { AIFileInfo, SessionArtifact } from '@blueking/chat-x';
 
-// 会话级文件产物：在 AIFileInfo 基础上补充命中所需字段
-type SessionArtifact = AIFileInfo & {
-  artifactId: string; // 全局唯一 id：messageUid#index#outputId
-  messageUid: string; // 所属 AssistantMessage 的 uid
-};
+// 会话级文件产物：拍平去重后即为 AIFileInfo
+type SessionArtifact = AIFileInfo;
 
 type AIFileInfo = {
   name: string;
   outputId: string;
   size: number;
-  type: AIFileType;
+  /** 扩展名（如 'pdf' / 'py'）或无扩展名文件名（如 'Dockerfile'），大小写不敏感 */
+  type: string;
 };
 ```
 
+> **破坏性变更**：原 `AIFileType` 枚举已移除，`AIFileInfo.type` 改为 `string`。此前写 `type: AIFileType.Pdf` 的代码改为 `type: 'pdf'` 即可；枚举成员的值与新字符串一一对应，运行时数据无需迁移。
+
 ## 关联 Composable
 
 预览**命中与取链**由 [useArtifactPreview](/composables/use-artifact-preview) 提供（Provider / Consumer + `ARTIFACT_PREVIEW_TOKEN`）。**正文加载与渲染**由内部 `useArtifactPreviewLoader` + `ArtifactPreviewHost` 完成，不在该 composable 内。

package/dist/mcp/generated/docs/file-icon.md

@@ -0,0 +1,111 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+按扩展名渲染文件类型图标：内联 svg，尺寸用 1em 跟随外层 font-size； 扩展名解析走 normalizeFileExtension（优先 fileType，缺省回退 fileName，大小写不敏感， 支持 Dockerfile / .gitignore 这类无扩展名或点号开头的文件）；未登记类型返回 unknown 兜底图标。 源码位置：src/components/file-icon/file-icon.vue，图标注册表在 src/icons/file-icons.ts。
+
+### 关联组件
+- **file-artifact-panel** — 文件产物列表与预览头使用该组件展示类型图标
+- **assistant-message** — 消息内的文件产物卡片使用该组件
+
+---
+<!-- FULL DOC -->
+
+# FileIcon 文件类型图标
+
+> **能力域**：辅助能力
+
+`FileIcon` 按文件扩展名渲染对应的类型图标，用于文件列表、附件卡片、产物预览头等需要「一眼看出这是什么文件」的场景。图标以内联 svg 形式打进包内，不产生额外网络请求，也不需要消费方配置静态资源路径。
+
+## 源码事实
+
+- **源码位置**：`src/components/file-icon/file-icon.vue`
+- **图标注册表**：`src/icons/file-icons.ts`（导出 `getFileIconSvg` / `UNKNOWN_FILE_ICON_SVG`）
+- **扩展名解析**：`src/utils/file-type.ts` 的 `normalizeFileExtension`
+
+## 核心能力
+
+- **扩展名驱动**：优先取 `fileType`，缺省时回退 `fileName` 推断；大小写不敏感
+- **特殊文件名**：`Dockerfile` / `Makefile` 这类无扩展名文件，以及 `.gitignore` / `.editorconfig` 这类点号开头的文件都能正确命中
+- **多扩展名共用图标**：如 `xlsx` / `xls` / `csv` / `tsv` 共用表格图标，`tsx` / `jsx` 共用 React 图标
+- **兜底不报错**：未登记的扩展名返回 `unknown` 图标，后台新增文件类型时前端不会缺图
+- **尺寸自适应**：内部 svg 固定为 `1em`，直接用外层 `font-size` 控制大小
+
+## 基础用法
+
+```vue
+<template>
+  <FileIcon file-type="pdf" />
+</template>
+
+<script setup lang="ts">
+  import { FileIcon } from '@blueking/chat-x';
+</script>
+```
+
+**渲染效果**
+
+## 从文件名推断
+
+后台未下发 `type` 时传 `fileName` 即可，组件会取最后一段扩展名：
+
+```vue
+<template>
+  <!-- 取 xlsx -->
+  <FileIcon file-name="季度报告.final.xlsx" />
+  <!-- 取 gitignore -->
+  <FileIcon file-name=".gitignore" />
+</template>
+```
+
+两者同时传入时以 `fileType` 优先。
+
+## 控制尺寸
+
+图标宽高为 `1em`，用外层 `font-size` 控制即可，无需改 svg：
+
+```vue
+<template>
+  <span style="font-size: 16px"><FileIcon file-type="py" /></span>
+  <span style="font-size: 32px"><FileIcon file-type="py" /></span>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型     | 必填 | 默认值      | 说明                                                     |
+| -------- | -------- | ---- | ----------- | -------------------------------------------------------- |
+| fileType | `string` | 否   | `undefined` | 文件类型：扩展名（如 `pdf` / `py`）或无扩展名文件名（如 `Dockerfile`） |
+| fileName | `string` | 否   | `undefined` | 文件名，`fileType` 缺省时用于推断扩展名                    |
+
+两者都不传时渲染兜底图标。
+
+### Emits / Slots / Expose
+
+- 无。
+
+## 图标覆盖范围
+
+| 图标 | 覆盖扩展名 |
+| ---- | ---------- |
+| 文档类 | `pptx` / `docx` / `pdf` / `txt` / `rst` / `md` / `markdown` / `tex` |
+| 表格类 | `xlsx` / `xlsm` / `xls` / `csv` / `tsv` |
+| 前端 | `html` / `htm` / `css` / `scss` / `less` / `js` / `mjs` / `cjs` / `ts` / `tsx` / `jsx` / `vue` / `xml` |
+| 后端 / 系统 | `py` / `go` / `rs` / `rb` / `java` / `kt` / `swift` / `c` / `h` / `cpp` / `hpp` / `cs` / `php` / `lua` / `r` / `scala` / `dart` / `sql` / `sh` / `bash` / `zsh` / `ps1` |
+| 配置 | `json` / `jsonc` / `yaml` / `yml` / `toml` / `ini` / `cfg` / `conf` / `env` / `editorconfig` / `Makefile` |
+| 工具链 | `Dockerfile` / `dockerignore` / `gitignore` |
+| 图片 | `png` / `jpg` / `jpeg` / `svg` |
+| 兜底 | 以上之外的所有类型 |
+
+新增类型时在 `src/icons/file-icons.ts` 的 `FILE_ICON_GROUPS` 里补一行即可；对应 svg 需先放进 `src/svgs/` 并按需 `?raw` 引入（只引实际用到的，避免把整个图标库打进产物）。
+
+## 使用建议
+
+- 图标颜色由 svg 自带，不继承 `currentColor`，不要试图用 `color` 覆盖
+- 需要与文件名同行展示时，给父容器设 `display: flex` + `gap`，组件本身已是 `inline-flex` 且 `flex-shrink: 0`
+
+## 关联组件
+
+- [FileArtifactPanel](../message/file-artifact-panel.md) — 文件产物列表与预览头使用该组件。
+- [AssistantMessage](../message/assistant-message.md) — 消息内文件产物卡片的图标来源。

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

@@ -20,16 +20,17 @@
 
 > **导出说明**：`InfoMessage` **未**从包入口导出（入口同名是 TS interface）。消费方经 `MessageRender` / `MessageContainer` 使用。下文 `InfoMessageComp` 为文档站内部示例。
 
-系统信息分隔组件，在聊天消息列表中以**居中虚线分隔条**的形式展示非对话类信息（会话重置、时间节点、状态变更等）。
+系统信息分隔组件，在聊天消息列表中以**左右虚线夹中文案**的形式展示非对话类信息（会话重置、时间节点、状态变更等）。
 
 ## 视觉原理
 
-组件通过 `height: 0` + `border-bottom: 1px dashed #dcdee5` 生成一条贯穿全宽的虚线，内容文字区域设置白色背景"浮"在虚线中央，形成"文字刻在分隔线上"的视觉效果：
+根节点 `.ai-info-message` 为横向 flex：两侧通过 `::before` / `::after` 拉伸出虚线（主题边框色），中间 `.ai-info-message-body` 承载文案（主题次要文案色）。整块正常占位，避免旧实现 `height: 0` 导致内容被裁切遮挡：
 
 ```
-───── ─ ─ 以下是新的对话 ─ ─ ─────
+─────── 以下是新的对话 ───────
 ```
 
+多行时，多条 `.ai-info-message-content` 在 body 内纵向排列（`gap: 4px`），两侧虚线仍夹住整块文案区域。
 ## 基础用法
 
 `content` 传入字符串，渲染单行分隔信息：
@@ -56,7 +57,7 @@
 
 ## 多行信息
 
-`content` 传入字符串数组时，每个元素渲染为一个独立的文字浮标，均居中排列在同一条虚线上：
+`content` 传入字符串数组时，每个元素渲染为一行居中文案，在中间 body 内纵向排列，两侧虚线夹住整块区域：
 
 ```vue
 <template>
@@ -134,7 +135,7 @@
 
 | 属性名    | 类型                 | 说明                                                               |
 | --------- | -------------------- | ------------------------------------------------------------------ |
-| content   | `string \| string[]` | 信息内容。字符串渲染单行，数组渲染多个文字浮标，均居中排列在虚线上 |
+| content   | `string \| string[]` | 信息内容。字符串渲染单行；数组在中间区域纵向多行展示，两侧虚线夹住整块 |
 | id        | `number \| string`   | 消息 ID（接收但不使用，由 MessageContainer 管理）                  |
 | messageId | `number \| string`   | 消息唯一标识（接收但不使用）                                       |
 | status    | `MessageStatus`      | 消息状态（接收但不使用，组件无状态相关渲染逻辑）                   |

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

@@ -138,6 +138,7 @@ type UserQuestionOptionItem = {
 - 前端会为每道**选择题**追加 `label: 'others'` 的自由输入项；后端无需重复下发该选项。
 - 当用户选择 Others 时，`answer[].description` 为用户输入文本。
 - 业务可通过 `UserQuestionCard` 的 `#question` slot 渲染自定义表单；作答有效时调用 `setAnswer` 回传 `UserQuestionAnswerItem`，无效时传 `undefined`。
+- UI 一次只展示一题：标题栏 `< 当前题 / 总题数 >` 切换；单选预设选项作答后自动跳下一题，多选 / Others 需手动切换（协议字段不变）。
 
 ## Interrupt
 

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

@@ -26,7 +26,7 @@
 - **消息分组**：将连续的非用户消息合并为一组，每组共享一个工具栏
 - **Tool 消息关联**：自动将 `role: 'tool'` 消息注入到对应 Assistant 消息的 toolCall 中
 - **Loading 自动注入**：末尾为用户消息时，自动追加 Loading 动画组
-- **滚动管理**：`messageStatus` 为流式、等待响应或请求中（`streaming` / `pending` / `fetching`）时显示「停止生成」，离开底部时显示「返回底部」；`renderMode` 为 `Share` 时不显示「停止生成」
+- **滚动管理**：`messageStatus` 为流式、等待响应或请求中（`streaming` / `pending` / `fetching`）时显示「停止生成」，离开底部时显示「返回底部」；`renderMode` 为 `Share` 时不显示「停止生成」。挂载时通过 `jumpToBottom()` 瞬时贴底，避免切换会话时从顶部平滑滚到底部的动画
 - **多选模式**：支持按消息组勾选，用户消息与 AI 回复联动选中
 
 ## 基础用法
@@ -124,10 +124,29 @@
   - `renderMode === RenderMode.Share`（分享预览模式）
   - 消息组的 `pause` 为 `true`（来源于 `message.property?.extra?.pause`）
   - 多选模式（`enableSelection`）开启且消息组不是 Loading 类型
+- AI 消息组的时间通过 `MessageTools` 的 `#append` 插槽渲染在工具图标右侧，取值为组内**最后一条**带 `createdAt` 的消息（即本轮回答完成时间）；组内 `reasoning` / `activity` 等子消息不单独展示时间，全组都没有 `createdAt` 时不展示
 - `renderMode === RenderMode.Test` 时，工具栏会过滤掉「分享」按钮，其余正常
 - `renderMode === RenderMode.Share` 时，`message-group-messages` 自动添加 `message-group-enabled-selection` 类名（与 `enableSelection: true` 一致的多选视觉效果）
 - Loading 消息组的 `type` 是 `MessageRole.Loading`，不显示工具栏和多选 Checkbox
 
+## DOM 定位标识
+
+为方便业务方通过 `document.querySelector` 定位消息（埋点、自动化测试、外部滚动锚定等），渲染结构上固定输出两层标识：
+
+| 层级     | 选择器                                | 值                                                  |
+| -------- | ------------------------------------- | --------------------------------------------------- |
+| 消息组   | `.message-group[data-message-group-id]` | `MessageGroup.uid`（与外层 `id` 同值）              |
+| 单条消息 | `.ai-message-item[data-message-id]`   | `message.id`，缺失时回退 `message.uid`；两者都无则不输出该属性 |
+
+```js
+// 定位某条消息
+document.querySelector('[data-message-id="123"]');
+// 定位某个消息组下的全部消息
+document.querySelectorAll('[data-message-group-id="xxx"] [data-message-id]');
+```
+
+`.ai-message-item` 是 `MessageContainer` 统一包裹的容器，`#default` 插槽自定义渲染的消息同样被它包裹，因此无论用默认 `MessageRender` 还是自定义渲染，标识都一致存在。
+
 ## 等待响应（Loading 自动注入）
 
 当 `messages` 末尾为 `role: 'user'` 时，自动追加 Loading 消息组，展示 AI 正在处理的加载动画（`renderMode` 为 `Share` 时不追加，且 `MessageContainer` 会过滤 Loading 组）：
@@ -533,10 +552,11 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 | 按钮         | 显示条件                                                                                       | 点击行为               |
 | ------------ | ---------------------------------------------------------------------------------------------- | ---------------------- |
 | 「停止生成」 | `messageStatus` 为 `streaming`、`pending`、`fetching` 或 `stop-loading`（停止中 loading 态），且 `renderMode` 不为 `Share` | 触发 `@stop-streaming` |
-| 「返回底部」 | `debouncedShowScrollBottomBtn`（距底部 > 100px，且防抖 300ms 后才显示/隐藏）                     | 滚动到消息列表底部     |
+| 「返回底部」 | `debouncedShowScrollBottomBtn`（距底部 > 100px，且防抖 300ms 后才显示/隐藏）                     | 平滑滚动到消息列表底部（显式 `toScrollBottom('smooth')`） |
 
 > **防抖说明**：「返回底部」按钮的显隐使用 300ms 防抖，避免快速滚动时按钮频繁闪烁。隐藏时立即生效（无防抖），显示时延迟 300ms。
 
+> **首屏 / 切换会话贴底**：`MessageContainer` 挂载时若已有消息组，会立即调用 `jumpToBottom()`，并在下一帧再补一次，避免历史消息渲染过程中出现「从顶部滚到底部」的动画。流式输出场景下的小幅跟随仍由 markdown 挂载触发的 `toScrollBottom()`（距底较近时走 smooth）完成。
 ## API
 
 ### Props
@@ -613,32 +633,16 @@ enum MessageToolsStatus {
   Hidden = 'hidden',
 }
 
-// 消息角色
-enum MessageRole {
-  User = 'user',
-  Assistant = 'assistant',
-  Tool = 'tool',
-  Reasoning = 'reasoning',
-  Activity = 'activity',
-  Info = 'info',
-  Interrupt = 'interrupt',
-  Loading = 'loading',
-}
-
-// 消息状态
-enum MessageStatus {
-  Pending = 'pending',
-  Streaming = 'streaming',
-  Complete = 'complete',
-  Error = 'error',
-  Stop = 'stop',
-  Disabled = 'disabled',
-}
+// 消息角色 / 消息状态完整枚举见常量文档，勿在此维护副本
+// MessageRole、MessageStatus → ../../types/constants
 ```
 
+> `MessageRole` / `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。
+
 ## 关联组件
 
 - [MessageRender](/components/message/message-render) — 按组渲染每条消息时委托使用
+- [MessageTime](/components/feedback/message-time) — AI 消息组工具栏右侧的时间
 - [InterruptMessage 中断消息](/components/agent/interrupt-message) — `role: 'interrupt'` 的渲染与 `onInterruptResume` 透传
 - [ChatInput](/components/input/chat-input) — 常与输入区组合构成完整对话界面
 - [LoadingMessage](/components/message/loading-message) — 末尾为用户消息时自动追加加载组

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

@@ -315,35 +315,12 @@ h(ContentRender, { content: message.content || '', status: message.status }, /*
 ```typescript
 import { MessageRole, MessageStatus, MessageToolsStatus, type Message, type IToolBtn } from '@blueking/chat-x';
 
-// 消息角色
-enum MessageRole {
-  User = 'user',
-  Assistant = 'assistant',
-  Info = 'info',
-  Reasoning = 'reasoning',
-  Tool = 'tool',
-  Activity = 'activity',
-  Loading = 'loading',
-  Interrupt = 'interrupt',
-}
-
-// 消息状态
-enum MessageStatus {
-  Pending = 'pending',
-  Streaming = 'streaming',
-  Complete = 'complete',
-  Error = 'error',
-  Stop = 'stop',
-  Disabled = 'disabled',
-}
-
-// 工具按钮状态（仅转发给 UserMessage）
-enum MessageToolsStatus {
-  Disabled = 'disabled',
-  Hidden = 'hidden',
-}
+// MessageRole / MessageStatus 完整枚举见 ../../types/constants
+// MessageToolsStatus：Disabled | Hidden（仅转发给 UserMessage）
 ```
 
+> `MessageRole` / `MessageStatus` 完整取值见 [常量枚举](../../types/constants)。
+
 ## 关联组件
 
 - [MessageContainer](/components/setup/message-container) — 内部按组调用以渲染每条消息