diagram-design 语义模式（Semantic Patterns）实战指南：行为优先选型、七大模式与组合规则

本篇技术指南讲解 diagram-design 技能库中位于 semantic-patterns.md 的语义模式体系：它回答"先决定画什么行为，再决定怎么排版"的选型问题，定义了 Fan-in queue / bottleneck、Stage framework with semantic slots、Unstructured input → structured artifact、Paired policy-evaluation traces、Secure paved road、Governance / control catalog、Compensating security layers 七种可复用的行为模式，并为每种模式给出触发条件、必备原语、复杂度预算、反模式清单、静态回退方案与最近的视觉类型。读完本文，你将掌握：在 39 种视觉类型之外独立建模系统行为的完整方法，如何为队列瓶颈、策略评估、信任边界、安全纵深等高频场景一次画对图，以及如何用仓库自带的验证脚本（verify-semantic-motion.py）保证模式文档与实现契约不漂移。

一、核心思想：行为（What）与布局（How）是两条独立的轴

语义模式解决的是很多图示工具的共同痛点——能把盒子排好，却无法表达系统"正在做什么"。diagram-design 的答案是把行为抽象成一条独立于排版之外的轴：

Semantic patterns describe what a system does; the 39 visual types describe how information is arranged.

这句话的含义是：

• 语义模式（Semantic pattern）描述系统行为：排队、竞争、策略评估、信任边界、治理强制点、纵深防御……
• 视觉类型（Visual type）描述信息排列：数据流、流程图、架构图、层叠栈……
• 选型顺序固定：当行为、状态、强制（enforcement）或风险是承载信息的关键时，先选一个语义模式，再用它路由到的最近视觉类型作为布局语法；如果没有模式匹配，就直接选视觉类型。

这一设计被正式记录在 ADR 0002 — Semantic patterns never expand the visual-type taxonomy 中：行为是独立轴，七个语义模式各自路由到最近的既有视觉类型进行布局，模式拥有语义原语和更紧的预算，但永远不产生第二套布局语法。视觉类型数量只在出现真正新的布局语法时才增加（如 Polar 使计数从 38 变为 39）。换句话说：新增一个行为只需"一个模式小节 + 一行路由表"，而不是一套类型参考、模板和示例三件套。

对应地，在 SKILL.md 的第 3 节"Selection: semantic pattern, then visual type"中，选型流程被固化为一句话：当行为、状态、强制或风险承载意义时，先加载 semantic-patterns.md 选定一个主模式，再选最近的视觉类型；若无模式匹配，直接选类型。

一条图的模式纪律

• 一张图只用一个主模式（one primary pattern per figure）。
• 第二个模式最多只能提供一个支撑原语；如果两个模式都需要完整表达，就拆成"总览图 + 细节图"两张。
• 标签与结果（labels and outcomes）必须在静态帧内完整可读——这为后面的"静态回退"原则埋下伏笔。

二、路由表：从"读者需要理解什么"到"模式 → 最近视觉类型"

这是整个语义模式体系的入口。设计者首先问"读者必须理解什么"，然后查表路由。下表完整继承自原文档：

读者必须理解……	语义模式	最近视觉类型
大量到达争抢有限的服务容量	Fan-in queue / bottleneck（扇入队列 / 瓶颈）	Data flow
各阶段重复出现的问题、输入、控制与输出	Stage framework with semantic slots（带语义槽的阶段框架）	Process
松散对话沉淀为持久的结构化记录	Unstructured input → structured artifact（非结构化输入 → 结构化产物）	Data flow
两个策略决策为何不同、何处首次分叉	Paired policy-evaluation traces（成对策略评估轨迹）	Flowchart
哪些路由跨越信任边界、哪些被阻断	Secure paved road（安全铺装道路）	Architecture
每个强制表面适用哪些控制	Governance / control catalog（治理 / 控制目录）	Layer stack
防御如何降低风险、残余风险还剩什么	Compensating security layers（补偿性安全层）	Layer stack

这张路由表在 SKILL.md 第 3 节中还有一张等价的"行为触发词 → 模式 → 最近类型"表，方便从业务描述反向命中。两张表语义一致，且由 verify-semantic-motion.py（第 26–34 行的 PATTERN_NAMES）强制校验：7 个模式名称必须同时出现在 SKILL.md 路由表与语义模式文档中，否则验证失败。

三、七大语义模式详解

每个模式都按统一的六字段结构描述：Selection triggers（选择触发条件）、Required primitives（必备原语）、Complexity budget（复杂度预算）、Anti-patterns（反模式）、Static fallback（静态回退）、Nearest visual type（最近视觉类型）。这套字段结构也被验证脚本强制约束——verify-semantic-motion.py 第 35–42 行的 PATTERN_FIELDS 逐项检查每个模式小节是否齐全。

1. Fan-in queue / bottleneck（扇入队列 / 瓶颈）

选择触发条件： 多个生产者汇聚到一个审阅者、服务、关卡或受限资源；故事的关键在于到达速率、队列深度、等待时间、容量或背压。

必备原语： 不同的来源；扇入的入口（fanned ingress）；带可见槽位和计数（visible slots and count）的有序队列；容量 / 服务速率标签；一个受限的服务点；准入与延期/拒绝两种结果。标签必须带单位（8/hour、3 slots），不能只写"高"。

复杂度预算： ≤5 个来源、≤5 个队列槽位、1 个瓶颈、2 种结果、≤9 个主节点。超出部分把多余来源聚合为命名群体（named cohort）。

反模式： 用等宽管道掩盖竞争；箭头在可追溯前就合并；仅靠盒子大小暗示容量；装饰性堆叠；改变条目顺序的动画；只用红色表示过载。

静态回退： 展示有代表性的最终队列、数字计数/容量、瓶颈标签和两条结果路径——静态图也必须揭示"工作为什么会等待"。

最近视觉类型： 默认 Data flow；当服务阶段（而非来源）占主导时改用 Process。Data flow 类型的布局语法（横泳道 × 步骤列、数据载荷芯片、单一焦点跨角色交接）在 type-data-flow.md 中有完整参数化定义。

仓库中可对照的实现示例：example-queue-animated.html，它把"队列计数"作为可选的动画原语（见 animation.md 的 Queue counter 行：稳定槽位 + 条目揭示 + 可见数字计数，≤5 个条目且不允许重排）。

2. Stage framework with semantic slots（带语义槽的阶段框架）

选择触发条件： 生命周期或运营模型在各阶段重复相同的语义问题，通常是 Question（问题）、Input（输入）、Governance（治理）、Output（输出）；跨阶段的可比性比消息时序更重要。

必备原语： 有序的阶段标题；一致的槽位网格；显式的空/不适用槽位；阶段到阶段的交接（handoff）；稳定的槽位标签；每阶段一个主输出。每个阶段都必须保持槽位顺序不变。

复杂度预算： 3–6 个阶段、3–4 种槽位、≤20 个已填充单元格、每个单元格 ≤2 行文字。单元格需要整段文字时，拆出细节图。

反模式： 每个阶段发明不同的内部布局；槽位语义靠位置传达却没有标签；用几十个单元格制造虚假精确；把阶段顺序与所有权泳道混为一谈；靠缩小字号塞进一张画布。

静态回退： 渲染完整的"阶段 × 槽位"矩阵，含交接与显式的 — 或 Not applicable 条目。不能依赖分段揭示来教学这套模式。

最近视觉类型： Process；只有当重复的行表示所有者而非语义槽时，才改用 Swimlane（参见 type-process.md 与 type-swimlane.md 的分工说明）。

3. Unstructured input → structured artifact（非结构化输入 → 结构化产物）

选择触发条件： 对话、笔记、提示词或漫无边际的请求被引出、规范化，并写入持久的简报、工单、记录、schema 或其他结构化产物。

必备原语： 来源话语；澄清性问题；提取出的字段/值对；一个命名的转换；持久产物边界；从代表性语句到字段的来源追溯链（provenance links）；缺失/未知状态。

复杂度预算： ≤4 次往来、≤6 个产物字段、1 个转换、≤3 条来源追溯链。展示代表性内容，而不是完整对话记录。

反模式： 两个盒子之间的"AI 魔法"闪光；把产物画成又一个聊天气泡；没有来源的字段凭空出现；对缺失事实编造确定性；把打字动画当作唯一可读的文案。

静态回退： 在完成的有标签产物旁展示一段简短来源摘录，至少包含一条来源映射，并让任何未知字段保持可见。

最近视觉类型： Data flow；当引出过程包含多个有序关卡时改用 Process。Data flow 的载荷类型芯片（WB/DB/TB/FL/LS，输入芯片在节点左下、输出芯片在右下，位置不可协商）正是表达"非结构化 → 结构化"载荷形态变化的手段，见 type-data-flow.md 第 8 节。

4. Paired policy-evaluation traces（成对策略评估轨迹）

选择触发条件： 两个原本相似的请求走向不同结果；读者需要逐规则看清 PASS、FAIL、SKIPPED、NOT REACHED 状态，以及首次分叉点（first divergence）。

必备原语： 两条轨迹上相同的规则顺序；显式的状态文本 + 符号/形状（不能只靠颜色）；产生差异的输入；最终结果；有标签的首次分叉标记；区分 SKIPPED（适用流程被有意绕过）与 NOT REACHED（评估在更早处停止）。

复杂度预算： 恰好 2 条轨迹、3–6 条规则、1 个首次分叉点、≤12 个状态单元格、每条轨迹 1 个结果。标签超过一行时，规则细节移到注释。

反模式： 比较两个各自独立排序的流程；只有绿/红点没有文字；把 skipped 与 not-reached 当同义词；高亮每一处差异；已拒绝的轨迹继续往下画规则（好像下游规则还在运行）。

静态回退： 同时展示所有规则状态与两个结果；用一条持久的分隔线/括号和标签标出首次分叉。

最近视觉类型： Flowchart（有序决策逻辑）；仅当消息与时间也承载信息时改用 Sequence。流程图类型的形状语义（圆角矩形=动作、菱形=决策、实心点=汇合点）见 type-flowchart.md。

该模式是仓库中"模式 + 动画原语"结合的旗舰案例：example-policy-trace-animated.html 使用 step 模式逐条揭示规则，并且被 verify-semantic-motion.py 严格校验——它要求示例必须包含 PASS/FAIL/SKIPPED/NOT REACHED 文本状态、FIRST DIVERGENCE 标记，且 Trace B 的持久连接线必须终止于第一个 FAIL，之后才是 NOT REACHED 行与 denied 结果，从结构上杜绝"被拒绝的轨迹还继续跑下游规则"的反模式。动画原语 Policy evaluation 的预算（3–6 条规则、2 条轨迹）与模式预算完全一致，见 animation.md。

5. Secure paved road（安全铺装道路）

选择触发条件： 受支持的架构提供从入口/构建到部署的有界路径；信任边界、特权时刻、允许的入口、禁止的入口、批准与阻断的部署路径是核心看点。

必备原语： 有标签的信任边界；参与者与身份；带正向文本标签的允许入口；在边界处终止的禁止入口；批准的部署路径；被阻断的绕行路径；特权关卡；隔离运行时；审计目的地。除颜色外，还必须使用不同的线型与停止符号。

复杂度预算： ≤3 个信任区、≤8 个组件、≤10 条路径、≤2 条禁止路径、1 个特权关卡。控制细节拆成目录图。

反模式： 一个没有路由语义的虚线框号称"安全"；禁止箭头穿入受保护区域；秘密或身份暗示却无标签；每个组件都画成可信的；绕行路径在视觉上重新汇入批准路径。

静态回退： 渲染每条边界以及允许/禁止两类路由。被阻断的路径必须在进入或部署前可见地停止。

最近视觉类型： Architecture。架构类型的虚线边界矩形（信任区）、正交连接器与桥接原语正是承载信任边界语义的布局语法，见 type-architecture.md。对应实现示例为 example-paved-road-animated.html。

6. Governance / control catalog（治理 / 控制目录）

选择触发条件： 控制清单必须按执行位置（authoring、workspace、merge/CI、deploy/runtime 或其他命名表面）来理解；一个扁平清单会掩盖这些强制点。

必备原语： 强制表面分组；命名的控制项；强制执行者（code、platform、human）；执行时机（write、merge、deploy、run）；可绕过性或例外路径；覆盖/缺口标注。

复杂度预算： 3–5 个表面、每表面 3–7 个控制项、总计 ≤24 个控制项、每控制项 ≤3 个属性。仅在条目列表存在于他处时才用计数概括。

反模式： 35 个小药丸；按模糊主题而非强制点分组；把愿望与已强制执行的控制混为一谈；只有图标没有控制名；不展示表面覆盖就声称纵深防御。

静态回退： 展示完整的分类目录，含表面标题以及执行者与执行时机的文本标签；保留缺口与例外。

最近视觉类型： Layer stack；当角色权限（而非强制表面）是主要对比维度时改用 DP security matrix（见 type-layers.md 与 type-dp-security-matrix.md）。层叠栈的行内"索引标签 + 层名 + 右侧说明"三段式布局天然适配控制目录分组。

7. Compensating security layers（补偿性安全层）

选择触发条件： 没有哪一层是完美的；每一层防御都覆盖上一层遗留的失效，残余风险必须在层间可见地收窄、转移或保留到底。

必备原语： 有序的威胁/风险输入；命名的防御层；每层的缓解措施；显式的局限或逃逸；层间传递的残余风险载体；最终残余风险与后果/响应。必须使用标签或递减的度量，绝不能只靠面积。

复杂度预算： 3–5 层、1 条主风险线索、每层 ≤2 项缓解、1 条最终残余风险陈述。多个无关威胁拆成独立图。

反模式： 暗示最后一层让风险归零；等宽的不透明板块没有传播关系；把审计当预防；缩小形状却没有数字或文字含义；无解释地颠倒预防/检测/恢复顺序。

静态回退： 展示完整传播链：初始风险 → 缓解 → 每层的逃逸风险 → 最终残余风险与响应。

最近视觉类型： Layer stack；当包含边界（而非有序补偿）承载意义时改用 Nested（见 type-nested.md）。

四、复杂度预算：两套预算取更严

语义模式自带预算，但它不豁免视觉类型的预算。组合规则明确写道：

• 模式可以特化 status（状态）、boundary（边界）、queue（队列）或 propagation（传播）原语，但选定的类型仍拥有页面轴向、连接器语法、间距与类型专属上限。
• 取模式预算与视觉类型预算中更严格者。语义单元格/状态不是突破九节点总览目标的许可。
• 状态与结果必须使用稳定文本。颜色、动效、位置只能强化意义，绝不能单独承载意义。

这与 SKILL.md 第 7 节的全局复杂度预算一致：单图最多 9 个节点、12 条箭头、2 个 coral 焦点元素；超出即拆分为"总览 + 细节"两张图。每个类型的专属上限（如 Data flow 最多 4 泳道 × 6 步骤、Flowchart 决策菱形 ≤3 出口）同样生效。

五、静态优先：静态回退与"动画只是演示层"

语义模式体系的底层纪律是 static by default：

• 每个模式都定义了静态回退（Static fallback）——在无 JavaScript、无动效、打印、导出、截图、prefers-reduced-motion: reduce 场景下，静态帧必须完整呈现全部语义（标签、状态、结果、边界、队列计数）。
• 可选的动画是演示层，不是另一种模式。animation.md 开篇即规定：动画解释一张完整的静态图，绝不补充缺失的意义；只有显式要求或动效确实能澄清有序变化时才加载它，否则用 none 模式输出静态 HTML。
• 四种动画模式（none/reveal/step/loop）中，reveal 是唯一被认可的自动播放模式——初始化时可播放一次，结束后保持完整，不随视口重入而重播，无显式 Replay 操作不重启。这一裁决被记录在 ADR 0003 — Reveal is the only sanctioned autoplay。

动画原语与语义模式一一呼应：Queue counter（队列计数，配合模式 1）、Typing / field population（字段填充，配合模式 3）、Policy evaluation（策略评估，配合模式 4）、Containment（包含，配合模式 7 的 Nested 变体）、Audit append（审计追加，配合模式 6）等。所有原语都要求"文本、计数、符号、图案或轮廓"与颜色并存，并且从不改变条目顺序、从不提升静态预算。

六、组合规则与仓库级验证

组合规则（原文四则）

1. 语义模式可特化 status/boundary/queue/propagation 原语；选定的类型仍拥有页面轴向、连接器语法、间距与类型专属上限。
2. 取模式预算与视觉类型预算中更严格者；语义单元格/状态不构成突破九节点总览目标的许可。
3. 状态与结果使用稳定文本；颜色、动效、位置只能强化意义，不能单独承载。
4. 可选动画是演示层而非另一种模式；仅在请求动效或动效实质澄清有序变化时加载 animation.md。

如何验证

仓库把上述契约做成了可执行检查，核心是 scripts/verify-semantic-motion.py，它只依赖 Python 标准库、不执行示例 JS，验证内容包括：

• 7 个语义模式名称必须完整路由到 SKILL.md（PATTERN_NAMES）；
• 每个模式小节必须包含六字段（Selection triggers:、Required primitives:、Complexity budget:、Anti-patterns:、Static fallback:、Nearest visual type:，即 PATTERN_FIELDS）；
• SKILL.md 中语义模式路由必须出现在 39 行视觉类型指南之前（router_position > guide_position 即报错）；
• 视觉类型指南必须保持 39 行（VISUAL_TYPE_COUNT = 39）；
• 动画文档必须包含 4 种模式、8 种动画原语及静态/可访问性契约术语；
• example-policy-trace-animated.html 的 step 模式示例必须满足：单一 motion root、完整静态回退声明、五键控制（Play/Pause/Replay/Previous/Next）、aria-live 状态区、无 JS 回退、SVG role="img" 与 title/desc 契约、PASS/FAIL/SKIPPED/NOT REACHED/FIRST DIVERGENCE 文本、以及"Trace B 持久连接线终止于首个 FAIL"的结构约束；禁止 setInterval 与 Math.random。

运行方式（从仓库根目录）：

python3 scripts/verify-semantic-motion.py            # 文档契约 + 动画示例全量验证
python3 scripts/verify-semantic-motion.py --markdown-only   # 仅校验文档/路由
python3 scripts/verify-semantic-motion.py --example-only    # 仅校验策略轨迹示例

实操落地的完整工作流

综合 SKILL.md 与 semantic-patterns.md，一次符合规范的语义模式制图流程是：

1. 判断承载信息的是行为/状态/强制/风险，还是纯粹的信息排列；前者进入模式选型，后者直接选视觉类型。
2. 从路由表命中一个主模式（必要时参考 SKILL.md 的行为触发词表交叉确认）。
3. 加载路由到的最近视觉类型参考（如 type-data-flow.md、type-flowchart.md、type-architecture.md、type-layers.md）获取布局语法，并叠加模式的语义原语。
4. 同时遵守模式预算与类型预算，取更严格者；超出即拆"总览 + 细节"。
5. 默认输出完整静态帧；只有明确请求动效时，才按 animation.md 的契约添加 reveal/step 模式，且静态帧语义不受动效影响。
6. 用 python3 scripts/verify-semantic-motion.py 与仓库的其他校验脚本（如 scripts/verify-geometry.py、scripts/self_check.py）做输出前检查。

通过这套"行为轴独立建模 + 路由到最近布局语法 + 双预算约束 + 静态回退兜底"的体系，diagram-design 让同一张 Data flow、Flowchart、Architecture 或 Layer stack 布局可以承载完全不同的系统行为语义，同时把复杂度失控、"AI 拼图感"和动效替代信息这三类典型失败挡在输出之前。