feat: add x-markdown skills (#1813)

* feat: x-markdown skills

* revert: revert x-sdks change

* revert: x-sdks change

* feat: add marketplace

* fix: fix cr

* fix: fix cr

Author: Div627

packages/x-skill/.claude-plugin/marketplace.json

@@ -2,6 +2,7 @@
   "name": "x-agent-skills",
   "metadata": {
     "description": "Ant Design X intelligent agent skills collection",
+    "descriptionZh": "Ant Design X 智能技能库，提供完整的 AI 对话应用开发技能",
     "version": "2.3.0-beta.1",
     "author": "Ant Design X Team",
     "homepage": "https://github.com/ant-design/x",
@@ -13,6 +14,8 @@
       "ant-design-x",
       "x-chat",
       "x-request",
+      "x-markdown",
+      "markdown",
       "chat-provider",
       "ai",
       "react",
@@ -23,9 +26,18 @@
     {
       "name": "x-sdk-skills",
       "description": "Ant Design X SDK core skill package, including complete features such as useXChat, XRequest, and custom Provider",
+      "descriptionZh": "Ant Design X SDK 核心技能包，包含 useXChat、XRequest 和自定义 Provider 等完整功能",
       "source": "./",
       "strict": false,
       "skills": ["./skills/use-x-chat", "./skills/x-chat-provider", "./skills/x-request"]
+    },
+    {
+      "name": "x-markdown",
+      "description": "Ant Design X Markdown rendering skill package, providing rich text rendering and chat enhancement features",
+      "descriptionZh": "Ant Design X Markdown 渲染技能包，提供富文本渲染和对话增强功能",
+      "source": "./",
+      "strict": false,
+      "skills": ["./skills/x-markdown"]
     }
   ]
 }

packages/x-skill/README-zh_CN.md

@@ -17,7 +17,7 @@
 - 🤖 **智能化开发体验**：基于最佳实践的代码生成和优化建议，让 AI 辅助您的开发
 - ⚡ **效率大幅提升**：减少重复性工作，加速 Ant Design X 项目开发
 - 🛡 **质量保证**：严格遵循 Ant Design X 设计规范，确保代码质量和一致性
-- 🎯 **场景全覆盖**：覆盖对话组件、数据请求、状态管理等常见 AI 应用场景
+- 🎯 **场景全覆盖**：覆盖对话组件、数据请求、状态管理、Markdown 渲染等常见 AI 应用场景
 - 🔧 **多 IDE 支持**：支持 Claude Code、CodeFuse、Cursor 等主流 AI IDE
 
 ## 📦 安装
@@ -81,10 +81,14 @@ npx x-skill
 
 网络请求最佳实践，优化 API 调用和数据处理。
 
+### x-markdown
+
+Markdown 渲染指南，覆盖流式输出、自定义组件映射、插件与主题。
+
 ## 🎯 适用场景
 
 - **🚀 新项目启动**：快速搭建 Ant Design X 项目框架，包含完整的配置和最佳实践
-- **⚙️ 功能开发**：获取组件使用最佳实践和代码示例，加速功能实现
+- **⚙️ 功能开发**：获取组件使用、渲染与集成的最佳实践和代码示例，加速功能实现
 - **🔍 问题排查**：智能诊断和解决常见开发问题，提供专业的解决方案
 - **📈 性能优化**：获取性能调优的专业建议，提升应用性能
 

packages/x-skill/README.md

@@ -17,7 +17,7 @@ Intelligent skill library specially designed for Ant Design X
 - 🤖 **Intelligent Development Experience**: Code generation and optimization suggestions based on best practices, with AI assisting your development
 - ⚡ **Significant Efficiency Boost**: Reduce repetitive work and accelerate Ant Design X project development
 - 🛡 **Quality Assurance**: Strictly follow Ant Design X design specifications to ensure code quality and consistency
-- 🎯 **Full Scenario Coverage**: Cover common AI application scenarios like conversation components, data requests, and state management
+- 🎯 **Full Scenario Coverage**: Cover common AI application scenarios like conversation components, data requests, state management, and Markdown rendering
 - 🔧 **Multi-IDE Support**: Support mainstream AI IDEs like Claude Code, CodeFuse, and Cursor
 
 ## 📦 Installation
@@ -81,10 +81,14 @@ Chat data flow management, providing efficient data stream processing solutions.
 
 Network request best practices, optimizing API calls and data processing.
 
+### x-markdown
+
+Markdown rendering guide for streaming output, component mapping, plugins, and themes.
+
 ## 🎯 Applicable Scenarios
 
 - **🚀 New Project Startup**: Quickly set up Ant Design X project framework with complete configuration and best practices
-- **⚙️ Feature Development**: Get best practices and code examples for component usage to accelerate feature implementation
+- **⚙️ Feature Development**: Get best practices and code examples for component usage, rendering, and integration to accelerate feature implementation
 - **🔍 Problem Troubleshooting**: Intelligent diagnosis and resolution of common development issues with professional solutions
 - **📈 Performance Optimization**: Get professional advice for performance tuning to improve application performance
 

packages/x-skill/scripts/config.ts

@@ -41,10 +41,12 @@ const skillConfig: Config = {
   zh: {
     'use-x-chat': 'packages/x/docs/x-sdk/use-x-chat.zh-CN.md',
     'x-request': 'packages/x/docs/x-sdk/x-request.zh-CN.md',
+    'x-markdown': 'packages/x/docs/x-markdown/examples.zh-CN.md',
   },
   en: {
     'use-x-chat': 'packages/x/docs/x-sdk/use-x-chat.en-US.md',
     'x-request': 'packages/x/docs/x-sdk/x-request.en-US.md',
+    'x-markdown': 'packages/x/docs/x-markdown/examples.en-US.md',
   },
   paths: {
     // 中文技能目录

packages/x-skill/skills-zh/x-markdown/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: x-markdown
+version: 2.3.0-beta.1
+description: 当任务涉及 @ant-design/x-markdown 的 Markdown 渲染、流式输出、自定义组件映射、插件、主题或聊天富内容展示时使用。
+---
+
+# 🎯 技能定位
+
+**本技能专注解决一个问题**：如何用 `@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](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 '@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](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/ant-design/x/blob/main/packages/x/docs/x-markdown/introduce.zh-CN.md)
+- [XMarkdown 示例](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/examples.zh-CN.md)
+- [XMarkdown 流式渲染](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/streaming.zh-CN.md)
+- [XMarkdown Components](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/components.zh-CN.md)
+- [XMarkdown 插件](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/plugins.zh-CN.md)
+- [XMarkdown 主题](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/themes.zh-CN.md)

packages/x-skill/skills-zh/x-markdown/reference/API.md

@@ -0,0 +1,41 @@
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| content | 需要渲染的 Markdown 内容 | `string` | - |
+| children | Markdown 内容（与 `content` 二选一） | `string` | - |
+| components | 将 HTML 节点映射为自定义 React 组件 | `Record<string, React.ComponentType<ComponentProps> \| keyof JSX.IntrinsicElements>` | - |
+| streaming | 流式渲染行为配置 | `StreamingOption` | - |
+| config | Marked 解析配置，后应用且可能覆盖内置 renderer | [`MarkedExtension`](https://marked.js.org/using_advanced#options) | `{ gfm: true }` |
+| rootClassName | 根元素的额外 CSS 类名 | `string` | - |
+| className | 根容器的额外 CSS 类名 | `string` | - |
+| paragraphTag | 段落使用的 HTML 标签（避免自定义组件含块级元素时的校验问题） | `keyof JSX.IntrinsicElements` | `'p'` |
+| style | 根容器的内联样式 | `CSSProperties` | - |
+| prefixCls | 组件节点 CSS 类名前缀 | `string` | - |
+| openLinksInNewTab | 是否为所有链接添加 `target="_blank"` 并在新标签页打开 | `boolean` | `false` |
+| dompurifyConfig | HTML 净化与 XSS 防护的 DOMPurify 配置 | [`DOMPurify.Config`](https://github.com/cure53/DOMPurify#can-i-configure-dompurify) | - |
+| protectCustomTagNewlines | 是否保留自定义标签内部的换行 | `boolean` | `false` |
+| escapeRawHtml | 是否将 Markdown 中的原始 HTML 转义为纯文本展示（不解析为真实 HTML），用于防 XSS 同时保留内容 | `boolean` | `false` |
+| debug | 是否开启调试模式（显示性能监控浮层） | `boolean` | `false` |
+
+### StreamingOption
+
+| 字段 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| hasNextChunk | 是否还有后续内容块。为 `false` 时会刷新缓存并完成渲染 | `boolean` | `false` |
+| enableAnimation | 是否为块级元素启用文字淡入动画 | `boolean` | `false` |
+| animationConfig | 动画配置（如淡入时长、缓动函数） | `AnimationConfig` | - |
+| tail | 是否启用尾部指示器 | `boolean \| TailConfig` | `false` |
+| incompleteMarkdownComponentMap | 将未闭合 Markdown 片段映射到自定义 loading 组件 | `Partial<Record<'link' \| 'image' \| 'html' \| 'emphasis' \| 'list' \| 'table' \| 'inline-code', string>>` | `{ link: 'incomplete-link', image: 'incomplete-image' }` |
+
+### TailConfig
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| content | 尾部显示的内容 | `string` | `'▋'` |
+| component | 自定义尾部组件，优先级高于 content | `React.ComponentType<{ content?: string }>` | - |
+
+### AnimationConfig
+
+| 属性         | 说明             | 类型     | 默认值          |
+| ------------ | ---------------- | -------- | --------------- |
+| fadeDuration | 动画时长（毫秒） | `number` | `200`           |
+| easing       | 缓动函数         | `string` | `'ease-in-out'` |

packages/x-skill/skills-zh/x-markdown/reference/CORE.md

@@ -0,0 +1,65 @@
+# 核心指南
+
+## 包职责边界
+
+| 需求                          | 对应包                   |
+| ----------------------------- | ------------------------ |
+| 把消息内容渲染成 Markdown     | `@ant-design/x-markdown` |
+| 构建聊天 UI 容器              | `@ant-design/x`          |
+| 管理 Provider、请求与消息状态 | `@ant-design/x-sdk`      |
+
+## 安装与最小渲染
+
+```bash
+npm install @ant-design/x-markdown
+```
+
+```tsx
+import { XMarkdown } from '@ant-design/x-markdown';
+
+const content = `
+# Hello
+
+- item 1
+- item 2
+`;
+
+export default () => <XMarkdown content={content} />;
+```
+
+## 安全默认值
+
+- `content` 和 `children` 二选一即可，不要同时传。
+- 先让纯 Markdown 渲染正确，再加插件或自定义组件。
+- 当模型输出可能包含外链时，优先开启 `openLinksInNewTab`。
+- 如果原始 HTML 只需要保留文本展示，优先使用 `escapeRawHtml`。
+- 如果必须渲染真实 HTML，请显式检查 `dompurifyConfig`。
+
+## 常见集成模式
+
+### 基础内容块
+
+```tsx
+<XMarkdown content={message} className="x-markdown-light" />
+```
+
+### 聊天消息渲染
+
+在 `useXChat` 产出消息列表之后，再用 `XMarkdown` 负责内容展示。
+
+```tsx
+<XMarkdown content={message.message.content} openLinksInNewTab escapeRawHtml />
+```
+
+### 最小检查清单
+
+- 先确认内容本身真的是 Markdown，而不是结构化组件协议。
+- 不要把渲染逻辑塞进 Provider。
+- 不要把请求逻辑塞进 `XMarkdown`。
+- 主题和自定义组件放在基础渲染稳定之后再加。
+
+## 何时继续阅读其他参考
+
+- 内容是流式分块到达时，阅读 [STREAMING.md](STREAMING.md)
+- 需要自定义标签、代码块、插件、主题时，阅读 [EXTENSIONS.md](EXTENSIONS.md)
+- 需要完整属性表时，阅读 `API.md`

packages/x-skill/skills-zh/x-markdown/reference/EXTENSIONS.md

@@ -0,0 +1,72 @@
+# 扩展指南
+
+## Components
+
+`components` 是主要扩展入口，可把 Markdown 或自定义 HTML 标签映射到 React 组件。
+
+```tsx
+import { Mermaid, Sources, Think } from '@ant-design/x';
+import { XMarkdown } from '@ant-design/x-markdown';
+
+<XMarkdown
+  content={content}
+  components={{
+    mermaid: Mermaid,
+    think: Think,
+    sources: Sources,
+  }}
+/>;
+```
+
+### 组件映射规则
+
+- 映射对象尽量保持稳定，避免每次渲染创建新对象。
+- 用 `streamStatus` 区分临时 loading UI 和最终渲染结果。
+- 如果自定义组件内部包含块级元素，必要时用 `paragraphTag` 避免非法嵌套。
+- 自定义标签应语义明确，避免混乱的 Markdown/HTML 混写。
+
+## 插件
+
+内置插件从 `@ant-design/x-markdown/plugins/...` 导入，并通过 `config` 接入。
+
+```tsx
+import Latex from '@ant-design/x-markdown/plugins/Latex';
+
+<XMarkdown
+  content={content}
+  config={{
+    extensions: Latex(),
+  }}
+/>;
+```
+
+当需求属于“新增解析语法”时用插件；仅仅是替换已渲染节点的视觉表现时，用 `components` 更合适。
+
+## 主题
+
+先从内置主题样式开始。
+
+```tsx
+import '@ant-design/x-markdown/themes/light.css';
+
+<XMarkdown className="x-markdown-light" content={content} />;
+```
+
+如果要定制：
+
+1. 保留内置主题类名
+2. 额外加一个自定义类名
+3. 只覆盖真正需要的 CSS 变量
+
+## 自定义标签建议
+
+- 保持自定义标签结构完整
+- 除非语法有意为之，否则避免在自定义 HTML 块内部插入多余空行
+- 如果自定义标签内换行需要保留，检查 `protectCustomTagNewlines`
+
+## 如何选工具
+
+- 用 `components` 替换渲染后的节点
+- 用插件扩展 Markdown 解析能力
+- 用主题控制排版、间距和颜色
+- 用 `dompurifyConfig` 与 `escapeRawHtml` 处理安全，不要拿它们做视觉定制