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

阶段 4.6 设计文档：图谱演进第一批（看清关系 + 层层聚焦 + 控制工具条）

状态：已实施并通过验收 日期：2026-06-14 来源：PRODUCT.md「图谱演进候选池」（2026-06-13 沉淀）的首次落地；经 2026-06-14 spark 脑暴收敛。 与 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 读取 <!-- confidence: ... -->，build-graph-data.sh:261 输出 {id, from, to, type}
• 当前类型定义也把边 type 定义成 Confidence：types.ts:56
• 当前渲染已有置信度 class / 虚线基础：static-renderer.ts:940、static-renderer.ts:1682
• 关系词汇表：.wiki-schema.md（schema-template.md:178，实现 / 依赖 / 对比 / 矛盾 / 衍生）
• 置信度体系：SKILL.md:384 起 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
• neighbors 选区全链路已通（App / GraphSelection / GraphPanel / RightDrawer）
• 密度模式 point-plus-focus、model/visibility.ts::applyFocusMode、Community 全套类型均在
• ❗ 区分：现有 focusNode 是"镜头对准某点"，neighbors 是"全局图上叠加高亮"；本批新增的是"隐藏非聚焦集、只渲染聚焦子集"的视图过滤层

类型筛选：节点 type（entities/topics/sources）建库即分好（build-graph-data.sh:89），纯前端开关。时间筛选（最近 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 前置动作。