394 lines
16 KiB
Markdown
394 lines
16 KiB
Markdown
# 全局 Sigma 社区高亮交互设计
|
||
|
||
日期：2026-06-26
|
||
状态：已确认方向，待用户复核
|
||
当前分支：`codex/global-sigma-community-spotlight-design`
|
||
|
||
> **实现勘误（plan-eng-review 2026-06-26）**：核实代码后两点收口，实现以 `workbench/docs/global-sigma-community-spotlight-plan.md` 为准。
|
||
> 1. 本文“点社区后地图几乎没有反馈”部分不成立——现状点社区已驱动云团/标签/边 dim（`selection`→`community.selected`，sigma-global-renderer.ts:251/679/716/1034）。真正缺的只有：其他社区**节点** dim + 相机轻量动画。
|
||
> 2. 下文“新增 `spotlightCommunityId` 独立状态”按 plan 收口为**复用现有 `selection`**（高亮社区与选中社区始终同步，无需平行字段）；正文 `spotlightCommunityId` 字样一律读作“selection 的社区视觉态”。`focusCommunity()` 仍绝不复用。
|
||
|
||
## 目的
|
||
|
||
这份设计用于补齐 llm-wiki 全局图谱里“点击社区之后，图本身几乎没有反馈”的体验缺口。
|
||
|
||
当前全局图已经承担“知识库地图”的职责：用户可以看到社区分布、节点点位、少量地标标签和跨社区关系。点击社区后，右侧抽屉会显示社区简介；只有点击抽屉里的“进入社区”，才会进入 DOM/SVG 社区阅读视图。这个两步边界是正确的，应该保留。
|
||
|
||
但现在点击社区后，地图本身没有形成足够强的“我正在看这个社区”的状态：用户主要靠右侧抽屉理解选择结果，图谱区域更像静态背景。本设计要补的是全局图内部的临时高亮态。
|
||
|
||
一句话：
|
||
|
||
**点击社区后仍停留在全局地图，但地图要轻量高亮当前社区；真正进入社区仍由抽屉里的“进入社区”按钮负责。**
|
||
|
||
## 术语说明
|
||
|
||
本设计避免继续使用“社区聚焦”命名这个新状态。
|
||
|
||
在现有 PRODUCT / ADR 语境里，“社区聚焦视图”已经指向进入社区后的 DOM/SVG 局部阅读视图，也就是 `focusCommunity()` 会切过去的那条路径。本文要设计的是“仍停留在全局 Sigma 地图里的临时强调状态”，两者不是一回事。
|
||
|
||
因此，本文统一使用：
|
||
|
||
- **全局社区高亮态**：留在 Sigma 全局图里，当前社区被强调，其他社区弱化。
|
||
- **社区阅读视图 / 社区聚焦视图**：进入 DOM/SVG 社区视图，主要用于阅读和深入探索。
|
||
- **`spotlightCommunityId`**：后续实现中建议使用的临时状态名，避免继续复用 `focus` / `focusCommunity`。
|
||
|
||
## 设计结论
|
||
|
||
采用“全局内高亮”方案。
|
||
|
||
1. 点击社区后，不切到社区视图。
|
||
2. 右侧抽屉继续显示社区简介。
|
||
3. 全局 Sigma 图进入临时社区高亮态。
|
||
4. 当前社区变清晰、变突出。
|
||
5. 其他社区明显弱化但仍可见。
|
||
6. 视角只做轻量构图调整，不做强镜头推进。
|
||
7. 左上“回全图”按钮复用为退出高亮入口。
|
||
8. 点空白处也可以退出高亮并清空当前选择。
|
||
9. 抽屉里的“进入社区”按钮继续负责进入 DOM/SVG 社区阅读。
|
||
|
||
这个方案保留了“全局图是地图”的心智：用户是在地图里选中一片区域，而不是已经进入那片区域阅读。
|
||
|
||
## 为什么不直接进入社区
|
||
|
||
点击社区直接进入社区视图会让操作更快，但会牺牲全局地图的浏览能力。
|
||
|
||
全局图里的社区点击有两个不同目的：
|
||
|
||
- 看这个社区在全局里的位置。
|
||
- 进入这个社区阅读细节。
|
||
|
||
这两个目的不应该合并成一个动作。当前产品已经用“点击社区打开简介抽屉，再点进入社区”的方式把它们分开，这是合理的。
|
||
|
||
因此，本设计不改变已有两步逻辑，只增强第一步的地图反馈。
|
||
|
||
## 为什么不强拉近镜头
|
||
|
||
最初可以想到一种动画：点击社区后，镜头明显拉近到该社区，其他社区隐藏，像进入一个局部世界。
|
||
|
||
这个方案不推荐，原因是它会和“尚未进入社区视图”的心智冲突。用户看到画面只剩一个社区时，很容易以为自己已经进入社区；这会削弱抽屉里“进入社区”按钮的意义。
|
||
|
||
更好的体验是“高亮构图”，不是“深入切换”：
|
||
|
||
- 视角可以轻微平移，让当前社区处在更舒服的位置。
|
||
- 视角可以轻微放大，但不能放大到只剩当前社区。
|
||
- 主要靠高亮、清晰度和弱化规则表达当前对象。
|
||
- 其他社区仍然在场，维持全局空间感。
|
||
|
||
最终感觉应该是：
|
||
|
||
**我仍在看整张知识地图，只是当前社区被重点标出来了。**
|
||
|
||
## 现有代码边界
|
||
|
||
这次设计基于当前代码事实，不把全局和社区两条路线混在一起。
|
||
|
||
当前已有边界：
|
||
|
||
- `focusCommunity(id)` 会把路由切到 `dom-svg-community`，它代表“进入社区阅读”。
|
||
- Sigma 全局路线里的社区点击现在走 `selectOnSigma({ kind: "community", id })`，代表“选中社区并打开摘要”。
|
||
- Sigma 全局路线的适配数据目前显式传入 `focus: null`，所以全局路线不会消费 DOM 社区视图的 focus 状态。
|
||
- Sigma 全局已经有社区云团覆盖层、社区标签覆盖层、节点命中热区、空白点击、相机状态读取和恢复。
|
||
- Sigma 全局的“回全图”按钮现在只在本路线内清空 focus/selection；社区视图里的“回全图”通过全局路由回调切回 Sigma。
|
||
|
||
因此，后续实现不应复用 `focusCommunity(id)` 来做全局高亮。需要新增一个只属于全局 Sigma 的临时状态，例如 `spotlightCommunityId`。它和“进入社区阅读”的 focus 必须分开。
|
||
|
||
## 与既有 ADR 和阶段关系
|
||
|
||
本设计不推翻 ADR-21 / ADR-22 的社区点击修订，而是增强它们的第一步。
|
||
|
||
ADR-21 和 ADR-22 已经明确：全局图里点击社区不再直接进入社区聚焦视图，而是先显示社区摘要，再由明确按钮进入社区。本设计继续遵守这条边界，只是在“先显示社区摘要”的同时，让全局地图也给出足够清楚的视觉反馈。
|
||
|
||
阶段归属上，本设计应作为阶段 4.7 之后的独立图谱交互任务处理，建议归入后续阶段 4.8 或独立 issue。它依赖阶段 4.7 已完成的“地图心智”和 Sigma 覆盖层性能地基，但不属于 #70 标签兜底，也不应混入社区阅读视图改造。
|
||
|
||
进入实现前，需要同步 PRODUCT.md 的对应阶段记录和 ADR-21 / ADR-22 关系说明，避免“社区聚焦视图”和“全局社区高亮态”在产品文档里继续混用。
|
||
|
||
## 用户交互规则
|
||
|
||
### 1. 普通全局状态
|
||
|
||
用户打开图谱时，默认进入普通全局状态。
|
||
|
||
普通全局状态显示：
|
||
|
||
- 社区分布。
|
||
- 节点点位。
|
||
- 关系骨架。
|
||
- 少量地标标签。
|
||
- 搜索、筛选、Pin、选中等已有状态。
|
||
|
||
普通全局状态不显示：
|
||
|
||
- 全量标签。
|
||
- 节点卡片。
|
||
- 大段正文。
|
||
- 社区内部阅读布局。
|
||
|
||
### 2. 点击社区
|
||
|
||
用户点击社区云团、社区区域或社区图例时：
|
||
|
||
- 保持在 Sigma 全局路线。
|
||
- 选中该社区。
|
||
- 右侧抽屉显示社区简介。
|
||
- 图谱进入全局社区高亮态。
|
||
- 当前社区视觉增强。
|
||
- 其他社区明显弱化但仍可见。
|
||
- 不自动进入社区视图。
|
||
|
||
如果用户再次点击另一个社区：
|
||
|
||
- 高亮态切换到新社区。
|
||
- 抽屉切换到新社区简介。
|
||
- 视角做一次轻量构图调整。
|
||
|
||
### 3. 进入社区
|
||
|
||
用户只有点击抽屉里的“进入社区”按钮，才进入 DOM/SVG 社区阅读视图。
|
||
|
||
进入社区视图后：
|
||
|
||
- 图谱切到社区阅读路线。
|
||
- 社区内节点可以使用更高信息密度。
|
||
- 社区视图继续承担阅读和探索任务。
|
||
- 这不属于全局社区高亮态。
|
||
|
||
### 4. 回全图按钮复用
|
||
|
||
左上“回全图”按钮保留同一文案和同一入口，但按当前状态分层处理。
|
||
|
||
在社区视图中点击：
|
||
|
||
- 切回 Sigma 全局路线。
|
||
|
||
在 Sigma 全局高亮态中点击：
|
||
|
||
- 不切路线。
|
||
- 清除全局社区高亮态。
|
||
- 清空当前社区选择并关闭抽屉。
|
||
- 视角回到完整全局构图。
|
||
|
||
在普通 Sigma 全局状态中点击：
|
||
|
||
- 重置全局视角。
|
||
- 清空临时选择。
|
||
- 保持筛选、Pin、搜索等明确用户状态。
|
||
|
||
这样用户只需要理解一个含义：“回到全局地图”。系统内部根据当前层级选择正确动作。
|
||
|
||
### 5. 点空白处
|
||
|
||
点空白处是“退出当前临时高亮”的快捷动作。
|
||
|
||
如果当前在全局社区高亮态：
|
||
|
||
- 退出高亮态。
|
||
- 清空当前社区选择。
|
||
- 抽屉同步关闭。
|
||
- 视角回到普通全局构图。
|
||
|
||
如果当前只是普通全局选中节点或社区：
|
||
|
||
- 清空选择。
|
||
- 关闭抽屉。
|
||
|
||
如果工具栏面板打开：
|
||
|
||
- 先关闭工具栏面板，再处理选择或高亮，保持现有空白点击优先级。
|
||
|
||
“回全图”和“点空白处”在全局社区高亮态下做相同清理动作，这是有意冗余：前者给用户一个可发现按钮，后者给熟练用户一个快速退出手势。两者都代表“离开当前社区摘要，回到普通全局地图”，所以都清空选择并关闭抽屉。
|
||
|
||
## 高亮态视觉规则
|
||
|
||
全局社区高亮态的核心不是“把当前社区单独放大”，而是“在全局地图上强调当前社区”。
|
||
|
||
当前社区：
|
||
|
||
- 社区云团不弱化。
|
||
- 社区标签优先显示。
|
||
- 社区内重要节点标签优先显示。
|
||
- 社区内节点和内部关系保持正常或略增强。
|
||
- 与当前社区相关的跨社区关系可以保留一部分。
|
||
|
||
其他社区：
|
||
|
||
- 社区云团降低不透明度。
|
||
- 节点降低不透明度，但仍保留可辨认的点位。
|
||
- 普通节点标签隐藏或明显弱化。
|
||
- 普通关系线弱化。
|
||
- 与当前社区存在强关系的邻近社区可以弱化得更轻。
|
||
|
||
这种“弱化但仍可见”的规则优于完全隐藏。完全隐藏会让用户误以为已经进入社区视图；弱化保留全局定位。
|
||
|
||
### 叠加优先级
|
||
|
||
全局社区高亮态必须和搜索、筛选、Pin、选中状态同时工作，不能互相覆盖。
|
||
|
||
优先级建议如下：
|
||
|
||
1. **筛选**决定对象是否属于当前可见集合。被筛掉的对象不因为高亮态强行出现；如果当前抽屉对象被筛掉，沿用既有“对象不在当前结果中”的提示和“显示该对象 / 清除选择”动作。
|
||
2. **搜索命中**优先于社区弱化。即使搜索结果在其他社区，也不能被当前社区高亮态压到看不见；命中节点、命中社区标签和必要路径应保持可见。
|
||
3. **当前选中对象**优先于普通弱化。当前抽屉对象必须始终可辨认。
|
||
4. **Pin / 固定节点**优先于普通节点。被用户固定过的节点不能因为高亮态突然消失。
|
||
5. **社区高亮态**只处理剩余普通对象的强弱关系。
|
||
|
||
典型例子：用户正在高亮社区 A，同时搜索命中社区 B 的节点。此时社区 A 仍是当前上下文，但社区 B 的搜索命中节点必须清晰可见，不能被当作普通非当前社区节点压暗。
|
||
|
||
## 动画规则
|
||
|
||
动画采用“轻量构图调整”，不采用强镜头推进。
|
||
|
||
点击社区后：
|
||
|
||
1. 抽屉立即打开，不等待动画结束。
|
||
2. 当前社区马上进入高亮状态。
|
||
3. 视角在短时间内轻微平移，让该社区落到更舒服的位置。
|
||
4. 如果社区已经处于良好位置，不必移动视角。
|
||
5. 如果社区在画面边缘，可以适度平移。
|
||
6. 可以轻微放大，但放大比例必须受上限约束。
|
||
7. 右侧抽屉打开时，构图中心应略偏左，避免当前社区被抽屉遮挡。
|
||
|
||
连续点击不同社区时：
|
||
|
||
- 新点击立即接管当前高亮状态。
|
||
- 新构图动画立即打断旧动画。
|
||
- 动画不排队、不叠加。
|
||
- 如果旧动画已经接近终点，可以从当前相机状态平滑过渡到新目标。
|
||
- 抽屉内容以最后一次点击为准。
|
||
|
||
动画时长建议：
|
||
|
||
- 普通情况：约 300-500ms。
|
||
- 用户开启系统减少动态效果时：直接跳到终态或使用极短过渡。
|
||
|
||
动画目标：
|
||
|
||
- 让用户感觉“视线被带到当前社区”。
|
||
- 不制造“已经进入社区”的错觉。
|
||
- 不让全图位置关系发生重排。
|
||
|
||
明确不做：
|
||
|
||
- 不移动节点真实坐标。
|
||
- 不重新布局整张图。
|
||
- 不把当前社区节点物理拖到中心。
|
||
- 不隐藏所有其他社区。
|
||
- 不用强 zoom 取代高亮表达。
|
||
|
||
## 状态模型
|
||
|
||
后续实现应区分三类状态。
|
||
|
||
### 路由状态
|
||
|
||
决定用户在哪种视图：
|
||
|
||
- Sigma 全局。
|
||
- DOM/SVG 社区阅读。
|
||
- DOM 小图兜底。
|
||
- 超限或不可用提示。
|
||
|
||
“进入社区”改变路由状态。
|
||
|
||
### 全局社区高亮状态
|
||
|
||
只在 Sigma 全局路线内存在。
|
||
|
||
它记录当前被全局高亮的社区 id，建议命名为 `spotlightCommunityId`，用来驱动：
|
||
|
||
- 当前社区高亮。
|
||
- 其他社区弱化。
|
||
- 社区标签优先级。
|
||
- 轻量构图动画。
|
||
- “回全图”在全局路线内的行为。
|
||
|
||
它不等于进入社区。
|
||
|
||
状态落点建议：
|
||
|
||
- 放在 Sigma 全局 route renderer / facade renderer 的局部状态里。
|
||
- 不进入顶层 `GraphFacadeState.focus`。
|
||
- 不复用 `focusCommunity()`。
|
||
- 不写入知识库文件。
|
||
- 路由离开 Sigma 全局时可以丢弃。
|
||
- 底层 Sigma renderer 只消费这个视觉状态，不把它当成业务数据源。
|
||
|
||
### 选择状态
|
||
|
||
继续记录当前抽屉对象，例如选中某个社区或节点。
|
||
|
||
点击社区时，选择状态和全局社区高亮状态通常同步：
|
||
|
||
- 选择状态决定抽屉显示什么。
|
||
- 全局社区高亮状态决定地图如何表达。
|
||
|
||
退出高亮时，同时清空选择并关闭抽屉。这样“回全图”和“点空白处”的结果一致，用户不会看到地图已经回全局、抽屉还停在旧社区的割裂状态。
|
||
|
||
## 性能边界
|
||
|
||
这次交互不能把每次点击变成一次昂贵的全图重建。
|
||
|
||
优先策略：
|
||
|
||
- 节点真实坐标不变。
|
||
- 布局不重算。
|
||
- 相机只做平移和轻微缩放。
|
||
- 视觉弱化通过渲染状态或属性控制。
|
||
- 社区云团和标签覆盖层继续复用现有结构。
|
||
- 相机移动过程中只更新覆盖层位置，不重建覆盖层 DOM。
|
||
|
||
现有 Sigma 全局已经做过覆盖层拆分：结构更新和相机重定位分开。这个方向应继续保持。
|
||
|
||
需要避免：
|
||
|
||
- 点击社区就重新计算全图布局。
|
||
- 每一帧重建社区云团 DOM。
|
||
- 大量新增 hover DOM 元素。
|
||
- 用全量标签显示解决高亮反馈问题。
|
||
- 在全局社区高亮态中引入社区阅读级别的富内容。
|
||
|
||
## 后续实现边界
|
||
|
||
建议后续实现拆成一项独立任务，不和 #70 标签兜底混在一起。
|
||
|
||
#70 适合继续保持小修复：只给全局已显示标签加长度兜底，防止长标签破图。
|
||
|
||
全局社区高亮是新交互能力，应另开 issue 或设计任务实现。它至少会涉及：
|
||
|
||
- Sigma 全局路线的临时高亮状态。
|
||
- 社区点击后的 `spotlightCommunityId` 写入。
|
||
- 回全图按钮的分层行为。
|
||
- 空白点击退出高亮。
|
||
- 相机轻量构图动画。
|
||
- 高亮态视觉弱化规则。
|
||
- 搜索、筛选、Pin、抽屉选择的状态协调。
|
||
- 浏览器交互验证。
|
||
|
||
## 验收标准
|
||
|
||
实现完成后，应至少验证以下路径。
|
||
|
||
1. 普通全局图点击社区：右侧抽屉打开，当前社区高亮，其他社区弱化但仍可见，不进入社区视图。
|
||
2. 点击抽屉“进入社区”：进入 DOM/SVG 社区阅读视图。
|
||
3. 社区视图点“回全图”：回到 Sigma 全局路线。
|
||
4. 全局高亮态点“回全图”：停留在 Sigma，全图恢复普通构图。
|
||
5. 全局高亮态点空白处：退出高亮，抽屉关闭，选择清空。
|
||
6. 连续点击不同社区：抽屉和图谱高亮同步切换，动画不抖动。
|
||
7. 高亮状态下搜索和筛选：不丢失明确用户状态，不出现空白图。
|
||
8. 节点 Pin 和拖拽后的固定位置：不因高亮和回全图丢失。
|
||
9. 右侧抽屉打开时：高亮社区不被抽屉遮挡。
|
||
10. 减少动态效果设置开启时：动画降级为无动画或极短过渡。
|
||
|
||
## 不在本设计内
|
||
|
||
本设计不包含：
|
||
|
||
- 改写社区阅读视图。
|
||
- 把社区视图迁移到 Sigma。
|
||
- 全局 hover 完整方案。
|
||
- 全局节点详情卡片重做。
|
||
- 社区内部布局重排。
|
||
- 大图聚合系统。
|
||
- #70 标签长度兜底实现。
|
||
|
||
全局 hover 可以在本设计之后另开一份设计：它应基于这里定义的全局社区高亮状态继续补，而不是重新定义点击社区的意义。
|