markdown-mermaid-writing

Markdown 和 Mermaid 编写

概述

本技能教你——并强制执行一种标准——使用 markdown 并嵌入 Mermaid 图表作为默认和规范格式 来创建科学文档。

核心信念：在 .md 文件中用 Mermaid 图表表达的关系比任何图像都更有价值。它是文本，因此可以在 git 中干净地 diff。它不需要构建步骤。它在 GitHub、GitLab、Notion、VS Code 以及任何 markdown 查看器中原生渲染。它比用散文描述相同关系使用更少的 token。而且它以后总是可以转换为精美的图像——但文本版本仍然是事实来源。

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

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

何时使用此技能

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

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

对于结构或关系图表，不要从 Python matplotlib、seaborn 或 AI 图像生成开始。那些是第二阶段和第三阶段——仅在 Mermaid 无法表达所需内容时使用（例如，带有真实数据的散点图、逼真图像）。

🎨 源格式理念

为什么基于文本的图表胜出

重要事项	Markdown 中的 Mermaid	Python / AI 图像
Git diff 可读	✅	❌ 二进制 blob
无需重新生成即可编辑	✅	❌
与散文相比 token 高效	✅ 更小	❌ 更大
无需构建步骤即可渲染	✅	❌ 需要托管
AI 无需视觉即可解析	✅	❌
在 GitHub / GitLab / Notion 中工作	✅	⚠️ 如果托管
可访问（屏幕阅读器）	✅ accTitle/accDescr	⚠️ 需要替代文本
以后可转换为图像	✅ 随时	— 已经是图像

三阶段工作流

flowchart LR
    accTitle: 三阶段文档工作流
    accDescr: 第一阶段 Markdown 中的 Mermaid 始终必需，是事实来源。第二阶段和第三阶段是可选的，用于精美输出的下游转换。

    p1["📄 第一阶段<br/>Markdown 中的 Mermaid<br/>（始终 — 事实来源）"]
    p2["🐍 第二阶段<br/>Python 生成<br/>（可选 — 数据图表）"]
    p3["🎨 第三阶段<br/>AI 生成视觉<br/>（可选 — 润色）"]
    out["📊 最终交付物"]

    p1 --> out
    p1 -.->|"需要时"| p2
    p1 -.->|"需要时"| 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

💡 选择正确的类型，而不是简单的类型。 不要对所有内容都默认使用流程图。
对于按时间顺序的事件，时间线优于流程图。对于服务交互，序列图优于流程图。
扫描表格并进行匹配。

---

🔧 核心工作流

第一步：确定文档类型

在从头编写之前，检查是否存在模板：

文档类型	模板
拉取请求记录	templates/pull_request.md
问题 / 缺陷 / 功能请求	templates/issue.md
冲刺 / 项目板	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

第二步：阅读样式指南

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

需要内化的关键规则：

• 每个文档一个 H1 — 标题。永远不要更多。
• 仅在 H2 标题上使用表情符号 — 每个 H2 一个表情符号，H3/H4 中不使用
• 引用所有内容 — 每个外部声明都添加脚注 [^N] 并包含完整 URL
• 谨慎使用粗体 — 每段最多 2-3 个粗体术语，绝不使用完整句子
• 每个 </details> 后加水平线 — 强制要求
• 比较、配置、结构化数据使用表格而非散文
• 图表优于文本墙 — 如果描述流程、结构或关系，添加 Mermaid

第三步：选择图表类型并阅读其指南

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

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

每个图表的强制规则：

accTitle: 短名称 3-8 个单词
accDescr: 一两句话解释此图表显示的内容。

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

第四步：编写文档

从模板开始。应用 markdown 样式指南。将图表与相关文本内联放置——而不是放在单独的“图表”部分。

第五步：作为文本提交

嵌入 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 图表作为示意图的 简报：

工作流：
1. 在 .md 中创建概念为 Mermaid（此技能 — 第一阶段）
2. 将相同概念描述给 scientific-schematics 以生成精美的 PNG（第三阶段）
3. 提交两者 — .md 作为源，PNG 作为补充图

与 scientific-writing 集成

当 scientific-writing 生成手稿时，所有图表和结构图应使用此技能的标准。写作技能处理散文和引用；此技能处理视觉结构。

工作流：
1. 使用 scientific-writing 起草手稿
2. 对于每个显示工作流、架构或关系的图：
   - 用遵循此技能指南的 Mermaid 图表替换占位符
3. 仅对真正需要逼真/复杂渲染的图使用 scientific-schematics

与 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

此技能（作为 scientific-agent-skills 的一部分）根据 MIT 许可证分发。包含的 Apache-2.0 内容兼容下游使用，并保留署名，如本技能各文件头所示。

---

[^1]: GitHub Blog. (2022). "Include diagrams in your Markdown files with Mermaid." https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

[^2]: Mermaid. "Mermaid Diagramming and Charting Tool." https://mermaid.js.org/