菜单
指导用户使用 @ant-design/agentic-ui 的 Markdown Editor / Renderer 扩展语法。图表场景**优先使用内置 chart**（HTML 注释 `chartType` + 表格），**只有当内置 chartType 都不能表达诉求时才回退 Mermaid**。Triggers on keywords like 表格, 视频, 图表, 卡片, 提示块, 流程图, 语法, 怎么写, how to write table chart video card mermaid.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/antdigital-ai/agentic-ui --skill markdown-syntax-guide命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Develop TaskList for step or task status display in @ant-design/agentic-ui. Use when showing task items, expand/collapse, status icons, or thought chain in tasks. Triggers on TaskList, task list, task item, step list, TaskItem, TaskStatus.
Develop AgenticLayout (left-center-right layout with header) in @ant-design/agentic-ui. Use when building app shell, sidebar layout, or three-column layout. Triggers on AgenticLayout, layout, left center right, header, sidebar.
Guides development workflow, design system, scripts, and component inventory for @ant-design/agentic-ui. Use when onboarding, adding new components, running build/test/docs, or asking about project structure, conventions, or component list. Triggers on agentic-ui, development workflow, 开发流程, 组件清单, 设计系统, 新组件, build, test, docs, AGENTS.md.
基于 SOC 职业分类
正在显示 SKILL.md
| 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. |
当用户或 AI 需要生成可被 @ant-design/agentic-ui 的 MarkdownEditor / MarkdownRenderer 正确解析的内容时，使用本技能提供与代码实现严格对齐的语法指导。
核心原则（图表场景）：先看「图表选型决策表」 → 命中内置 chartType 就用 HTML 注释 + 表格 → 实在没有合适 chartType 才回退 Mermaid 代码块。
| 触发关键词 | 指导内容 |
|---|---|
表格, 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 代码块 |
怎么写, 语法, 格式 | 综合语法速查 |
基础 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（四象限图）。
方式一：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:自定义名称格式，渲染时会识别为视频并嵌入播放器。
铁律：先查"图表选型决策表"。命中内置
chartType一律用 HTML 注释 + 表格；仅当找不到任何合适的内置 chartType（典型如"流程图、时序图、状态机、甘特图、ER 图"等关系/流程类）时，才回退 Mermaid。
| 用户诉求 | 推荐 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 |
在 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 |
注释体写成 JSON 数组：
<!-- [{"chartType": "bar", "x": "产品", "y": "销量"}, {"chartType": "pie", "x": "产品", "y": "销量"}] -->
| 产品 | 销量 |
| :--- | ---: |
| A | 100 |
| B | 150 |
| C | 80 |
🔸 当数组里所有
chartType都为"table"时，插件会跳过转换，保留原始表格渲染。
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（显式覆盖列名映射）。当前实现已自动处理以下"用户书写不规范"的常见情况，生成示例时无需提醒用户改写数据：
"y": "销售额" 可自动匹配表头 销售额(元) / 销售额（元）（忽略括号单位后缀）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柱状图（销量对比）
<!-- {"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 |
出现以下信号时才考虑 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" |
链接卡片（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>
使用 ::: 语法（兼容 markdown-it-container）。注意：::: 与内容之间需用空行分隔。
:::info
这是信息提示块。
:::
:::warning
这是警告提示块。
:::
:::success
这是成功提示块。
:::
:::error
这是错误提示块。
:::
alt使用attachment:显示名称格式，渲染为可下载的附件链接。
任务列表
- [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: 功能说明
```
chartType 直接给注释 + 表格chartType 注释必须紧贴表格上方（中间不能有空行外的内容）；链接卡片的注释必须与链接在同一段落。x / y / groupBy / colorLegend / filterBy 都对应表头列名。列名模糊匹配已生效——写 "y": "销售额" 能命中表头 销售额(元)，无需特意写完整。8,287.44 / 12.5% / 1.2k / 1.5万 / 1.5e3 / +1,234 都会自动转 number，不要让用户手工去掉单位/逗号/百分号。[{...}, {...}]；如果数组里全是 chartType: "table"，插件会跳过转换。agentic-ui-task 任务块；复杂关系才用 Mermaid。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。