markdown-mermaid-writing

Markdown 与 Mermaid 编写

概述

本技能教你——并强制执行一个标准——使用 Markdown 中嵌入 Mermaid 图表作为默认和规范格式 进行科学文档编写。

核心假设：以 .md 文件中的 Mermaid 图表表达的关系，其价值高于任何图片。它是文本，因此在 git 中可以清晰地 diff。它无需构建步骤。它在 GitHub、GitLab、Notion、VS Code 以及任何 Markdown 查看器中都能原生渲染。它比用散文描述同样的关系使用更少的 token。并且以后随时可以转换为精美的图片——但文本版本始终是真理源。

“你的报告和文件越是采用 .md 格式，内容越是普通文本，而 mermaid 本身也是一种简单的‘脚本语言’，这对任何下游渲染都很有帮助，尤其是 AI 生成的图像（使用 mermaid 而不是冗长的文本来描述关系 < token）。此外，mermaid 可以与 markdown 一起渲染，让人或 AI 几乎在任何地方都能轻松使用。”

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

何时使用此技能

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

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

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

🎨 源格式哲学

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

重要特性	Markdown 中的 Mermaid	Python / AI 图像
Git diff 可读	✅	❌ 二进制 blob
无需重新生成即可编辑	✅	❌
相比散文更节省 token	✅ 更少	❌ 更多
无需构建步骤即可渲染	✅	❌ 需要托管
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 步：确定文档类型

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

文档类型	模板
拉取请求记录	templates/pull_request.md
问题 / 错误 / 功能请求	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 标题上使用 Emoji — 每个 H2 一个 emoji，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
• 每个节点最多一个 emoji — 放在标签开头
• 使用 snake_case 节点 ID — 与标签匹配

第 4 步：编写文档

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

第 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 图表作为生成示意图的概要：

工作流：
1. 将概念创建为 .md 中的 Mermaid 图表（此技能 — 阶段 1）
2. 向 scientific-schematics 描述相同概念，以生成精美的 PNG 图像（阶段 3）
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，且 emoji 仅在 H2 上使用？
• 每个 </details> 后面是否都有水平线？

---

📚 参考索引

样式指南

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

图表类型指南（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 内容兼容用于下游使用，并保留归属，如同本技能中文件头所保留的那样。

---