@blueking/chat-x 0.0.42 → 0.0.45-beta.1

package/dist/mcp/generated/docs/user-question-card.md

@@ -0,0 +1,211 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。
+
+### 关联组件
+- **interrupt-message** — outcome.success 时挂载 UserQuestionAnsweredCard 回显回答
+- **chat-container** — 检测最近待回答 UserQuestion 并把 UserQuestionCard 放在输入区上方
+- **interrupt** — 定义 UserQuestionInterrupt 与 UserQuestionResume 协议
+
+---
+<!-- FULL DOC -->
+
+# UserQuestionCard 用户问题中断
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/interrupt-message/user-question/user-question-card.vue`
+- **能力域**：Agent 能力
+- **能力说明**：渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。
+
+> **能力域**：Agent 能力
+
+`UserQuestionCard` 用于渲染 `InterruptReason.UserQuestion`（`'aidev:user_question'`）中断。它通常由 `ChatContainer` 自动挂载到 `ChatInput` 上方，用户回答后通过 `onInterruptResume(payload, interrupt)` 回传 `UserQuestionResume`。
+
+## 交互能力
+
+- **单选 / 多选**：每道题通过 `multiSelect` 控制选择行为；未传时不展示单选/多选标签，默认仍按单选处理。
+- **Others 自由输入**：默认 [UserQuestionChoice](/components/agent/user-question-choice) 为每道题追加 `label: 'others'` 输入项，输入文本写入 `answer[].description`。
+- **自定义作答形态**：通过 `#question` slot 可替换默认选择题，渲染任意表单；作答有效时调用 `setAnswer` 回传 `UserQuestionAnswerItem`，无效时传 `undefined`。
+- **完成校验**：所有题目均已作答（`setAnswer` 收到有效答案）后才允许点击「完成」。
+- **跳过**：点击「跳过」返回 `status: 'cancelled'` 与空 `answers`。
+- **自由文本兜底**：当存在待回答 UserQuestion 且业务配置了 `onInterruptResume` 时，用户也可以直接在 `ChatInput` 输入文本；容器会将文本转换为单条 Others 回答。
+
+## 数据协议
+
+待回答中断：
+
+```typescript
+const interrupt = {
+  id: 'interrupt_user_question',
+  reason: InterruptReason.UserQuestion,
+  toolCallId: 'tool_call_user_question',
+  message: '请选择实现方案',
+  metadata: {
+    questions: [
+      {
+        header: '请选择实现方案',
+        multiSelect: false,
+        question: '你希望采用哪种冒泡排序实现？',
+        options: [
+          { label: 'basic', description: '基础冒泡排序' },
+          { label: 'optimized', description: '优化版冒泡排序' },
+        ],
+      },
+    ],
+  },
+};
+```
+
+完成回答后生成的 resume：
+
+```typescript
+const payload = {
+  interruptId: 'interrupt_user_question',
+  reason: InterruptReason.UserQuestion,
+  status: 'resolved',
+  payload: {
+    answers: [
+      {
+        question: '你希望采用哪种冒泡排序实现？',
+        multiSelect: false,
+        answer: [{ label: 'optimized', description: '优化版冒泡排序' }],
+      },
+    ],
+  },
+};
+```
+
+## 基础用法
+
+> 业务侧通常不直接使用本组件；推荐构造 `InterruptMessage` 后交给 `ChatContainer` / `MessageContainer` 渲染。下面示例用于说明组件 API 和 payload 形状。
+
+```vue
+<template>
+  <UserQuestionCard
+    :interrupt="pendingInterrupt"
+    :on-resume="handleResume"
+  />
+</template>
+
+<script setup lang="ts">
+  import { InterruptReason, UserQuestionCard, type OnInterruptResume } from '@blueking/chat-x';
+
+  const pendingInterrupt = {
+    id: 'interrupt_user_question',
+    reason: InterruptReason.UserQuestion,
+    toolCallId: 'tool_call_user_question',
+    metadata: {
+      questions: [
+        {
+          header: '请选择实现方案',
+          multiSelect: false,
+          question: '你希望采用哪种实现？',
+          options: [{ label: 'basic', description: '基础冒泡排序' }],
+        },
+      ],
+    },
+  };
+
+  const handleResume: OnInterruptResume = async (payload, interrupt) => {
+    console.log(interrupt.id, payload);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 已回答回显
+
+`InterruptMessageRender` 在 `content.outcome.type === 'success'` 且 `content.result.reason === InterruptReason.UserQuestion` 时，会在会话内渲染 `UserQuestionAnsweredCard`。
+
+```vue
+<UserQuestionAnsweredCard
+  :answers="answers"
+  status="resolved"
+/>
+```
+
+**渲染效果**
+
+## ChatContainer 自动挂载
+
+`ChatContainer` 内部通过 `useMessageGroup` 查找最近一条 `outcome.type === 'interrupt'` 的 `UserQuestion`，并在 `ChatInput` 的 `#interrupt` 插槽中渲染 `UserQuestionCard`：
+
+```vue
+<ChatContainer
+  v-model="inputValue"
+  :messages="messages"
+  :on-interrupt-resume="handleResume"
+  :on-send-message="handleSendMessage"
+/>
+```
+
+如果没有配置 `onInterruptResume`，自由文本输入不会被截获，仍按普通 `onSendMessage` 发送，避免用户输入被静默清空。
+
+## 自定义题目渲染（#question slot）
+
+默认每道题由 [UserQuestionChoice](/components/agent/user-question-choice) 渲染；业务可覆盖 `#question` slot 接入自定义表单：
+
+```vue
+<template>
+  <UserQuestionCard
+    :interrupt="pendingInterrupt"
+    :on-resume="handleResume"
+  >
+    <template #question="{ question, qIndex, answer, setAnswer, confirm }">
+      <!-- 自定义表单：作答有效时 setAnswer(answerItem)，无效时 setAnswer(undefined) -->
+      <MyCustomForm
+        :model="question"
+        @change="setAnswer"
+        @submit="confirm"
+      />
+    </template>
+  </UserQuestionCard>
+</template>
+```
+
+`ChatContainer` 提供同名 `#interruptQuestion` slot，参数与 `#question` 一致，透传自输入区上方的 `UserQuestionCard`。
+
+## API
+
+### UserQuestionCard Props
+
+| 属性名    | 类型                    | 默认值 | 说明                                   |
+| --------- | ----------------------- | ------ | -------------------------------------- |
+| interrupt | `UserQuestionInterrupt` | —      | **必填**，含 `metadata.questions`      |
+| onResume  | `OnInterruptResume`     | —      | 完成 / 跳过时触发，签名为 `(payload, interrupt)` |
+
+### UserQuestionAnsweredCard Props
+
+| 属性名  | 类型                         | 默认值       | 说明                         |
+| ------- | ---------------------------- | ------------ | ---------------------------- |
+| answers | `UserQuestionAnswerItem[]`   | —            | 已回答内容列表               |
+| status  | `'resolved' \| 'cancelled'` | `'resolved'` | 回显状态，决定展示已回复/已取消 |
+
+### UserQuestionCard Slots
+
+| 插槽名   | 参数                                                                                                              | 说明                                                                 |
+| -------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| question | `{ question, qIndex, answer, setAnswer, confirm }`                                                                | 自定义单题渲染；未覆盖时回退 [UserQuestionChoice](/components/agent/user-question-choice) |
+
+slot 参数说明：
+
+| 参数       | 类型                                              | 说明                                           |
+| ---------- | ------------------------------------------------- | ---------------------------------------------- |
+| question   | `UserQuestionItem`                                | 原始题目数据                                   |
+| qIndex     | `number`                                          | 题目序号（从 0 开始）                          |
+| answer     | `UserQuestionAnswerItem \| undefined`             | 当前题已组装答案，`undefined` 表示未作答       |
+| setAnswer  | `(answer: UserQuestionAnswerItem \| undefined) => void` | 写入/清空当前题答案                            |
+| confirm    | `() => void`                                      | 触发「完成」，等价点击底部完成按钮（需全部已答） |
+
+### Events / Expose
+
+无。
+
+## 关联文档
+
+- [中断类型 Interrupt](../../types/interrupt.md)
+- [UserQuestionChoice 选择题](/components/agent/user-question-choice)
+- [InterruptMessage 中断消息](/components/agent/interrupt-message)
+- [ChatContainer 聊天容器](/components/setup/chat-container)

package/dist/mcp/generated/docs/user-question-choice.md

@@ -0,0 +1,108 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+UserQuestionCard 默认的选择题渲染组件，封装单选/多选、Others 输入与答案组装。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-choice.vue。
+
+### 关联组件
+- **user-question-card** — 默认通过
+- **user-question-option** — 内部逐条渲染选项行
+- **interrupt** — 答案结构遵循 UserQuestionAnswerItem
+
+---
+<!-- FULL DOC -->
+
+# UserQuestionChoice 用户问题选择题
+
+> **能力域**：Agent 能力
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/interrupt-message/user-question/user-question-choice.vue`
+- **能力说明**：封装 UserQuestion 的选择题交互，负责选项归一化、单选/多选切换、Others 输入校验与 `UserQuestionAnswerItem` 组装。
+
+`UserQuestionChoice` 是 [UserQuestionCard](/components/agent/user-question-card) 在 `#question` slot 未覆盖时的**默认渲染**。业务侧也可单独使用，配合 `useUserQuestion` 的 `setAnswer` 接入自定义面板。
+
+## 交互能力
+
+- **单选 / 多选**：由 `question.multiSelect` 控制；未传时不展示单选/多选标签，但仍按单选行为处理。
+- **Others 自由输入**：前端自动在选项末尾追加 `label: 'others'` 输入项。
+- **实时同步答案**：选择或输入变化时 emit `answer`；作答有效时回传已组装的 `UserQuestionAnswerItem`，无效时回传 `undefined`。
+- **Enter 确认**：Others 输入框按 Enter 触发 `confirm`，等价于点击「完成」按钮（需上层已全部作答）。
+
+## 基础用法（单选）
+
+```vue
+<template>
+  <UserQuestionChoice
+    :question="singleQuestion"
+    @answer="handleAnswer"
+    @confirm="handleConfirm"
+  />
+</template>
+
+<script setup lang="ts">
+  import { UserQuestionChoice, type UserQuestionAnswerItem } from '@blueking/chat-x';
+
+  const singleQuestion = {
+    header: '请选择实现方案',
+    multiSelect: false,
+    question: '你希望采用哪种冒泡排序实现？',
+    options: [
+      { label: 'basic', description: '基础冒泡排序' },
+      { label: 'optimized', description: '优化版冒泡排序' },
+    ],
+  };
+
+  const handleAnswer = (answer: UserQuestionAnswerItem | undefined) => {
+    console.log(answer);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 多选
+
+```vue
+<UserQuestionChoice
+  :question="multiQuestion"
+  @answer="handleAnswer"
+/>
+```
+
+**渲染效果**
+
+## 在 UserQuestionCard 中使用
+
+通常无需直接使用本组件；`UserQuestionCard` 默认已在 `#question` slot 回退中挂载：
+
+```vue
+<UserQuestionCard :interrupt="interrupt" :on-resume="handleResume" />
+```
+
+如需替换某一题的渲染，覆盖 `#question` slot 即可；未覆盖时仍回退到 `UserQuestionChoice`。
+
+## API
+
+### Props
+
+| 属性名   | 类型               | 默认值 | 说明                         |
+| -------- | ------------------ | ------ | ---------------------------- |
+| question | `UserQuestionItem` | —      | **必填**，含 `options` 等字段 |
+
+### Events
+
+| 事件名  | 参数                                      | 说明                                                         |
+| ------- | ----------------------------------------- | ------------------------------------------------------------ |
+| answer  | `(answer: UserQuestionAnswerItem \| undefined)` | 作答变化；有效时回传已组装答案，无效（未选/ Others 空）时 `undefined` |
+| confirm | —                                         | 用户在 Others 输入框按 Enter 时触发，上层可绑定「完成」逻辑   |
+
+### Slots / Expose
+
+无。
+
+## 关联文档
+
+- [UserQuestionCard 用户问题中断](/components/agent/user-question-card)
+- [UserQuestionOption 用户问题选项](/components/agent/user-question-option)
+- [中断类型 Interrupt](../../types/interrupt.md)

package/dist/mcp/generated/docs/user-question-option.md

@@ -0,0 +1,42 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+UserQuestionChoice 内部选项行，处理单选/多选状态和 Others 输入。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-option.vue。
+
+---
+<!-- FULL DOC -->
+
+# UserQuestionOption 用户问题选项
+
+> **能力域**：Agent 能力
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-message/interrupt-message/user-question/user-question-option.vue`
+- **能力说明**：UserQuestionChoice 内部选项行，处理单选/多选状态和 Others 输入。
+
+## API 摘要
+
+### Props
+
+- `{ option: NormalizedUserQuestionOption; othersText?: string; selected: boolean; }`
+
+### Emits
+
+- `{ (e: 'confirm'): void; (e: 'select'): void; (e: 'update:othersText', value: string): void; }`
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 组件依赖
+
+- 无组件依赖或仅依赖基础库。
+
+## 使用建议
+
+- 优先通过 [UserQuestionChoice](/components/agent/user-question-choice) 或 [UserQuestionCard](/components/agent/user-question-card) 使用；直接使用前请确认 props 数据结构来自对应类型定义。

package/dist/mcp/generated/docs/vnode-renderer.md

@@ -0,0 +1,126 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+将 Markdown token 转成 VNode 的内部渲染桥。 源码位置：src/components/chat-content/vnode-renderer.ts。
+
+### 关联组件
+- **markdown-content** — MarkdownContent 对普通 token 分组使用本组件渲染
+- **code-content** — fence/code_block 代码块通常会被 MarkdownContent 提前分流到 CodeContent
+- **mermaid-content** — mermaid 代码块通常会被 MarkdownContent 提前分流到 MermaidContent
+- **image-content** — 图片 token 由 tokensToVNodes 转为 ImageContent
+
+---
+<!-- FULL DOC -->
+
+# VNodeRenderer VNode 渲染器
+
+> **能力域**：辅助能力
+
+`VNodeRenderer` 是 Markdown 渲染链路里的内部桥接组件。它接收 markdown-it 解析出的 `Token[]`，调用 `tokensToVNodes` 转成 Vue VNode，并返回渲染函数结果。
+
+通常不需要业务侧直接使用。完整 Markdown 内容请优先使用 [MarkdownContent](../rendering/markdown-content.md)，它会先识别 Mermaid、LaTeX、代码块等特殊 token，再把普通 token 分组交给 `VNodeRenderer`。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/vnode-renderer.ts`
+- **能力说明**：将 Markdown token 转成 VNode 的内部渲染桥。
+
+## 核心能力
+
+- **Token 到 VNode**：将 markdown-it 的 block、inline、text、link、image、html 等 token 转为 Vue VNode
+- **稳定 key**：`tokensToVNodes` 基于 token 类型、标签和内容 hash 生成 key，降低流式渲染时 DOM 误复用风险
+- **HTML 安全入口**：`options.html` 开启时可渲染 HTML token，实际安全过滤依赖 `options.sanitize`
+- **渲染规则复用**：支持传入 markdown-it `renderer` 与 `mditOptions`，复用自定义 renderer rule
+- **特殊 token 兜底**：图片 token 转成 `ImageContent`，链接自动补充 `target="_blank"` 与 `rel="noopener noreferrer"`
+
+## 基础用法
+
+```vue
+<template>
+  <VNodeRenderer :tokens="tokens" />
+</template>
+
+<script setup lang="ts">
+  import MarkdownIt from '@blueking/chat-x/src/markdown-it/index';
+  import VNodeRenderer from '@blueking/chat-x/src/components/chat-content/vnode-renderer';
+
+  const md = new MarkdownIt();
+  const tokens = md.parse('这是一段 **加粗文本**。', {});
+</script>
+```
+
+**渲染效果**
+
+## 空 Tokens
+
+`tokens` 为空数组时，`tokensToVNodes` 返回空数组，不渲染任何内容。
+
+## 与 MarkdownContent 的关系
+
+`MarkdownContent` 会先按 token 类型分流，再将普通 token 交给 `VNodeRenderer`：
+
+```vue
+<template v-else>
+  <VNodeRenderer
+    :options="vnodeOptions"
+    :tokens="groupedToken"
+  />
+</template>
+```
+
+其中 `vnodeOptions` 会携带 HTML 净化函数、markdown-it renderer 和 parser options：
+
+```typescript
+const vnodeOptions = {
+  html: true,
+  mditOptions: md.options,
+  renderer: md.renderer,
+  sanitize: (html: string) => dompurify.sanitize(html, domPurifyConfig),
+};
+```
+
+## API
+
+### Props
+
+| 属性名  | 类型                  | 必填 | 默认值 | 说明                         |
+| ------- | --------------------- | ---- | ------ | ---------------------------- |
+| tokens  | `Token[]`             | 是   | —      | markdown-it token 数组       |
+| options | `TokenToVNodeOptions` | 否   | `{}`   | token 转 VNode 的渲染选项    |
+
+### Emits
+
+- 无。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 类型定义
+
+```typescript
+export interface TokenToVNodeOptions {
+  highlight?: ((str: string, lang: string, attrs?: unknown) => string) | null;
+  html?: boolean;
+  mditOptions?: Options;
+  renderer?: Renderer;
+  sanitize?: (html: string) => string;
+}
+```
+
+## 使用建议
+
+- 业务侧不要绕过 `MarkdownContent` 直接渲染完整 Markdown 字符串；`VNodeRenderer` 只接收已经解析好的 token。
+- 如果启用 `options.html`，必须同步传入 `sanitize`，否则 HTML token 会直接进入 `innerHTML`。
+- 特殊内容如代码块、Mermaid、LaTeX 推荐继续走 `MarkdownContent` 的分流逻辑。
+
+## 关联组件
+
+- [MarkdownContent](../rendering/markdown-content.md) — Markdown 主渲染器。
+- [CodeContent](../rendering/code-content.md) — 代码块渲染。
+- [MermaidContent](../rendering/mermaid-content.md) — Mermaid 图表渲染。
+- [ImageContent](../medias/image-content.md) — 图片 token 渲染。