动态行为图 mermaid 约定（图类小模块）
术-格式 · 术层 skill 全文
本页是 <code>rules/skills/drafts/bestpractice_dynamic_behavior_diagram_mermaid.md</code> 的逐字投影（仅隐私清洗，零改写）。
时点提示：本页是仓内文件 rules/skills/drafts/bestpractice_dynamic_behavior_diagram_mermaid.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。
报告元数据（frontmatter）
name: bestpractice_dynamic_behavior_diagram_mermaid
description: 动态行为图的 mermaid 操作约定（术·格式，DLS 系统 A 第三个图类小模块）。承载「掌握运行时」与「实现过程时序」：时序 flavor（sequenceDiagram，追踪真实执行流）+ 状态 flavor（stateDiagram-v2，状态迁移 + 因果回路 + 事件-行为-结构三层）。触发场景：按 workflow_essence_diagramming 路由到「过程/机制理解→时序/状态」后落笔时；给一个系统画「跑起来怎么走」时。
type: BestPractice（术·格式）
status: draft (Beta) — 2026-07-10 首版，T3219 图法设计 §2.2 落地 + DDP dogfood 真实用例（cmd_pipeline 时序 + job 状态机）；晋级前需真实动态图 dogfood ≥1 轮独立 regulator 判「帮理解运行时」
created: 2026-07-10
version: 0.1.0 (draft)动态行为图 mermaid 约定（图类小模块）
术 skill。何时画、怎么选图法、触本质判据归道 skill workflow_essence_diagramming；本文件只管动态行为图这一类落到 mermaid 的操作约定。动态行为图回答「怎么运转」（一步步怎么走、处于什么状态、有什么反馈），不回答「长什么样」（结构/边界，那归静态结构图术 skill）。
目标
产出一张读图路径 ≡ 执行路径的动态图：时序图顺读就是程序顺执行、状态机一条路径就是一个场景走完。两个 flavor 共享动态子内核（时间轴、事件因果、场景分支、部分同构），按「看过程还是看状态」分工。
flavor A｜时序图法（sequenceDiagram，承载「实现过程/一次执行怎么走」）
画一次真实执行：谁先调谁、消息怎么传、分支怎么走。优先追踪真实代码/真实运行，不画想象的流程（DDP dogfood 的时序图追踪的是 cli.py:cmd_pipeline 真实步骤，非设计想象）。
语法约定
- 图头：
sequenceDiagram。 - participant 就是一套模块划分里的运行时 cut（和该系统静态架构图的模块对得上；一个关键场景交叉校验两图 participant 是否一致）。participant 名短，别塞职责（职责在消息上说）。
- 消息全标注（时序图的「命题化边」）：
A->>B: 消息（实线发起 / 同步调用）、B-->>A: 返回（虚线返回）。Tversky 箭头语义承重——实线发起、虚线返回，认符号即认动作。禁止裸箭头无消息。 - 分支用
alt/else（互斥分支，如 PASS/FLAG）、opt（可选步骤，如「若未加 --skip-regulator」）、loop（重复）。别用一堆并列箭头硬凑分支。 - 自处理用
A->>A: 自己做什么（如门内部跑 DA1-DA4）。 - 长时序按
Note over A,B: 阶段名分段，别让一张时序图拉得过长（超一屏就按阶段拆或抽子图）。
flavor B｜状态机图法（stateDiagram-v2，承载「运行时/不同场景处于什么状态、怎么迁移」）
画一个对象/系统随时间在不同场景下的状态迁移。承载「运行时」——用户点名的「系统随时间、在不同情况下的动态运行表现」。
语法约定
- 图头：
stateDiagram-v2。[*]是起止。 - 迁移带触发条件：
待支付 --> 已支付: 支付成功，箭头标注写「什么事件触发这次迁移」。状态取一套模块的 runtime cut。 - 一个场景 = 一条从
[*]到终态的路径；读者选一个关心的场景，顺迁移箭头走完。 - 因果回路补反馈：状态机表达不了的「随时间反馈闭环」（Meadows：线性文字表达不了同时互联，一圈才看得见），用回到前序状态的迁移画出反馈（如
挡住 --> 已装配: 补材料重跑）。 - 事件-行为-结构三层定深度：不停在「发生了什么」（事件），下探到「什么结构产生了这行为」（结构），服务触及本质。
- 对接变更类：涉及「一次变更的前后状态对比」时接
workflow_change_visualization的 V-01~V-06，不重造。
预期/实测对照（D-16，诚实标注）
要接真实运行误差信号时：先画设计态该有的时序/状态，再对实测，差异定位到具体消息或迁移当可定位误差信号。诚实一件事：这个「预期 vs 实测对照」是需求侧设计构造，不是调研搬来的成熟实验框架，标 [需求构造]。
节点被下钻时的符号约定（边守恒的动态落法）
道 skill workflow_essence_diagramming §子系统下钻与递归拆解定了边守恒不变量：父图中进出被钻节点的每条边，必须在子图守住。静态图守的是依赖边，动态图守的是消息/事件——两个 flavor 各有落法。
- 时序 flavor：lifeline 展开为子时序 → 边界消息守恒。父时序图里某个 participant
P被判为子系统要下钻，先数清打到P的每条入消息和P发出的每条出消息（含返回）。画P内部子时序时，把这些消息落成子图的边界消息：用外部占位 participant（如Caller、Downstream）代表父图对端，子时序以「收到父图那条入消息」开头、以「发出父图那条出消息/返回」收尾，中间才是P内部谁调谁。边界自检：父图P的进出消息集合 ⊆ 子时序边界消息集合 ∪ refined 映射（父图一条请求在子时序裂成校验+落盘+回执时写一行映射）。对不上＝父时序漏标了一条P的消息，或子时序凭空多/少了一次对外交互。 - 状态机 flavor：状态展开为子状态机 → 进出事件守恒。父状态图里某个状态
S内部另有子状态要下钻，先数清进入S的每个触发事件和离开S通向别的状态的每个事件。画S的子状态机时，用[*]起止代表「从父图进入S」和「离开S回父图」，且离开子状态机的每条出边事件必须与父图里S的出边事件一一对应（同名或 refined 映射）。子状态机内部可以有自己的中间状态与回环，但对外的进入事件与离开事件集合必须与父图S的进出事件闭合。对不上＝父状态图漏了一条S的迁移，或子状态机多开/少开了一个对外出口。 - 不做的事：边界 participant /
[*]只承载父图已有的进出消息或事件，不在子图里替被钻节点新增对外交互（那是父图该改）；也不把父图其余 participant/状态整块搬进子图当背景（混层）。子图只画被钻节点内部 + 一圈边界消息/进出事件。
排版质量（防文字重叠/溢出，机械可检）
与静态结构图术 skill 同一套排版纪律（真源 adhoc_jobs/diagram_learning_systems_20260701/dogfood_ddp_20260708/inputs/layout_quality_ruleset.md）：
- participant / 状态名短（≤40 字符）；细节写在消息/迁移标注上，别塞进 participant。
- 消息/迁移标注也别过长（一句「这一步做什么」的动词短语，参考中位 9-15 字符）。
- 长时序按阶段拆，别拉成竖排长图；状态图场景多时按场景分图。
- 机械自检：
python3 tools/mermaid_diagram_check/check.py <file.md> [--strict]（工具路径查tools/INDEX.md）——它支持 sequence（查箭头带:message）和 state（迁移），超阈值 FLAG 给定位。
验收标准（无上下文 agent 可自判）
确定层（机械可查，走 mermaid_diagram_check）：
- 时序图 participant 齐、消息全标注、分支用 alt/opt 不裸箭头。
- 状态机迁移全标注触发条件、有起止
[*]。 - mermaid 可解析（语法结构校验通过）。
语义层（派独立 regulator 判，给可定位反例）：
- 时序图：顺读能不能复述实现过程；读不出的步是可定位反例。
- 状态机：能不能说清不同场景各走什么路径、反馈闭环在哪；若做 D-16 对照，对不上的消息/状态就是可定位反例。
已知陷阱
- participant/消息含括号、冒号、斜杠时不加处理易解析失败——消息里的冒号是 mermaid 语法分隔符，正文冒号改用中文「：」或去掉。
- 把「看状态」硬画成时序、或「看过程」硬画成状态机 = 两头不讨好；按「你要展示它怎么走一遍（时序）还是它会处于哪些状态（状态机）」选 flavor。
- 画想象的流程而非真实执行——动态图最该追踪真实代码/运行，否则和设计文档没差异（DDP dogfood 的价值正在于时序图从
cmd_pipeline真实取源）。 - 其余待更多 dogfood 回填。
可用资源
- 上游道 skill：
workflow_essence_diagramming（何时画/选图法/状态过程二元/四正交拆解的 runtime cut）。 - 姊妹术 skill：
bestpractice_static_structure_diagram_mermaid（静态结构，与本类互补：静态答长什么样、动态答怎么运转，同系统常配一张静态 + 一张动态）。 - 变更类：
workflow_change_visualization+bestpractice_markdown_report（状态 flavor 的前后变更对接它，不重造）。 - 排版检查：
tools/mermaid_diagram_check/（路径查tools/INDEX.md）。 - 真实用例：DDP dogfood
adhoc_jobs/diagram_learning_systems_20260701/dogfood_ddp_20260708/DDP_dynamic_diagrams.md（cmd_pipeline 时序追踪 + job 状态机，18 张）；渲染参照contexts/knowledge_cards/kc_kv_cache_decode_flow.md（sequenceDiagram 真卡）。