first
This commit is contained in:
@@ -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 里追加任务。
|
||||
Reference in New Issue
Block a user