框架关系图背后的秘密：learn-from-materials Graph Studio 交互图谱设计与实现-育师

【免费下载链接】learn-from-materials

Turn PDFs, books and papers into interactive learning webpages｜将复杂材料转化为可追溯、可测验、可做笔记的学习网页

项目地址：https://gitcode.com/gh_mirrors/le/learn-from-materials

learn-from-materials 是一款把 PDF、书籍、论文转化为可追溯、可测验、可笔记的交互式学习网页的开源工具。它的学习页里最"会讲故事"的模块，就是框架关系图（Graph Studio 交互图谱）：概念以卡片形式排布在点阵画布上，连线标注"谁支持谁、谁反馈给谁"，并且每条线都能打开查看理由和原文出处。这篇文章带你拆解这张关系图背后的设计取舍：三种连线如何区分证据与推断、布局如何自动计算、交互与主题系统做了哪些克制。

框架关系图长什么样：卡片与图谱一键切换

进入学习页的"核心框架"板块后，你会看到两套视图按钮：框架卡片与框架关系图。卡片视图适合逐个阅读概念，图谱视图则把整份材料的逻辑结构一次性铺开。

点击"框架关系图"后，画布顶部会出现节点与关系计数（例如"124 节点 / 106 关系"），以及图例、缩放工具栏。注意这张图不是装饰——每张卡片底部都挂着关系芯片，写明"支持 / 补充：某概念 → 某概念"，让你不看连线也能读到关系语义。

三种连线颜色：把"材料说的"和"我们猜的"分开

Graph Studio 最核心的设计决策，是把每条关系边的证据等级用颜色 + 文字双重编码：

连线类型	颜色	含义
实线（中性色）	深绿/灰蓝	材料依据：原文直接支持的关系
蓝色	浅蓝绿	整合推断：学习页为了帮助理解做的分析性连接
金色	琥珀金	反馈 / 回路：结果回到上游，改变证据或决策

为什么重要？因为一张"看起来都连上了"的关系图，很容易把推断伪装成事实。Graph Studio 的做法是：颜色只表示证据等级，不表示关系强弱，且所有线都是实线（早期版本用虚线表示推断，因与入场动画冲突且在小字号下读作"断线"而被移除）。规则细节记录在 references/diagram-design-and-delivery.md 中。

每条关系的数据结构本身也带出处，示例可见 examples/overview-methods-content.json：

{ "id": "feedback-evidence", "from": "f-action", "to": "f-evidence", "type": "feedback", "evidence": "material", "explanation": "测试结果成为证据链的新观察", "source": "methods-demo.txt · Lines 9-10" }

系统内置 9 种关系类型：是前提、下一步、导致、支持/补充、对比/冲突、属于、应用于、反馈修正、并行/并列，在 templates/extensions.js 的types映射中集中定义。

布局算法：让图谱自己找到位置

图谱没有使用力导向（物理模拟）布局，而是确定性网格算法——同样的数据永远得到同样的排布，便于测试与回归。核心逻辑都在 templates/graph-studio.js：

拓扑排序：从"没有待决入边"的节点开始排序，靠近上一个选中节点、连接度高的优先；遇到循环则保留原材料顺序，不发明层级。
连通分量分组：互相不相连的节点各自成组，画布上以"独立关系分支"标签分开，避免把不相关概念硬塞进一张图。
按需分列：一条单链只占一列，不再预留三列空白网格；跨组排列时按"每行最多 3 张卡"分行居中。
走线分层：相邻两行的连接走卡片之间的空隙；跨行或反馈线则借用画布右侧的外部回车道，车道逐条外移、互不交叠。

行间距还会根据该行承载的连线数量动态加高，保证箭头不压卡片。

交互细节：点击、悬停、缩放与全屏

点击卡片：高亮该节点与直接相连的卡片和连线，无关卡片变暗（用更弱的底色变暗，而非透明度——保证"被淡化"的内容依然可读），下方列出每条关系的完整端点名与理由；点空白处或按Esc恢复全图。
悬停预览：鼠标经过卡片即弹出详细说明（含出处），且面板锚定在节点上而非跟随指针；指针从卡片移动到面板之间有"走廊"保护，缓慢或对角移动不会中途关闭面板。
缩放工具栏：−/+围绕视口中心缩放（保持你的视觉焦点）、"适合宽度"保证卡片可读、"查看全图"整体适配、"全屏查看"把画布提升为模态层并支持 Tab 焦点循环。
动效克制：图谱首次可见时连线"绘制"一次，随后保持静态；选中节点只在相关连线上播放一次短促的方向提示（一颗在连线上方独立路径上移动的"彗星"），没有持续流动或脉冲。系统开启"减少动态效果"时，直接呈现完整静态图。

这些"不许回退"的规则同样写在 references/diagram-design-and-delivery.md，并有静态检查脚本 scripts/verify-diagram-motion.cjs 守护。

主题与可访问性：颜色从不写死

所有图谱颜色都来自 templates/graph-studio.css 中的--dg-*令牌，warm-paper、minimal、dark 三套主题各自覆写一份，切换主题时画布、点阵、卡片、箭头、工具栏整体联动。两个容易踩坑的细节：

箭头是实心填充三角形，颜色走 CSS 类而不是硬编码fill——否则切换主题后箭头会残留旧色；
卡片底色画在<button>元素上，规避了 Chromium 在变换容器中对article背景做白色混合的渲染问题。

可访问性方面：画布可键盘聚焦，节点是真正的按钮并带aria-pressed，关系列表使用aria-live，触屏设备不依赖悬停（提供"查看详细说明与出处"按钮代替）。

数据门禁：没有关系的图，必须大声承认

图谱的数据质量靠"关系图门禁"保证，规范见 references/relation-gate.md，校验器是 scripts/verify_relations.py：

两个以上框架却零条可见关系：默认 ERROR，除非规则账本逐条说明"材料不支持连接"；
框架有连线但存在孤立节点：默认 ERROR，独立框架须在账本中逐项写明理由；
端点缺失、自环、重复边、关系类型不合法：直接报错；
全部关系都是推断：告警要求回看原文——不允许靠"加几条没出处的线"让图变好看。

渲染端还有兜底：若页面未声明任何关系，画布上方会明确提示"这是关系数据缺失，不是渲染故障"。方法论整图则来自独立的methodology.json规范文件（结构、入口节点、主路径、分支与反馈边，字段定义见 references/whole-material-methodology.md），示例可对照 examples/rsi-methodology.learnkb/methodology.json。