admin/aiagent

Fork 0

Files

renjianbo 541a08628c chore: 保存笔记本本地未提交改动(源码+新增文件，排除构建缓存/大文件)

2026-07-11 08:58:10 +08:00

18 KiB

Raw Permalink Blame History

天工智能体平台 — 用户体验改进落地文档

版本: 1.0 | 日期: 2026-06-21 | 基于: 天工平台工程团队 UX 审计报告

总览

本次 UX 审计覆盖平台全部 34 条路由，识别出 22 个具体问题（3 严重 + 5 高危 + 10 中危 + 4 低危）。按 6 个阶段、24 个任务组织执行计划。

优先级	阶段	任务数	预计工时	目标
P0	1. 导航与信息架构	4	M	菜单瘦身 + 面包屑 + 全局搜索
P0	2. 工作流设计器交互增强	4	L	undo/redo + 未保存提示 + 画布辅助
P1	3. 全局反馈与加载体验	4	M	通知中心 + 骨架屏 + 空状态
P1	4. 登录与新手引导	3	M	渐进式登录提示 + 引导向导
P2	5. 响应式与可访问性	4	L	暗色模式 + 移动端 + i18n 框架
P2	6. 效率提升与反馈闭环	4	M	偏好持久化 + 反馈收集

Phase 1: 导航与信息架构优化 (P0)

问题现状

frontend/src/components/MainLayout.vue 使用 el-menu 水平排列 22 个菜单项（实际代码中 45 个 el-menu-item/el-sub-menu），在 1366px 屏幕即溢出隐藏。全平台无面包屑导航，深层页面（如 /agents/:id/design）无返回路径。

1.1 重构菜单为二级分组结构

文件: frontend/src/components/MainLayout.vue

<!-- 改造方案：el-menu → 分组下拉结构 -->
<template>
  <div class="main-nav">
    <el-dropdown v-for="group in menuGroups" :key="group.name" trigger="hover">
      <el-button type="text">{{ group.icon }} {{ group.label }}</el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item
            v-for="item in group.children"
            :key="item.path"
            @click="router.push(item.path)"
          >
            {{ item.icon }} {{ item.label }}
          </el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
  </div>
</template>

5 个菜单分组：

分组	包含	目标项数
核心功能	主控台 / 工作流 / Agent 管理	3
AI 交互	对话 / 编排 / 测试 / 团队	4
市场与资源	模板市场 / 技能商店 / 工具 / 节点模板	4
运维管理	监控 / 告警 / 日志	3
系统设置	工作区 / 权限 / 模型配置 / 数据源	4

1.2 添加面包屑导航

文件: frontend/src/components/BreadcrumbNav.vue（新建）+ MainLayout.vue（修改）

基于 route.matched 自动生成，无需手动维护。在 MainLayout 的 el-main 顶部嵌入。

// 核心逻辑
const breadcrumbs = computed(() =>
  route.matched
    .filter(r => r.meta?.title && !r.meta?.hidden)
    .map((r, i, arr) => ({
      label: r.meta!.title as string,
      path: i < arr.length - 1 ? r.path : undefined,
      isLast: i === arr.length - 1,
    }))
)

参考规格: D:\aaa\aiagent\team_projects\a3760fbb-8b9b-45ed-adba-db6f809b89d3\D-aaa-aiagent\breadcrumb_spec.md

1.3 菜单去重与合并

文件: frontend/src/views/Monitoring.vue, AgentDashboard.vue, MainLayout.vue, frontend/src/router/index.ts

合并项	方案
AgentDashboard + Monitoring	统一监控面板，tab 切换 Agent 视角/系统视角
DigitalEmployeeFactory + TeamBuilder	合并入口为"虚拟团队"
DataSources + KnowledgeDashboard	合并为"知识库管理中心"

目标：菜单项从 22 → ≤16 个。

1.4 全局搜索 (Ctrl+K)

文件: frontend/src/components/GlobalSearch.vue（新建）+ MainLayout.vue（修改）

Ctrl+K 唤起，ESC 关闭
搜索范围：页面导航 > Agent > 工作流 > 知识库 > 飞书机器人 > 帮助
全键盘操作：↑↓ 选择，Enter 跳转
150ms debounce，本地即时检索

参考规格: D:\aaa\aiagent\team_projects\a3760fbb-8b9b-45ed-adba-db6f809b89d3\D-aaa-aiagent\global_search_spec.md

验收标准:

菜单项 ≤16 个，1366px 屏幕无溢出
所有页面显示面包屑，可点击跳转
Ctrl+K 唤起全局搜索，500ms 内返回结果
Agent 监控和系统监控合并为统一面板
所有现有路由保持可访问

Phase 2: 工作流设计器交互增强 (P0)

问题现状

frontend/src/components/WorkflowEditor/ 是平台核心高频页面，但缺失撤销/重做、未保存变更提示、画布辅助功能。UI 文案已写了 Ctrl+Z/Ctrl+Shift+Z（工具栏），但功能未实现。

2.1 撤销/重做系统

文件: frontend/src/components/WorkflowEditor/composables/useUndoRedo.ts（新建）+ WorkflowEditor.vue（修改）

基于 Command Pattern 实现，参考产出代码：

D:\aaa\aiagent\team_projects\a3760fbb-8b9b-45ed-adba-db6f809b89d3\D-aaa-aiagent\frontend\src\
  ├── composables/useCommandHistory.ts    ← undo/redo 状态管理
  ├── commands/index.ts                    ← 命令注册
  ├── commands/AddNodeCommand.ts
  ├── commands/DeleteNodeCommand.ts
  ├── commands/MoveNodeCommand.ts
  ├── commands/AddEdgeCommand.ts
  ├── commands/DeleteEdgeCommand.ts
  └── commands/UpdateNodeConfigCommand.ts

关键设计:

历史栈深度 50
支持 node add/remove/move、edge add/remove、node data change
canUndo/canRedo 计算属性驱动工具栏按钮状态
dirty tracking 标记保存状态

2.2 未保存变更提示

文件: frontend/src/views/WorkflowDesigner.vue, frontend/src/views/AgentConfig.vue

// 路由守卫
import { onBeforeRouteLeave } from 'vue-router'
import { ElMessageBox } from 'element-plus'

onBeforeRouteLeave((to, from) => {
  if (isDirty.value) {
    return ElMessageBox.confirm('你有未保存的更改，确定要离开吗？', '提示', {
      confirmButtonText: '离开',
      cancelButtonText: '留下',
      type: 'warning',
    }).then(() => true).catch(() => false)
  }
  return true
})

// 浏览器关闭
window.addEventListener('beforeunload', (e) => {
  if (isDirty.value) {
    e.preventDefault()
    e.returnValue = ''
  }
})

2.3 画布辅助功能

文件: frontend/src/components/WorkflowEditor/WorkflowEditor.vue, CanvasToolbar.vue（新建）

小地图（可折叠 @vue-flow/minimap）
网格/吸附切换按钮
自动布局按钮（dagre）
缩放到适配按钮（fit-view）
节点搜索/定位输入框

以浮动工具栏形式在画布左下角展示。

2.4 节点配置面板优化

文件: frontend/src/components/WorkflowEditor/NodeConfigPanel.vue

增加节点类型搜索/筛选
LLM 节点 prompt 实时预览
配置项 help tooltip
一键复制节点配置

验收标准:

Ctrl+Z 可撤销最近 50 步操作
有未保存变更时离开页面弹出确认提示
画布小地图可折叠，缩放/适配按钮正常
节点配置面板有实时预览和 tooltip

Phase 3: 全局反馈与加载体验 (P1)

问题现状

全平台使用 v-loading 指令，页面加载时大面积空白。ElMessage 通知消失后不可回溯。空状态和错误状态使用裸 el-empty，文案不一致。

3.1 通知中心

文件: frontend/src/components/NotificationCenter.vue（新建）+ frontend/src/stores/notification.ts（新建）+ MainLayout.vue（修改）

收集 ElMessage/ElNotification 到持久化队列（最多 100 条）
顶部铃铛图标 + 红点未读数
下拉面板分类（全部/成功/警告/错误）
单条已读、全部已读、清空
点击通知跳转到相关页面

3.2 骨架屏加载

文件: frontend/src/views/Agents.vue, Home.vue, Executions.vue, TemplateMarket.vue

替换列表加载时的 v-loading 为定制骨架屏：

<!-- Agent 列表骨架屏示例 -->
<template v-if="loading">
  <el-skeleton :rows="pageSize" animated>
    <template #template>
      <div class="skeleton-row">
        <el-skeleton-item variant="text" style="width: 30%" />
        <el-skeleton-item variant="text" style="width: 40%" />
        <el-skeleton-item variant="text" style="width: 15%" />
        <el-skeleton-item variant="rect" style="width: 80px; height: 32px" />
      </div>
    </template>
  </el-skeleton>
</template>

封装 useSkeleton composable 统一加载状态管理。

3.3 统一空状态/错误状态

文件: frontend/src/components/EmptyState.vue（新建）+ ErrorState.vue（新建）

<!-- EmptyState API -->
<EmptyState
  icon="inbox"
  title="还没有智能体"
  description="创建你的第一个 AI 助手，开始智能体之旅"
  :action="{ label: '新建智能体', onClick: handleCreate }"
/>

全局替换裸用的 el-empty 和 el-alert。

3.4 操作确认与进度反馈

文件: frontend/src/components/ConfirmDialog.vue（新建）

危险操作展示被删除对象的具体信息（名称、关联资源数）
批量操作增加进度条（已处理 x/y）
长时间操作使用非阻塞通知代替阻塞弹窗

验收标准:

通知中心可查看最近 100 条通知，支持分类和跳转
4 个主要列表页使用骨架屏
所有空/错误状态使用统一组件
批量操作有实时进度反馈
网络断开时自动显示离线横幅

Phase 4: 登录与新手引导 (P1)

问题现状

Login.vue 在 5 次失败后直接进入 60 秒冷却，缺乏渐进式提示。新用户无引导流程，平台 34 条路由 + 56 个工具对新手极不友好。

4.1 登录页渐进式错误提示

文件: frontend/src/views/Login.vue（修改 line 276-285 附近）

失败次数	行为
第 1-2 次	通用错误提示："用户名或密码错误"
第 3 次	增加"忘记密码？"链接
第 4 次	显示验证码输入
第 5 次	15 秒短冷却（非 60 秒）+ "联系管理员"入口

4.2 新用户引导向导

文件: frontend/src/components/OnboardingWizard.vue（新建）+ frontend/src/stores/user.ts（修改）

5 步引导：

欢迎 — 平台能力概览（~1 min）
选择身份 — 开发者 / 业务用户 / 管理员（~1 min）
创建第一个 Agent — 从模板创建（~3 min）
体验对话 — 发送第一条消息（~2 min）
完成 — 个性化快捷入口 + 徽章（~1 min）

首次登录自动弹出，支持"跳过"和"稍后再说"，完成后可从头像菜单重新进入。

4.3 上下文帮助系统

文件: frontend/src/components/ContextHelp.vue（新建）+ HelpPanel.vue（新建）

每个页面顶部可折叠帮助横幅（3-5 个 FAQ）
表单字段 help tooltip
右下角悬浮"?"帮助按钮 → 侧边帮助面板
0 个 Agent 的新用户突出显示"快速上手"按钮

验收标准:

登录失败 3 次显示忘记密码，第 5 次仅 15 秒冷却
新用户首次登录看到 5 步引导
所有页面有帮助横幅
引导完成率 ≥ 60%

Phase 5: 响应式与可访问性 (P2)

5.1 核心页面响应式

文件: frontend/src/views/Agents.vue, Home.vue, Monitoring.vue, AgentChat.vue, MainLayout.vue

表格在 ≤768px 转为卡片布局
MainLayout 菜单在小屏转为汉堡菜单（el-drawer）
监控图表在小屏堆叠排列

5.2 暗色模式

文件: frontend/src/stores/theme.ts（新建）+ frontend/src/styles/dark-theme.css（新建）+ MainLayout.vue（修改）

利用 Element Plus 2.x 原生 CSS 变量暗色支持
主题切换按钮：浅色 / 暗色 / 跟随系统
暗色变量适配：画布背景、消息气泡、卡片
用户偏好持久化 localStorage
默认跟随 prefers-color-scheme

5.3 键盘无障碍与 ARIA

项目	说明
Tab 导航	所有交互元素可通过 Tab 访问，焦点样式可见
Focus Trap	模态对话框焦点不逃逸
ARIA	表格/菜单/选项卡添加 role 和 label
Skip Link	键盘用户可跳过导航直达内容
颜色	错误状态同时使用图标 + 颜色（不只依赖颜色）

5.4 国际化框架

文件: frontend/src/i18n/index.ts（新建）+ frontend/src/locales/zh-CN.json + en-US.json

引入 vue-i18n
提取中文硬编码到 zh-CN.json
创建 en-US.json（优先核心页面：登录、主控台、Agent 管理）
语言切换下拉菜单

验收标准:

375px 移动端宽度下 Agent/工作流列表正常显示
暗色模式切换后全页面颜色正常
Tab 可导航所有交互元素
语言切换为英文后登录页/主控台显示英文

Phase 6: 效率提升与反馈闭环 (P2)

6.1 用户偏好持久化

文件: frontend/src/stores/userPreferences.ts（新建）

表格列可见性和顺序（每页独立）
分页大小偏好（10/20/50）
侧边栏折叠状态
持久化到 localStorage，按 workspace 隔离
首页"最近使用"快捷入口（最近 5 个 Agent/工作流）

6.2 Agent 列表行内快速预览

文件: frontend/src/views/Agents.vue（修改）+ frontend/src/components/AgentQuickPreview.vue（新建）

表格行展开显示简易聊天输入框，不离开列表即可发送一条测试消息
收藏功能（星标 Agent）
Popover 悬浮预览 Agent 配置摘要
批量操作工具栏（批量部署/停止/导出）

6.3 用户反馈收集

文件: frontend/src/components/FeedbackWidget.vue（新建）+ MainLayout.vue（修改）

右下角悬浮反馈按钮
反馈类型：Bug 报告 / 功能建议 / 使用体验
自动附带 URL、浏览器信息、用户 ID
支持截图标注（可选）
后端 POST /api/v1/feedback 端点

6.4 执行历史体验优化

文件: frontend/src/views/Executions.vue, ExecutionDetail.vue（修改）+ frontend/src/components/ExecutionTimeline.vue（新建）

时间范围筛选（今天/近7天/近30天/自定义）
执行耗时分布图表
节点执行时间线可视化（el-timeline）
失败执行一键重试（相同参数）

验收标准:

表格列配置和分页大小刷新后保持
Agent 列表行展开快速测试
反馈 Widget 可提交 Bug/建议
执行历史支持时间筛选和一键重试
执行详情展示节点时间线

22 个 UX 问题总清单

ID	严重度	类别	问题	文件位置
F01	🔴 Critical	导航	22 个横向菜单项严重溢出	`MainLayout.vue:50-140`
F02	🔴 Critical	导航	全平台无面包屑导航	全局
F03	🔴 Critical	编辑器	工作流设计器无撤销/重做	`WorkflowEditor/`
F04	🟠 High	编辑器	无未保存变更提示	`WorkflowDesigner.vue`
F05	🟠 High	加载	全平台 v-loading 无骨架屏	`Agents.vue` 等
F06	🟠 High	通知	ElMessage 消失后无法回溯	全局
F07	🟠 High	信息架构	菜单功能重叠	`router/index.ts`
F08	🟠 High	搜索	无全局搜索	全局
F09	🟡 Medium	登录	登录失败 60 秒冷却无渐进提示	`Login.vue:276-285`
F10	🟡 Medium	引导	新用户无引导流程	全局
F11	🟡 Medium	主题	无暗色模式	全局样式
F12	🟡 Medium	响应式	除 MobileChat 外无移动端适配	全局
F13	🟡 Medium	表格	Agent/Home 操作列过宽导致横向滚动	`Agents.vue:109`
F14	🟡 Medium	测试	Agent 测试需跳转到设计器	`Agents.vue`
F15	🟡 Low	偏好	用户偏好不持久化	全局 store
F16	🟡 Low	反馈	无用户反馈收集渠道	全局
F17	🟡 Low	可访问性	无键盘导航和 ARIA	全局
F18	🟡 Low	执行	执行历史缺少时间筛选和重试	`Executions.vue`
F19	🟢 Low	节点	节点配置无实时预览	`NodeConfigPanel.vue`
F20	🟢 Low	菜单	菜单无 ARIA 属性	`MainLayout.vue`
F21	🟢 Low	通知	长时间操作无进度反馈	全局
F22	🟢 Low	帮助	表单字段无 help tooltip	全局

实现顺序建议

Week 1-2:  Phase 1 (导航) → Phase 2 (设计器)           ← P0 必须交付
Week 3-4:  Phase 3 (反馈) → Phase 4 (登录引导)          ← P1 核心体验
Week 5-8:  Phase 5 (响应式/暗色) → Phase 6 (效率)       ← P2 完善体验

技术栈对齐

前端: Vue 3 + TypeScript + Pinia + Element Plus + Vue Router
后端: FastAPI + SQLAlchemy + Pydantic
代码规范: 使用 frontend/src/composables/ 模式，Pinia stores 按领域拆分
新文件放置: 遵循现有目录结构（components 新组件、stores 新 store）

复用现有基础设施

现有模块	可复用场景
`useWorkflowStore`	undo/redo 系统依赖
`MainLayout.vue`	面包屑、搜索、通知中心嵌入点
`router/index.ts`	面包屑和全局搜索的数据源
`Login.vue`	忘记密码对话框已有，扩展渐进式提示
Element Plus 2.x	暗色模式原生支持，骨架屏组件
`el-dialog` / `el-drawer`	引导向导、帮助面板 UI 基础

参考资料

完整审计报告: D:\aaa\aiagent\team_projects\a3760fbb-8b9b-45ed-adba-db6f809b89d3\D-aaa-aiagent\
UX 执行计划: ux_improvement_plan.json (6 阶段 24 任务)
导航审计: navigation_audit.md (34 路由全覆盖)
菜单去重: menu_dedup_report.md
面包屑规格: breadcrumb_spec.md
全局搜索规格: global_search_spec.md
新手引导规格: onboarding_product_spec.json
参考前端代码: frontend/src/ (composables/components/stores)
参考后端代码: backend/app/ (routers/models/schemas)

18 KiB Raw Permalink Blame History Unescape Escape

天工智能体平台 — 用户体验改进落地文档

总览

Phase 1: 导航与信息架构优化 (P0)

问题现状

1.1 重构菜单为二级分组结构

1.2 添加面包屑导航

1.3 菜单去重与合并

1.4 全局搜索 (Ctrl+K)

Phase 2: 工作流设计器交互增强 (P0)

问题现状

2.1 撤销/重做系统

2.2 未保存变更提示

2.3 画布辅助功能

2.4 节点配置面板优化

Phase 3: 全局反馈与加载体验 (P1)

问题现状

3.1 通知中心

3.2 骨架屏加载

3.3 统一空状态/错误状态

3.4 操作确认与进度反馈

Phase 4: 登录与新手引导 (P1)

问题现状

4.1 登录页渐进式错误提示

4.2 新用户引导向导

4.3 上下文帮助系统

Phase 5: 响应式与可访问性 (P2)

5.1 核心页面响应式

5.2 暗色模式

5.3 键盘无障碍与 ARIA

5.4 国际化框架

Phase 6: 效率提升与反馈闭环 (P2)

6.1 用户偏好持久化

6.2 Agent 列表行内快速预览

6.3 用户反馈收集

6.4 执行历史体验优化

22 个 UX 问题总清单

实现顺序建议

技术栈对齐

复用现有基础设施

参考资料

18 KiB

Raw Permalink Blame History