markdown-mermaid-writing

Markdown 与 Mermaid 编写

概述

本技能将教你如何使用 内嵌 Mermaid 图表的 Markdown 作为默认且规范的格式来编写科学文档，并强制执行这一标准。

核心理念：在 .md 文件中用 Mermaid 图表表达关系，比任何图片都更有价值。它是文本，因此在 git 中可以清晰地进行差异比较。它无需构建步骤。它可在 GitHub、GitLab、Notion、VS Code 和任何 Markdown 查看器中原生渲染。与用文字描述同一关系相比，它消耗的令牌更少。而且它随时可以转换为精美图片——但文本版本始终是事实来源。

“尽量用普通文本将报告和文件写成 .md 格式，Mermaid 也是如此，此外它还是一种简单的‘脚本语言’。这有助于后续的各种渲染，尤其是 AI 生成图片（用 Mermaid 代替冗长的文字来描述关系，能减少令牌消耗）。此外，Mermaid 可以与 Markdown 一同渲染，让人类或 AI 几乎可以在任何地方轻松使用。”

— Clayton Young (@borealBytes)，2026-02-19

何时使用此技能

在以下情况下使用此技能：

• 创建任何科学文档——报告、分析、手稿、方法部分
• 编写任何文档——README、操作指南、决策记录、项目文档
• 制作任何图表——工作流、数据管道、架构、时间线、关系
• 生成任何将纳入版本控制的输出——如果要放进 git，就应该使用 Markdown
• 配合任何其他技能工作——此技能定义了包裹其他所有输出的文档层
• 有人要求你“添加图表”或“可视化关系”——始终优先使用 Mermaid

对于结构图或关系图，不要一开始就使用 Python matplotlib、seaborn 或 AI 图像生成。 这些属于第二阶段和第三阶段——仅当 Mermaid 无法表达所需内容时才使用（例如，包含真实数据的散点图、照片级图像）。

🎨 源格式理念

为什么基于文本的图表更胜一筹

关注点	Markdown 中的 Mermaid	Python / AI 图像
git 差异易于阅读	✅	❌ 二进制文件
无需重新生成即可编辑	✅	❌
相比文字描述更省令牌	✅ 更少	❌ 更多
无需构建步骤即可渲染	✅	❌ 需要托管
无需视觉识别即可供 AI 解析	✅	❌
适用于 GitHub / GitLab / Notion	✅	⚠️ 需托管
无障碍（屏幕阅读器）	✅ accTitle/accDescr	⚠️ 需要替代文本
可在之后转换为图像	✅ 随时	— 本身已是图像

三阶段工作流

flowchart LR
    accTitle: Three-Phase Documentation Workflow
    accDescr: Phase 1 Mermaid in markdown is always required and is the source of truth. Phases 2 and 3 are optional downstream conversions for polished output.

    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
    p2["🐍 Phase 2<br/>Python Generated<br/>(optional — data charts)"]
    p3["🎨 Phase 3<br/>AI Generated Visuals<br/>(optional — polish)"]
    out["📊 Final Deliverable"]

    p1 --> out
    p1 -.->|"when needed"| p2
    p1 -.->|"when needed"| p3
    p2 --> out
    p3 --> out

    classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class p1 required
    class p2,p3 optional
    class out output

第一阶段是强制的。 即使你继续进入第二或第三阶段，也要提交 Mermaid 源码。

Mermaid 能表达的内容

Mermaid 支持 24 种图表类型。几乎所有科学关系都能用其中一种来表达：

使用场景	图表类型	文件
实验工作流 / 决策逻辑	流程图	references/diagrams/flowchart.md
服务交互 / API 调用 / 消息传递	时序图	references/diagrams/sequence.md
数据模型 / 架构	ER 图	references/diagrams/er.md
状态机 / 生命周期	状态图	references/diagrams/state.md
项目时间线 / 路线图	甘特图	references/diagrams/gantt.md
占比 / 构成	饼图	references/diagrams/pie.md
系统架构（缩放层级）	C4	references/diagrams/c4.md
概念层级 / 头脑风暴	思维导图	references/diagrams/mindmap.md
按时间顺序排列的事件 / 历史	时间线	references/diagrams/timeline.md
类层级 / 类型关系	类图	references/diagrams/class.md
用户旅程 / 满意度地图	用户旅程	references/diagrams/user_journey.md
双轴比较 / 优先级排序	象限图	references/diagrams/quadrant.md
需求可追溯性	需求图	references/diagrams/requirement.md
流量大小 / 资源分布	桑基图	references/diagrams/sankey.md
数值趋势 / 柱状图 + 折线图	XY 图表	references/diagrams/xy_chart.md
组件布局 / 空间排列	块图	references/diagrams/block.md
工作项状态 / 任务列	看板	references/diagrams/kanban.md
云基础设施 / 服务拓扑	架构图	references/diagrams/architecture.md
多维比较 / 技能雷达图	雷达图	references/diagrams/radar.md
层级占比 / 预算	矩形式树图	references/diagrams/treemap.md
二进制协议 / 数据格式	数据包图	references/diagrams/packet.md
Git 分支 / 合并策略	Git 图	references/diagrams/git_graph.md
代码风格的时序图（编程语法）	ZenUML	references/diagrams/zenuml.md
多图组合模式	复杂示例	references/diagrams/complex_examples.md

💡 选择合适的类型，而不是最容易的类型。 不要事事都默认使用流程图。 时间线比流程图更适合表示按时间顺序排列的事件；时序图比流程图更适合表示 服务交互。浏览表格并选择匹配的类型。

---

🔧 核心工作流

步骤 1：确定文档类型

从头开始编写前，先检查是否存在模板：

文档类型	模板
Pull request 记录	templates/pull_request.md
Issue / bug / 功能请求	templates/issue.md
Sprint / 项目看板	templates/kanban.md
架构决策（ADR）	templates/decision_record.md
演示 / 简报	templates/presentation.md
研究论文 / 分析	templates/research_paper.md
项目文档	templates/project_documentation.md
操作指南 / 教程	templates/how_to_guide.md
状态报告	templates/status_report.md

步骤 2：阅读风格指南

编写任何 .md 文件前：阅读 references/markdown_style_guide.md。

需要牢记的关键规则：

• 每份文档只能有一个 H1 —— 即标题。绝不能多于一个。
• 仅在 H2 标题中使用表情符号 —— 每个 H2 使用一个表情符号，H3/H4 中不使用
• 所有内容都要引用 —— 每项外部论述都要添加带完整 URL 的脚注 [^N]
• 谨慎使用粗体 —— 每段最多 2-3 个加粗术语，绝不加粗完整句子
• 每个 </details> 后都要加水平分隔线 —— 必须遵守
• 比较、配置和结构化数据优先使用表格，而非散文
• 优先使用图表，而非大段文字 —— 如果内容描述流程、结构或关系，就添加 Mermaid

步骤 3：选择图表类型并阅读指南

创建任何 Mermaid 图表之前：先阅读 references/mermaid_style_guide.md。

然后打开对应类型的文件（例如 references/diagrams/flowchart.md），查看示例、提示和可复制粘贴的模板。

每张图表都必须遵守以下规则：

accTitle: Short Name 3-8 Words
accDescr: One or two sentences explaining what this diagram shows.

• 不要使用 %%{init} 指令——这会破坏 GitHub 深色模式
• 不要使用内联 style——仅使用 classDef
• 每个节点最多使用一个表情符号——放在标签开头
• 节点 ID 使用 snake_case——与标签相匹配

步骤 4：编写文档

从模板开始。应用 Markdown 风格指南。将图表放在相关文本旁边，不要放在单独的“Figures”章节中。

步骤 5：以文本形式提交

提交的内容是嵌入 Mermaid 的 .md 文件。如果还生成了 PNG 或 AI 图像，它们都只是补充内容——Markdown 才是源文件。

---

⚠️ 常见问题

雷达图语法（radar-beta）

错误：

radar
title Example
x-axis ["A", "B", "C"]
"Series" : [1, 2, 3]

正确：

radar-beta
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3

• 使用 radar-beta，不要使用 radar（不存在这个单独的关键字）
• 使用 axis 定义维度，不要使用 x-axis
• 使用 curve 定义数据系列，不要使用带冒号的引号标签
• 不要使用 accTitle/accDescr——radar-beta 不支持无障碍注释；请始终在图表上方添加描述性斜体段落

XY 图表与雷达图的区别

图表	关键字	轴语法	数据语法
XY 图表（柱形／折线）	xychart-beta	x-axis ["Label1", "Label2"]	bar [10, 20] 或 line [10, 20]
雷达图（蜘蛛网／网状）	radar-beta	axis id["Label"]	curve id["Label"]{10, 20}

忘记在支持的类型中使用 accTitle/accDescr

只有部分图表类型支持 accTitle/accDescr。对于不支持的类型，请始终在代码块正上方放置描述性斜体段落：

雷达图对比了三种方法在五个性能维度上的表现。注意：雷达图不支持 accTitle/accDescr。

radar-beta
...

---

🔗 与其他技能集成

与 scientific-schematics 配合

scientific-schematics 可生成 AI 驱动的出版级图像（PNG）。将 Mermaid 图表用作示意图的设计说明：

Workflow:
1. Create the concept as Mermaid in .md (this skill — Phase 1)
2. Describe the same concept to scientific-schematics for a polished PNG (Phase 3)
3. Commit both — the .md as source, the PNG as a supplementary figure

与 scientific-writing 配合

scientific-writing 生成稿件时，所有图表和结构图都应遵循本技能的标准。写作技能负责正文和引用；本技能负责视觉结构。

Workflow:
1. Use scientific-writing to draft the manuscript
2. For every figure that shows a workflow, architecture, or relationship:
   - Replace placeholder with a Mermaid diagram following this skill's guide
3. Use scientific-schematics only for figures that truly need photorealistic/complex rendering

与 literature-review 配合

文献综述会生成包含大量关系数据的摘要。使用本技能来：

• 创建文献领域的概念图（思维导图）
• 展示发表时间线（时间线或甘特图）
• 比较研究方法（象限图或雷达图）
• 绘制论文中描述的数据流图（时序图或流程图）

与任何会生成输出文档的技能配合

在完成任何技能生成的文档之前，请应用本技能的检查清单：

• 文档是否使用了模板？如果使用了，我是否从正确的模板开始？
• 所有图表是否都使用 Mermaid，并包含 accTitle + accDescr？
• 是否没有 %%{init}、没有内联 style，且只使用 classDef？
• 所有外部论断是否都使用 [^N] 标注了引用？
• 是否只有一个 H1，且表情符号只出现在 H2 上？
• 每个 </details> 后是否都有水平分隔线？

---

📚 参考索引

风格指南

指南	路径	行数	内容
Markdown 风格指南	references/markdown_style_guide.md	~733	标题、格式、引用、表格、Mermaid 集成、模板、质量检查清单
Mermaid 风格指南	references/mermaid_style_guide.md	~458	无障碍性、表情符号集、颜色类、主题中立性、类型选择、复杂度等级

图表类型指南（24 种）

每个文件都包含：可用于生产环境的范例、针对该类型的提示，以及可复制粘贴的模板。

references/diagrams/ — architecture、block、c4、class、complex_examples、er、flowchart、gantt、git_graph、kanban、mindmap、packet、pie、quadrant、radar、requirement、sankey、sequence、state、timeline、treemap、user_journey、xy_chart、zenuml

文档模板（9 种）

templates/ — decision_record、how_to_guide、issue、kanban、presentation、project_documentation、pull_request、research_paper、status_report

示例

assets/examples/example-research-report.md — 一份完整的科学研究报告，展示了恰当的标题层级、多种图表类型（流程图、时序图、甘特图）、表格、脚注引用、可折叠章节，以及所有已应用的风格指南规则。

---

📝 署名

本技能中的所有风格指南、图表类型指南和文档模板均移植自 SuperiorByteWorks-LLC/agent-project 仓库，该仓库采用 Apache-2.0 许可证。

• 来源：https://github.com/SuperiorByteWorks-LLC/agent-project
• 作者：Clayton Young / Superior Byte Works, LLC（@borealBytes）
• 许可证：Apache-2.0

本技能（作为 research-agent-skills 的一部分）采用 MIT 许可证分发。所含 Apache-2.0 内容可兼容下游使用，但须保留署名；本技能各处文件头中均保留了相关署名。

---

Agent 操作流程

1. 检查环境。 开始写作前，收集用户的草稿、数据、图表和目标发表平台。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先做小规模版本。 起草一个章节或段落，并与用户确认语气、结构和术语。
4. 使用以上说明和参考资料完成全部任务。
5. 验证结果。 每项陈述都有用户数据或经过核实的来源作为依据；数字与表格和图表一致；引用真实有效（citation-verification）。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
某项陈述没有数据或引用作为依据	在文本中标出（例如 [citation needed]），不要编造依据。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），调整做法并告知用户。切勿编造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿伪造结果、参数、标识符、引用或统计数据。如果某项内容无法运行或验证，请如实说明。
• 用户是作者：切勿添加用户未提供或未批准的结果、参考资料或陈述。
• 请将此处与版本相关的细节视为可能已过时，并根据已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，执行前必须征得用户同意。

相关技能

• literature-review：通过检索 PubMed、arXiv、bioRxiv 和 Semantic Scholar（以及通过 parallel-cli 进行网页搜索），开展系统性文献综述、筛选……
• academic-plotting：根据研究背景，为 ML 论文生成可用于发表的高质量图表。