Diagram Design 参数化 Loop 图型指南：用确定性几何绘制飞轮、反馈环与共享状态中枢
【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design
本文以 diagram-design 开源仓库中的 type-loop.md 类型规范为核心，讲解如何用参数化方式绘制「增强循环 / 飞轮 / 反馈环」类示意图：一条顺时针推进的工作流环 + 一个累积共享状态的中枢。读完本文你将掌握 Loop 的 YAML 输入契约、完全确定性的 SVG 几何公式、双连接器语法（实线圆弧 + 虚线回写辐条）、暗色变体 token 交换，以及可直接对照仓库示例复现的完整清单。
Loop 是 diagram-design 39 种视觉类型中唯一的「循环 + 共享状态」组合图型（见 SKILL.md 的视觉类型引导）。它与普通的环形流程图不同：环上的每一步工作都会把结果写回一个共同的中心，读者必须同时看到两种运动——工作沿环顺时针推进，以及每一轮向同一中枢写回持久状态。
1. 适用场景与类型边界
Best for：增强循环（reinforcing cycles）、飞轮（flywheels）、反馈环（feedback loops）、运营循环（operating loops）——凡是「最后一步回馈第一步、且一个共享中枢累积状态」的主题都适用。
| 场景 | 选择 |
|---|---|
| 路径有终点、向结果分支、或从不真正回到第一步 | 改用Flowchart |
| 环上不累积共享状态、中枢仅作装饰 | 改用Cycle（普通环形流程） |
| 回写是虚构的、中心不沉淀任何记录 | 同样不是 Loop——虚线回写辐条是 Loop 的定义性信号，去掉它图就退化成普通圆环流程 |
选择时有一条硬性判据：最后一个站必须真实地连回第 0 个站。如果这个「回归」是假的，请使用 Flowchart 展示真实终点。
2. 输入契约——参数驱动的唯一事实来源
Loop 是参数化图型：§1 的输入决定站数量、角度、边交点、连接器路径与 viewBox 边界；相同输入必须产出完全相同的几何。完整契约如下（来自 type-loop.md §1）：
title: "The self-improving loop" subtitle: "Every pass improves the shared operating record" hub: # exactly one name: "Shared memory" sublabel: "one record, every loop" stations: # 5..8, clockwise from top - { name: "Capture", sublabel: "signals in", spoke_label: "SIGNALS" } - { name: "Research", sublabel: "evidence pulled" } - { name: "Decide", sublabel: "human approves", focal: true } - { name: "Act", sublabel: "work ships", spoke_label: "OUTCOMES" } - { name: "Measure", sublabel: "outcomes logged" } - { name: "Learn", sublabel: "playbook updated" } station_w: 160 station_h: 64 hub_w: 200 hub_h: 104 radius: 240 margin: 64 dark: false硬性预算（hard budget）：
- 5–8 个站 + 恰好 1 个中枢。超过 8 个站，把主题拆成「总览 Loop + 若干细节图」；两个中枢意味着两个系统，画成两张图。
- 至多一个站可设
focal: true；零个焦点站也允许（当没有需要强调的编辑关口时）。 - 站的顺序是语义化的：
stations[0]位于顶部，后续条目顺时针排布；最后一站总是连回第 0 站。
字段语义说明（与同仓库 type-medallion.md 等参数化图型一致）：name是站名（Geist sans 节点名），sublabel是技术副标签（Geist Mono），spoke_label可选——当副标签已经说明回写内容时可以省略；focal: true触发accent-tint填充 +accent描边。
3. 布局数学——完全确定性的几何
全部计算采用 SVG 坐标（正 y 向下）。设中枢中心C = (cx, cy)、站数量N、站环半径R、站半尺寸a = station_w/2、b = station_h/2、中枢半尺寸A = hub_w/2、B = hub_h/2。
3.1 站中心（§2.1）
对零基索引的站k：
theta_k = -90deg + k * (360deg / N) u_k = (cos(theta_k), sin(theta_k)) P_k = C + R * u_k station_center_x(k) = cx + R * cos(theta_k) station_center_y(k) = cy + R * sin(theta_k) station_x(k) = station_center_x(k) - station_w/2 station_y(k) = station_center_y(k) - station_h/2- 站 1 位于顶部（
-90deg），k增大即顺时针移动。 - 理想几何算出后，站矩形就近取整到 4px 网格；成对站取整时必须保持对称（4px 网格是全仓库的硬性规则，见 SKILL.md §7）。
- 环与矩形的交点保留三位小数，保证每条弧都在同一个圆上。
3.2 实线环流端点（§2.2）
环连接器是从站k到站j = (k + 1) mod N的同圆 SVG 圆弧：所有线段共用中心C、半径R、顺时针 sweep。站矩形打断了圆；连接器从源框的顺时针出口开始，止于目标框逆时针入口之前，箭头尖端精确落在目标描边上。
求圆/矩形交点：对站k的四条边逐一求解。竖直边x = x_e：
y = cy +/- sqrt(R^2 - (x_e - cx)^2)保留y落在该边范围内的候选；水平边y = y_e：
x = cx +/- sqrt(R^2 - (y_e - cy)^2)保留x落在该边范围内的候选。两个存活点按绕C的归一化极角分类：
q_entry(k) = circle/box intersection immediately before theta_k clockwise q_exit(k) = circle/box intersection immediately after theta_k clockwise箭头尖端补偿：标准 marker（refX=7、多边形尖端在x=8）+ 环描边宽度 1.2 时，marker_overhang = 1.2：
phi_entry = atan2(q_entry(j).y - cy, q_entry(j).x - cx) phi_end = phi_entry - marker_overhang / R q_end = C + R * (cos(phi_end), sin(phi_end)) M q_exit(k).x q_exit(k).y A R R 0 0 1 q_end.x q_end.y- 大弧标志恒为
0（相邻站间距 < 180°）；sweep 标志恒为1（SVG 坐标下顺时针）。 - 箭头超出的 1.2px 恰好补到
q_entry(j)，落在框边上而不穿过描边。 - 末站
N-1回到第 0 站的闭合连接器使用同一公式。
类型专属例外：Loop 的圆形环弧是 SKILL.md §6 规则 1（强制正交圆角连接）的文档化例外，与 Medallion 的晋升弧同一先例。Loop 的环绝不混入三次曲线、直线或圆角正交段——六个可见缺口必须读作同一连续圆的分片。
3.3 虚线回写辐条端点（§2.3）
每条辐条从站边缘向内指向中枢，用同一套射线/矩形求交公式，作用于径向向量u_k：
box_distance(v, half_w, half_h) = min(half_w / abs(v.x), half_h / abs(v.y)) # ignore a term whose denominator is zero d_station = box_distance(u_k, a, b) d_hub = box_distance(u_k, A, B) marker_gap = 6 # 4..8px; 6px canonical spoke_start(k) = P_k - d_station * u_k hub_edge(k) = C + d_hub * u_k spoke_end(k) = C + (d_hub + marker_gap) * u_k因为箭头从站指向C，加上marker_gap让端点停在中枢边界外 6px——较浅的箭头在中枢描边之前停下，而不是撞上去。径向辐条是「禁用斜线直连」的另一类型专属例外：辐条必须是真半径，不得互相交叉，只能接触其源站与中枢。
辐条标签是可选的（站的副标签已命名回写内容时可省）。使用时遵循arrow-label角色：置于辐条一侧，带不透明paper遮罩，与描边保持可见的 6–10px 间隙。只给精选子集加标签，不要强行把六条标签塞进中枢光晕。
3.4 viewBox 尺寸（§2.4）
viewBox 必须容纳完整站矩形、外环曲线、箭头以及至少margin的呼吸空间：
left <= cx - R - station_w/2 - margin right >= cx + R + station_w/2 + margin top <= cy - R - station_h/2 - margin bottom >= cy + R + station_h/2 + margin viewBox_w = right - left viewBox_h = bottom - top检查上下限时要包含完整圆极值cx +/- R、cy +/- R及站边界与箭头净空。绝不允许裁切掉站描边、箭头或环弧。六站规范示例：viewBox="0 0 1040 680"，C=(520,340)，R=240，站 160×64，中枢 200×104，四周留出宽裕净空——与仓库 example-loop.html 中的实际 SVG 完全一致。
4. 视觉语法——元素与绘制顺序
| 元素 | 处理方式 |
|---|---|
| 站（Station） | 标准节点：paper填充、ink描边、radius-md；名称用node-name，副标签用sublabel |
| 中枢（Hub） | 全图唯一的深色元素：ink填充、paper文字；比站略大 |
| 焦点站（Focal station） | 至多一个：accent-tint填充、accent描边；站名可用accent |
| 环流（Ring flow） | 站圆上的A R R 0 0 1圆弧，实线muted描边，默认箭头在目标端；仅顺时针 |
| 回写辐条（Write-back spoke） | 虚线soft描边、降低强调，stroke-dasharray="5,4"，配soft箭头 |
| 辐条标签（Spoke label） | arrow-label角色、soft、大写、paper 遮罩、距连接器 6–10px |
绘制顺序（Z 序是关键）：paper 或可选点阵 → 环箭头 → 虚线辐条 → 辐条标签遮罩与文字 → 站框 → 中枢 → 文字。节点绘制在后，天然遮罩连接器微小的越界，而每个预期的端点仍精确落在边上。
中枢不是第 7 个流程步骤——它是累积状态：记忆、标准、证据、策略或共享运营记录。它的文案保持克制：一个名称 + 一句短副标签。
5. 连接器规则（强制项）
SKILL.md §6 的连接器六规则对 Loop 整体适用，仅被两个 Loop 专属连接器原语替换：圆形环弧（§3.2）与直线径向辐条（§3.3）。规则如下：
- 环箭头：同半径圆弧、实线、顺时针。每条路径用
A R R 0 0 1；目标箭头落在站边上，任何连接器不得以中心点收尾。 - 辐条：虚线、向内指向。实线辐条会摧毁「运营流 vs 回写」的视觉区分。
- 标签：不透明遮罩 + 可见 6–10px 连接器间隙。绝不把文字放在描边上。
- 无重叠：环连接器与辐条不得互相重叠。环路径保持在中枢外侧；辐条占据各自的径向路由。
- 辐条扇出：当两条辐条必须从同一站边出发时，按 §6 公式扇出连接点，至少 12px 间距。标准 Loop 每站一条辐条；只有语义无法合并时才用第二条。
- 环路穿越中枢：若环路由会穿过中枢，增大
R或拆分图；不要把流动穿进共享状态，也不要改用正交路径。
6. 暗色变体——token 交换而非第二套调色板
应用 style-guide.md 的反转规则即可，不要另造调色板：
| 角色 | 亮色 | 暗色 |
|---|---|---|
| 画布与站填充 | paper | 暗paper |
| 主文字与站描边 | ink | 反转ink |
| 中枢填充 / 中枢文字 | ink/paper | 反转ink/ 暗paper |
| 环流 | muted | 暗muted |
| 回写辐条与标签 | soft | 暗soft |
| 焦点填充 / 描边 | accent-tint/accent | 暗accent-tint/ 更亮的暗accent |
| 分隔线与点阵 | rule | 同透明度反转rule |
语义关系在暗色模式下不变：一个ink填充中枢、一个可选accent站、中性实线环箭头、更浅的虚线回写。仓库中的 example-loop-dark.html 展示了同一几何在 token 反转下的成品：--paper: #2d3142、--ink: #f5f5f5、--accent: #f08a59，且每个 marker 颜色同步换为暗色 token（如#bfc0c0、#8e98ac）。
7. 可复现性清单（9 项）
- 站数量在 5–8 之间，中枢数量恰好为 1。
- 站 0 位于
-90deg；其余按360/N顺时针等分。 - 每条实线环箭头都连接相邻站，用
A R R 0 0 1、同一R；最后一站回到第一站。 - 每个环箭头落在站边上，而非中心。
- 每条虚线辐条从站内边出发，在中枢描边前
marker_gap处停止。 - 环连接器保持在中枢外侧；辐条不交叉、不重叠。
- 至多一个站使用
accent-tint+accent；只有中枢使用深色ink填充。 - 辐条标签（若存在）使用
arrow-label、不透明遮罩、6–10px 间隙。 - viewBox 完整容纳站框、描边、曲线、箭头与边距，无裁切。
对照仓库 example-loop.html 可以逐条验证：六条环弧均为A240 240 0 0 1、六条辐条以stroke-dasharray: 5 4结束于V280/L616 284等（离中枢描边恰为 6px）、Decide 站带class="station focal"、唯一的class="hub"矩形使用ink填充。仓库还提供python3 scripts/self_check.py <file>（无障碍 SVG 契约与单文件安全）与python3 scripts/verify-geometry.py <file>（标签遮罩与几何校验）两条验证路径，后者在 SKILL.md §9 预输出清单 中亦有引用。
8. 反模式速查
| 反模式 | 失败原因 / 修正 |
|---|---|
| 两个中枢 | 两个累积状态 = 两个系统。画两张图。 |
| 实线辐条 | 看起来像主流程，杀死虚线回传信号。改用虚线soft回写。 |
| 无理由的不等角站位 | 环不再读作同一个运营节律。除非有文档化的相位分组需要刻意留缝，否则用等分360/N。 |
| 圆弧 + 正交段混用 | 环退化成圆角矩形。每一段都必须是同一半径的圆弧，环才能读作一个连续圆。 |
| 连接器穿越中枢 | 流程与状态混淆。把环路由到外侧或放大半径。 |
| 多个站用 accent | 编辑关口消失。至多保留一个焦点站。 |
| 超过 8 个站 | 标签和辐条挤占中枢空间。拆成总览 + 细节。 |
| 从不真正回归的「环」 | 那只是排成圆形的 Flowchart。用 Flowchart 并展示真实终点。 |
9. 示例资产与仓库对照
仓库为 Loop 提供三个配套示例（见 type-loop.md §8）：
- example-loop.html — 极简亮色：六站自改进运营循环（默认画廊示例，被 docs/screenshots/manifest.json 收录渲染为
docs/screenshots/loop.png）。 - example-loop-dark.html — 同一几何在暗色 token 反转下。
- example-loop-full.html — 编辑页版式：旗舰 Loop + 三张不等宽摘要卡（
1.1fr 1fr 0.9fr）+ 页脚 colophon，卡 1 点出「虚线才是产品」（The dashed lines are the product）。
三份文件共享同一组 SVG 几何：viewBox="0 0 1040 680"、C=(520,340)、R=240、六条A240 240 0 0 1环弧、六条5 4虚线辐条。暗色与亮色仅在 CSS 变量与 marker 填充上不同，这正印证了 §6「token 交换而非新调色板」的设计。若需进一步了解 Loop 在图型选择表中的定位，可回看 SKILL.md 的视觉类型引导表（"Reinforcing cycle / flywheel where the last step feeds the first and a shared hub accumulates state →Loop"）。
【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
