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 图像生成开始。 这些属于第 2 阶段和第 3 阶段——仅在 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

**第 1 阶段是必需的。**即使继续进入第 2 或第 3 阶段，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/ — 架构图、块图、c4、类图、complex_examples、er、流程图、甘特图、git_graph、看板、思维导图、数据包、饼图、象限图、雷达图、需求图、桑基图、时序图、状态图、时间线、树图、用户旅程、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 License。

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

此技能（作为 academic-skills 的一部分）遵循 MIT License 分发。所包含的 Apache-2.0 内容适用于下游使用，但须保留署名；整个技能的文件头中均保留了相关信息。

---