概念图 mermaid 约定（图类小模块）
Z3 全文↑ Z2 条目
术-格式 · 术层 skill 全文
本页是 <code>rules/skills/drafts/bestpractice_concept_map_mermaid.md</code> 的逐字投影（仅隐私清洗，零改写）。
时点提示：本页是仓内文件 rules/skills/drafts/bestpractice_concept_map_mermaid.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。
报告元数据（frontmatter）
name: bestpractice_concept_map_mermaid
description: 概念图的 mermaid 操作约定（术·格式，DLS 系统 A 首个图类小模块）。labeled-edge 语法、命题化边的写法、拆解预算、复习指令位置、卡片集成。触发场景：按 workflow_essence_diagramming 路由到"概念/知识学习→概念图"后落笔时；给知识卡片写 canonical 图时。
type: BestPractice（术·格式）
status: draft (Beta) — r002 首版，已有 4 张真卡用例（contexts/knowledge_cards/）
created: 2026-07-03
version: 0.1.0 (draft)概念图 mermaid 约定（图类小模块）
术 skill。何时画、怎么选图法、触本质判据归道 skill workflow_essence_diagramming；本文件只管概念图这一类落到 mermaid 的操作约定。
目标
产出一张边全部命题化、块数在预算内、能直接进知识卡片的 mermaid 概念图。
语法约定
- 图头：
flowchart LR（关系链为主）或flowchart TB（层级/汇聚为主）。 - 边标注：
A -->|"关系短语"| B，短语与两端节点连读成一条可判真假的命题（例：q -->|"与全部 K 点积并缩放"| s）。禁止裸箭头。 - 节点文本带角色语义时用引号包裹并可含释义（例：
q["Q：我在找什么"]）；含特殊字符（括号、冒号）必须引号包裹，防解析失败。 - 节点形状：默认矩形；数据存储/缓存用
[("…")]圆柱；判断分支用{"…"}。三色 classDef（existing 灰 / added 绿 / removed 红）仅在表达变更时使用，语义与bestpractice_markdown_report既有约定一致，不另造。 - 单图一级块 ≤7（拆解预算）；超了就按道 skill 纪律拆成块序列，逐块小图 + 一张合成图。
卡片集成（学习场景）
- frontmatter
propositions列表从图边提取：每条命题对应至少一条边，边与命题不允许各说各话。 - 正文顺序固定：复习指令（"不看下文，凭记忆画/述 X"）→ 拆解块序列 → canonical mermaid → 同构标注。复习指令必须在 canonical 之前，防复习时剧透。
- 同构标注节引用来源锚（survey 行号 / 库内蒸馏资产路径），不留无源断言。
验收标准
- mermaid 可解析（渲染器或 CI 校验通过）。
- 边标注率 100%：无一条裸箭头。
- 每条 proposition 能指到对应的边；每条边连读成句后可判真假。
- 一级块数 ≤7；卡片正文四段序完整（复习指令在 canonical 前）。
已知陷阱
- 节点/边文本含括号、冒号等字符时不加引号会解析失败——全部文本一律引号包裹最省心（r002 落卡时的真实处理方式）。
- 其余待 dogfood 回填，不预测凑数。
可用资源
- 真实用例：
contexts/knowledge_cards/kc_attention_qkv.md（概念卡）、kc_kv_cache.md（结构卡）、kc_kv_cache_decode_flow.md（sequenceDiagram 过程卡，时序类参照）、kc_rope.md（机制卡）。 - 上游道 skill：
workflow_essence_diagramming；变更类图法：workflow_change_visualization+bestpractice_markdown_report。