mesalogo
625182c3dc
Persist conversation pins across restarts and show pinned conversations first, including older history. Anchor action menus above the list without shifting neighboring rows, with keyboard dismissal and sidebar-close cleanup. Add schema 36 migration, focused regression coverage, and feature documentation. File-level staging also includes existing workbar styles and browser contract adjustments in shared files. Validation: 145 backend tests and 237 App tests passed; typecheck and lint passed. Full test run timed out with Runtime and Agent package failures; native Electron visual validation remains pending. Release note: 会话菜单新增置顶和取消置顶，重启后仍保留；操作菜单现在悬浮显示，不再挤动下方会话。
253 lines
13 KiB
Markdown
253 lines
13 KiB
Markdown
# 应用导航与系统工具入口 UI 设计
|
||
|
||
## 文档信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 状态 | 设计中 |
|
||
| 版本 | 0.2 |
|
||
| 日期 | 2026-09-08 |
|
||
| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
|
||
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
|
||
| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
|
||
|
||
本文定义入口、设置和轻量资源监控界面。文件、终端和浏览器的内容布局继续遵守助手工作栏
|
||
文档。
|
||
|
||
## 1. 侧栏信息架构
|
||
|
||
```text
|
||
品牌
|
||
项目选择
|
||
项目活动汇总（仅有活动时显示）
|
||
新对话
|
||
搜索
|
||
|
||
当前对话
|
||
魔法笔记 3
|
||
知识库
|
||
智能心跳 1
|
||
运行记录
|
||
|
||
最近对话
|
||
...
|
||
|
||
────────────────────────
|
||
[文件] [终端] [浏览器] [资源] [设置]
|
||
```
|
||
|
||
“当前对话”和“运行记录”属于固定系统入口。三个内置应用位于二者之间。侧栏底部不再显示
|
||
“本地工作区”和 `platform · arch`；排障信息移至关于或诊断页面。
|
||
|
||
## 2. 底部系统工具栏
|
||
|
||
底部使用连续平整表面和顶部分隔线，不做成账户卡片或嵌套卡片。按钮顺序固定：
|
||
|
||
| 位置 | 图标 | 可见工具提示 | 点击结果 |
|
||
| --- | --- | --- | --- |
|
||
| 1 | `FolderOpen` | 文件 | 聚焦不可关闭的工作区面板 |
|
||
| 2 | `SquareTerminal` | 终端 | 打开或聚焦当前执行空间终端 |
|
||
| 3 | `Globe` | 浏览器 | 聚焦当前 Conversation 的匹配浏览器实例 |
|
||
| 4 | `Activity` | 资源监控 | 打开或聚焦本机资源监控面板 |
|
||
| 末位 | `Settings` | 设置 | 打开设置页面 |
|
||
|
||
图标使用项目现有 Lucide 库。每个按钮采用统一的 `34px × 34px` 点击区域，内部图标建议
|
||
`16px`。工具栏使用 `8px` 内边距和 `4px` 间隔；设置按钮通过自动空白靠右，不添加第二条
|
||
视觉分隔线。
|
||
|
||
### 2.1 状态
|
||
|
||
- 默认：透明背景，图标使用次级文字色。
|
||
- 悬停：使用弱表面色，不能强于当前选中状态。
|
||
- 选中：使用强调选中背景，并提高图标对比度。
|
||
- 键盘焦点：显示统一焦点环，不能被侧栏边缘裁切。
|
||
- 处理中：创建或激活请求未完成时暂时禁用对应按钮，保留尺寸并提供进行中名称。
|
||
- 徽标：只用于等待处理、错误或活动状态，不显示无意义的常驻绿色圆点。
|
||
|
||
选中状态表达“对应工作栏面板正在显示”，不表达功能已安装或权限已授予。
|
||
|
||
## 3. 主导航应用区
|
||
|
||
应用入口沿用现有 `nav-item` 行，不使用应用卡片。图标、名称和徽标保持单行：
|
||
|
||
```text
|
||
[图标] 魔法笔记 3
|
||
[图标] 知识库
|
||
[图标] 智能心跳 1
|
||
```
|
||
|
||
隐藏某个应用后，其余应用向上补位。运行记录始终位于最后一个可见应用之后，不因应用显隐
|
||
改变样式或归类为工具。
|
||
|
||
设置页打开期间，主侧栏显示最后一次成功保存的导航状态。Switch 更新成功后导航立即变化，
|
||
失败时保持原导航。
|
||
|
||
## 4. 应用与工具设置
|
||
|
||
设置中心新增“应用与工具”分类，采用 `standard` PageShell：
|
||
|
||
```text
|
||
应用与工具
|
||
管理主导航中的应用。系统工具由 GoodBuddy 提供并固定在侧栏底部。
|
||
|
||
应用
|
||
魔法笔记 笔记、待办和评论 [显示在侧边栏 开]
|
||
知识库 管理和检索知识 [显示在侧边栏 开]
|
||
智能心跳 查看计划、建议和运行历史 [显示在侧边栏 开]
|
||
|
||
系统工具
|
||
文件 打开当前工作区 内置
|
||
终端 进入当前执行空间 内置
|
||
浏览器 打开 GoodBuddy 受控浏览器 内置
|
||
资源监控 查看本机 CPU、内存和磁盘 IO 内置
|
||
|
||
系统入口
|
||
当前对话、运行记录和设置位置固定，不参与上述配置。
|
||
```
|
||
|
||
应用显隐使用共享 Switch，标签必须是“显示在侧边栏”，不能缩写为“启用”。切换时立即保存，
|
||
请求期间禁用三个应用显隐 Switch；失败后恢复原值，并在对应设置行显示可重试错误。系统工具
|
||
使用紧凑只读列表，不渲染禁用的卸载、停用或固定按钮。
|
||
|
||
功能已停用时，对应应用行显示“功能已停用”和设置入口，保留显隐偏好但暂时禁用 Switch。
|
||
|
||
若某应用自身支持业务启停，应在该应用原有设置中保留“启用功能”开关，并用说明区分：
|
||
|
||
- “显示在侧边栏”只控制入口。
|
||
- “启用功能”控制该功能是否运行。
|
||
|
||
## 5. 助手工作栏反馈
|
||
|
||
点击系统工具后，右侧工作栏按现有布局回流打开。主内容页面保持不变，侧栏不渲染工具内容。
|
||
|
||
- 文件：激活默认存在且不可关闭的“工作区”Tab，焦点进入目录区域或错误修复入口。
|
||
- 终端：激活匹配终端，焦点进入终端输入区；新建期间保留按钮宽度和进度状态。
|
||
- 浏览器：激活绑定当前 Conversation 的最近使用“浏览器”Tab；没有匹配实例时创建一个，
|
||
没有 Conversation 时按产品规则复用最近实例或进入待绑定空状态。
|
||
- 资源监控：激活“资源监控”Tab，焦点进入指标摘要；首个样本加载后开始绘制历史。
|
||
|
||
后台事件可以更新徽标，不能自动展开工作栏或切换当前 Tab。由用户点击快捷按钮触发的打开
|
||
属于显式操作，可以展开工作栏并切换 Tab。
|
||
|
||
### 5.1 资源监控面板
|
||
|
||
资源监控使用紧凑单列，不使用指标卡片墙：
|
||
|
||
```text
|
||
资源监控 本机
|
||
|
||
CPU 18%
|
||
[最近 5 分钟折线图]
|
||
|
||
内存 9.6 / 32 GB
|
||
[使用量进度条]
|
||
|
||
磁盘 IO 读 12 MB/s · 写 3 MB/s
|
||
|
||
GoodBuddy
|
||
CPU 4% · 内存 620 MB · 桌面进程 7
|
||
|
||
更新于 14:32:08
|
||
```
|
||
|
||
- CPU 折线纵轴固定为 `0%` 至 `100%`，不能根据当前低负载动态放大波动。
|
||
- 内存同时显示使用量、总量和百分比；进度条不代替文字数值。
|
||
- 磁盘 IO 使用每秒读写字节并按统一单位格式化，不显示累计设备字节数。
|
||
- GoodBuddy 摘要只显示聚合值，不列 PID、命令行或环境变量。
|
||
- 首次加载或停止后恢复时，CPU 和磁盘 IO 显示“正在建立采样基线”，不先渲染 `0%`；内存
|
||
等瞬时指标可以立即显示。
|
||
- 部分可用时只在对应指标行显示“不可用”和简短原因；全部失败时显示重试入口。
|
||
- 图表不使用动效平移；`prefers-reduced-motion` 下行为不变。
|
||
- 面板失去活动状态、工作栏收起或窗口隐藏、最小化时停止更新；返回后重新建立区间指标基线，
|
||
不填补离开期间的历史。
|
||
|
||
## 6. 文案
|
||
|
||
固定使用以下名称：
|
||
|
||
| 对象 | 文案 |
|
||
| --- | --- |
|
||
| 设置分类 | 应用与工具 |
|
||
| 文件系统工具 | 文件 |
|
||
| 终端系统工具 | 终端 |
|
||
| 浏览器系统工具 | 浏览器 |
|
||
| 浏览器说明 | GoodBuddy 受控浏览器 |
|
||
| 资源系统工具 | 资源监控 |
|
||
| 资源范围 | 本机 |
|
||
| 指标缺失 | 不可用 |
|
||
| 应用显隐开关 | 显示在侧边栏 |
|
||
| 内置来源 | 内置 |
|
||
|
||
不再使用“本地工作区”作为侧栏底部身份名称。项目和默认工作区的路径继续由项目选择器、页面
|
||
范围或工作区面板显示。
|
||
|
||
## 7. 键盘和无障碍
|
||
|
||
- 底部按钮均为独立 `button`，不能嵌套在整行设置按钮中。
|
||
- Tab 顺序为文件、终端、浏览器、资源监控、设置。
|
||
- 图标按钮通过 `aria-label` 提供名称，工具提示不能作为唯一可访问名称。
|
||
- 工作栏打开后按现有焦点策略聚焦目标面板；用户通过固定工作栏开关关闭时，焦点返回该开关。
|
||
- 选中按钮使用 `aria-pressed` 或等价的可访问状态，不能只依靠背景色。
|
||
- 徽标的数量或状态合并进按钮可访问名称，例如“终端，1 个等待处理”。
|
||
- 应用显隐 Switch 支持 Space 切换，保存失败后恢复原值并保留焦点。
|
||
|
||
## 8. 响应式
|
||
|
||
- 侧栏宽度 `220px` 至 `420px` 时，底部按钮尺寸不随宽度缩放。
|
||
- 窄窗口继续使用现有侧栏抽屉；工具栏不转为多行。
|
||
- 空间不足时缩小设置按钮前的弹性空白，不隐藏四个系统工具和设置。
|
||
- 工具提示不得超出窗口；靠近底边时显示在按钮上方。
|
||
- 粗指针设备不依赖悬停，按钮的可访问名称和选中反馈保持有效。
|
||
|
||
### 会话置顶与操作菜单
|
||
|
||
会话行的“更多会话操作”提供“置顶会话／取消置顶”，本地与消息通道会话均可使用。
|
||
置顶会话显示带“已置顶”可访问名称的图标；当前项目和搜索过滤仍生效，过滤后的列表先显示
|
||
置顶会话，两组内各按更新时间倒序。取消置顶恢复时间排序，不改变会话更新时间。
|
||
置顶状态重启后保留；保存成功后更新图标和顺序，失败保留原状态并显示应用错误通知。
|
||
存储尚未就绪或置顶请求进行中时禁用置顶操作。
|
||
|
||
操作菜单通过 body Portal 浮在会话列表上方，不撑开会话行。菜单锚定更多按钮，默认位于
|
||
按钮下方，随滚动、窗口及菜单尺寸变化重新定位，距窗口边缘至少 `8px`；空间不足时限制
|
||
宽高并允许菜单内部滚动。使用共享表面色、边框、圆角与浮层阴影。
|
||
|
||
入口提供 `aria-haspopup="menu"`、展开状态和控制关系；菜单使用 `menu`／`menuitem`。
|
||
打开后聚焦首个可用按钮，上下方向键循环移动，Home／End 到首尾；Escape 关闭并返回
|
||
触发按钮，点击外部或焦点离开时关闭。本地会话继续提供分支、重命名和删除确认，复制与
|
||
导出也适用于消息通道会话。持久化与刷新规则见
|
||
[会话置顶存储](../assistant-workbar/execution-history-storage.md#会话置顶)。
|
||
|
||
## 9. 未来插件入口
|
||
|
||
插件市场交付后另行定义插件区域、固定数量、溢出和权限界面。系统入口与四个系统工具的位置
|
||
保持保留，不向插件开放。
|
||
|
||
## 10. 项目活动汇总
|
||
|
||
对应 [FR-14](./prd.md#fr-14-项目活动汇总)，状态与计数遵守
|
||
[活动逻辑](./logic-design.md#9-项目活动汇总)。
|
||
|
||
- 全局汇总按钮仅在有活动时显示在项目选择器下方，紧凑显示待处理与运行中数量，空闲时整行隐藏，
|
||
右侧显示展开箭头，与下方新建会话保留 `8px` 间距。可访问名称明确数量属于“全项目活动”。
|
||
- 项目菜单在项目行显示同口径数量，保留“本地项目 / 远程项目 / 远程通道”分组和 SSH Host
|
||
层级，不因活动状态重排项目。数量为零时不显示标记，连接状态仍独立显示。
|
||
项目名独占一行，状态数量排列在名称下方，避免窄侧栏中数量挤占名称宽度。
|
||
- 点击汇总在按钮下方打开项目菜单，只列有活动会话的项目，每项显示项目名和同口径计数。
|
||
桌面鼠标悬停或点击项目展开右侧会话菜单，右侧空间不足且左侧可容纳时向左展开。两个面板
|
||
相接，各自拥有边框、圆角与阴影；会话层对齐所选项目行，底部空间不足时仅上移会话层，
|
||
不改变项目层的位置或高度。指针离开项目行进入会话层时不收起。展开项目不切换当前会话。
|
||
- 会话层顶部显示项目名，每行显示完整可换行的会话标题与明确状态文字，待处理会话排在
|
||
运行中会话之前。项目行保留子菜单箭头，会话行不显示箭头。不展开 Task、Job 或 Run 列表。
|
||
- 点击会话先关闭菜单并恢复入口焦点，再请求进入该条会话；允许离开当前页面后，
|
||
选择所属项目、清除搜索和该会话未读标记、清除任务选择与会话操作菜单，窄窗口同时关闭侧栏。
|
||
设置页沿用未保存修改的离开检查，取消离开时保留原页面。
|
||
- 菜单挂载到 body，使用 `menu`、`menuitem`、`aria-haspopup`、`aria-expanded` 与控制关系，
|
||
不隔离背景、不增加遮罩。原生浏览器相交遮挡沿用共享机制。
|
||
- 打开后焦点进入首个项目；上下方向键循环选择当前层项目或会话，Home、End 到首尾，
|
||
Enter、Space 激活，右方向键进入会话层。左方向键或 Escape 返回项目层并恢复对应项目
|
||
焦点；顶层 Escape 关闭并恢复汇总焦点，不继续关闭窄侧栏。Tab 关闭菜单后继续正常焦点
|
||
顺序；点击外部、焦点离开、再次点击入口或隐藏侧栏也关闭菜单。
|
||
- 单面板宽度为 `264px`，窗口小于 `620px` 或项目菜单两侧均无法容纳子菜单时，就地进入会话层并显示“返回项目列表”，
|
||
触控无需悬停。浮层距窗口边缘至少 `16px`，每层最大高度为 `480px`，短窗口进一步限制
|
||
高度并独立滚动。活动全部结束时，关闭已打开菜单并隐藏摘要。
|