markdown-mermaid-writing

Markdown 与 Mermaid 写作

概述

本技能为 使用 Mermaid 结构图的 Markdown 文档 提供一套可选的内部风格。请优先遵循所要求的输出格式、仓库既有约定和期刊要求。本技能不能替代科学分析或绘图。

在 .md 文件中以 Mermaid 表达的关系是可编辑文本，在 git 中能干净地生成 diff。兼容的宿主无需单独的用户构建步骤即可渲染它。它会在宿主支持 Mermaid 的地方渲染；普通 Markdown 查看器可能只显示代码，而不同平台/扩展附带的 Mermaid 版本各异。它采用紧凑的源表示形式，不过 token 用量取决于具体图表。导出 SVG/PNG 需要渲染器；请将图表源文件与导出的图一并保留。

“你越是把报告和文件以纯文本形式的 .md 保存，mermaid 也是如此，它同时是一种简单的‘脚本语言’。这有助于任何下游渲染，尤其是 AI 生成的图像（用 mermaid 而不是仅用长篇文字来描述关系 < tokens）。此外，mermaid 可以与 markdown 一起渲染，便于人类或 AI 几乎在任何地方轻松使用。”

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

何时使用本技能

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

• 撰写所需的 Markdown 报告、README、方法概述或研究笔记
• 绘制工作流、数据管道、模式、状态机或概念关系图
• 维护可编辑的 Mermaid 源文件及其渲染后的 SVG/PNG 导出图

对于实测数据、不确定性、统计图形、精确几何或 Mermaid 无法忠实呈现的出版级图，请直接使用科学绘图工具。Mermaid 不是定量图表或现有 SVG/代码原生资源的必需前置步骤。

🎨 源格式理念

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

关注点	Markdown 中的 Mermaid	Python / AI 图像
Git diff 可读	✅ 文本源	绘图代码/SVG 也可以是文本
可编辑源	✅	绘图脚本和矢量源可编辑
紧凑的关系表示法	通常	取决于表示方式
原生预览	取决于宿主/版本	取决于查看器/格式
无需视觉即可被 AI 解析	✅	❌
在目标环境中可用	检查 Mermaid 支持与版本	检查图像格式支持
无障碍（屏幕阅读器）	检查 SVG 元数据和文本替代	提供 alt 文本/数据表
之后可转换为图像	✅ 随时	— 已是图像

三阶段工作流

flowchart LR
    accTitle: Three-Phase Documentation Workflow
    accDescr: Markdown holds the structural diagram source. Quantitative charts come from data and plotting code; optional illustrations require a separate factual review.

    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(structural source)"]
    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
    data["Data and plotting code"] --> 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，对定量图表保留数据/代码。AI 插图不是定量转换；请对照其来源核验每个标签和关系。

Mermaid 能表达什么

本技能包含 23 个图表类型指南以及一个组合指南。Mermaid 支持更多类型；这些参考是经过筛选的子集，并非完整的版本目录：

使用场景	图表类型	文件
实验性工作流 / 决策逻辑	流程图	references/diagrams/flowchart.md
服务交互 / API 调用 / 消息传递	时序图	references/diagrams/sequence.md
数据模型 / schema	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 步：阅读风格指南

对于此 Markdown 工作流，请阅读 references/markdown_style_guide.md。将 emoji、标题数量和水平分隔线视为项目内部风格，而不是 Markdown 语法要求。

需要内化的关键规则：

• 每篇文档一个 H1 —— 即标题。绝不要更多。
• 仅在 H2 标题上使用 emoji —— 每个 H2 一个 emoji，H3/H4 中不用
• 为事实主张提供依据 —— 使用经过核实的来源和要求的引用格式
• 谨慎使用加粗 —— 每段最多 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} 指令已弃用，建议改用 YAML 配置
• 在支持的情况下优先使用可复用的 classDef；样式语法因图表类型而异
• 每个节点最多一个 emoji —— 放在标签开头
• 使用符合该类型语法的描述性 ID：snake_case 适用于流程图；ER/类/状态图的约定有所不同

第 4 步：撰写文档

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

交付前在实际目标环境中渲染。在选择较新的图表类型之前，检查其 Mermaid 版本和插件要求；GitHub 为此项检查提供了 info 图表。 在最新版本上本地预览成功，并不能证明 GitHub 或其他宿主会正常渲染。在不支持 Mermaid 的地方，请提供渲染后的 SVG/PNG 及文字说明，并保留 .md 源文件。

第 5 步：保留源文件和验证信息

将 .md 源文件、渲染后的交付物和经过测试的渲染器版本保留在一起。 遵循项目的版本控制工作流；此技能本身并不授权提交或发布。 有关命令行导出、嵌入和经过测试的无障碍矩阵，请阅读 当前渲染与验证。

---

⚠️ 常见陷阱

雷达图语法（radar-beta）

错误（以文本形式显示，以免破坏文档渲染器）：

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

正确：

radar-beta
accTitle: Example Radar Scores
accDescr: Illustrative values of one, two, and three on a shared zero-to-three scale.
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3

• 使用 radar-beta，而不是 radar（裸关键字不存在）
• 使用 axis 定义维度，而不是 x-axis
• 使用 curve 定义数据系列，而不是带引号且带冒号的标签
• Mermaid 12.0.0 雷达图会输出 accTitle/accDescr；请检查较旧的宿主，并保留可见的描述

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。对于不支持的类型，请始终在代码块正上方放置一个描述性斜体段落：

雷达图在明确、统一的评分尺度上比较三种方法。确切数值见数据表。

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 搭配使用

对于使用 Mermaid 结构图的稿件，此技能负责处理图表语法。 请遵循稿件要求的图表格式和科学可视化惯例。

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 plotting or schematic tools where appropriate to the scientific content

与 literature-review 搭配使用

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

• 创建文献全景的概念图（Mindmap）
• 展示发表时间线（Timeline 或 Gantt）
• 比较研究方法（Quadrant 或 Radar）
• 为论文中描述的数据流绘制图表（Sequence 或 Flowchart）

与任何生成输出文档的技能搭配使用

在使用此技能最终确定文档之前，请检查：

• 文档是否使用了模板？如果是，我是否从正确的模板开始？
• 每个图表是否采用合适的格式，并具有可用的无障碍元数据或文本替代方案？
• 配置是否受目标环境支持，并已在浅色/深色主题下测试？
• 引用是否支撑了外部论断，合成值是否已标注？
• 是否只有一个 H1，emoji 是否仅用于 H2？
• 最终的 Markdown/HTML 结构是否能正确渲染？

---

📚 参考索引

风格指南

指南	路径	行数	涵盖内容
Markdown 风格指南	references/markdown_style_guide.md	见文件	标题、格式、引用、表格、Mermaid 集成、模板、质量检查清单
Mermaid 风格指南	references/mermaid_style_guide.md	见文件	无障碍、emoji 集、颜色类、主题中立性、类型选择、复杂度层级
当前渲染	references/current-rendering.md	见文件	Mermaid 12 变更、CLI 导出、浏览器 API、已测试的无障碍矩阵、科学检查

图表指南（23 种类型外加组合）

每个文件包含：生产级范例、该类型专属技巧，以及可直接复制粘贴的模板。

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 — 一份合成质量控制报告，包含明确虚构的数据、可审计的计数表、结构流程图、条形图和时间顺序表。它不含任何实验或软件 API 相关主张。

---

📝 署名

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

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

此技能（作为 scientific-agent-skills 的一部分）在 MIT 许可证下分发。所包含的 Apache-2.0 内容可在保留署名的情况下用于下游用途，此技能中所有文件头部均已保留相应署名。

---