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

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-渲染工具返回内容，JSON 场景交给 DescPanel 展示。 源码位置：src/components/chat-message/tool-message/tool-message.vue。
+渲染工具返回内容；DescPanel 解析 JSON 为 key-value，嵌套值 JSON.stringify 后经 HighlightKeyword 展示。 源码位置：src/components/chat-message/tool-message/tool-message.vue。
 
 ### 关联组件
 - **assistant-message** — 结果常作为 assistant 消息中 toolCall.toolMessage 内联展示
@@ -12,51 +12,57 @@
 <!-- FULL DOC -->
 
 # ToolMessage 工具消息
+
 ## 源码事实
 
 - **源码位置**：`src/components/chat-message/tool-message/tool-message.vue`
 - **能力域**：消息系统
-- **能力说明**：渲染工具返回内容，JSON 场景交给 DescPanel 展示。
+- **能力说明**：渲染工具返回内容，JSON 场景交给 DescPanel + HighlightKeyword 展示。
 
-> **能力域**：消息系统
+> **导出说明**：`ToolMessage` **未**从包入口导出（入口同名是 TS interface）。消费方经 `MessageRender` / `ToolcallRender` 使用。下文 `ToolMessageComp` 为文档站内部示例。
 
-工具（Function Call）执行结果展示组件。内部通过 `DescPanel` 渲染，标题固定为"返回内容"，支持将 JSON 自动解析为 key-value 列表。
+工具执行结果展示组件。内部通过 `DescPanel` 渲染，标题固定为「返回内容」，可解析 JSON 为 key-value 列表。
 
-> **通常不需要直接使用此组件**。`ToolcallRender` 在 `toolCall.toolMessage` 有值时会自动内联渲染；`MessageContainer` 处理 `role: 'tool'` 消息时也会通过 `MessageRender` 自动渲染。
+> **通常不需要直接使用**。`ToolcallRender` 在 `toolCall.toolMessage` 有值时内联渲染；`role: 'tool'` 也可由 `MessageRender` 渲染。
 
 ## 渲染架构
 
 ```
 ToolMessage
-└── DescPanel（desc="content || (typeof error === 'string' ? error : undefined)"，title="返回内容"）
-      ├── JSON.parse(desc) 成功且结果为 object/array
-      │     └── key-value 列表（v-for 遍历）
-      │           值超长时截断 + overflow-tips tooltip
-      └── 其他（parse 失败 / 结果为基本类型）
-            └── 纯文本展示
+└── DescPanel（desc = content || (typeof error === 'string' ? error : undefined)，title="返回内容"）
+      ├── JSON.parse 成功且结果为 object/array（排除 null）
+      │     └── key-value 列表
+      │           · key / value 均经 HighlightKeyword 展示
+      │           · 嵌套 object/array：JSON.stringify 后展示（无 overflow-tips）
+      └── 其他（parse 失败 / 标量）
+            └── HighlightKeyword 纯文本
 ```
 
 ## 基础用法
 
 ```vue
 <template>
-  <ToolMessage
-    :content="content"
-    tool-call-id="call_1"
-    :duration="850"
-  />
+  <MessageRender :message="message" />
 </template>
 
 <script setup lang="ts">
-  import { ToolMessage } from '@blueking/chat-x';
-
-  const content = JSON.stringify({
-    city: '北京',
-    temperature: 22,
-    weather: '晴',
-    humidity: '45%',
-    wind: '东北风 3 级',
-  });
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: 't1',
+    messageId: 't1',
+    role: MessageRole.Tool,
+    status: MessageStatus.Complete,
+    toolCallId: 'call_1',
+    duration: 850,
+    content: JSON.stringify({
+      city: '北京',
+      temperature: 22,
+      weather: '晴',
+      humidity: '45%',
+      wind: '东北风 3 级',
+    }),
+  };
 </script>
 ```
 
@@ -70,18 +76,22 @@ ToolMessage
 
 ```vue
 <template>
-  <ToolMessage
-    content=""
-    :error="error"
-    tool-call-id="call_3"
-    :duration="5000"
-  />
+  <MessageRender :message="message" />
 </template>
 
 <script setup lang="ts">
-  import { ToolMessage } from '@blueking/chat-x';
-
-  const error = 'Connection timeout: database server is unreachable (timeout: 5000ms)';
+  import { MessageRender, MessageRole, MessageStatus } from '@blueking/chat-x';
+
+  const message = {
+    id: 't3',
+    messageId: 't3',
+    role: MessageRole.Tool,
+    status: MessageStatus.Error,
+    toolCallId: 'call_3',
+    duration: 5000,
+    content: '',
+    error: 'Connection timeout: database server is unreachable (timeout: 5000ms)',
+  };
 </script>
 ```
 
@@ -98,25 +108,27 @@ ToolMessage
 | 解析失败（非法 JSON）       | 捕获异常，返回原字符串          | 纯文本                              |
 | `content` 和 `error` 均为空 | `''` → 解析失败                 | 空内容区                            |
 
-> **注意**：JSON 数组在 JavaScript 中 `typeof [] === 'object'` 为 `true`，因此数组会以 `0:`、`1:`、`2:` 为键渲染为 key-value 列表，而**非**纯文本。
+> **注意**：JSON 数组 `typeof [] === 'object'`，会以 `0:`、`1:`、`2:` 为键渲染为列表，而非整段纯文本。
 
-**嵌套对象值的处理**：当 value 本身是对象时，`{{ value }}` 会渲染为 `[object Object]`，但 hover 展示的 overflow-tips 会显示 `JSON.stringify(value)` 的完整字符串。
+**嵌套对象 / 数组值**：`DescPanel` 用 `JSON.stringify(value)` 转成字符串后交给 `HighlightKeyword`，**不再**使用 overflow-tips。
 
 ```typescript
-// ✅ 渲染为 key-value 列表
+// key-value 列表
 const jsonObject = '{"city":"北京","temperature":22}';
 
-// ✅ 渲染为 index-keyed 列表（0: item1, 1: item2）
+// index-keyed 列表（0: item1, 1: item2）
 const jsonArray = '["item1","item2","item3"]';
 
-// ✅ 渲染为纯文本（基本类型）
-const jsonNumber = '42';
-const jsonBool = 'true';
+// 嵌套值 stringify 展示
+const nested = '{"result":"success","data":{"city":"北京","meta":{"humidity":45}}}';
 
-// ✅ 渲染为纯文本（解析失败）
+// 标量 / 非法 JSON → 纯文本
+const jsonNumber = '42';
 const plainText = '查询成功，共返回 10 条记录。';
 ```
 
+**嵌套 JSON 渲染效果**
+
 ## 与 ToolcallRender 的关系
 
 `ToolcallRender` 在详情面板展开时，若 `toolCall.toolMessage` 有值，会在底部内联渲染 `ToolMessage`：
@@ -186,8 +198,8 @@ const messages = [
 
 | 属性名     | 类型               | 说明                                                                            |
 | ---------- | ------------------ | ------------------------------------------------------------------------------- |
-| content    | `string`           | 工具执行返回内容；与 `error` 通过 `\|\|` 决定优先级，**truthy 时 error 被忽略** |
-| error      | `string`           | 工具执行错误信息；仅当 `content` 为 falsy 且 `error` 为 `string` 类型时展示     |
+| content    | `string`                 | 工具执行返回内容；与 `error` 通过 `\|\|` 决定优先级，**truthy 时 error 被忽略** |
+| error      | `boolean \| string`      | 类型上可为 boolean；**仅当为 `string` 且 content 为 falsy 时**才会展示           |
 | toolCallId | `string`           | 关联的工具调用 ID（透传，组件内不使用）                                         |
 | duration   | `number`           | 工具执行耗时（毫秒，透传，组件内不使用）                                        |
 | status     | `MessageStatus`    | 消息状态（透传，组件内不使用）                                                  |
@@ -210,11 +222,15 @@ interface ToolMessage {
   content: string;
   toolCallId: string; // 关联的 ToolCall.id
   duration: number; // 工具执行耗时（毫秒）
-  error?: string; // 执行错误信息
+  error?: boolean | string; // 仅 string 会展示在 DescPanel
   name?: string;
 }
 ```
 
+### Events / Slots / Expose
+
+无。
+
 ## 关联组件
 
 - [AssistantMessage](/components/message/assistant-message) — toolCall.toolMessage 内联场景

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

@@ -0,0 +1,237 @@
+<!-- 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。
+
+### 关联组件
+- **chat-container** — Provider 主场景，聚合 sessionArtifacts 并挂载 FileArtifactPanel
+- **file-artifact-panel** — 侧栏面板消费 activeArtifactId 与 setActiveArtifactId；预览加载在面板内 Host
+- **assistant-message** — 文件产物来源 property.artifacts
+
+---
+<!-- FULL DOC -->
+
+# useArtifactPreview 文件产物预览
+
+> **分类**：composable
+
+Provider/Consumer 模式的文件产物预览状态管理。Provider 在 `ChatContainer` 中创建，负责维护当前命中的文件 id；Consumer 在深层 `ArtifactFileCard` 中注入，用于点击卡片触发预览。
+
+**职责边界**：
+
+- **本 composable**：维护「命中文件」与「URL 解析缓存」；打开侧栏 Tab（`addCustomTab`）由容器通过 `onOpen` 注入
+- **不在本 composable**：聚合会话文件列表、渲染预览面板、按类型 fetch 正文 / iframe 展示 —— 分别由 `useMessageGroup.sessionArtifacts`、`FileArtifactPanel`、内部 `ArtifactPreviewHost` + `useArtifactPreviewLoader` 承担
+
+## 函数签名
+
+### useArtifactPreviewProvider
+
+```typescript
+function useArtifactPreviewProvider(options: {
+  /** 读取业务侧异步取链回调（getter 保持对 props 变更敏感） */
+  getOnArtifactClick?: () => OnArtifactClick | undefined;
+  /** 命中文件后触发：由容器负责 addCustomTab + 展开侧栏 + 选中 Tab */
+  onOpen: (artifactId: 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;
+    };
+```
+
+### buildArtifactId
+
+```typescript
+function buildArtifactId(messageUid: string, index: number, outputId: string): string;
+// => `${messageUid}#${index}#${outputId}`
+```
+
+## 使用示例
+
+### 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, removeCustomTab } = useCustomTabProvider({ /* ... */ });
+
+// 会话级文件产物聚合已内聚在 useMessageGroup，直接消费
+const { sessionArtifacts } = useMessageGroup({ keyword, messages, selectedUserMessages });
+
+const { activeArtifactId, setActiveArtifactId } = useArtifactPreviewProvider({
+  getOnArtifactClick: () => props.onArtifactClick,
+  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('');
+  }
+});
+```
+
+### 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,
+    index: props.index ?? 0,
+    messageUid: props.messageUid ?? '',
+  });
+};
+```
+
+### 侧栏列表内切换命中文件
+
+```typescript
+// FileArtifactPanel 列表点击 → emit select → 容器调用 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>`                      | 当前命中的文件 id（`messageUid#index#outputId`）                     |
+| canResolveArtifactUrl | `ComputedRef<boolean>`                  | 是否具备异步取链能力（有 `onArtifactClick` 时为 true，下载按钮据此显隐） |
+| openPreview         | `(payload: OpenArtifactPreviewPayload) => void` | 由文件卡片触发：计算 id、更新命中态、调用 `onOpen`             |
+| resolveArtifactUrls | `(file: AIFileInfo) => Promise<ArtifactUrlResult>` | 调用 `onArtifactClick` 并按 `outputId` 缓存结果；并发请求去重 |
+| setActiveArtifactId | `(id: string) => void`                    | 直接设置命中文件 id；侧栏列表内切换选中时使用                        |
+
+## 类型定义
+
+```typescript
+import type { AIFileInfo, ArtifactUrlResult, OnArtifactClick } from '@blueking/chat-x';
+
+/** 打开预览时的入参：文件 + 消息内下标 + 所属消息 uid */
+type OpenArtifactPreviewPayload = {
+  file: AIFileInfo;
+  index: number;
+  messageUid: string;
+};
+
+/**
+ * 会话级文件产物：在 AIFileInfo 基础上补充命中所需的唯一 id 与所属消息。
+ * 同一会话可能出现多个 AssistantMessage + 同名文件，文件名不可作唯一键。
+ */
+type SessionArtifact = AIFileInfo & {
+  artifactId: string;
+  messageUid: string;
+};
+
+/** onArtifactClick 返回值（snake_case） */
+type ArtifactUrlResult = {
+  download_url?: string;
+  preview_url?: string;
+};
+```
+
+## 唯一 id 规则
+
+同一会话可能存在多个 `AssistantMessage`，且不同消息里可能有同名文件，因此**文件名不可作为唯一键**。Provider 侧聚合与 Consumer 侧透传必须使用同一 `buildArtifactId` 规则：
+
+```typescript
+buildArtifactId('msg-a', 2, 'output-9'); // => 'msg-a#2#output-9'
+```
+
+- `messageUid`：所属 `AssistantMessage` 的 `uid`（回退 `String(id)`）
+- `index`：文件在所属消息 `property.artifacts` 数组中的下标
+- `outputId`：文件自身的 `AIFileInfo.outputId`
+
+## 完整触发链路
+
+```
+ArtifactFileCard（点击）
+  └─ useArtifactPreviewConsumer().openPreview({ file, index, messageUid })
+       └─ useArtifactPreviewProvider（ChatContainer）
+            ├─ activeArtifactId = buildArtifactId(...)
+            └─ onOpen(artifactId) → addCustomTab(FILE_ARTIFACT_TAB_NAME)
+                 └─ FileArtifactPanel（列表 + 下载头，@select → setActiveArtifactId）
+                      └─ ArtifactPreviewHost（loader + 分类型 renderer）
+```
+
+分类型预览策略见 [FileArtifactPanel 预览机制](../components/message/file-artifact-panel#预览机制)。
+
+## 设计特点
+
+- **职责单一**：composable 不直接调用 `useCustomTab`，侧栏 Tab 打开逻辑由 `onOpen` 注入；也不做正文 fetch / iframe 渲染
+- **ShallowRef 优先**：`activeArtifactId` 使用 `shallowRef`，避免不必要的深层响应式开销
+- **Consumer 兜底**：`useArtifactPreviewConsumer` 无 Provider 时返回 `undefined`，文件卡片在无容器上下文时自动不可点击
+- **与 useCustomTab 协作**：「文件产物」Tab 通过 `addCustomTab` 按需添加（`order: -1`、`closable: false`），会话无文件产物时由容器 `removeCustomTab` 清理
+
+## 关联组件
+
+- [ChatContainer](../components/setup/chat-container) — Provider 主场景，内置「文件产物」Tab
+- [FileArtifactPanel](../components/message/file-artifact-panel) — 侧栏列表与预览 Host 挂载
+- [AssistantMessage](../components/message/assistant-message) — 文件产物来源（`property.artifacts`）

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,28 @@ const isExecutionMessage = (m: Message): boolean => {
 | toolCall   | `function.name`、`mcpName`、`description`、`arguments`、`id` |
 | flow_agent | 各任务 `task_name`、各节点 `name`                             |
 
+## sessionArtifacts 会话级文件产物
+
+`sessionArtifacts` 拍平当前会话所有 `AssistantMessage.property.artifacts`，供 `ChatContainer` 侧栏「文件产物」Tab 聚合预览。由于同一会话可能出现「多个 AssistantMessage + 同名文件」，文件名不可作为唯一键，统一用 `messageUid`（回退 `String(id)`）+ 消息内下标 + `outputId` 通过 [`buildArtifactId`](./use-artifact-preview) 生成全局唯一 `artifactId`：
+
+```typescript
+const sessionArtifacts = computed(() => {
+  const list = [];
+  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 });
+    });
+  }
+  return list;
+});
+```
+
+预览命中与取链见 [useArtifactPreview](./use-artifact-preview)；侧栏列表与分类型预览（`ArtifactPreviewHost`）见 [FileArtifactPanel](../components/message/file-artifact-panel)。
+
 ## 待审批统计
 
 `useMessageGroup` 会统计消息列表中处于待审批状态的 AI Dev 审批中断：
@@ -186,6 +209,7 @@ const {
 | ---------------- | ----------------------------- | --------------------------------------------------------------------------- |
 | messageGroups    | `Ref<MessageGroup[]>`         | 完整消息分组列表                                                            |
 | executionGroups  | `ComputedRef<MessageGroup[]>` | 仅包含执行类消息的分组（工具调用 + FlowAgent），自动提取 `userMessageTitle` |
+| sessionArtifacts | `ComputedRef<SessionArtifact[]>` | 拍平会话所有 AssistantMessage 文件产物，含全局唯一 `artifactId`         |
 | pendingApprovalCount | `ComputedRef<number>`      | 当前消息中待审批 AI Dev 审批中断的数量                                      |
 | pendingApprovalTipText | `ComputedRef<string>`    | 待审批阻塞发送提示文案；无待审批时为空字符串                                |
 | isShareMode      | `ShallowRef<boolean>`         | 是否处于分享模式                                                            |