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