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

package/skills/blueking-chat-x/references/components/interrupt-message.md

@@ -0,0 +1,212 @@
+# InterruptMessage 中断消息
+
+> 能力域：Agent 能力 ｜ 导入：`import { InterruptMessage } from '@blueking/chat-x'` ｜ since 1.0.0
+
+渲染 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）
+
+---
+
+# 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（可交互回显，透传 onInterruptResume）
+      └── aidev:user_question → UserQuestionAnsweredCard（支持 #answeredQuestion 透传 #answer）
+```
+
+| `InterruptReason`              | 子组件              |
+| ------------------------------ | ------------------- |
+| `aidev:tool_approval`（待审批） | `ToolApprovalCard`  |
+| `aidev:tool_approval`（已处理） | `ToolApprovalCard`（可交互回显，仍可取消 / 刷新） |
+| `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` 回显审批单（`readonly: false`）：待审批态仍可取消 / 刷新，终态展示置灰的取消按钮。`resultRenderers` 须与 interrupt 态一样透传 `onInterruptResume`，否则取消 / 刷新无回调。`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/skills/blueking-chat-x/references/components/key-value-content.md

@@ -0,0 +1,128 @@
+# KeyValueContent 键值内容
+
+> 能力域：内容渲染 ｜ 导入：`import { KeyValueContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+以键值列表展示结构化内容。 源码位置：src/components/chat-content/key-value-content/key-value-content.vue。
+
+**关联**：user-message（用户消息内展示结构化附加信息）
+
+---
+
+# KeyValueContent 键值对内容
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/key-value-content/key-value-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：以键值列表展示结构化内容。
+
+> **能力域**：内容渲染
+
+键值对列表展示基础组件，每行以 `key : value` 格式渲染一条数据，支持可选标题栏（带 `ThinkingIcon`）。
+
+主要被 `UserMessage` 内部用于渲染结构化引用内容（`property.extra.cite.data`），通常不需要手动引入。
+
+## 组件结构
+
+```
+div.ai-key-value-content（flex column，gap: 8px，font-size: 12px，color: #4d4f56）
+├── [v-if="title"] div.ai-key-value-title（flex，gap: 4px，font-size: 12px，font-weight: 700，color: #3a84ff）
+│     ├── ThinkingIcon（14×14px）
+│     └── {{ title }}
+└── div.ai-key-value-content（flex column，无 gap）   ← 与外层同名嵌套
+      └── div.key-value-item × N（flex row，gap: 3px，min-height: 20px）
+            ├── div.item-key   → {{ item.key }}（flex: 0 0 auto，font-weight: bold，color: #333）
+            ├── "："            → 硬编码文本节点，冒号不属于任何 div
+            └── div.item-value → {{ item.value }}（overflow hidden，ellipsis，`word-break: break-all` 允许多行换行）
+```
+
+> **注意**：内层也是 `.ai-key-value-content` 类（与外层同名），仅用于布局，无额外样式差异。  
+> **注意**：`v-for` 使用 `item.key` 作为 `:key`，`content` 中的 `key` 字段必须唯一，否则触发 Vue 重复 key 警告。  
+> **注意**：`item.value` 在单行方向仍可能因 `text-overflow: ellipsis` 显示省略，但配合 `word-break: break-all` 长串会优先换行展示，**无 tooltip**（与 `DescPanel` 不同）。
+
+## 基础用法
+
+```vue
+<template>
+  <KeyValueContent :content="data" />
+</template>
+
+<script setup lang="ts">
+  import { KeyValueContent } from '@blueking/chat-x';
+
+  const data = [
+    { key: '名称', value: '蓝鲸智云' },
+    { key: '版本', value: 'v3.0' },
+    { key: '状态', value: '运行中' },
+  ];
+</script>
+```
+
+## 带标题
+
+传入 `title` 时，顶部显示 `ThinkingIcon` + 标题文本（蓝色加粗）：
+
+```vue
+<template>
+  <KeyValueContent
+    title="模型参数"
+    :content="[
+      { key: '模型', value: 'GPT-4' },
+      { key: '温度', value: '0.7' },
+      { key: '最大 Token', value: '2048' },
+      { key: '频率惩罚', value: '0.5' },
+    ]"
+  />
+</template>
+```
+
+## 超长 value 换行
+
+`.item-value` 使用 `word-break: break-all`，长 URL 或长文本会在容器内换行；仍保留 `overflow: hidden` 与 `text-overflow: ellipsis` 以约束极端情况，**悬停无 tooltip**：
+
+## API
+
+### Props
+
+| 属性名  | 类型                                | 必填 | 说明                                                              |
+| ------- | ----------------------------------- | ---- | ----------------------------------------------------------------- |
+| content | `{ key: string; value: string; }[]` | ✓    | 键值对数组；`key` 同时作为 `v-for` 的 `:key`，需保证唯一          |
+| title   | `string`                            | —    | 标题文本；传入后在列表上方渲染 `ThinkingIcon + title`（蓝色加粗） |
+
+## 使用场景
+
+`KeyValueContent` 由 `UserMessage` 内部使用，渲染结构化引用内容（`property.extra.cite` 为对象类型时）：
+
+```typescript
+// UserMessage 内部逻辑（简化）
+const citeTitle = computed(() => {
+  const cite = props.property?.extra?.cite;
+  return cite && typeof cite !== 'string' ? cite.title : undefined;
+});
+
+const citeContent = computed(() => {
+  const cite = props.property?.extra?.cite;
+  return cite && typeof cite !== 'string' ? cite.data : cite;
+});
+// citeContent 为数组时 → <KeyValueContent :content="citeContent" :title="citeTitle" />
+// citeContent 为字符串时 → <CiteContent :content="citeContent" />
+```
+
+如需在用户消息中展示结构化引用，将 `property.extra.cite` 设置为以下格式即可：
+
+```typescript
+const message = {
+  // ...
+  property: {
+    extra: {
+      cite: {
+        title: '引用标题',
+        data: [{ key: '字段名', value: '字段值' }],
+      },
+    },
+  },
+};
+```
+
+## 关联组件
+
+- [UserMessage](/components/message/user-message) — 键值气泡展示

package/skills/blueking-chat-x/references/components/knowledge-rag-content.md

@@ -0,0 +1,122 @@
+# KnowledgeRagContent 知识召回内容
+
+> 能力域：Agent 能力 ｜ 导入：`import { KnowledgeRagContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+渲染知识召回活动，包含加载态、Markdown 内容与引用来源。 源码位置：src/components/chat-content/knowledge-rag-content/knowledge-rag-content.vue。
+
+**关联**：activity-message（activityType 为 knowledge_rag 时分发到本组件）、activity-layout（提供可折叠的活动容器外壳）、markdown-content（渲染知识召回摘要正文）、reference-content（渲染召回引用来源列表）
+
+---
+
+# KnowledgeRagContent 知识召回内容
+
+> **能力域**：Agent 能力
+
+`KnowledgeRagContent` 用于渲染知识召回活动内容，包含活动标题、加载态、Markdown 摘要和引用来源列表。它是 `ActivityMessage` 在 `activityType === 'knowledge_rag'` 时使用的具体内容组件。
+
+通常不需要直接使用，`MessageRender -> ActivityMessage` 会根据消息类型自动分发到本组件。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/knowledge-rag-content/knowledge-rag-content.vue`
+- **能力说明**：渲染知识召回活动，包含加载态、Markdown 内容与引用来源。
+
+## 核心能力
+
+- **活动外壳**：基于 `ActivityLayout` 渲染可折叠活动区域，默认展开
+- **状态标题**：`status` 为 `pending` / `streaming` 时标题显示“检索中”并展示 Loading；其他状态显示“检索完成”
+- **Markdown 摘要**：使用 `MarkdownContent` 渲染 `content.content`
+- **引用来源**：使用 `ReferenceContent` 渲染 `content.referenceDocument`
+- **空值兜底**：正文缺失时传入空字符串，引用缺失时传入空数组
+
+## 基础用法
+
+```vue
+<template>
+  <KnowledgeRagContent
+    v-model:collapsed="collapsed"
+    :content="content"
+    status="complete"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import KnowledgeRagContent from '@blueking/chat-x/src/components/chat-content/knowledge-rag-content/knowledge-rag-content.vue';
+  import type { KnowledgeRagMessageContent } from '@blueking/chat-x';
+
+  const collapsed = ref(false);
+
+  const content: KnowledgeRagMessageContent = {
+    content: '根据知识库检索，**蓝鲸智云** 常见 Agent 接入流程包括...',
+    referenceDocument: [
+      { name: 'Agent 接入指南', url: 'https://example.com/agent-guide', originFile: 'https://example.com/docs/agent-guide' },
+    ],
+  };
+</script>
+```
+
+**渲染效果**
+
+## 检索中状态
+
+当消息状态为 `pending` 或 `streaming` 时，标题区域显示 Loading，标题文案为“检索中”。
+
+## 折叠状态
+
+`collapsed` 通过 `v-model:collapsed` 与 `ActivityLayout` 双向绑定，适合由父级活动消息统一控制展开/收起。
+
+## API
+
+### Props
+
+| 属性名     | 类型                         | 必填 | 默认值 | 说明                                     |
+| ---------- | ---------------------------- | ---- | ------ | ---------------------------------------- |
+| content    | `KnowledgeRagMessageContent` | 否   | —      | 知识召回摘要与引用来源                   |
+| messageUid | `string`                     | 否   | —      | 所属消息唯一标识，当前组件暂未直接使用   |
+| status     | `MessageStatus`              | 否   | —      | 消息状态，影响标题文案与 Loading 显示    |
+
+### Models
+
+| 名称      | 类型      | 默认值  | 说明             |
+| --------- | --------- | ------- | ---------------- |
+| collapsed | `boolean` | `false` | 活动内容是否折叠 |
+
+### Emits
+
+- 无显式 emits；`v-model:collapsed` 会产生 `update:collapsed`。
+
+### Slots
+
+- 无。
+
+### Expose
+
+- 无。
+
+## 类型定义
+
+```typescript
+export type KnowledgeRagMessageContent = {
+  content: string;
+  referenceDocument: ReferenceDocumentContent[];
+};
+
+export type ReferenceDocumentContent = {
+  name: string;
+  originFile: string;
+  url: string;
+};
+```
+
+## 使用建议
+
+- 业务接入时优先通过 [ActivityMessage](../message/activity-message.md) 或完整消息链路使用，避免重复判断 `activityType`。
+- `referenceDocument` 为空时组件仍会渲染正文区域，引用列表由 `ReferenceContent` 处理空数组。
+
+## 关联组件
+
+- [ActivityMessage](../message/activity-message.md) — 活动消息分发入口。
+- [ActivityLayout](../helper/activity-layout.md) — 折叠活动外壳。
+- [MarkdownContent](../rendering/markdown-content.md) — Markdown 摘要渲染。
+- [ReferenceContent](../rendering/reference-content.md) — 引用来源列表。

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

@@ -0,0 +1,200 @@
+# LatexContent LaTeX 公式
+
+> 能力域：内容渲染 ｜ 导入：`import { LatexContent } from '@blueking/chat-x'` ｜ since 1.0.0
+
+使用 KaTeX 渲染 LaTeX 公式内容。 源码位置：src/components/markdown-token/latex-content/latex-content.vue。
+
+**关联**：markdown-content（插件解析 $...$ / $$...$$ 后生成数学 token 并挂载本组件）
+
+---
+
+# LatexContent LaTeX 公式渲染
+## 源码事实
+
+- **源码位置**：`src/components/markdown-token/latex-content/latex-content.vue`
+- **能力域**：内容渲染
+- **能力说明**：使用 KaTeX 渲染 LaTeX 公式内容。
+
+> **能力域**：内容渲染
+
+Markdown Token 层的 LaTeX 公式渲染基础组件，基于 **KaTeX** 实现。被 `MarkdownContent` 在解析到数学公式 token 时自动调用，通常无需手动引入。
+
+核心能力：**流式防抖渲染**（throttle 100ms）、**语法自动补全**（`completeLatexContent`）、**渐进式降级重试**（最多 5 次）、**错误静默**（错误文本白色不可见）。
+
+## 组件结构与 Token 渲染路径
+
+```
+props.token（Token[]）
+│
+├─ token.type === 'math_block'（单块且 token.length ≤ 1）
+│    wrapperTag = 'div'，wrapperClass = 'ai-block-latex-content'
+│    └─ <div class="ai-block-latex-wrapper">
+│          └─ renderLatexToken(token) → <span class="block-katex">KaTeX HTML</span>
+│
+├─ token.type === 'math_inline'（或混合 token 数组）
+│    wrapperTag = 'span'，wrapperClass = 'ai-inline-latex-content'
+│    └─ renderLatexToken(token) → <span class="inline-katex">KaTeX HTML</span>
+│
+├─ token.type === 'inline'（含 children）
+│    └─ renderInlineChildren(token.children)
+│         ├─ math_inline  → renderLatexToken（递归）
+│         ├─ text         → escapeHtml
+│         ├─ softbreak    → '\n'
+│         ├─ hardbreak    → '<br>'
+│         ├─ code_inline  → '<code>...</code>'
+│         ├─ strong_open/close → '<strong>' / '</strong>'
+│         ├─ em_open/close    → '<em>' / '</em>'
+│         ├─ s_open/close     → '<s>' / '</s>'
+│         ├─ link_open/close  → '<a href="...">...</a>'
+│         ├─ image            → '<img src="..." alt="...">'
+│         └─ 未知类型         → escapeHtml(token.content)
+│
+├─ token.type === 'paragraph_open/close' → '<p>' / '</p>'
+└─ token.type === 'text' / 其他         → escapeHtml(token.content)
+```
+
+### displayMode 判断规则
+
+```typescript
+// renderLatexToken 内部
+const displayMode = token.type === 'math_block' || token.meta?.displayMode === true;
+// math_inline 也可通过 meta.displayMode=true 强制块级渲染
+```
+
+## 基础用法：块级公式
+
+```vue
+<template>
+  <LatexContent :token="token" />
+</template>
+
+<script setup lang="ts">
+  import { LatexContent } from '@blueking/chat-x';
+  import type { Token } from 'markdown-it';
+
+  const token: Token[] = [{ type: 'math_block', content: 'E = mc^2' } as Token];
+</script>
+```
+
+## 行内公式
+
+`math_inline` 类型，包装为 `span.ai-inline-latex-content`，嵌入文字流中渲染：
+
+```vue
+<template>
+  <!-- 行内公式 -->
+  <LatexContent :token="[{ type: 'math_inline', content: 'a^2 + b^2 = c^2' }]" />
+</template>
+```
+
+## 混合 inline token（文字 + 公式）
+
+传入 `inline` token 并带 `children` 时，`renderInlineChildren` 逐一处理文本、公式、标记：
+
+## 积分与根号
+
+## 矩阵
+
+## 对齐环境
+
+## 流式渲染防闪烁
+
+组件针对流式 Markdown 输入进行了优化：**100ms throttle**（leading + trailing）避免每字符重渲染，**`completeLatexContent`** 在每次渲染前自动补全不完整语法：
+
+```vue
+<template>
+  <LatexContent :token="streamingTokens" />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { LatexContent } from '@blueking/chat-x';
+
+  const streamingTokens = ref([{ type: 'math_block', content: '' }]);
+
+  const simulate = async () => {
+    const formula = '\\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}';
+    let content = '';
+    for (const char of formula) {
+      await new Promise(r => setTimeout(r, 50));
+      content += char;
+      streamingTokens.value = [{ type: 'math_block', content }];
+    }
+  };
+</script>
+```
+
+## 语法自动补全（completeLatexContent）
+
+在每次调用 KaTeX 前，组件先通过 `completeLatexContent` 修复不完整语法，处理顺序为：
+
+| 步骤 | 处理内容                                                              | 示例                                          |
+| ---- | --------------------------------------------------------------------- | --------------------------------------------- |
+| 0    | 不完整 `\begin{env` → 猜测环境名补全 `\begin{env}\end{env}`           | `\begin{pma` → `\begin{pmatrix}\end{pmatrix}` |
+| 0.1  | 不完整 `\end{env` → 猜测环境名补全                                    | `\end{alig` → `\end{aligned}`                 |
+| 0.2  | 末尾不完整命令 `\begi` → 若匹配已知命令前缀则移除，完整命令则补全参数 | `\frac` → `\frac{}{}`                         |
+| 1    | 未闭合 `{}` → 补全缺失的 `}`                                          | `\frac{a}{b` → `\frac{a}{b}`                  |
+| 2    | 未闭合 `[]` → 补全缺失的 `]`                                          | `\sqrt[3` → `\sqrt[3]`                        |
+| 3    | 双参数命令缺第二个参数 → 追加 `{}`                                    | `\frac{a}` → `\frac{a}{}`                     |
+| 4    | `\begin{env}` 无对应 `\end{env}` → 追加 `\end{env}`                   | `\begin{matrix}...` → `...\end{matrix}`       |
+
+**可猜测的环境名**（`COMMON_ENVS`）：`aligned`、`align`、`equation`、`gather`、`matrix`、`pmatrix`、`bmatrix`、`vmatrix`、`cases`、`array`、`split`、`multline`
+
+**双参数命令**（`TWO_ARG_COMMANDS`）：`frac`、`dfrac`、`tfrac`、`binom`、`cfrac`、`overset`、`underset` 等
+
+**单参数命令**（`ONE_ARG_COMMANDS`）：`sqrt`、`text`、`mathbf`、`hat`、`vec`、`overline`、`boxed` 等
+
+## 渐进式降级重试（tryRenderKatex）
+
+补全后仍渲染失败时，最多重试 5 次，每次尝试两种裁剪策略：
+
+```
+尝试 completeLatexContent(content) → KaTeX 渲染
+  失败 →
+    策略 1：移除末尾不完整命令（正则 /\\[a-zA-Z]+(\{[^{}]*\})*\s*$/）
+    策略 2：移除未闭合 {（正则 /\{[^{}]*$/）
+  若仍失败 → 返回 null
+    → 渲染 <span class="katex-loading" style="color: #666; font-style: italic;">原始文本（HTML 转义）</span>
+```
+
+> **错误静默**：KaTeX 以 `errorColor: '#fff'`（白色）渲染错误文本，错误不可见。若检测到 HTML 中含 `katex-error` 类或 `color:#cc0000`，也视为渲染失败，降级为 `katex-loading` 显示原始文本。
+
+## API
+
+### Props
+
+| 属性名 | 类型      | 必填 | 说明                                                                                                                     |
+| ------ | --------- | ---- | ------------------------------------------------------------------------------------------------------------------------ |
+| token  | `Token[]` | ✓    | markdown-it Token 数组；支持 `math_block`、`math_inline`、`inline`（含 children）、`paragraph_open/close`、`text` 等类型 |
+
+### Token 结构
+
+```typescript
+// math_block / math_inline
+{
+  type: 'math_block' | 'math_inline';
+  content: string;              // LaTeX 公式字符串
+  meta?: { displayMode?: boolean }; // true → 块级渲染（math_inline 可用此强制块级）
+}
+
+// inline（含行内标记 + 公式混排）
+{
+  type: 'inline';
+  children: Token[];            // 子 token 列表
+}
+```
+
+## 样式说明
+
+| 类名                    | 标签   | 作用                                                                                        |
+| ----------------------- | ------ | ------------------------------------------------------------------------------------------- |
+| `.ai-block-latex-content`  | `div`  | 单一 `math_block` 时的外层，`text-align: center`，`overflow: auto hidden`，`margin: 16px 0` |
+| `.ai-inline-latex-content` | `span` | 混合/行内时的外层，`display: inline`，`vertical-align: baseline`                            |
+| `.ai-block-latex-wrapper`  | `div`  | 每个 `math_block` token 的包装，`text-align: center`，`margin: 16px 0`                      |
+| `.block-katex`          | `span` | 块级 KaTeX 输出                                                                             |
+| `.inline-katex`         | `span` | 行内 KaTeX 输出                                                                             |
+| `.katex-loading`        | `span` | 渲染失败降级态，斜体灰色显示原始 LaTeX 文本                                                 |
+
+## 关联组件
+
+- [MarkdownContent](/components/rendering/markdown-content) — 数学公式 token 的来源与挂载