| name | markdown-syntax-guide |
| description | 指导用户使用 @ant-design/agentic-ui 的 Markdown Editor / Renderer 扩展语法。图表场景**优先使用内置 chart**(HTML 注释 `chartType` + 表格),**只有当内置 chartType 都不能表达诉求时才回退 Mermaid**。Triggers on keywords like 表格, 视频, 图表, 卡片, 提示块, 流程图, 语法, 怎么写, how to write table chart video card mermaid. |
Markdown 语法指导 Skill
当用户或 AI 需要生成可被 @ant-design/agentic-ui 的 MarkdownEditor / MarkdownRenderer 正确解析的内容时,使用本技能提供与代码实现严格对齐的语法指导。
核心原则(图表场景):先看「图表选型决策表」 → 命中内置 chartType 就用 HTML 注释 + 表格 → 实在没有合适 chartType 才回退 Mermaid 代码块。
Skill 激活场景
| 触发关键词 | 指导内容 |
|---|
表格, table | 基础 Markdown 表格 + chartType: "table" 高级表格 + 图表化表格 |
视频, video | HTML <video> 标签 +  图片式语法 |
图表, chart, 柱状图, 饼图, 折线图, 散点, 雷达, 漏斗, 箱线, 直方 | 优先给 chartType HTML 注释 + 表格示例(见图表选型决策表) |
流程图, 时序图, 甘特图, mermaid | 回退方案:内置 chartType 无法表达流程关系时,才给 Mermaid 代码块 |
卡片, card, link-card | 链接卡片语法({"type":"card", ...} + 链接) |
提示块, alert, info, warning, success, error | ::: 容器语法 |
附件, attachment |  语法 |
任务列表, task list | GFM - [x] / agentic-ui-task 代码块 |
工具栏, tool use bar | agentic-ui-toolusebar 代码块 |
文件列表, filemap | agentic-ui-filemap 代码块 |
MDX, 内嵌组件 | React 组件嵌入(依赖 MDX 渲染上下文) |
apaasify | aPaaS Schema 代码块 |
怎么写, 语法, 格式 | 综合语法速查 |
语法速查表
1. 表格 (Tables)
基础 Markdown 表格
| 标题 1 | 标题 2 | 标题 3 |
| :----- | :----: | -----: |
| 左对齐 | 居中 | 右对齐 |
| 内容 | 内容 | 内容 |
高级表格(通过 HTML 注释启用)
<!-- {"chartType": "table"} -->
| 姓名 | 年龄 | 职业 |
| :--- | :--- | :----- |
| 张三 | 28 | 工程师 |
| 李四 | 32 | 设计师 |
将表格渲染为图表(柱状图、饼图、折线图等)
<!-- {"chartType": "bar", "x": "产品", "y": "销量", "title": "销量对比"} -->
| 产品 | 销量 |
| :--- | :--- |
| A | 100 |
| B | 150 |
| C | 80 |
支持的 chartType:bar(条形)、column(柱状)、line(折线)、area(面积)、pie(饼图)、donut(环形)、radar(雷达)、scatter(散点)、funnel(漏斗)、table(表格)、descriptions(定义列表)。
2. 视频 (Video)
方式一:HTML video 标签
<video src="https://example.com/video.mp4" controls width="400"></video>
带完整属性:
<video src="video.mp4" controls autoplay loop muted poster="poster.jpg" width="640" height="360"></video>
多格式源:
<video controls width="600">
<source src="https://example.com/video.mp4" type="video/mp4">
<source src="https://example.com/video.webm" type="video/webm">
Your browser does not support the video tag.
</video>
方式二:图片式视频语法(扩展 Markdown,类似图片写法)

alt 使用 video:自定义名称 格式,渲染时会识别为视频并嵌入播放器。
3. 图表 (Charts)
铁律:先查"图表选型决策表"。命中内置 chartType 一律用 HTML 注释 + 表格;仅当找不到任何合适的内置 chartType(典型如"流程图、时序图、状态机、甘特图、ER 图"等关系/流程类)时,才回退 Mermaid。
3.1 图表选型决策表
| 用户诉求 | 推荐 chartType | 是否需要 Mermaid |
|---|
| 类目对比(横向) | bar | ❌ |
| 类目对比(纵向) | column | ❌ |
| 趋势 / 时间序列 | line | ❌ |
| 累积趋势 / 占比堆叠 | area | ❌ |
| 占比 / 构成 | pie | ❌ |
| 占比(中间留空) | donut | ❌ |
| 多维能力对比 | radar | ❌ |
| 二维点分布 / 相关性 | scatter | ❌ |
| 转化漏斗 | funnel | ❌ |
| 数据分布(五数概括) | boxplot | ❌ |
| 频数分布 | histogram | ❌ |
| 仅展示原始表格(不画图) | table | ❌ |
| 键值对定义列表 | descriptions | ❌ |
| 流程图 / 决策树 | — | ✅ Mermaid flowchart |
| 时序图 / 调用链 | — | ✅ Mermaid sequenceDiagram |
| 甘特图 / 时间安排 | — | ✅ Mermaid gantt |
| 状态机 | — | ✅ Mermaid stateDiagram |
| ER 图 / 类图 | — | ✅ Mermaid erDiagram / classDiagram |
3.2 内置图表语法(首选)
在 Markdown 表格的正上方紧贴一行 HTML 注释,注释体是合法 JSON:
<!-- {"chartType": "pie", "x": "类型", "y": "占比", "title": "类型分布"} -->
| 类型 | 占比 |
| :--- | ---: |
| A | 30 |
| B | 50 |
| C | 20 |
配置字段速查:
| 字段 | 类型 | 说明 |
|---|
chartType | string | 图表类型,必填,见上方决策表 |
x | string | X 轴列名,对应表头 |
y | string | Y 轴列名,对应表头 |
title | string | 图表标题(可选) |
groupBy | string | 分组列名,用于 radar / scatter / funnel / boxplot / histogram 多组对比 |
colorLegend | string | 颜色图例列名(多系列染色) |
filterBy | string | 过滤维度列名 |
height | number | 图表高度,默认 400 |
3.3 多图表配置(一个表格画多种图)
注释体写成 JSON 数组:
<!-- [{"chartType": "bar", "x": "产品", "y": "销量"}, {"chartType": "pie", "x": "产品", "y": "销量"}] -->
| 产品 | 销量 |
| :--- | ---: |
| A | 100 |
| B | 150 |
| C | 80 |
🔸 当数组里所有 chartType 都为 "table" 时,插件会跳过转换,保留原始表格渲染。
3.4 内置 chart 的智能识别能力
当前实现已自动处理以下"用户书写不规范"的常见情况,生成示例时无需提醒用户改写数据:
- 列名模糊匹配:注释里
"y": "销售额" 可自动匹配表头 销售额(元) / 销售额(元)(忽略括号单位后缀)
- 数值自动识别(表格单元格 → number):
- 千分位:
8,287.44 / 12,3456 / 1,234.5(中英文逗号皆可,末段需 ≥ 3 位数字)
- 百分比:
12.5% / -3% / +12,345.6%(保留字面值,不做 /100)
- 紧凑后缀:
1.2k / 3M / -2.5B / 1.5e3k(k=1e3, m=1e6, b=1e9, t=1e12,大小写均可)
- 科学计数法:
1.2e3 / -3.14E+10 / 1e-5(裸形式由 Number() 直接处理)
- 中文金额:
1.5万 / 2亿(由 parseChineseCurrencyToNumber 兜底)
- 带正号:
+1,234 / +3.14
3.5 完整示例
柱状图(销量对比)
<!-- {"chartType": "column", "x": "品类", "y": "销售额", "title": "品类销售额排名"} -->
| 品类 | 销售额(元) |
| :--------- | ---------: |
| 休闲食品 | 29,337.76 |
| 酒水饮料 | 16,895.05 |
| 速冻日配 | 16,843.76 |
折线图(趋势)
<!-- {"chartType": "line", "x": "时段", "y": "客单价", "title": "分时段客单价"} -->
| 时段 | 客单价(元) |
| :---- | ---------: |
| 8:00 | 56.76 |
| 9:00 | 87.94 |
| 10:00 | 78.35 |
雷达图(多维对比)
<!-- {"chartType": "radar", "x": "维度", "y": "得分", "groupBy": "用户"} -->
| 用户 | 维度 | 得分 |
| :--- | :--- | ---: |
| 张三 | 性能 | 85 |
| 张三 | 体验 | 90 |
| 李四 | 性能 | 78 |
| 李四 | 体验 | 88 |
漏斗图(转化)
<!-- {"chartType": "funnel", "x": "阶段", "y": "人数"} -->
| 阶段 | 人数 |
| :------- | ----: |
| 浏览 | 10000 |
| 加购 | 3500 |
| 下单 | 1800 |
| 支付完成 | 1500 |
饼图 + 柱状图共存
<!-- [{"chartType": "pie", "x": "渠道", "y": "GMV"}, {"chartType": "bar", "x": "渠道", "y": "GMV"}] -->
| 渠道 | GMV |
| :---- | -----: |
| 直营 | 12.5万 |
| 分销 | 3亿 |
| 跨境 | 1.2k |
3.6 兜底:Mermaid(仅在内置 chartType 都不适用时使用)
出现以下信号时才考虑 Mermaid:用户提到 流程图 / 时序图 / 甘特图 / 状态机 / ER 图 / 类图,或要表达"节点之间的关系/调用顺序"。
mermaid 语言代码块在 MarkdownEditor 中受支持(流式解析也对其特殊处理,见 findMatchingClose.ts),MarkdownRenderer 通过通用代码块渲染:
```mermaid
flowchart TD
A[开始] --> B{判断}
B -- 是 --> C[执行]
B -- 否 --> D[结束]
C --> D
```
💡 在 MarkdownEditor 中可用快捷键 Cmd/Ctrl + Option/Alt + M 直接插入 Mermaid 代码块。
反例(不应该用 Mermaid 的场景):
| ❌ 错误用法 | ✅ 应该用 |
|---|
用 Mermaid pie 画占比 | 内置 chartType: "pie" |
用 Mermaid xychart-beta 画柱状/折线 | 内置 chartType: "column" / "line" |
| 用 Mermaid 画散点图 | 内置 chartType: "scatter" |
4. 卡片 (Cards)
链接卡片(Link Card)
格式:HTML 注释 {"type": "card", ...} + 紧接着的 Markdown 链接。
<!-- {"type": "card", "icon": "https://example.com/icon.svg", "title": "卡片标题", "description": "卡片描述"} -->
[链接文本](https://example.com "悬停提示")
简化示例:
<!-- {"type": "card", "title": "网易", "description": "Electronic Gaming & Multimedia"} -->
[网易](https://example.com/company/49 "公司信息")
注释必须与链接在同一段落内,且 type 必须为 "card"。
内嵌 React 组件(MDX)
import { Card } from 'antd';
<Card title="卡片标题">
卡片内容
</Card>
5. 提示块 (Alerts)
使用 ::: 语法(兼容 markdown-it-container)。注意:::: 与内容之间需用空行分隔。
:::info
这是信息提示块。
:::
:::warning
这是警告提示块。
:::
:::success
这是成功提示块。
:::
:::error
这是错误提示块。
:::
6. 附件 (Attachments)

alt 使用 attachment:显示名称 格式,渲染为可下载的附件链接。
7. 其他扩展
任务列表
- [x] 已完成任务
- [ ] 未完成任务
aPaaSify Schema 组件
```apaasify
{
"type": "page",
"body": [
{
"type": "button",
"label": "点击我"
}
]
}
```
Agentic UI 嵌入块(@ant-design/agentic-ui MarkdownEditor / MarkdownRenderer)
任务列表(渲染为 TaskList):
```agentic-ui-task
{
"items": [
{ "key": "1", "title": "步骤", "content": "详情", "status": "loading" }
]
}
```
(默认 variant 为 simple;需完整任务链样式时在 JSON 根级增加 "variant": "default"。)
工具使用栏(渲染为 ToolUseBar):
```agentic-ui-toolusebar
{
"tools": [
{ "id": "1", "toolName": "web_search", "toolTarget": "example.com", "status": "loading" }
]
}
```
文件列表(渲染为 FileMapView):
```agentic-ui-filemap
{
"fileList": [
{ "uuid": "1", "name": "README.md", "size": 2048, "type": "text/markdown", "url": "https://example.com/README.md" },
{ "uuid": "2", "name": "package.json", "size": 512, "type": "application/json", "url": "https://example.com/package.json" }
]
}
```
支持字段:
fileList(或别名 files):文件对象数组
name:文件名(必填)
uuid / id:唯一标识(可选,缺省时自动生成)
size:文件大小(字节数,可选)
type:MIME 类型(可选,用于显示文件图标)
url:文件链接(可选)
previewUrl:预览链接(可选)
status:"done" / "uploading" / "pending" / "error"(可选)
errorMessage:错误说明(status === "error" 时显示,可选)
className:自定义根元素类名(可选)
3D 模型(若项目支持)
```model
format: glb
source: https://example.com/3d/model.glb
camera:
position: [0, 2, 5]
target: [0, 0, 0]
```
音频
```audio
source: https://example.com/audio/note.mp3
title: 功能说明
```
指导原则
- 优先给出可直接复制的示例:用户通常需要「照着改」就能用,先示例后讲解。
- 图表回复决策顺序(最重要):
- 先匹配「§3.1 图表选型决策表」→ 命中内置
chartType 直接给注释 + 表格
- 仅当落到决策表最后几行(流程图 / 时序图 / 甘特图 / 状态机 / ER 图 / 类图)时,才给 Mermaid 代码块
- 绝对不要用 Mermaid 画饼图、柱状图、折线图、散点图等内置已支持的图——Mermaid 是兜底而非首选
- 说明必须紧邻:
chartType 注释必须紧贴表格上方(中间不能有空行外的内容);链接卡片的注释必须与链接在同一段落。
- 字段名与表格列一致:
x / y / groupBy / colorLegend / filterBy 都对应表头列名。列名模糊匹配已生效——写 "y": "销售额" 能命中表头 销售额(元),无需特意写完整。
- 数值不需要预处理:表格里的
8,287.44 / 12.5% / 1.2k / 1.5万 / 1.5e3 / +1,234 都会自动转 number,不要让用户手工去掉单位/逗号/百分号。
- JSON 格式严格:HTML 注释内的 JSON 不能有尾逗号、不能有注释、字符串必须双引号,否则解析失败保留原表格。
- 多图共存用数组:同一表格画多种图时,注释体写
[{...}, {...}];如果数组里全是 chartType: "table",插件会跳过转换。
- Mermaid 使用门槛:仅当用户明确要表达「节点之间的关系/调用顺序/状态变化」且没有任何内置 chartType 能表达时,才使用。
- 流程表达的非 Mermaid 替代:简单步骤优先用有序列表、
agentic-ui-task 任务块;复杂关系才用 Mermaid。
- 区分渲染环境:MDX、
apaasify、model、audio 等依赖具体项目配置,需说明「若项目支持」。
参考文档
| 文档 / 源码 | 内容 |
|---|
docs/utils/markdown-syntax.md | 完整 Markdown 语法(中文) |
docs/utils/markdown-syntax.en-US.md | 英文版语法 |
docs/utils/chart-config.md | 图表配置详解 |
docs/demos-pages/video.md | 视频支持说明 |
src/MarkdownRenderer/plugins/remarkChartFromComment.ts | HTML 注释 → chart 代码块的 mdast 转换 |
src/Plugins/chart/ChartRender.tsx | 11 种图表类型的运行时渲染 |
src/MarkdownRenderer/utils/chartAxisMatch.ts | 列名模糊匹配(忽略括号单位) |
src/MarkdownRenderer/utils/astExtract.ts | 表格单元格数值识别(千分位 / 百分比 / 紧凑后缀 / 科学计数) |
src/MarkdownEditor/editor/utils/findMatchingClose.ts | Mermaid 代码块的流式完整性判断 |
快速回复模板
当用户问「怎么在 Markdown 里加表格/视频/图表/卡片」时,可复用上述对应章节的示例,并附带一句说明(如「将示例中的 URL、列名换成你的数据即可」)。
命令行速查(可选)
如需快速获取某类语法的代码片段,可运行:
python .cursor/skills/markdown-syntax-guide/scripts/lookup.py -l
python .cursor/skills/markdown-syntax-guide/scripts/lookup.py table.advanced
python .cursor/skills/markdown-syntax-guide/scripts/lookup.py chart.bar
python .cursor/skills/markdown-syntax-guide/scripts/lookup.py video.html
语法片段数据位于 data/syntax-snippets.json。