# 天工 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/*`)
```yaml
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/*`)
```yaml
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/*`)
```yaml
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/*`)
```yaml
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/*`)
```yaml
GET    /api/v1/template-market         # 模板列表
POST   /api/v1/platform/agents/from-template  # 从模板创建 Agent
```

### 4.6 定时任务 (`/api/v1/agent-schedules/*`)
```yaml
GET    /api/v1/agent-schedules         # 列表
POST   /api/v1/agent-schedules/{id}/toggle  # 启停
```

### 4.7 目标/任务 (`/api/v1/goals/*`, `/api/v1/tasks/*`)
```yaml
GET    /api/v1/goals                   # 目标列表
GET    /api/v1/goals/{id}              # 目标详情 + 任务树
GET    /api/v1/tasks                   # 任务列表
```

### 4.8 推送 (`/api/v1/push/*`, `/api/v1/fcm/*`)
```yaml
POST   /api/v1/fcm/register            # 注册设备 Token
GET    /api/v1/notifications           # 通知列表
PUT    /api/v1/notifications/{id}/read # 标记已读
```

### 4.9 语音 (`/api/v1/voice/*`)
```yaml
POST   /api/v1/voice/asr               # 语音转文字
POST   /api/v1/voice/tts               # 文字转语音
```

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

### 4.11 知识库 (`/api/v1/knowledge/*`)
```yaml
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 |

---

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