@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/docs/spark/2026-06-19-sigma-global-graph-renderer-design.md

@@ -0,0 +1,360 @@
+# Sigma/Graphology Global Graph Renderer Design
+
+日期：2026-06-19
+状态：待用户复核
+当前分支：`codex/pr52-sigma-global-renderer-design`
+
+## 目的
+
+这份设计确定 Sigma/Graphology 如何正式接入 llm-wiki 的全局图谱视角。
+
+前一轮性能计划已经选择 Sigma/Graphology 作为未来全局大图渲染路线，但它只完成了路线选择和试验验证，没有切换生产图谱。当前任务不是继续做隐藏试验，也不是重新评估 Sigma、vis-network、聚合方案，而是把 Sigma/Graphology 作为首选正式全局路线接入的产品和工程边界定清楚，方便后续直接写实施计划。
+
+这里的 Phase 0 是“正式接入前的最后开工门槛”，不是重新开启选型。如果 Phase 0 发现 Sigma 存在硬阻塞，本实施方向应停止并记录 blocker，再另开技术路线决策；不要在同一份落地计划里临时转向 vis-network。
+
+本设计延续 2026-06-18 的大图体验结论：
+
+**全局图谱负责看结构，社区聚焦负责读内容。**
+
+## 设计结论
+
+采用“全局统一 Sigma，社区继续阅读”的首选正式路线。
+
+1. 所有全局视角统一使用 Sigma/Graphology，不按节点数量分成大小图两套全局渲染主路径。
+2. 全局视角只承担地图级结构浏览：社区分布、节点点位、关键标签、搜索命中、Pin、选中和高亮。
+3. 社区阅读、离线详情、内容阅读和富信息卡片继续使用现有 DOM/SVG 阅读路径，不在本次强行改成 Sigma。
+4. Sigma/Graphology 是首选正式全局路线，不是隐藏开关或实验入口；Phase 0 只决定是否允许进入正式接入，不在本计划内改选其它渲染路线。
+5. 旧 DOM/SVG 全局图不再作为用户可选的第二套主路径，只保留为小图异常兜底和社区/详情阅读能力。
+6. 如果 WebGL 不可用、Sigma 初始化失败或画布异常，系统按规模进入明确兜底：小图退回现有 DOM/SVG，全局大图进入最低可用的聚合安全视图，并记录可排查原因。
+
+一句话：
+
+**全局统一成一张高性能地图；社区继续承担阅读和理解。**
+
+## 为什么不选“大图才用 Sigma”
+
+只让大图走 Sigma、小图继续走当前全局 DOM/SVG，短期改动较小，但长期会留下两套全局图。
+
+同样是全局视角，搜索、高亮、Pin、选中、筛选、社区摘要、返回全局等行为就必须在两条渲染路径里持续对齐。后续任何体验调整都容易变成双份维护，也容易让小图和大图出现细节不一致。
+
+本次不以 MVP 思维处理，因此选择长期边界更清楚的方案：只要是全局视角，就统一走 Sigma/Graphology。
+
+## 为什么不把社区也改成 Sigma
+
+社区阅读不是单纯画更多点。社区内需要完整节点在场、核心节点卡片、摘要、阅读抽屉、节点内容、上下文动作和更高信息密度。
+
+Sigma/Graphology 适合承担全局地图的高性能绘制和视口交互；社区阅读更适合继续使用现有富交互 DOM/SVG 路径。把全局和社区一次性全改成 Sigma 会扩大风险，也会偏离已经确定的“全局看结构，社区读内容”。
+
+## 用户体验边界
+
+### 全局视角
+
+全局视角是地图，不是阅读界面。
+
+显示：
+
+- 节点点位。
+- 社区颜色和社区边界。
+- 少量关键节点标签。
+- 重要边或社区间骨架关系。
+- 搜索命中。
+- 当前选中对象。
+- Pin 提示。
+- 社区图例和筛选结果。
+
+降级或不显示：
+
+- 普通节点卡片。
+- 大段正文。
+- 全量标签。
+- 全量弱边。
+- 会导致大图卡顿的复杂阴影、动画和富组件。
+
+### 社区阅读和详情
+
+社区阅读继续承担内容理解。
+
+进入社区后：
+
+- 社区内节点完整在场。
+- 核心、选中、搜索命中和 Pin 节点可以升级为更高信息密度。
+- 继续使用现有阅读抽屉、节点详情和社区摘要能力。
+- 社区阅读路径不被 Sigma 的内部状态接管。
+
+## 责任边界
+
+### 图谱引擎负责什么
+
+`packages/graph-engine/` 继续作为图谱语义和产品规则的唯一来源。
+
+它负责：
+
+- 节点、边和社区身份。
+- 搜索结果。
+- 筛选状态。
+- Pin 状态。
+- 选择状态。
+- 社区聚焦。
+- 聚合标记。
+- 全局摘要、节点摘要、社区摘要和不可见对象提示。
+- 抽屉命令，例如进入社区、打开详情、显示对象、清除选择。
+- 大图预算，例如标签、边、卡片和聚合容器显示规则。
+
+### Sigma/Graphology 负责什么
+
+Sigma/Graphology 只负责全局地图绘制和视口层交互。
+
+它负责：
+
+- 全局节点点位绘制。
+- 全局边绘制。
+- 社区颜色和必要的视觉分组表达。
+- 搜索命中、选中、Pin 等状态的视觉表达。
+- 拖动、缩放和画布命中。
+- 把用户点到的渲染对象投射回图谱引擎能识别的对象。
+
+它不负责：
+
+- 决定搜索命中是谁。
+- 决定抽屉显示什么。
+- 决定进入哪个社区。
+- 保存真实图谱状态。
+- 成为新的业务数据源。
+
+### 适配层
+
+正式接入需要清晰的 Sigma 全局适配层，但这一层不从零搭建。`packages/graph-engine/src/render/adapter.ts` 已经有渲染器无关契约（`GraphRendererAdapterData` / `GraphRendererBehaviorContract`），Sigma 试验也已经消费过其中的语义状态，例如选择、搜索命中、Pin、社区和聚合行为。
+
+不过，试验代码仍直接遍历原始 `data.nodes` / `data.edges` 生成 Sigma 点线，因此不能把“数据出向”视为生产就绪。生产 Sigma 必须画适配层输出的受控渲染数据，尤其要使用图谱引擎已经算好的预算、过滤、聚合、标签可见性和语义状态；不能在 Sigma 路径里重新决定画哪些节点、边和标签。
+
+本次主要补两块：第一，把“数据出向”从试验可用推进到生产可用；第二，把 Sigma 的点击、悬停和视口事件转回图谱引擎命令（“命令入向”），以及渲染器生命周期和失败兜底。
+
+适配层必须遵守：
+
+- `GraphData` 不为了 Sigma 改形状。
+- Graphology 只保存渲染用图结构，不保存另一份真实业务状态。
+- 抽屉永远通过图谱引擎摘要结果渲染，不读取 Sigma 内部状态。
+- 如果未来更换渲染库，搜索、Pin、社区、抽屉和选择规则不需要重写。
+- 社区区域命中由图谱引擎或适配层根据节点位置、社区 hull / 聚合区域和空间索引计算；Sigma 只上报画布坐标或渲染对象 id，不自己决定“点到了哪个社区”。命中优先级保持为节点、聚合/社区区域、空白。
+
+## 交互规则
+
+### 点击节点
+
+点击全局节点时：
+
+- 全局视角不自动跳转。
+- 选中该节点。
+- 高亮该节点和少量直接相关节点。
+- 右侧打开节点轻量摘要。
+- 不自动进入社区。
+- 不自动打开完整阅读内容。
+
+用户在轻量摘要里选择“打开详情 / 阅读”后，进入所属社区并选中该节点。
+
+### 点击社区
+
+点击社区区域或社区图例时：
+
+- 全局视角不自动跳转。
+- 选中该社区。
+- 高亮该社区和少量跨社区关系。
+- 右侧打开社区摘要。
+- 不自动进入社区。
+
+用户点击“进入社区”后，才进入社区阅读路径。
+
+### 搜索
+
+搜索只改变当前视图的高亮、淡化、列表和摘要，不重排整张图。
+
+搜索命中很多时：
+
+- 命中节点保持可见提示。
+- Pin 节点保持可见提示。
+- 已选对象保持上下文。
+- 普通弱边和普通标签可以降级。
+
+### 筛选
+
+筛选不自动清空当前选择。
+
+如果当前选中对象被筛选排除：
+
+- 右侧抽屉保留该对象。
+- 明确提示它不在当前结果中。
+- 提供清除选择或显示该对象的动作。
+
+### Pin
+
+Pin 是持久标记，不等于当前选中。
+
+大图降级时，Pin 节点仍要尽量保留可见提示。Pin 可以影响重要性排序，但不能成为唯一排序规则。
+
+### 缩放和拖动
+
+缩放只改变信息密度，不自动切换到社区阅读。
+
+拖动和缩放过程中可以临时降级：
+
+- 隐藏普通标签。
+- 隐藏弱边。
+- 减少复杂视觉效果。
+
+交互停止后补回当前预算允许显示的信息。核心锚点、搜索命中、Pin 和选中对象不能在交互中突然消失。
+
+### 返回全局
+
+从社区返回全局后：
+
+- 正常情况下回到 Sigma 全局图。
+- 如果当前环境已判定 Sigma 不可用，则回到对应规模的兜底全局视图，不能再次尝试进入一个已知失败的 Sigma 实例。
+- 保留合理上下文，例如刚刚所在社区轻微高亮。
+- 不把用户带到用户可选的另一套全局主路径；兜底只在异常状态下自动发生。
+
+### 失败兜底
+
+如果 Sigma 无法启动（WebGL 不可用、初始化失败、画布异常）：
+
+- 按规模分层兜底，而不是一律退回 DOM/SVG：小图退回现有 DOM/SVG 全局图；大图退回最低可用的聚合安全视图。因为 DOM/SVG 在 10000 节点本就约 8836ms、36.8 FPS、近乎拖不动，把大图退给它等于把用户丢进一张已知卡死的图。
+- “小图 / 大图”的具体阈值由实施计划用历史基线和真实机器验证确定，初始建议用节点数、边数和社区规模共同判断，而不是只看节点数。
+- 大图聚合安全视图只保证不空白、不卡死、能说明当前图谱结构和下一步动作；它不是完整替代图谱。它只显示社区容器、少量骨架边、选中 / 搜索 / Pin 标记，以及右侧抽屉中的溢出列表入口。
+- 聚合安全视图下的可用动作限定为：查看社区摘要、查看搜索 / Pin / 选中对象列表、进入社区阅读、清除选择或重试 Sigma。节点级自由点选、完整边浏览、完整标签显示不在兜底目标内。
+- 用户要看到轻提示，说明当前处于“图谱安全显示”而不是正常高性能全局图；提示不能打断使用。
+- 用户既不看到空白死图，也不被丢进卡死的大图。
+- 系统记录失败原因，供后续排查。
+- 兜底不是用户主路径，不提供“新旧图谱切换”作为常规入口。这里的聚合降级只是兜底形态，不是第二套全局主产品。
+
+## 性能和验收标准
+
+正式接入不是“Sigma 能画出来”就算完成，而是全局图从小到大都统一、顺滑、可恢复、行为不变。
+
+收益锚点要先说清楚：Sigma 的主要价值不是伺候极端的 10000 节点，而是让数百到数千节点的常见知识库从明显卡顿变丝滑。当前 DOM/SVG 在 1000 节点已要约 900ms、5000 节点约 4615ms 首屏，Sigma 试验把它们压到约 146ms / 175ms。因此验收中心是“真实规模显著变快 + 大图不崩溃”；10000 节点是压力上界，只用来保证不崩，不是产品叙事中心，也不值得为它过度设计（例如为 90000 条弱边堆复杂边预算，而真实库根本到不了那个量级）。
+
+最低验收：
+
+1. 所有全局视角统一走 Sigma/Graphology。
+2. 社区阅读和详情继续使用现有阅读体验。
+3. 点击节点、点击社区、搜索、筛选、Pin、进入社区、返回全局、不可见对象提示语义保持一致。
+4. 1000 节点全局图接近无感。
+5. 5000 节点全局图拖动、缩放、搜索和抽屉打开明显流畅。
+6. 10000 节点全局图不能出现拖不动、缩放卡住、搜索迟迟不亮、抽屉慢开或画面大跳变。
+7. 大图拖动和缩放目标稳定在 45 FPS 以上。
+8. 10000 节点首次进入全局图时必须有明确加载状态，不能长时间空白。
+9. Sigma 初始化失败、WebGL 不可用或画布异常时能自动兜底。
+10. 现有图谱引擎测试、前端图谱行为测试和大图性能测试都必须通过。
+
+## 必测图谱形状
+
+后续实施计划必须跑完整 11 类图谱形状，而不是只复用早期 5 类试验结果。
+
+必须覆盖：
+
+1. 真实图谱快照代理。
+2. 1000 节点稀疏图。
+3. 1000 节点密集图。
+4. 5000 节点稀疏图。
+5. 5000 节点密集图。
+6. 10000 节点聚合图。
+7. 10000 节点高边图。
+8. 超大社区。
+9. 很多小社区。
+10. 很多搜索命中。
+11. 很多 Pin 节点。
+
+每类至少验证：
+
+- 首次渲染。
+- 拖动。
+- 缩放。
+- 搜索高亮。
+- 点选节点。
+- 点选社区或聚合容器。
+- 打开抽屉。
+- 进入社区。
+- 返回全局。
+- 重复交互后的内存和稳定性。
+
+## 实施前置门禁（Phase 0）
+
+写任何生产渲染代码之前，必须先过一道“允许开工”的性能门禁。当前选择 Sigma 的方向成立，但接入前的证据还不够硬：
+
+- 现有 Sigma 试验数据（10000 节点约 289ms、60.9 FPS）是“历史隔离基线”，由第一版未硬化的试验脚本产出。决策文档自己也要求“锁定 Sigma 前必须重跑硬化试验”。
+- 关键缺口：5000 / 10000 节点的重复交互内存测试此前是 not run，只有 1000 节点测过内存增长——大图反复交互是否泄漏，目前没有任何数据。
+- 试验用的是极简 drawer 和简单视觉更新模型，不是 workbench 真实的抽屉 / 阅读器 / overlay 负载。
+
+因此 Phase 0 分两层，不把所有发布回归都压到开工前。
+
+开工门禁必须完成：
+
+1. 先升级 harness 判定标准，确保它真的能按本文档验收，而不是继续用过低阈值或极简 drawer 得出虚假通过。
+2. 重跑完整 11 类形状的核心动作：首次渲染、拖动、缩放、搜索高亮、点选节点、点选社区/聚合、打开抽屉。
+3. 补齐大图（5000 / 10000）重复交互内存周期。
+4. 补一个接近真实 drawer / overlay 负载的延迟测试。这里不要求先完成生产集成；可以用代表性负载模拟，但必须比早期极简 drawer 更接近 workbench。
+
+发布回归必须完成：
+
+1. 进入社区。
+2. 返回全局。
+3. 失败兜底。
+4. 小图行为回归。
+5. 完整 11 类形状的端到端循环。
+
+开工门禁任一项不达标即停下记录 blocker。若 blocker 指向 Sigma 方案本身不可行，停止本实施方向，另开技术路线决策；不要在同一份落地计划里临时改接 vis-network。
+
+开工门禁不通过，下面的生产接入动作不启动；发布回归不通过，不能宣布正式接入完成。
+
+## 工程落点
+
+后续实施计划应围绕以下落点展开（按依赖排序，第 1 条是真正的硬骨头）：
+
+1. 先解耦协调层对 DOM/SVG 的隐性依赖。此前的渲染器协调层拆分（已合入 main，对应 `graph-renderer-coordination-split` 计划）已把“决策”（`controller.ts`）和“画图”（`render-pipeline.ts`）分到不同文件，但 controller 仍有多处直接操作具体 DOM（如 `context.dom.nodeElements.get(id)?.focus()`、`.classList.add("is-dragging")`；见 `render-context.ts` 里 `nodeElements: Map<…, HTMLButtonElement>`、`edgeElements: Map<…, SVGPathElement>`）。这些假设“每节点是可单独 focus / 加 class 的 DOM、每边是 SVG path”，对 Sigma 的 WebGL 画布全不成立。必须先把已知 DOM 附着点限定在当前渲染层命令里（如 `setNodeFocused` / `setNodeDragging` / `setSearchState`），不要把它扩成泛化渲染框架。
+2. 拆清 renderer root、pipeline、controls 的边界。当前生产入口会固定创建 DOM/SVG 根、节点按钮、SVG 边、搜索框、图例和小地图；只抽象 controller 还不够。实施计划需要明确哪些 UI 控件仍由 DOM 外壳承载，哪些图形内容交给 Sigma canvas，哪些能力保留在社区/详情 DOM/SVG 路径。
+3. 复用已有的 `render/adapter.ts` 契约，但要把“数据出向”补成生产可用：Sigma 画适配层输出的受控渲染数据，不直接遍历原始全量 `GraphData` 自己决定预算。
+4. 补“命令入向”：把 Sigma 的点击、悬停、视口事件转回图谱引擎命令，不在 Sigma 回调里重算语义。
+5. 把现有试验用 Sigma 代码收敛成生产路径，而不是直接复制测试 harness。
+6. 明确全局 Sigma 与社区 DOM/SVG 的路由点。当前 `createGraphFacade` 只创建一个 renderer，`focusCommunity` 只是让同一个 renderer 重新聚焦；正式接入必须决定是双 renderer 切换、单 facade 内部切换，还是 renderer host 管理两种 view，并写清共享状态、销毁、回调、返回全局和兜底如何走。
+7. 保持现有 workbench 的 `GraphPanel` 对外能力不大改：数据加载、Pin 持久化、选择回调、打开详情、可见状态通知继续通过当前边界通信。复杂度定位要摆正——真正动手术的是 `graph-engine/render` 和 facade 内部，不是 workbench/GraphPanel；后者只调 facade 高层 API，本就不碰渲染细节。
+8. 把 Graphology 和 Sigma 从试验依赖提升为正式运行依赖时，要明确包边界和构建产物影响。
+9. 给 WebGL/Sigma 初始化失败增加可测试兜底路径（分层方案见“失败兜底”）。
+10. 加一个开发期内部开关（env / config 级，不暴露为用户功能）用于新旧渲染对比与快速回退。它默认不进入正式用户路径；如果未来要作为线上应急开关，必须另行写明触发条件、谁能开启、用户会看到什么、何时关闭。它和“不给用户新旧切换按钮”不矛盾，一个是开发/运维工具，一个是产品形态。
+11. 把性能 harness 从“试验记录”升级为正式验收门禁（即 Phase 0 门禁）。
+
+## 不在本次范围
+
+本次不包含：
+
+- 在本实施计划内重新评估或改接 vis-network。若 Phase 0 发现 Sigma 硬阻塞，应停止并另开技术路线决策。
+- 做聚合方案作为第二套全局主产品（聚合仅作为大图失败兜底的降级形态，见“失败兜底”，不作为可选主产品）。
+- 把社区阅读也改成 Sigma。
+- 新增旧图/新图用户切换按钮（开发期内部对比开关不属此列，见“工程落点”第 10 条）。
+- 新增 Agent 提问入口。
+- 新增边点击关系详情。
+- 移动端专项体验。
+- 桌面壳专项实现。
+- 完整键盘漫游。
+- 类型、来源、时间等多套备用组织视角。
+
+## 残余风险
+
+1. Sigma 在生产环境和试验 harness 中的表现可能不同，因此实施前必须通过开工门禁，发布前必须完成完整 11 类形状回归。
+2. WebGL 在不同电脑和未来桌面壳里的可用性不同，因此兜底路径必须是真实可测的。
+3. 全局统一 Sigma 会触碰小图全局体验，因此小图行为回归也必须测，不能只测大图。
+4. 如果适配层边界不够硬，后续容易把搜索、选择、抽屉逻辑写进 Sigma 回调，导致返工。
+5. controller、renderer root、pipeline 和 controls 现仍有 DOM/SVG 假设，若不先收敛成清晰渲染边界就接 Sigma，会在回调里重造一套交互附着，造成双份维护——这是本次最大的隐性工作量。
+6. 大图聚合安全视图必须严格保持兜底定位；一旦把它扩成完整可选图谱产品，就会重新引入第二套全局路线。
+
+## 后续动作
+
+用户复核通过后，再把这份设计转换成实施计划。
+
+实施计划应按阶段推进：
+
+1. 先过 Phase 0 开工门禁（升级 harness 判定标准、重跑核心动作、补大图内存周期、补代表性 drawer / overlay 负载）；不达标即停，不进入生产接入。
+2. 解耦 controller、renderer root、pipeline 和 controls 对 DOM/SVG 的隐性依赖，把已知交互附着收敛成渲染器边界命令。
+3. 复用 adapter.ts，把 Sigma 数据出向补到生产可用，并补齐命令入向。
+4. 明确全局 Sigma 与社区 DOM/SVG 的路由点、共享状态、销毁、回调、返回全局和兜底。
+5. 落地生产级 Sigma 全局路径和分层兜底边界。
+6. 补齐交互语义和抽屉联动。
+7. 全程用 11 类形状持续回归，发布前完成完整端到端循环。
+8. 最后把旧 DOM/SVG 从全局主路径移除；它仍可作为小图异常兜底、社区阅读和详情能力保留并测试。

package/skills/llm-wiki-skill/docs/spark/2026-06-20-paper-ui-port-design.md

@@ -0,0 +1,162 @@
+# Paper 视觉 + 布局 移植设计（图谱后置）
+
+日期：2026-06-20
+状态：已转执行计划（被 plan 的评审修订更新）
+当前分支：`feat/paper-ui`
+
+> **执行以 plan 为准**：本 spec 是设计意图；几处实现细节已被 `docs/plans/2026-06-20-paper-ui-port-phased-plan.md` 的 plan-eng-review + Codex 修订**取代**——①不引入 `.pw-*` 并行类，就地演进现有 `.msg-*/.chat-*` 等类；②强调色用 `data-accent` 预设而非行内变量；③`ModelSelector` 组件不存在，需新建（复用 SettingsPanel 的 config 路径）；④TopBar 不显示「篇数」（`KnowledgeBaseInfo` 无此字段）；⑤搜索 ⌘K 做客户端真搜索；⑥PRODUCT.md 对齐提前到实现第一步。以 plan 为实现真相。
+
+## 目的
+
+把已定稿的 Paper 设计原型（`/Users/kangjiaqi/designs/llm-wiki-skill/bright/paper-final-v2.html`，独立 design 仓库）的**视觉语言 + 布局**移植并复刻进 `workbench/web`，作为产品的新默认外观。
+
+这份文档只确定移植的产品与工程边界，方便后续直接写实施计划。它**不**重新评估视觉方向（方向已通过 baoyu-design 多轮迭代锁定），**不**包含图谱画布内部视觉（明确后置），**不**做 MVP 取舍（除图谱外尽量一步到位）。
+
+设计原型与真实 app **同组件架构、同「CSS 变量 + 语义类名」范式**——原型本就是照 workbench 真实结构画的（同名组件 ChatPanel / Sidebar / Composer / ToolStatus / RightDrawer；真实 app 没有 ModelSelector，需要新建 TopBar 模型选择控件并复用 SettingsPanel 的配置路径）。因此本次是「换皮 + 按 v2 重排布局」，不是重写业务逻辑。
+
+## 设计结论
+
+1. **以 v2 的视觉 + 布局为准做像素级复刻**，而不是「v2 视觉套真实结构」。引入 v2 的统一顶栏、药丸 Tab、气泡对话、单卡 Composer、右抽屉阅读视觉、外观调参面板。
+2. **默认浅色暖纸主题**（真实 app 现在默认 dark，本次改默认 light）；夜灯（暖深色）一键切换保留。
+3. **Tweaks 外观调参做成真实用户偏好**：纸张质感 / 强调色 / 用户气泡 / 手写体点缀 / 密度，随时切换、localStorage 持久化，零后端改动。
+4. **真实 app 已有但 v2 没有的功能全部保留并 Paper 化**：导出、批量消化、产物 Artifacts、素材消化 input-chip、拖拽消化、抽屉 resize/tab/全屏、批量消化面板等。
+5. **图谱后置**：本次只把图谱 Tab 入口 / 工具条 / 图例 Paper 化到与整体不突兀；**图谱画布内部（Sigma 渲染配色）不动**。图谱活地图 Paper 化作为独立后续任务（见末节）。
+6. **未实现的功能留 UI + 接口，后期接真功能**，不在本次强行做后端。
+
+一句话：**v2 的样子，真实的功能，图谱留到下一程。**
+
+## 为什么引入统一 TopBar 是最优解，而不是沿用 statusbar
+
+v2 的布局里，模型选择器、新对话、主题切换、外观调参、搜索这些控件是**横跨「对话」和「图谱」两个视图共享的一条顶栏**，位于 Tab 之上。
+
+真实 app 现在没有顶栏：知识库信息分散在 Sidebar（库列表）和每个视图各自的 statusbar（`ChatPanel` 顶部有一条 `.statusbar` 显示库名 + 模型 pill；`GraphPanel` 另有自己的头部）。其后果是**主题切换按钮被复制传进 ChatPanel 和 GraphPanel 两处**（`App.tsx` 里 `onToggleTheme` 分别传给两个面板）。
+
+引入一条**共享 TopBar** 不只是为了像 v2，它本身是更干净的架构：
+
+- 跨视图共享的控件（模型、新对话、主题、外观、搜索）只需要在一处声明，消除当前的双份传递与潜在不一致。
+- 视图切换（对话/图谱）只切 Tab 下面的主区，顶栏稳定不动，符合「顶栏是全局控件、Tab 是视图、主区是内容」的清晰分层。
+- `ChatPanel` 的 `.statusbar` 与 `GraphPanel` 的头部职责被上提，两个面板回归「只渲染各自内容」，边界更单一。
+
+因此 TopBar 是「顺手把结构理顺」，不是为了好看的妥协。**采用。**
+
+## 用户拍板的具体决策（硬约束）
+
+- **去掉**顶栏左侧知识库头里的「模型名 + 下拉」。左侧只保留：书本图标 + 库名 + origin/valid 标记，纯展示，不可点、无 chevron；不显示篇数（`KnowledgeBaseInfo` 无此字段）。模型展示与切换只在右侧 TopBar 模型控件，控件需新建并复用 SettingsPanel 的 `config.modelRoles.main` 读写路径。
+- **去掉**侧栏左下角的「夜灯模式」项（与右上角主题切换功能重合）。主题切换只保留在右上角顶栏。
+- **默认主题 = 浅色暖纸**。
+- **主页凸显三个现有功能**：导出（HTML/PDF/PPTX…）、搜索 ⌘K、批量消化。
+- **搜索 ⌘K**：本次做当前库页面引用 metadata 的本地真搜索，数据来自 App/TopBar 级 refs cache；真实跨库 / 全文搜索后端拆为子任务，不在本次扩 scope。
+- 其余 v2 元素**全部保留复刻**。
+
+## 范围
+
+### 本次做
+
+- 全局 Paper token 层（浅纸 + 夜灯）映射到现有 `--app-*` 与 shadcn 变量。
+- 新 TopBar 组件 + 移除/上提原 statusbar 控件。
+- Sidebar Paper 化（去夜灯项）。
+- 对话区：扁平消息 → 气泡；工具状态暖化；Composer 单卡化；概念链接 / 荧光笔样式。
+- RightDrawer 阅读视觉 Paper 化（保留 resize/tab/全屏）。
+- 外观偏好系统（`lib/appearance.ts` + `AppearancePanel`）+ localStorage 持久化。
+- 导出 / 批量消化入口凸显并 Paper 化；搜索 ⌘K 做当前库 refs 本地过滤。
+- 图谱 Tab 外壳 / 工具条 / 图例 Paper 化到不突兀。
+
+### 本次不做（后续任务）
+
+- 图谱**画布内部**视觉（Sigma 节点 / 社区配色，在 `packages/graph-engine` 的 `render/render-styles.ts`）。
+- 真实跨库 / 全文搜索后端。
+- 任何与外观无关的后端改动。
+
+## 布局骨架（以 v2 为准）
+
+```
+app-shell（竖向 flex）
+├─ TopBar（新增）
+│   ├─ 左：知识库头 = 书本图标 + 库名 + origin/valid（纯展示，不显示模型名 / 不下拉 / 不显示篇数）
+│   └─ 右：搜索⌘K · 模型选择器(新建) · 新对话 · 主题切换 · 外观齿轮(Tweaks)
+├─ body（横向 flex）
+│   ├─ Sidebar：笔记本列表 + 会话列表 + footer(图谱活地图 · 设置)【去「夜灯模式」】
+│   ├─ Main：药丸 Tab(对话 / 图谱) + 对话视图 ｜ 图谱视图
+│   └─ RightDrawer：阅读抽屉（节点 / wiki / 产物，保留 resize / tab / 全屏）
+├─ AppearancePanel（右上齿轮触发的 Tweaks 浮层，右上角展开）
+├─ SettingsPanel（侧栏「设置」→ 现有配置模态，沿用）
+└─ BatchDigestPanel（沿用，Paper 化）
+```
+
+落地分工（避免功能重合）：
+
+- **右上角齿轮 = 外观调参（AppearancePanel）**：纸张 / 配色 / 气泡 / 手写 / 密度 / 主题。
+- **侧栏「设置」= 现有 SettingsPanel 配置模态**（模型凭证、库登记等），不变。
+
+## 样式与 token 策略
+
+1. **Paper token 层**：把 v2 的 `:root` / `[data-theme="light"]` / `[data-theme="dark"]` 暖纸 / 夜灯变量，映射到 `workbench/web/src/index.css` 现有的 `--app-*` 与 shadcn 变量（沿用 design 仓库 `bright/paper-theme.css` 的映射思路，但**补全 v2 实际用到、`paper-theme.css` 漏掉的**：社区色 `--comm-*`、纸张层 `--paper-glow / --paper-vignette / --paper-mottle / --paper-grain`、`--dot`、暖阴影 `--shadow / --shadow-lg`）。
+2. **组件样式层**：不引入 `.pw-*` 并行层；把现有 `.msg-*` / `.chat-*` / `.tool-*` / `.drawer-*` 等组件类就地演进为 Paper 外观。真实独有组件（导出栏、批量面板、抽屉 resize 把手等）保留既有类并 Paper 化对齐。
+3. **字体**：`index.html` 引入 Plus Jakarta Sans（正文）+ Caveat（手写点缀）+ JetBrains Mono（路径 / 代码）。注意 CJK：Latin 在前、CJK 系统字体兜底，CJK 正文 line-height 放大。
+4. **data 属性**：`documentElement` 上 `data-theme`（已有）+ 新增 `data-paper` / `data-userbubble` / `data-hand` / `data-density` / `data-accent`；强调色由 CSS 里的 `data-accent` 预设统一驱动（`--accent` / `--accent-deep` / `--accent-soft`），不用行内 JS 变量。
+
+token 替换只换「颜色 / 字体」，达不到复刻；真正复刻需要组件级结构改动（气泡、单卡 Composer、药丸 Tab、摘要卡去左竖条等），本设计的组件清单即覆盖这些。
+
+## 外观偏好（Tweaks = 真实功能）
+
+- 新 `workbench/web/src/lib/appearance.ts`：
+  - `AppearancePrefs` 类型：`{ theme, paper, accent, userbubble, hand, density }`。
+  - 取值：`theme: light|dark`；`paper: clean|grid|laid`；`accent: terracotta|clay|amber|rose`；`userbubble: soft|solid`；`hand: on|off`；`density: cozy|compact`。
+  - 读写 localStorage（键前缀 `llm-wiki-agent-appearance-*`，SSR-safe，`typeof window` 守卫），并提供 `applyAppearance(prefs)`：把上述写成 `documentElement` 的 data 属性；强调色通过 `data-accent` 预设生效。
+  - 复用现有 `theme` 机制：`theme` 仍走现有 `THEME_STORAGE_KEY` 与 `dataset.theme` + `.dark` class，但**默认值改为 `light`**；其余外观项新增。
+- 新 `AppearancePanel` 组件：复刻 v2 `TweaksPanel`（分段控件 + 配色色板），右上齿轮 popover，右上角展开，带显隐。
+- 状态归属：偏好状态由 `App` 持有（与现有 `theme` 并列），通过一个 effect 应用到 `documentElement`（仿现有 theme effect），`AppearancePanel` 受控。
+- **默认值**：`theme=light` · `paper=clean` · `accent=terracotta` · `userbubble=soft` · `hand=on` · `density=cozy`。
+
+## 组件改造清单
+
+| 组件 / 文件 | 改造 | 备注 |
+|---|---|---|
+| `App.tsx` | 新增 TopBar 挂载、外观偏好状态 + effect、移除分散的 `onToggleTheme` 双传 | 顶栏控件回流到此处统一编排 |
+| **TopBar（新）** | 左 kb 头（静态，不显示模型名 / 不下拉 / 不显示篇数）+ 右控件组（搜索⌘K 当前库 refs 本地搜索、模型选择器[新建]、新对话、主题、外观齿轮） | 共享于对话 / 图谱两视图 |
+| `ChatPanel.tsx` | 移除 `.statusbar`（控件上提 TopBar）；扁平消息 → 气泡（就地演进 `.msg-row/.msg-avatar/.msg-body/.msg-content` 等类，用户 soft/solid 两态、头像区分）；导出栏 Paper 化并凸显；保留 input-chip / 拖拽消化 | 最大块 |
+| `MarkdownView.tsx` | 概念链接补 `.at` Paper 下划线样式（点击开抽屉逻辑已存在）；荧光笔 `.hl` | 功能已在，补样式 |
+| `ToolStatusRunway.tsx` / `ToolHistorySummary.tsx` | 暖化对齐 v2（脉冲竖条 + 微光轨道 → 折叠 chips），保留真实信息量 | runway 比 v2 更全，套皮不减信息 |
+| Composer（在 `ChatPanel` 内） | 分离式 → v2 单卡（内嵌发送 + focus 暖光环 + 占位符随 `data-hand` 切手写 / 正文）；`RefMenu` / `CommandMenu` Paper 化 | |
+| `Sidebar.tsx` | 笔记本 / 会话 / footer(图谱 · 设置) Paper 化；**移除「夜灯模式」项**；保留折叠 | |
+| `RightDrawer.tsx` + 摘要 / 节点视图 | v2 阅读视觉：摘要改「带标签柔卡」（**去掉左竖条 AI slop**）、meta chip 带社区圆点、关联列表、操作按钮；保留 resize / tab / 全屏 | |
+| `TopBar` 模型选择器 | 新建控件，Paper 化（分组、打勾、pop 动画），复用 SettingsPanel 的 config 读写路径 | 真实 app 无现成 ModelSelector |
+| `BatchDigestPanel.tsx` | Paper 化；入口上浮凸显 | |
+| `GraphPanel.tsx` | 仅 Tab 入口 / 工具条 / 图例 Paper 化；画布内部不动 | 后置任务的边界 |
+| **`lib/appearance.ts`（新）** / **`AppearancePanel`（新）** | 见上节 | |
+
+## 持久化
+
+- 外观偏好与现有 UI 偏好一致走 **localStorage**（现有：`llm-wiki-agent-theme` / sidebar-collapsed / drawer-width / main-view）。
+- 不写后端、不进 `~/.llm-wiki-agent/`。
+
+## 测试 / 验收
+
+- `npm run build`（含 `tsc -b`）、`npm run typecheck`、现有 `npm test`（node:test / vitest）全绿。
+- **真实功能不回归**：消息流式（SSE）、`@` 引用 / `/` 命令、导出、批量消化、产物抽屉、抽屉 resize/tab/全屏、切库 / 切对话、概念链接开抽屉。
+- **视觉回归**：2 主题 × 3 纸张 × 4 配色 × 2 气泡 × 2 密度 × 手写开关，逐项截图核对；浅 / 夜灯首屏。
+- 过一遍主流程（手动或 Playwright）。
+
+## 落地节奏
+
+一步到位，单分支 `feat/paper-ui`，内部按逻辑单元分 commit：
+
+1. Paper token 层（`index.css` 变量 + 字体）
+2. 外观偏好系统（`lib/appearance.ts` + `AppearancePanel` + App 接线）
+3. TopBar 新增 + statusbar 控件上提
+4. Sidebar Paper 化（去夜灯项）
+5. 对话区气泡化 + 工具状态暖化
+6. Composer 单卡化 + 菜单 / 导出 Paper 化
+7. RightDrawer 阅读视觉
+8. 图谱 Tab 外壳 Paper 化 + 收尾回归
+
+## 后续任务（不在本次，记录在案）
+
+1. **图谱活地图 Paper 化**：把社区 / 节点配色对齐暖纸调，配色在 `packages/graph-engine` 的 `render/render-styles.ts`（Sigma 渲染），与图谱体验一起规划，不在 CSS 层。
+2. **真实跨库 / 全文搜索后端**：本次只做当前库 refs metadata 的本地搜索；跨库、全文内容索引、后端搜索 API 作为独立子任务。
+
+## 风险 / 边界
+
+- 引入 TopBar 涉及 `App.tsx` 与 `ChatPanel` / `GraphPanel` 的控件回流，是真实重构；已确认接受（理由见上）。属可控范围，因「不以 MVP 处理」而值得一次做对。
+- v2 原型用极简 `tinyMd` 渲染抽屉正文，`## 标题` / `- 列表` 当纯文本；真实 app 用 `MarkdownView`（正常 markdown），移植后此问题不存在。
+- 强调色 `data-accent` 预设需要同时覆盖浅 / 夜灯；用 `color-mix(... var(--card))` 推导 `--accent-soft` 保证两主题都成立。