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

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. 图谱画布内部视觉继续后置。

总体布局

页面继续保持四层结构：

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 里追加任务。