# Chat Markdown 自定义渲染元素（组件）实现指南

## 📋 目录

- [概述](#概述)
- [核心架构](#核心架构)
- [快速开始：生成 Markdown 并插入自定义标签](#快速开始生成-markdown-并插入自定义标签)
- [实现步骤：创建自定义渲染组件](#实现步骤创建自定义渲染组件)
- [现有示例](#现有示例)
- [最佳实践](#最佳实践)
- [常见问题](#常见问题)

## 概述

本项目使用 `mp-html` 组件作为 Markdown 渲染引擎，通过 `markdown-it-container` 插件机制实现自定义元素的渲染。当需要在 Markdown 中渲染自定义组件时（如工具调用、执行过程等），可以通过创建容器块来扩展渲染能力。

### 核心优势

- ✅ **插件化设计**：通过 `markdown-it-container` 插件扩展，不影响核心渲染逻辑
- ✅ **类型安全**：支持 UTS/TypeScript 类型定义
- ✅ **灵活扩展**：可以自定义任意容器标签的渲染
- ✅ **动态数据**：支持通过 `processingList` 传递动态数据，实现实时更新
- ✅ **多端支持**：基于 uni-app-x，支持 H5、小程序、App 多端

## 核心架构

### 技术栈

- **渲染引擎**：`mp-html` 组件（基于 `markdown-it`）
- **插件系统**：`markdown-it-container`
- **容器组件**：`container.vue` 自定义组件
- **数据处理**：`processingList` + `getProcessingDataByPriority`

### 架构图

```
┌─────────────────────────────────────────┐
│         Markdown 文本                    │
│  (包含 :::container 语法)                │
└──────────────┬──────────────────────────┘
               │
               │ markdown-it 解析
               ▼
┌─────────────────────────────────────────┐
│      markdown-it-container 插件          │
│  - 识别 :::container 语法               │
│  - 转换为 <container> 标签              │
└──────────────┬──────────────────────────┘
               │
               │ 生成 HTML 节点
               ▼
┌─────────────────────────────────────────┐
│         mp-html 组件                     │
│  (uni_modules/mp-html)                  │
└──────────────┬──────────────────────────┘
               │
               │ 识别 container 标签
               ▼
┌─────────────────────────────────────────┐
│         node.vue 组件                    │
│  - 识别 <container> 标签                │
│  - 调用 getRenderData()                 │
│  - 合并 processingList 数据             │
└──────────────┬──────────────────────────┘
               │
               │ 传递合并后的数据
               ▼
┌─────────────────────────────────────────┐
│      container.vue 组件                  │
│  - 渲染工具调用状态                      │
│  - 显示执行详情                          │
│  - 处理用户交互                          │
└─────────────────────────────────────────┘
```

### 数据流

```
Markdown 文本
  ↓
:::container executeId="xxx" type="Page" status="EXECUTING"
:::
  ↓
<container data='{"executeId":"xxx","type":"Page","status":"EXECUTING"}'></container>
  ↓
container.vue 组件接收 data 属性
  ↓
getRenderData() 合并 processingList 数据
  ↓
最终渲染的组件数据 = data + processingList[executeId]
```

## 快速开始：生成 Markdown 并插入自定义标签

在实际开发中，我们通常需要在代码中动态生成包含自定义容器标签的 Markdown 字符串。本节介绍如何在前端生成这些标签。

### 方式一：使用工具函数（推荐）

#### 1. 使用现有的工具函数

项目已提供 `containerHelper.uts` 工具函数，位于 `subpackages/utils/containerHelper.uts`。

**核心函数**：

```uts
/**
 * 生成工具调用自定义块
 * @param beforeText 之前的文本内容
 * @param toolCallData 工具调用数据
 * @returns 包含自定义块的完整文本
 */
export function getCustomBlock(
  beforeText: string,
  toolCallData: { 
    type?: string; 
    name?: string; 
    executeId?: string; 
    status?: string 
  }
): string
```

**使用示例**：

```uts
import { getCustomBlock } from '@/subpackages/utils/containerHelper.uts'

// 在消息处理中生成容器块
const toolCallData = {
  type: 'Page',
  name: '页面预览',
  executeId: 'exec-123',
  status: 'EXECUTING'
}

let markdown = '这是一段普通文本。'
markdown = getCustomBlock(markdown, toolCallData)
// 结果: '这是一段普通文本。\n\n:::container executeId="exec-123" type="Page" status="EXECUTING" name="页面预览"\n:::\n\n'
```

#### 2. 底层工具函数

如果需要更灵活的控制，可以使用底层函数：

```uts
import { getBlockWrapper, getBlockName } from '@/subpackages/utils/containerHelper.uts'

/**
 * 生成自定义容器块
 * @param data 属性数据对象
 * @returns 格式化的容器块字符串
 */
function generateContainerBlock(data: Record<string, any>): string {
  const blockName = getBlockName() // 返回 'container'
  return getBlockWrapper(blockName, data)
}

// 使用示例
const block = generateContainerBlock({
  executeId: 'exec-123',
  type: 'Page',
  status: 'EXECUTING',
  name: '页面预览'
})
// 结果: '\n\n:::container executeId="exec-123" type="Page" status="EXECUTING" name="页面预览"\n:::\n\n'
```

### 方式二：直接字符串拼接

如果只是偶尔使用，也可以直接拼接字符串：

```uts
// 准备数据
const executeId = 'exec-123'
const type = 'Page'
const status = 'EXECUTING'
const name = '页面预览'

// 拼接 Markdown
const markdown = `这是一段文本。

:::container executeId="${executeId}" type="${type}" status="${status}" name="${name}"
:::

继续其他内容...`
```

### 方式三：创建专用的生成函数

对于特定的业务场景，可以创建专门的生成函数：

```uts
/**
 * 生成页面预览容器块
 * @param markdownText 现有的 Markdown 文本
 * @param pageData 页面数据
 * @returns 插入容器块后的 Markdown
 */
export function insertPagePreviewBlock(
  markdownText: string,
  pageData: { executeId: string; name: string; status: string }
): string {
  const block = `\n\n:::container executeId="${pageData.executeId}" type="Page" status="${pageData.status}" name="${pageData.name}"\n:::\n\n`
  
  // 检查是否已存在，避免重复插入
  if (markdownText.includes(`executeId="${pageData.executeId}"`)) {
    return markdownText
  }
  
  return `${markdownText}${block}`
}

/**
 * 生成工具调用容器块
 * @param markdownText 现有的 Markdown 文本
 * @param toolCallData 工具调用数据
 * @returns 插入容器块后的 Markdown
 */
export function insertToolCallBlock(
  markdownText: string,
  toolCallData: { executeId: string; type: string; name: string; status: string }
): string {
  const attrs = Object.entries(toolCallData)
    .map(([key, value]) => `${key}="${value}"`)
    .join(' ')
  
  const block = `\n\n:::container ${attrs}\n:::\n\n`
  
  // 检查是否已存在
  if (markdownText.includes(`executeId="${toolCallData.executeId}"`)) {
    return markdownText
  }
  
  return `${markdownText}${block}`
}
```

### 数据传递规则

#### 1. 简单属性（字符串、数字）

直接在容器语法中传递：

```markdown
:::container executeId="exec-123" type="Page" status="EXECUTING" name="页面预览"
:::
```

#### 2. 复杂数据（对象、数组）

如果需要传递复杂数据，有两种方式：

**方式一：通过 processingList 传递（推荐）**

```uts
// 在消息对象中设置 processingList
const message = {
  text: markdownWithContainer,
  processingList: [
    {
      executeId: 'exec-123',
      type: AgentComponentTypeEnum.Page,
      name: '页面预览',
      status: ProcessingEnum.EXECUTING,
      result: {
        input: { url: 'https://example.com' },
        data: { html: '<div>...</div>' }
      },
      // ... 其他字段
    }
  ]
}
```

**方式二：在容器语法中传递 JSON 字符串**

```markdown
:::container executeId="exec-123" data='{"key":"value","nested":{"prop":123}}'
:::
```

### 实际使用场景

#### 场景 1：SSE 流式消息处理

```uts
// 在 AgentDetailService.uts 中
import { getCustomBlock } from '@/subpackages/utils/containerHelper.uts'

// 处理 PROCESSING 事件
if (eventType === ConversationEventTypeEnum.PROCESSING) {
  const processingResult = responseData.result || {}
  responseData.executeId = processingResult.executeId

  // 生成包含容器块的 Markdown
  const accumulatedText = getCustomBlock(
    currentMessage.text || '',
    responseData
  )

  // 更新消息
  newMessage = {
    ...currentMessage,
    text: accumulatedText,
    status: MessageStatusEnum.Loading,
    processingList: [
      ...(currentMessage?.processingList || []),
      responseData,
    ] as ProcessingInfo[],
  }
}
```

#### 场景 2：检查标签是否已存在

`getCustomBlock` 函数已经内置了重复检查逻辑：

```uts
// 在 containerHelper.uts 中
export function getCustomBlock(
  beforeText: string,
  toolCallData: { type?: string; name?: string; executeId?: string; status?: string }
): string {
  const { type, executeId } = toolCallData
  
  if (!type || !executeId) {
    return beforeText
  }

  const hasBlock = beforeText.includes(`executeId="${executeId}"`)

  if (hasBlock) {
    // 如果已经存在相同的执行ID，则不重复添加
    return beforeText
  }

  // ... 生成新块
}
```

#### 场景 3：动态更新处理状态

```uts
// 当处理状态更新时，更新 processingList
const updateProcessingStatus = (
  executeId: string,
  newStatus: ProcessingEnum,
  result?: ExecuteResultInfo
) => {
  const currentMessage = getCurrentMessage()
  
  // 更新 processingList 中对应项的状态
  const updatedProcessingList = currentMessage.processingList?.map(item => {
    if (item.executeId === executeId) {
      return {
        ...item,
        status: newStatus,
        result: result || item.result
      }
    }
    return item
  }) || []
  
  // 更新消息
  updateMessage({
    processingList: updatedProcessingList
  })
}
```

### 注意事项

1. **使用换行分隔**：容器块前后需要添加换行，确保 Markdown 解析正确

   ```markdown
   ✅ 正确
   文本内容
   
   :::container executeId="xxx"
   :::
   
   继续内容
   
   ❌ 可能有问题
   文本内容
   :::container executeId="xxx"
   :::
   继续内容
   ```

2. **属性值转义**：属性值中的引号需要转义或使用单引号

   ```markdown
   ✅ 正确
   :::container name="页面\"预览\""
   :::
   
   ✅ 也可以
   :::container name='页面"预览"'
   :::
   ```

3. **避免重复插入**：在流式渲染中，注意检查标签是否已存在，避免重复插入

4. **executeId 唯一性**：确保每个容器块都有唯一的 `executeId`，用于标识和匹配 `processingList` 中的数据

## 实现步骤：创建自定义渲染组件

如果你需要创建新的自定义渲染组件，请按照以下步骤操作。

### 第一步：了解容器组件结构

容器组件位于 `uni_modules/mp-html/components/mp-html/container/container.vue`。

**组件 Props**：

```vue
props: {
  data: {
    type: Object,
    required: true
  }
}
```

**数据合并逻辑**：

在 `node.vue` 中，通过 `getRenderData()` 方法合并数据：

```javascript
getRenderData(data) {
  if(!data) {
    return {}
  }
  
  if(typeof data === 'string') {
    data = JSON.parse(data)
  }
  
  // 从 processingList 中按优先级获取数据并合并
  const result = {
    ...data,
    ...getProcessingDataByPriority(data.executeId, this.processingList)
  }
  
  return result
}
```

### 第二步：修改容器组件（如果需要）

如果需要支持新的渲染类型，可以修改 `container.vue` 组件：

```vue
<template>
  <view class="tool-call-status">
    <!-- 根据 type 渲染不同的内容 -->
    <view v-if="toolCall.type === 'Page'" class="page-preview">
      <!-- 页面预览内容 -->
    </view>
    <view v-else-if="toolCall.type === 'Tool'" class="tool-call">
      <!-- 工具调用内容 -->
    </view>
    <!-- 默认渲染 -->
    <view v-else class="default-container">
      <!-- 默认内容 -->
    </view>
  </view>
</template>

<script>
export default {
  props: {
    data: {
      type: Object,
      required: true
    }
  },
  computed: {
    toolCall() {
      return this.data
    }
  }
}
</script>
```

### 第三步：在 Markdown 中使用

在代码中生成包含容器块的 Markdown：

```uts
import { getCustomBlock } from '@/subpackages/utils/containerHelper.uts'

const markdown = getCustomBlock('', {
  executeId: 'exec-123',
  type: 'Page',
  name: '页面预览',
  status: 'EXECUTING'
})
```

### 第四步：传递 processingList

在消息对象中设置 `processingList`：

```uts
const message = {
  text: markdown,
  processingList: [
    {
      executeId: 'exec-123',
      type: AgentComponentTypeEnum.Page,
      name: '页面预览',
      status: ProcessingEnum.EXECUTING,
      result: {
        input: { /* 输入参数 */ },
        data: { /* 输出数据 */ }
      },
      cardBindConfig: { /* 卡片配置 */ },
      targetId: 123
    }
  ] as ProcessingInfo[]
}
```

### 第五步：在组件中使用

在消息组件中传递 `processingList`：

```vue
<template>
  <mp-html 
    :content="processedText" 
    :processing-list="msg.processingList" 
    :markdown="true" 
    :container-style="`width: 100%;`" 
  />
</template>
```

## 现有示例

### 示例 1：工具调用容器（Tool Call）

**生成 Markdown**：

```uts
import { getCustomBlock } from '@/subpackages/utils/containerHelper.uts'

const markdown = getCustomBlock('', {
  executeId: 'tool-call-123',
  type: 'Tool',
  name: '读取文件',
  status: 'EXECUTING'
})
```

**Markdown 语法**：

```markdown
:::container executeId="tool-call-123" type="Tool" status="EXECUTING" name="读取文件"
:::
```

**渲染效果**：

- 显示工具名称和状态
- 支持展开/收起查看详情
- 显示调用参数和结果
- 支持复制功能

### 示例 2：页面预览容器（Page Preview）

**生成 Markdown**：

```uts
const markdown = getCustomBlock('', {
  executeId: 'page-preview-123',
  type: 'Page',
  name: '页面预览',
  status: 'FINISHED'
})
```

**processingList 数据**：

```uts
{
  executeId: 'page-preview-123',
  type: AgentComponentTypeEnum.Page,
  name: '页面预览',
  status: ProcessingEnum.FINISHED,
  result: {
    input: { url: 'https://example.com' },
    data: { html: '<div>页面内容</div>' }
  }
}
```

**渲染效果**：

- 显示页面名称和状态
- 支持预览页面（点击眼睛图标）
- 显示执行结果

### 示例 3：动态状态更新

**初始状态**：

```uts
// 生成 EXECUTING 状态的容器
let markdown = getCustomBlock('', {
  executeId: 'exec-123',
  type: 'Page',
  status: 'EXECUTING'
})

let processingList = [{
  executeId: 'exec-123',
  status: ProcessingEnum.EXECUTING,
  // ... 其他字段
}]
```

**更新为完成状态**：

```uts
// 更新 processingList
processingList = processingList.map(item => {
  if (item.executeId === 'exec-123') {
    return {
      ...item,
      status: ProcessingEnum.FINISHED,
      result: {
        input: { /* ... */ },
        data: { /* ... */ }
      }
    }
  }
  return item
})

// Markdown 文本不需要修改，组件会自动根据 processingList 更新显示
```

## 最佳实践

### 1. 使用工具函数生成容器块

**推荐**：使用 `getCustomBlock` 函数

```uts
import { getCustomBlock } from '@/subpackages/utils/containerHelper.uts'

const markdown = getCustomBlock(beforeText, toolCallData)
```

**原因**：
- 自动处理重复检查
- 统一的格式和风格
- 易于维护和修改

### 2. executeId 唯一性

**推荐**：确保每个容器块都有唯一的 `executeId`

```uts
const executeId = `exec-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
```

**原因**：
- 用于匹配 `processingList` 中的数据
- 避免重复插入容器块
- 支持动态更新状态

### 3. 数据分离

**推荐**：简单属性放在容器语法中，复杂数据通过 `processingList` 传递

```uts
// ✅ 推荐
// Markdown 中只包含标识信息
:::container executeId="exec-123" type="Page" status="EXECUTING"
:::

// processingList 中包含完整数据
processingList: [{
  executeId: 'exec-123',
  result: { /* 复杂数据 */ }
}]
```

**原因**：
- Markdown 文本保持简洁
- 复杂数据可以动态更新
- 支持流式渲染

### 4. 状态管理

**推荐**：使用 `ProcessingEnum` 枚举管理状态

```uts
import { ProcessingEnum } from '@/types/enums/common.uts'

const status = ProcessingEnum.EXECUTING // 'EXECUTING'
// 或
const status = ProcessingEnum.FINISHED // 'FINISHED'
const status = ProcessingEnum.FAILED    // 'FAILED'
```

**原因**：
- 类型安全
- 避免拼写错误
- 便于维护

### 5. 优先级处理

**推荐**：理解 `getProcessingDataByPriority` 的优先级逻辑

优先级顺序：`FINISHED` > `FAILED` > `EXECUTING`

```uts
// 如果 processingList 中有多个相同 executeId 的项
// 会优先使用 FINISHED 状态的数据
const result = getProcessingDataByPriority(executeId, processingList)
```

**原因**：
- 确保显示最终状态
- 支持状态覆盖
- 处理并发更新

### 6. 错误处理

**推荐**：在生成容器块时进行数据验证

```uts
export function getCustomBlock(
  beforeText: string,
  toolCallData: { type?: string; name?: string; executeId?: string; status?: string }
): string {
  const { type, executeId } = toolCallData
  
  // ✅ 验证必要字段
  if (!type || !executeId) {
    console.warn('getCustomBlock: type 或 executeId 缺失', toolCallData)
    return beforeText
  }

  // ... 其他逻辑
}
```

### 7. 性能优化

**推荐**：避免频繁更新 Markdown 文本

```uts
// ✅ 推荐：只更新 processingList
updateMessage({
  processingList: newProcessingList
})

// ❌ 不推荐：每次都重新生成整个 Markdown
updateMessage({
  text: generateNewMarkdown() // 可能导致性能问题
})
```

**原因**：
- Markdown 解析有性能开销
- `processingList` 更新更高效
- 组件会自动响应数据变化

## 常见问题

### Q1: 容器块不显示怎么办？

**A**: 检查以下几点：

1. **Markdown 语法是否正确**：确保使用 `:::container` 语法，且前后有换行

   ```markdown
   ✅ 正确
   :::container executeId="xxx"
   :::
   
   ❌ 错误
   :::container executeId="xxx":::
   ```

2. **mp-html 组件配置**：确保 `markdown` 属性为 `true`

   ```vue
   <mp-html :markdown="true" :content="text" />
   ```

3. **容器插件是否启用**：检查 `markdown-it/index.js` 中是否配置了 `markdown-it-container`

4. **控制台错误**：检查浏览器控制台是否有错误信息

### Q2: 如何传递复杂数据？

**A**: 使用 `processingList` 传递复杂数据：

```uts
// 在消息对象中设置
const message = {
  text: markdownWithContainer,
  processingList: [{
    executeId: 'exec-123',
    result: {
      input: { /* 复杂对象 */ },
      data: { /* 复杂对象 */ }
    }
  }]
}
```

容器组件会自动从 `processingList` 中获取并合并数据。

### Q3: 如何更新容器状态？

**A**: 更新 `processingList` 中对应项的状态：

```uts
// 更新 processingList
const updatedList = processingList.map(item => {
  if (item.executeId === targetExecuteId) {
    return {
      ...item,
      status: ProcessingEnum.FINISHED,
      result: newResult
    }
  }
  return item
})

// 更新消息
updateMessage({ processingList: updatedList })
```

容器组件会自动响应数据变化并更新显示。

### Q4: 如何支持新的容器类型？

**A**: 修改 `container.vue` 组件，添加新的渲染逻辑：

```vue
<template>
  <view class="custom-container">
    <!-- 根据 type 渲染不同内容 -->
    <view v-if="toolCall.type === 'YourNewType'">
      <!-- 新类型的渲染内容 -->
    </view>
    <!-- 现有类型 -->
    <view v-else>
      <!-- 现有渲染逻辑 -->
    </view>
  </view>
</template>
```

### Q5: 容器组件如何获取数据？

**A**: 数据通过以下流程传递：

1. **Markdown 中的属性**：通过 `:::container executeId="xxx"` 传递
2. **processingList**：通过组件 props 传递
3. **数据合并**：在 `node.vue` 的 `getRenderData()` 中合并
4. **组件接收**：`container.vue` 通过 `data` prop 接收合并后的数据

### Q6: 如何调试容器组件？

**A**: 使用以下方法：

1. **添加 console.log**：在 `container.vue` 中打印接收的数据

   ```vue
   <script>
   export default {
     props: {
       data: Object
     },
     mounted() {
       console.log('Container data:', this.data)
     }
   }
   </script>
   ```

2. **检查 processingList**：确认 `processingList` 中是否有对应 `executeId` 的数据

3. **检查数据合并**：在 `node.vue` 的 `getRenderData()` 中添加日志

4. **Vue DevTools**：使用 Vue DevTools 检查组件 props 和 data

### Q7: 如何处理多个相同 executeId 的容器？

**A**: `getProcessingDataByPriority` 函数会按优先级返回数据：

```uts
// 优先级：FINISHED > FAILED > EXECUTING
const result = getProcessingDataByPriority(executeId, processingList)
// 返回优先级最高的项
```

如果有多个相同 `executeId` 的项，会优先使用 `FINISHED` 状态的数据。

### Q8: 容器组件支持哪些交互？

**A**: 当前 `container.vue` 组件支持：

- **展开/收起**：点击头部切换详情显示
- **复制**：复制参数或结果到剪贴板
- **预览**：对于 Page 类型，支持页面预览（点击眼睛图标）

可以在 `container.vue` 中添加更多交互功能。

### Q9: 如何在流式渲染中避免重复插入？

**A**: `getCustomBlock` 函数已经内置了重复检查：

```uts
const hasBlock = beforeText.includes(`executeId="${executeId}"`)

if (hasBlock) {
  return beforeText // 已存在，不重复添加
}
```

确保每次调用时传入完整的 `beforeText`。

### Q10: 容器组件样式如何自定义？

**A**: 修改 `container.vue` 中的样式：

```vue
<style lang="scss">
.tool-call-status {
  // 自定义样式
  background-color: #f0f0f0;
  border-radius: 8rpx;
  
  // 更多样式...
}
</style>
```

## 总结

通过本指南，你可以：

1. ✅ 理解 Markdown 自定义渲染的架构和原理
2. ✅ **快速上手**：学会如何在代码中生成包含自定义容器标签的 Markdown
3. ✅ **深入实现**：了解如何创建和自定义渲染组件
4. ✅ 遵循最佳实践，编写高质量的代码
5. ✅ 解决常见问题，快速定位和修复错误

## 参考资源

- [mp-html 文档](https://github.com/jin-yufeng/mp-html)
- [markdown-it-container 文档](https://github.com/markdown-it/markdown-it-container)
- [uni-app-x 官方文档](https://uniapp.dcloud.net.cn/uni-app-x/)

---

**维护者**：开发团队

如有问题或建议，请联系开发团队或提交 Issue。