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

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

> 版本: 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)