@blueking/chat-x 0.0.5 → 0.0.6

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

@@ -0,0 +1,217 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ToolMessage 展示工具（Function Call）执行返回，内部用 DescPanel 将 JSON 解析为 key-value 或纯文本。通常不单独使用： ToolcallRender 在 toolCall.toolMessage 有值时内联渲染；独立 role 为 tool 的消息由 MessageRender 统一渲染。核心关注 content 与 error。
+
+### 关联组件
+- **assistant-message** — 结果常作为 assistant 消息中 toolCall.toolMessage 内联展示
+- **message-render** — 独立 tool 角色消息由 MessageRender 渲染为 ToolMessage
+- **desc-panel** — 内部使用 DescPanel 展示「返回内容」
+
+---
+<!-- FULL DOC -->
+
+# ToolMessage 工具消息
+
+> **层级**：分子组件 · **功能域**：消息展示
+
+工具（Function Call）执行结果展示组件。内部通过 `DescPanel` 渲染，标题固定为"返回内容"，支持将 JSON 自动解析为 key-value 列表。
+
+> **通常不需要直接使用此组件**。`ToolcallRender` 在 `toolCall.toolMessage` 有值时会自动内联渲染；`MessageContainer` 处理 `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 失败 / 结果为基本类型）
+            └── 纯文本展示
+```
+
+## 基础用法
+
+```vue
+<template>
+  <ToolMessage
+    :content="content"
+    tool-call-id="call_1"
+    :duration="850"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ToolMessage } from '@blueking/chat-x';
+
+  const content = JSON.stringify({
+    city: '北京',
+    temperature: 22,
+    weather: '晴',
+    humidity: '45%',
+    wind: '东北风 3 级',
+  });
+</script>
+```
+
+**JSON 对象内容（key-value 列表）**
+
+**纯文本内容**
+
+## 错误状态
+
+`content` 为空时展示 `error`，由 `content || (typeof error === 'string' ? error : undefined)` 决定。仅当 `error` 为字符串类型时才会展示，非字符串类型的 `error`（如对象）会被忽略：
+
+```vue
+<template>
+  <ToolMessage
+    content=""
+    :error="error"
+    tool-call-id="call_3"
+    :duration="5000"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ToolMessage } from '@blueking/chat-x';
+
+  const error = 'Connection timeout: database server is unreachable (timeout: 5000ms)';
+</script>
+```
+
+## DescPanel 内容渲染规则
+
+`DescPanel` 内部对 `desc`（即 `content || (typeof error === 'string' ? error : undefined)`）进行 `JSON.parse`，然后根据解析结果类型决定渲染方式：
+
+| `desc` 内容                 | `JSON.parse` 结果               | 渲染方式                            |
+| --------------------------- | ------------------------------- | ----------------------------------- |
+| 合法 JSON 对象 `{}`         | `object`（非 null）             | **key-value 列表**，键为字段名      |
+| 合法 JSON 数组 `[]`         | `array`（也是 `object`）        | **index-keyed 列表**，键为 0、1、2… |
+| 合法 JSON 基本类型          | `number` / `string` / `boolean` | 纯文本                              |
+| `"null"` 字符串             | `null`（`typeof 'object'`）     | 空内容区（v-for 遍历 null 无输出）  |
+| 解析失败（非法 JSON）       | 捕获异常，返回原字符串          | 纯文本                              |
+| `content` 和 `error` 均为空 | `''` → 解析失败                 | 空内容区                            |
+
+> **注意**：JSON 数组在 JavaScript 中 `typeof [] === 'object'` 为 `true`，因此数组会以 `0:`、`1:`、`2:` 为键渲染为 key-value 列表，而**非**纯文本。
+
+**嵌套对象值的处理**：当 value 本身是对象时，`{{ value }}` 会渲染为 `[object Object]`，但 hover 展示的 overflow-tips 会显示 `JSON.stringify(value)` 的完整字符串。
+
+```typescript
+// ✅ 渲染为 key-value 列表
+const jsonObject = '{"city":"北京","temperature":22}';
+
+// ✅ 渲染为 index-keyed 列表（0: item1, 1: item2）
+const jsonArray = '["item1","item2","item3"]';
+
+// ✅ 渲染为纯文本（基本类型）
+const jsonNumber = '42';
+const jsonBool = 'true';
+
+// ✅ 渲染为纯文本（解析失败）
+const plainText = '查询成功，共返回 10 条记录。';
+```
+
+## 与 ToolcallRender 的关系
+
+`ToolcallRender` 在详情面板展开时，若 `toolCall.toolMessage` 有值，会在底部内联渲染 `ToolMessage`：
+
+```typescript
+// toolcall-render.vue 内部逻辑（简化）
+// <ToolMessage v-if="toolCall?.toolMessage" v-bind="toolCall.toolMessage" />
+
+const toolCall = {
+  id: 'call_weather',
+  type: 'function',
+  function: {
+    name: 'get_weather',
+    arguments: '{"city":"北京"}',
+    description: '获取天气信息',
+  },
+  // 提供此字段后 ToolcallRender 会自动渲染 ToolMessage
+  toolMessage: {
+    id: '3',
+    messageId: '3',
+    role: 'tool',
+    content: '{"temperature":22,"weather":"晴"}',
+    status: 'complete',
+    duration: 850,
+    toolCallId: 'call_weather',
+  },
+};
+```
+
+## 与 MessageContainer 的关系
+
+`MessageContainer` 通过 `toolCallId` 将 `role: 'tool'` 消息注入对应 AssistantMessage 的 `toolCall.toolMessage`，整个过程自动完成，无需手动引入 `ToolMessage`：
+
+```typescript
+const messages = [
+  {
+    id: '1',
+    messageId: '1',
+    role: 'assistant',
+    content: '好的，我来查询天气。',
+    status: 'complete',
+    toolCalls: [
+      {
+        id: 'call_weather',
+        type: 'function',
+        function: { name: 'get_weather', arguments: '{"city":"北京"}' },
+      },
+    ],
+  },
+  {
+    id: '2',
+    messageId: '2',
+    role: 'tool', // MessageContainer 自动处理
+    content: '{"temperature":22,"weather":"晴"}',
+    status: 'complete',
+    toolCallId: 'call_weather', // ← 通过此字段自动关联并注入上方 toolCall
+    duration: 850,
+  },
+];
+```
+
+## API
+
+### Props
+
+组件 Props 继承自 `Partial<ToolMessage>`，所有字段均可选：
+
+| 属性名     | 类型               | 说明                                                                            |
+| ---------- | ------------------ | ------------------------------------------------------------------------------- |
+| content    | `string`           | 工具执行返回内容；与 `error` 通过 `\|\|` 决定优先级，**truthy 时 error 被忽略** |
+| error      | `string`           | 工具执行错误信息；仅当 `content` 为 falsy 且 `error` 为 `string` 类型时展示     |
+| toolCallId | `string`           | 关联的工具调用 ID（透传，组件内不使用）                                         |
+| duration   | `number`           | 工具执行耗时（毫秒，透传，组件内不使用）                                        |
+| status     | `MessageStatus`    | 消息状态（透传，组件内不使用）                                                  |
+| id         | `string \| number` | 消息 ID（透传，组件内不使用）                                                   |
+| messageId  | `string \| number` | 消息唯一标识（透传，组件内不使用）                                              |
+
+> **说明**：`ToolMessage` 组件内部只使用 `content` 和 `error` 两个字段（传给 `DescPanel`），其他字段均被透传接收但不使用，由父组件（`ToolcallRender` / `MessageContainer`）在外部管理。
+
+## 类型定义
+
+```typescript
+import { MessageRole, MessageStatus, type ToolMessage } from '@blueking/chat-x';
+
+// ToolMessage 继承自 BaseMessage<MessageRole.Tool, string>
+interface ToolMessage {
+  id: string | number;
+  messageId: string | number;
+  role: MessageRole.Tool; // 'tool'
+  status: MessageStatus;
+  content: string;
+  toolCallId: string; // 关联的 ToolCall.id
+  duration: number; // 工具执行耗时（毫秒）
+  error?: string; // 执行错误信息
+  name?: string;
+}
+```
+
+## 关联组件
+
+- [AssistantMessage](./assistant-message.md) — toolCall.toolMessage 内联场景
+- [MessageRender](./message-render.md) — 独立 tool 消息派发
+- [DescPanel](../atomic/desc-panel.md) — 返回内容面板

package/dist/mcp/generated/docs/toolcall-render.md

@@ -0,0 +1,299 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+ToolcallRender 折叠展示一次工具/MCP 调用：头部显示名称、状态色、耗时与 MCP 标识，展开区展示参数与返回。 内部组合 DescPanel 与 HighlightKeyword；可在详情底部内联 ToolMessage 结果。
+
+### 关联组件
+- **desc-panel** — 详情区展示参数与描述文本
+- **highlight-keyword** — 标题与状态文案关键词高亮
+- **tool-message** — 详情底部可内联工具返回消息
+
+---
+<!-- FULL DOC -->
+
+# ToolcallRender 工具调用渲染器
+
+> **层级**：分子组件 · **功能域**：工具与反馈
+
+展示 AI 调用外部工具/函数过程与结果的渲染组件。由**可折叠头部**和**详情面板**组成，根据 `status` 自动切换颜色和状态文案，支持 MCP 调用识别和内联结果展示。
+
+## 组件结构
+
+```
+.ai-toolcall-render
+├── .ai-toolcall-render-header（高 40px，class="toolcall-status-{status}"）
+│   ├── ArrowRightIcon（14×14px，点击切换折叠；默认 rotate(0deg)，展开后 rotate(90deg)）
+│   ├── "调用工具：" / "调用 MCP："（有 mcpName 时）
+│   ├── .toolcall-header-title（工具名，overflow-tips 溢出截断）
+│   └── .toolcall-status-title
+│         ├── Loading（仅 pending / streaming 时显示）
+│         ├── 状态文案（调用中 / 调用成功 / 调用失败）
+│         └── .toolcall-duration（耗时，如 "(1.2s)"）
+│
+└── .ai-toolcall-render-content（v-show，默认折叠）
+      ├── DescPanel（title="描述"，desc=function.description）← 始终渲染
+      ├── DescPanel（title="参数"，desc=function.arguments）← 始终渲染
+      └── ToolMessage（v-if="toolCall?.toolMessage"）← 有结果时渲染
+```
+
+## 基础用法
+
+```vue
+<template>
+  <ToolcallRender
+    :tool-call="toolCall"
+    :status="MessageStatus.Complete"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ToolcallRender, MessageStatus, MessageContentType, type ToolCall } from '@blueking/chat-x';
+
+  const toolCall: ToolCall = {
+    id: 'call_1',
+    type: MessageContentType.Function,
+    function: {
+      name: 'get_weather',
+      arguments: JSON.stringify({ city: '北京', unit: 'celsius' }),
+      description: '获取指定城市的实时天气信息',
+    },
+    toolMessage: {
+      content: JSON.stringify({ city: '北京', temperature: 22, weather: '晴' }),
+      status: 'complete',
+      duration: 1200,
+      toolCallId: 'call_1',
+    },
+  };
+</script>
+```
+
+**渲染效果**
+
+## 调用状态
+
+`status` prop 同时控制头部的 CSS class（`toolcall-status-{status}`）、背景/边框颜色、状态文案和 Loading 动画：
+
+| `status`                | 状态文案 | 背景色            | 边框色    | Loading |
+| ----------------------- | -------- | ----------------- | --------- | ------- |
+| `pending` / `streaming` | 调用中   | `#fafbfd`         | `#dcdee5` | ✓       |
+| `complete` / `success`  | 调用成功 | `#ebfaf0`         | `#a1e3ba` | -       |
+| `error`                 | 调用失败 | `#fff0f0`         | `#f8b4b4` | -       |
+| 其他 / `undefined`      | 调用中   | —（无匹配 class） | —         | -       |
+
+> **说明**：`statusTitle` 的 `switch` 语句中 `default` 与 `case Pending` 共享同一返回值，`streaming` 和未知 status 均命中 `default` 分支，显示"调用中"。Loading 动画由 `v-if="status === 'pending' || status === 'streaming'"` 单独控制。
+
+**三种状态对比**
+
+## 工具标题（toolTitle）
+
+头部标题的计算规则：
+
+```
+有 mcpName → "{mcpName} / {function.name}"
+无 mcpName → function.name || toolCall.id
+```
+
+`function.name` 为空字符串时，自动回退到 `toolCall.id` 作为标题。标题超出容器宽度时截断并配备 overflow-tips。
+
+## 折叠/展开详情面板
+
+详情面板**默认折叠**，点击头部左侧的 **箭头图标**（14×14px 可点区域，非整行）切换折叠状态。折叠状态由 `collapsed`（默认 `true`）和 `superCollapsed` 两个 `shallowRef` 共同管理，不暴露为 prop/v-model。
+
+| 折叠状态     | 箭头旋转角度            | 详情面板      |
+| ------------ | ----------------------- | ------------- |
+| 折叠（默认） | `rotate(0deg)`（朝右）  | `v-show` 隐藏 |
+| 展开         | `rotate(90deg)`（朝下） | 可见          |
+
+详情面板由三块区域构成：
+
+| 区块     | 数据来源               | 渲染方式                                             | 渲染条件                     |
+| -------- | ---------------------- | ---------------------------------------------------- | ---------------------------- |
+| 描述     | `function.description` | `DescPanel`（纯文本 / key-value 列表）               | **始终渲染**，无值则显示空白 |
+| 参数     | `function.arguments`   | `DescPanel`（JSON 对象 → key-value；其他 → 纯文本）  | **始终渲染**，无值则显示空白 |
+| 工具结果 | `toolCall.toolMessage` | `ToolMessage` 组件（`v-if="toolCall?.toolMessage"`） | 仅当 `toolMessage` 存在时    |
+
+## 调用耗时
+
+耗时来源优先级（`||` 运算符）：
+
+```typescript
+durationDisplay = formatDuration(props.duration || toolCall?.toolMessage?.duration);
+```
+
+| 场景                                       | 耗时来源                    |
+| ------------------------------------------ | --------------------------- |
+| 传入 `duration` prop                       | 使用 prop 值                |
+| 未传 `duration`，toolMessage 有 `duration` | 使用 `toolMessage.duration` |
+| 两者均无                                   | 不显示耗时                  |
+
+```vue
+<!-- 方式一：直接传 duration prop（优先） -->
+<ToolcallRender :tool-call="toolCall" status="complete" :duration="1200" />
+
+<!-- 方式二（推荐）：duration 放在 toolMessage 中，无需额外 prop -->
+<ToolcallRender :tool-call="toolCallWithDuration" status="complete" />
+```
+
+```typescript
+// 推荐：duration 统一由 toolMessage 管理
+const toolCallWithDuration: ToolCall = {
+  id: 'call_1',
+  type: 'function',
+  function: { name: 'get_weather', arguments: '{"city":"北京"}' },
+  toolMessage: {
+    content: '{"temperature":22}',
+    status: 'complete',
+    duration: 1200, // ← 组件自动读取，无需额外传 duration prop
+    toolCallId: 'call_1',
+  },
+};
+```
+
+## MCP 工具调用
+
+`function.mcpName` 有值时：
+
+- 头部文案从 **"调用工具："** 自动切换为 **"调用 MCP："**
+- 标题格式变为 `{mcpName} / {functionName}`
+
+```typescript
+const mcpToolCall: ToolCall = {
+  id: 'call_mcp_1',
+  type: 'function',
+  function: {
+    name: 'query_table',
+    arguments: JSON.stringify({ table: 'events', limit: 50 }),
+    description: '通过 MCP 协议查询蓝鲸数据平台中的事件数据',
+    mcpName: 'bk-data-server', // ← 有值时头部显示"调用 MCP："
+  },
+};
+// 头部显示：调用 MCP：  bk-data-server / query_table
+```
+
+**渲染效果**
+
+## 调用失败
+
+`toolMessage.error` 有值且 `content` 为空时，`ToolMessage` 内部展示错误信息（由 `content || error` 决定）。`status` 设为 `error` 控制头部红色样式：
+
+```typescript
+const failedToolCall: ToolCall = {
+  id: 'call_1',
+  type: 'function',
+  function: {
+    name: 'execute_sql',
+    arguments: JSON.stringify({ sql: 'SELECT * FROM users' }),
+    description: '执行数据库查询',
+  },
+  toolMessage: {
+    content: '', // 空 content → ToolMessage 显示 error
+    error: 'Connection timeout: database is unreachable (5000ms)',
+    status: 'error',
+    duration: 5000,
+    toolCallId: 'call_1',
+  },
+};
+```
+
+**渲染效果**
+
+## 无 description 场景
+
+`function.description` 为可选字段，缺失时"描述"区块仍会渲染（`DescPanel` 始终存在），但内容为空白占位：
+
+## 与 AssistantMessage 配合
+
+`ToolcallRender` 通常不需要单独使用，将 `toolCalls` 传给 `AssistantMessage`，会自动为每个工具调用渲染 `ToolcallRender`：
+
+```typescript
+const assistantMessage = {
+  id: '1',
+  role: 'assistant',
+  content: '好的，我来帮你查询天气。',
+  status: 'complete',
+  toolCalls: [
+    {
+      id: 'call_1',
+      type: 'function',
+      function: {
+        name: 'get_weather',
+        arguments: '{"city":"北京"}',
+        description: '获取天气信息',
+      },
+      toolMessage: {
+        content: '{"temperature":22,"weather":"晴"}',
+        status: 'complete',
+        duration: 850,
+        toolCallId: 'call_1',
+      },
+    },
+  ],
+};
+```
+
+需要自定义遍历渲染时：
+
+```vue
+<template>
+  <ToolcallRender
+    v-for="toolCall in assistantMessage.toolCalls"
+    :key="toolCall.id"
+    :tool-call="toolCall"
+    :status="toolCall.toolMessage?.status ?? MessageStatus.Pending"
+  />
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型            | 默认值 | 说明                                                                        |
+| -------- | --------------- | ------ | --------------------------------------------------------------------------- |
+| toolCall | `ToolCall`      | —      | 工具调用信息对象                                                            |
+| status   | `MessageStatus` | —      | 调用状态，控制头部颜色和状态文案；未传时 `default` 分支显示"调用中"         |
+| duration | `number`        | —      | 调用耗时（毫秒），优先于 `toolCall.toolMessage?.duration`；均无时不显示耗时 |
+
+## 类型定义
+
+```typescript
+import {
+  MessageStatus,
+  MessageContentType,
+  type ToolCall,
+  type FunctionCall,
+  type ToolMessage,
+} from '@blueking/chat-x';
+
+// ToolCall —— 工具调用对象
+type ToolCall = {
+  id: string;
+  type: 'function'; // MessageContentType.Function
+  function: FunctionCall;
+  toolMessage?: Partial<ToolMessage>; // 有值时在详情面板底部内联渲染 ToolMessage
+};
+
+// FunctionCall —— 函数调用描述
+type FunctionCall = {
+  name: string; // 函数名；为空时标题 fallback 为 toolCall.id
+  arguments: string; // 调用参数（通常为 JSON 字符串）
+  description?: string; // 工具描述；为空时"描述"区块保留但内容为空白
+  mcpName?: string; // MCP 服务名；有值时头部改为"调用 MCP："，标题格式变为 "{mcpName} / {name}"
+};
+
+// ToolMessage —— 工具返回消息
+interface ToolMessage {
+  role: 'tool';
+  content: string; // 返回内容（通常为 JSON 字符串）
+  status: MessageStatus;
+  duration: number; // 调用耗时（毫秒），被 ToolcallRender 自动读取
+  error?: string; // 错误信息（仅当 content 为空时由 ToolMessage 展示）
+  toolCallId: string; // 对应 ToolCall.id
+}
+```
+
+## 关联组件
+
+- [DescPanel](../atomic/desc-panel.md) — 描述与参数面板
+- [HighlightKeyword](../atomic/highlight-keyword.md) — 标题高亮
+- [ToolMessage](./tool-message.md) — 内联工具返回