admin/aiagent
1
0
Fork 0
Code Issues 14 Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
beff3fac8d153e77295c6ea79a76209e9f7bf03d
aiagent/docs/android-ux-improvement-requirements.md
renjianbo beff3fac8d fix: delete agent 500 error + dynamic personality + deployment guide 
- Fix delete agent 500: clean up FK records (agent_llm_logs, permissions,
  schedules, executions, team_members) and unbind goals/tasks before delete
- Remove hardcoded personality templates in Android, replace with dynamic
  system prompt generation from name + description
- Set promptSectionsEnabled=false to bypass PromptComposer for personality
- Add Tencent Cloud Linux deployment guide (Docker Compose)
- Accumulated backend service updates, frontend UI fixes, Android app changes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-29 01:17:21 +08:00

294 lines
14 KiB
Markdown
Raw 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.
# 天工 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 |
---
*文档结束 — 由产品经理 + 前端架构师 + 后端架构师联合编制*
Reference in New Issue View Git Blame Copy Permalink