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

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

@@ -0,0 +1,232 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+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
+- **file-artifact-panel** — 侧栏面板消费 activeArtifactId 与 setActiveArtifactId；预览加载在面板内 Host
+- **assistant-message** — 文件产物来源 property.artifacts
+
+---
+<!-- FULL DOC -->
+
+# useArtifactPreview 文件产物预览
+
+> **分类**：composable
+
+Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatContainer` 中创建，负责维护当前命中的文件 `outputId`；Consumer 在深层 `ArtifactFileCard` 中注入，用于点击卡片触发预览。
+
+**职责边界**：
+
+- **本 composable**：维护「命中文件」与「URL 解析」（TTL 缓存 + 并发去重；常规 `resolveArtifactUrls(file)`，重试可 `force` 刷新）；打开侧栏 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, options?: { force?: boolean }) => Promise<ArtifactUrlResult>;
+  setActiveArtifactId: (id: string) => void;
+};
+```
+
+### useArtifactPreviewConsumer
+
+```typescript
+function useArtifactPreviewConsumer():
+  | undefined
+  | {
+      activeArtifactId: Ref<string>;
+      canResolveArtifactUrl: ComputedRef<boolean>;
+      openPreview: (payload: OpenArtifactPreviewPayload) => void;
+      resolveArtifactUrls: (file: AIFileInfo, options?: { force?: boolean }) => 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 { activeArtifactId, setActiveArtifactId } = useArtifactPreviewProvider({
+  getOnArtifactClick: () => props.onArtifactClick,
+  // 点击文件卡片：展开侧栏并选中「文件产物」Tab
+  onOpen: () => {
+    addCustomTab({
+      closable: false,
+      label: t('文件产物'),
+      name: FILE_ARTIFACT_TAB_NAME,
+      order: -1,
+    });
+  },
+});
+
+// 有产物时静默挂上 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）
+
+```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, 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';
+
+/** 打开预览时的入参 */
+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）
+
+sessionArtifacts 变化（有产物）
+  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 静默挂上，不抢当前选中（如执行情况）
+```
+
+分类型预览策略见 [FileArtifactPanel 预览机制](../components/message/file-artifact-panel#预览机制)。
+
+## 设计特点
+
+- **职责单一**：composable 不直接调用 `useCustomTab`，侧栏 Tab 打开逻辑由 `onOpen` 注入；也不做正文 fetch / iframe 渲染
+- **ShallowRef 优先**：`activeArtifactId` 使用 `shallowRef`，避免不必要的深层响应式开销
+- **Consumer 兜底**：`useArtifactPreviewConsumer` 无 Provider 时返回 `undefined`，文件卡片在无容器上下文时自动不可点击
+- **与 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`）
+- [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

@@ -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>;
@@ -116,6 +117,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 +214,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>`         | 是否处于分享模式                                                            |