# X Markdown

> 当任务涉及 @antdv-next/x-markdown 的 Markdown 渲染、流式输出、自定义组件映射、插件、主题或聊天富内容展示时使用。

- Skill: `antdv-next/x-markdown-2` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add antdv-next/x-markdown-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/antdv-next/x-markdown-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: antdv-next (https://skillmd.com/u/antdv-next)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/antdv-next/x-markdown-2

---


# 🎯 技能定位

**本技能专注解决一个问题**：如何用 `@antdv-next/x-markdown` 正确、稳定地渲染 Markdown 内容。

覆盖范围包括：

- 基础渲染与包职责边界
- LLM 流式输出与不完整语法处理
- 自定义组件映射与聊天富内容渲染
- 插件、主题与安全默认配置

## 目录导航

- [📦 包职责边界](#-包职责边界)
- [🚀 快速决策指南](#-快速决策指南)
- [🛠 推荐工作流](#-推荐工作流)
- [🚨 开发规则](#-开发规则)
- [🤝 技能协作](#-技能协作)
- [🔗 参考资源](#-参考资源)

# 📦 包职责边界

| 层级       | 包名                     | 职责                                            |
| ---------- | ------------------------ | ----------------------------------------------- |
| **UI层**   | `@antdv-next/x`          | 聊天 UI、Bubble、Sender、交互组件               |
| **数据层** | `@antdv-next/x-sdk`      | Provider、请求、流式数据流、状态管理            |
| **渲染层** | `@antdv-next/x-markdown` | Markdown 解析、流式渲染、插件、主题、自定义渲染 |

> ⚠️ `x-markdown` 不是聊天状态管理工具。它负责把已有消息内容渲染出来，不负责请求和消息流本身。

# 🚀 快速决策指南

| 当你需要...             | 优先阅读                                 | 典型结果                                     |
| ----------------------- | ---------------------------------------- | -------------------------------------------- |
| 用最小配置渲染 Markdown | [CORE.md](reference/CORE.md)             | 用 `XMarkdown` 渲染基础内容                  |
| 渲染 LLM 流式输出       | [STREAMING.md](reference/STREAMING.md)   | 正确处理 `hasNextChunk`、占位符、尾部指示器  |
| 把标签映射到业务组件    | [EXTENSIONS.md](reference/EXTENSIONS.md) | 为自定义标签、代码块、富内容组件建立稳定映射 |
| 增加插件或主题定制      | [EXTENSIONS.md](reference/EXTENSIONS.md) | 完成插件导入、主题类名接入、最小 CSS 覆盖    |
| 查看属性细节和默认值    | [API.md](reference/API.md)               | 获取 `XMarkdown` 与 streaming 的完整属性表   |

# 🛠 推荐工作流

1. 先看 [CORE.md](reference/CORE.md)，先让基础渲染跑通。
2. 只有在内容是分块到达时，才继续看 [STREAMING.md](reference/STREAMING.md)。
3. 只有在需要自定义标签、插件、主题时，才继续看 [EXTENSIONS.md](reference/EXTENSIONS.md)。
4. 属性名与默认值以 [API.md](reference/API.md) 为准，不要凭记忆猜。

## 最小使用示例

```tsx
import { XMarkdown } from "@antdv-next/x-markdown";

export default () => <XMarkdown content="# Hello" />;
```

# 🚨 开发规则

- `components` 映射尽量保持稳定，不要在每次渲染时创建新的内联组件对象。
- 最后一块内容必须设置 `streaming.hasNextChunk = false`，否则不完整占位内容不会被刷新成最终结果。
- 谨慎处理原始 HTML。如果只想保留文本展示，优先使用 `escapeRawHtml`。
- 如果必须渲染 HTML，请显式审查 `dompurifyConfig`，不要依赖模糊默认行为。
- 主题覆盖尽量最小化。先继承 `x-markdown-light` 或 `x-markdown-dark`，只改必要变量。
- 如果自定义组件依赖完整语法，再在 `streamStatus === 'done'` 时执行昂贵逻辑。

# 🤝 技能协作

| 场景                           | 推荐技能组合                                                  | 原因                                            |
| ------------------------------ | ------------------------------------------------------------- | ----------------------------------------------- |
| 聊天中的富文本回答             | `x-chat-provider` → `x-request` → `use-x-chat` → `x-markdown` | 前三者负责数据流，`x-markdown` 负责最终内容渲染 |
| 内置 Provider + Markdown 回复  | `x-request` → `use-x-chat` → `x-markdown`                     | 请求配置与渲染职责分离                          |
| 独立的 Markdown 页面或文档视图 | `x-markdown`                                                  | 不需要聊天状态管理                              |

## 边界规则

- 适配接口格式，用 **`x-chat-provider`**
- 配置传输、认证、重试、流分隔，用 **`x-request`**
- 管理 Vue 聊天状态，用 **`use-x-chat`**
- 处理 Markdown 解析、流式恢复和富组件渲染，用 **`x-markdown`**

# 🔗 参考资源

- [CORE.md](reference/CORE.md) - 包职责、安装与起步、安全默认值、常见渲染模式
- [STREAMING.md](reference/STREAMING.md) - 分块渲染、不完整语法恢复、loading/done 行为
- [EXTENSIONS.md](reference/EXTENSIONS.md) - 组件映射、插件、主题、自定义标签建议
- [API.md](reference/API.md) - 从官方 `x-markdown` 文档生成的 API 参考

## 官方文档

- [XMarkdown 介绍](https://github.com/antdv-next/x/blob/main/packages/docs/src/pages/markdown/introduce.zh-CN.md)
- [XMarkdown 示例](https://github.com/antdv-next/x/blob/main/packages/docs/src/pages/markdown/examples.zh-CN.md)
- [XMarkdown 流式渲染](https://github.com/antdv-next/x/blob/main/packages/docs/src/pages/markdown/streaming.zh-CN.md)
- [XMarkdown Components](https://github.com/antdv-next/x/blob/main/packages/docs/src/pages/markdown/components.zh-CN.md)
- [XMarkdown 插件](https://github.com/antdv-next/x/blob/main/packages/docs/src/pages/markdown/plugins.zh-CN.md)
- [XMarkdown 主题](https://github.com/antdv-next/x/blob/main/packages/docs/src/pages/markdown/themes.zh-CN.md)