first

docs/spark/2026-06-21-graph-experience-completion-design.md

@@ -0,0 +1,534 @@
+# 图谱体验完整收口设计
+
+日期：2026-06-21
+状态：已收敛范围（≤2000 节点）并确认根因，待实现
+当前分支：`codex/graph-experience-completion-spec`
+
+## 目的
+
+这份设计用于收口 llm-wiki 图谱当前出现的“两套全图体验”问题。
+
+现在的产品方向已经明确：全局图谱使用 Sigma/Graphology 承担高性能地图视角，社区阅读继续使用 DOM/SVG 承担富信息阅读视角。但当前体验里还残留旧 DOM 全图路径：刚进入图谱是新版 Sigma 全局，进入社区后点击工具栏“回全图”却可能回到旧 DOM 全图，导致样式、点击、社区选择、拖拽、Pin、搜索和抽屉行为割裂。
+
+本设计的目标不是重新做一套 Sigma 全图，也不是把旧 DOM 全图整体搬进 Sigma，而是把已经成熟的全局交互规则统一下来，让 Sigma 全局和 DOM 小图兜底都遵守同一套产品规则。
+
+一句话：
+
+**全局永远是一张地图；正常全局永远回 Sigma；DOM 全图只做小图异常兜底，但规则必须一致。**
+
+## 范围与规模假设
+
+本设计按个人知识库的真实规模收敛，不为超大图过度设计：
+
+- 目标规模：常态 1000 个节点以内，硬上限 2000 个节点。
+- 2000 节点以内，Sigma（WebGL）可直接流畅渲染点状全局，无需把节点折叠成聚合块。
+- 因此本设计**不包含**节点聚合折叠（“+N 省略号”）、聚合平滑，以及面向超大图的“聚合安全视图”。
+- 渲染承载从四种收敛为三种：Sigma 全局、DOM 社区、DOM 小图兜底。
+- 仅保留一条极简的超限保护：万一节点数超过上限，给出“图太大，请用筛选”的提示并降级，不卡死、不回旧 DOM 全图，也不为此构建聚合系统。
+
+## 背景依据
+
+本设计延续以下已确认结论：
+
+- `2026-06-18-large-graph-global-community-design.md`：全局图谱负责看结构，社区聚焦负责读内容。
+- `2026-06-19-sigma-global-graph-renderer-design.md`：所有正常全局视角统一使用 Sigma/Graphology，DOM/SVG 不再作为用户可选的第二套全局主路径。
+- `2026-06-19-sigma-global-production-integration-result.md`：生产路由边界已定义为 `sigma-global`、`dom-svg-community`、`dom-svg-small-fallback` 和 `aggregation-safety-fallback`。
+- `2026-06-20-paper-ui-port-design.md`：当前阶段不做图谱画布内部的山水纸面化；图谱画布先跟随项目现有主题。
+
+因此，这次收口不是选型问题，而是把体验、状态和路由规则对齐到已经批准的路线。
+
+## 现状诊断（已复现）
+
+收口前先确认问题真实存在并定位根因，避免在已经正确的代码上返工。
+
+已确认的复现路径：从社区点工具栏“回全图”，会回到旧 DOM/SVG 全图（白色节点卡片、圆形社区计数标记），而不是 Sigma 全局点状地图。
+
+根因（代码级）：
+
+- “进入社区”路由（`dom-svg-community`）默认接到旧 DOM/SVG 渲染管线。
+- 这套 DOM 管线自带一套工具条，其“回全图”按钮调用的是管线内部的 `resetViewState()`：它只是把 DOM 视图重新铺满全部节点并在 DOM 里重画，**不会通知 facade 切回 Sigma 全局**。
+- 对照之下，Sigma 自身工具条的“回全图”是正确的（留在 Sigma），但那不是用户在社区里点到的那个按钮。
+
+因此根因与“架构边界 / 风险 2”一致：**社区的“回全图”必须上交全局路由切回 Sigma，而不是在 DOM 管线内部自我重置。** 这是本次收口的最小必改项。
+
+## 设计结论
+
+采用“同一套全局规则，三种渲染承载”的方案。
+
+1. 正常全局视角只走 Sigma 全局。
+2. 社区视角继续走 DOM/SVG 社区阅读。
+3. DOM 全图不再作为正常产品路径，只允许在 Sigma 不可用且图在上限内时作为异常兜底。
+4. 节点规模控制在 2000 以内，Sigma 不需要节点聚合；超出上限只做极简降级提示，不回 DOM 全图。
+5. 全局交互规则必须从旧 DOM 全图成熟经验里抽出来，成为共享规则；Sigma 全局与 DOM 小图兜底共用同一套规则，不各写一套心智。
+6. 社区里所有“回全图”入口都必须回到 Sigma 全局；只有 Sigma 已判定不可用时，才按兜底策略进入 DOM 小图兜底。
+7. 全局节点可拖拽保留，并沿用既有“松手即固定 / Pin / 固定位置恢复”能力。
+
+## 第一眼体验
+
+图谱打开的第一页要有“地图感”，不是阅读页，也不是卡片墙。
+
+默认全局视角应呈现：
+
+- 点状节点结构。
+- 社区的空间分布和颜色区分。
+- 少量关键标签。
+- 关系骨架。
+- 搜索命中、选中、Pin 和固定位置提示。
+- 顶栏、图例、工具栏保持当前项目主题，不做额外山水纸面化。
+
+默认全局视角不出现：
+
+- 节点卡片。
+- 大段正文。
+- 成片摘要卡。
+- 自动展开的社区内容。
+- 可见的圆形社区选择按钮。
+- 用户可见的“新版 / 旧版全图”切换。
+
+全局图的核心观感是“我在看一张知识地图”，而不是“我在读一组内容卡片”。
+
+## 用户体验规则
+
+### 1. 打开图谱
+
+用户点击“图谱”Tab 后，默认进入 Sigma 全局点状地图。
+
+如果上一次有搜索、选中、Pin、固定节点或所在社区上下文，应尽量恢复这些上下文，但不能因此进入旧 DOM 全图。
+
+### 2. 点击节点
+
+在全局视角点击节点时：
+
+- 保持在全局地图。
+- 选中节点。
+- 高亮节点和少量直接相关节点。
+- 打开轻量节点摘要。
+- 不自动进入社区。
+- 不自动打开完整阅读内容。
+
+轻量节点摘要里可以提供“进入所属社区”或“打开详情 / 阅读”。只有用户点这些明确动作，才进入 DOM 社区阅读。
+
+### 3. 点击社区
+
+在全局视角点击社区区域、社区标记或社区图例时：
+
+- 保持在全局地图。
+- 选中社区。
+- 高亮社区和关键跨社区关系。
+- 打开轻量社区摘要。
+- 不自动进入社区。
+
+轻量社区摘要里的“进入社区”是进入 DOM 社区阅读的明确动作。
+
+社区选择入口只保留一套：
+
+- 背景社区色块是选中社区的主入口。
+- 社区图例可以作为列表式辅助入口。
+- 不再额外显示圆形社区选择按钮。
+- 正常全局视角里，圆形社区按钮和背景色块不能同时存在。
+
+这样用户只需要理解一件事：点地图上的社区区域，就是选中这个社区。
+
+### 4. 进入社区
+
+用户点击“进入社区”后，进入 DOM/SVG 社区阅读视角。
+
+社区视角承担阅读任务：
+
+- 社区内节点完整在场。
+- 核心、选中、搜索命中、Pin 和固定节点可以升级为更高信息密度。
+- 抽屉可以显示更完整的内容和关系。
+- 社区视角可以继续使用 DOM/SVG 的成熟富交互。
+
+这条路径不改成 Sigma。
+
+### 5. 回全图
+
+社区里的所有“回全图”动作必须回到 Sigma 全局。
+
+这包括：
+
+- 社区工具栏里的“回全图”。
+- 抽屉里的返回全局动作。
+- 任何快捷返回全局的入口。
+
+回全图后：
+
+- 仍是点状 Sigma 全局地图。
+- 保留刚才社区的上下文高亮。
+- 保留搜索、选中、Pin、固定节点和视口上下文。
+- 不跳到旧 DOM 全图。
+
+如果 Sigma 已经失败且不可用，才进入对应兜底路径。
+
+### 6. 搜索和筛选
+
+搜索和筛选只改变高亮、淡化、列表和摘要，不自动重排整张图。
+
+如果当前选中的节点或社区被筛选排除：
+
+- 抽屉保留该对象。
+- 提示它当前不在筛选结果中。
+- 提供“清除选择”或“显示该对象”的动作。
+
+搜索、筛选、Pin 和固定位置不能互相抢状态。
+
+### 7. 全局拖拽和固定位置
+
+Sigma 全局必须支持节点拖拽。
+
+采用已有成熟规则：
+
+- 用户拖动全局节点时，节点跟随指针移动。
+- 松手后该节点自动固定。
+- 固定状态等同于用户明确调整过位置，应持久保存。
+- 固定节点在搜索、筛选、进入社区、回全局、刷新页面和重启应用后都要尽量保持位置。
+- 取消固定必须是明确动作，例如按钮或菜单项，不使用容易误触的双击。
+
+固定位置是一套共享状态，不属于某一个渲染器。
+
+因此：
+
+- Sigma 全局读写同一份固定位置。
+- DOM 社区读取同一份固定位置，用于保持用户熟悉的锚点。
+- DOM 小图兜底读取同一份固定位置，避免兜底时图突然变成另一张。
+
+### 8. 悬停、缩放和拖动画布
+
+全局视角需要达到旧 DOM 全图的日常可用手感：
+
+- 悬停能提示节点或社区。
+- 缩放只调整信息密度，不自动进入社区。
+- 拖动画布保持地图连续。
+- 交互过程中可以临时隐藏普通标签、弱边和复杂效果。
+- 核心锚点、搜索命中、Pin、固定节点和选中对象不能突然消失。
+
+### 9. 社区名字与地图标注
+
+社区名字按“地图地名”处理，不按按钮处理。
+
+默认全局视角：
+
+- 只显示少量重要社区名。
+- 社区名贴近对应社区色块的视觉中心或稳定空白位置。
+- 社区名是一行轻量标注，过长省略。
+- 社区名不放进圆形容器。
+- 拥挤时优先隐藏普通社区名，只保留当前选中、悬停、搜索相关或重要社区名。
+
+悬停或选中社区时：
+
+- 对应社区名变清晰。
+- 可以显示完整社区名和节点数。
+- 背景色块轻微高亮。
+- 抽屉显示社区摘要。
+
+社区名的职责是帮助读地图，不是成为第二个社区入口。
+
+### 10. 拥挤降噪
+
+全局拥挤时，靠“缩小点和线、淡化弱边、减少标签”保持点状地图的可读性。2000 节点以内不需要把节点折叠成聚合块。
+
+降噪分三层：
+
+1. 正常密度：显示点、关键线、社区色块和少量社区名。
+2. 开始拥挤：缩小普通节点，降低弱边透明度，隐藏普通标签。
+3. 明显拥挤：继续缩小普通点，只保留关系骨架；社区名减少到重要、悬停、选中或搜索相关社区。
+
+以下对象不被降噪隐藏，哪怕周围拥挤也要优先露出：
+
+- 当前选中节点。
+- 搜索命中节点。
+- Pin 节点。
+- 用户拖过并固定位置的节点。
+- 社区核心节点。
+
+这些对象是用户正在关心的锚点。
+
+### 11. 规模上限与超限保护
+
+正常情况下节点规模在 2000 以内，全局始终是可直接渲染的点状地图。
+
+万一某个知识库节点数超过上限：
+
+- 不卡死，不回旧 DOM 全图。
+- 给出明确提示，例如“图较大，请用筛选缩小范围”。
+- 引导用户用筛选 / 进入社区 / 搜索来缩小当前可见范围。
+
+不为超限场景构建节点聚合或第二套全图产品。
+
+### 12. 空白点击
+
+点击全局空白区域只清理当前临时选择或关闭浮层。
+
+空白点击不负责：
+
+- 切换新旧全图。
+- 进入社区。
+- 回全图。
+- 重排布局。
+
+## 视图切换的视觉连续性
+
+全局是 Sigma（WebGL 点状），社区是 DOM/SVG（富阅读卡片），两种渲染天生不同。切换时要让用户觉得“我放大 / 缩小了同一张地图”，而不是“跳到了另一个页面”。
+
+心法：全局与社区不是两个视图，而是同一张地图的两个缩放层级。
+
+按重要性分三层处理。
+
+### 1. 节点表现统一
+
+同一个节点在全局和社区必须是“同一个对象的不同详细程度”，不是两种外观：
+
+- 颜色按类型 / 社区决定，全局与社区完全一致。
+- 节点的基本形态是“带颜色的点 + 标签”；放大时同一个点展开为卡片，卡片是“点被打开”，不是另一种物件。
+- Sigma 高缩放下的卡片与 DOM 社区的卡片共用同一套卡片样式（圆角、阴影、社区色描边一致）。配色与字体已通过共享样式来源统一，重点是统一“点↔卡片”这层表现。
+
+### 2. 位置连续，不瞬移
+
+- 进入社区时，社区视图的初始节点位置以这些节点在全局中的相对位置为起点，再缓动到阅读布局；不丢进全新或随机布局。
+- 这一条同时解决“固定位置在社区如何使用”：固定 / 全局坐标作为进场起点，再过渡到阅读布局，二者不冲突。
+- 进入社区表现为“镜头推进”：Sigma 先朝目标社区色块聚拢、其余淡出，再把社区视图淡入到该色块刚才的位置与大小；回全图反向。
+- 用户刚点击 / 选中的节点，在切换前后保持位置不跳变、外观一致。
+
+### 3. 切换是渐变，不是硬切
+
+- 两套渲染器交替时使用约 200–300ms 的交叉淡入淡出，并对齐缩放与中心，让它像“一张图变清晰”，而不是“两张图对调”。
+- 外壳（工具条、右抽屉、背景）在切换前后保持一致，不在两条路由间换皮。
+
+分阶段：先做便宜且收益最大的部分——共享卡片样式、社区色、统一外壳、进场用全局位置、交叉淡入淡出、选中节点不跳变。逐节点跨渲染器的位移动画（每个节点从全局坐标滑到社区坐标）工作量大、收益递减，先不做，必要时再加。
+
+不为消除接缝而把社区改成 Sigma：社区是精读场景，DOM 的富文本卡片与抽屉天然优于 WebGL。两套渲染器是合理分工，接缝靠上面三层弥合。
+
+## 架构边界
+
+### 不直接“搬 DOM 到 Sigma”
+
+把旧 DOM 全图的代码直接迁移到 Sigma 不是最优解。
+
+原因是旧 DOM 全图里混合了两类东西：
+
+- 成熟的产品规则，例如点击节点、点击社区、Pin、固定位置、抽屉、搜索高亮。
+- DOM/SVG 特有的绘制方式，例如元素结构、样式、事件绑定和布局细节。
+
+真正应该保留的是第一类产品规则，而不是第二类绘制实现。
+
+因此，正确做法是：
+
+**抽出旧 DOM 全图已经验证过的交互语义，让 Sigma 全局实现这些语义。**
+
+这样后续如果渲染器变化，用户心智不变。
+
+### 规则层
+
+全局规则层负责回答：
+
+- 点到节点应该发生什么。
+- 点到社区应该发生什么。
+- 搜索命中如何影响图面和抽屉。
+- Pin 与固定位置如何表现。
+- 进入社区和回全图如何切换。
+- 当前对象被筛掉时如何提示。
+- 兜底时哪些能力必须保留。
+
+规则层不负责画图。
+
+### Sigma 全局
+
+Sigma 全局负责正常全局地图：
+
+- 画点、边、社区和关键标签。
+- 承接缩放、平移、悬停、节点点击、社区命中和节点拖拽。
+- 把用户点到或拖到的对象交给全局规则层处理。
+- 展示规则层给出的选中、高亮、Pin、固定和摘要状态。
+
+Sigma 不保存另一份业务状态，也不自行决定抽屉内容。
+
+### DOM 社区
+
+DOM 社区负责社区阅读：
+
+- 完整展示社区节点。
+- 承担内容阅读、节点详情和更高密度交互。
+- 使用同一份选中、搜索、Pin 和固定位置状态。
+- “回全图”动作交还给全局路由，而不是在 DOM 内部自己回旧全图。
+
+### DOM 小图兜底
+
+DOM 小图兜底只在 Sigma 不可用且图规模较小时出现。
+
+它必须遵守与 Sigma 全局相同的规则：
+
+- 点击节点打开轻量节点摘要。
+- 点击社区打开轻量社区摘要。
+- 进入社区走 DOM 社区。
+- 回全图仍由全局路由判断。
+- 搜索、筛选、Pin、固定位置和抽屉规则一致。
+
+用户不应该感觉兜底后换了一套产品。
+
+### 超限降级提示
+
+不再设“聚合安全视图”。节点规模控制在 2000 以内，正常不会触发超大图。
+
+唯一的超限保护是一条静态降级提示：
+
+- 不卡死，不回旧 DOM 全图。
+- 告诉用户图较大，引导用筛选 / 搜索 / 进入社区缩小范围。
+- 提供清除选择、重试等基本动作。
+
+它不是第二套全图产品，也不构建节点聚合。
+
+### Sigma 可用性判定
+
+“Sigma 是否可用”是一次性的全局判定结果，由全局统一判断并广播，各视图共享同一结论：
+
+- 判定为不可用的条件：Sigma 初始化失败，或运行期发生不可恢复错误（例如 WebGL 上下文缺失 / 丢失）。
+- 判定为不可用后，图在上限内走 DOM 小图兜底。
+- “回全图”只有在已判定 Sigma 不可用时才进入兜底，否则一律回 Sigma 全局。
+- 超限降级是独立的另一条保护：只要节点数超过上限就触发，与 Sigma 是否可用无关。
+
+## 状态同步规则
+
+先区分两个“统一”：**交互规则**由全局承载（Sigma 全局、DOM 小图兜底）共用；**以下状态**由全部视图（含 DOM 社区）共用。
+
+以下状态必须在 Sigma 全局、DOM 社区、DOM 小图兜底之间共享：
+
+- 当前知识库。
+- 当前视图路由。
+- 当前选中节点或社区。
+- 当前搜索词和搜索命中。
+- 当前筛选条件。
+- Pin 节点。
+- 固定节点位置。
+- 当前社区上下文。
+- 右侧抽屉对象。
+- Sigma 是否可用的判定结果。
+
+尤其要注意固定位置：
+
+- 固定位置不是 Sigma 私有状态。
+- 固定位置不是 DOM 私有状态。
+- 固定位置是用户对知识地图的编辑结果。
+
+只要用户拖过节点，后续各视图都应该尊重这次调整。
+
+## 兜底规则
+
+兜底不再按“旧版全图”理解，而按“同规则的异常承载”理解。
+
+正常情况：
+
+```mermaid
+flowchart LR
+  A["打开图谱"] --> B["Sigma 全局地图"]
+  B --> C["轻量节点/社区摘要"]
+  C --> D["进入 DOM 社区阅读"]
+  D --> E["回全图"]
+  E --> B
+```
+
+Sigma 不可用：
+
+```mermaid
+flowchart LR
+  A["打开图谱"] --> B["Sigma 不可用"]
+  B --> C["DOM 小图兜底"]
+  C --> D["同一套全局规则"]
+```
+
+节点超过上限（极少发生）：
+
+```mermaid
+flowchart LR
+  A["打开图谱"] --> B["节点数超过上限"]
+  B --> C["超限降级提示"]
+  C --> D["引导筛选/搜索/进社区"]
+```
+
+兜底状态下可以降低视觉和性能要求，但不能换掉交互心智。
+
+## 明确不做
+
+本次收口不包含：
+
+- 把社区阅读改成 Sigma。
+- 把全局改成卡片化视图。
+- 保留正常全局里的圆形社区选择按钮。
+- 新增山水纸面感图谱视觉。
+- 增加用户可见的新旧全图切换。
+- 重做关系数据生产。
+- 新增路径解释、导出图片、图谱 lint 等额外能力。
+- 把大图异常回退到旧 DOM 全图硬撑。
+- 用双击空白这类隐式动作承担取消固定或切换视图。
+- 节点聚合折叠（“+N 省略号”）与聚合平滑。
+- 面向超大图的聚合安全视图（改为极简超限提示）。
+- 逐节点跨渲染器的位移动画（先做淡入淡出即可）。
+
+## 验收标准
+
+实现完成后，至少需要满足以下可观察结果：
+
+1. 打开“图谱”Tab，第一眼是 Sigma 点状全局地图，不是 DOM 全图，不是卡片墙。
+2. 全局点击节点，停留在全局，打开轻量节点摘要。
+3. 全局点击社区，停留在全局，打开轻量社区摘要。
+4. 点击“进入社区”，进入 DOM 社区阅读。
+5. 在社区点击工具栏“回全图”，回到 Sigma 全局，不回旧 DOM 全图。
+6. 从抽屉或其他入口回全图，也回到 Sigma 全局。
+7. Sigma 全局可以拖动节点，松手后节点固定。
+8. 刷新页面后，固定节点位置仍恢复。
+9. 进入社区再回全局，固定节点位置仍恢复。
+10. 搜索、筛选、选中、Pin 和固定位置在全局与社区之间不丢失。
+11. Sigma 不可用时，DOM 小图兜底仍遵守同一套全局规则，不进入旧 DOM 全图。
+12. 节点超过上限时只显示超限降级提示，不卡死、不进入旧 DOM 全图、不出现节点聚合。
+13. 全局视角不出现节点卡片。
+14. 正常全局视角不出现圆形社区选择按钮；背景社区色块是地图上的社区选择入口。
+15. 社区名以地图地名方式显示，不塞进圆形按钮。
+16. 拥挤时缩小普通节点、淡化弱边、减少标签；不出现节点聚合折叠。
+17. 社区里的“回全图”上交全局路由切回 Sigma；代码层不存在第二条用户正常可达的 DOM 全图入口。
+18. 切换全局↔社区时，被选中节点颜色 / 标签一致、位置不跳变；切换为淡入淡出而非硬切；社区进场以全局相对位置为起点。
+19. 用户看不到“旧版 / 新版全图”这样的模式分叉。
+
+## 风险与处理原则
+
+### 风险 1：拖拽固定位置牵涉多视图状态
+
+处理原则：固定位置是用户成果，必须做成共享状态。不要让 Sigma、DOM 社区和 DOM 兜底各自保存位置。
+
+### 风险 2：DOM 社区内部仍有自己的回全图逻辑
+
+已确认为本次根因（见“现状诊断”）：社区工具条的“回全图”调用 DOM 管线内部的 `resetViewState()`，没有切回 Sigma。
+
+处理原则：社区里的回全图动作必须上交全局路由，不允许 DOM 社区自行切回旧 DOM 全图。
+
+### 风险 3：兜底体验再次分叉
+
+处理原则：DOM 小图兜底不是旧产品复活。它必须调用同一套全局规则，只换渲染承载。
+
+### 风险 4：全局地图被做成阅读界面
+
+处理原则：全局只看结构。阅读、详情和高密度内容留给社区视角和右侧抽屉。
+
+### 风险 5：两套渲染器在切换处视觉割裂
+
+处理原则：把全局与社区当作同一张地图的两个缩放层级——统一节点表现（点↔卡片同源）、保持位置连续、用淡入淡出替代硬切。详见“视图切换的视觉连续性”。
+
+## 后续交接边界
+
+后续如果进入实现计划，应只围绕以下交付边界展开，不扩大到图谱新功能：
+
+- 统一全局返回路径（社区“回全图”上交全局路由切回 Sigma，替换 DOM 管线内部的 `resetViewState` 自我重置）。
+- 统一全局交互规则。
+- 补齐 Sigma 全局日常交互。
+- 沿用全局节点拖拽和固定位置能力。
+- 移除正常全局里的圆形社区按钮，改为社区色块 + 地图地名。
+- 接入拥挤降噪规则：缩点、淡边、减标签，不做节点聚合。
+- 实现全局↔社区切换的视觉连续性（节点表现统一、位置连续、淡入淡出）。
+- 同步 DOM 小图兜底规则。
+- 节点超过上限时显示超限降级提示。
+- 按本文验收标准逐项验证。
+
+这份文档只定义设计和验收，不直接进入实现。
+
+## 修订记录
+
+- 2026-06-21（二版）：按 ≤2000 节点收敛——删除节点聚合、聚合平滑与聚合安全视图，渲染承载收敛为三种；补“现状诊断”确认根因（社区回全图调用 DOM 管线 `resetViewState`，未切回 Sigma）；新增“视图切换的视觉连续性”；补 Sigma 可用性判定与相关验收项。