@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

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

@@ -0,0 +1,266 @@
+# FlowAgentContent FlowAgent 执行内容
+
+> 能力域：Agent 能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ 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 操作
+- **侧栏执行情况面板只读**：侧栏「执行情况」Tab 内经 `ExecutionSummary` 渲染的同一组件同样只保留「详情」，不展示「重试 / 跳过」；面板身份由 `ExecutionSummary` 通过 `EXECUTION_PANEL_TOKEN` 提供，组件以 `useExecutionPanelInject` 读取。因此重试 / 跳过只出现在对话流内的执行情况
+
+## 状态映射
+
+组件将后端原始 `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 行尾展示「重试」或「跳过」按钮（侧栏「执行情况」面板与 Share 分享态不展示，见下方显隐条件）。点击后：
+
+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`；且不在 Share 分享态、不在侧栏「执行情况」面板内 | loading +「重试中」，二者均禁用    | `flow_node_retry`      |
+| 跳过 | 失败态且 `node.skippable === true`；且不在 Share 分享态、不在侧栏「执行情况」面板内 | loading +「跳过中」，二者均禁用    | `flow_node_skip`       |
+| 详情 | 始终展示（含 Share 分享态与侧栏面板） | 不受 pending 影响                  | —（打开侧栏 Tab，不走 resume） |
+
+行尾操作由内部 composable [`useFlowNodeActions`](/composables/use-flow-node-actions) 聚合为声明式列表，组件层仅遍历渲染；两类只读场景合并为它的 `hideResumeActions` 入参。
+
+## 节点详情联动
+
+点击节点「详情」按钮时，组件调用 `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. **侧栏「执行情况」面板同为只读**：面板内经 `ExecutionSummary` → `MessageRender` 渲染的本组件不展示「重试 / 跳过」，只保留「详情」；判定来自 `useExecutionPanelInject()`（内部上下文，未从包入口导出；缺省 `false`），与 Share 态一起并入 `hideResumeActions`。因此脱离 `ExecutionSummary` 独立使用组件时，行为与对话流内一致。
+8. **`onInterruptResume` 透传链路**：`MessageRender` → `ActivityMessage` → `FlowAgentContent`；未传入时重试 / 跳过按钮仍展示但点击无回调。
+9. **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` 数据结构来自对应类型定义。

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

@@ -0,0 +1,236 @@
+# FlowAgentNodeDetail FlowAgent 节点详情
+
+> 能力域：Agent 能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+展示 FlowAgent 节点输入、输出、异常、耗时等详情。 源码位置：src/components/chat-content/flow-agent-content/flow-agent-node-detail.vue。
+
+**关联**：flow-agent-content（节点详情入口由 FlowAgentContent 挂载到自定义 Tab）、detail-section（详情页内部分段容器）、simple-table（展示输入参数、插件输出定义与结构化输出）、chat-container（应用层通过 onCustomTabChange 拉取节点详情并回填）
+
+---
+
+# FlowAgentNodeDetail FlowAgent 节点详情
+
+> **能力域**：Agent 能力
+
+`FlowAgentNodeDetail` 用于展示 FlowAgent 单个节点的配置与输出详情。它通常被 `FlowAgentContent` 通过自定义 Tab 挂载到侧栏，应用层再根据 `messageUid`、`task_id`、`node_id` 拉取真实节点详情并回填到 `data`。
+
+组件自身只负责详情展示，不负责接口请求、Tab 生命周期或消息定位逻辑。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/flow-agent-content/flow-agent-node-detail.vue`
+- **能力说明**：展示 FlowAgent 节点输入、输出、异常、耗时等详情。
+
+## 核心能力
+
+- **双 Tab 展示**：内置“节点配置”和“节点输出”两个页签，默认展示“节点配置”
+- **配置详情**：展示流程模板、节点名称、步骤名称、是否可选、失败处理和超时控制
+- **参数表格**：使用 `SimpleTable` 展示输入参数、插件输出定义和结构化输出
+- **加载骨架屏**：`loading` 为 `true` 时展示标题和内容骨架，不渲染真实数据
+- **定位插槽**：提供 `locateButton` 插槽，允许侧栏注入“在对话中定位”等操作按钮
+- **值格式化**：`null` / `undefined` 显示为 `--`，对象值通过 `JSON.stringify` 转为字符串
+
+## 基础用法
+
+```vue
+<template>
+  <FlowAgentNodeDetail
+    :data="nodeDetailData"
+    :loading="false"
+    node_id="n1"
+    node_name="采集主机指标"
+    :task_id="100"
+    task_name="主机巡检流程"
+  >
+    <template #locateButton>
+      <button type="button">定位</button>
+    </template>
+  </FlowAgentNodeDetail>
+</template>
+
+<script setup lang="ts">
+  import FlowAgentNodeDetail from '@blueking/chat-x/src/components/chat-content/flow-agent-content/flow-agent-node-detail.vue';
+  import type { NodeDetailData } from '@blueking/chat-x';
+
+  const nodeDetailData: Partial<NodeDetailData> = {
+    basic_info: {
+      node_name: '采集主机指标',
+      template_name: '主机巡检流程',
+      stage_name: '巡检准备',
+      optional: false,
+      skippable: true,
+      retryable: true,
+      error_ignorable: false,
+      auto_retry: { enable: true, interval: 30, times: 2 },
+      timeout_config: { enable: true, seconds: 300, action: 'forced_fail' },
+    },
+    inputs: {
+      bk_host_id: 10001,
+      collect_items: ['cpu', 'memory', 'disk'],
+    },
+    plugin_output: [
+      {
+        key: '${cpu_usage}',
+        name: 'CPU 使用率',
+        type: 'number',
+        schema: { description: '当前主机 CPU 使用率', enum: [], type: 'number' },
+      },
+    ],
+    outputs: [{ key: 'cpu_usage', preset: false, value: 23.5 }],
+  };
+</script>
+```
+
+**渲染效果**
+
+## 加载态
+
+`loading` 为 `true` 时，组件展示骨架屏，标题中的节点名和内容区均不会读取 `data` 展示。
+
+## 空数据
+
+当输入参数、插件输出定义或结构化输出为空时，对应 `SimpleTable` 渲染 `--` 占位行。
+
+## Tab 内容
+
+| Tab        | 内容                                                         |
+| ---------- | ------------------------------------------------------------ |
+| 节点配置   | 基础信息、失败处理、超时控制、输入参数、插件输出定义         |
+| 节点输出   | 结构化输出，来自 `data.outputs`                              |
+
+`activeTab` 是组件内部状态，不通过 prop 或 expose 暴露。
+
+## 字段展示规则
+
+| 区域         | 数据来源                         | 展示规则                                      |
+| ------------ | -------------------------------- | --------------------------------------------- |
+| 流程模板     | `data.basic_info.template_name`   | 空值显示 `--`                                 |
+| 节点名称     | `data.basic_info.node_name`       | 空值显示 `--`                                 |
+| 步骤名称     | `data.basic_info.stage_name`      | 空值显示 `--`                                 |
+| 是否可选     | `data.basic_info.optional`        | `true` 显示“是”，否则显示“否”                 |
+| 失败处理     | `skippable` / `auto_retry.enable` | 支持“手动跳过”和“自动重试”；均无时显示 `--`  |
+| 超时控制     | `timeout_config`                  | 未启用时显示 `--`；`forced_fail` 显示“强制失败” |
+| 输入参数     | `data.inputs`                     | 对象条目转为 `{ key, value }` 表格            |
+| 插件输出定义 | `data.plugin_output`              | 展示名称、变量说明和 KEY                     |
+| 结构化输出   | `data.outputs`                    | 展示输出 key 与格式化后的 value              |
+
+## 自定义 Tab 联动
+
+`FlowAgentContent` 点击节点“详情”时，会将本组件挂载到自定义 Tab，并先传入 `loading: true` 和节点定位参数：
+
+```typescript
+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` 中读取这些参数，请求节点详情后返回新的 `props.data` 和 `props.loading`。
+
+## API
+
+### Props
+
+| 属性名    | 类型                       | 必填 | 默认值 | 说明                         |
+| --------- | -------------------------- | ---- | ------ | ---------------------------- |
+| data      | `Partial<NodeDetailData>`  | 是   | —      | 节点详情数据                 |
+| loading   | `boolean`                  | 否   | —      | 是否显示骨架屏               |
+| node_id   | `string`                   | 否   | —      | 节点 ID，来自自定义 Tab 参数 |
+| node_name | `string`                   | 否   | —      | 节点名称                     |
+| task_id   | `number`                   | 否   | —      | 任务 ID                      |
+| task_name | `string`                   | 否   | —      | 任务名称                     |
+
+> Props 类型来自 `CustomBkFlowTabData['props'] & { data: Partial<NodeDetailData> }`。
+
+### Emits
+
+- 无。
+
+### Slots
+
+| 插槽名       | 说明                         |
+| ------------ | ---------------------------- |
+| locateButton | 标题栏右侧操作区，如定位按钮 |
+
+### Expose
+
+- 无。
+
+## 类型定义
+
+```typescript
+export type CustomBkFlowTabData = CustomTabData<{
+  data?: Partial<NodeDetailData>;
+  loading?: boolean;
+  node_id?: string;
+  node_name?: string;
+  task_id?: number;
+  task_name?: string;
+}>;
+
+export interface NodeDetailData {
+  inputs: Record<string, unknown>;
+  node_id: string;
+  task_id: number;
+  basic_info: {
+    auto_retry: {
+      enable: boolean;
+      interval: number;
+      times: number;
+    };
+    error_ignorable: boolean;
+    node_name: string;
+    optional: boolean;
+    retryable: boolean;
+    skippable: boolean;
+    stage_name: string;
+    template_name: string;
+    timeout_config: {
+      action: string;
+      enable: boolean;
+      seconds: number;
+    };
+  };
+  outputs: Array<{
+    key: string;
+    preset: boolean;
+    value: unknown;
+  }>;
+  plugin_output: Array<{
+    key: string;
+    name: string;
+    schema: {
+      description: string;
+      enum: unknown[];
+      properties?: Record<string, unknown>;
+      type: string;
+    };
+    type: string;
+  }>;
+}
+```
+
+## 使用建议
+
+- 优先由 [FlowAgentContent](./flow-agent-content.md) 通过自定义 Tab 挂载，不建议业务组件手动拼装 Tab 生命周期。
+- 接口请求与数据回填应放在应用层 `ChatContainer` 的 `onCustomTabChange` 链路中处理。
+- `data` 可传 `Partial<NodeDetailData>`，但真实展示依赖 `basic_info`、`inputs`、`plugin_output`、`outputs` 等字段；缺字段时对应区域会降级为空表格或 `--`。
+
+## 关联组件
+
+- [FlowAgentContent](./flow-agent-content.md) — 节点详情入口。
+- [DetailSection](./detail-section.md) — 详情分段容器。
+- [SimpleTable](./simple-table.md) — 详情表格。
+- [ChatContainer](../setup/chat-container.md) — 自定义 Tab 数据回填入口。

package/skills/blueking-chat-x/references/components/highlight-keyword.md

@@ -0,0 +1,146 @@
+# HighlightKeyword 关键词高亮
+
+> 能力域：辅助能力 ｜ 导入：`import { HighlightKeyword } from '@blueking/chat-x'` ｜ since 1.0.0
+
+根据注入关键词高亮文本片段。 源码位置：src/components/highlight-keyword/highlight-keyword.ts。
+
+**关联**：toolcall-render（工具调用标题与状态文案高亮）、desc-panel（工具详情键值与描述文本高亮）、execution-summary（执行摘要搜索过滤与列表高亮）
+
+---
+
+# HighlightKeyword 关键词高亮
+## 源码事实
+
+- **源码位置**：`src/components/highlight-keyword/highlight-keyword.ts`
+- **能力域**：辅助能力
+- **能力说明**：根据注入关键词高亮文本片段。
+
+> **能力域**：辅助能力
+
+函数式组件，用于在文本中高亮匹配的搜索关键词。通过 `useKeywordInject` 从上层注入关键词，自动将匹配部分包裹在带高亮样式的 `<span>` 中。
+
+主要配合 `ExecutionSummary` 的搜索功能使用，实现搜索结果的视觉高亮。
+
+## 工作原理
+
+```
+props.text + inject(keyword)
+        │
+        ├── keyword 为空 → 直接渲染原文本
+        │
+        └── keyword 非空
+            ├── 正则 split 文本为 parts[]
+            ├── parts.length === 1 → 无匹配，渲染原文本
+            └── parts.length > 1 → 匹配部分用 <span class="highlight"> 包裹
+```
+
+组件使用 `defineComponent` + `h()` 渲染函数实现，不依赖模板。
+
+## 基础用法
+
+```vue
+<template>
+  <HighlightKeyword :text="text" />
+</template>
+
+<script setup lang="ts">
+  import { HighlightKeyword } from '@blueking/chat-x';
+
+  const text = '这是一段包含 Vue 3 Composition API 的示例文本';
+</script>
+```
+
+> **注意**：关键词通过 `useKeywordProvider` / `useKeywordInject`（`provide/inject`）注入，不通过 props 传入。上层需先调用 `useKeywordProvider()` 设置关键词。
+
+**渲染效果**（在输入框中输入关键词，观察文本高亮变化）
+
+## 关键词高亮示例
+
+预设关键词为 `API`，文本中所有匹配部分会以高亮背景显示：
+
+## 与 ExecutionSummary 配合
+
+`ExecutionSummary` 内部通过 `useKeywordProvider` 提供搜索关键词，后代组件中的 `HighlightKeyword` 自动响应：
+
+```
+ExecutionSummary
+├── useKeywordProvider(keyword)  ← Input 绑定
+└── MessageRender
+    └── AssistantMessage
+        └── ToolcallRender
+            └── HighlightKeyword(:text)  ← inject(keyword)
+```
+
+## 配套 Composables
+
+### useKeywordProvider
+
+在上层组件中创建关键词并 `provide`，后代组件通过 `useKeywordInject` 消费：
+
+```typescript
+import { useKeywordProvider } from '@blueking/chat-x';
+
+const { keyword } = useKeywordProvider();
+keyword.value = '搜索词';
+```
+
+### useKeywordInject
+
+在后代组件中注入关键词，返回 `ComputedRef<string> | undefined`：
+
+```typescript
+import { useKeywordInject } from '@blueking/chat-x';
+
+const keyword = useKeywordInject();
+console.log(keyword?.value); // 当前搜索关键词
+```
+
+### useKeywordMatch
+
+用于判断组件的可搜索文本是否与当前关键词匹配。内部调用 `useKeywordInject` 获取关键词，根据传入的文本提取函数判断是否命中：
+
+```typescript
+import { useKeywordMatch } from '@blueking/chat-x';
+
+const { keywordMatched } = useKeywordMatch(() => [props.title, props.description, props.content]);
+
+// keywordMatched.value === true 表示命中搜索
+// keywordMatched.value === false 表示未命中（可据此隐藏组件）
+// keyword 为空时始终返回 true
+```
+
+`useKeywordMatch` 的典型用途是在 `ExecutionSummary` 的搜索过滤中，让组件自行判断是否匹配搜索词，与 `HighlightKeyword` 配合实现搜索 + 高亮。
+
+## API
+
+### Props
+
+| 属性名 | 类型     | 必填 | 说明       |
+| ------ | -------- | ---- | ---------- |
+| text   | `string` | ✓    | 待高亮文本 |
+
+### 依赖注入
+
+| 注入项  | 提供方               | 说明                   |
+| ------- | -------------------- | ---------------------- |
+| keyword | `useKeywordProvider` | 搜索关键词，响应式更新 |
+
+### 配套 Composables
+
+| 函数名               | 参数                                            | 返回值                                     | 说明                                          |
+| -------------------- | ----------------------------------------------- | ------------------------------------------ | --------------------------------------------- |
+| `useKeywordProvider` | —                                               | `{ keyword: ShallowRef<string> }`          | 创建并 `provide` 关键词，用于上层组件         |
+| `useKeywordInject`   | —                                               | `ComputedRef<string> \| undefined`         | 注入关键词，用于后代组件                      |
+| `useKeywordMatch`    | `getSearchTexts: () => (string \| undefined)[]` | `{ keywordMatched: ComputedRef<boolean> }` | 判断组件文本是否匹配关键词，空关键词返回 true |
+
+### CSS 类名
+
+| 类名                    | 说明                                |
+| ----------------------- | ----------------------------------- |
+| `.ai-highlight-keyword` | 匹配文本的高亮样式（背景色 + 圆角） |
+
+## 关联组件
+
+- [ToolcallRender](/components/agent/toolcall-render) — 工具调用头部高亮
+- [DescPanel](/components/rendering/desc-panel) — 详情面板键值高亮
+- [ExecutionSummary](/components/agent/execution-summary) — 执行摘要搜索