AstrBot-Desktop/docs/ui-redesign-plan.md

65 行
3.9 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# AstrBot Desktop UI 重构方案
## Design read
这是一个 Windows 桌面工具型应用,面向需要同时管理陪伴实例和运维实例的用户;视觉应偏安静、可信、信息密度可控的工作台,而不是营销网站或 SaaS 落地页。
## 设计原则
- 保留业务逻辑和交互路径,先重构视觉层和布局层。
- 采用单一冷色中性 token 系统,蓝色只承担交互和连接状态,不使用紫蓝渐变。
- 主任务优先:聊天输入和当前槽位最突出,诊断/连接元信息作为次级层。
- 让错误、离线、空会话、上传中、重连中都能在同一位置理解和恢复。
- 桌面优先,窄窗口可收缩;不把移动端营销布局套进桌面工具。
- 普通 UI 不增加动画;桌宠既有状态动画保留,并加入 reduced-motion 兜底。
## 不变合同
| 范畴 | 保留内容 |
| ---- | ---------------------------------------------------------------------- |
| 页面 | `chat`、`connections`、`desktop`、`pet`、`diagnostics` |
| 连接 | `companion` / `operations` 独立 REST、SSE、Token、会话、消息、未读状态 |
| 数据 | `profile_id`、`server_instance_id`、`conversation_id` 及现有 schema |
| IPC | 现有 `invoke()` commands 和 `listen()` event names |
| 安全 | Rust 持有凭据和本机权限;React 不获得任意文件/命令执行能力 |
| 测试 | 保留现有 Vitest、Playwright、Rust workspace 检查入口 |
## 分阶段队列
### P0 — 先稳定工作台骨架
- `src/styles.css`:抽取颜色、边框、间距、状态和 z-index tokens;补全统一 `:focus-visible`、disabled、error、loading 语义。
- `src/App.tsx`:保持页面 key 和事件逻辑不变,清理页面头部层级与导航可读性。
- `src/features/chat/ChatPanel.tsx`:把运行时状态、槽位 tabs、会话列表、消息流、composer 分成明确的语义区域。
- 验证:Vitest、typecheck、lint、Vite build;聊天页新增关键交互回归断言。
### P1 — 完善核心页面
- `src/features/profiles/ProfileManager.tsx`、`CredentialEnrollmentCard.tsx`:统一表单布局、字段标签、错误/成功反馈和敏感信息说明。
- `src/features/chat/StatusBubble.tsx`:统一连接状态颜色、读屏文本和小窗口窄尺寸。
- `src/App.tsx` 的 `DesktopBehaviorPage`、`DiagnosticsPage`:减少重复卡片,建立明确的设置/诊断分组。
- 验证:表单与槽位隔离测试、键盘导航检查、窄窗口 Playwright。
### P2 — 性能与一致性
- 页面级拆分 `App.tsx` 中非聊天视图,降低首屏 JS 体积。
- 清理重复主题覆盖,保留 dark/light 两套可验证 token。
- 统一消息、状态、按钮、表单的可访问名称与 tooltip;补齐 reduced motion。
- 验证:生产构建体积对比、Playwright 截图/溢出检查、完整 Rust + frontend gate。
## 首批实施范围
只改聊天页视觉层,具体文件:
- `src/features/chat/ChatPanel.tsx`:仅在需要时补充语义属性或可见标签,不改变数据处理。
- `src/styles.css`:新增/调整 chat 相关 token 与布局规则,保留现有 class 兼容。
- `src/App.tsx`:如需调整聊天页外壳,只改 `ChatPage` 的呈现结构,不改导航和 IPC。
- `src/App.test.tsx`:补充聊天页视觉相关的可访问名称/状态回归,不重写现有业务测试。
## 完成标准
- 聊天发送、切槽位、切会话、附件、语音、重连、停止生成、打开快捷窗口行为不变。
- 主聊天区域在 1280px、1024px、680px 窗口下无横向溢出。
- 键盘能到达导航、槽位 tabs、会话、消息操作、输入和发送按钮,焦点可见。
- 深浅色主题对比度满足 WCAG AA;错误和连接状态不只依赖颜色。
- 前端 typecheck、lint、unit test、build 通过。