🎯 技能定位

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

覆盖范围包括：

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

目录导航

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

📦 包职责边界

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

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

🚀 快速决策指南

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

🛠 推荐工作流

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

最小使用示例

import { XMarkdown } from '@ant-design/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
• 管理 React 聊天状态，用 use-x-chat
• 处理 Markdown 解析、流式恢复和富组件渲染，用 x-markdown

🔗 参考资源

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

官方文档

• XMarkdown 介绍
• XMarkdown 示例
• XMarkdown 流式渲染
• XMarkdown Components
• XMarkdown 插件
• XMarkdown 主题