Files
aiagent/docs/用户体验改进落地文档.md

489 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 天工智能体平台 — 用户体验改进落地文档
> 版本: 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`
```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` 顶部嵌入。
```typescript
// 核心逻辑
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`
```typescript
// 路由守卫
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` 为定制骨架屏:
```vue
<!-- 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`(新建)
```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. **欢迎** — 平台能力概览(~1 min)
2. **选择身份** — 开发者 / 业务用户 / 管理员(~1 min)
3. **创建第一个 Agent** — 从模板创建(~3 min)
4. **体验对话** — 发送第一条消息(~2 min)
5. **完成** — 个性化快捷入口 + 徽章(~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)