AstrBot-Desktop/docs/reports/ui-audit-2026-07-21.md

5 KiB

AstrBot Desktop 前端 UI 审计

日期:2026-07-21
范围:src/App.tsx、src/styles.css、src/features/**、前端测试与构建配置

审计方式

  • 读取 docs/01_Architecture_Design.md、docs/02_Codex_Implementation_Tasks.md 和现有前端实现。
  • 按 Impeccable technical audit 的 Accessibility、Performance、Theming、Responsive、Anti-patterns 五个维度检查。
  • 运行本地 detector:node C:\Users\Administrator\.agents\skills\impeccable\scripts\detect.mjs --json src/App.tsx src/styles.css src/features;未返回结构化命中项,因此以下结论以源码和基线检查为准。
  • 基线:pnpm run typecheck、pnpm run lint、pnpm run test、pnpm run build 均通过;Node 版本有 24.14.0 vs 要求 >=24.17.0 的警告。

Health score

维度 分数 结论
Accessibility 2/4 已有主导航、部分 ARIA 和 live region,但焦点、键盘 tab 语义、表单标签及窗口控件仍不完整
Performance 2/4 聊天状态集中在大组件,生产 JS gzip 约 4.0 MB,存在按页面拆分和减少无关重渲染空间
Theming 2/4 有 dark/light 主题,但大量颜色、渐变和阴影直接写在 CSS,主题 token 未形成单一来源
Responsive 2/4 有 900/760/680px 断点,但聊天会话列表、工具栏、桌面窗口尺寸和 44px 触控目标仍需验证
Anti-patterns 2/4 不是营销页式 AI slop,但存在渐变背景、重复卡片、过度圆角/阴影和全局大标题层级偏重
总分 10/20 Acceptable:需要系统性重构,但不需要改写业务架构

P0:阻塞项

当前没有确认会阻塞任务完成的 P0 功能问题。

P1:发布前必须处理

  1. 聊天页信息层级不稳定 — src/features/chat/ChatPanel.tsx:577;运行时状态、槽位切换、会话列表、消息流和输入区堆在同一面板,主任务入口不够突出。
  2. 主题令牌不完整 — src/styles.css:1、src/styles.css:1804;深浅色主题依赖大量重复选择器和硬编码色值,新增页面容易产生视觉漂移。
  3. 焦点和键盘状态不完整 — src/styles.css:246 只覆盖输入框/选择框;导航按钮、槽位 tab、消息操作和窗口控件缺少统一 :focus-visible 样式。
  4. 表单标签与可读性不一致 — src/App.tsx:945、src/App.tsx:950、src/App.tsx:973 使用 aria-label 代替可见标签;CredentialEnrollmentCard 的 label 结构也需要统一间距和错误提示。
  5. 聊天构建体积过大 — pnpm run build 输出 index-D8Ql9rJN.js 约 5.6 MB(gzip 约 4.0 MB);页面级懒加载和资源边界应纳入 P2,若继续增加桌宠/诊断功能则应提前拆分。
  6. 状态反馈缺少统一视觉语义 — 连接、加载、错误、空会话和上传状态分散在多个 class,颜色和文案没有统一 token/状态等级。
  7. 桌宠浮层遮挡主导航 — 浏览器预览中 pp-pet-overlay 覆盖左侧导航项,桌宠可见时会降低页面可操作性;应限制浮层层级/停靠区,或提供不遮挡导航的安全边界。

P2:下一批处理

  1. 统一桌面工作区的密度、间距、圆角和阴影,减少重复 card 包裹。
  2. 修正 680px 以下布局:会话列表、聊天工具条、输入框按钮和长文本溢出。
  3. 给所有异步按钮补充进行中、失败、恢复动作和 aria-live 反馈。
  4. 给聊天消息操作、附件移除、窗口控制补充 tooltip/可见焦点,不依赖符号字符表达含义。
  5. 引入 text-wrap: balance/pretty、font-variant-numeric: tabular-nums 和统一字体回退链。
  6. 增加 prefers-reduced-motion 覆盖,保留桌宠状态动画但避免普通 UI 无限动画扩散。

不可改变的产品边界

  • 技术栈继续使用 Tauri 2、React、TypeScript、Vite、Rust、SQLite、REST + SSE。
  • 保留页面 key:chat、connections、desktop、pet、diagnostics。
  • 不改变 Tauri IPC command/event 名称、Rust 权限边界、profile/slot/session/message 数据结构。
  • 不改变 companion 与 operations 两个槽位的隔离规则,不把 conversation_id 单独作为本地唯一键。
  • 不让 React 直接读取凭据、任意文件或执行 Shell;不修改后端协议和数据库迁移。

首批建议

先重构 ChatPage / ChatPanel 的视觉层:保留所有 state、invoke/listen、session、attachment、voice 和发送逻辑,只调整信息分组、CSS token、状态展示和响应式布局。

外部技能可用性

  • 已使用本地 Impeccable audit 规范与 detector。
  • 已读取本机 redesign-existing-projects 与 design-taste-frontend 技能说明,并将其约束应用于方案;它们没有独立可执行命令或额外 CLI。