alterlab-mermaid

Markdown 和 Mermaid 写作

概述

这项技能旨在教你并规范科学文档的编写：默认且规范的格式是 使用 Markdown 并嵌入 Mermaid 图表。

核心理念：在 .md 文件中用 Mermaid 图表表达关系，胜过任何图像。它是文本，因此在 git 中可以清晰地查看差异。无需构建步骤。在 GitHub、GitLab、Notion、VS Code 和任何 Markdown 查看器中都能原生渲染。与用文字描述同一关系相比，它占用的令牌更少。之后也始终可以将它转换为精美图像，但文本版本仍然是唯一事实来源。

“尽量让报告和文件采用 .md 格式的纯文本，Mermaid 也是纯文本，同时还是一种简单的‘脚本语言’。这有助于后续进行各种渲染，尤其是生成 AI 图像（用 Mermaid 代替大段描述关系的文字，令牌占用更少）。此外，Mermaid 可以和 Markdown 一起渲染，方便人类或 AI 在几乎任何地方使用。”

— Clayton Young（@borealBytes），2026-02-19

何时使用这项技能

在以下情况下使用这项技能：

• 编写 Markdown 文档——README、操作指南、决策记录、项目文档、状态报告、分析报告
• 制作 结构图或关系图——工作流、数据管道、架构、时间线、模式
• 生成 需要纳入版本控制的输出——如果要放进 git，就应该使用 Markdown
• 有人要求你在文档中“添加图表”或“展示关系”——从 Mermaid 开始

不要用 Python matplotlib、seaborn 或 AI 图像生成来制作结构图或关系图。它们属于第 2 阶段和第 3 阶段，仅在 Mermaid 无法表达所需内容时才使用（例如，真实数据的散点图、照片级真实感图像），因为文本图表始终可以查看差异并编辑。

不适用的情况

场景	改用
起草或修改论文正文（引言、方法、讨论）	alterlab-scientific-writing / alterlab-paper-writer
为示意图或架构制作精美的 AI 渲染出版插图（PNG）	alterlab-scientific-schematics
绘制真实数值数据（散点图、分布图、热图）	alterlab-matplotlib / alterlab-seaborn
将 PDF、Office 文件或网页转换为 Markdown	alterlab-markitdown

🎨 源格式理念

为什么文本图表更胜一筹

关注点	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 可以表达的内容

此技能提供了 23 种 Mermaid 图表类型的指南，以及一份多图表组合指南。几乎所有科学关系都能用其中一种图表表示：

使用场景	图表类型	文件
实验工作流／决策逻辑	Flowchart	references/diagrams_flowchart.md
服务交互／API 调用／消息传递	Sequence	references/diagrams_sequence.md
数据模型／架构	ER diagram	references/diagrams_er.md
状态机／生命周期	State	references/diagrams_state.md
项目时间线／路线图	Gantt	references/diagrams_gantt.md
比例／组成	Pie	references/diagrams_pie.md
系统架构（缩放层级）	C4	references/diagrams_c4.md
概念层级／头脑风暴	Mindmap	references/diagrams_mindmap.md
按时间顺序排列的事件／历史	Timeline	references/diagrams_timeline.md
类层级／类型关系	Class	references/diagrams_class.md
用户旅程／满意度图	User Journey	references/diagrams_user_journey.md
双轴比较／优先级排序	Quadrant	references/diagrams_quadrant.md
需求可追溯性	Requirement	references/diagrams_requirement.md
流量大小／资源分布	Sankey	references/diagrams_sankey.md
数值趋势／柱状图 + 折线图	XY Chart	references/diagrams_xy_chart.md
组件布局／空间排列	Block	references/diagrams_block.md
工作项状态／任务列	Kanban	references/diagrams_kanban.md
云基础设施／服务拓扑	Architecture	references/diagrams_architecture.md
多维比较／技能雷达图	Radar	references/diagrams_radar.md
层级比例／预算	Treemap	references/diagrams_treemap.md
二进制协议／数据格式	Packet	references/diagrams_packet.md
Git 分支／合并策略	Git Graph	references/diagrams_git_graph.md
代码风格的序列（编程语法）	ZenUML	references/diagrams_zenuml.md
多图表组合模式	Complex Examples	references/diagrams_complex_examples.md

💡 选择合适的类型，而不是最简单的类型。 不要默认所有情况都用流程图。 表示按时间顺序排列的事件，时间线比流程图更合适；表示服务交互，序列图比流程图 更合适。查看表格并选择匹配的类型。

渲染器版本很重要。 GitHub、GitLab、Notion 和 VS Code 各自捆绑了不同版本的 Mermaid。Mermaid 12.0（2026 年 9 月）默认将流程图、类图、ER 图、状态图和需求图切换为 ELK 布局，并将 redux-color/neo 设为这些图表及序列图的默认主题和外观，因此相同的源代码在 12.x 渲染器和 11.x 渲染器上的布局与外观可能不同——不要针对某一个渲染器手动调整间距。xychart、block、sankey 和 packet 在 Mermaid 11.9–11.10 中去掉了 -beta 后缀；当前版本的 Mermaid 可解析这两种写法，本技能中使用的 -beta 形式在较旧的渲染器上也能使用。此处未提供较新类型（例如 venn-beta、ishikawa-beta、wardley-beta、swimlane、用例图、agentflow-beta）的指南；使用前请确认目标渲染器支持这些类型。

---

🔧 核心工作流

步骤 1：识别文档类型

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

文档类型	模板
拉取请求记录	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

步骤 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 后面的行中（已在 Mermaid 11.12、11.17 和 12.0 上验证）

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 渲染为 SVG 的无障碍标题和描述。Mindmap、Sankey 和 Block 图表会在解析时因包含这两个属性而失败；较旧的渲染器会导致 Treemap 失败（在 Mermaid 11.12 上观察到；11.17 和 12.0 已接受）；Timeline 和 Kanban 虽然接受这两个属性，但会将其丢弃（已在 Mermaid 11.12、11.17 和 12.0 上检查）。对于这六种类型，请在代码块正上方直接添加一段描述性斜体文字：

按方法类别划分的文献领域思维导图。Mindmap 不支持 accTitle/accDescr。

mindmap
...

---

🔗 与其他技能集成

与 alterlab-scientific-schematics 集成

alterlab-scientific-schematics 可生成 AI 驱动的出版级图像（PNG）。使用 Mermaid 图表作为示意图的简报：

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

与 alterlab-scientific-writing 配合使用

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

Workflow:
1. Use alterlab-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 alterlab-scientific-schematics only for figures that truly need photorealistic/complex rendering

与 alterlab-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 图、看板、思维导图、数据包图、饼图、象限图、雷达图、需求图、桑基图、序列图、状态图、时间线、树图、用户旅程图、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

此技能采用 Apache-2.0 许可证（其 frontmatter 中的 license），因为其大部分内容移植自上述 Apache-2.0 许可来源；整个 AlterLab Academic Skills 仓库采用 MIT 许可证（参见 THIRD_PARTY_NOTICES.md）。保留移植文件中的署名标头；单独重新分发此技能时，请附上 Apache-2.0 许可证文本。此处所做的更改已记录在仓库的 CHANGELOG 中。

---