@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/workbench/docs/graph-evolution-1-design.md

@@ -0,0 +1,210 @@
+# 阶段 4.6 设计文档：图谱演进第一批（看清关系 + 层层聚焦 + 控制工具条）
+
+> 状态：**已实施并通过验收**
+> 日期：2026-06-14
+> 来源：[PRODUCT.md](../PRODUCT.md)「图谱演进候选池」（2026-06-13 沉淀）的首次落地；经 2026-06-14 spark 脑暴收敛。
+> 与 [stage-4.5-design.md](stage-4.5-design.md) 的关系：4.5 是「图谱可用性收尾」（已合入）；本批是其后第一个增量批次，复用 4.5 的画布导航 / 点击即阅读 / 右抽屉基建。G1-2、G1-3 **修订** 4.5 的 D4.5-6（社区交互、左上角浮层图例），冲突处以本文档为准。
+> 阶段编号：**4.6**（作者 2026-06-14 拍板，已登记 PRODUCT.md §4）。实施完成后已同步 PRODUCT.md 与 ADR-23；决策号沿用 `G1-*`。
+
+---
+
+## §0 背景：方向与边界
+
+「图谱演进候选池」作为备忘清单合格，但作为推进依据有三处会误导，spark 脑暴已逐一纠正：
+
+1. **它把一条主线藏成了清单里的普通一项**。候选池自己写了尸检教训"局部图才是工具"，却把「局部图模式」与「导出美图」并列。真相：局部聚焦是主线，关系边 / 过滤器是挂在它上面的增强。
+2. **它混进了一个根本不是图谱功能的东西**。「图谱增强检索（后端暗改）」用户看不见图谱，是 RAG 检索质量功能（属 ADR-19 检索演进线），不该占图谱候选池的决策位。本批不收。
+3. **「高价值低成本」是会骗人的排序轴**。7 项全标"高价值低成本"等于没排序，还诱导"先挑便宜的"。正确的尺子是**就绪度**——候选池里多数项不是"要新建的新功能"，而是阶段四「双宿主统一」时被打散、就绪度不同的半成品。
+
+**本批方向（作者拍板）**：让**在用的人更顺手**（日常可用性）——看得清关系、能层层聚焦、控制件不挡图。美观 / 惊艳 demo 后移。"功能完善"指**用户真正能用到的**功能，花里胡哨靠边站。
+
+候选池逐项处置：
+
+| 候选池项 | 本批处置 | 理由 |
+|---|---|---|
+| 关系类型上边 | ✅ 做（G1-1） | 关系词汇表与置信度体系已存在；当前边 `type` 实际是置信度，本批先补齐边数据契约，再渲染 |
+| 局部图模式 | ✅ 做（G1-2） | 主线；引擎已有 focus/neighbors/密度，差"聚焦视图"组装 |
+| 类型/时间过滤器 | ◐ 类型做、时间二期（G1-2） | 类型数据现成；时间需给节点补 mtime |
+| 左上角浮层（社区面板） | ✅ 重构为控制工具条（G1-3/4） | 现状不透明挡图、低频霸屏 |
+| 路径查找 + agent 讲解 | ⏸ 后移 | 惊艳 demo 非日常顺手；旧 HTML 做过、引擎留残骸 |
+| lint 健康上图 | ⏸ 下一批 | "知识库体检"与"浏览聚焦"不同类、代码不共享 |
+| 导出美图 | ⏸ 后移 | 美观后移；导出走外挂 Skill 是未来路线（见 §5 备注） |
+| 图谱增强检索 | ✗ 不收 | 非图谱功能，归 ADR-19 检索线 |
+| 远期池（嵌入布局 / LLM 推断边 / AI 摘要 / 社区摘要 hover） | ⏸ 远期 | 依赖消化管线升级 |
+
+---
+
+## §1 核心决策（G1-1 ~ G1-5）
+
+### G1-1 关系类型上边（看清关系）
+
+把边"是什么关系""有多确定"同时画出来，二者都是本批 G1-1 的完整交付，不做"只有颜色、没有置信度虚实"的降级版。
+
+**数据契约 · 关系类型与置信度必须分开**：
+- `relation_type`（字段名可在实现时按本地命名定，但语义必须独立）承载关系词：实现 / 依赖 / 对比 / 矛盾 / 衍生
+- `confidence` 承载置信度：`EXTRACTED` / `INFERRED` / `AMBIGUOUS`
+- 当前代码里 `GraphEdge.type` 是 `Confidence`，`build-graph-data.sh` 输出的 `type` 也是置信度；执行时不可直接把现有 `type` 当关系类型上色
+- 如果 Phase 0.2 核验发现任一维缺失，先补 `build-graph-data.sh` 与类型/测试，再接 UI；后端服务仍零改动
+
+**必做 · 颜色 = 关系类型**（克制编码，避免与节点色抢视觉——节点已用左色条编码 ENTITY/SOURCE 等类型）：
+- 对立关系给警示色：**矛盾**、**对比**（琥珀）——❗ 矛盾色须**避开 ENTITY 节点已用的红**，取品红 / 橙红一类，防"红节点 vs 红边"语义混淆
+- 顺承关系（实现 / 依赖 / 衍生）= 统一中性色（蓝灰，跟随主题）
+- hover 边时浮出关系词中文，让中性色边也能查到具体类型
+
+**必做 · 虚实 = 置信度**（`EXTRACTED` 实线 / `INFERRED` 虚线 / `AMBIGUOUS` 点划或弱虚线）：置信度不再借用关系色表达，必须与关系类型并存。
+
+**全局低权重、聚焦才完整呈现（与 G1-2 协同，关键）**：截图实测 88 节点 / 217 边，全局图上给每条边都强着色只会更糊。所以全局视图边保持**低视觉权重**（细、低饱和）；进入 G1-2 聚焦视图（边数骤减）后，关系色 / 虚实才完整显现。关系边的价值在"看清局部"，不在"全局花式"。
+
+- **不做方向箭头**（有向信息 `from/to` 已在数据，箭头增噪，需要时再加）
+- 配套**边图例**（颜色 / 虚实含义）进控制工具条弹出层（G1-3）
+
+**现状证据**：
+- 当前边数据带 `type`，但含义是置信度：[build-graph-data.sh:160](../../scripts/build-graph-data.sh#L160) 读取 `<!-- confidence: ... -->`，[build-graph-data.sh:261](../../scripts/build-graph-data.sh#L261) 输出 `{id, from, to, type}`
+- 当前类型定义也把边 `type` 定义成 `Confidence`：[types.ts:56](../../packages/graph-engine/src/types.ts#L56)
+- 当前渲染已有置信度 class / 虚线基础：[static-renderer.ts:940](../../packages/graph-engine/src/render/static-renderer.ts#L940)、[static-renderer.ts:1682](../../packages/graph-engine/src/render/static-renderer.ts#L1682)
+- 关系词汇表：`.wiki-schema.md`（[schema-template.md:178](../../templates/schema-template.md#L178)，实现 / 依赖 / 对比 / 矛盾 / 衍生）
+- 置信度体系：[SKILL.md:384](../../SKILL.md#L384) 起 `EXTRACTED` / `INFERRED`
+- ❗ Phase 0.2 必须产出样本，证明每条边同时有关系类型与置信度；缺哪个补哪个，不裁掉 UI 维度
+
+**归属**：引擎层渲染（`packages/graph-engine/render`），两端同享。
+
+### G1-2 递进式聚焦（层层钻进，主线）
+
+用户心智："先用社区筛出想看的范围，再在范围里点出重点。"两层递进：
+
+```
+第一层  点社区行/团块  → 只显示该社区节点，隐藏其余社区（非淡化）；进入【社区聚焦视图】
+第二层  视图内点节点    → 节点高亮 + 右抽屉打开阅读态（沿用 4.5 点击即阅读，二者合一）
+类型筛选 实体/主题/来源 → 与社区聚焦同机制（visibility 过滤），可叠加
+```
+
+**手势契约**（关键，消歧义）：
+
+| 操作 | 行为 |
+|---|---|
+| 单击空白（聚焦视图内） | 退一层：节点高亮 → 当前社区视图（**不回全图**——用户明确要的"误操作不打回原形"） |
+| 单击空白（全局视图） | 清空当前选区 / 高亮，不切换视图 |
+| 双击空白 | 一步回全图（沿用 4.5 D4.5-1 已有手势） |
+| Esc | 一步回全图并清空（**不做逐级**——逐级靠单击空白，分工清晰、不让用户迷糊在第几层） |
+
+**弹出层与空白点击优先级**：如果控制工具条弹出层已打开，第一次单击画布空白只关闭弹出层，不触发聚焦退层 / 清选区；弹出层已关闭时，才执行上表的画布语义。
+
+**与 4.5 的关系**：4.5 D4.5-6 的社区点击是"选中整簇高亮 + 其余淡化 + 视口飞至"（选区态）。本批**升级**为"隐藏其余、进入聚焦视图"，同时抽屉仍呈现该簇选区态动作（聚焦与选中合一，一个动作两个收益）。
+
+**现状证据**（多为"半成品收尾"而非新建）：
+- `focusNode` 引擎已有且工作台已接：[GraphPanel.tsx:361](../web/src/components/GraphPanel.tsx#L361)
+- `neighbors` 选区全链路已通（App / GraphSelection / GraphPanel / RightDrawer）
+- 密度模式 `point-plus-focus`、`model/visibility.ts::applyFocusMode`、`Community` 全套类型均在
+- ❗ 区分：现有 `focusNode` 是"镜头对准某点"，`neighbors` 是"全局图上叠加高亮"；本批新增的是"**隐藏非聚焦集、只渲染聚焦子集**"的视图过滤层
+
+**类型筛选**：节点 `type`（entities/topics/sources）建库即分好（[build-graph-data.sh:89](../../scripts/build-graph-data.sh#L89)），纯前端开关。**时间筛选（最近 N 天）本批不做**——节点数据无 mtime，需轻度改管线，归二期。
+
+**归属**：引擎层过滤逻辑，两端同享。
+
+### G1-3 顶部控制工具条（取代左上角浮层）
+
+**问题**：现左上角"社区"面板不透明、从顶到底霸屏、直接盖住画布节点（作者截图实证），且把"图例（被动看）"与"聚焦筛选（主动点）"两种相反性质揉在一处 → 又大又挡。
+
+**设计**：把常驻浮层换成"画布是主角、控制件平时收边、叫了才上前"。
+
+- **位置**：图谱视图顶部标签栏下方的横条（工作台截图红框区，现为空白）；离线 HTML 取页面顶部。固定、不挡图、横向可扩展
+- **平时**：只露少量入口（筛选/社区、图例、回全图），其余收"更多"
+- **点"筛选/社区"** → 弹出一张紧凑面板：社区列表（点行 = 进 G1-2 聚焦视图）+ 类型开关 + 边图例（颜色/虚实含义）。点画布空白优先收起弹出层
+- **取代**现常驻浮层"社区"白面板（删除该浮层）
+
+> **取舍**：本方案比"给旧面板加个折叠箭头"工程量大，但本批的类型筛选（G1-2）和边图例（G1-1）都要进场，塞进旧大列表只会更挤；一次把工具条立起来避免二次返工。这是主动选择，不是过度设计。
+
+**防失控原则**（写死，避免工具条沦为图标垃圾堆）：
+
+> 工具条只放「对整张图」的操作（筛选 / 回全图 / 图例 / 未来导出）；「对单个节点」的操作（阅读 / 提问 / 建链）留在点节点后的右抽屉。常用露出、长尾收「更多」。
+
+- **成长位（本批不做，仅预留布局）**：导出美图、切换布局、健康体检——来了都挂这条工具条
+
+### G1-4 默认收起 + 半透明（"折叠"需求的升级）
+
+用户原始诉求是"面板可折叠（小屏不友好）"。升级为：
+
+- **不是"默认展开 + 可折叠"，而是"默认收起、用时展开"**（弹出层用完即收，画布常态 100% 可见）
+- 控制面板 / 弹出层**半透明（毛玻璃）**，即便展开也不死挡图
+- 收起 / 展开状态**记本机**（沿用 4.5 D9 / ADR-22："图例折叠属于浏览状态，留本机，不入库文件"）
+
+### G1-5 双宿主分工
+
+沿用 ADR-21「一个引擎、两个宿主」+ capabilities 注入：
+
+| 能力 | 工作台 | 离线 HTML（Skill） |
+|---|---|---|
+| 关系边上色/虚实 + 边图例（G1-1） | ✅ | ✅ |
+| 递进聚焦 + 类型筛选（G1-2） | ✅ | ✅ |
+| 控制工具条 + 默认收起 + 半透明（G1-3/4） | ✅ 顶部标签栏下方 | ✅ 页面顶部 |
+| 节点提问 / 建链（onAsk） | ✅ | ✗（离线无 agent，点节点 = 阅读/高亮，不提问） |
+
+差异仅靠现有 `GraphEngineCapabilities`（`onAsk` 等回调）表达，引擎核心零分叉。
+
+---
+
+## §2 实施面
+
+**实施顺序（先止血）**：G1-3 / G1-4（解决挡图）→ G1-2（聚焦 + 类型筛选）→ G1-1（关系边）。关系边排最后，因它要靠聚焦视图才看得清（见 G1-1 全局低权重）。
+
+```
+packages/graph-engine/
+├── src/types.ts  边契约区分 relation_type 与 confidence，保留旧 type=confidence 兼容入口直到脚本与测试迁完
+├── render/   关系边渲染（全局低权重 / 聚焦完整呈现）+ hover 关系词；边图例；控制工具条 + 弹出面板（半透明 / 默认收起）；
+│             离线 HTML 已有 `.offline-header`（标题 + 统计 badges，build-graph-html.sh:239），工具条挂入该 header，非新增结构
+├── model/    聚焦视图过滤层（隐藏非聚焦集，区别于现有 focus 镜头/neighbors 叠加）；类型筛选过滤
+├── select/   社区点击语义：从"选中高亮"升级为"进入聚焦视图 + 选区态"（修订 D4.5-6）
+└── index.ts  必要的视图状态 API（进/出聚焦视图、当前筛选集）
+
+workbench/web/
+├── 删除左上角常驻"社区"浮层，改接顶部工具条
+├── 顶部标签栏下方挂工具条容器；弹出面板复用 cmdk/shadcn 既有组件
+└── 单击/双击空白手势接线（G1-2 手势契约）；节点聚焦 → 右抽屉阅读态（复用 4.5 GraphReader）
+
+tests/
+├── 引擎单测：关系类型→颜色、置信度→虚实；聚焦视图过滤（隐藏集正确）；类型筛选；手势状态机
+└── 回归：关系边 DOM 断言；社区点击新语义；离线 HTML 工具条存在 + 无 onAsk 入口
+```
+
+脚本：`scripts/build-graph-data.sh` 在本批范围内，用来补齐关系类型 + 置信度边契约。后端服务：**零改动**。离线 HTML：引擎升级自动获得关系边 / 聚焦 / 工具条（两端红利）。
+
+## §3 验收剧本（给实施 plan 引用）
+
+1. **关系边**：边按关系类型着色——矛盾色（**非 ENTITY 红**）、对比琥珀、顺承中性色；置信度控制虚实——`INFERRED` 虚线 / `EXTRACTED` 实线 / `AMBIGUOUS` 弱虚线；全局视图边低权重、聚焦视图内完整呈现；hover 边浮关系词；山水 / 墨夜两主题下均与节点色可区分
+2. **边图例**：工具条弹出面板含边图例，颜色/虚实说明与实际渲染一致
+3. **社区聚焦（第一层）**：点社区 → 仅该社区节点可见、其余隐藏；**单击空白回到该社区视图而非全图**；双击空白回全图
+4. **节点聚焦（第二层）**：社区视图内点节点 → 高亮 + 右抽屉阅读态同时出现；Esc 一步回全图并清空
+5. **类型筛选**：实体/主题/来源开关即时增减可见节点，可与社区聚焦叠加；时间筛选**不存在**（二期）
+6. **控制工具条**：左上角不再有常驻浮层；顶部工具条平时只露少量入口、半透明不挡图；点筛选弹出紧凑面板（社区+类型+边图例），弹出层打开时点空白只先收回弹出层；收起状态重启后保持（本机）
+7. **离线 HTML**：关系边 / 聚焦 / 类型筛选 / 工具条全部可用；点节点 = 阅读/高亮，**无提问入口**
+8. **自动化**：主仓库 JS 测试 / regression / typecheck / 引擎测试 / 双产物构建全绿
+
+## §4 风险
+
+| 风险 | 对策 |
+|---|---|
+| 边密集（217 条）+ 多色 → 全局噪音 | G1-1：全局低权重、聚焦才完整呈现；仅对立关系独立色（矛盾避 ENTITY 红）、顺承中性；双主题调试取证 |
+| 聚焦视图过滤与现有 focus/neighbors 概念混淆 | §1 已区分"镜头/叠加/过滤"三者；新增的是过滤层，不动现有两者；单测断言隐藏集 |
+| 社区点击语义变更破坏 4.5 选区回归 | 明确为"升级 D4.5-6"；保留选区态动作，只加"隐藏其余"；4.5 selection 测试须保持绿 |
+| 边 `type` 当前是置信度，不是关系类型；关系类型 / 置信度任一维可能缺失 | Phase 0.2 先定完整边契约；缺字段就在 build-graph-data.sh 与类型/测试补齐，再接 UI；不交付"仅颜色维"半成品 |
+| 工具条 / 弹出层在离线 HTML 与工作台样式漂移 | 引擎层统一实现，宿主只注入位置与 capabilities |
+
+## §5 实施结果：PRODUCT.md / ADR 同步
+
+阶段 4.6 已按本文档落地，实施后文档状态如下：
+
+1. **阶段编号**：已定 **4.6**（2026-06-14），PRODUCT.md §4 / §10 已登记为已完成
+2. **ADR 同步**：
+   - 已修订 **ADR-21 / D4.5-6**：社区交互从"选中高亮"升级为"聚焦视图（隐藏其余）"；左上角浮层图例 → 顶部控制工具条
+   - 已新增 **ADR-23**：关系边可视化采用"关系类型控制颜色、置信度控制虚实"
+   - 已在 **ADR-19** 注记"图谱增强检索"移交检索质量演进线，不占本批图谱候选池决策位
+3. **候选池更新**：PRODUCT.md「图谱演进候选池」已标注本批已落地项，并记录"图谱增强检索移交 ADR-19 线"
+
+> 备注（导出美图走外挂 Skill 的未来路线）：作者倾向美观/导出类用 pi-agent 可插拔 Skill 实现。需厘清——**工作台里图本身的实时观感属渲染引擎，Skill 改不了**；Skill 能做的是"吃图数据吐精致产物（PNG/SVG/独立 HTML）"。且 Skill 是独立进程，拿不到"工作台当前视角"（缩放/聚焦/钉位），"导出当前视角"要么退回导出全局，要么由工作台把视口状态喂给 Skill。本批不实现，记此以备远期。
+
+## Changelog
+
+- 2026-06-14 v4（实施完成同步）：阶段 4.6 已落地并通过验收；更新状态为已实施，§5 改为实施结果，记录 PRODUCT.md / ADR-19 / ADR-21 / ADR-23 / 候选池同步结果。
+- 2026-06-14 v3（计划审查修订）：修正 G1-1 数据事实——当前 edge `type` 是置信度而非关系类型；明确本批必须补齐关系类型 + 置信度双字段，不做"仅颜色维"降级；把 build-graph-data.sh 纳入必要实施面；统一 Esc 为一步回全图；补工具条弹出层与画布空白点击优先级。
+- 2026-06-14 v2（自审修订）：spark 后自我 review 补 6 处——G1-1 拆"颜色必做 / 虚实条件做"并补"全局低权重、聚焦才完整呈现"（找回脑暴洞察：关系边价值在局部不在全局）、矛盾色避开 ENTITY 红；G1-2 的 Esc 改"一步回全图"（去三级逐级）、补全局视图单击空白行为；G1-3 记工具条 vs 折叠取舍理由；§2 厘清离线 HTML 工具条挂入现有 offline-header、补实施顺序（G1-3/4 → G1-2 → G1-1）；验收剧本 1 与风险表同步。
+- 2026-06-14 v1：首版。来源：2026-06-14 spark 脑暴（候选池三处纠偏 + 按就绪度而非成本重排）。含 G1-1（关系边双维度克制编码）、G1-2（递进聚焦 + 手势契约，升级 D4.5-6）、G1-3（顶部控制工具条取代浮层）、G1-4（默认收起 + 半透明）、G1-5（双宿主分工）、实施面 / 验收剧本 / 风险 / PRODUCT.md 前置动作。