251 lines
13 KiB
Markdown
251 lines
13 KiB
Markdown
# 天工智能体 Android 客户端 — 版本升级落地方案
|
||
|
||
> 基于两轮功能完整性评估（源码扫描 + 竞品对标）编制
|
||
> 评估日期: 2026-06-27 | 当前版本: v1.0.0 (Build 1)
|
||
|
||
---
|
||
|
||
## 一、版本规划总览
|
||
|
||
```
|
||
v1.0.0 ──→ v1.1.0 ──→ v1.2.0 ──→ v2.0.0
|
||
(当前) (紧急修复) (体验对齐) (能力突破)
|
||
|
||
v1.1.0: 修复阻塞缺陷 + 补齐对话核心交互 (预计 3-5 人天)
|
||
v1.2.0: 竞品体验对齐 + 通知推送完善 (预计 5-8 人天)
|
||
v2.0.0: 智能体管理闭环 + 离线能力 + 安全加固 (预计 8-12 人天)
|
||
```
|
||
|
||
---
|
||
|
||
## 二、v1.1.0 — 紧急修复版
|
||
|
||
### 目标：消除 P0 阻塞缺陷，补齐对话核心三大交互
|
||
|
||
### 2.1 后端必须配合的修复
|
||
|
||
| # | 问题 | 当前状态 | 修复方案 | 负责端 | 工时 |
|
||
|---|------|---------|---------|--------|------|
|
||
| 1 | `POST /api/v1/feedback` 返回 404 | 用户赞/踩操作必定失败，UI 乐观更新后回滚提示"反馈提交失败" | 后端新增 POST handler，接收 `FeedbackRequest`，写入 feedback 表 | 后端 | 0.5d |
|
||
| 2 | `POST /api/v1/fcm/register` 接口验证 | FCM 令牌注册 API 存在但未端到端验证 | 确认接口正常，支持 token 注册/注销 | 后端 | 0.5d |
|
||
|
||
### 2.2 Android 端修复清单
|
||
|
||
#### P0 — 阻塞性缺陷
|
||
|
||
| # | 功能 | 当前状态 | 修复方案 | 涉及文件 | 工时 |
|
||
|---|------|---------|---------|---------|------|
|
||
| 1 | **通知列表页** | API 存在但无 UI 页面，NavGraph 无对应路由 | 新增 `NotificationsScreen` + `NotificationsViewModel`，注册路由 `Routes.NOTIFICATIONS`，支持已读/未读标记 | `NavGraph.kt`、新建 `NotificationsScreen.kt`、`NotificationsViewModel.kt` | 1d |
|
||
| 2 | **FCM 推送集成** | `FcmTokenManager.initialize()` 是空操作，Firebase 依赖和 `google-services.json` 未添加 | 添加 Firebase deps → 放置 `google-services.json` → 取消 `FcmTokenManager` 中的注释代码 → 在 `TiangongApp.onCreate()` 调用 `initialize()` | `build.gradle.kts`、`FcmTokenManager.kt`、`TiangongApp.kt` | 1d |
|
||
|
||
#### P1 — 对话核心交互补齐
|
||
|
||
| # | 功能 | 当前状态 | 修复方案 | 涉及文件 | 工时 |
|
||
|---|------|---------|---------|---------|------|
|
||
| 3 | **停止生成** | 发送消息后无法中途停止 | 在 `ChatViewModel` 中暴露 `stopGeneration()` 方法（cancel SSE job），流式文本旁添加停止按钮 | `ChatViewModel.kt`、`ChatScreen.kt` | 0.5d |
|
||
| 4 | **消息重发** | 发送失败后无重试入口 | UI 在失败消息旁显示重试按钮，调用已有的 `sendMessage` 逻辑重新发起 | `ChatScreen.kt`、`ChatViewModel.kt` | 0.5d |
|
||
| 5 | **Think 推理可视化** | `SseEvent.Think` 事件被完全忽略（`ChatViewModel.kt:318` 空处理） | 新增 `ThinkTrace` 可折叠组件，接收迭代号和推理内容，折叠状态下显示"思考中…"，展开显示完整推理链 | 新建 `ThinkTrace.kt`、修改 `ChatViewModel.kt:318`、`ChatScreen.kt` | 1d |
|
||
|
||
### 2.3 v1.1.0 代码质量修复（附带）
|
||
|
||
| # | 位置 | 问题 | 修复 |
|
||
|---|------|------|------|
|
||
| Q1 | `AppModule.kt:81` | `runBlocking` 阻塞主线程读取 DataStore | 改用动态 BaseUrl 拦截器，避免 DI 阶段同步等待 |
|
||
| Q2 | `AgentListScreen.kt:65` | `uiState.error!!` 空安全风险 | 改用 `?.let { }` 安全调用 |
|
||
| Q3 | `SettingsScreen.kt:141` | 用户名硬编码 "admin" | 从 `GET /api/v1/auth/me` 获取真实用户名 |
|
||
|
||
### 2.4 v1.1.0 验收标准
|
||
|
||
- [ ] 赞/踩反馈能成功提交到后端并持久化
|
||
- [ ] 通知列表页可展示通知、标记已读
|
||
- [ ] FCM 推送能收到后台推送并跳转
|
||
- [ ] 流式生成过程中可点击停止
|
||
- [ ] 失败消息可重发
|
||
- [ ] Think 推理过程以卡片形式展示
|
||
- [ ] 编译 0 error，安装到测试机正常运行
|
||
|
||
---
|
||
|
||
## 三、v1.2.0 — 体验对齐版
|
||
|
||
### 目标：对齐 ChatGPT/Claude 核心交互体验，完善通知体系
|
||
|
||
### 3.1 对话增强
|
||
|
||
| # | 功能 | 竞品对标 | 修复方案 | 工时 |
|
||
|---|------|---------|---------|------|
|
||
| 1 | **编辑已发送消息** | ChatGPT / Claude 均支持 | 长按用户消息弹出菜单 → 点击编辑 → 进入编辑模式 → 重新发送编辑后的内容 | 1d |
|
||
| 2 | **重新生成回复** | ChatGPT / Claude 均支持 Regenerate | 最后一条助手消息旁添加"重新生成"按钮，复用 `sendMessage` 使用上一条用户消息文本 | 0.5d |
|
||
| 3 | **工具调用审批** | Claude 有工具权限确认弹窗 | 收到 `SseEvent.ToolCall` 时弹出审批对话框展示工具名和输入参数，用户确认后才允许执行（需后端支持 `tool_approval` 事件类型或 SSE 双向通信改造） | 2d |
|
||
| 4 | **对话重命名** | ChatGPT / Claude 均支持长按重命名 | `ConversationListScreen` 长按弹出菜单 → 重命名对话框 → 更新 Room 和 API | 0.5d |
|
||
| 5 | **对话搜索** | ChatGPT / Claude 均支持历史搜索 | 在 `ConversationListScreen` 顶部添加搜索栏，调用 `GET /api/v1/conversations?search=`（如后端支持）或本地 Room 全文搜索 | 1d |
|
||
|
||
### 3.2 通知体系完善
|
||
|
||
| # | 功能 | 修复方案 | 工时 |
|
||
|---|------|---------|------|
|
||
| 6 | 通知免打扰时段 | 设置页新增通知偏好（开启/关闭/免打扰时段），存储到 DataStore | 0.5d |
|
||
| 7 | 通知点击跳转 | FCM 通知点击 → 解析 deep link → 跳转对应对话 | 0.5d |
|
||
| 8 | 通知分组 | 按类型分组（系统通知/对话通知），Android 通知渠道适配 | 0.5d |
|
||
|
||
### 3.3 UI/UX 打磨
|
||
|
||
| # | 功能 | 修复方案 | 工时 |
|
||
|---|------|---------|------|
|
||
| 9 | **暗色主题 Markdown 适配** | `MarkdownRenderer.kt:68` 硬编码文字颜色改为从 Compose 主题动态获取 | 0.5d |
|
||
| 10 | 服务器地址动态更新 | 替换 `runBlocking` 方案，使用 OkHttp 动态 BaseUrl 拦截器，修改服务器地址后无需重启 | 1d |
|
||
| 11 | 离线网络提示 | 新增 `NetworkMonitor` 工具类（ConnectivityManager + Flow），离线时在 ChatScreen 顶部展示横幅 | 0.5d |
|
||
| 12 | 骨架屏优化 | `SkeletonChat` 增加更多变化（工具卡片骨架、流式文本骨架） | 0.5d |
|
||
| 13 | **底部快捷操作栏** | `ChatScreen` 底部输入区重构：语音按钮/附件按钮/停止生成按钮横向排列于输入框上方，停止按钮仅在流式生成时显示 | 0.5d |
|
||
| 14 | **左侧抽屉导航** | 实现 `ModalNavigationDrawer`，抽屉内容：当前智能体信息 + 历史对话列表（最近 10 条）+ 设置入口 + 退出登录。点击对话直接跳转，无需进入独立历史页面。参考 ChatGPT Android 交互模式 | 1d |
|
||
|
||
### 3.4 v1.2.0 验收标准
|
||
|
||
- [ ] 可编辑已发送的用户消息
|
||
- [ ] 可重新生成最后一条助手回复
|
||
- [ ] 工具调用前弹出审批确认
|
||
- [ ] 对话可重命名、搜索
|
||
- [ ] 暗色主题下 Markdown 文字清晰可见
|
||
- [ ] 修改服务器地址无需重启
|
||
- [ ] 离线时显示网络提示横幅
|
||
- [ ] 流式生成时输入框上方显示停止按钮
|
||
- [ ] 左侧抽屉可滑出，展示历史对话和设置入口
|
||
|
||
---
|
||
|
||
## 四、v2.0.0 — 能力突破版
|
||
|
||
### 目标：智能体管理闭环 + 安全加固 + 离线能力
|
||
|
||
### 4.1 智能体管理
|
||
|
||
| # | 功能 | 竞品对标 | 修复方案 | 工时 |
|
||
|---|------|---------|---------|------|
|
||
| 1 | **智能体详情页** | ChatGPT GPT 详情页 | 新增 `AgentDetailScreen`，展示工作流配置、预算配置、版本信息、工具列表 | 2d |
|
||
| 2 | **智能体创建/编辑** | ChatGPT GPT Builder | 新增 `AgentEditScreen`（表单：名称/描述/系统提示词/模型参数/工具选择），调用后端 CRUD API | 3d |
|
||
| 3 | **智能体部署/停止** | — | AgentListItem 添加操作菜单（启动/停止/删除），调用后端部署 API | 1d |
|
||
| 4 | 模型参数调节 | 高级设置 | 在智能体详情页或 ChatScreen 中暴露 temperature/max_iterations 参数调整 | 1d |
|
||
|
||
### 4.2 安全加固
|
||
|
||
| # | 功能 | 修复方案 | 工时 |
|
||
|---|------|---------|------|
|
||
| 5 | **生物识别锁** | 集成 `BiometricPrompt`（指纹/面部），App 进入后台超过 1 分钟 → 回到前台需验证 | 1d |
|
||
| 6 | **登录渐进锁定** | `LoginViewModel` 添加失败计数：5次失败 → 30秒冷却，10次 → 5分钟锁定 | 0.5d |
|
||
| 7 | SSL Certificate Pinning | OkHttp 添加 CertificatePinner，防止中间人攻击 | 0.5d |
|
||
|
||
### 4.3 离线与数据
|
||
|
||
| # | 功能 | 修复方案 | 工时 |
|
||
|---|------|---------|------|
|
||
| 8 | **离线消息缓存** | 启动时从 Room 读取最近对话列表展示，网络恢复后增量同步。实现 offline-first 读取策略 | 2d |
|
||
| 9 | **数据导出** | 设置页新增"导出对话数据"按钮 → 生成 JSON/ZIP → 系统分享 Sheet | 1d |
|
||
| 10 | **缓存清理** | 设置页新增"清除缓存"按钮 → 清空 Room DB + DataStore（保留 token） | 0.5d |
|
||
|
||
### 4.4 多模态扩展
|
||
|
||
| # | 功能 | 修复方案 | 工时 |
|
||
|---|------|---------|------|
|
||
| 11 | 文件上传 (PDF/DOCX等) | 扩展上传逻辑支持非图片文件，显示文件类型图标 | 1d |
|
||
| 12 | 拍照输入 | 添加相机 intent，拍照后自动压缩上传 | 0.5d |
|
||
|
||
### 4.5 v2.0.0 验收标准
|
||
|
||
- [ ] 可查看智能体详情（工作流/预算/工具）
|
||
- [ ] 可创建和编辑智能体
|
||
- [ ] 生物识别锁正常工作
|
||
- [ ] 连续登录失败触发冷却时间
|
||
- [ ] 离线时能查看历史对话
|
||
- [ ] 支持数据导出和缓存清理
|
||
|
||
---
|
||
|
||
## 五、代码质量修复路线图
|
||
|
||
<!-- 附带修复，分配到各个版本中 -->
|
||
|
||
| # | 位置 | 问题 | 修复版本 | 工时 |
|
||
|---|------|------|---------|------|
|
||
| Q1 | `AppModule.kt:81` | `runBlocking` 阻塞主线程 | v1.2.0 (动态 URL 拦截器) | 1d |
|
||
| Q2 | `AgentListScreen.kt:65` | `uiState.error!!` NPE 风险 | v1.1.0 | 0.1d |
|
||
| Q3 | `MarkdownRenderer.kt:68` | 硬编码文字颜色 | v1.2.0 | 0.5d |
|
||
| Q4 | `SseClient.kt:108,134,193` | 每次重连创建新 CoroutineScope | v1.1.0 (统一用 viewModel 管理) | 0.3d |
|
||
| Q5 | `ChatViewModel.kt:151,161` | 静默吞异常 | v1.1.0 (添加日志) | 0.1d |
|
||
| Q6 | `ChatViewModel.kt:318` | Think 事件空实现 | v1.1.0 (ThinkTrace 组件) | 1d |
|
||
| Q7 | `VoiceInputButton.kt:132,149` | 录音错误无提示 | v1.1.0 (Toast 提示) | 0.1d |
|
||
| Q8 | `SettingsScreen.kt:141` | 用户名硬编码 | v1.1.0 (API 获取) | 0.2d |
|
||
| Q9 | `SettingsScreen.kt:217` | 服务器变更需重启 | v1.2.0 (动态 URL) | 1d |
|
||
|
||
---
|
||
|
||
## 六、工时汇总
|
||
|
||
| 版本 | 范围 | 前端工时 | 后端工时 | 合计 |
|
||
|------|------|---------|---------|------|
|
||
| v1.1.0 | 紧急修复 (3新增 + 6修复 + 附带质量) | 5.8 人天 | 1 人天 | **6.8 人天** |
|
||
| v1.2.0 | 体验对齐 (5对话增强 + 3通知 + 6UI打磨) | 10 人天 | 1 人天 | **11 人天** |
|
||
| v2.0.0 | 能力突破 (4智能体 + 3安全 + 3离线 + 2多模态) | 13 人天 | 2 人天 | **15 人天** |
|
||
| **总计** | | **28.8 人天** | **4 人天** | **32.8 人天** |
|
||
|
||
---
|
||
|
||
## 七、里程碑与交付节奏
|
||
|
||
```
|
||
Week 1 ──────── Week 2 ──────── Week 3-4 ────── Week 5-6
|
||
|
||
v1.1.0 开发 v1.2.0 开发 v1.2.0 收尾 v2.0.0 开发
|
||
├─ 反馈API ├─ 编辑/重生成 ├─ 测试/修bug ├─ 智能体管理
|
||
├─ 通知列表 ├─ 工具审批 ├─ 灰度发布 ├─ 离线缓存
|
||
├─ FCM集成 ├─ 暗色主题 │ ├─ 安全加固
|
||
├─ 停止/重发 ├─ 动态URL │ ├─ 文件上传
|
||
├─ ThinkTrace ├─ 离线提示 │ └─ 测试发布
|
||
└─ 代码质量 ├─ 对话管理 │
|
||
├─ 快捷操作栏 │
|
||
└─ 抽屉导航 │
|
||
↓ ↓ ↓ ↓
|
||
v1.1.0 v1.2.0 v1.2.1 v2.0.0
|
||
(第1周末) (第3周末) (第4周) (第6周末)
|
||
```
|
||
|
||
---
|
||
|
||
## 八、风险与依赖
|
||
|
||
| # | 风险 | 影响 | 应对措施 |
|
||
|---|------|------|---------|
|
||
| 1 | 后端反馈接口未及时上线 | v1.1.0 阻塞 | 提前与后端对齐，确认 feedback 表结构和路由 |
|
||
| 2 | `google-services.json` 获取困难 | FCM 推送延期 | 提前向 Firebase 项目管理员申请 |
|
||
| 3 | 工具审批需后端 SSE 协议改造 | v1.2.0 延期 | 先实现 UI 端准备，后端改造可降级为"仅展示审批结果" |
|
||
| 4 | 智能体 CRUD API 后端未实现 | v2.0.0 范围缩减 | 与后端确认 API 开发排期，必要时 v2.0 先做只读详情 |
|
||
|
||
---
|
||
|
||
## 九、附录：两次评估发现汇总对照
|
||
|
||
### 第一次评估（API 测试 + 编译验证）
|
||
|
||
| 类别 | 发现 | 状态 |
|
||
|------|------|------|
|
||
| API | 16/19 端点正常工作 | 已确认 |
|
||
| API | `POST /api/v1/feedback` → 404 | v1.1.0 修复 |
|
||
| 编译 | `TokenDataStore.clearAll()` Boolean? 类型错误 | 已修复 |
|
||
| 编译 | `AuthInterceptor.performReLogin()` 挂起函数调用错误 | 已修复 |
|
||
| 编译 | `AgentListViewModel.debounce()` 缺少 FlowPreview | 已修复 |
|
||
| 编译 | BUILD SUCCESSFUL, 0 errors | 通过 |
|
||
|
||
### 第二次评估（源码扫描 + 竞品对标）
|
||
|
||
| 类别 | 数量 |
|
||
|------|------|
|
||
| 已实现功能 | 22 项 |
|
||
| P0 阻塞缺陷 | 3 项 |
|
||
| P1 严重缺失 | 7 项 |
|
||
| P2 一般缺失 | 8 项 |
|
||
| 代码质量问题 | 9 项 |
|
||
| 竞品覆盖度 vs ChatGPT | 62% |
|
||
|
||
---
|
||
|
||
> 文档版本: v1.0 | 编制: 基于 Claude Code 源码分析 | 下次评审: v1.1.0 发布后
|