@blueking/chat-x 0.0.45-beta.7 → 0.0.45-beta.8

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

@@ -0,0 +1,216 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+渲染 human-in-the-loop 中断消息，分发工具审批，并按 reason 回显 resume 结果（审批单 / 用户回答）。 源码位置：src/components/chat-message/interrupt-message/interrupt-message.vue。
+
+### 关联组件
+- **message-render** — role 为 interrupt 时渲染本组件
+- **user-question-card** — UserQuestion 待回答面板与回答回显
+- **tool-approval-card** — AIDevToolApproval 专用子卡片
+- **message-container** — 透传 onInterruptResume；末条为 interrupt 时不触发组 hover
+
+---
+<!-- FULL DOC -->
+
+# InterruptMessage 中断消息
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/interrupt-message/interrupt-message.vue`
+- **能力域**：Agent 能力
+- **能力说明**：渲染 human-in-the-loop 中断消息，分发工具审批，并按 `result.reason` 回显 resume 结果。
+
+> **能力域**：Agent 能力
+
+human-in-the-loop 中断消息渲染器（导出名 **`InterruptMessageRender`**）。对应 `MessageRole.Interrupt`，解析 `content.outcome` 渲染审批卡片或兜底提示。
+
+> 通常由 [MessageRender](/components/message/message-render) 自动调用，无需业务侧直接引入。
+> `UserQuestion` 的待回答卡片由 [ChatContainer](/components/setup/chat-container) 放在输入区上方，本组件在 `outcome.success` 时按 `result.reason` 回显审批单或用户回答。
+
+## 渲染架构
+
+```
+InterruptMessageRender
+├── content.message（可选）→ 顶部说明文案
+└── content.outcome.type === 'interrupt'
+      └── v-for interrupts
+            ├── reason === aidev:tool_approval → ToolApprovalCard（透传 onInterruptResume，用于取消审批）
+            ├── reason === aidev:user_question → 不在消息内渲染，交由 ChatContainer 输入区挂载
+            └── 未注册 reason → 兜底块（item.message 或「暂不支持的中断消息」）
+
+content.outcome.type === 'success'
+└── resultRenderers[result.reason]
+      ├── aidev:tool_approval → ToolApprovalCard（readonly，隐藏取消审批）
+      └── aidev:user_question → UserQuestionAnsweredCard（支持 #answeredQuestion 透传 #answer）
+```
+
+| `InterruptReason`              | 子组件              |
+| ------------------------------ | ------------------- |
+| `aidev:tool_approval`（待审批） | `ToolApprovalCard`  |
+| `aidev:tool_approval`（已处理） | `ToolApprovalCard`（`readonly`，只读回显） |
+| `aidev:user_question`（待回答） | 输入区 `UserQuestionCard`，本组件不渲染 |
+| `aidev:user_question`（已回答） | `UserQuestionAnsweredCard` |
+| 其他 / 未注册                  | 兜底文案区域        |
+
+## 基础用法（待审批）
+
+```vue
+<template>
+  <InterruptMessageRender
+    :id="message.id"
+    :message-id="message.messageId"
+    :role="message.role"
+    :status="message.status"
+    :content="message.content"
+    :on-interrupt-resume="handleInterruptResume"
+  />
+</template>
+
+<script setup lang="ts">
+  import {
+    InterruptMessageRender,
+    APPROVAL_STATUS,
+    InterruptReason,
+    MessageRole,
+    MessageStatus,
+    type InterruptMessage,
+  } from '@blueking/chat-x';
+
+  const message: InterruptMessage = {
+    id: 'msg_interrupt',
+    messageId: 'msg_interrupt',
+    role: MessageRole.Interrupt,
+    status: MessageStatus.Pending,
+    content: {
+      message: '算法方案评审单需要您关注',
+      outcome: {
+        type: 'interrupt',
+        interrupts: [
+          {
+            id: 'interrupt_1',
+            reason: InterruptReason.AIDevToolApproval,
+            toolCallId: 'tool_call_1',
+            metadata: {
+              ticket: {
+                approvers: ['张三'],
+                sn: 'REV-2026-04-24-001',
+                status: APPROVAL_STATUS.PENDING,
+                submit_time: '2026-04-24 14:30:15',
+                title: '算法方案评审单',
+                url: 'https://example.com/tickets/001',
+              },
+            },
+          },
+        ],
+      },
+    },
+  };
+
+  const handleInterruptResume = async (payload, interrupt) => {
+    // ToolApprovalCard 点击「取消审批」时，payload 为 ToolApprovalResume
+    console.log(payload, interrupt?.id);
+  };
+</script>
+```
+
+**渲染效果**
+
+## UserQuestion 待回答
+
+待回答的 `UserQuestion` 不在消息内渲染；`ChatContainer` 会找到最近一条待回答中断，并在 `ChatInput` 上方挂载 [UserQuestionCard](/components/agent/user-question-card)。
+
+```vue
+<InterruptMessageRender
+  :content="userQuestionMessage.content"
+  role="interrupt"
+/>
+```
+
+**渲染效果**
+
+## AIDevToolApproval 已处理回显（outcome.success）
+
+`outcome.type === 'success'` 且 `result.reason === InterruptReason.AIDevToolApproval` 时，会话内以只读 `ToolApprovalCard` 回显审批单。`result.payload.metadata` 需透传中断时的 `metadata`（含 `ticket`）：
+
+```vue
+<InterruptMessageRender
+  :content="resumedMessage.content"
+  role="interrupt"
+/>
+```
+
+**渲染效果**
+
+## UserQuestion 已回答回显（outcome.success）
+
+`outcome.type === 'success'` 且 `result.reason === InterruptReason.UserQuestion` 时，会话内回显用户回答。可通过 `#answeredQuestion` slot 自定义单题回显：
+
+```vue
+<InterruptMessageRender
+  :content="userQuestionAnsweredMessage.content"
+  role="interrupt"
+>
+  <template #answeredQuestion="{ item, index, status }">
+    <MyCustomAnswerView :data="item" :index="index" :status="status" />
+  </template>
+</InterruptMessageRender>
+```
+
+**渲染效果**
+
+## 不支持的中断类型（兜底）
+
+```vue
+<InterruptMessageRender :content="unsupportedContent" role="interrupt" />
+```
+
+**渲染效果**
+
+## 在 MessageContainer 中使用
+
+配置 `onInterruptResume`，由容器经 `MessageRender` 透传到本组件：
+
+```vue
+<MessageContainer
+  :messages="messages"
+  :on-interrupt-resume="handleInterruptResume"
+/>
+```
+
+当消息组**最后一条**为 `role: 'interrupt'` 时，容器**不会**在鼠标移入时设置 `isHover`，避免误显 AI 工具栏遮挡审批卡片。
+
+## API
+
+### Props
+
+继承 `Partial<InterruptMessage>` 的字段（`id`、`messageId`、`role`、`content`、`status` 等），并额外支持：
+
+| 属性名            | 类型               | 默认值 | 说明                                      |
+| ----------------- | ------------------ | ------ | ----------------------------------------- |
+| content           | `InterruptMessage['content']` | — | 含 `message`、`outcome`、`result` 等      |
+| onInterruptResume | `OnInterruptResume` | —     | 用户完成中断操作后的回调（可选）          |
+
+### Slots
+
+| 插槽名           | 参数                                              | 说明                                                                 |
+| ---------------- | ------------------------------------------------- | -------------------------------------------------------------------- |
+| answeredQuestion | `{ item, index, status }`                         | 自定义 UserQuestion 已回答内容回显，透传给 `UserQuestionAnsweredCard` 的 `#answer` |
+
+slot 参数与 [UserQuestionAnsweredCard](/components/agent/user-question-answered-card) 的 `#answer` 一致。
+
+### Events / Expose
+
+无。
+
+## 类型定义
+
+```typescript
+import type { Interrupt, InterruptMessage, OnInterruptResume } from '@blueking/chat-x';
+```
+
+详见 [中断类型 Interrupt](../../types/interrupt.md)。
+
+## 关联组件
+
+- [ToolApprovalCard](/components/agent/tool-approval-card) — AI Dev 审批单卡片
+- [MessageRender](/components/message/message-render) — 按 `role` 派发
+- [MessageContainer](/components/setup/message-container) — 列表容器与 `onInterruptResume` 透传

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

@@ -0,0 +1,377 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+定义 RunFinishedOutcome、BaseInterrupt、AIDevToolApprovalInterrupt、AIDevToolApprovalResume、UserQuestionInterrupt、InterruptResult、BaseResume、InterruptMessage 与 OnInterruptResume。 与 MessageRole.Interrupt、InterruptMessageRender、UserQuestionCard、ToolApprovalCard 配合，对应 RUN_FINISHED outcome。
+
+### 关联组件
+- **interrupt-message** — 根据 outcome.interrupts 与 reason 渲染中断 UI，success 时按 result.reason 回显审批单或用户回答
+- **user-question-card** — UserQuestion 交互面板，挂载在 ChatInput 上方
+- **tool-approval-card** — AIDevToolApproval 专用卡片
+- **message-render** — role 为 interrupt 时派发 InterruptMessageRender
+
+---
+<!-- FULL DOC -->
+
+# 中断类型 Interrupt
+
+> **分类**：type
+
+AG-UI [Interrupts](https://docs.ag-ui.com/drafts/interrupts) 协议相关类型，定义在 `src/ag-ui/types/interrupt.ts`，由 `@blueking/chat-x` 导出。
+
+中断链路分为两段：
+
+1. Agent 返回 `RUN_FINISHED { outcome: { type: 'interrupt', interrupts } }`，前端渲染等待用户处理的 UI。
+2. 用户操作后调用 `onInterruptResume(payload, interrupt?)`，业务侧按 `payload.operation` 分支处理，并将 `payload` 作为 `RunAgentInput.resume` 回传给 Agent。
+
+## InterruptResumeOperation
+
+统一标识用户在「中断消息 / 活动消息」上触发的、需回传 Agent 处理的动作：
+
+```typescript
+enum InterruptResumeOperation {
+  /** 主动取消第三方工具审批 */
+  ApprovalCancel = 'approval_cancel',
+  /** 重试失败的流程节点（bkflow） */
+  FlowNodeRetry = 'flow_node_retry',
+  /** 跳过失败的流程节点（bkflow） */
+  FlowNodeSkip = 'flow_node_skip',
+}
+```
+
+业务侧通过 `onInterruptResume` 回调的 `payload.operation` 字段进行分支处理；新增操作类型只需扩展此枚举，回调契约与透传链路保持不变。
+
+## RunFinishedOutcome
+
+`RUN_FINISHED` 事件的 `outcome` 联合类型：
+
+```typescript
+type RunFinishedOutcome =
+  | { interrupts: Interrupt[]; type: 'interrupt' }
+  | { type: 'success' };
+```
+
+| `type`        | 说明                                                                 |
+| ------------- | -------------------------------------------------------------------- |
+| `'interrupt'` | 等待用户响应；`interrupts` 驱动 UI 渲染审批卡片、用户问题面板等       |
+| `'success'`   | 用户已通过 `resume` 处理；按 `result.reason` 在会话内回显审批单（`AIDevToolApproval`）或用户回答（`UserQuestion`） |
+
+## BaseInterrupt
+
+所有中断项的公共结构：
+
+```typescript
+type BaseInterrupt<T extends InterruptReason, M extends Record<string, any>> = {
+  expiresAt?: string;
+  id: string;
+  message?: string;
+  metadata?: M;
+  properties?: Record<string, any>;
+  reason: T;
+  toolCallId: string;
+};
+```
+
+## AIDevToolApprovalInterrupt
+
+AI Dev 第三方工具审批中断，`reason` 为 `InterruptReason.AIDevToolApproval`（`'aidev:tool_approval'`）：
+
+```typescript
+type AIDevToolApprovalInterruptPayloadMetaData = {
+  ticket: {
+    approvers: string[];
+    sn: string;
+    status: APPROVAL_STATUS;
+    submit_time: string;
+    title: string;
+    url: string;
+  };
+};
+
+type AIDevToolApprovalInterrupt = BaseInterrupt<
+  InterruptReason.AIDevToolApproval,
+  AIDevToolApprovalInterruptPayloadMetaData
+>;
+```
+
+## AIDevToolApprovalResume
+
+AI Dev 第三方工具审批中断响应（resume 后用于 `outcome.success` 时会话内回显审批单）。`payload.metadata` 透传中断时的 `metadata`（含 `ticket`），以便复用 `ToolApprovalCard` 只读渲染：
+
+```typescript
+type AIDevToolApprovalResume = BaseResume<
+  InterruptReason.AIDevToolApproval,
+  { metadata: AIDevToolApprovalInterruptPayloadMetaData }
+>;
+```
+
+## UserQuestionInterrupt
+
+用户回答问题中断，`reason` 为 `InterruptReason.UserQuestion`（`'aidev:user_question'`）。交互面板由 `ChatContainer` 挂载到 `ChatInput` 上方。
+
+```typescript
+type UserQuestionInterrupt = BaseInterrupt<
+  InterruptReason.UserQuestion,
+  {
+    questions: UserQuestionItem[];
+  }
+>;
+
+type UserQuestionItem = {
+  header: string;
+  /** 是否多选；仅选择题语义，自定义表单类问题可不传 */
+  multiSelect?: boolean;
+  options?: UserQuestionOptionItem[];
+  question: string;
+};
+
+type UserQuestionOptionItem = {
+  description: string;
+  label: string;
+};
+```
+
+约定：
+
+- `multiSelect: false` 表示单选题，`true` 表示多选题；**不传**时 UI 不展示单选/多选标签，默认选择题组件仍按单选行为处理。
+- 前端会为每道**选择题**追加 `label: 'others'` 的自由输入项；后端无需重复下发该选项。
+- 当用户选择 Others 时，`answer[].description` 为用户输入文本。
+- 业务可通过 `UserQuestionCard` 的 `#question` slot 渲染自定义表单；作答有效时调用 `setAnswer` 回传 `UserQuestionAnswerItem`，无效时传 `undefined`。
+
+## Interrupt
+
+当前支持的中断联合类型：
+
+```typescript
+type Interrupt =
+  | AIDevToolApprovalInterrupt
+  | UserQuestionInterrupt
+  | BaseInterrupt<InterruptReason, Record<string, any>>;
+```
+
+## InterruptResult
+
+中断处理结果（resume 后回传/持久化，用于 `outcome.success` 时会话内回显）。按 `reason` 区分不同结果形态，统一具备 `BaseResume` 的 `{ interruptId, reason, status }`；新增中断类型的回显结果只需在此联合扩展：
+
+```typescript
+type InterruptResult = AIDevToolApprovalResume | UserQuestionResume;
+```
+
+## InterruptResume 联合类型
+
+用户操作后通过 `onInterruptResume` 回传的负载（与 `InterruptResult` 用途不同：`InterruptResume` 侧重**动作回传**，`InterruptResult` 侧重**success 态会话内回显**）：
+
+```typescript
+type InterruptResume = FlowNodeResume | ToolApprovalResume | UserQuestionResume;
+```
+
+| 类型                 | `operation` / `reason`              | 说明                                                         |
+| -------------------- | ----------------------------------- | ------------------------------------------------------------ |
+| `ToolApprovalResume` | `InterruptResumeOperation.ApprovalCancel` | 第三方工具审批取消                                           |
+| `FlowNodeResume`     | `flow_node_retry` / `flow_node_skip` | FlowAgent 失败节点重试 / 跳过；**无**对应 `Interrupt` 项     |
+| `UserQuestionResume` | `InterruptReason.UserQuestion`（`reason` 字段） | 用户回答问题                                                 |
+
+### ToolApprovalResume
+
+```typescript
+type ToolApprovalResume = {
+  operation: InterruptResumeOperation.ApprovalCancel;
+  payload: { interrupt_id: number | string };
+};
+```
+
+### FlowNodeResume
+
+流程节点不属于 interrupt，节点定位信息（`task_id` / `node_id`）随 `payload` 回传；此时 `onInterruptResume` 的第二个 `interrupt` 参数**不传**。
+
+```typescript
+type FlowNodeResume = {
+  operation: InterruptResumeOperation.FlowNodeRetry | InterruptResumeOperation.FlowNodeSkip;
+  payload: {
+    node_id: string;
+    task_id: number;
+  };
+};
+```
+
+## BaseResume / UserQuestionResume
+
+`UserQuestion` 的 resume payload 为单个对象，与 `chat-helper` 的 `IResume` 保持一致：
+
+```typescript
+type BaseResume<T extends InterruptReason, P extends Record<string, any>> = {
+  interruptId: string;
+  payload: P;
+  reason: T;
+  status: 'cancelled' | 'resolved';
+};
+
+type UserQuestionAnswerItem = {
+  answer: UserQuestionOptionItem[];
+  multiSelect?: boolean;
+  question: string;
+};
+
+type UserQuestionResume = BaseResume<
+  InterruptReason.UserQuestion,
+  {
+    answers: UserQuestionAnswerItem[];
+  }
+>;
+```
+
+示例：
+
+```typescript
+const resume: UserQuestionResume = {
+  interruptId: 'interrupt_user_question',
+  reason: InterruptReason.UserQuestion,
+  status: 'resolved',
+  payload: {
+    answers: [
+      {
+        question: '请选择语言',
+        multiSelect: true,
+        answer: [
+          { label: 'Java', description: 'Java' },
+          { label: 'others', description: 'Rust' },
+        ],
+      },
+    ],
+  },
+};
+```
+
+## InterruptMessage
+
+`MessageRole.Interrupt` 对应的消息类型，`content` 承载 outcome、可选说明文案与 resume 结果：
+
+```typescript
+type InterruptMessage = BaseMessage<
+  MessageRole.Interrupt,
+  {
+    message?: string;
+    outcome?: RunFinishedOutcome;
+    result?: InterruptResult;
+    runId?: string;
+    threadId?: string;
+  }
+>;
+```
+
+| 字段       | 说明                                                         |
+| ---------- | ------------------------------------------------------------ |
+| `message`  | 消息组顶部可选说明文案，由 `InterruptMessageRender` 展示     |
+| `outcome`  | `type: 'interrupt'` 时从 `interrupts` 渲染交互；`success` 时进入已处理态 |
+| `result`   | 用户 resume 后回传/持久化的 `InterruptResult`；按 `reason` 在会话内回显审批单或用户回答 |
+| `runId`    | 关联 AG-UI run 标识                                          |
+| `threadId` | 关联会话线程标识                                             |
+
+## OnInterruptResume
+
+用户完成中断操作或 FlowAgent 节点操作后的回调（由 `ChatContainer` / `MessageContainer` / `MessageRender` 透传）：
+
+```typescript
+type OnInterruptResume = (
+  payload: InterruptResume,
+  interrupt?: Interrupt,
+) => Promise<void> | void;
+```
+
+| 参数        | 说明                                                                                                       |
+| ----------- | ---------------------------------------------------------------------------------------------------------- |
+| `payload`   | 用户操作产生的 resume 负载；通过 `payload.operation`（或 `UserQuestionResume.reason`）区分动作类型         |
+| `interrupt` | 原始中断项；审批取消、用户问题等中断来源**必传**；FlowAgent 节点重试 / 跳过等非中断来源**不传**             |
+
+| `payload.operation`              | 触发场景                         | `interrupt` |
+| -------------------------------- | -------------------------------- | ----------- |
+| `approval_cancel`                | `ToolApprovalCard` 取消审批      | 必传        |
+| `flow_node_retry` / `flow_node_skip` | `FlowAgentContent` 失败节点操作 | 不传        |
+| —（`UserQuestionResume`）        | `UserQuestionCard` 提交回答      | 必传        |
+
+## 使用示例
+
+```typescript
+import {
+  APPROVAL_STATUS,
+  InterruptReason,
+  InterruptResumeOperation,
+  MessageRole,
+  MessageStatus,
+  type InterruptMessage,
+  type OnInterruptResume,
+} from '@blueking/chat-x';
+
+const message: InterruptMessage = {
+  id: 'msg_interrupt_1',
+  messageId: 'msg_interrupt_1',
+  role: MessageRole.Interrupt,
+  status: MessageStatus.Pending,
+  content: {
+    message: '需要您处理以下中断',
+    outcome: {
+      type: 'interrupt',
+      interrupts: [
+        {
+          id: 'interrupt_approval_1',
+          reason: InterruptReason.AIDevToolApproval,
+          toolCallId: 'tool_call_approval_1',
+          metadata: {
+            ticket: {
+              approvers: ['张三'],
+              sn: 'REV-2026-04-24-001',
+              status: APPROVAL_STATUS.PENDING,
+              submit_time: '2026-04-24 14:30:15',
+              title: '算法方案评审单',
+              url: 'https://example.com/tickets/REV-2026-04-24-001',
+            },
+          },
+        },
+        {
+          id: 'interrupt_question_1',
+          reason: InterruptReason.UserQuestion,
+          toolCallId: 'tool_call_question_1',
+          message: '请选择实现方案',
+          metadata: {
+            questions: [
+              {
+                header: '请选择实现方案',
+                multiSelect: false,
+                question: '你希望采用哪种排序实现？',
+                options: [
+                  { label: 'basic', description: '基础冒泡排序' },
+                  { label: 'optimized', description: '提前终止优化版' },
+                ],
+              },
+            ],
+          },
+        },
+      ],
+    },
+  },
+};
+
+const handleInterruptResume: OnInterruptResume = async (payload, interrupt) => {
+  if ('operation' in payload) {
+    switch (payload.operation) {
+      case InterruptResumeOperation.ApprovalCancel:
+        console.log('取消审批', payload.payload.interrupt_id, interrupt?.id);
+        break;
+      case InterruptResumeOperation.FlowNodeRetry:
+      case InterruptResumeOperation.FlowNodeSkip:
+        console.log('流程节点操作', payload.operation, payload.payload);
+        break;
+    }
+    return;
+  }
+  // UserQuestionResume
+  console.log('用户问题 resume', interrupt?.id, payload);
+};
+```
+
+## 关联文档
+
+- [常量枚举 Constants](./constants.md) — `InterruptReason`、`APPROVAL_STATUS`
+- [消息类型 Messages](./messages.md) — `InterruptMessage` 在消息联合类型中的位置
+- [InterruptMessage 中断消息](../components/agent/interrupt-message)
+- [UserQuestionCard 用户问题中断](../components/agent/user-question-card)
+- [ToolApprovalCard 审批卡片](../components/agent/tool-approval-card)

package/dist/mcp/generated/docs/key-value-content.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-KeyValueContent 以多行 key : value 形式展示结构化数据，可选标题栏与 ThinkingIcon。 常见于用户消息等需要表格化键值的气泡展示。
+以键值列表展示结构化内容。 源码位置：src/components/chat-content/key-value-content/key-value-content.vue。
 
 ### 关联组件
 - **user-message** — 用户消息内展示结构化附加信息
@@ -10,10 +10,15 @@ KeyValueContent 以多行 key : value 形式展示结构化数据，可选标题
 <!-- FULL DOC -->
 
 # KeyValueContent 键值对内容
+## 源码事实
 
-> **层级**：原子组件 · **功能域**：辅助组件
+- **源码位置**：`src/components/chat-content/key-value-content/key-value-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：以键值列表展示结构化内容。
 
-键值对列表展示原子组件，每行以 `key : value` 格式渲染一条数据，支持可选标题栏（带 `ThinkingIcon`）。
+> **能力域**：内容渲染
+
+键值对列表展示基础组件，每行以 `key : value` 格式渲染一条数据，支持可选标题栏（带 `ThinkingIcon`）。
 
 主要被 `UserMessage` 内部用于渲染结构化引用内容（`property.extra.cite.data`），通常不需要手动引入。
 
@@ -121,4 +126,4 @@ const message = {
 
 ## 关联组件
 
-- [UserMessage](../molecular/user-message.md) — 键值气泡展示
+- [UserMessage](/components/message/user-message) — 键值气泡展示