@blueking/chat-x 0.0.50 → 0.0.51-beta.2

package/skills/blueking-chat-x/references/components/file-icon.md

@@ -0,0 +1,109 @@
+# FileIcon 文件类型图标
+
+> 能力域：辅助能力 ｜ 导入：`import { FileIcon } from '@blueking/chat-x'` ｜ since 1.0.0
+
+按扩展名渲染文件类型图标：内联 svg，尺寸用 1em 跟随外层 font-size； 扩展名解析走 normalizeFileExtension（优先 fileType，缺省回退 fileName，大小写不敏感， 支持 Dockerfile / .gitignore 这类无扩展名或点号开头的文件）；未登记类型返回 unknown 兜底图标。 源码位置：src/components/file-icon/file-icon.vue，图标注册表在 src/icons/file-icons.ts。
+
+**关联**：file-artifact-panel（文件产物列表与预览头使用该组件展示类型图标）、assistant-message（消息内的文件产物卡片使用该组件）
+
+---
+
+# FileIcon 文件类型图标
+
+> **能力域**：辅助能力
+
+`FileIcon` 按文件扩展名渲染对应的类型图标，用于文件列表、附件卡片、产物预览头等需要「一眼看出这是什么文件」的场景。图标以内联 svg 形式打进包内，不产生额外网络请求，也不需要消费方配置静态资源路径。
+
+## 源码事实
+
+- **源码位置**：`src/components/file-icon/file-icon.vue`
+- **图标注册表**：`src/icons/file-icons.ts`（导出 `getFileIconSvg` / `UNKNOWN_FILE_ICON_SVG`）
+- **扩展名解析**：`src/utils/file-type.ts` 的 `normalizeFileExtension`
+
+## 核心能力
+
+- **扩展名驱动**：优先取 `fileType`，缺省时回退 `fileName` 推断；大小写不敏感
+- **特殊文件名**：`Dockerfile` / `Makefile` 这类无扩展名文件，以及 `.gitignore` / `.editorconfig` 这类点号开头的文件都能正确命中
+- **多扩展名共用图标**：如 `xlsx` / `xls` / `csv` / `tsv` 共用表格图标，`tsx` / `jsx` 共用 React 图标
+- **兜底不报错**：未登记的扩展名返回 `unknown` 图标，后台新增文件类型时前端不会缺图
+- **尺寸自适应**：内部 svg 固定为 `1em`，直接用外层 `font-size` 控制大小
+
+## 基础用法
+
+```vue
+<template>
+  <FileIcon file-type="pdf" />
+</template>
+
+<script setup lang="ts">
+  import { FileIcon } from '@blueking/chat-x';
+</script>
+```
+
+**渲染效果**
+
+## 从文件名推断
+
+后台未下发 `type` 时传 `fileName` 即可，组件会取最后一段扩展名：
+
+```vue
+<template>
+  <!-- 取 xlsx -->
+  <FileIcon file-name="季度报告.final.xlsx" />
+  <!-- 取 gitignore -->
+  <FileIcon file-name=".gitignore" />
+</template>
+```
+
+两者同时传入时以 `fileType` 优先。
+
+## 控制尺寸
+
+图标宽高为 `1em`，用外层 `font-size` 控制即可，无需改 svg：
+
+```vue
+<template>
+  <span style="font-size: 16px"><FileIcon file-type="py" /></span>
+  <span style="font-size: 32px"><FileIcon file-type="py" /></span>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型     | 必填 | 默认值      | 说明                                                     |
+| -------- | -------- | ---- | ----------- | -------------------------------------------------------- |
+| fileType | `string` | 否   | `undefined` | 文件类型：扩展名（如 `pdf` / `py`）或无扩展名文件名（如 `Dockerfile`） |
+| fileName | `string` | 否   | `undefined` | 文件名，`fileType` 缺省时用于推断扩展名                    |
+
+两者都不传时渲染兜底图标。
+
+### Emits / Slots / Expose
+
+- 无。
+
+## 图标覆盖范围
+
+| 图标 | 覆盖扩展名 |
+| ---- | ---------- |
+| 文档类 | `pptx` / `docx` / `pdf` / `txt` / `rst` / `md` / `markdown` / `tex` |
+| 表格类 | `xlsx` / `xlsm` / `xls` / `csv` / `tsv` |
+| 前端 | `html` / `htm` / `css` / `scss` / `less` / `js` / `mjs` / `cjs` / `ts` / `tsx` / `jsx` / `vue` / `xml` |
+| 后端 / 系统 | `py` / `go` / `rs` / `rb` / `java` / `kt` / `swift` / `c` / `h` / `cpp` / `hpp` / `cs` / `php` / `lua` / `r` / `scala` / `dart` / `sql` / `sh` / `bash` / `zsh` / `ps1` |
+| 配置 | `json` / `jsonc` / `yaml` / `yml` / `toml` / `ini` / `cfg` / `conf` / `env` / `editorconfig` / `Makefile` |
+| 工具链 | `Dockerfile` / `dockerignore` / `gitignore` |
+| 图片 | `png` / `jpg` / `jpeg` / `svg` |
+| 兜底 | 以上之外的所有类型 |
+
+新增类型时在 `src/icons/file-icons.ts` 的 `FILE_ICON_GROUPS` 里补一行即可；对应 svg 需先放进 `src/svgs/` 并按需 `?raw` 引入（只引实际用到的，避免把整个图标库打进产物）。
+
+## 使用建议
+
+- 图标颜色由 svg 自带，不继承 `currentColor`，不要试图用 `color` 覆盖
+- 需要与文件名同行展示时，给父容器设 `display: flex` + `gap`，组件本身已是 `inline-flex` 且 `flex-shrink: 0`
+
+## 关联组件
+
+- [FileArtifactPanel](../message/file-artifact-panel.md) — 文件产物列表与预览头使用该组件。
+- [AssistantMessage](../message/assistant-message.md) — 消息内文件产物卡片的图标来源。

package/skills/blueking-chat-x/references/components/file-upload-btn.md

@@ -0,0 +1,159 @@
+# FileUploadBtn 文件上传按钮
+
+> 能力域：输入交互 ｜ 导入：`import { FileUploadBtn } from '@blueking/chat-x'` ｜ since 1.0.0
+
+文件选择按钮，封装 input[type=file] 并输出选择事件。 源码位置：src/components/ai-buttons/file-upload-btn/file-upload-btn.vue。
+
+**关联**：chat-input（输入区附件上传按钮常见挂载位置）、file-content（选中文件常以列表形式展示待发送内容）
+
+---
+
+# FileUploadBtn 文件上传按钮
+## 源码事实
+
+- **源码位置**：`src/components/ai-buttons/file-upload-btn/file-upload-btn.vue`
+- **能力域**：输入交互
+- **能力说明**：文件选择按钮，封装 input[type=file] 并输出选择事件。
+
+> **能力域**：输入交互
+
+聊天输入框内置的文件上传触发按钮，点击后弹出系统文件选择框。内部包含隐藏的 `<input type="file">` 与可见的图标按钮；**不限制文件类型**，在按钮层只对**单文件**做大小与空文件过滤，**已选文件个数上限**由上层（如 `ChatInput`）统一校验并提示，避免按钮与输入区各弹一条错误提示。
+
+## 组件结构
+
+```
+.ai-file-upload-btn（display: flex，align-items: center）
+├── input[type="file"]（.file-upload-btn-input，display: none，multiple，:accept）
+│     accept 缺省时不下发该属性，系统选择框不过滤任何类型
+│     触发后走 handleFileInputChange → 校验 → emit upload → target.value = ''
+└── span.ai-shortcut-btn.file-upload-btn-icon（热区 32×32px / 圆角 8px；图标字号跟随 --ai-icon-size-sm：small=16px、normal=18px；color: #979ba5；hover: #f0f1f5）
+      v-tippy: "上传文件，最多支持 {count} 个，单个最大 {size}MB"
+        （{count} / {size} 由 MAX_UPLOAD_FILES 与 MAX_UPLOAD_FILE_SIZE 运行时填充，theme: ai-chat-box，offset: [0, 16]，可通过 tippyOptions 扩展）
+      @click → fileInputRef.click()
+      └── <slot> 默认：FileUploadIcon
+```
+
+## 文件校验逻辑
+
+```
+用户选择文件
+  │
+  ├─ 遍历所选文件：size > 0 且 size < MAX_UPLOAD_FILE_SIZE（约 2.4MB）→ 加入 toEmit
+  │       size 为 0 或 ≥ 上限 → sizeRejected += 1
+  │
+  ├─ sizeRejected > 0 → bkui-vue Message.error（formatUploadNotAddedMessage，说明可能超大或超出个数等）
+  │
+  ├─ toEmit.length > 0 → emit('upload', toEmit)
+  │
+  └─ target.value = ''（重置 input，允许再次选择同一文件）
+```
+
+**关键边界行为**：
+
+| 场景                                                         | 结果                                                                 |
+| ------------------------------------------------------------ | -------------------------------------------------------------------- |
+| 一次多选超过上层允许个数（如 `ChatInput` 内已达 3 个）       | 由 **ChatInput** 侧 toast 并丢弃/不计入，不在本按钮内按个数提前拦截 |
+| 部分文件因空文件或单文件超大被过滤                           | 弹出错误 toast；若仍有合法文件，**仍触发** `upload`（payload 为合法子集） |
+| 全部被过滤（均为空或超大）                                   | 仅 toast，**不触发** `upload`                                        |
+| `file.size === 0`                                          | 计入未添加提示，不进入 `upload` payload                              |
+| `file.size >= MAX_UPLOAD_FILE_SIZE`（与全局常量一致，约 2.4MB） | 计入未添加提示，不进入 `upload` payload（比较为严格 `<`）           |
+| 选择后取消                                                   | `files.length === 0`，不触发 `upload`                                |
+
+> `multiple` prop 声明存在但当前模板中 `input` 的 `multiple` 属性为**硬编码**（非 `:multiple="multiple"` 绑定），始终允许多选，该 prop 暂时无实际效果。
+
+> **文件类型不做限制**：组件不再默认 `accept="image/*"`，任意类型文件都可选择。若业务需要收窄，显式传入 `accept`。个数上限由上层（如 `ChatInput` 的 `MAX_UPLOAD_FILES`）控制，详见 [ChatInput 文件上传](/components/input/chat-input#file-upload)。
+
+## 基础用法
+
+```vue
+<template>
+  <FileUploadBtn @upload="handleUpload" />
+</template>
+
+<script setup lang="ts">
+  import { FileUploadBtn } from '@blueking/chat-x';
+
+  const handleUpload = (files: File[]) => {
+    console.log(
+      '选中文件:',
+      files.map(f => `${f.name}(${f.size}B)`),
+    );
+  };
+</script>
+```
+
+## 限制文件类型
+
+默认**不限制**文件类型。需要收窄时通过 `accept` 属性控制系统文件选择框的过滤条件，遵循 `<input type="file">` 的 `accept` 规范：
+
+```vue
+<template>
+  <!-- 不限制类型（默认，不下发 accept） -->
+  <FileUploadBtn @upload="handleUpload" />
+
+  <!-- 仅图片 -->
+  <FileUploadBtn
+    accept="image/*"
+    @upload="handleUpload"
+  />
+
+  <!-- 文档类型 -->
+  <FileUploadBtn
+    accept=".pdf,.doc,.docx,.xlsx,.pptx"
+    @upload="handleUpload"
+  />
+</template>
+```
+
+> `accept` 仅影响文件选择框的过滤 UI，不做服务端验证，请在 `upload` 回调中自行校验 MIME 类型。
+
+## 自定义图标
+
+通过默认插槽替换上传图标：
+
+```vue
+<template>
+  <FileUploadBtn @upload="handleUpload">
+    <span style="font-size: 16px; line-height: 1;">📎</span>
+  </FileUploadBtn>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型           | 默认值 | 说明                                                                       |
+| ------------ | -------------- | ------ | -------------------------------------------------------------------------- |
+| accept       | `string`       | —      | 文件选择框过滤类型，遵循 `<input accept>` 规范；缺省时不下发，不限制类型 |
+| multiple     | `boolean`      | `true` | 声明属性（当前版本未实际绑定到 input，始终多选）                           |
+| tippyOptions | `AITippyProps` | —      | 扩展 tooltip 配置，会与内置配置合并                                        |
+
+### Events
+
+| 事件名 | 参数              | 说明                                                                                      |
+| ------ | ----------------- | ----------------------------------------------------------------------------------------- |
+| upload | `(files: File[])` | 当存在至少一个合法文件时触发；`files` 为过滤掉空文件与单文件超大（`size >= MAX_UPLOAD_FILE_SIZE`，约 2.4MB）后的数组；个数截断不在此组件内完成 |
+
+### Slots
+
+| 插槽名  | 说明                                            |
+| ------- | ----------------------------------------------- |
+| default | 自定义按钮图标内容，默认为内置 `FileUploadIcon` |
+
+## 使用场景
+
+`FileUploadBtn` 由 `ChatInput` 组件内置，当 `ChatInput` 的 `supportUpload` prop 为 `true`（默认值）时自动渲染。一般不需要单独引入，除非构建完全自定义的输入区域。
+
+## 类型定义
+
+```typescript
+import type { TippyOptions } from 'vue-tippy';
+
+type AITippyProps = Partial<Pick<TippyOptions, 'appendTo' | 'placement' | 'zIndex'>>;
+```
+
+## 关联组件
+
+- [ChatInput](/components/input/chat-input) — 默认内置上传入口
+- [FileContent](/components/medias/file-content) — 选中文件列表展示

package/skills/blueking-chat-x/references/components/flow-agent-content.md

@@ -0,0 +1,264 @@
+# FlowAgentContent FlowAgent 执行内容
+
+> 能力域：Agent 能力 ｜ 导入：`import { FlowAgentContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+渲染 FlowAgent 任务/节点执行状态、耗时、详情入口和自定义 Tab 联动。 源码位置：src/components/chat-content/flow-agent-content/flow-agent-content.vue。
+
+**关联**：flow-agent-node-detail（详情入口点击后挂载到自定义 Tab 渲染）、activity-layout（提供可折叠的活动容器外壳）、chat-container（通过自定义 Tab 在侧栏展示节点详情）
+
+---
+
+# 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 失败节点行显示「重试 / 跳过 / 详情」按钮组（间距 12px）；成功 / 运行中等非失败节点仅显示「详情」。重试 / 跳过依赖节点 `retryable` / `skippable` 能力位，通过 `onInterruptResume` 回传 Agent
+- **重试 / 跳过进行中态**：点击后节点行进入 `is-pending`，按钮组常驻显示（无需 hover）；进行中按钮切换为 loading +「重试中 / 跳过中」，重试与跳过互斥禁用；被阻塞按钮 hover 显示提示（如「任务正在重试中，不可跳过」）；详情不受影响。pending 以 `task_id:node_id:retry` 为键，后端 `retry` 计数变化后自动失效
+- **详情入口联动**：「详情」按钮点击后通过自定义 Tab 挂载 `FlowAgentNodeDetail`
+- **分享态只读查看**：`RenderMode.Share` 下保留耗时、「详情」「有效证据」等只读查看入口，仅隐藏「重试 / 跳过」等交互式 resume 操作
+
+## 状态映射
+
+组件将后端原始 `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"
+    :on-interrupt-resume="handleInterruptResume"
+    :status="status"
+  />
+</template>
+
+<script setup lang="ts">
+  import { FlowAgentContent } from '@blueking/chat-x';
+  import type { BkFlowMessageContent, OnInterruptResume } from '@blueking/chat-x';
+
+  const messageUid = 'flow-msg-1';
+  const status = 'success';
+  const handleInterruptResume: OnInterruptResume = async payload => {
+    console.log('flow node resume:', payload);
+  };
+  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, retryable: true, skippable: true, start_time: '', finish_time: '' },
+      },
+    },
+  ];
+</script>
+```
+
+**渲染效果**（hover 失败节点行可看到「重试 / 跳过 / 详情」按钮组；点击「详情」会向侧栏自定义 Tab 注入节点详情）
+
+## 执行中状态
+
+`status` 为 `pending` / `streaming` 时，标题栏图标显示为加载动画；运行中的节点显示旋转 Loading，待执行 / 挂起节点显示对应颜色的状态点。
+
+## 失败节点重试 / 跳过
+
+失败节点（`convergedState === 'failed'`）且具备对应能力位时，hover 行尾展示「重试」或「跳过」按钮。点击后：
+
+1. 节点行添加 `is-pending` class，按钮组常驻显示（设计稿：鼠标移出后仍可见进行中反馈）
+2. 被点击按钮进入 loading +「重试中 / 跳过中」，重试与跳过均禁用（`is-disabled`，置灰色 `#c4c6cc`）
+3. 另一按钮 hover 显示阻塞提示（`v-tippy`）
+4. 调用 `onInterruptResume`，**不传** `interrupt` 参数；进行中重复点击被 `handleActionClick` 拦截
+
+```typescript
+// 组件层点击分发（禁用态不执行 run）
+const handleActionClick = (action: FlowNodeActionVM) => {
+  if (action.disabled) return;
+  action.run();
+};
+```
+
+```typescript
+// 重试
+onInterruptResume?.({
+  operation: InterruptResumeOperation.FlowNodeRetry,
+  payload: { node_id: node.id, task_id: task.task_id },
+});
+
+// 跳过
+onInterruptResume?.({
+  operation: InterruptResumeOperation.FlowNodeSkip,
+  payload: { node_id: node.id, task_id: task.task_id },
+});
+```
+
+| 按钮 | 显隐条件                              | 进行中表现                         | `operation`          |
+| ---- | ------------------------------------- | ---------------------------------- | ---------------------- |
+| 重试 | 失败态且 `node.retryable === true`    | loading +「重试中」，二者均禁用    | `flow_node_retry`      |
+| 跳过 | 失败态且 `node.skippable === true`    | loading +「跳过中」，二者均禁用    | `flow_node_skip`       |
+| 详情 | 始终展示（含 Share 分享态）           | 不受 pending 影响                  | —（打开侧栏 Tab，不走 resume） |
+
+行尾操作由内部 composable [`useFlowNodeActions`](/composables/use-flow-node-actions) 聚合为声明式列表，组件层仅遍历渲染。
+
+## 节点详情联动
+
+点击节点「详情」按钮时，组件调用 `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（节点；`is-pending` 时按钮组常驻）
+            ├── node-status（Loading / 状态圆点）
+            ├── node-name（HighlightKeyword + 溢出提示）
+            └── node-trailing（含 Share 分享态）
+                ├── node-time（节点耗时，hover / pending 时隐藏）
+                └── node-actions（hover 或 `is-pending` 时显示，间距 12px）
+                    ├── node-action-btn「重试」（失败 + retryable；Share 态隐藏；进行中 loading + 禁用）
+                    ├── node-action-btn「跳过」（失败 + skippable；Share 态隐藏；进行中 loading + 禁用）
+                    └── node-action-btn「详情」（始终可用，含 Share 态，点击挂载详情 Tab）
+```
+
+## API
+
+### Props
+
+| 属性名     | 类型                     | 必填 | 默认值      | 说明                                                                       |
+| ---------- | ------------------------ | ---- | ----------- | -------------------------------------------------------------------------- |
+| content    | `BkFlowMessageContent`   | 否   | `[{}]`      | 任务数组；传入单个 `BkFlowTask` 时自动包装为单元素数组                       |
+| messageUid | `string`                 | 否   | —           | 所属消息唯一标识，注入到节点详情 Tab 的 `data.messageUid`，用于异步回填数据 |
+| onInterruptResume | `OnInterruptResume` | 否   | —           | 节点「重试 / 跳过」与第三方审批取消复用同一回调，按 `payload.operation` 分流；流程节点操作时不传 `interrupt` |
+| 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;
+  retryable?: boolean; // 是否可重试（失败节点「重试」按钮显隐）
+  skip: boolean;
+  skippable?: 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` 下保留节点/任务耗时与「详情」「有效证据」查看入口，仅过滤「重试 / 跳过」等交互式 resume 操作（由 `useFlowNodeActions` 的 `hideResumeActions` 收敛）。
+7. **`onInterruptResume` 透传链路**：`MessageRender` → `ActivityMessage` → `FlowAgentContent`；未传入时重试 / 跳过按钮仍展示但点击无回调。
+8. **pending 自动收敛**：`useFlowNodeActions` 以 `task_id:node_id:retry` 为 pending 键；节点重试再次失败（`retry` +1）后键变化，进行中态自动解除，无需手动清理。
+
+## 关联组件
+
+- [FlowAgentNodeDetail](/components/agent/flow-agent-node-detail) — 节点详情面板
+- [ActivityLayout](/components/helper/activity-layout) — 可折叠活动容器
+- [ChatContainer](/components/setup/chat-container) — 侧栏自定义 Tab 挂载场景
+- [useFlowNodeActions](/composables/use-flow-node-actions) — 节点行尾操作聚合 composable
+- [中断类型 Interrupt](/types/interrupt) — `InterruptResumeOperation`、`FlowNodeResume`、`OnInterruptResume`
+- [使用建议] 优先通过上层组合组件（`MessageRender`）使用；直接使用前请确认 `content` 数据结构来自对应类型定义。