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

package/dist/mcp/generated/docs/use-custom-tab.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
+useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据、可选 collapsed 注入受控折叠态 ref。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不主动切换选中；addCustomTab 会展开并选中。 未被主动切换过时，选中态默认跟随 Tab 栏首位（order 最小），如常驻的「文件产物」。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
 
 ### 关联组件
 - **chat-container** — Provider 与侧栏 Tab 主场景
@@ -21,6 +21,8 @@ Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边
 
 ```typescript
 function useCustomTabProvider<T extends Record<string, unknown>>(options: {
+  // 侧栏折叠态；由容器传入受控 ref（如 ChatContainer 的 v-model:asideCollapsed），缺省内部自持
+  collapsed?: Ref<boolean>;
   // 执行情况 Tab 是否展示，缺省 true；传 getter 以保持响应式
   executionTabVisible?: () => boolean | undefined;
   onTabChange?: (tab: CustomTab<T>) => void;
@@ -28,8 +30,9 @@ function useCustomTabProvider<T extends Record<string, unknown>>(options: {
   tabs: ShallowRef<CustomTab<T>[]>;
   displayTabs: ComputedRef<CustomTab<T>[]>;
   selectedTab: Ref<CustomTab<T>>;
-  isCollapse: ShallowRef<boolean>;
+  isCollapse: Ref<boolean>;
   addCustomTab: (tab: CustomTab<T>) => void;
+  ensureCustomTab: (tab: CustomTab<T>) => void;
   removeCustomTab: (tabName: string) => void;
   selectCustomTab: (tab: CustomTab<T>) => void;
   resetCustomTab: () => void;
@@ -46,6 +49,7 @@ function useCustomTabConsumer<T extends Record<string, unknown>>():
       displayTabs: ComputedRef<CustomTab<T>[]>;
       selectedTab: ShallowRef<CustomTab<T> | null>;
       addCustomTab: (tab: CustomTab<T>) => void;
+      ensureCustomTab: (tab: CustomTab<T>) => void;
       removeCustomTab: (tabName: string) => void;
       selectCustomTab: (tab: CustomTab<T>) => void;
       resetCustomTab: () => void;
@@ -59,7 +63,7 @@ function useCustomTabConsumer<T extends Record<string, unknown>>():
 ```typescript
 import { useCustomTabProvider, EXECUTION_TAB_NAME } from '@blueking/chat-x';
 
-const { tabs, selectedTab, isCollapse, addCustomTab, removeCustomTab, selectCustomTab, resetCustomTab } =
+const { tabs, selectedTab, isCollapse, addCustomTab, ensureCustomTab, removeCustomTab, selectCustomTab, resetCustomTab } =
   useCustomTabProvider({
   onTabChange: async tab => {
     // Tab 切换时加载数据
@@ -76,7 +80,7 @@ import { useCustomTabConsumer } from '@blueking/chat-x';
 
 const tabManager = useCustomTabConsumer();
 
-// 添加一个自定义 Tab
+// 添加一个自定义 Tab（展开侧栏并选中）
 tabManager?.addCustomTab({
   name: 'node-detail-123',
   label: '节点详情',
@@ -86,6 +90,14 @@ tabManager?.addCustomTab({
   },
 });
 
+// 仅确保 Tab 存在（不展开、不切换选中）—— 如常驻挂上文件产物 Tab
+tabManager?.ensureCustomTab({
+  name: 'file-artifact',
+  label: '文件产物',
+  closable: false,
+  order: -1,
+});
+
 // 移除 Tab
 tabManager?.removeCustomTab('node-detail-123');
 ```
@@ -104,9 +116,10 @@ tabManager?.removeCustomTab('node-detail-123');
 | --------------- | --------------------------- | ------------------------------------------------- |
 | tabs            | `ShallowRef<CustomTab[]>`   | 所有 Tab 列表（含默认的执行情况 Tab，保留隐藏项） |
 | displayTabs     | `ComputedRef<CustomTab[]>`  | Tab 栏实际展示列表：过滤 `visible === false`，按 `order` 升序稳定排序 |
-| selectedTab     | `Ref<CustomTab>`            | 当前选中的 Tab；选中项被隐藏时自动回退到首个可见 Tab |
-| isCollapse      | `ShallowRef<boolean>`       | 侧边栏折叠状态；`addCustomTab` 时自动设为 `false` |
-| addCustomTab    | `(tab: CustomTab) => void`  | 添加 Tab；同名 Tab 合并更新（可改 `order` / `visible` / `label`） |
+| selectedTab     | `Ref<CustomTab>`            | 当前选中的 Tab；未被主动切换过时跟随 Tab 栏首位，选中项被隐藏时自动回退到首个可见 Tab |
+| isCollapse      | `Ref<boolean>`              | 侧边栏折叠状态；传入 `collapsed` 时即该受控 ref（读写都作用于外部），否则为内部状态；`addCustomTab` 时自动设为 `false` |
+| addCustomTab    | `(tab: CustomTab) => void`  | 添加/合并 Tab，**展开侧栏并选中**目标 Tab |
+| ensureCustomTab | `(tab: CustomTab) => void`  | 添加/合并 Tab，**不展开、不主动切换选中**；用于常驻挂载（如文件产物） |
 | removeCustomTab | `(tabName: string) => void` | 移除指定 Tab                                      |
 | selectCustomTab | `(tab: CustomTab) => void`  | 切换到指定 Tab，触发 `onTabChange` 回调           |
 | resetCustomTab  | `() => void`                  | 重置为仅保留「执行情况」Tab、折叠侧栏并选中默认 Tab；`ChatContainer` 在卸载时调用，避免残留自定义 Tab |
@@ -136,7 +149,11 @@ interface CustomTab<T = Record<string, unknown>> {
 - 排序为稳定排序，`order` 相同的 Tab 保持插入先后顺序
 - 选中的 Tab 被配置隐藏时，内容不再渲染，自动切换到首个可见 Tab
 - `addCustomTab` 同时展开侧边栏（`isCollapse = false`）并在 `nextTick` 后自动选中目标 Tab；同名 Tab 合并更新
+- `ensureCustomTab` 与 `addCustomTab` 共用合并逻辑，但不改 `isCollapse`、自身不切换 `selectedTab`；适合「常驻挂载文件产物 Tab」等场景
+- 默认选中跟随 Tab 栏首位：只要没调用过 `selectCustomTab` / `addCustomTab`，挂上更靠前（`order` 更小）的 Tab 就会成为选中项，因此常驻的「文件产物」（`order: -1`）是侧栏默认面板；一旦主动切换过便不再跟随。`resetCustomTab` 会重置该标记
+- 折叠态支持受控：传入 `collapsed` 后 Provider 不再自持状态，内部展开动作直接写回该 ref，容器即可通过 `v-model` 把状态交给外部判断
 
 ## 关联组件
 
-- [ChatContainer](../components/setup/chat-container) — 侧栏 Tab 与自定义面板
+- [ChatContainer](../components/setup/chat-container) — 侧栏 Tab 与自定义面板
+- [useArtifactPreview](./use-artifact-preview) — 文件产物 Tab：初始化 `ensureCustomTab` 常驻挂载，点击卡片时 `addCustomTab`

package/dist/mcp/generated/docs/use-global-config.md

@@ -1,10 +1,11 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size 与 supportUpload； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。
+useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>、timezone?: ComputedRef<string | undefined>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size、supportUpload 与 timezone； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。
 
 ### 关联组件
 - **chat-container** — 根容器调用 useGlobalConfig 注入 supportUpload
+- **message-time** — 消息时间组件读取 timezone
 
 ---
 <!-- FULL DOC -->
@@ -13,7 +14,7 @@ useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、suppo
 
 > **分类**：composable
 
-在聊天容器根组件与子组件之间通过 Vue `provide` / `inject` 共享**全局展示相关配置**（当前包括字号主题档位 `size`、是否支持上传 `supportUpload`）。与 Teleport 插槽 ID 无关。
+在聊天容器根组件与子组件之间通过 Vue `provide` / `inject` 共享**全局展示相关配置**（当前包括字号主题档位 `size`、是否支持上传 `supportUpload`、消息时间时区 `timezone`）。与 Teleport 插槽 ID 无关。
 
 > 字号主题主要通过 `ChatContainer` 根节点的 `data-ai-size` 与 CSS 变量（`--ai-font-size` 等）生效；`GlobalConfig.size` 供后代在逻辑层读取当前档位，样式层无需逐组件传参。
 
@@ -25,10 +26,11 @@ ChatContainer（根）
   ├── useGlobalConfig({
   │     size: computed(() => props.size ?? 'small'),
   │     supportUpload: computed(() => props.supportUpload ?? false),
+  │     timezone: computed(() => props.timezone),
   │   })
-  │     └── provide(GLOBAL_CONFIG_TOKEN, { size, supportUpload })
+  │     └── provide(GLOBAL_CONFIG_TOKEN, { size, supportUpload, timezone })
   │
-  └── MessageContainer → … → UserMessage 等
+  └── MessageContainer → … → UserMessage / MessageTime 等
 
 UserMessage（后代）
   ├── injectGlobalConfig()
@@ -51,11 +53,14 @@ UserMessage（后代）
   const props = defineProps<{
     size?: 'normal' | 'small';
     supportUpload?: boolean;
+    timezone?: string;
   }>();
 
   useGlobalConfig({
     size: computed(() => props.size ?? 'small'),
     supportUpload: computed(() => props.supportUpload ?? false),
+    // 无默认值：未配置时由 MessageTime 回退到浏览器时区
+    timezone: computed(() => props.timezone),
   });
 </script>
 ```
@@ -88,11 +93,13 @@ export type AiSizeMode = 'normal' | 'small';
 export type GlobalConfig = {
   size?: ComputedRef<AiSizeMode>;
   supportUpload: ComputedRef<boolean>;
+  timezone?: ComputedRef<string | undefined>;
 };
 
 export function useGlobalConfig(options: GlobalConfig): {
   size?: ComputedRef<AiSizeMode>;
   supportUpload: ComputedRef<boolean>;
+  timezone?: ComputedRef<string | undefined>;
 };
 
 export function injectGlobalConfig(): GlobalConfig | undefined;
@@ -110,6 +117,7 @@ export function injectGlobalConfig(): GlobalConfig | undefined;
 | --------------- | ------------------------------------------------------------------------ |
 | `size`          | 可选。字号主题档位 `normal`（14px）/ `small`（12px），与 `ChatContainer.size` 对齐 |
 | `supportUpload` | 是否支持上传，与根容器 `ChatContainer` 的 `supportUpload` 等展示策略对齐 |
+| `timezone`      | 可选。消息时间展示所用的 IANA 时区名，与 `ChatContainer.timezone` 对齐；未配置时 `MessageTime` 按浏览器时区展示 |
 
 ### `useGlobalConfig(options)`
 
@@ -117,6 +125,7 @@ export function injectGlobalConfig(): GlobalConfig | undefined;
 | ----------------------- | ------------------------------------------------------------------------------------- |
 | `options.size`          | 可选。字号主题档位，建议使用 `computed(() => props.size ?? 'small')` 与根 props 同步 |
 | `options.supportUpload` | 是否支持上传，建议使用 `computed(() => props.supportUpload ?? false)` 与根 props 同步 |
+| `options.timezone`      | 可选。消息时间时区，建议使用 `computed(() => props.timezone)` 与根 props 同步；不设默认值，交由 `MessageTime` 回退浏览器时区 |
 
 - 调用后立即 `provide(GLOBAL_CONFIG_TOKEN, options)`。
 - 必须在具有组件实例上下文的 `setup` 中调用（与 Vue `provide` 要求一致）。
@@ -136,5 +145,6 @@ export function injectGlobalConfig(): GlobalConfig | undefined;
 
 ## 关联组件
 
-- [ChatContainer](../components/setup/chat-container) — 调用 `useGlobalConfig` 注入 `size` 与 `supportUpload`
+- [ChatContainer](../components/setup/chat-container) — 调用 `useGlobalConfig` 注入 `size`、`supportUpload` 与 `timezone`
+- [MessageTime](../components/feedback/message-time) — 读取 `timezone` 展示消息时间
 - [主题配置](../theme/theme) — `data-ai-size` 与 CSS 变量说明

package/dist/mcp/generated/docs/use-message-group.md

@@ -71,15 +71,18 @@ role=user  role=tool     其他 role
 `role: 'tool'` 消息不会独立渲染，而是通过 `toolCallId` 注入到对应 AssistantMessage 的 `toolCall.toolMessage` 字段：
 
 ```typescript
-const toolMessage = messages.find(
+const assistantToolMessage = messages.find(
   m => m.role === 'assistant' && m.toolCalls?.some(t => t.id === message.toolCallId),
-);
-if (toolMessage) {
-  const toolCall = toolMessage.toolCalls?.find(t => t.id === message.toolCallId);
+) as AssistantMessage | undefined;
+if (assistantToolMessage) {
+  const toolCall = assistantToolMessage.toolCalls?.find(t => t.id === message.toolCallId);
   if (toolCall) {
     toolCall.toolMessage = message;
   }
-  // 同步 assistant 状态（错误等）
+  // error 时强制 assistant 为 Error；否则保留原 status，空值兜底 Complete
+  assistantToolMessage.status = message.error
+    ? MessageStatus.Error
+    : assistantToolMessage.status || MessageStatus.Complete;
 }
 ```
 
@@ -119,24 +122,29 @@ const isExecutionMessage = (m: Message): boolean => {
 
 ## sessionArtifacts 会话级文件产物
 
-`sessionArtifacts` 拍平当前会话所有 `AssistantMessage.property.artifacts`，供 `ChatContainer` 侧栏「文件产物」Tab 聚合预览。由于同一会话可能出现「多个 AssistantMessage + 同名文件」，文件名不可作为唯一键，统一用 `messageUid`（回退 `String(id)`）+ 消息内下标 + `outputId` 通过 [`buildArtifactId`](./use-artifact-preview) 生成全局唯一 `artifactId`：
+`sessionArtifacts` 拍平当前会话所有 `AssistantMessage.property.artifacts`，供 `ChatContainer` 侧栏「文件产物」Tab 聚合预览。以 **`outputId`** 为会话内唯一键去重（同 `outputId` 视为同一文件），保留最后一次出现的文件信息，列表顺序与「最后一次出现」的相对顺序一致：
 
 ```typescript
 const sessionArtifacts = computed(() => {
-  const list = [];
+  // delete + set：同 key 覆盖内容，并把该项挪到 Map 末尾，保证「最后出现」顺序
+  const byOutputId = new Map();
   for (const message of messages.value) {
     if (message.role !== MessageRole.Assistant) continue;
     const artifacts = message.property?.artifacts;
     if (!artifacts?.length) continue;
-    const messageUid = message.uid ?? String(message.id);
-    artifacts.forEach((file, index) => {
-      list.push({ ...file, artifactId: buildArtifactId(messageUid, index, file.outputId), messageUid });
-    });
+    for (const file of artifacts) {
+      if (byOutputId.has(file.outputId)) {
+        byOutputId.delete(file.outputId);
+      }
+      byOutputId.set(file.outputId, file);
+    }
   }
-  return list;
+  return Array.from(byOutputId.values());
 });
 ```
 
+> `SessionArtifact` 即为 `AIFileInfo` 别名；文件名可能重复，不可作唯一键。
+
 预览命中与取链见 [useArtifactPreview](./use-artifact-preview)；侧栏列表与分类型预览（`ArtifactPreviewHost`）见 [FileArtifactPanel](../components/message/file-artifact-panel)。
 
 ## 待审批统计
@@ -209,7 +217,7 @@ const {
 | ---------------- | ----------------------------- | --------------------------------------------------------------------------- |
 | messageGroups    | `Ref<MessageGroup[]>`         | 完整消息分组列表                                                            |
 | executionGroups  | `ComputedRef<MessageGroup[]>` | 仅包含执行类消息的分组（工具调用 + FlowAgent），自动提取 `userMessageTitle` |
-| sessionArtifacts | `ComputedRef<SessionArtifact[]>` | 拍平会话所有 AssistantMessage 文件产物，含全局唯一 `artifactId`         |
+| sessionArtifacts | `ComputedRef<SessionArtifact[]>` | 拍平会话所有 AssistantMessage 文件产物，按 `outputId` 去重（保留最后一次） |
 | pendingApprovalCount | `ComputedRef<number>`      | 当前消息中待审批 AI Dev 审批中断的数量                                      |
 | pendingApprovalTipText | `ComputedRef<string>`    | 待审批阻塞发送提示文案；无待审批时为空字符串                                |
 | isShareMode      | `ShallowRef<boolean>`         | 是否处于分享模式                                                            |

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

@@ -6,6 +6,7 @@
 ### 关联组件
 - **message-render** — 由 MessageRender 在 role 为 user 时创建
 - **message-tools** — 消息工具栏交互与状态由 MessageTools 体系承载
+- **message-time** — createdAt 经工具栏 prepend 插槽展示
 - **message-container** — 嵌入列表时由 MessageContainer 管理分组与多选
 - **chat-input** — 编辑态普通消息使用 ChatInput
 
@@ -47,8 +48,11 @@
       v-if: messageToolsStatus !== 'hidden'
       visibility: hidden（默认）→ visible（:hover 时）
       tools: [copy, cite, edit, delete]，updateTools: []
+      #prepend slot → MessageTime（createdAt，工具图标左侧）
 ```
 
+> **时间随工具栏显隐**：时间位于工具栏内，与工具按钮共用 `visibility` 控制，因此同样在悬停消息时才可见。
+
 **编辑模式**（点击 `edit` 按钮后 `isEdit=true`）
 
 ```
@@ -356,6 +360,7 @@ binaryFiles 有值 → 进入编辑模式（editContent 可为空）
 | 属性名             | 类型                                                                                       | 说明                                                                      |
 | ------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
 | content            | `string \| InputContent[]`                                                                 | 消息内容，字符串或含 text/binary 的数组                                   |
+| createdAt          | `number \| string`                                                                         | 消息创建时间，经 `MessageTools` 的 `#prepend` 插槽交给 `MessageTime` 渲染在工具图标左侧；无值时不展示 |
 | property           | `{ extra?: MessageExtra; artifacts?: AIFileInfo[] }`                                       | 附加属性；本组件消费 `extra.cite` / `shortcut` / `context`                |
 | messageToolsStatus | `MessageToolsStatus`                                                                       | 工具按钮状态，`disabled` 禁用、`hidden` 从 DOM 移除                       |
 | onAction           | `MessageToolsProps['onAction']`                                                            | 工具回调；`copy`/`edit` 有内置行为，`cite`/`delete` 需外部处理            |
@@ -417,4 +422,5 @@ type MessageExtra = {
 
 - [MessageRender](/components/message/message-render) — user 角色由其实例化
 - [MessageTools](/components/feedback/message-tools) — 工具栏交互
+- [MessageTime](/components/feedback/message-time) — 工具栏左侧的消息时间
 - [MessageContainer](/components/setup/message-container) — 列表与多选容器

package/dist/mcp/generated/docs/user-question-card.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。
+渲染 UserQuestion 中断的待回答面板：一次只展示一题，标题栏提供题号切换， Footer 展示已完成进度；支持单选自动跳下一题、多选/Others、完成与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。
 
 ### 关联组件
 - **interrupt-message** — outcome.success 时挂载 UserQuestionAnsweredCard 回显回答
@@ -16,7 +16,7 @@
 
 - **源码位置**：`src/components/chat-message/interrupt-message/user-question/user-question-card.vue`
 - **能力域**：Agent 能力
-- **能力说明**：渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。
+- **能力说明**：渲染 UserQuestion 中断的待回答面板；一次一题分页切换，支持单选/多选、Others、跳过与已完成进度。
 
 > **能力域**：Agent 能力
 
@@ -24,6 +24,9 @@
 
 ## 交互能力
 
+- **一次一题**：正文只展示当前题；标题栏右侧提供 `< 当前题 / 总题数 >` 切换定位（单题为 `1 / 1`），首末题对应箭头禁用。
+- **自动跳转**：单选预设选项从未答变为有效答时，自动跳到下一题（最后一题停留）；多选与 Others 不自动跳，靠箭头切换。
+- **已完成进度**：Footer 左侧展示「已完成 N 题」；右侧为「跳过」+「完成」。
 - **单选 / 多选**：每道题通过 `multiSelect` 控制选择行为；未传时不展示单选/多选标签，默认仍按单选处理。
 - **Others 自由输入**：默认 [UserQuestionChoice](/components/agent/user-question-choice) 为每道题追加 `label: 'others'` 输入项，输入文本写入 `answer[].description`。
 - **自定义作答形态**：通过 `#question` slot 可替换默认选择题，渲染任意表单；作答有效时调用 `setAnswer` 回传 `UserQuestionAnswerItem`，无效时传 `undefined`。
@@ -142,7 +145,7 @@ const payload = {
 />
 ```
 
-- 卡片内「完成 / 跳过」→ `onInterruptResume(payload, interrupt)`
+- 卡片内「跳过 / 完成」→ `onInterruptResume(payload, interrupt)`（Footer 右置，跳过在前、完成在后）
 - 输入框直接发送 → `onSendMessage(content, docSchema, { interrupt, payload })`，其中 `payload` 由 `buildSkipResumePayload(interrupt)` 生成（`status: 'cancelled'`）
 
 ## 工具函数 buildSkipResumePayload

package/dist/mcp/generated/index.json

@@ -1,6 +1,6 @@
 {
   "version": "2.0.0",
-  "generatedAt": "2026-07-29T07:29:01.699Z",
+  "generatedAt": "2026-08-18T06:27:42.645Z",
   "domains": {
     "setup": {
       "label": "对话搭建",
@@ -83,6 +83,7 @@
       "label": "工具与反馈",
       "components": [
         "delete-tool",
+        "message-time",
         "message-tools",
         "scroll-btn",
         "tool-btn",
@@ -98,6 +99,7 @@
       "components": [
         "activity-layout",
         "ai-loading",
+        "file-icon",
         "highlight-keyword",
         "message-loading",
         "questions-container",
@@ -362,8 +364,8 @@
       "name": "UserQuestionCard 用户问题中断",
       "slug": "user-question-card",
       "kind": "component",
-      "description": "渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。",
-      "aiSummary": "渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。",
+      "description": "渲染 UserQuestion 中断的待回答面板；一次一题分页切换，支持单选/多选、Others、跳过与已完成进度。",
+      "aiSummary": "渲染 UserQuestion 中断的待回答面板：一次只展示一题，标题栏提供题号切换， Footer 展示已完成进度；支持单选自动跳下一题、多选/Others、完成与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。",
       "relatedComponents": [
         {
           "slug": "interrupt-message",
@@ -433,12 +435,35 @@
       "docFile": "docs/delete-tool.md",
       "domain": "feedback"
     },
+    {
+      "name": "MessageTime 消息时间",
+      "slug": "message-time",
+      "kind": "component",
+      "description": "按「今天 / 昨天 / 今年内 / 跨年」四档格式展示消息创建时间。",
+      "aiSummary": "按 createdAt 展示消息时间，四档格式：今天 `12:00`、昨天 `昨天 12:00`、今年内更早 `3-12 12:00`、非今年 `2025-3-12 12:00`； 时区取 props.timezone，未传时回退 injectGlobalConfig().timezone（由 ChatContainer 的 timezone prop 注入），都没有则用浏览器时区； 无值或非法时间不渲染任何 DOM。通常通过 MessageTools 的 prepend / append 插槽使用。 源码位置：src/components/message-tools/message-time/message-time.vue。",
+      "relatedComponents": [
+        {
+          "slug": "message-tools",
+          "relation": "通过 prepend / append 插槽嵌入工具栏"
+        },
+        {
+          "slug": "user-message",
+          "relation": "用户消息在工具栏左侧展示时间"
+        },
+        {
+          "slug": "message-container",
+          "relation": "AI 消息组在工具栏右侧展示本轮回答时间"
+        }
+      ],
+      "docFile": "docs/message-time.md",
+      "domain": "feedback"
+    },
     {
       "name": "MessageTools 消息工具栏",
       "slug": "message-tools",
       "kind": "component",
       "description": "消息悬浮工具栏，组合复制、删除、反馈等工具按钮。",
-      "aiSummary": "消息悬浮工具栏，组合复制、删除、反馈等工具按钮。 源码位置：src/components/message-tools/message-tools.vue。",
+      "aiSummary": "消息悬浮工具栏，组合复制、删除、反馈等工具按钮；提供 prepend / append 两端插槽承载消息时间等附加内容。 源码位置：src/components/message-tools/message-tools.vue。",
       "relatedComponents": [
         {
           "slug": "tool-btn",
@@ -451,6 +476,10 @@
         {
           "slug": "delete-tool",
           "relation": "id 为 delete 时替换为带确认的删除按钮"
+        },
+        {
+          "slug": "message-time",
+          "relation": "通过 prepend / append 插槽嵌入消息时间"
         }
       ],
       "docFile": "docs/message-tools.md",
@@ -555,6 +584,25 @@
       "docFile": "docs/ai-loading.md",
       "domain": "helper"
     },
+    {
+      "name": "FileIcon 文件类型图标",
+      "slug": "file-icon",
+      "kind": "component",
+      "description": "按文件扩展名渲染对应类型图标，尺寸随外层 font-size 自适应。",
+      "aiSummary": "按扩展名渲染文件类型图标：内联 svg，尺寸用 1em 跟随外层 font-size； 扩展名解析走 normalizeFileExtension（优先 fileType，缺省回退 fileName，大小写不敏感， 支持 Dockerfile / .gitignore 这类无扩展名或点号开头的文件）；未登记类型返回 unknown 兜底图标。 源码位置：src/components/file-icon/file-icon.vue，图标注册表在 src/icons/file-icons.ts。",
+      "relatedComponents": [
+        {
+          "slug": "file-artifact-panel",
+          "relation": "文件产物列表与预览头使用该组件展示类型图标"
+        },
+        {
+          "slug": "assistant-message",
+          "relation": "消息内的文件产物卡片使用该组件"
+        }
+      ],
+      "docFile": "docs/file-icon.md",
+      "domain": "helper"
+    },
     {
       "name": "HighlightKeyword 关键词高亮",
       "slug": "highlight-keyword",
@@ -1115,7 +1163,7 @@
       "slug": "file-artifact-panel",
       "kind": "component",
       "description": "汇总当前会话全部文件产物，支持搜索、选中与分类型预览，挂载在 ChatContainer 侧栏「文件产物」Tab。",
-      "aiSummary": "汇总当前会话所有 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。",
+      "aiSummary": "汇总当前会话所有 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。",
       "relatedComponents": [
         {
           "slug": "assistant-message",
@@ -1267,6 +1315,10 @@
           "slug": "message-tools",
           "relation": "消息工具栏交互与状态由 MessageTools 体系承载"
         },
+        {
+          "slug": "message-time",
+          "relation": "createdAt 经工具栏 prepend 插槽展示"
+        },
         {
           "slug": "message-container",
           "relation": "嵌入列表时由 MessageContainer 管理分组与多选"
@@ -1504,7 +1556,7 @@
       "slug": "chat-container",
       "kind": "component",
       "description": "完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。",
-      "aiSummary": "完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。 透传 models / selectedModel；支持 welcomeTitle 与 #welcome。 源码位置：src/components/chat-container/chat-container.vue。",
+      "aiSummary": "完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。 透传 models / selectedModel；支持 welcomeTitle 与 #welcome。 侧栏展开/折叠由外部 v-model:asideCollapsed 严格受控（传入后以外部值为准，内部展开动作仅发 update 事件），不再依赖执行数据或文件产物有无；无数据时侧栏照常展开并展示空态。 侧栏固定从右侧展开（无 placement prop），且不再内置折叠按钮。 「文件产物」Tab 常驻挂载。 源码位置：src/components/chat-container/chat-container.vue。",
       "relatedComponents": [
         {
           "slug": "message-container",
@@ -1586,7 +1638,7 @@
       "slug": "use-artifact-preview",
       "kind": "composable",
       "description": "Provider/Consumer 模式的文件产物预览状态管理，用于 ChatContainer 侧栏「文件产物」Tab 的命中与切换。 Provider 在 ChatContainer 中创建，Consumer 在深层文件卡片中注入使用。",
-      "aiSummary": "useArtifactPreviewProvider 维护 activeArtifactId，openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（按 outputId 缓存 download_url / preview_url）； useArtifactPreviewConsumer 在后代注入同一套 API。buildArtifactId 用 messageUid#index#outputId 生成唯一 id。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。",
+      "aiSummary": "useArtifactPreviewProvider 维护 activeArtifactId（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（每次重新取链，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。",
       "relatedComponents": [
         {
           "slug": "chat-container",
@@ -1644,7 +1696,7 @@
       "slug": "use-container-scroll",
       "kind": "composable",
       "description": "为消息容器提供滚动控制的组合式函数对，通过 **Provider/Consumer** 模式在父子组件间共享滚动状态。",
-      "aiSummary": "useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。",
+      "aiSummary": "useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、jumpToBottom、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 toScrollBottom 缺省按距底部距离自动选择行为：超过 INSTANT_SCROLL_DISTANCE（600px）时瞬时贴底，否则平滑滚动，避免切换会话时出现长距离平滑滚动动画。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。",
       "relatedComponents": [
         {
           "slug": "message-container",
@@ -1666,7 +1718,7 @@
       "slug": "use-custom-tab",
       "kind": "composable",
       "description": "Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边栏的 Tab 动态管理。Provider 在 `ChatContainer` 中创建，Consumer 在任意后代组件中注入使用。",
-      "aiSummary": "useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。",
+      "aiSummary": "useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据、可选 collapsed 注入受控折叠态 ref。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不主动切换选中；addCustomTab 会展开并选中。 未被主动切换过时，选中态默认跟随 Tab 栏首位（order 最小），如常驻的「文件产物」。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。",
       "relatedComponents": [
         {
           "slug": "chat-container",
@@ -1711,12 +1763,16 @@
       "name": "useGlobalConfig",
       "slug": "use-global-config",
       "kind": "composable",
-      "description": "在聊天根容器与子组件之间通过 provide/inject 共享全局展示配置（字号主题档位、是否支持上传等）。",
-      "aiSummary": "useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size 与 supportUpload； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。",
+      "description": "在聊天根容器与子组件之间通过 provide/inject 共享全局展示配置（字号主题档位、是否支持上传、消息时间时区等）。",
+      "aiSummary": "useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>、timezone?: ComputedRef<string | undefined>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size、supportUpload 与 timezone； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。",
       "relatedComponents": [
         {
           "slug": "chat-container",
           "relation": "根容器调用 useGlobalConfig 注入 supportUpload"
+        },
+        {
+          "slug": "message-time",
+          "relation": "消息时间组件读取 timezone"
         }
       ],
       "docFile": "docs/use-global-config.md"
@@ -1787,7 +1843,7 @@
       "slug": "constants",
       "kind": "type",
       "description": "`@blueking/chat-x` 导出的常量和枚举类型。",
-      "aiSummary": "汇总 MessageRole、MessageStatus（含 Fetching 请求中）、MessageContentType、MessageToolsStatus、MessageState、Z-Index 与 CONST_MESSAGE_TOOLS 等导出常量。 用于构造消息、配置 MessageContainer 工具栏与输入态，以及层级与默认快捷指令。与类型 messages 配套使用。",
+      "aiSummary": "汇总 MessageRole、MessageStatus（含 Fetching 请求中、Complete/Completed 完成态兼容）、MessageContentType、MessageToolsStatus、MessageState、Z-Index 与 CONST_MESSAGE_TOOLS 等导出常量。 用于构造消息、配置 MessageContainer 工具栏与输入态，以及层级与默认快捷指令。与类型 messages 配套使用。",
       "relatedComponents": [
         {
           "slug": "message-tools",

package/dist/utils/file-type.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 文件分类：图标兜底与预览渲染策略的共同依据。
+ * - code：可交给 highlight.js 渲染的源码 / 配置文件
+ * - text：纯文本，直接按原文展示
+ * - binary：无法在前端直接解析，统一交由后端 preview_url 预览
+ */
+export type AIFileKind = 'binary' | 'code' | 'html' | 'image' | 'markdown' | 'text';
+/**
+ * 归一化文件类型标识：优先取后台下发的 type，缺省时回退文件名。
+ * 统一转小写并截取最后一段扩展名；无扩展名的文件（Dockerfile / Makefile）直接返回文件名本身。
+ */
+export declare const normalizeFileExtension: (type?: string, name?: string) => string;
+/** 解析文件分类；未登记的扩展名按 binary 兜底 */
+export declare const resolveFileKind: (type?: string, name?: string) => AIFileKind;

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './file';
+export * from './file-type';
 export * from './markdown-completer';
 export { completeMarkdownSyntax } from './stream-markdown-completer';
 export * from './utils';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/chat-x",
-  "version": "0.0.49-beta.1",
+  "version": "0.0.49-beta.10",
   "description": "蓝鲸智云 AI Chat 组件库 —— 遵循 AG-UI，为 AI Agent 和人类开发者共同设计的对话 UI 组件库。",
   "main": "index.js",
   "bin": {
@@ -79,7 +79,7 @@
     "vitepress": "2.0.0-alpha.16",
     "vitest": "^4.0.18",
     "vue-tsc": "^3.1.4",
-    "@blueking/chat-helper": "0.0.12-beta.11"
+    "@blueking/chat-helper": "0.0.12-beta.21"
   },
   "scripts": {
     "dev": "vite --config vite.config.ts",

package/dist/components/chat-message/assistant-message/message-artifacts/file-icon.d.ts

@@ -1,29 +0,0 @@
-import { AIFileType } from '../../../../ag-ui/types/file';
-/** 文件类型 → 图标映射；未命中类型兜底用文本图标 */
-export declare const FILE_ICON_MAP: {
-    readonly html: import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
-        [key: string]: any;
-    }>;
-    readonly jpg: import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
-        [key: string]: any;
-    }>;
-    readonly json: import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
-        [key: string]: any;
-    }>;
-    readonly md: import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
-        [key: string]: any;
-    }>;
-    readonly markdown: import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
-        [key: string]: any;
-    }>;
-    readonly pdf: import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
-        [key: string]: any;
-    }>;
-    readonly txt: import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
-        [key: string]: any;
-    }>;
-};
-/** 图标为共享 VNode，克隆后再渲染，避免同类型多处复用同一实例 */
-export declare const getFileIcon: (type: AIFileType) => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
-    [key: string]: any;
-}>;