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

package/dist/mcp/generated/docs/use-artifact-preview.md

@@ -0,0 +1,234 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useArtifactPreviewProvider 维护 activeArtifactId（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（每次重新取链，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。
+
+### 关联组件
+- **chat-container** — Provider 主场景，聚合 sessionArtifacts 并挂载 FileArtifactPanel
+- **file-artifact-panel** — 侧栏面板消费 activeArtifactId 与 setActiveArtifactId；预览加载在面板内 Host
+- **assistant-message** — 文件产物来源 property.artifacts
+
+---
+<!-- FULL DOC -->
+
+# useArtifactPreview 文件产物预览
+
+> **分类**：composable
+
+Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatContainer` 中创建，负责维护当前命中的文件 `outputId`；Consumer 在深层 `ArtifactFileCard` 中注入，用于点击卡片触发预览。
+
+**职责边界**：
+
+- **本 composable**：维护「命中文件」与「URL 解析」（每次重新取链 + 并发去重）；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
+- **不在本 composable**：聚合会话文件列表、渲染预览面板、按类型 fetch 正文 / iframe 展示 —— 分别由 `useMessageGroup.sessionArtifacts`、`FileArtifactPanel`、内部 `ArtifactPreviewHost` + `useArtifactPreviewLoader` 承担（预览重载键为 `outputId:type`）
+
+## 函数签名
+
+### useArtifactPreviewProvider
+
+```typescript
+function useArtifactPreviewProvider(options: {
+  /** 读取业务侧异步取链回调（getter 保持对 props 变更敏感） */
+  getOnArtifactClick?: () => OnArtifactClick | undefined;
+  /** 命中文件后触发：由容器负责 addCustomTab + 展开侧栏 + 选中 Tab */
+  onOpen: (outputId: string) => void;
+}): {
+  activeArtifactId: ShallowRef<string>;
+  canResolveArtifactUrl: ComputedRef<boolean>;
+  openPreview: (payload: OpenArtifactPreviewPayload) => void;
+  resolveArtifactUrls: (file: AIFileInfo) => Promise<ArtifactUrlResult>;
+  setActiveArtifactId: (id: string) => void;
+};
+```
+
+### useArtifactPreviewConsumer
+
+```typescript
+function useArtifactPreviewConsumer():
+  | undefined
+  | {
+      activeArtifactId: Ref<string>;
+      canResolveArtifactUrl: ComputedRef<boolean>;
+      openPreview: (payload: OpenArtifactPreviewPayload) => void;
+      resolveArtifactUrls: (file: AIFileInfo) => Promise<ArtifactUrlResult>;
+      setActiveArtifactId: (id: string) => void;
+    };
+```
+
+## 使用示例
+
+### Provider（ChatContainer）
+
+会话级文件产物由 [`useMessageGroup`](./use-message-group) 统一聚合（`sessionArtifacts`），Provider 只负责命中与打开侧栏 Tab：
+
+```typescript
+import {
+  useArtifactPreviewProvider,
+  useCustomTabProvider,
+  useMessageGroup,
+  FILE_ARTIFACT_TAB_NAME,
+} from '@blueking/chat-x';
+import { t } from '@blueking/chat-x/lang';
+
+const { addCustomTab, ensureCustomTab, removeCustomTab } = useCustomTabProvider({ /* ... */ });
+
+// 会话级文件产物聚合已内聚在 useMessageGroup，直接消费
+const { sessionArtifacts } = useMessageGroup({ keyword, messages, selectedUserMessages });
+
+const FILE_ARTIFACT_TAB = {
+  closable: false,
+  label: t('文件产物'),
+  name: FILE_ARTIFACT_TAB_NAME,
+  order: -1,
+};
+
+// 常驻挂载：不随产物有无增删，无产物时由面板展示空态
+ensureCustomTab(FILE_ARTIFACT_TAB);
+
+const { activeArtifactId, setActiveArtifactId } = useArtifactPreviewProvider({
+  getOnArtifactClick: () => props.onArtifactClick,
+  // 点击文件卡片：展开侧栏并选中「文件产物」Tab
+  onOpen: () => {
+    addCustomTab(FILE_ARTIFACT_TAB);
+  },
+});
+
+// 仅维护命中态：无产物清空，命中项失效时回落到第一个
+watch(sessionArtifacts, list => {
+  if (!list.length) {
+    setActiveArtifactId('');
+    return;
+  }
+  if (!list.some(item => item.outputId === activeArtifactId.value)) {
+    setActiveArtifactId(list[0].outputId);
+  }
+}, { immediate: true });
+```
+
+### Consumer（ArtifactFileCard）
+
+```typescript
+import { useArtifactPreviewConsumer } from '@blueking/chat-x';
+
+const artifactPreview = useArtifactPreviewConsumer();
+
+// 有 Provider 时卡片可点击；无 Provider 时返回 undefined，卡片不可点击
+const clickable = computed(() => !!props.onPreview || !!artifactPreview);
+
+const handleCardClick = () => {
+  if (props.onPreview) {
+    props.onPreview(props.file);
+    return;
+  }
+  artifactPreview?.openPreview({ file: props.file });
+};
+```
+
+### 侧栏列表内切换命中文件
+
+```typescript
+// FileArtifactPanel 列表点击 → emit select(outputId) → 容器调用 setActiveArtifactId
+// 右侧预览由面板内 ArtifactPreviewHost 消费 activeArtifact，自行取链并按类型渲染
+<FileArtifactPanel
+  :active-id="activeArtifactId"
+  :artifacts="sessionArtifacts"
+  @select="setActiveArtifactId"
+/>
+```
+
+### 业务侧取链（ChatContainer `onArtifactClick`）
+
+文本类预览需要可 `fetch` 的 `download_url`；iframe 类需要 `preview_url`（一般为后台转好的 PDF）：
+
+```typescript
+const onArtifactClick = async (file: AIFileInfo) => {
+  const res = await api.getArtifactUrls(file.outputId);
+  return {
+    download_url: res.download_url,
+    preview_url: res.preview_url,
+  };
+};
+```
+
+## 内置常量
+
+| 常量名                    | 值                 | 说明                                      |
+| ------------------------- | ------------------ | ----------------------------------------- |
+| `FILE_ARTIFACT_TAB_NAME`  | `'file-artifact'`  | 「文件产物」侧栏 Tab 的固定标识，不可关闭 |
+| `ARTIFACT_PREVIEW_TOKEN`  | `Symbol`           | provide/inject 注入 Token                 |
+
+## 返回值说明
+
+| 属性/方法名         | 类型                                      | 说明                                                                 |
+| ------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
+| activeArtifactId    | `ShallowRef<string>`                      | 当前命中的文件 `outputId`                                            |
+| canResolveArtifactUrl | `ComputedRef<boolean>`                  | 是否具备异步取链能力（有 `onArtifactClick` 时为 true，下载按钮据此显隐） |
+| openPreview         | `(payload: OpenArtifactPreviewPayload) => void` | 由文件卡片触发：以 `file.outputId` 更新命中态、调用 `onOpen`   |
+| resolveArtifactUrls | `(file: AIFileInfo) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 取链；每次重新获取，不缓存；同文件并发去重 |
+| setActiveArtifactId | `(id: string) => void`                    | 直接设置命中文件 `outputId`；侧栏列表内切换选中时使用                |
+
+## 类型定义
+
+```typescript
+import type { AIFileInfo, ArtifactUrlResult, OnArtifactClick } from '@blueking/chat-x';
+
+/** 打开预览时的入参 */
+type OpenArtifactPreviewPayload = {
+  file: AIFileInfo;
+};
+
+/**
+ * 会话级文件产物：以 outputId 为会话内唯一键（同 outputId 视为同一文件）。
+ * 拍平去重后即为 AIFileInfo，此处用别名标明语义。
+ */
+type SessionArtifact = AIFileInfo;
+
+/** onArtifactClick 返回值（snake_case） */
+type ArtifactUrlResult = {
+  download_url?: string;
+  preview_url?: string;
+};
+```
+
+## 唯一键规则
+
+会话内以 **`outputId`** 作为文件产物唯一键：
+
+- 同一 `outputId` 在多条 `AssistantMessage` 中出现时，`sessionArtifacts` 去重并保留**最后一次**出现的文件信息
+- `activeArtifactId`、列表 `:key`、`select` 事件参数均使用 `outputId`
+- 文件名可能重复，**不可**作为唯一键
+
+## 完整触发链路
+
+```
+ArtifactFileCard（点击）
+  └─ useArtifactPreviewConsumer().openPreview({ file })
+       └─ useArtifactPreviewProvider（ChatContainer）
+            ├─ activeArtifactId = file.outputId
+            └─ onOpen(outputId) → addCustomTab(FILE_ARTIFACT_TAB_NAME) 展开并选中
+                 └─ FileArtifactPanel（列表 + 下载头，@select → setActiveArtifactId）
+                      └─ ArtifactPreviewHost（loader + 分类型 renderer）
+
+容器初始化
+  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 常驻挂上（不展开侧栏）；因 order:-1 排在首位，
+     未主动切换过 Tab 时会成为默认选中面板；无产物时由面板展示整块空态
+
+sessionArtifacts 变化
+  └─ 仅维护命中态（无产物清空，命中项失效回落第一个）；不增删 Tab
+```
+
+分类型预览策略见 [FileArtifactPanel 预览机制](../components/message/file-artifact-panel#预览机制)。
+
+## 设计特点
+
+- **职责单一**：composable 不直接调用 `useCustomTab`，侧栏 Tab 打开逻辑由 `onOpen` 注入；也不做正文 fetch / iframe 渲染
+- **ShallowRef 优先**：`activeArtifactId` 使用 `shallowRef`，避免不必要的深层响应式开销
+- **Consumer 兜底**：`useArtifactPreviewConsumer` 无 Provider 时返回 `undefined`，文件卡片在无容器上下文时自动不可点击
+- **与 useCustomTab 协作**：点击卡片走 `addCustomTab`（展开 + 选中）；容器初始化时走 `ensureCustomTab` 常驻挂载（不展开；因 `order: -1` 在未主动切换前会成为默认选中），无产物也不移除，由面板展示空态
+
+## 关联组件
+
+- [ChatContainer](../components/setup/chat-container) — Provider 主场景，内置「文件产物」Tab
+- [FileArtifactPanel](../components/message/file-artifact-panel) — 侧栏列表与预览 Host 挂载
+- [AssistantMessage](../components/message/assistant-message) — 文件产物来源（`property.artifacts`）
+- [useCustomTab](./use-custom-tab) — `addCustomTab` / `ensureCustomTab` 分工

package/dist/mcp/generated/docs/use-container-scroll.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。
+useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、jumpToBottom、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 toScrollBottom 缺省按距底部距离自动选择行为：超过 INSTANT_SCROLL_DISTANCE（600px）时瞬时贴底，否则平滑滚动，避免切换会话时出现长距离平滑滚动动画。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。
 
 ### 关联组件
 - **message-container** — Provider 挂载于消息列表滚动区域
@@ -35,7 +35,10 @@ useContainerScrollProvider(containerRef, bottomRef)
   ├── wheel 事件（passive）→ deltaY < 0 时 autoScrollEnabled=false
   │     （用户向上滚动时暂停自动滚动）
   │
-  ├── toScrollBottom() → autoScrollEnabled=true + bottomRef.scrollIntoView('smooth')
+  ├── jumpToBottom()   → autoScrollEnabled=true + container.scrollTop = scrollHeight（瞬时）
+  ├── toScrollBottom(behavior?) → autoScrollEnabled=true；
+  │     behavior 缺省时：距底部 > INSTANT_SCROLL_DISTANCE(600) → jumpToBottom()
+  │     否则 / 显式 'smooth' → bottomRef.scrollIntoView({ behavior:'smooth', block:'end' })
   ├── toScrollTop()    → containerRef.scrollTo({ top:0, behavior:'smooth' })
   │
   └── provide(CONTAINER_SCROLL_TOKEN, computed(() => ({
@@ -43,6 +46,7 @@ useContainerScrollProvider(containerRef, bottomRef)
             isScrollBottom,             // ShallowRef<boolean>（保持响应式）
             scrollBottomHeight,         // ShallowRef<number>（保持响应式）
             debouncedShowScrollBottomBtn, // customRef，防抖显示返回底部按钮
+            jumpToBottom,
             toScrollBottom,
             toScrollTop,
         })))

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

@@ -28,6 +28,7 @@ function useMessageGroup(options: {
 }): {
   messageGroups: Ref<MessageGroup[]>;
   executionGroups: ComputedRef<MessageGroup[]>;
+  sessionArtifacts: ComputedRef<SessionArtifact[]>;
   pendingApprovalCount: ComputedRef<number>;
   pendingApprovalTipText: ComputedRef<string>;
   isShareMode: ShallowRef<boolean>;
@@ -70,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;
 }
 ```
 
@@ -116,6 +120,33 @@ const isExecutionMessage = (m: Message): boolean => {
 | toolCall   | `function.name`、`mcpName`、`description`、`arguments`、`id` |
 | flow_agent | 各任务 `task_name`、各节点 `name`                             |
 
+## sessionArtifacts 会话级文件产物
+
+`sessionArtifacts` 拍平当前会话所有 `AssistantMessage.property.artifacts`，供 `ChatContainer` 侧栏「文件产物」Tab 聚合预览。以 **`outputId`** 为会话内唯一键去重（同 `outputId` 视为同一文件），保留最后一次出现的文件信息，列表顺序与「最后一次出现」的相对顺序一致：
+
+```typescript
+const sessionArtifacts = computed(() => {
+  // 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;
+    for (const file of artifacts) {
+      if (byOutputId.has(file.outputId)) {
+        byOutputId.delete(file.outputId);
+      }
+      byOutputId.set(file.outputId, file);
+    }
+  }
+  return Array.from(byOutputId.values());
+});
+```
+
+> `SessionArtifact` 即为 `AIFileInfo` 别名；文件名可能重复，不可作唯一键。
+
+预览命中与取链见 [useArtifactPreview](./use-artifact-preview)；侧栏列表与分类型预览（`ArtifactPreviewHost`）见 [FileArtifactPanel](../components/message/file-artifact-panel)。
+
 ## 待审批统计
 
 `useMessageGroup` 会统计消息列表中处于待审批状态的 AI Dev 审批中断：
@@ -186,6 +217,7 @@ const {
 | ---------------- | ----------------------------- | --------------------------------------------------------------------------- |
 | messageGroups    | `Ref<MessageGroup[]>`         | 完整消息分组列表                                                            |
 | executionGroups  | `ComputedRef<MessageGroup[]>` | 仅包含执行类消息的分组（工具调用 + FlowAgent），自动提取 `userMessageTitle` |
+| sessionArtifacts | `ComputedRef<SessionArtifact[]>` | 拍平会话所有 AssistantMessage 文件产物，按 `outputId` 去重（保留最后一次） |
 | pendingApprovalCount | `ComputedRef<number>`      | 当前消息中待审批 AI Dev 审批中断的数量                                      |
 | pendingApprovalTipText | `ComputedRef<string>`    | 待审批阻塞发送提示文案；无待审批时为空字符串                                |
 | isShareMode      | `ShallowRef<boolean>`         | 是否处于分享模式                                                            |