@joekytc/dsh-swarm 0.1.2 → 0.2.0

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

@@ -0,0 +1,384 @@
+# Paper UI V2 外壳对齐补完设计
+
+日期：2026-06-20
+状态：待作者审阅
+分支：`codex/paper-ui-v2-layout`
+
+## 背景
+
+Paper UI 基础迁移已经完成，旧的 6 phase goal-plan 也已经收口。但当前实现更像是“旧工作台套上暖纸皮肤”，距离 `paper-final-v2.html` 的布局和交互仍有明显差距。
+
+这份设计不是重开 Paper UI，也不是修改旧 goal-plan ledger，而是在当前 Paper 基础上做一个新的 **V2 外壳对齐补完包**。目标是把侧栏、主区、Composer、工具调用、右抽屉、图谱页外壳这些用户一眼能感知到的结构补齐。
+
+V2 原型参考：
+
+- `/Users/kangjiaqi/designs/llm-wiki-skill/bright/paper-final-v2.html`
+
+相关旧文档：
+
+- `docs/plans/2026-06-20-paper-ui-port-phased-plan.md`
+- `docs/plans/2026-06-20-paper-ui-port-progress.json`
+- `docs/spark/2026-06-20-paper-ui-port-design.md`
+
+旧文档仍保留为基础迁移记录；本文件只描述下一轮深度还原。
+
+## 目标
+
+把当前 Paper UI 从“约 80% 像 V2”推进到可以作为 V2 还原版验收的状态。
+
+具体目标：
+
+- 侧边栏结构按 V2 重排，笔记本和会话分开显示。
+- 侧栏顶部只保留折叠入口，不再常驻刷新和设置。
+- 侧栏左下角按 V2 放置底部入口：图谱活地图、设置、新建知识库。
+- Composer 变成更轻的单卡输入体验，发送按钮内嵌，不再单独占一整行。
+- 工具调用展示只突出当前动作，历史默认轻量收起。
+- 右抽屉打开时桌面端主区让位，输入框不被覆盖；小屏端覆盖显示。
+- 图谱页外壳修正工具条遮挡和布局拥挤问题。
+- 保留真实产品已有功能和状态逻辑。
+
+## 不做什么
+
+本次不做以下内容：
+
+- 不改图谱画布内部的 Sigma 节点、边、社区配色。
+- 不做跨库搜索或全文搜索后端。
+- 不重写后端。
+- 不搬 V2 原型里的 mock 数据。
+- 不把旧 goal-plan 的 progress ledger 继续翻状态。
+- 不为了像 V2 而删掉真实产品已有能力。
+
+## 已确认的产品决定
+
+1. 这次范围定义为 **V2 还原补完包**。
+2. 侧边栏改为 V2 结构：笔记本列表和会话列表独立显示。
+3. 会话不再嵌在当前知识库树下面。
+4. 侧栏底部保留图谱活地图、设置、新建知识库。
+5. 侧栏底部的“新建知识库”实际复用现在“添加现有库”的功能。
+6. 原来的空库“新建知识库”功能先不显示。
+7. 侧栏顶部只保留折叠按钮，不保留刷新和设置。
+8. 夜灯模式不在侧栏底部出现，主题切换继续放在 TopBar。
+9. 右抽屉桌面端打开时主区让位，小屏端覆盖。
+10. 工具调用只突出当前动作，历史轻量收起。
+11. 图谱画布内部视觉继续后置。
+
+## 总体布局
+
+页面继续保持四层结构：
+
+```text
+App
+├─ TopBar：全局操作
+├─ AppBody
+│  ├─ Sidebar：笔记本 / 会话 / 底部入口
+│  ├─ Main：对话或图谱
+│  └─ RightDrawer：阅读 / 图谱摘要 / 产物
+├─ AppearancePanel
+└─ SettingsPanel
+```
+
+### TopBar
+
+TopBar 继续承载全局操作：
+
+- 当前知识库信息
+- 对话 / 图谱状态
+- 搜索
+- 模型选择
+- 新对话
+- 主题切换
+- 外观偏好
+
+TopBar 不承载图谱专属操作，也不放侧栏折叠按钮。图谱重置、重构等操作仍留在图谱页内部。
+
+### Sidebar
+
+侧边栏改为三段：
+
+1. 顶部：品牌名 + 折叠按钮。
+2. 中间：笔记本列表、会话列表。
+3. 底部：图谱活地图、设置、新建知识库。
+
+侧栏顶部只保留折叠功能。刷新和设置不再作为顶部常驻按钮。
+
+笔记本列表只负责选库。会话列表只展示当前库会话。这样更接近 V2，也减少现在“知识库树里塞会话”的复杂感。
+
+底部入口规则：
+
+- “图谱活地图”：进入图谱视图。
+- “设置”：打开现有 SettingsPanel。
+- “新建知识库”：调用现有 AddExternalDialog，也就是现在“添加现有库”的功能，只改入口命名和视觉位置。
+
+折叠状态下，侧栏变成窄 rail。至少保留：
+
+- 展开侧栏
+- 当前库 / 笔记本
+- 对话
+- 图谱
+- 设置
+- 新建知识库
+
+刷新不作为折叠 rail 的核心常驻入口。
+
+### Main
+
+主区继续在对话和图谱之间切换。
+
+对话页的第一优先级是阅读消息和继续输入。输入区不能过高，不能把页面底部变成操作面板。
+
+图谱页的第一优先级是画布可读。工具条、搜索、控制区、图例要围绕画布，不遮盖画布，也不压缩主要内容。
+
+### RightDrawer
+
+桌面和宽屏下，右抽屉作为布局中的一列。打开时主区宽度减少，Composer 跟着收窄，不能被抽屉覆盖。
+
+小屏下，抽屉作为覆盖层显示，避免主区被压到不可用。
+
+抽屉现有能力继续保留：
+
+- resize
+- 全屏
+- 关闭
+- 产物 tab
+- wiki / graph reader / graph summary 内容
+
+## 组件设计
+
+### 侧边栏
+
+当前侧边栏的问题：
+
+- 顶部有折叠、刷新、设置三个按钮，视觉噪声高。
+- 底部是“新建知识库 / 添加现有库”，和 V2 不一致。
+- 会话嵌在知识库下面，结构偏工程化。
+
+目标形态：
+
+- 顶部只保留折叠。
+- 中部用“笔记本”和“会话”两个明确分区。
+- 底部形成固定操作区，接近 V2。
+- 当前选中库和当前会话都要有清晰高亮。
+- 外部库、默认库等 badge 继续保留，但视觉弱化，不抢主标题。
+
+### Composer
+
+当前 Composer 的问题：
+
+- 输入区整体高度过大。
+- “就绪”和“发送”单独占一行。
+- 导出按钮占据输入卡底部一整条，显得比输入本身更重。
+
+目标形态：
+
+- 输入框和发送按钮合成一个卡片。
+- 发送 / 停止按钮内嵌到输入卡右下角。
+- “就绪”状态不再常驻占位，只在生成中、错误、消化素材等状态需要时显示。
+- `@`、`/`、`⌘↵` 提示写入 placeholder；只有菜单、错误、消化素材等临时状态需要额外轻提示。
+- 导出入口变轻，放在输入卡下方的轻量工具区，不能压低输入框主体。
+- 拖拽消化和素材 chip 继续保留。
+
+### 工具调用展示
+
+当前工具调用的问题：
+
+- 历史工具摘要容易在对话里占据过多视觉空间。
+- 用户关注的是“现在正在做什么”，不是每次历史工具都扑脸展示。
+
+目标形态：
+
+- 运行中：显示一条清晰的当前动作，例如“正在读取 mamba.md”。
+- 完成后：默认收成轻量摘要，例如“已读取 2 个页面”。
+- 详情可展开，但不默认展开。
+- 错误和取消状态仍要明显可见。
+- 原有工具状态事件语义不删，只调整呈现层级。
+
+### 右抽屉
+
+当前右抽屉的问题：
+
+- 已经是布局列，但体验还没有达到 V2 的丝滑让位。
+- Composer 和主区在抽屉打开时需要更稳定地响应宽度变化。
+
+目标形态：
+
+- 桌面端打开抽屉时，主区自然变窄。
+- Composer 仍完整可输入、可发送。
+- 抽屉宽度调整时，主区跟随变化，不出现遮挡。
+- 小屏端使用覆盖式抽屉。
+- resize、全屏、关闭不回归。
+
+### 图谱页外壳
+
+当前图谱页的问题：
+
+- 工具条和控制区有遮挡、拥挤风险。
+- 图谱页外壳还没有完全变成 V2 的“活地图”感觉。
+
+目标形态：
+
+- 图谱工具条固定在画布上方的外壳区域，不覆盖画布。
+- 搜索框、重置布局、重构图谱等控件有稳定位置。
+- 图例和统计信息轻量显示，不抢画布。
+- 图谱页从侧栏底部“图谱活地图”进入时，命名和视觉一致。
+- Sigma 画布内部不改。
+
+## 阶段拆分
+
+### Phase A：侧栏 V2 重排
+
+目标：先把导航骨架对齐 V2。
+
+包含：
+
+- 顶部只保留折叠按钮。
+- 移除顶部刷新和设置常驻按钮。
+- 笔记本列表和会话列表分区显示。
+- 会话不再嵌套在知识库下面。
+- 底部入口改为图谱活地图、设置、新建知识库。
+- “新建知识库”调用现有添加现有库流程。
+- 折叠 rail 对齐新信息架构。
+
+验收：
+
+- 页面侧栏顶部只看到折叠入口。
+- 侧栏中部能清楚区分笔记本和会话。
+- 侧栏底部不出现“添加现有库”文案，只出现“新建知识库”。
+- 点击底部“新建知识库”打开现有添加现有库流程。
+- 点击底部“设置”打开设置。
+- 点击底部“图谱活地图”进入图谱视图。
+- 折叠和展开都可用。
+
+### Phase B：对话页 V2 补完
+
+目标：让对话页接近 V2 的阅读和输入体验。
+
+包含：
+
+- Composer 单卡内嵌发送按钮。
+- 弱化或移除常驻“就绪”行。
+- 导出入口轻量化，不再撑高输入区。
+- 工具调用改为当前动作优先，历史轻量收起。
+- 消息区节奏和空态跟 V2 对齐。
+
+验收：
+
+- 发送按钮在输入框内，不单独占一整行。
+- 输入区高度明显低于当前实现。
+- 空对话和已有对话都不出现底部操作过重的问题。
+- 运行工具时能看清当前动作。
+- 工具完成后历史默认不扑脸。
+- `@`、`/`、发送、停止、导出、拖拽消化不回归。
+
+### Phase C：右抽屉让位体验
+
+目标：把 V2 的抽屉丝滑感补齐。
+
+包含：
+
+- 桌面端抽屉打开时主区让位。
+- Composer 跟随主区宽度变化。
+- 抽屉 resize 时不遮挡输入区。
+- 小屏端抽屉覆盖显示。
+
+验收：
+
+- 1440 宽度打开抽屉，主区和输入框完整可见。
+- 拖动抽屉宽度时，主区没有被遮挡。
+- 1024 宽度仍可使用。
+- 768 宽度使用覆盖式抽屉，不把主区压坏。
+- 全屏、关闭、resize 不回归。
+
+### Phase D：图谱页外壳修正
+
+目标：修掉图谱工具条遮挡和外壳割裂。
+
+包含：
+
+- 图谱工具条重新排布，固定在画布上方的外壳区域。
+- 搜索、控制、统计、图例重新整理层级。
+- “图谱活地图”命名与入口一致。
+- 不改 Sigma 内部渲染。
+
+验收：
+
+- 图谱工具条不遮挡画布。
+- 图谱搜索和控制按钮位置稳定。
+- 图例不抢主要视觉。
+- 1440、1024、768 三个宽度无明显重叠。
+- 图谱重置布局、重构图谱、搜索等真实功能不回归。
+
+## 测试与验证
+
+每个阶段完成后至少验证：
+
+- `cd workbench/web && npm run typecheck`
+- `cd workbench/web && npm run build`
+- `cd workbench/web && npm test`
+- `cd workbench/web && npm run lint`
+
+视觉和交互要实际打开页面检查：
+
+- 1440 桌面宽度
+- 1024 中等宽度
+- 768 窄屏宽度
+
+关键手动流程：
+
+- 切库
+- 切会话
+- 折叠 / 展开侧栏
+- 底部图谱活地图入口
+- 底部设置入口
+- 底部新建知识库入口
+- 发送消息
+- `@` 引用
+- `/` 命令
+- 工具调用运行和完成
+- 打开 wiki 抽屉
+- 抽屉 resize / 全屏 / 关闭
+- 切图谱页
+- 图谱重置布局 / 重构图谱
+
+建议补充自动化覆盖：
+
+- Sidebar DOM 测试：底部按钮文案和行为、顶部按钮移除、折叠 rail。
+- Composer DOM 测试：发送按钮在输入卡内、状态行弱化、导出入口存在。
+- ToolStatus DOM 测试：运行态当前动作、完成态轻量摘要、展开详情。
+- Drawer layout 测试：桌面让位、小屏覆盖、resize 不遮挡。
+- Graph shell 测试：工具条不使用覆盖画布的定位，图例和画布区域独立。
+- Visual paper 脚本补一组 V2 shell 截图：sidebar、chat with drawer、graph 三个状态。
+
+## 风险与处理
+
+### 风险 1：侧栏重排影响切库 / 切会话
+
+处理：只改信息架构和呈现，不改后端会话模型。切库、切会话仍复用现有回调和状态。
+
+### 风险 2：Composer 轻量化时丢掉导出或批量消化入口
+
+处理：导出和批量消化必须保留，只调整视觉重量和位置。
+
+### 风险 3：工具调用轻量化导致信息不足
+
+处理：默认轻量，但保留展开详情。错误和取消状态不能隐藏。
+
+### 风险 4：抽屉让位在中等宽度下挤坏主区
+
+处理：设置桌面让位和小屏覆盖的明确断点；1024 作为重点验收宽度。
+
+### 风险 5：图谱页修外壳时误碰 Sigma 内部
+
+处理：实现计划里明确限制，不改 `packages/graph-engine` 的渲染样式。
+
+## 完成定义
+
+这次补完包完成时，用户应能直观看到：
+
+- 侧栏已经是 V2 的“笔记本 / 会话 / 底部入口”结构。
+- Composer 不再笨重。
+- 工具调用不再扑脸。
+- 抽屉打开不再遮挡或压坏输入区。
+- 图谱页工具条不再遮盖画布。
+- 整体从“换皮”变成“V2 外壳真正落地”。
+
+完成后再视情况把这份设计转成新的执行计划；不要继续往旧 goal-plan ledger 里追加任务。