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

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-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。
+useArtifactPreviewProvider 维护 activeArtifactId（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（TTL 8 分钟缓存；常规只传 file，force 可强制刷新，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。
 
 ### 关联组件
 - **chat-container** — Provider 主场景，聚合 sessionArtifacts 并挂载 FileArtifactPanel
@@ -15,12 +15,12 @@ useArtifactPreviewProvider 维护 activeArtifactId，openPreview 命中文件并
 
 > **分类**：composable
 
-Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatContainer` 中创建，负责维护当前命中的文件 id；Consumer 在深层 `ArtifactFileCard` 中注入，用于点击卡片触发预览。
+Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatContainer` 中创建，负责维护当前命中的文件 `outputId`；Consumer 在深层 `ArtifactFileCard` 中注入，用于点击卡片触发预览。
 
 **职责边界**：
 
-- **本 composable**：维护「命中文件」与「URL 解析缓存」；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
-- **不在本 composable**：聚合会话文件列表、渲染预览面板、按类型 fetch 正文 / iframe 展示 —— 分别由 `useMessageGroup.sessionArtifacts`、`FileArtifactPanel`、内部 `ArtifactPreviewHost` + `useArtifactPreviewLoader` 承担
+- **本 composable**：维护「命中文件」与「URL 解析」（TTL 缓存 + 并发去重；常规 `resolveArtifactUrls(file)`，重试可 `force` 刷新）；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
+- **不在本 composable**：聚合会话文件列表、渲染预览面板、按类型 fetch 正文 / iframe 展示 —— 分别由 `useMessageGroup.sessionArtifacts`、`FileArtifactPanel`、内部 `ArtifactPreviewHost` + `useArtifactPreviewLoader` 承担（预览重载键为 `outputId:type`）
 
 ## 函数签名
 
@@ -31,12 +31,12 @@ function useArtifactPreviewProvider(options: {
   /** 读取业务侧异步取链回调（getter 保持对 props 变更敏感） */
   getOnArtifactClick?: () => OnArtifactClick | undefined;
   /** 命中文件后触发：由容器负责 addCustomTab + 展开侧栏 + 选中 Tab */
-  onOpen: (artifactId: string) => void;
+  onOpen: (outputId: string) => void;
 }): {
   activeArtifactId: ShallowRef<string>;
   canResolveArtifactUrl: ComputedRef<boolean>;
   openPreview: (payload: OpenArtifactPreviewPayload) => void;
-  resolveArtifactUrls: (file: AIFileInfo) => Promise<ArtifactUrlResult>;
+  resolveArtifactUrls: (file: AIFileInfo, options?: { force?: boolean }) => Promise<ArtifactUrlResult>;
   setActiveArtifactId: (id: string) => void;
 };
 ```
@@ -50,18 +50,11 @@ function useArtifactPreviewConsumer():
       activeArtifactId: Ref<string>;
       canResolveArtifactUrl: ComputedRef<boolean>;
       openPreview: (payload: OpenArtifactPreviewPayload) => void;
-      resolveArtifactUrls: (file: AIFileInfo) => Promise<ArtifactUrlResult>;
+      resolveArtifactUrls: (file: AIFileInfo, options?: { force?: boolean }) => Promise<ArtifactUrlResult>;
       setActiveArtifactId: (id: string) => void;
     };
 ```
 
-### buildArtifactId
-
-```typescript
-function buildArtifactId(messageUid: string, index: number, outputId: string): string;
-// => `${messageUid}#${index}#${outputId}`
-```
-
 ## 使用示例
 
 ### Provider（ChatContainer）
@@ -77,13 +70,14 @@ import {
 } from '@blueking/chat-x';
 import { t } from '@blueking/chat-x/lang';
 
-const { addCustomTab, removeCustomTab } = useCustomTabProvider({ /* ... */ });
+const { addCustomTab, ensureCustomTab, removeCustomTab } = useCustomTabProvider({ /* ... */ });
 
 // 会话级文件产物聚合已内聚在 useMessageGroup，直接消费
 const { sessionArtifacts } = useMessageGroup({ keyword, messages, selectedUserMessages });
 
 const { activeArtifactId, setActiveArtifactId } = useArtifactPreviewProvider({
   getOnArtifactClick: () => props.onArtifactClick,
+  // 点击文件卡片：展开侧栏并选中「文件产物」Tab
   onOpen: () => {
     addCustomTab({
       closable: false,
@@ -94,13 +88,23 @@ const { activeArtifactId, setActiveArtifactId } = useArtifactPreviewProvider({
   },
 });
 
-// 无文件产物时清理 Tab 与命中态
+// 有产物时静默挂上 Tab（不抢焦点）；无产物时清理
 watch(sessionArtifacts, list => {
   if (!list.length) {
     removeCustomTab(FILE_ARTIFACT_TAB_NAME);
     setActiveArtifactId('');
+    return;
   }
-});
+  ensureCustomTab({
+    closable: false,
+    label: t('文件产物'),
+    name: FILE_ARTIFACT_TAB_NAME,
+    order: -1,
+  });
+  if (!list.some(item => item.outputId === activeArtifactId.value)) {
+    setActiveArtifactId(list[0].outputId);
+  }
+}, { immediate: true });
 ```
 
 ### Consumer（ArtifactFileCard）
@@ -118,18 +122,14 @@ const handleCardClick = () => {
     props.onPreview(props.file);
     return;
   }
-  artifactPreview?.openPreview({
-    file: props.file,
-    index: props.index ?? 0,
-    messageUid: props.messageUid ?? '',
-  });
+  artifactPreview?.openPreview({ file: props.file });
 };
 ```
 
 ### 侧栏列表内切换命中文件
 
 ```typescript
-// FileArtifactPanel 列表点击 → emit select → 容器调用 setActiveArtifactId
+// FileArtifactPanel 列表点击 → emit select(outputId) → 容器调用 setActiveArtifactId
 // 右侧预览由面板内 ArtifactPreviewHost 消费 activeArtifact，自行取链并按类型渲染
 <FileArtifactPanel
   :active-id="activeArtifactId"
@@ -163,32 +163,27 @@ const onArtifactClick = async (file: AIFileInfo) => {
 
 | 属性/方法名         | 类型                                      | 说明                                                                 |
 | ------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
-| activeArtifactId    | `ShallowRef<string>`                      | 当前命中的文件 id（`messageUid#index#outputId`）                     |
+| activeArtifactId    | `ShallowRef<string>`                      | 当前命中的文件 `outputId`                                            |
 | canResolveArtifactUrl | `ComputedRef<boolean>`                  | 是否具备异步取链能力（有 `onArtifactClick` 时为 true，下载按钮据此显隐） |
-| openPreview         | `(payload: OpenArtifactPreviewPayload) => void` | 由文件卡片触发：计算 id、更新命中态、调用 `onOpen`             |
-| resolveArtifactUrls | `(file: AIFileInfo) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 并按 `outputId` 缓存结果；并发请求去重 |
-| setActiveArtifactId | `(id: string) => void`                    | 直接设置命中文件 id；侧栏列表内切换选中时使用                        |
+| openPreview         | `(payload: OpenArtifactPreviewPayload) => void` | 由文件卡片触发：以 `file.outputId` 更新命中态、调用 `onOpen`   |
+| resolveArtifactUrls | `(file: AIFileInfo, options?: { force?: boolean }) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 取链；成功结果按 `outputId` 缓存 8 分钟；**常规调用只传 `file`**，仅预览重试 / 强刷传 `{ force: true }`（不要传 `undefined` 作为第二参）；并发去重 |
+| setActiveArtifactId | `(id: string) => void`                    | 直接设置命中文件 `outputId`；侧栏列表内切换选中时使用                |
 
 ## 类型定义
 
 ```typescript
 import type { AIFileInfo, ArtifactUrlResult, OnArtifactClick } from '@blueking/chat-x';
 
-/** 打开预览时的入参：文件 + 消息内下标 + 所属消息 uid */
+/** 打开预览时的入参 */
 type OpenArtifactPreviewPayload = {
   file: AIFileInfo;
-  index: number;
-  messageUid: string;
 };
 
 /**
- * 会话级文件产物：在 AIFileInfo 基础上补充命中所需的唯一 id 与所属消息。
- * 同一会话可能出现多个 AssistantMessage + 同名文件，文件名不可作唯一键。
+ * 会话级文件产物：以 outputId 为会话内唯一键（同 outputId 视为同一文件）。
+ * 拍平去重后即为 AIFileInfo，此处用别名标明语义。
  */
-type SessionArtifact = AIFileInfo & {
-  artifactId: string;
-  messageUid: string;
-};
+type SessionArtifact = AIFileInfo;
 
 /** onArtifactClick 返回值（snake_case） */
 type ArtifactUrlResult = {
@@ -197,28 +192,27 @@ type ArtifactUrlResult = {
 };
 ```
 
-## 唯一 id 规则
+## 唯一键规则
 
-同一会话可能存在多个 `AssistantMessage`，且不同消息里可能有同名文件，因此**文件名不可作为唯一键**。Provider 侧聚合与 Consumer 侧透传必须使用同一 `buildArtifactId` 规则：
+会话内以 **`outputId`** 作为文件产物唯一键：
 
-```typescript
-buildArtifactId('msg-a', 2, 'output-9'); // => 'msg-a#2#output-9'
-```
-
-- `messageUid`：所属 `AssistantMessage` 的 `uid`（回退 `String(id)`）
-- `index`：文件在所属消息 `property.artifacts` 数组中的下标
-- `outputId`：文件自身的 `AIFileInfo.outputId`
+- 同一 `outputId` 在多条 `AssistantMessage` 中出现时，`sessionArtifacts` 去重并保留**最后一次**出现的文件信息
+- `activeArtifactId`、列表 `:key`、`select` 事件参数均使用 `outputId`
+- 文件名可能重复，**不可**作为唯一键
 
 ## 完整触发链路
 
 ```
 ArtifactFileCard（点击）
-  └─ useArtifactPreviewConsumer().openPreview({ file, index, messageUid })
+  └─ useArtifactPreviewConsumer().openPreview({ file })
        └─ useArtifactPreviewProvider（ChatContainer）
-            ├─ activeArtifactId = buildArtifactId(...)
-            └─ onOpen(artifactId) → addCustomTab(FILE_ARTIFACT_TAB_NAME)
+            ├─ activeArtifactId = file.outputId
+            └─ onOpen(outputId) → addCustomTab(FILE_ARTIFACT_TAB_NAME) 展开并选中
                  └─ FileArtifactPanel（列表 + 下载头，@select → setActiveArtifactId）
                       └─ ArtifactPreviewHost（loader + 分类型 renderer）
+
+sessionArtifacts 变化（有产物）
+  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 静默挂上，不抢当前选中（如执行情况）
 ```
 
 分类型预览策略见 [FileArtifactPanel 预览机制](../components/message/file-artifact-panel#预览机制)。
@@ -228,10 +222,11 @@ ArtifactFileCard（点击）
 - **职责单一**：composable 不直接调用 `useCustomTab`，侧栏 Tab 打开逻辑由 `onOpen` 注入；也不做正文 fetch / iframe 渲染
 - **ShallowRef 优先**：`activeArtifactId` 使用 `shallowRef`，避免不必要的深层响应式开销
 - **Consumer 兜底**：`useArtifactPreviewConsumer` 无 Provider 时返回 `undefined`，文件卡片在无容器上下文时自动不可点击
-- **与 useCustomTab 协作**：「文件产物」Tab 通过 `addCustomTab` 按需添加（`order: -1`、`closable: false`），会话无文件产物时由容器 `removeCustomTab` 清理
+- **与 useCustomTab 协作**：点击卡片走 `addCustomTab`（展开 + 选中）；会话已有产物时走 `ensureCustomTab`（只挂载，不抢焦点）；无文件产物时由容器 `removeCustomTab` 清理
 
 ## 关联组件
 
 - [ChatContainer](../components/setup/chat-container) — Provider 主场景，内置「文件产物」Tab
 - [FileArtifactPanel](../components/message/file-artifact-panel) — 侧栏列表与预览 Host 挂载
-- [AssistantMessage](../components/message/assistant-message) — 文件产物来源（`property.artifacts`）
+- [AssistantMessage](../components/message/assistant-message) — 文件产物来源（`property.artifacts`）
+- [useCustomTab](./use-custom-tab) — `addCustomTab` / `ensureCustomTab` 分工

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 在切换时拉取数据。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不切换选中；addCustomTab 会展开并选中。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
 
 ### 关联组件
 - **chat-container** — Provider 与侧栏 Tab 主场景
@@ -30,6 +30,7 @@ function useCustomTabProvider<T extends Record<string, unknown>>(options: {
   selectedTab: Ref<CustomTab<T>>;
   isCollapse: ShallowRef<boolean>;
   addCustomTab: (tab: CustomTab<T>) => void;
+  ensureCustomTab: (tab: CustomTab<T>) => void;
   removeCustomTab: (tabName: string) => void;
   selectCustomTab: (tab: CustomTab<T>) => void;
   resetCustomTab: () => void;
@@ -46,6 +47,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 +61,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 +78,7 @@ import { useCustomTabConsumer } from '@blueking/chat-x';
 
 const tabManager = useCustomTabConsumer();
 
-// 添加一个自定义 Tab
+// 添加一个自定义 Tab（展开侧栏并选中）
 tabManager?.addCustomTab({
   name: 'node-detail-123',
   label: '节点详情',
@@ -86,6 +88,14 @@ tabManager?.addCustomTab({
   },
 });
 
+// 仅确保 Tab 存在（不展开、不切换选中）—— 如侧栏已因执行情况打开时同步挂上文件产物
+tabManager?.ensureCustomTab({
+  name: 'file-artifact',
+  label: '文件产物',
+  closable: false,
+  order: -1,
+});
+
 // 移除 Tab
 tabManager?.removeCustomTab('node-detail-123');
 ```
@@ -106,7 +116,8 @@ tabManager?.removeCustomTab('node-detail-123');
 | 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`） |
+| 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 +147,9 @@ interface CustomTab<T = Record<string, unknown>> {
 - 排序为稳定排序，`order` 相同的 Tab 保持插入先后顺序
 - 选中的 Tab 被配置隐藏时，内容不再渲染，自动切换到首个可见 Tab
 - `addCustomTab` 同时展开侧边栏（`isCollapse = false`）并在 `nextTick` 后自动选中目标 Tab；同名 Tab 合并更新
+- `ensureCustomTab` 与 `addCustomTab` 共用合并逻辑，但不改 `isCollapse`、不切换 `selectedTab`；适合「侧栏已打开时同步挂上文件产物」等场景
 
 ## 关联组件
 
-- [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-message-group.md

@@ -119,24 +119,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 +214,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-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-06T04:13:41.238Z",
   "domains": {
     "setup": {
       "label": "对话搭建",
@@ -362,8 +362,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",
@@ -1115,7 +1115,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：按类型走 text_from_download（html / markdown / md / txt / json） 或 preview_url_iframe（其余类型）；download_url / preview_url 经 onArtifactClick 异步获取（TTL 缓存，重试 force）； 预览重载键为 outputId:type；常规 resolveArtifactUrls 只传 file。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。",
       "relatedComponents": [
         {
           "slug": "assistant-message",
@@ -1586,7 +1586,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（TTL 8 分钟缓存；常规只传 file，force 可强制刷新，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。",
       "relatedComponents": [
         {
           "slug": "chat-container",
@@ -1666,7 +1666,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 在切换时拉取数据。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不切换选中；addCustomTab 会展开并选中。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。",
       "relatedComponents": [
         {
           "slug": "chat-container",
@@ -1787,7 +1787,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/chat-x",
-  "version": "0.0.49-beta.1",
+  "version": "0.0.49-beta.2",
   "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.14"
   },
   "scripts": {
     "dev": "vite --config vite.config.ts",