Files

renjianbo 1693292bbd feat: SSML emotional TTS, agent avatars, AgentChat UX overhaul, virtual company enhancements

- SSML TTS with emotional styles (_build_ssml, mstts:express-as) and natural pauses
- Agent avatar support: DB migration, API, frontend emoji/URL rendering
- AgentChat UX: highlight.js code blocks, copy buttons, streaming cursor, char count,
  auto-title, keyboard shortcuts, message feedback (thumbs), undo delete, mobile responsive
- Virtual company: M2 control, tier-3/4 capabilities, per-dept session fix, deliverable
  validator, insight analyzer enhancements
- New services: agent_profiler, deliverable_validator, redis_task_registry
- Android: auth refactor, launcher icons, network security config, update manager
- Frontend: useSpeechQueue composable, Agents/AgentConfig/AgentTest enhancements
- Various backend fixes and expanded test coverage

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-08-01 23:22:38 +08:00

14 KiB

Raw Blame History

天工智能体 Android 客户端 PRD 文档

版本: v1.3.0 (versionCode=4) 更新日期: 2026-07-27 目标平台: Android 8.0+ (API 26+)，目标 API 34

1. 产品概述

天工智能体 Android 客户端是天工 AI Agent 平台的移动端入口，与 Web 前端（localhost:3001）和后端（101.43.95.130:8037）共享同一套 API。用户可通过手机完成 Agent 对话、语音输入、智能体管理、消息推送等全部核心操作。

核心价值

随身 AI 助手: 随时随地与 Agent 对话，支持流式实时输出
多 Agent 切换: 支持多个自定义 Agent，每个 Agent 独立会话
语音交互: 内置录音转文字（ASR）和文本转语音（TTS）
离线队列: 无网络时消息自动暂存，恢复网络后自动发送

2. 目标用户

用户类型	描述	核心需求
普通用户	日常 AI 对话使用者	流畅对话、语音输入、消息推送
高级用户	Agent 创建/管理者	多 Agent 切换、知识库管理、自定义配置
开发者	调试/测试服务器	服务器地址配置、网络诊断

3. 技术架构

3.1 技术栈

层级	技术选型
UI	Jetpack Compose + Material 3
导航	Navigation Compose（17 个路由）
DI	Hilt + Dagger
网络	Retrofit + OkHttp + Gson
SSE 流式	自定义 SseClient（callbackFlow）
本地存储	Room（消息/会话缓存）+ DataStore（偏好设置）
安全存储	AndroidX EncryptedSharedPreferences（AES256-GCM）
图片加载	Coil Compose
Markdown 渲染	Markwon
音频播放	Media3 ExoPlayer
音频录制	MediaRecorder
推送	Firebase Cloud Messaging
崩溃上报	Tencent Bugly
数据统计	Umeng

3.2 架构模式: MVVM + Repository

┌──────────────────────────────────────────────┐
│  UI Layer (Compose Screens)                  │
│  观察 StateFlow<UiState>，用户操作 → VM      │
└──────────────────┬───────────────────────────┘
                   │ Hilt 注入
┌──────────────────▼───────────────────────────┐
│  ViewModel Layer (7 个 @HiltViewModel)        │
│  MutableStateFlow + viewModelScope.launch     │
└──────────────────┬───────────────────────────┘
                   │
┌──────────────────▼───────────────────────────┐
│  Repository Layer (7 个 Repository)           │
│  桥接网络 API 与本地数据源                     │
└────────┬──────────────────┬──────────────────┘
         │                  │
┌────────▼────────┐  ┌──────▼──────────────────┐
│ Remote (API)    │  │ Local (Room + DataStore) │
│ ApiService (52  │  │ AppDatabase (3 表)       │
│ 个端点)         │  │ TokenDataStore (偏好)    │
│ SseClient       │  │ CredentialStore (加密)   │
│ Interceptors x3 │  │ OfflineQueue             │
└─────────────────┘  └─────────────────────────┘

3.3 OkHttp 拦截器链

顺序	拦截器	职责
1	DynamicUrlInterceptor	动态改写请求 URL（支持运行时切换服务器）
2	AuthInterceptor	注入 Bearer Token（仅信任主机），401 自动刷新
3	HttpLoggingInterceptor	请求/响应日志（Debug: BODY, Release: NONE）

3.4 超时策略

类型	超时
连接超时	30s
写入超时	30s
读取超时	0ms（无限，SSE 流式需要）

4. 导航流程

4.1 路由启动决策

SplashScreen (1.5s 品牌动画)
├── !onboardingCompleted → OnboardingScreen（引导页）
├── token == null        → LoginScreen（密码登录）
└── token + onboarded    → ChatScreen（主界面）

4.2 完整路由表（17 条）

路由	页面	说明
`splash`	启动页	品牌动画 + Token 验证
`login`	密码登录	用户名+密码，长按标题配置服务器
`register`	注册	用户名/邮箱/密码/确认密码
`phone_login`	手机登录	验证码登录
`onboarding`	引导页	新用户首次引导
`chat`	主界面	对话列表+输入+抽屉导航
`agents`	Agent 管理	创建/删除/编辑智能体
`agent_market`	Agent 市场	浏览/安装市场智能体
`history`	对话历史	全部会话列表
`settings`	设置	主题/通知/语音/TTS
`about`	关于	版本信息
`account_security`	账号安全	修改密码/手机号
`subscription`	订阅	套餐购买
`memory_manage`	记忆管理	Agent 知识库 CRUD
`notification_detail`	通知详情	推送消息查看
`notifications`	通知列表	全部推送消息
`network_diagnose`	网络诊断	连通性测试

5. 功能清单

5.1 核心对话 (ChatScreen)

功能	状态	说明
流式对话	v1.0	SSE 实时流式输出，支持 Think→ToolCall→ToolResult→Message 事件序列
多 Agent 切换	v1.0	TopAppBar 下拉选 Agent，抽屉显示全部 Agent
消息重发	v1.1	失败消息支持重试
Think 追踪面板	v1.1	可折叠，展示 Agent 推理过程
停止生成	v1.2	停止后保留已输出内容，不会丢失半截消息
编辑消息	v1.2	编辑已发送的用户消息并重新生成回复
重新生成	v1.2	对最后一条 Assistant 消息重新生成
工具调用审批	v1.2	Agent 调用工具前弹审批条，用户可允许/拒绝
历史加载	v1.3	上拉无限加载历史消息
消息排队	v1.3	流式输出期间可继续输入，自动排队发送
离线队列	v1.2	无网络时消息暂存 Room，恢复网络后自动发送

5.2 语音交互

功能	说明
录音转文字	MediaRecorder 录制 AAC → 上传 ASR → 填入输入框
文字转语音	Assistant 消息旁有朗读按钮 → TTS → ExoPlayer 播放
实时波形	录音按钮显示波形反馈

5.3 消息交互

功能	说明
Markdown 渲染	消息气泡内支持 Markdown 格式，代码块/表格/列表
消息反馈	点赞/踩 + 可选文字评论
复制消息	长按消息复制全文
分享消息	分享到系统分享面板
图片发送	Coil 选图 → 上传 → 消息内嵌图片

5.4 推送通知

功能	说明
FCM 推送	Firebase 消息接收，支持数据消息
本地通知	NotificationHelper 创建通知渠道并显示
未读角标	TopAppBar 铃铛图标显示未读数

5.5 APP 更新

功能	说明
版本检查	启动时检查 /api/v1/app/check-update
强制更新	返回 `force=false` 弹窗提示，`force=true` 全屏不可关闭
SHA256 校验	下载 APK 后校验哈希，不匹配则拒绝安装
URL 白名单	仅允许 `https://*.tiangong.ai` 域名下载

5.6 离线支持

功能	说明
离线检测	NetworkMonitor（ConnectivityManager 回调）
消息暂存	Room pending_messages 表
自动回放	恢复网络后按创建时间顺序发送
离线提示	输入框禁用 + 顶部离线横幅

6. 安全设计

6.1 网络安全

措施	实现
HTTPS 强制	`usesCleartextTraffic=false`，仅本地开发地址豁免
证书校验	系统默认证书链校验
域名白名单	network_security_config.xml 定义可信域名
URL 白名单	DynamicUrlInterceptor 拒绝非本地 HTTP 地址
APK 下载白名单	AppUpdateManager 仅允许 `https://*.tiangong.ai`
APK 哈希校验	服务端返回 SHA256，客户端下载后校验
Host 校验	AuthInterceptor 仅向信任主机发送 Authorization 头

6.2 数据安全

措施	实现
Token 加密存储	AndroidX EncryptedSharedPreferences（AES256-GCM）
密码不存储	不在本地留存密码，401 跳转登录页
备份保护	`allowBackup=false`，禁止 adb backup 导出数据
API Key 外置	Bugly KEY 从 local.properties 注入，不提交 git
google-services.json	已从 git 移除

6.3 服务器地址访问控制

层级	控制
UI	长按"密码登录"标题才显示配置入口（普通用户不可见）
DynamicUrlInterceptor	非内网 IP 的 HTTP 地址直接拒绝
AuthInterceptor	非信任主机不发送 Authorization 头

7. API 集成

7.1 ApiService 端点分组（52 个端点）

分组	端点数	主要操作
认证	10	登录/注册/刷新/改密/手机验证码/注销
Agent	5	CRUD + 列表查询
对话	2	非流式对话（流式走 SseClient）
语音	2	ASR 转写 + TTS 合成
通知	3	未读数/列表/已读标记
文件上传	1	图片/文件上传
FCM	2	注册/注销推送 Token
反馈	1	消息点赞/踩 + 评论
会话管理	4	消息历史/会话列表/更新/删除
消息搜索	1	全文搜索
Agent 记忆	14	知识库/学习模式/向量记忆 CRUD + 导入导出
APP 更新	1	版本检查
统计	1	事件上报
Agent 市场	9	浏览/安装/评分/收藏/分类
模板市场	2	浏览/使用模板
场景模板	2	预设场景模板
计费	6	套餐/订阅/用量/订单/支付

7.2 SSE 事件类型（9 种）

事件	说明
`Message`	流式文本内容片段
`Think`	Agent 推理过程
`ToolCall`	Agent 调用工具（触发审批）
`ToolResult`	工具调用结果
`Final`	最终完整内容
`Plan`	Agent 执行计划
`Done`	流结束（无 Final 时的兜底）
`Error`	服务端错误
`ConnectionError`	客户端连接错误（含重连次数）

8. 错误处理

8.1 用户友好错误映射

原始异常	用户提示
`ConnectException`	网络连接失败，请检查网络设置
`SocketTimeoutException`	请求超时，请稍后重试
`UnknownHostException`	无法连接到服务器，请检查地址
`SSLHandshakeException`	安全连接失败，请检查服务器证书
HTTP 401	用户名或密码错误
HTTP 403	账号已被禁用
HTTP 429	请求过于频繁，请稍后重试
HTTP 5xx	服务器繁忙，请稍后重试

8.2 错误横幅行为

错误不自动消失（用户可读完整信息）
提供"重试"按钮（调用最近失败的消息重发）
提供"关闭"按钮（手动关闭）
横幅优先级: 错误 > 重连失败 > 离线 > 重连中 > 工具审批

9. 本地数据库

9.1 Room 表结构

表	用途
`messages`	消息本地缓存（id, conversationId, agentId, role, content, toolName, toolInput, toolOutput, tokenUsage, createdAt）
`conversations`	会话列表（sessionId, agentId, agentName, title, lastMessage, lastMessageAt, messageCount, isPinned）
`pending_messages`	离线消息队列（id, agentId, message, sessionId, createdAt）

9.2 DataStore 偏好

Key	类型	说明
`server_url`	String	动态服务器地址
`theme_mode`	Int	0=System, 1=Light, 2=Dark
`voice_enabled`	Boolean	语音输入开关
`tts_enabled`	Boolean	语音朗读开关
`current_agent_id`	String	当前选中的 Agent
`last_session_id`	String	上次会话 ID
`onboarding_completed`	Boolean	引导完成标记

10. 版本历史

版本	versionCode	主要变更
v1.0.0	1	初始版本：基础对话、Agent 列表、登录/注册
v1.1.0	—	Think 追踪面板、消息重试、会话管理
v1.2.0	—	动态 URL 切换、离线队列、停止保留内容、编辑消息、重新生成、工具审批、计费模块
v1.3.0	4	拉取历史消息、流式输入解锁（消息排队）、安全加固（HTTPS/Token加密/APK校验）、UX 修复

11. 第三方 SDK

SDK	版本	用途
Firebase BOM	—	推送消息（FCM）
Tencent Bugly	—	崩溃上报
Umeng	—	数据统计
Markwon	—	Markdown 渲染
Coil	—	图片加载
Media3 ExoPlayer	—	音频播放

12. 构建配置

配置项	值
compileSdk	34
minSdk	26 (Android 8.0)
targetSdk	34
JVM Target	17
包名	`com.tiangong.aiagent`
应用名	天工智能体
默认服务器	`http://101.43.95.130:8037/`
代码混淆	Release 开启（ProGuard）

13. 已知限制与下阶段规划

已知限制

后端无 HTTPS 证书，云服务器仍走 HTTP（通过 network_security_config 单独豁免）
未实现消息端到端加密
大文件上传无分片/断点续传
无多语言支持（仅中文）
未适配平板/Fold 大屏布局

建议下阶段

后端升级 HTTPS + WebSocket（替代 SSE）
消息本地全文搜索（FTS）
桌面小部件（App Widget）
快捷方式（Shortcuts）
无障碍适配（TalkBack）

本文档基于代码实际状态生成（2026-07-27），版本 v1.3.0。项目路径: D:\workspace\aiagent\android

14 KiB Raw Blame History Unescape Escape

天工智能体 Android 客户端 PRD 文档

1. 产品概述

核心价值

2. 目标用户

3. 技术架构

3.1 技术栈

3.2 架构模式: MVVM + Repository

3.3 OkHttp 拦截器链

3.4 超时策略

4. 导航流程

4.1 路由启动决策

4.2 完整路由表（17 条）

5. 功能清单

5.1 核心对话 (ChatScreen)

5.2 语音交互

5.3 消息交互

5.4 推送通知

5.5 APP 更新

5.6 离线支持

6. 安全设计

6.1 网络安全

6.2 数据安全

6.3 服务器地址访问控制

7. API 集成

7.1 ApiService 端点分组（52 个端点）

7.2 SSE 事件类型（9 种）

8. 错误处理

8.1 用户友好错误映射

8.2 错误横幅行为

9. 本地数据库

9.1 Room 表结构

9.2 DataStore 偏好

10. 版本历史

11. 第三方 SDK

12. 构建配置

13. 已知限制与下阶段规划

已知限制

建议下阶段

14 KiB

Raw Blame History