docs-figure-logic

name	docs-figure-logic
description	Use when explaining how a retikz feature, module, pipeline, runtime, adapter, registry, compiler, or interaction works with a concise implementation logic figure. Always read docs-figure-contract first.

Docs Figure Logic

本 skill 用于给“功能如何实现”配叙述性逻辑图。先读 docs-figure-contract，本文只补充实现逻辑图的风格方法：如何抽象节点、组织箭头、处理 path label、区分 stroke / fill、安排布局。

目标

逻辑说明图要像论文里的概念图：结构清楚、排版规整、标签短、箭头语义稳定、颜色克制。不要蒸馏具体模板，不要把某张图的节点数量、形状组合或代码结构照搬下来；要蒸馏可复用的绘图语言：统一节点边界模式、灰色主线、按需使用类别色、沿线短 label、宽松网格布局。有框模式使用细描边、同色浅填充和小圆角；无框模式依靠位置、文字与连线表达结构。

一张好逻辑图先回答三个问题：

• 这张图唯一要证明的结论是什么？
• 哪些稳定角色是理解结论所必需的？
• 角色之间是执行、映射、依赖、汇聚还是对照关系？

不要把所有实现细节画进去。图只保留解释当前小节所需的主链路、关键分支和一两个约束点，并在当前组件或模块的职责边界停止。涉及全局 JSX → IR → Scene 管线时，只画与当前职责相接的入口 / 出口，再链接 /kernel/concepts/design/principles，不要重复绘制整条管线。

先选图型

先按关系选图型，再确定坐标。图型选错时不要靠更多箭头补救。

图型	适用关系	结构规则
流程图	存在真实执行或数据先后	一条主链从入口到输出；辅助输入用虚线进入具体阶段
映射图	多个信号分别对应 owner / 结果	平行成对排列，每对只画映射箭头；实现位置收进目标节点第二行
架构 / 职责图	包、layer、owner 与依赖边界	用分组框和主次依赖表达职责，不制造入口到出口的伪流程
Registry / 汇聚图	多个同等来源合并为有效集合	内置与自定义从同级入口汇入 resolver；诊断从解析点向下分离
对照图	两种模式或前后状态	两侧结构镜像对齐，不变部分保持一致，只突出真正变化

再选表达风格

图型决定关系结构，表达风格决定读者需要多少实现语境。先回答“读者只需理解关系，还是还要知道它在哪里、怎样落地”，再选一种风格；不要因为某种风格更好看而替代这个判断。

风格	适用场景	画法与边界
简洁学术版（纯逻辑）	解释概念心智模型、设计原则、稳定抽象、能力映射或高层输入输出；正文重点是“是什么、为何成立、彼此如何关联”	使用统一无框节点，只保留稳定角色和可命名关系。省略包名、文件路径、可选模块、诊断支路和逐阶段实现细节
块状流程图（逻辑 + 解释）	解释真实包边界、模块职责、数据 / 编译流程、入口与输出、可选依赖、扩展点或诊断路径；读者还要知道“在哪里、如何发生、由谁负责”	使用统一有框节点与必要分组；节点可用第二行标明职责或实现锚点。主链突出真实执行 / 数据流，辅助关系用虚线退后

选择规则：

1. 结论只依赖抽象关系，删去具体 owner 后仍能成立时，选简洁学术版。
2. 结论依赖某个包、layer、registry、编译阶段、输入输出或可选能力的归属时，选块状流程图。
3. 同一主题确实需要两张图时，先用简洁学术版建立总览，再用块状流程图解释一个具体链路；两张图必须分别证明不同结论，不能只换皮重复。
4. 同一张图只能选一种节点边界模式；两种风格的共用视觉约束仍以 docs-figure-contract 为准。

工作流

1. 用一句话写出图要证明的结论和停止边界。
2. 从上表选择图型，再按“再选表达风格”确定信息密度；无法归类时先拆分结论，不直接写 demo。
3. 读相关代码，找入口、稳定角色、核心状态 / IR、registry、输出和诊断边界。
4. 写节点清单：id / 角色 / 类别 / 标题 / 第二行 / 所属分组。
5. 写连线清单：起点 / 终点 / 关系名 / 主链或辅助 / 是否需要 label；无法命名的边不进入图。
6. 默认确定从左到右的唯一阅读方向，再安排辅助输入、状态、诊断和分组；只有满足下文纵向布局条件，或层级 / 上下堆叠本身承载语义时才改为从上到下，并先写明采用纵向的具体原因。
7. 选择统一边界模式，并写下“角色类别 -> 颜色”映射；同页复用同一编码。
8. 用 retikz 写 demo，先完成主关系，再加入不可缺少的辅助信息。
9. 做一次删减和紧凑化检查，再回看正文是否解释每个非显然角色。

节点风格

节点优先表达“角色”，不是文件、函数或临时变量。边框必须表达分类、分组、容器或复杂流程边界；若角色无需分类且内容清晰简洁，整张图可以使用 stroke="none"、无填充的无框节点。选定模式后整图统一，不混用有框与无框节点。

选择有框模式时使用下表：

节点类型	stroke / fill	使用方式
常规流程角色	gray / lightgray stroke + 同色低透明 fill	用于处理阶段与无须分类的稳定角色；统一 cornerRadius={4}。
类别角色	P2 类别色 stroke + 同色低透明 fill	用于读者必须区分的稳定角色类别；同色节点必须属于同一类别。
当前重点角色	保持所属类别颜色	单行节点可加粗正文正在解释的一到两个角色；双行节点的标题加粗只表达层级，重点靠主链位置和正文指认
辅助角色	gray / lightgray stroke + 同色低透明 fill	用于配置、缓存、registry、旁路输入；仍使用 cornerRadius={4}，通过虚线连接退到次要层级。
分组边界	LogicFrame + LogicFrameTitle	用于 layer、runtime、adapter、package、职责范围等语义分组；按 docs-figure-contract 紧密包裹内容并在框内预留标题行。

彩色节点的 fill 必须来自 stroke 的同色系弱化：降低 opacity / saturation / lightness 后形成浅底，而不是换成无关背景色。节点内部文字按 docs-figure-contract 的双行节点规则组织；标题是稳定角色，第二行才放职责、输入输出或实现锚点。不要在一个节点里塞三行以上解释；放不下说明时，拆成正文。

有框逻辑图不使用无边框 Node 承担注释或模拟分组标题；分组标题使用 LogicFrameTitle。短关系名放在 step label，文件路径、约束和补充解释移入图前后正文。

有框模式中的节点形状承担语义：圆角矩形表示处理或组件，圆 / 小圆表示抽象单元或操作点，菱形表示判断，圆柱表示存储，虚线外框表示分组边界。不要只靠文字区分不同角色。

箭头风格

箭头只表达可命名的关系。每条箭头都必须能用一句话说清楚。

• 主数据流 / 控制流：细灰色实线 arrow="->"，沿主阅读方向排列；箭头头部小，不抢节点。
• 密集结构连接：使用浅灰细实线，可省略箭头头部，让布局暗示方向。
• 辅助输入 / 依赖：灰色或语义色虚线，进入主节点侧边，不穿过主链。
• 辅助输入位于分组下方且能对应到具体内部角色时，与目标中心对齐并用垂直虚线直接连接该角色；不要为了对称汇聚到分组底边或两个角点。
• 反馈回路：从图外侧绕回状态节点，避免横穿主流程；只有反馈是机制核心时才画。
• 类别路径：仅当路径本身属于一种需要区分的通信、异常或反馈类别时使用对应 P2 色；普通主链保持灰色。
• 回退 / 优先级表达的是候选查找，不是连续执行；使用编号或优先级栈，并在正文或图中明确“仅当前项缺省时继续”。不要用一串无说明的箭头把候选画成顺序流程。
• 映射图每对角色只保留“信号 -> owner / 结果”的映射边；文件路径、目录或实现锚点放进目标节点第二行，不追加伪下游箭头。
• Registry 图把无效注册、重复 key、未知能力等诊断放在 resolver / consumer 下方，与有效主链分离；错误边只承担诊断语义。
• 禁止无语义连线：装饰线、重复箭头、为了对称而加的箭头都删掉。

箭头颜色跟随语义，而不是跟随节点外观：主链默认灰色，辅助线退后，彩色线只用于读者必须区分的通信、依赖、异常或反馈语义。危险 / 成功语义才使用 red / green。

Path Label

path label 是“关系名”，不是解释句。

• 优先写动词、短名词或数学符号：parse、resolve、features、retry、θ、∇θ、ŷ。
• 只给关键边加 label；如果每条边都需要 label，说明节点命名或图形结构不够清楚。
• 按 docs-figure-contract 根据路径方向显式设置 position、side 和 sloped；竖向依赖标签默认保持水平，斜线 / 曲线仅在沿线排版更易对应关系时使用 sloped: true。
• label 用小字号，贴近路径中段或转折后留白处；中性路径用 gray，彩色语义路径的 label 跟随 path 色。
• label 不压线、不压节点、不和箭头头部争位置；必要时把路径改成折线给 label 留空间。
• 同一图内 label 的位置规则一致：主链 label 显式使用 side: 'top'，辅助线 label 按语义显式选择线旁或下方。
• label 不加背景框，不放进节点里；需要被强调的中间语义可以实体化成小节点。

不要把文件路径、函数全名、完整条件表达式写进 path label。这些信息放灰色注释或正文。

Stroke / Fill 区分

逻辑图先根据语义选择统一边界模式，再用线型和位置表达结构。边框不承担分类、分组、容器或复杂边界时，优先省略；有框模式中的 fill 不是装饰色块，而是 stroke 色的低透明浅底。

• 无分类需求且内容清晰简洁时，所有角色节点统一使用 stroke="none" 且不填充，依靠位置、文字、字重和连线区分结构。
• 需要有框模式时，所有常规角色节点使用 cornerRadius={4} 与浅 fill：fill = stroke color + low opacity，让节点形成柔和面。
• 中性节点用 gray / lightgray 的浅 fill，视觉层级低于彩色语义节点。
• 语义分组统一使用 LogicFrame 的默认虚线浅灰边界；不要手写空边界 Node。几何 / 参考边界不套用此规则。
• 颜色只表达类别，当前重点只调整标题字重；不用高饱和 fill。
• 不在同一图中混用有框与无框节点；采用无框模式时，整张图所有 Node 一并切换为 stroke="none"。
• 同一语义不要同时改 stroke、fill、字体颜色和线型；一次只改一两个维度。

布局规则

布局先保证阅读顺序，再追求紧凑。距离本身表达关系强弱：同类、同组、同一映射对应该更近，无关类别和辅助分支才拉开。

• 逻辑图默认并优先采用从左到右的横向排列，包括流程、回退、优先级链与分支汇聚；先按横向主链安排坐标，辅助输入、状态和诊断放在主链上方或下方。
• 只有流程节点特别多、关系特别复杂，或层级 / 上下堆叠本身承载语义时才使用从上到下：经过删减、合并、分组和缩短 label 后，主链仍超过 5 个阶段，或仍存在多层分支 / 递归、明显交叉线、节点重叠，或在 500px 视口必须缩小统一字号才能读清；简单层级图则必须能说明为何上下位置本身参与表达关系。单纯沿用旧坐标、画布偏窄或横向间距尚未压缩，不构成改用纵向的理由。
• 主节点落在同一条水平 / 垂直基线上；间距按节点宽度、path label 和箭头的视觉占位平衡，不要求中心坐标等距。
• 同类节点聚集并对齐，复用相近宽高与稳定间距；同类节点之间的空白不要明显大于跨类别主关系的空白。
• 平行映射按最高节点计算行距，列宽由中英文最长 label 决定；每行箭头方向和长度保持一致。
• 横向主链穿过分组时，把分组外侧的入口 / 出口节点靠近边界，只给箭头保留清晰可辨的安全长度；不要让分组两侧的长边撑大整张图。
• 分组标题占独立标题行；IR、Scene、resolver 等内容节点向分组内部居中，不贴边，也不让标题与虚线相交。
• 相邻两条边只有一侧带 label 时，中间节点可以向无 label 一侧小幅偏移，为带 label 的边增加留白；偏移后仍要保证无 label 一侧不显拥挤。
• 辅助输入放主链上方或下方，状态 / 输出放主链末端附近。
• 多个下方辅助输入优先放在同一基线，各自与所支持的内部角色对齐；分组与辅助节点之间保留能看清短连线的稳定间距，不贴边，也不靠斜线连接补偿错位。
• 先压缩节点坐标和逻辑画布，再考虑缩短文字；同级角色沿用正文统一字号，不单独缩小较长或多行标签。
• 回路和旁路沿外侧走线，不从节点之间穿插。
• 同层主节点控制在 3-5 个；超过 5 个时合并为组或只画关键边界。
• 回退 / 优先级在窄屏优先改为纵向优先级栈，保留编号和终止条件，不横向挤压候选。
• 文字 label 与节点、箭头保持清晰的安全间距，不靠手感贴边。
• 页面宽度不足时先删减节点、缩短 label、压缩跨度和合并同类阶段；仅在满足上述复杂度或层级语义条件时改成纵向主链，不缩小同级字体。
• 完成语义布局后在约 1440px 桌面视口实测 SVG，确认文字可读、关系清楚且没有失衡空白；若容器缩放导致内容明显偏小，先压缩无 label 的边、节点安全间距之外的空白、分组外长边和画布，带 label、anchors 或诊断分支的空间仍按真实包围盒保留。

抽象规则

• 用稳定概念命名节点，不用临时变量名。
• 文件路径只放在第二行或灰色注释中，不要抢主链路。
• 能放进角色第二行的信息不实体化为新节点；新节点必须能改变读者对关系结构的理解。
• 如果两个阶段只是实现细节连续调用，合并成一个节点。
• 如果一个节点既是数据又是处理器，拆开或在正文说明；不要让一个标记承担两个概念。
• 如果辅助分支无法解释当前段落，删掉它。

逻辑图检查

画完后逐项检查：

• 是否先选定图型，且没有把映射、依赖、候选优先级画成连续执行流程？
• 是否已按读者所需语境选择简洁学术版或块状流程图，并避免用两张内容重复的图表达同一个结论？
• 节点清单和连线清单中的每个角色 / 关系是否仍有必要？
• 删除任一节点后，图是否仍能说明当前小节？如果能，删掉它。
• 每条箭头是否能用一句话解释？不能就删或改。
• 是否只有一个主要阅读方向？
• 是否默认采用从左到右；若使用从上到下，是否能明确指出删减与压缩后仍存在的节点数量、分支 / 递归、交叉线、500px 可读性问题，或上下位置本身承载的层级语义？
• 节点边框是否承担分类、分组、容器或复杂边界语义？内容清晰简洁且无需分类时，是否去掉了装饰性边框？
• 是否只有一种节点边界模式，有框常规节点是否都使用 cornerRadius={4}？
• 语义分组是否使用 LogicFrame + LogicFrameTitle，而不是手写空边界和标题 Node？
• 分组框是否紧密包裹标题与内容，标题是否位于框内左上角的预留标题行并使用灰色常规字重？
• 同色节点是否属于同一角色类别，当前重点是否用加粗而不是颜色表达？
• 双行节点是否保持统一标题 / 第二行层级，实现位置是否仍被误画成流程节点？
• path label 是否短、少、位置稳定？
• 带 label 的边是否获得了额外留白，相邻无 label 的边是否仍不过挤？
• 分组下方的辅助输入是否对齐实际内部目标并使用垂直连接，而不是连到底边角点？
• 分组外侧入口 / 出口箭头是否已压到安全短距，逻辑画布是否贴合实际内容？
• 同类节点是否聚集、对齐，距离是否与关系强弱一致？
• 同级角色是否保持统一字号，没有用缩小单个标签代替布局调整？
• 每个 step / edge label 是否按路径方向显式设置 position、side 和 sloped？
• stroke / fill 是否有清晰分工，而不是装饰？
• 是否只有一个主要阅读方向；需要当前强调时是否只保留一到两个重点？
• 正文是否解释了图里的缩写、边界和反馈？
• 是否仍遵守 docs-figure-contract 的 hideCode、id 连线、响应式和验证规则？