markdown-syntax-guide

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>` 标签 + `![video:xxx](url)` 图片式语法
`图表`, `chart`, `柱状图`, `饼图`, `折线图`, `散点`, `雷达`, `漏斗`, `箱线`, `直方`	优先给 `chartType` HTML 注释 + 表格示例（见图表选型决策表）
`流程图`, `时序图`, `甘特图`, `mermaid`	回退方案：内置 chartType 无法表达流程关系时，才给 Mermaid 代码块
`卡片`, `card`, `link-card`	链接卡片语法（`{"type":"card", ...}` + 链接）
`提示块`, `alert`, `info`, `warning`, `success`, `error`	`:::` 容器语法
`附件`, `attachment`	`![attachment:xxx](url)` 语法
`任务列表`, `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（定义列表）、docCards（卡片列表）、quadrant（四象限图）。

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，类似图片写法）

![video:视频名称](https://example.com/video.mp4)

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`	❌
文档/网站/工具的卡片栅格（标题 + URL + 简介 + 标签）	`docCards`	❌
优先级矩阵 / 二维分类（四象限）	`quadrant`	❌
流程图 / 决策树	—	✅ 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.3.1 卡片栅格（`docCards`）

当用户希望以「双列 / 单列卡片」呈现一组带 标题、URL、简介、标签 的条目时，使用 chartType: "docCards"。一行 Markdown 表格 = 一张卡片，与现有 chart 共用同一套契约。

<!-- {"chartType": "docCards", "title": "推荐文档站", "cardColumns": 2} -->

| 名称              | 地址                          | 简介                       | 亮点                       |
| :---------------- | :---------------------------- | :------------------------- | :------------------------- |
| Tailwind CSS Docs | https://tailwindcss.com/docs  | 结构清晰、搜索与导航强     | 交互式示例, 深链, 暗色模式 |
| MDN               | https://developer.mozilla.org | 权威 Web 平台参考          | 多语言, 可折叠, 示例可编辑 |

表头别名（默认匹配）：名称 / 标题 / name / title → title； 地址 / 链接 / URL → url；简介 / 描述 → description； 亮点 / 标签 → tags。同样支持「列名 = 逻辑名 + 中英文括号单位」的宽松匹配。
标签拆分：tags 列允许半角逗号 ,、分号 ;、竖线 |、斜杠 / 与全角 ， ； 、 分隔。
可选配置：cardColumns（默认 2，传 1 即全宽列表）、fieldMap（显式覆盖列名映射）。
降级策略：注释中无法定位主标题列时，整表会降级为普通 Markdown 表格，避免空白卡片栅格。

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)

![attachment:文件名.pdf](https://example.com/file.pdf)

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: 功能说明
```

指导原则

优先给出可直接复制的示例：用户通常需要「照着改」就能用，先示例后讲解。
图表回复决策顺序（最重要）：
1. 先匹配「§3.1 图表选型决策表」→ 命中内置 chartType 直接给注释 + 表格
2. 仅当落到决策表最后几行（流程图 / 时序图 / 甘特图 / 状态机 / ER 图 / 类图）时，才给 Mermaid 代码块
3. 绝对不要用 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。