astrbot_plugin_imagestudio/docs/ui-redesign-audit-2026-07-21.md

7.2 KiB

ImageStudio 前端 UI 审计

日期:2026-07-21 范围:frontend/standalone-web 工作台、共享 API 类型、导航与 Gallery 页面 方法:Impeccable audit 技术检查、源码静态审计、基线 typecheck/build/contract tests

项目盘点

技术栈与入口

  • Vue 3 Composition API + TypeScript + Vite 6。
  • 独立 Web 入口:frontend/standalone-web/src/main.ts → App.vue。
  • AstrBot 插件页入口:frontend/plugin-page/src/main.ts,通过 astrbot-page-bridge 注入后复用 standalone-web/src/App.vue。
  • API 统一入口:frontend/shared/api/client.ts;路径常量集中在 frontend/shared/api/endpoints.ts,基础路径为 /api/v1/plugins/extensions/astrbot_plugin_imagestudio。
  • 当前无 Vue Router;页面切换由 activeNav + URL 查询参数 view / module / materialView / profile 维护,并使用 history.replaceState。

页面与主要组件

  • 工作台页面:overview、generate、queue、performance、gallery、profiles、materials、settings、logs。
  • 主要页面组件:GalleryPage.vue、ProfilesPage.vue、AdvancedMaterialImportPage.vue、SettingsPage.vue、BackupPage.vue、LogsPage.vue。
  • 主要复用组件:AppNavigationRail.vue、StateCard.vue、EmptyState.vue、MetricCardGrid.vue、多个 Dialog/Drawer 组件。
  • 复杂业务子域:workflow、profiles、materials;多数页面仍由 App.vue 组合和持有状态。

不能改变的契约

  • 不改变导航 key、module 映射、URL 查询参数语义及插件页/独立 Web 双入口。
  • 不改变 frontend/shared/api/endpoints.ts 中的 endpoint 名称、HTTP 方法、请求体字段和响应类型。
  • 不改变 frontend/shared/types/** 的数据结构,尤其是 image、job、workflow、profile、material、settings、storage 相关类型。
  • 不改变生成、队列、图库批量操作、工作流轮次/分支、角色卡、素材识别、设置备份与日志的现有交互语义。
  • 不删除 AstrBot plugin page bridge、媒体签名/载荷流程、后端连接状态与错误恢复路径。

Audit Health Score

维度 分数 关键发现
Accessibility 2/4 已有语义按钮、aria-current、aria-pressed、状态 live region;但部分表单控件缺少显式 label,图片预览/弹层焦点管理与键盘闭环需要统一验证。
Performance 2/4 生产构建可用;App.vue 单文件约 22k 行、Web JS gzip 约 211.5 kB,且存在 transition: width、transition: max-height 等布局属性动画。
Theming 2/4 有 dark/light 变量和主色持久化;但 tokens 集中在 App.vue,大量页面级颜色/阴影/渐变仍混杂,主题边界难以复用。
Responsive Design 2/4 Gallery 等页面有 1180/900/560 断点;工作台整体仍依赖 244px rail、宽 topbar 与多列面板,窄桌面窗口存在拥挤/溢出风险。
Anti-Patterns 2/4 本地 detector 命中布局属性动画、圆角元素厚边、侧边/顶部强调条、占位图片检测;背景网格、玻璃模糊和多层渐变也提高了视觉噪声。
Total 10/20 Acceptable:功能基础稳定,但需要有边界的结构化 UI 重构。

Anti-Patterns Verdict

部分通过,仍有明显 AI/模板化痕迹。 具体包括:工作台背景的装饰性网格、多个 surface 的渐变与 blur、状态卡片的顶部强调条、导航 active 状态的侧边强调、圆角 + 宽阴影组合,以及大单体 App 文件导致的重复视觉词汇难以治理。它们不是功能阻塞,但会让工具界面显得“装饰先于任务”。

问题清单与优先级

P0 Blocking

  • 当前没有确认到会阻塞主要任务完成的 P0 UI 问题。基线功能检查全部通过。

P1 Major

  • P1-01:工作台壳层与业务页面耦合过重:frontend/standalone-web/src/App.vue 约 22k 行,同时承载导航、数据加载、弹层、生成器、队列、图库、素材与设置。影响:任何视觉调整都容易触碰业务状态,回归面大。
  • P1-02:桌面窄窗口的结构风险:导航 rail、sticky topbar、双栏工作区和多个固定最小宽度并存,约 1024–1280px 宽度下容易造成操作区压缩、横向滚动或首屏信息层级失衡。
  • P1-03:主题 token 没有形成可复用层:核心变量主要位于 App.vue 的全局 style,页面组件继续直接组合 var(--panel)、var(--border)、颜色混合和阴影。影响:dark/light 与未来页面统一成本高。
  • P1-04:交互状态覆盖不均:部分按钮有 disabled/hover/focus,弹层、批量操作、加载、空态、错误态的状态表达不完全统一;需要以组件级状态矩阵补齐。
  • P1-05:可访问性需专项修复:GalleryPage.vue 搜索框和批量 checkbox 等控件依赖邻近文本,部分复杂弹层/预览需要确认 focus return、Escape、焦点陷阱与可读名称;不能只依赖视觉状态。
  • P1-06:性能边界:App.vue 产生单一大 JS/CSS 包,构建已给出超过 500 kB 的 chunk 警告;本轮不改业务加载策略,但应避免新增全局样式和重型运行时依赖。

P2 Minor

  • P2-01:视觉节奏不一致:8/10/12/14/16/18/22/24 等间距和 7/8/10/12 等圆角并存,需抽取有限的 spacing/radius scale。
  • P2-02:装饰噪声偏高:背景网格、渐变、backdrop-filter 在多个层级重复,降低任务区域的对比度和层级清晰度。
  • P2-03:状态色与表面色混用:good/warn/bad/idle 的 border、背景、顶部条规则分散在多个选择器,需集中到语义状态 tokens。
  • P2-04:图库卡片信息密度不稳定:grid/list/inspector 三种模式的操作按钮、选中态和媒体占比不完全一致,批量操作区在窄桌面易成为第二工具栏。
  • P2-05:部分过渡动画直接改变布局属性:检测命中 transition: width 与 transition: max-height;应优先改为 transform/opacity 或 grid 行过渡。
  • P2-06:图片替代文本规则不统一:多数业务图片有 alt,但预览/通知缩略图存在空 alt 或依赖上下文的情况,需要区分装饰图与内容图。

正向发现

  • 业务 API 与类型文件集中,页面重构可以保持数据契约不变。
  • 导航、状态卡、空态、预览对话框已有复用组件,不需要推倒重来。
  • Gallery 已具备搜索、筛选、grid/list、批量操作、预览、错误和 loading 路径,适合作为第一批页面。
  • 基线 npm.cmd run typecheck、npm.cmd run build:web、npm.cmd run test:contracts 均通过。

来源与边界

  • 本地源码:frontend/standalone-web/src/App.vue、frontend/standalone-web/src/features/gallery/GalleryPage.vue、frontend/standalone-web/src/components/AppNavigationRail.vue、frontend/shared/api/client.ts、frontend/shared/api/endpoints.ts、frontend/shared/types/**。
  • 本地配置:frontend/package.json、frontend/standalone-web/vite.config.ts、frontend/plugin-page/vite.config.ts。
  • Impeccable 本地 detector:命中 5 项静态提示,未替代人工审计。
  • 未使用外部网络资料;本次目标是对现有仓库实现做代码级审计。