@blueking/chat-x 0.0.43 → 0.0.45-beta.2

package/dist/mcp/generated/docs/constants.md

@@ -36,6 +36,7 @@ enum MessageRole {
   HiddenSystem = 'hidden-system',
   HiddenUser = 'hidden-user',
   Info = 'info',
+  Interrupt = 'interrupt',
   Loading = 'loading',
   Pause = 'pause',
   Placeholder = 'placeholder',
@@ -72,6 +73,70 @@ enum MessageStatus {
 | --------------- | ---- |
 | `Fetching`      | 请求中：与 `useMessageGroup` 在末尾用户消息后注入的 Loading 占位（`LOADING_MESSAGE_ID`）配合时，`ChatContainer` 会将传入输入区与列表底部的状态推导为该值，便于展示「停止」与禁止重复发送。 |
 
+### InterruptReason
+
+human-in-the-loop 中断原因枚举，用于 `Interrupt.reason` 区分中断类型并选择对应的 UI 渲染器。
+
+```typescript
+enum InterruptReason {
+  AIDevToolApproval = 'aidev:tool_approval',
+  UserQuestion = 'aidev:user_question',
+}
+```
+
+### APPROVAL_STATUS
+
+AI Dev 工具审批单状态枚举，`AIDevToolApprovalInterrupt.metadata.ticket.status` 使用该类型。
+
+```typescript
+enum APPROVAL_STATUS {
+  ABANDONED = 'abandoned',
+  APPROVED = 'approved',
+  CANCELLED = 'cancelled',
+  DRAFT = 'draft',
+  EXPIRED = 'expired',
+  PENDING = 'pending',
+  REJECTED = 'rejected',
+  REVOKED = 'revoked',
+}
+```
+
+### APPROVAL_STATUS_MAP
+
+审批单状态到展示文案的映射，供 `ToolApprovalCard` 等组件使用：
+
+```typescript
+const APPROVAL_STATUS_MAP: Record<APPROVAL_STATUS, string> = {
+  [APPROVAL_STATUS.ABANDONED]: '已废弃',
+  [APPROVAL_STATUS.APPROVED]: '已通过',
+  [APPROVAL_STATUS.CANCELLED]: '已取消',
+  [APPROVAL_STATUS.DRAFT]: '待审批',
+  [APPROVAL_STATUS.EXPIRED]: '已过期',
+  [APPROVAL_STATUS.PENDING]: '待审批',
+  [APPROVAL_STATUS.REJECTED]: '已拒绝',
+  [APPROVAL_STATUS.REVOKED]: '已撤销',
+};
+```
+
+| 状态值      | 展示文案 |
+| ----------- | -------- |
+| `pending`   | 待审批   |
+| `draft`     | 待审批   |
+| `approved`  | 已通过   |
+| `rejected`  | 已拒绝   |
+| `cancelled` | 已取消   |
+| `expired`   | 已过期   |
+| `abandoned` | 已废弃   |
+| `revoked`   | 已撤销   |
+
+### RunFinishedOutcome
+
+AG-UI `RUN_FINISHED` 事件的结束结果类型。中断结果不再是字符串枚举，而是对象联合类型；`type: 'interrupt'` 时，中断列表放在 `interrupts` 字段中。
+
+```typescript
+type RunFinishedOutcome = { interrupts: Interrupt[]; type: 'interrupt' } | { type: 'success' };
+```
+
 ### MessageContentType
 
 消息内容类型枚举：
@@ -238,6 +303,6 @@ console.log(
 
 ## 关联组件
 
-- [MessageTools](../components/molecular/message-tools.md) — 消息工具栏
-- [ChatInput](../components/molecular/chat-input.md) — 输入与状态
-- [MessageContainer](../components/molecular/message-container.md) — 工具与消息展示
+- [MessageTools](../components/feedback/message-tools) — 消息工具栏
+- [ChatInput](../components/input/chat-input) — 输入与状态
+- [MessageContainer](../components/setup/message-container) — 工具与消息展示

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ContentRender 按消息 content 类型分发：字符串走 Markdown 管线，数组可走引用文档等；可扩展自定义 slot。 主要 props 为 content、status，与 MessageRender、AssistantMessage 等配合使用。 内置与 MarkdownContent、ReferenceContent 等原子/分子组件衔接。
+按 MessageContentType 分发 Markdown、文本、引用、键值、图片等内容。 源码位置：src/components/chat-content/content-render/content-render.vue。
 
 ### 关联组件
 - **markdown-content** — 文本类 Markdown 正文的默认渲染实现
@@ -12,8 +12,13 @@ ContentRender 按消息 content 类型分发：字符串走 Markdown 管线，
 <!-- FULL DOC -->
 
 # ContentRender 内容渲染器
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：内容渲染
+- **源码位置**：`src/components/chat-content/content-render/content-render.vue`
+- **能力域**：内容渲染
+- **能力说明**：按 MessageContentType 分发 Markdown、文本、引用、键值、图片等内容。
+
+> **能力域**：内容渲染
 
 消息内容渲染分发组件，根据 `content` 的 JavaScript 类型自动选择渲染方式：字符串 → `MarkdownContent`（Markdown 渲染），数组 → `ReferenceContent`（引用列表）。
 
@@ -234,6 +239,6 @@ enum MessageStatus {
 
 ## 关联组件
 
-- [MarkdownContent](../atomic/markdown-content.md) — 字符串 Markdown 正文
-- [ReferenceContent](../atomic/reference-content.md) — 引用文档数组
-- [AssistantMessage](./assistant-message.md) — assistant 消息中默认使用
+- [MarkdownContent](/components/rendering/markdown-content) — 字符串 Markdown 正文
+- [ReferenceContent](/components/rendering/reference-content) — 引用文档数组
+- [AssistantMessage](/components/message/assistant-message) — assistant 消息中默认使用

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

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-DeleteTool 在点击删除图标后弹出 Tippy 确认层，需再次点击「删除」才 emit confirm，避免误删。 触发器为 ToolBtn；MessageTools 在工具 id 为 delete 时用本组件替换普通 ToolBtn。
+消息删除二次确认工具。 源码位置：src/components/message-tools/delete-tool/delete-tool.vue。
 
 ### 关联组件
 - **tool-btn** — 删除图标与触发入口
@@ -11,8 +11,13 @@ DeleteTool 在点击删除图标后弹出 Tippy 确认层，需再次点击「
 <!-- FULL DOC -->
 
 # DeleteTool 删除确认按钮
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：工具与反馈
+- **源码位置**：`src/components/message-tools/delete-tool/delete-tool.vue`
+- **能力域**：工具与反馈
+- **能力说明**：消息删除二次确认工具。
+
+> **能力域**：工具与反馈
 
 删除操作的二次确认组件。点击删除图标后弹出确认弹窗，用户需再次点击"删除"按钮才会触发 `confirm` 事件，防止误删。内部由 `ToolBtn`（触发按钮）+ `Tippy`（确认弹窗）组合实现。
 
@@ -184,5 +189,5 @@ export type DeleteToolProps = IToolBtn & {
 
 ## 关联组件
 
-- [ToolBtn](../atomic/tool-btn.md) — 触发按钮
-- [MessageTools](./message-tools.md) — 工具栏中 delete 替换入口
+- [ToolBtn](/components/feedback/tool-btn) — 触发按钮
+- [MessageTools](/components/feedback/message-tools) — 工具栏中 delete 替换入口

package/dist/mcp/generated/docs/desc-panel.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-DescPanel 将描述字符串尝试 JSON 解析为键值列表展示，否则按纯文本输出，用于工具调用详情折叠区。 内部对键与值使用 HighlightKeyword 支持搜索高亮。
+将文本或 JSON 内容降级为可读描述面板。 源码位置：src/components/tool-call/desc-panel/desc-panel.vue。
 
 ### 关联组件
 - **toolcall-render** — 工具调用详情中渲染描述与参数
@@ -11,8 +11,13 @@ DescPanel 将描述字符串尝试 JSON 解析为键值列表展示，否则按
 <!-- FULL DOC -->
 
 # DescPanel 描述面板
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：辅助组件
+- **源码位置**：`src/components/tool-call/desc-panel/desc-panel.vue`
+- **能力域**：内容渲染
+- **能力说明**：将文本或 JSON 内容降级为可读描述面板。
+
+> **能力域**：内容渲染
 
 工具调用（ToolCall）详情面板的描述区域组件，主要用于 `ToolcallRender` 内部的折叠面板中。
 
@@ -134,5 +139,5 @@ JSON 数组同样被视为 `object`，以数组索引（`0:`、`1:`…）作为
 
 ## 关联组件
 
-- [ToolcallRender](../molecular/toolcall-render.md) — 主要使用场景
-- [HighlightKeyword](./highlight-keyword.md) — 键值高亮
+- [ToolcallRender](/components/agent/toolcall-render) — 主要使用场景
+- [HighlightKeyword](/components/helper/highlight-keyword) — 键值高亮

package/dist/mcp/generated/docs/detail-section.md

@@ -0,0 +1,93 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+FlowAgent 节点详情中的标题/内容分段容器。 源码位置：src/components/chat-content/flow-agent-content/detail-section.vue。
+
+### 关联组件
+- **flow-agent-node-detail** — 节点详情中用于承载基础信息、输入参数、输出参数等区块
+- **simple-table** — 常作为分段内容展示结构化参数表格
+
+---
+<!-- FULL DOC -->
+
+# DetailSection 详情分段
+
+> **能力域**：Agent 能力
+
+`DetailSection` 是 FlowAgent 节点详情页中的轻量分段容器，用于给一组相关信息提供统一标题样式。组件自身只负责渲染标题和默认插槽，不处理数据格式、折叠、空态或表格逻辑。
+
+通常不需要单独接入，主要由 `FlowAgentNodeDetail` 内部组合使用。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/flow-agent-content/detail-section.vue`
+- **能力说明**：FlowAgent 节点详情中的标题/内容分段容器。
+
+## 核心能力
+
+- **统一标题样式**：标题前带蓝色竖条，标题文本使用详情页统一字号与字重
+- **内容完全透传**：通过默认插槽承载任意内容，如基础信息表单、`SimpleTable` 或自定义说明
+- **无内部状态**：不维护折叠、加载、选择等状态，适合作为详情页布局基础块
+
+## 基础用法
+
+```vue
+<template>
+  <DetailSection title="基础信息">
+    <div class="info-row">节点名称：采集主机指标</div>
+  </DetailSection>
+</template>
+
+<script setup lang="ts">
+  import DetailSection from '@blueking/chat-x/src/components/chat-content/flow-agent-content/detail-section.vue';
+</script>
+```
+
+**渲染效果**
+
+## 搭配 SimpleTable
+
+`DetailSection` 最常见的用法是包裹结构化内容，由外层负责分段标题，内部组件负责数据展示。
+
+```vue
+<template>
+  <DetailSection title="输入参数">
+    <SimpleTable
+      :columns="columns"
+      :data="data"
+    />
+  </DetailSection>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名 | 类型     | 必填 | 默认值 | 说明     |
+| ------ | -------- | ---- | ------ | -------- |
+| title  | `string` | 是   | —      | 分段标题 |
+
+### Emits
+
+- 无。
+
+### Slots
+
+| 插槽名  | 说明             |
+| ------- | ---------------- |
+| default | 分段主体展示内容 |
+
+### Expose
+
+- 无。
+
+## 使用建议
+
+- 用于详情页内部的短分段，不建议作为通用卡片或页面 Section 使用。
+- 内容空态应由插槽内组件自行处理，`DetailSection` 不会主动显示空态。
+
+## 关联组件
+
+- [FlowAgentNodeDetail](./flow-agent-node-detail.md) — 节点详情主体。
+- [SimpleTable](./simple-table.md) — 分段内常用的轻量表格。

package/dist/mcp/generated/docs/execution-summary.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-ExecutionSummary 以时间线汇总工具调用与 FlowAgent 等活动记录，支持关键词过滤与 HighlightKeyword 高亮。 点击可 emit 定位到会话中对应消息；内部用 MessageRender 渲染摘要条目中的消息片段。
+按消息流提取执行摘要，支持关键词定位和消息渲染。 源码位置：src/components/execution-summary/execution-summary.vue。
 
 ### 关联组件
 - **message-render** — 摘要列表内渲染消息内容
@@ -12,8 +12,13 @@ ExecutionSummary 以时间线汇总工具调用与 FlowAgent 等活动记录，
 <!-- FULL DOC -->
 
 # ExecutionSummary 执行摘要
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：辅助组件
+- **源码位置**：`src/components/execution-summary/execution-summary.vue`
+- **能力域**：Agent 能力
+- **能力说明**：按消息流提取执行摘要，支持关键词定位和消息渲染。
+
+> **能力域**：Agent 能力
 
 执行摘要面板组件，以时间线形式展示对话中的工具调用和 FlowAgent 活动记录。支持关键词搜索过滤和点击定位到对话中的消息位置。
 
@@ -121,6 +126,6 @@ interface MessageGroup {
 
 ## 关联组件
 
-- [MessageRender](./message-render.md) — 摘要内消息渲染
-- [HighlightKeyword](../atomic/highlight-keyword.md) — 搜索高亮
-- [ChatContainer](./chat-container.md) — 侧栏挂载场景
+- [MessageRender](/components/message/message-render) — 摘要内消息渲染
+- [HighlightKeyword](/components/helper/highlight-keyword) — 搜索高亮
+- [ChatContainer](/components/setup/chat-container) — 侧栏挂载场景

package/dist/mcp/generated/docs/file-content.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-FileContent 展示消息或输入区附件列表：图片显示缩略图并可进入 ImagePreview，文档以卡片展示文件名、类型与大小。 支持删除、图片加载失败占位及仅有远端文件名的降级展示。
+渲染文件附件，支持图片预览和下载事件。 源码位置：src/components/chat-content/file-content/file-content.vue。
 
 ### 关联组件
 - **image-preview** — 点击图片缩略图打开全屏预览
@@ -11,8 +11,13 @@ FileContent 展示消息或输入区附件列表：图片显示缩略图并可
 <!-- FULL DOC -->
 
 # FileContent 文件内容展示
+## 源码事实
 
-> **层级**：分子组件 · **功能域**：文件与图片
+- **源码位置**：`src/components/chat-content/file-content/file-content.vue`
+- **能力域**：媒体文件
+- **能力说明**：渲染文件附件，支持图片预览和下载事件。
+
+> **能力域**：媒体文件
 
 文件列表展示组件，支持图片缩略图预览、点击图片全屏预览（`ImagePreview`）、文档卡片展示（文件名/扩展名/文件大小）、图片加载失败占位和删除操作。
 
@@ -296,5 +301,5 @@ const formatFileSize = (file?: File): string => {
 
 ## 关联组件
 
-- [ImagePreview](./image-preview.md) — 图片全屏预览
-- [UserMessage](./user-message.md) — 用户消息内附件展示
+- [ImagePreview](/components/medias/image-preview) — 图片全屏预览
+- [UserMessage](/components/message/user-message) — 用户消息内附件展示

package/dist/mcp/generated/docs/file-upload-btn.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-FileUploadBtn 提供隐藏 file input 与图标按钮，选择后在按钮层过滤空文件与超大单文件并 emit upload； 个数上限不在此截断，由 ChatInput 等与 FileContent 配合完成「选择 → 展示 → 发送」链路。
+文件选择按钮，封装 input[type=file] 并输出选择事件。 源码位置：src/components/ai-buttons/file-upload-btn/file-upload-btn.vue。
 
 ### 关联组件
 - **chat-input** — 输入区附件上传按钮常见挂载位置
@@ -11,8 +11,13 @@ FileUploadBtn 提供隐藏 file input 与图标按钮，选择后在按钮层过
 <!-- FULL DOC -->
 
 # FileUploadBtn 文件上传按钮
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：文件与图片
+- **源码位置**：`src/components/ai-buttons/file-upload-btn/file-upload-btn.vue`
+- **能力域**：输入交互
+- **能力说明**：文件选择按钮，封装 input[type=file] 并输出选择事件。
+
+> **能力域**：输入交互
 
 聊天输入框内置的文件上传触发按钮，点击后弹出系统文件选择框。内部包含隐藏的 `<input type="file">` 与可见的图标按钮；在按钮层对**单文件**做大小与空文件过滤，**已选文件个数上限**由上层（如 `ChatInput`）统一校验并提示，避免按钮与输入区各弹一条错误提示。
 
@@ -56,7 +61,7 @@ FileUploadBtn 提供隐藏 file input 与图标按钮，选择后在按钮层过
 
 > `multiple` prop 声明存在但当前模板中 `input` 的 `multiple` 属性为**硬编码**（非 `:multiple="multiple"` 绑定），始终允许多选，该 prop 暂时无实际效果。
 
-> **`maxFiles` prop**：当前版本在按钮内**不参与截断或计数校验**，仅作类型与文档预留；列表最多几个文件由上层（如 `ChatInput` 的 `MAX_UPLOAD_FILES`）控制。详见 [ChatInput 文件上传](../molecular/chat-input.md#file-upload)。
+> **`maxFiles` prop**：当前版本在按钮内**不参与截断或计数校验**，仅作类型与文档预留；列表最多几个文件由上层（如 `ChatInput` 的 `MAX_UPLOAD_FILES`）控制。详见 [ChatInput 文件上传](/components/input/chat-input#file-upload)。
 
 ## 基础用法
 
@@ -149,10 +154,10 @@ FileUploadBtn 提供隐藏 file input 与图标按钮，选择后在按钮层过
 ```typescript
 import type { TippyOptions } from 'vue-tippy';
 
-type AITippyProps = Partial<Pick<TippyOptions, 'appendTo' | 'placement' | 'zIndex'>>;
+type AITippyProps = Partial<Omit<TippyOptions, 'content' | 'getReferenceClientRect' | 'theme' | 'triggerTarget'>>;
 ```
 
 ## 关联组件
 
-- [ChatInput](../molecular/chat-input.md) — 默认内置上传入口
-- [FileContent](../molecular/file-content.md) — 选中文件列表展示
+- [ChatInput](/components/input/chat-input) — 默认内置上传入口
+- [FileContent](/components/medias/file-content) — 选中文件列表展示

package/dist/mcp/generated/docs/flow-agent-content.md

@@ -0,0 +1,212 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+渲染 FlowAgent 任务/节点执行状态、耗时、详情入口和自定义 Tab 联动。 源码位置：src/components/chat-content/flow-agent-content/flow-agent-content.vue。
+
+### 关联组件
+- **flow-agent-node-detail** — 详情入口点击后挂载到自定义 Tab 渲染
+- **activity-layout** — 提供可折叠的活动容器外壳
+- **chat-container** — 通过自定义 Tab 在侧栏展示节点详情
+
+---
+<!-- FULL DOC -->
+
+# FlowAgentContent FlowAgent 执行内容
+
+> **能力域**：Agent 能力
+
+渲染 FlowAgent（标准运维 / 流程编排）执行过程的活动组件，以「任务 → 节点」两级结构展示执行状态、耗时统计与详情入口。组件内部消费 `useCustomTabConsumer`，点击节点「详情」会向侧栏的自定义 Tab 注入 `FlowAgentNodeDetail` 渲染节点输入输出。
+
+通常不需要直接使用，`MessageRender` 会根据消息 `content.type === flow_agent` 自动渲染。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/flow-agent-content/flow-agent-content.vue`
+- **能力说明**：渲染 FlowAgent 任务/节点执行状态、耗时、详情入口和自定义 Tab 联动。
+
+## 核心能力
+
+- **状态聚合统计**：汇总所有任务的 `statistics.state_counts`，在标题栏按「执行中 / 成功 / 失败 / 挂起 / 待执行」分类展示带颜色的计数（超过 99 显示 `99+`）
+- **两级折叠**：任务整体由 `ActivityLayout` 折叠；每个任务节点列表可单独展开/收起
+- **耗时格式化**：节点耗时与任务总耗时按 `d/h/m/s` 紧凑展示，小于 1 秒显示 `<1s`
+- **详情入口联动**：hover 节点行显示「详情」按钮，点击后通过自定义 Tab 挂载 `FlowAgentNodeDetail`
+- **分享态降级**：`RenderMode.Share` 下隐藏耗时与详情入口，仅保留只读的执行状态
+
+## 状态映射
+
+组件将后端原始 `state` / `task_state` 归一为 5 类收敛状态（`getConvergedState`），用于图标、颜色与统计分类：
+
+| 收敛状态    | 颜色        | 原始状态                                                                          |
+| ----------- | ----------- | --------------------------------------------------------------------------------- |
+| `success`   | `#18B456`   | `FINISHED`                                                                        |
+| `failed`    | `#EA3636`   | `FAILED`、`REVOKED`、`ROLL_BACK_FAILED`                                            |
+| `suspended` | `#F59500`   | `SUSPENDED`                                                                       |
+| `pending`   | `#4D4F56`   | `PENDING`                                                                         |
+| `running`   | `#3A84FF`   | `CREATED`、`LOOP_READY`、`READY`、`RUNNING`、`BLOCKED`、`ROLLING_BACK`、`ROLL_BACK_SUCCESS` 及未知状态（兜底） |
+
+## 基础用法
+
+`content` 为任务数组 `BkFlowTask[]`；传入单个对象时组件会自动包装为单元素数组。
+
+```vue
+<template>
+  <FlowAgentContent
+    :content="flowContent"
+    :message-uid="messageUid"
+    :status="status"
+  />
+</template>
+
+<script setup lang="ts">
+  import { FlowAgentContent } from '@blueking/chat-x';
+  import type { BkFlowMessageContent } from '@blueking/chat-x';
+
+  const messageUid = 'flow-msg-1';
+  const status = 'success';
+  const flowContent: BkFlowMessageContent = [
+    {
+      task_id: 100,
+      task_name: '主机巡检流程',
+      task_state: 'FINISHED',
+      task_outputs: { result: 'ok' },
+      statistics: { state_counts: { FINISHED: 2, FAILED: 1 }, total: 3 },
+      nodes: {
+        n1: { id: 'n1', name: '采集主机指标', state: 'FINISHED', elapsed_time: 12, type: 'task', loop: 0, retry: 0, skip: false, start_time: '', finish_time: '' },
+        n2: { id: 'n2', name: '分析异常项', state: 'FINISHED', elapsed_time: 65, type: 'task', loop: 0, retry: 0, skip: false, start_time: '', finish_time: '' },
+        n3: { id: 'n3', name: '推送告警', state: 'FAILED', elapsed_time: 3, type: 'task', loop: 0, retry: 1, skip: false, start_time: '', finish_time: '' },
+      },
+    },
+  ];
+</script>
+```
+
+**渲染效果**（hover 节点行可看到耗时切换为「详情」按钮，点击会向侧栏自定义 Tab 注入节点详情）
+
+## 执行中状态
+
+`status` 为 `pending` / `streaming` 时，标题栏图标显示为加载动画；运行中的节点显示旋转 Loading，待执行 / 挂起节点显示对应颜色的状态点。
+
+## 节点详情联动
+
+点击节点「详情」按钮时，组件调用 `addCustomTab` 注入一个以 `${task_id}|${node.id}|${node.name}` 为唯一 `name` 的 Tab，渲染组件为 `FlowAgentNodeDetail`：
+
+```ts
+addCustomTab?.({
+  label: node.name,
+  name: `${task.task_id}|${node.id}|${node.name}`,
+  data: {
+    component: BkFlowNodeDetail,
+    messageUid: props.messageUid,
+    props: {
+      loading: true,
+      node_id: node.id,
+      node_name: node.name,
+      task_id: task.task_id,
+      task_name: task.task_name,
+      data: {},
+    },
+  },
+});
+```
+
+> 实际节点详情数据由应用层在 `ChatContainer` 的 `onCustomTabChange` 中异步拉取后回填，组件本身只负责挂载占位与传参。组件卸载时（在消息容器滚动上下文中）会自动调用 `removeCustomTab` 清理对应 Tab。
+
+## 组件结构
+
+```
+ActivityLayout（activity-type=flow_agent，v-model:collapsed）
+├── #title（执行情况统计栏）
+│   ├── AiLoading / ArrowRightIcon（加载态 / 折叠箭头）
+│   └── flow-agent-stat-item × N（按收敛状态分类的计数）
+└── flow-agent-task-group × N（任务）
+    ├── flow-agent-task-header（点击折叠当前任务）
+    │   ├── task-arrow（任务展开箭头）
+    │   ├── task-state-icon（Loading / 状态图标）
+    │   ├── task-name（HighlightKeyword + 溢出提示）
+    │   └── task-time（任务总耗时 = 各节点耗时累加）
+    └── flow-agent-task-nodes（v-show 折叠）
+        └── flow-agent-node-item × N（节点）
+            ├── node-status（Loading / 状态圆点）
+            ├── node-name（HighlightKeyword + 溢出提示）
+            └── node-trailing（非 Share 态）
+                ├── node-time（节点耗时，hover 时隐藏）
+                └── node-detail-btn（hover 时显示，点击挂载详情 Tab）
+```
+
+## API
+
+### Props
+
+| 属性名     | 类型                     | 必填 | 默认值      | 说明                                                                       |
+| ---------- | ------------------------ | ---- | ----------- | -------------------------------------------------------------------------- |
+| content    | `BkFlowMessageContent`   | 否   | `[{}]`      | 任务数组；传入单个 `BkFlowTask` 时自动包装为单元素数组                       |
+| messageUid | `string`                 | 否   | —           | 所属消息唯一标识，注入到节点详情 Tab 的 `data.messageUid`，用于异步回填数据 |
+| status     | `MessageStatus`          | 否   | —           | 消息状态；`pending` / `streaming` 时标题栏显示加载动画                       |
+
+### Emits
+
+- 无。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 类型定义
+
+```typescript
+// 来自 @blueking/chat-x 导出
+type BkFlowMessageContent = BkFlowTask[];
+
+interface BkFlowTask {
+  task_id: number;
+  task_name: string;
+  task_state: string;          // 原始任务状态，经 getConvergedState 归一
+  task_outputs: unknown;       // 任务输出（当前展示区块已注释，不渲染）
+  statistics: {
+    state_counts: Record<string, number>; // 原始状态 → 数量，用于标题统计聚合
+    total: number;
+  };
+  nodes: Record<string, BkFlowNode>;       // key 为节点 id
+}
+
+interface BkFlowNode {
+  id: string;
+  name: string;
+  state: string;        // 原始节点状态
+  elapsed_time: number; // 耗时（秒）
+  type: string;
+  loop: number;
+  retry: number;
+  skip: boolean;
+  start_time: string;
+  finish_time: string;
+}
+```
+
+## 组件依赖
+
+- `AiLoading` — 标题栏流式加载动画
+- `ActivityLayout` — 可折叠活动容器外壳
+- `BkFlowNodeDetail` — 节点详情面板（经自定义 Tab 挂载）
+- `Loading`（bkui-vue） — 运行中状态的旋转指示
+- `HighlightKeyword` — 任务 / 节点名称的搜索关键词高亮
+
+## 注意事项
+
+1. **依赖自定义 Tab 上下文**：组件内部使用 `useCustomTabConsumer()!`，必须存在 `useCustomTabProvider` 提供者（`ChatContainer` 已内置）。脱离上下文直接使用需自行提供，否则详情入口会报错。
+2. **统计来自 `statistics.state_counts` 而非节点遍历**：标题栏计数直接读取后端下发的统计，不会实时统计 `nodes`；两者不一致时以 `state_counts` 为准。
+3. **任务总耗时为节点累加**：`task-time` 由各节点 `elapsed_time` 求和得到，并非任务级独立字段。
+4. **`task_outputs` 暂不渲染**：模板中任务输出展示区块已注释，传入也不会显示。
+5. **未知状态兜底为 `running`**：`getConvergedState` 对未识别的原始状态统一归为运行中。
+6. **Share 模式降级**：`RenderMode.Share` 下不渲染节点耗时与「详情」按钮，仅保留只读执行状态。
+
+## 关联组件
+
+- [FlowAgentNodeDetail](/components/agent/flow-agent-node-detail) — 节点详情面板
+- [ActivityLayout](/components/helper/activity-layout) — 可折叠活动容器
+- [ChatContainer](/components/setup/chat-container) — 侧栏自定义 Tab 挂载场景
+- [使用建议] 优先通过上层组合组件（`MessageRender`）使用；直接使用前请确认 `content` 数据结构来自对应类型定义。