# 安智伴 · AI 数字人陪护终端（Android）

English | [中文](./README_zh.md)

> 本项目与 [digital-human-monitor-v2](https://github.com/user/digital-human-monitor-v2)（家属监护 Web 端）配合使用，共同构成完整的"AI 数字人 + 家庭远程关怀"解决方案。

---

## 目录

- [需求分析](#需求分析)
- [设计思路](#设计思路)
- [技术架构](#技术架构)
- [模块说明](#模块说明)
- [全链路数据流](#全链路数据流)
- [通信协议](#通信协议)
- [集成要求](#集成要求)
- [SDK 接口文档](#sdk-接口文档)
- [构建与运行](#构建与运行)

---

## 需求分析

### 背景

中国老龄化进程加速，独居或空巢老人的心理陪伴和安全监护成为刚需。子女因工作或地理距离无法陪伴，需要一种低门槛、有温度的技术方案来弥合亲情距离。

### 核心需求

| 需求维度 | 描述 |
|---------|------|
| **AI 陪伴对话** | 老人可随时与屏幕上的"数字人"自然语音对话，获得情感陪伴和生活助理服务 |
| **家庭留言桥梁** | 子女通过 Web 端发送关怀留言 → 数字人主动转达；老人口述留言 → 子女在 Web 端收到 |
| **使用行为上报** | 设备自动向云端上报使用事件（开屏、对话时长等），供家属了解老人日常 |
| **离线数字人渲染** | 数字人形象的 2D 渲染完全在本地完成（NCNN 推理 + OpenGL），无需 GPU 服务器 |
| **低门槛部署** | 老人无需任何操作，设备预装即可使用；家属扫码绑定即可监护 |

### 用户角色

| 角色 | 使用场景 |
|------|---------|
| **老人**（设备端） | 与数字人语音聊天、听取家人留言、口述回复 |
| **家属**（Web 端） | 发送留言、查看老人使用动态、接收推送通知 |

---

## 设计思路

### 1. 端云分离、各司其职

- **端侧（本项目）**：承担数字人渲染（完全离线）+ 实时 AI 对话（通过 Qwen Omni-Realtime 云端模型）+ 家庭消息同步
- **云侧（Monitor Web）**：承担家属身份管理、设备绑定、消息存储与分发、使用数据可视化

### 2. AI 对话与数字人解耦

DUIX SDK 仅负责"给定 PCM 音频 → 渲染对应口型/表情动画"，不关心音频来源。音频可来自：
- Qwen Omni-Realtime 模型的实时语音回复
- 本地 TTS 合成
- 任意 WAV 文件

这种解耦使得 AI 模型可独立升级，不影响渲染管线。

### 3. 工具调用实现双向留言

通过 Qwen 的 Function Calling 能力，在 AI 对话中注册两个工具函数：
- `leave_message_for_family`：老人口述 → AI 提取内容 → 调用工具 → 消息存入云端
- `fetch_family_messages`：老人想听留言 → AI 调用工具 → 拉取消息 → 口播转达

AI 自主判断何时调用工具，无需老人学习任何操作指令。

### 4. 面向老人的交互设计

- **语义 VAD**：采用 `semantic_vad` 而非传统声学 VAD，能过滤电视背景音、咳嗽等噪音，仅在老人真正说话时响应
- **主动播报**：对话开始时若有未读家人留言，AI 会主动口播转达，无需老人主动查询
- **温和人设**：系统 Prompt 设定为"面向中国老年群体的心理陪伴 AI"，使用温和、简短、生活化的中文回复

---

## 技术架构

### 系统全景

```
┌──────────────────────────────────────────────────────────────────┐
│                        Android 设备端                             │
│                                                                  │
│  ┌─────────────┐    PCM音频    ┌──────────────────────────────┐  │
│  │ Qwen Omni   │ ────────────→ │        DUIX SDK              │  │
│  │ Realtime    │               │ ┌────────────────────────┐   │  │
│  │ (WebSocket) │    AI回复语音  │ │ NCNN 推理引擎          │   │  │
│  │             │               │ │ (口型/表情/动作 推理)   │   │  │
│  └──────┬──────┘               │ └───────────┬────────────┘   │  │
│         │                      │             │ ImageFrame     │  │
│  语音   │ 文本               │ ┌───────────▼────────────┐   │  │
│  输入   │ +语音               │ │ OpenGL ES 2.0 渲染     │   │  │
│         │                      │ │ (DUIXRenderer)         │   │  │
│  ┌──────▼──────┐               │ └───────────┬────────────┘   │  │
│  │  麦克风录音  │               │             │               │  │
│  │  (16kHz PCM) │               │ ┌───────────▼────────────┐   │  │
│  └─────────────┘               │ │ GLTextureView (UI)     │   │  │
│                                └──────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │              FamilyBridgeService (HTTP)                   │    │
│  │  • 设备注册 → POST /api/device/register                   │    │
│  │  • 拉取留言 → GET  /api/device/messages                   │    │
│  │  • 标记已读 → POST /api/device/messages/read              │    │
│  │  • 上报事件 → POST /api/device/usage                      │    │
│  │  • 对话存档 → POST /api/device/conversations              │    │
│  │  • 工具记录 → POST /api/device/tool-call                  │    │
│  └──────────────────────────────┬───────────────────────────┘    │
└─────────────────────────────────┼────────────────────────────────┘
                                  │ HTTPS
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│           digital-human-monitor-v2 (Next.js 云端)                │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
│  │ 设备管理  │  │ 消息存储  │  │ 行为分析  │  │ Web Push 推送 │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘    │
│                       │                                          │
│                       ▼                                          │
│              ┌──────────────┐                                    │
│              │  PostgreSQL   │                                    │
│              └──────────────┘                                    │
└──────────────────────────────────────────────────────────────────┘
```

### 技术栈

| 层级 | 技术 |
|------|------|
| **数字人渲染** | NCNN (端侧推理) + OpenCV 4.6 + OpenGL ES 2.0 + ONNX Runtime |
| **AI 对话** | 千问 Qwen 3.5 Omni Plus Realtime (WebSocket) |
| **音频处理** | AudioRecord (16kHz) → PCM → Base64 → WebSocket；AudioTrack 播放 |
| **网络通信** | OkHttp 4 (HTTP API) + OkHttp WebSocket (Qwen Realtime) |
| **本地存储** | SharedPreferences (设备 UUID、配置) |
| **构建系统** | Gradle 8.13.2 + AGP 8.9.1 + JDK 17 (Temurin) |
| **语言** | Kotlin (应用层) + Java (SDK 层) + C++ (Native 推理层) |

---

## 模块说明

### 项目结构

```
dh_aigc_android/
├── duix-sdk/           # 核心 2D 数字人渲染 SDK（库模块）
│   ├── src/main/java/  # Java SDK 接口层
│   │   └── ai/guiji/duix/
│   │       ├── sdk/client/         # DUIX 主控、渲染、回调、工具类
│   │       └── duix/DuixNcnn.java  # JNI 接口
│   └── src/main/cpp/   # C++ Native 推理引擎
│       ├── dhcore/     # 核心数字人推理
│       ├── dhmfcc/     # 音频 MFCC 特征提取
│       ├── dhunet/     # 口型网络模型
│       └── third/      # 预编译依赖 (NCNN, OpenCV, ONNX, libjpeg)
│
├── test/               # 演示应用（应用模块）
│   └── src/main/java/ai/guiji/duix/test/
│       ├── ui/activity/
│       │   ├── MainActivity.kt        # 主页：模型选择与下载管理
│       │   ├── CallActivity.kt        # 核心：数字人渲染 + AI 对话 + 留言桥梁
│       │   ├── SettingsActivity.kt     # 设备设置
│       │   └── VoiceCloneSetupActivity.kt  # 声音克隆配置
│       ├── service/
│       │   ├── FamilyBridgeService.kt  # 家庭监护 API 客户端
│       │   ├── OmniRealtimeClient.kt   # Qwen Omni WebSocket 客户端
│       │   ├── QwenTtsRealtimeClient.kt # Qwen TTS 客户端
│       │   ├── VoiceCloneService.kt    # 声音克隆服务
│       │   └── DashScopeConfig.java    # API 配置常量
│       ├── audio/
│       │   ├── AudioResampler.java     # PCM 重采样
│       │   └── StreamingAudioRecorder.java  # 实时麦克风录音
│       └── camera/
│           └── CameraFrameCapture.java # 摄像头帧采集
│
└── qwen-docs/          # 千问 Omni-Realtime API 参考文档
    ├── main.md         # 协议总览
    ├── client_events.md    # 客户端事件定义
    ├── server_events.md    # 服务端事件定义
    └── function_calling.md # 工具调用机制
```

### duix-sdk — 数字人渲染引擎

| 类 | 职责 |
|----|------|
| `DUIX` | 主控对象：管理初始化、渲染循环、音频驱动、生命周期 |
| `RenderThread` | 独立渲染线程：逐帧推理 + 音频同步 |
| `DUIXRenderer` | OpenGL ES 2.0 渲染器：将 ImageFrame 渲染到 TextureView |
| `DUIXTextureView` | 自定义 TextureView：提供 GL 渲染表面 |
| `VirtualModelUtil` | 模型资源管理：下载、校验、解压 |
| `DuixNcnn` | JNI 桥接：调用 C++ 层 NCNN 推理 |

**渲染流水线**：
```
pushPcm(音频) → MFCC特征提取 → NCNN口型网络推理
→ 获取ImageFrame(图像+掩码) → OpenGL混合渲染 → TextureView显示
```

### test — 应用集成层

| 类 | 职责 |
|----|------|
| `CallActivity` | 整合 DUIX 渲染 + Qwen 对话 + 留言桥梁的核心页面 |
| `OmniRealtimeClient` | Qwen Omni-Realtime WebSocket 客户端，处理实时语音对话 |
| `FamilyBridgeService` | 家庭监护云 API 客户端，负责设备注册、消息同步、事件上报 |
| `MainActivity` | 模型选择与下载管理入口 |

---

## 全链路数据流

### 1. AI 实时对话

```
老人说话 → 麦克风录音 (16kHz PCM)
→ Base64 编码 → input_audio_buffer.append (WebSocket)
→ Qwen Omni 模型推理
→ response.audio.delta (Base64 PCM 回传)
→ 解码为 PCM → DUIX.pushPcm()
→ NCNN 推理口型动画 → OpenGL 渲染
→ 同时 AudioTrack 播放语音
```

### 2. 留言传递（老人 → 家属）

```
老人对 AI 说 "帮我给儿子带个话，说我挺好的"
→ Qwen 识别意图 → 触发 leave_message_for_family 工具
→ 提取 recipientRelation="儿子", message="我挺好的"
→ FamilyBridgeService → POST /api/device/conversations
→ Monitor Web 存入数据库
→ Web Push 通知家属
→ AI 回复老人 "好的，已经帮您告诉儿子了"
```

### 3. 留言传递（家属 → 老人）

```
家属在 Web 端发送留言 → 存入 FamilyMessage 表
→ 老人设备启动 AI 对话
→ FamilyBridgeService 拉取未读消息
→ 注入 AI 系统 Prompt: "家里人刚留了新留言，请主动转告..."
→ AI 在第一轮回复中口播: "您儿子给您捎了个话——记得吃药"
```

### 4. 使用行为上报

```
设备事件 (APP_OPEN / AI_SESSION_STARTED / TOOL_CALLED / ...)
→ FamilyBridgeService → POST /api/device/usage
→ Monitor Web 存入 UsageEvent 表
→ 家属在"陪伴动态"页面查看趋势图
```

---

## 通信协议

### Qwen Omni-Realtime WebSocket

| 方向 | 事件 | 用途 |
|------|------|------|
| C→S | `session.update` | 设置模态(text+audio)、语音、VAD、系统 Prompt、工具列表 |
| C→S | `input_audio_buffer.append` | 推送用户麦克风 PCM (Base64) |
| S→C | `response.audio.delta` | 模型语音回复增量块 (Base64 PCM) |
| S→C | `response.text.done` | 模型文本回复完成 |
| S→C | `response.function_call_arguments.done` | 工具调用请求 |
| C→S | `conversation.item.create` | 回传工具执行结果 |
| C→S | `response.create` | 触发模型基于工具结果生成最终回复 |

### 注册的 AI 工具

| 工具名 | 参数 | 用途 |
|--------|------|------|
| `leave_message_for_family` | `recipientRelation` (称谓), `message` (内容), `importance` (优先级) | 老人留言给家人 |
| `fetch_family_messages` | `count` (数量 1-5) | 拉取家人留言 |

### FamilyBridge HTTP API

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/device/register` | POST | 设备注册，返回 `deviceUuid` + `bindUrl` |
| `/api/device/messages` | GET | 拉取待送达消息 |
| `/api/device/messages/read` | POST | 标记消息已读 |
| `/api/device/usage` | POST | 上报使用事件 |
| `/api/device/conversations` | POST | 上传对话轮次 |
| `/api/device/tool-call` | POST | 记录工具调用日志 |

---

## 集成要求

| 项目 | 要求 |
|------|------|
| 系统版本 | Android 10+ (API 24+) |
| CPU 架构 | arm64-v8a, armeabi-v7a |
| 硬件 | 8 核 CPU (骁龙 8 Gen2), 8GB+ 内存, 1GB+ 存储 |
| 内存 | 数字人运行需 ≥ 800MB 可用内存 |
| 网络 | 数字人渲染：无需网络；AI 对话 + 监护同步：需联网 |
| 开发 IDE | Android Studio Giraffe 2022.3.1+ |
| JDK | OpenJDK 17 (Temurin) |
| Gradle | 8.13.2 (使用项目自带 wrapper) |

---

## SDK 接口文档

### 术语

| 术语 | 含义 |
|------|------|
| PCM | 16kHz 采样率、16bit 位深、Mono 单通道的原始音频流 |
| WAV | 支持 PCM 编码的音频文件格式 |
| RenderSink | 渲染数据接收接口，SDK 提供默认实现 |
| DUIX | 数字人主控对象 |
| ImageFrame | 包含 rawBuffer (图像) + maskBuffer (掩码) + 宽高的渲染帧 |

### 模型检查与下载

```kotlin
// 检查基础配置
VirtualModelUtil.checkBaseConfig(context): Boolean
// 下载基础配置
VirtualModelUtil.baseConfigDownload(context, url, callback)

// 检查模型
VirtualModelUtil.checkModel(context, modelUrl): Boolean
// 下载模型
VirtualModelUtil.modelDownload(context, modelUrl, callback)
```

### 初始化与渲染

```kotlin
// 构建 DUIX 实例
val duix = DUIX(context, modelUrl, renderSink) { event, msg, info ->
    when (event) {
        Constant.CALLBACK_EVENT_INIT_READY -> { /* 初始化完成 */ }
        Constant.CALLBACK_EVENT_INIT_ERROR -> { /* 初始化失败 */ }
        Constant.CALLBACK_EVENT_PLAY_START -> { /* 播放开始 */ }
        Constant.CALLBACK_EVENT_PLAY_END   -> { /* 播放结束 */ }
    }
}
duix.init()
```

### 音频驱动

```kotlin
// PCM 流式推送（用于实时 AI 语音）
duix.pushPcm(pcmBytes)

// WAV 文件播放
duix.playWav(wavFilePath)
```

### 资源释放

```kotlin
// 在 Activity onDestroy 中调用
duix.release()
```

---

## 构建与运行

### 环境准备

1. 安装 Android Studio Giraffe 2022.3.1+
2. 配置 JDK 17：`File → Settings → Build → Gradle → Gradle JDK → 选择 JDK 17`
3. 连接 Android 设备（需满足硬件要求）

### 编译安装

```bash
# 使用 Gradle Wrapper 编译安装 test 应用
./gradlew :test:installDebug
```

### 配置说明

API 密钥和服务地址在 `DashScopeConfig.java` 中配置：

```java
MONITOR_BASE_URL   // 监护 Web 服务地址
REALTIME_BASE_URL  // Qwen Omni WebSocket 地址
DEFAULT_API_KEY    // DashScope API Key
AUDIO_SAMPLE_RATE  // 音频采样率 (24000)
```

---

## 关联项目

| 项目 | 角色 | 仓库 |
|------|------|------|
| **dh_aigc_android**（本项目） | 老人端：AI 数字人陪护 + 设备行为上报 | 当前仓库 |
| **digital-human-monitor-v2** | 家属端：远程监护 Web 面板 + 消息管理 + 推送通知 | [digital-human-monitor-v2](../digital-human-monitor-v2/) |