静态结构图 mermaid 约定（图类小模块）
术-格式 · 术层 skill 全文
本页是 <code>rules/skills/drafts/bestpractice_static_structure_diagram_mermaid.md</code> 的逐字投影（仅隐私清洗，零改写）。
时点提示：本页是仓内文件 rules/skills/drafts/bestpractice_static_structure_diagram_mermaid.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。
报告元数据（frontmatter）
name: bestpractice_static_structure_diagram_mermaid
description: 静态结构图的 mermaid 操作约定（术·格式，DLS 系统 A 第二个图类小模块）。承载「理解架构」与「了解知识」两个 flavor：架构图法（C4 分层缩放为骨架，Parnas/DDD 定边界，SEI viewtype 标签定读法，flowchart TB + subgraph 落法）新写于此；概念图法指针复用现有 bestpractice_concept_map_mermaid，不重写。触发场景：按 workflow_essence_diagramming 路由到「代码/系统架构→Module/C&C 视图」或「概念/知识学习→概念图」后落笔时；给设计文档/工具画结构图时。
type: BestPractice（术·格式）
status: draft (Beta) — 2026-07-08 首版，T3219 图法设计 §2.1 落地；晋级前需真实架构图 dogfood ≥1 轮 + essence_diagram_gate 落地
created: 2026-07-08
version: 0.2.0 (draft) # 0.1.0 首版；0.2.0（2026-07-09，Y 级兼容）补 §排版质量（R1-R4 防重叠/溢出/框分界不清 + 机械自检 CHK-1..CHK-7），真源 inputs/layout_quality_ruleset.md；既有语法约定/验收不变静态结构图 mermaid 约定（图类小模块）
术 skill。何时画、怎么选图法、系统拆解方法（四正交问题）、触本质判据归道 skill workflow_essence_diagramming；本文件只管静态结构图这一类落到 mermaid 的操作约定。静态结构图回答「长什么样」（结构、层次、边界、依赖 / 概念、命题），不回答「怎么运转」（时序、状态迁移，那归动态行为图术 skill）。
目标
产出一张边全部命题化、每层块数在预算内、顶上标了 viewtype、光读图就能重建模块结构与主要依赖的 mermaid 静态结构图。两个 flavor 共享静态子内核（静态结构、部分同构、拆解逐块、命题化边），只在节点与边的语义上分工：架构图节点是模块、边是依赖/通信；概念图节点是概念、边是概念间命题。
flavor A｜架构图法（新写，本文件承载）
画一个设计态或实际系统的架构：整体结构、层次、模块边界、依赖与通信。这是 workflow_essence_diagramming §系统拆解方法（四正交问题）直接投影成图，不是从菜单单选图式。
语法约定
- 图头：
flowchart TB（架构图默认自上而下，层次与包含感最强）。关系以横向依赖为主时可flowchart LR。 - viewtype 标签（架构图独有，必标）：整图顶部或最外层 subgraph 标题里写一行，说清三件事——这张图是哪个 viewtype、答什么、不答什么。写法示例：
subgraph Sys["订单系统 · viewtype=C&C · 答:运行时谁调谁 · 不答:代码怎么组织"]。不标 viewtype 的分层方框图，边和框的语义没定义，读者不知道该带什么问题来读。 - 包含/层次用 subgraph 嵌套编码（不用箭头表达从属）：谁在谁里面靠 subgraph 嵌套一眼看出（Bertin 位置编码排第一），不靠算。一个
subgraph id["标题"]是一个容器（Container 或一层）。 - 边标注（依赖/通信，必命题化）：
A -->|"依赖短语"| B，短语与两端节点连读成一条可判真假的命题（例：ord -->|"扣减库存(同步)"| inv）。同步/异步、调用/发布、读/写等通信语义写进标注。禁止裸箭头。区分实线-->（实调用/强依赖）与虚线-.->（弱依赖/指针引用/采纳不复制）。 - 节点文本带角色语义时引号包裹，可含释义（例：
artifact["artifact.py<br/>三流投影装配"]）；含括号、冒号等特殊字符必须引号包裹，防解析失败。 - 节点形状：模块/组件默认矩形；数据存储/账本/落盘文件用
[("…")]圆柱；判断/门用{"…"}菱形。三色 classDef（existing 灰 / added 绿 / removed 红）仅在表达变更或「新增 vs 复用」对比时使用，语义与bestpractice_markdown_report既有约定一致，不另造。
拆解落法（承接四正交问题）
- 一个系统画成一束小图，不是一张大图：按 C4 逐级 zoom——Context 一张（系统在环境中的位置）、每个 Container 一张 Component 图逐级下钻。每张图对应一个受众、一个问题。
- 每层 ≤7 个节点（拆解预算按 C4 层级逐层计，不是整系统 ≤7）。一层超 7 就再下钻一级 zoom。
- 边界依据 Parnas secret：subgraph 的切分切在会变化的设计决策处，不切在处理步骤上。切完自检：这个边界后面藏的是哪个会变的决策。
- 最粗切分依据 DDD 语义边界：最外层几个 subgraph 按领域语言含义变化的地方切（含义变的地方就是该切的地方）。
- 同一套模块喂多视图：架构图取 module cut 与 C&C cut。若同一系统还要画运行时图（动态类），participant 从同一套模块来，用一个关键场景交叉校验两图对不对得上。
本 flavor 辅助阅读
- 结构的包含关系用 subgraph 嵌套（位置编码），不用算就看出谁在谁里面；依赖关系用带标注的有向边，边方向就是依赖方向，读图路径同构于依赖推理。
- 每张图配一句读法（图的一部分，不是附言）：「从 Context 图看起，选一个 Container 下钻到它的 Component 图」。
- 同构标注（可选，服务理解）：图画完显式标一句「这个分层/依赖结构像你已知的什么」，把新架构挂到读者已有心智结构上。
节点被下钻时的符号约定（边守恒的静态落法）
道 skill workflow_essence_diagramming §子系统下钻与递归拆解定了边守恒不变量：父图中进出被钻节点的每条边，必须以同名（或注明 refined 映射）出现在子图里。本节给它在静态结构图上的具体画法。
- 进出依赖边 → 子图「外部接口位」节点：父图里某节点
N被判为子系统要下钻（标▼），先数清N在父图上的每条进边和出边（谁依赖它、它依赖谁）。画N的内部子图时，把这些边的对端各落成一个外部接口位节点——一圈占位节点摆在子图边缘，代表「来自外部的依赖入口 / 通向外部的依赖出口」，内部模块只跟这些外部接口位连，不直接跳到父图的真实模块名。 - 外部接口位画法：用区别于内部模块的形状/样式，标签写清对端 + 方向，例：
ext_up["◄ 来自 hook：触发装配"]、ext_dn["► 去 ledger：写落盘"]。可用一个subgraph Boundary["外部接口（父图进出边）"]把这一圈框起来，与内部模块区隔。 - 边守恒自检（画完必查）：父图中
N的进出边标签集合，应 ⊆ 子图外部接口位边标签集合 ∪ refined 映射表。对不上就是有一张图切错了——要么父图漏画了一条N的依赖，要么子图内部凭空多/少了一个对外接口。refined 情况（父图一条粗边在子图裂成两条细边）在子图旁写一行映射说明。 - 不做的事：外部接口位只承载父图已有的进出边，不在子图里替
N新增对外依赖（那是父图该改）；也不把父图真实模块整个搬进子图当背景（混层，违反 C4 一层一问题）。子图只画N内部 + 一圈外部接口位。
flavor B｜概念图法（指针复用，不在此重写）
「了解知识」——一个概念由什么组成、和别的概念什么关系——用 Novak 概念图，节点是概念、边是带语义标注的命题（A -->|"关系短语"| B），拆解预算 ≤7。操作约定、卡片集成四段序、复习指令位置全部沿用 bestpractice_concept_map_mermaid，本文件不复制。它和架构图法共享同一套静态子内核（同一套拆解、同一条部分同构），区别只在架构图节点是模块、概念图节点是概念。已有 4 张真卡（contexts/knowledge_cards/）是现成用例，直接接进来。
边界提醒：理解一个概念的结构是静态（用本类）；理解一个机制的运转过程（一步步怎么跑）是动态，归动态行为图术 skill。判据是「你要展示它的结构还是它的运转」，不是「它是知识还是架构」。
验收标准（无上下文 agent 可自判）
确定层（机械可查）：
- mermaid 可解析（渲染器或结构校验通过；当前无渲染管线，走 subgraph 嵌套合法 + 语法结构校验）。
- 边标注率 100%：无一条裸箭头。
- 每层一级块数 ≤7（超了说明该再下钻一级）。
- 架构图有 viewtype 标签（答什么/不答什么齐）；概念图 propositions 与图边一致。
语义层（派独立 regulator 判，给可定位反例）：
- 架构图：光读这张图，能不能重建系统的模块结构和主要依赖；重建不出的地方就是可定位反例（缺哪个模块、哪条依赖没画、哪个边界模糊）。
- 概念图：光读这张图，能不能复述概念间命题。
排版质量（防文字重叠/溢出/框分界不清，机械可检）
Opus 亲画的图排版干净、Sonnet 常出现文字重叠溢出，实测根因是三个可量化指标（真源 adhoc_jobs/diagram_learning_systems_20260701/dogfood_ddp_20260708/inputs/layout_quality_ruleset.md，阈值取自 Opus 实测值）。画完按下面自检，超阈值就改：
- R1 单节点标签 ≤40 字符（中文按字计；多路汇聚节点[连边≥4]可放宽到 60）。超了就把细节挪到边标签（
A -->|"具体说明"| B）或拆成子节点，别硬塞一个框。Opus 中位 22、从不超 59；Sonnet 常到 100+ 就是溢出主因。 - R2 单节点
<br/>≤1（最多标题+一句，共 2 行）。想列 3 条以上要点别塞一个框，各拆一节点或移到图外文字。Opus 硬上限 1，Sonnet 到 5。 - R3 subgraph 嵌套 ≤1 层（不做框里套框）。mermaid
subGraphTitleMargin默认 0，多层带标题嵌套直接导致"框分界不清"。要表达总-分就拆成多张图（总领一张 + 每块一张），不在一张里用嵌套硬做。 - R4 subgraph 标题 ≤30 字符：viewtype/答什么-不答什么这类契约放在 mermaid block 前面的独立文字段（本 skill §语法约定的 viewtype 标签也可用
%%注释承载），别塞进 subgraph 标题行。 - 机械自检：
python3 <checker> <file.md>跑 CHK-1..CHK-7（节点字符数/<br/>数/嵌套深度/标题长度），超阈值 FLAG 给具体节点名。别凭感觉判"够不够挤"。
已知陷阱
- 节点/边文本含括号、冒号、斜杠等字符时不加引号会解析失败——全部文本一律引号包裹最省心（承 concept_map r002 真实教训）。
- viewtype 标签漏标 = 分层方框图退化成「谁都以为看得懂、其实语义没定义」的图（SEI 点名的反模式）。补标就修好。
- 整系统 ≤7 会逼着把复杂系统硬压进一张图，节点挤成一团——正解是逐层 ≤7 + C4 下钻，不是删信息。
- 其余待 dogfood 回填，不预测凑数。
可用资源
- 上游道 skill：
workflow_essence_diagramming（何时画/选图法/四正交拆解方法/六纪律）。 - 概念图 flavor：
bestpractice_concept_map_mermaid+contexts/knowledge_cards/4 张真卡。 - 动态行为图（怎么运转）：动态行为图术 skill（时序 + 状态机 flavor，与本类互补）。
- 变更类图法：
workflow_change_visualization+bestpractice_markdown_report（三色 classDef 语义来源）。 - 理论锚（库内已蒸馏，不外求）：
software_architecture_in_practice（SEI《Documenting Software Architectures》，viewtype/structure-vs-view）、just_enough_software_architecture、design_it。 - 首个真实用例：
adhoc_jobs/diagram_learning_systems_20260701/dogfood_ddp_20260708/（DDP 设计态架构图，2026-07-08）。