aiagent/docs/android-ux-improvement-requirements.md

天工 Android 客户端 — 用户体验与功能提升需求文档

版本: v1.0
日期: 2026-06-24
基线: android-app-design.md (设计蓝图, 覆盖 4 页面: 登录/对话/Agent列表/设置)
Web 参考: frontend/src/ (33 路由页面, 已投产)
后端支撑: backend/app/main.py (40+ API 路由模块, 全部可用)

---

一、功能对齐矩阵

#	功能域	Web 前端	Android 设计 (现状)	对齐状态	移动端适配建议
1	登录/注册	✅ 状态机驱动, 验证码, 忘记密码, 30天免登录	✅ 基础登录	⚠️ 功能不足	补齐验证码/忘记密码/生物识别
2	Agent 对话	✅ 单Agent + 编排模式, SSE流式, 思考链, 工具调用, 审批	✅ 基础对话 + SSE	⚠️ 功能不足	补齐多模式/思考链/工具可视化
3	语音交互	✅ Web Speech API (语音输入 + TTS)	✅ ASR + TTS 接口	✅	需端侧 VAD/降噪优化
4	Agent 列表	✅ 搜索/筛选/CRUD/导入导出/部署停止	✅ 基础列表	⚠️ 功能不足	补齐搜索/导入导出/操作菜单
5	Agent 市场	✅ 分类浏览/详情/一键添加	❌	🔴 缺失	新增 — 移动端核心发现入口
6	工作流设计	✅ 可视化拖拽画布 (Vue Flow)	❌	🟡 低优先级	仅"查看"模式, 编辑留给 Web
7	Agent 配置	✅ 名称/描述/System Prompt/模型/工具/预算	❌	🔴 缺失	新增 — 基础配置(文本字段为主)
8	模板市场	✅ 场景模板浏览/一键创建	❌	🟡 中优先级	简化浏览 + 一键从模板创建
9	插件市场	✅ 插件安装/管理	❌	🟡 中优先级	浏览 + 安装/卸载
10	知识库	✅ 文档上传/知识库检索/仪表盘	❌	🟡 中优先级	简化检索(仅搜索对话)
11	数字员工	✅ 目标管理/任务树/工厂创建	❌	🟡 中优先级	目标查看 + 任务进度
12	Agent 定时	✅ Cron 定时触发/管理	❌	🟡 中优先级	查看 + 启停
13	团队协作	✅ 团队建设/成员管理	❌	🟡 中优先级	查看团队 + Agent 协作
14	推送通知	✅ FCM 集成	✅ FCM 基础	⚠️ 可增强	通知分类/优先级/富媒体
15	设置/工作区	✅ 工作区切换/多租户	✅ 基础设置	⚠️ 可增强	工作区切换/个性化
16	数据源	✅ CRUD/连接测试/查询	❌	🟢 低优先级	—
17	监控告警	✅ Dashboard/规则/日志	❌	🟢 低优先级	—
18	权限管理	✅ 管理员权限控制	❌	🟢 低优先级	—
19	离线能力	❌	❌	🟡 中优先级	聊天记录本地缓存

图例: 🔴 关键缺失 · 🟡 重要补充 · ⚠️ 功能不足 · ✅ 对齐 · 🟢 暂缓

---

二、屏幕级 UX 审计

2.1 登录页 (LoginScreen)

现状: 仅用户名+密码表单, 无错误冷却, 无生物识别, 无忘记密码入口。

问题:

• [P0] 连续登录失败无渐进式限制 → 账户爆破风险
• [P0] 无生物识别 (指纹/面部) → 每次输入密码体验差
• [P1] 无忘记密码流程 → 用户锁死无自救路径
• [P1] 无验证码机制 → 无机器人防护
• [P2] 无注册入口 → 只能登录, 不能自注册

参考: frontend/src/views/Login.vue — 状态机驱动的登录页, 包含

• 渐进式错误冷却 (3次→验证码, 5次→15秒锁定)
• 忘记密码 → 邮箱验证码 → 重置
• 30天免登录
• 注册 Tab

---

2.2 对话页 (ChatScreen)

现状: 基础消息列表 + SSE 流式, 语音按钮, Agent 选择器。

问题:

• [P0] 无思考链 (thinking trace) 展示 → 用户不知 Agent "在想什么"
• [P0] 无工具调用可视化 → 不知道 Agent 调用了哪些工具
• [P0] 单 Agent 模式仅有基础聊天, 缺少编排 (orchestrate) 入口
• [P1] 无消息重试/复制功能 → 遇到错误只能重发
• [P1] 无工具审批弹窗 → 高权限操作无人工确认
• [P1] 语音输入无 VAD (Voice Activity Detection) → 噪音误触发
• [P2] 无 TTS 自动播报开关 → 需每次手动触发

参考: frontend/src/views/AgentChat.vue (35KB) — 功能丰富的对话页, 包含:

• 单 Agent / 多 Agent 编排双模式
• SSE 流式 + 降级 POST 双通道
• 思考链可视化 (think/tool_call/tool_result/final 四阶段)
• 工具审批弹窗 (approval_required 事件)
• 消息重试 (retryMessage, 自动回填并重发)
• 消息复制
• 编排模式编辑器 (辩论/路由/顺序/流水线)
• localStorage 状态持久化 (24h TTL)

---

2.3 Agent 列表页 (AgentListScreen)

现状: 基础网格/列表展示 Agent。

问题:

• [P0] 无搜索/筛选 → Agent 数量多时不可用
• [P1] 无 Agent 市场入口 → 无法发现新 Agent
• [P1] 无导入/导出操作 → 无法迁移 Agent
• [P1] 无部署/停止操作 → 无法管理运行状态
• [P2] 无 Agent 详情页 → 点击仅能进入对话

参考: frontend/src/views/Agents.vue + AgentMarket.vue + agent.ts store

---

2.4 设置页 (SettingsScreen)

现状: 基础设置项。

问题:

• [P0] 无工作区切换 → 多租户用户无法切换上下文
• [P1] 无通知偏好设置 → 无法控制推送类型
• [P1] 无数据管理 (缓存清理/对话历史管理)
• [P2] 无深色模式/主题切换

参考: frontend/src/stores/user.ts — workspace 支持 (switchWorkspace)

---

三、P0-P2 优先级矩阵与用户故事

P0 — V1.0 必须交付 (阻塞核心体验)

#	用户故事	涉及页面	工作量
P0-1	思考链可视化 — 作为用户, 我想看到 Agent 的推理过程 (think/tool_call/tool_result/final), 以便理解 AI 如何做出决策	ChatScreen	中等
P0-2	工具调用可视化 — 作为用户, 我想看到 Agent 调用了哪些工具以及结果, 以便验证 AI 行为	ChatScreen	中等
P0-3	多 Agent 编排对话 — 作为用户, 我想让多个 Agent 以辩论/路由/顺序模式协作, 以便获得更高质量回答	ChatScreen	较大
P0-4	Agent 搜索与筛选 — 作为用户, 我想按名称/状态/类别搜索 Agent, 以便在大量 Agent 中快速定位	AgentListScreen	较小
P0-5	生物识别登录 — 作为用户, 我想用指纹/面部解锁登录, 以便快速安全地访问应用	LoginScreen	较小
P0-6	渐进式登录安全 — 作为系统, 需要在连续失败后增加验证码/冷却, 以防止暴力破解	LoginScreen	较小
P0-7	工作区切换 — 作为用户, 我想在多个工作区之间切换, 以便管理不同团队/项目的 Agent	SettingsScreen	中等

P1 — V1.1 重要交付 (提升完整度)

#	用户故事	涉及页面	工作量
P1-1	Agent 市场浏览 — 作为用户, 我想浏览和搜索公开 Agent, 以便发现有用的 AI 助手	新增 AgentMarket	较大
P1-2	一键从模板创建 Agent — 作为用户, 我想从场景模板快速创建 Agent, 以便无需从零配置	新增	中等
P1-3	忘记密码流程 — 作为用户, 我想通过邮箱验证码重置密码, 以便在忘记密码时自助恢复	LoginScreen	中等
P1-4	消息重试与复制 — 作为用户, 我想重试失败的消息或复制 Agent 回答, 以便纠正错误或保存有用信息	ChatScreen	较小
P1-5	工具审批弹窗 — 作为用户, 我想在 Agent 执行敏感操作前审批, 以便控制高风险行为	ChatScreen	较小
P1-6	Agent 部署/启停 — 作为用户, 我想控制 Agent 的运行状态 (部署/停止), 以便管理资源消耗	AgentListScreen	较小
P1-7	Agent 导入/导出 — 作为用户, 我想导出 Agent 配置为 JSON 并分享, 以便跨环境迁移	AgentListScreen	较小
P1-8	通知偏好设置 — 作为用户, 我想控制哪些事件触发推送, 以便减少打扰	SettingsScreen	较小
P1-9	聊天记录本地缓存 — 作为用户, 我想在网络断开时查看历史对话, 以便在离线环境继续参考	ChatScreen	中等

P2 — V1.2 增强交付 (体验升级)

#	用户故事	涉及页面	工作量
P2-1	注册入口 — 作为新用户, 我想在 App 内直接注册账号, 以便无需跳转 Web	LoginScreen	较小
P2-2	TTS 自动播报 — 作为用户, 我想让 Agent 回答自动语音朗读, 以便在驾车/运动时收听	ChatScreen	较小
P2-3	深色模式 — 作为用户, 我想切换到深色主题, 以便在夜间使用时减少视觉疲劳	全局	中等
P2-4	Agent 基础配置编辑 — 作为用户, 我想在手机上修改 Agent 名称/描述/System Prompt, 以便快速微调	新增 AgentConfig	中等
P2-5	工作流查看模式 — 作为用户, 我想查看 Agent 的工作流结构图, 以便了解其内部逻辑	新增	较大
P2-6	知识库搜索 — 作为用户, 我想搜索已上传的知识库文档, 以便找到相关资料	新增	中等
P2-7	数字员工目标查看 — 作为用户, 我想查看数字员工的当前目标和任务进度, 以便了解 AI 工作状态	新增 GoalView	中等

---

四、后端 API 依赖清单

Android 端需要调用的 API（全部已由 Web 前端验证可用）：

4.1 认证模块 (/api/v1/auth/*)

POST   /api/v1/auth/login              # 登录 → 返回 JWT
POST   /api/v1/auth/register           # 注册
GET    /api/v1/auth/me                 # 获取当前用户信息 (含 workspaces)
POST   /api/v1/auth/switch-workspace/{id}  # 切换工作区
POST   /api/v1/auth/forgot-password    # 发送重置验证码
POST   /api/v1/auth/reset-password     # 重置密码

4.2 Agent 模块 (/api/v1/agents/*)

GET    /api/v1/agents                  # 列表 (支持 search/status/skip/limit)
GET    /api/v1/agents/{id}             # 详情
POST   /api/v1/agents                  # 创建
PUT    /api/v1/agents/{id}             # 更新
DELETE /api/v1/agents/{id}             # 删除
POST   /api/v1/agents/{id}/deploy      # 部署
POST   /api/v1/agents/{id}/stop        # 停止
POST   /api/v1/agents/{id}/duplicate   # 复制
GET    /api/v1/agents/{id}/export      # 导出 JSON
POST   /api/v1/agents/import           # 导入 JSON

4.3 Agent 对话模块 (/api/v1/agent-chat/*)

POST   /api/v1/agent-chat/{agent_id}           # 非流式对话
POST   /api/v1/agent-chat/{agent_id}/stream    # SSE 流式对话
POST   /api/v1/agent-chat/bare                 # 无 Agent 对话
POST   /api/v1/agent-chat/bare/stream          # 无 Agent 流式
POST   /api/v1/agent-chat/orchestrate           # 多 Agent 编排

4.4 Agent 市场 (/api/v1/agent-market/*)

GET    /api/v1/agent-market            # 市场列表 (分类/搜索)
GET    /api/v1/agent-market/{id}       # 市场详情
POST   /api/v1/agent-market/{id}/install  # 添加 Agent

4.5 模板市场 (/api/v1/template-market/*)

GET    /api/v1/template-market         # 模板列表
POST   /api/v1/platform/agents/from-template  # 从模板创建 Agent

4.6 定时任务 (/api/v1/agent-schedules/*)

GET    /api/v1/agent-schedules         # 列表
POST   /api/v1/agent-schedules/{id}/toggle  # 启停

4.7 目标/任务 (/api/v1/goals/*, /api/v1/tasks/*)

GET    /api/v1/goals                   # 目标列表
GET    /api/v1/goals/{id}              # 目标详情 + 任务树
GET    /api/v1/tasks                   # 任务列表

4.8 推送 (/api/v1/push/*, /api/v1/fcm/*)

POST   /api/v1/fcm/register            # 注册设备 Token
GET    /api/v1/notifications           # 通知列表
PUT    /api/v1/notifications/{id}/read # 标记已读

4.9 语音 (/api/v1/voice/*)

POST   /api/v1/voice/asr               # 语音转文字
POST   /api/v1/voice/tts               # 文字转语音

4.10 审批 (/api/v1/approval/*)

POST   /api/v1/approval/{id}/resolve   # 审批决议 (approved/denied/skip)

4.11 知识库 (/api/v1/knowledge/*)

GET    /api/v1/knowledge/dashboard     # 知识库仪表盘
POST   /api/v1/knowledge/search        # 语义搜索

---

五、技术建议

5.1 SSE 流式对话增强

• 当前: 实现基础 SSE 读取
• 建议:
  • 支持 think / tool_call / tool_result / approval_required / final / error 六种事件类型解析
  • 流式数据增加缓冲池 + 逐块渲染, 避免大消息阻塞 UI 线程
  • 降级策略: SSE 失败 3s 内自动切 POST

5.2 离线与缓存策略

• 聊天记录: Room DB 存储 (24h TTL, 同 Web 的 localStorage 策略)
• Agent 列表: 增量同步 (ETag / Last-Modified)
• 图片/语音: DiskLruCache

5.3 安全增强

• JWT 存储 → EncryptedSharedPreferences (非明文 SharedPreferences)
• SSL Pinning → 防中间人
• 生物识别 → BiometricPrompt (AndroidX)

5.4 导航架构建议

底部 Tab:
  🏠 首页 (HomeScreen)      → 快捷入口: 最近对话/推荐Agent/通知摘要
  💬 对话 (ChatScreen)      → 主对话界面
  🤖 Agent (AgentListScreen) → Agent 列表 + 市场入口
  🔔 通知 (NotificationScreen) → 推送列表
  ⚙️ 设置 (SettingsScreen)   → 设置 + 工作区切换

5.5 Compose 组件复用建议

复用 Web 端已验证的交互模式:

• 思考链: trace-step 组件逻辑 → LazyColumn + AnimatedVisibility
• 工具调用: tool-calls-header + tool-call-item → Card + Chip 组合
• 编排对话: orchestrate-result 折叠面板 → ExpandableCard
• 审批弹窗: approval_required 事件 → AlertDialog + 三按钮

---

六、交付里程碑

里程碑	范围	预计迭代
M1: 核心补齐	P0-1~P0-7 全部	1-2 sprint
M2: 体验完善	P1-1~P1-9 全部	2-3 sprint
M3: 增强特性	P2-1~P2-7 按需	3-4 sprint

---

文档结束 — 由产品经理 + 前端架构师 + 后端架构师联合编制