# ShowenV2 — 数字生命窗口平台

## 愿景
ShowenV2 不仅是全息宠物播放器，而是一个**通用数字生命窗口平台**。

支持的显示模式：
- **全息显示** — 半透镜 45° 伪全息（当前硬件）
- **VR** — 头显输出（未来）
- **AR** — 增强现实叠加（未来）
- **直接屏幕** — 普通显示器/手机/平板

支持的内容类型：
- **宠物动画** — 视频状态机驱动的虚拟宠物（当前核心）
- **3D 模型** — 实时渲染 3D 角色/物体
- **数字人** — AI 驱动的虚拟形象
- **AI 歌姬** — 人工歌姬/虚拟歌手
- **未来内容** — 通过插件无限扩展

核心理念：**平台不关心内容是什么，插件决定一切**。

---

## 项目信息
- 旧项目: `/home/showen/Showen/hologram_player_rust/` (单体全息宠物播放器)
- 新项目: `/home/showen/Showen/ShowenV2/`
- 架构: 跨平台插件内核 + 功能插件

---

## 架构概览

```
┌─────────────────────────────────────────────────────┐
│                    main.rs                          │
│   加载配置 → 按平台注册插件 → ServiceManager.run()   │
├─────────────────────────────────────────────────────┤
│              core/ (跨平台内核，零业务逻辑)           │
│  ServiceManager  — 插件注册/生命周期/消息路由         │
│  Plugin trait    — 统一插件接口                      │
│  Message enum    — 类型安全的消息协议                │
│  Config          — 配置解析/验证（纯 serde）         │
├─────────────────────────────────────────────────────┤
│              plugins/ (一切皆插件)                   │
│                                                     │
│  ┌─ 渲染引擎 ─────────────────────────────────┐     │
│  │ video/   — 视频播放 (OpenCV, 当前核心)      │     │
│  │ render/  — 3D渲染引擎 (未来: wgpu/vulkan)  │     │
│  │ avatar/  — 数字人驱动 (未来: Live2D等)      │     │
│  └────────────────────────────────────────────┘     │
│                                                     │
│  ┌─ 显示后端 ─────────────────────────────────┐     │
│  │ screen/  — 屏幕管理 (X11/fbv/唤醒锁/光标) │     │
│  │ vr/      — VR 输出 (未来: OpenXR)          │     │
│  │ ar/      — AR 叠加 (未来)                  │     │
│  └────────────────────────────────────────────┘     │
│                                                     │
│  ┌─ 连接/交互 ────────────────────────────────┐     │
│  │ http/    — Web UI + REST API (warp)        │     │
│  │ ble/     — BLE 配网 (dbus BlueZ)           │     │
│  │ wifi/    — WiFi 管理 (nmcli)               │     │
│  │ voice/   — 语音交互 (未来: ASR/TTS)        │     │
│  │ sensor/  — 传感器输入 (未来: GPIO/触摸)     │     │
│  └────────────────────────────────────────────┘     │
│                                                     │
│  ┌─ AI 引擎 ──────────────────────────────────┐     │
│  │ ai/      — LLM 对话 (未来)                 │     │
│  │ singer/  — AI 歌姬 (未来: 歌声合成)        │     │
│  └────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────┘
```

**关键**: 内核 core/ 完全不知道"宠物""歌姬""3D模型"的存在。
它只知道"插件发消息、收消息、有生命周期"。
内容类型、显示方式、交互模式全部由插件组合决定。

---

## 当前实现范围 (Phase 1)

Phase 1 的目标：**完整迁移旧功能到新架构**，确保在 ARM 设备上运行正常。

| 插件 | 来源 | 平台 | 状态 |
|------|------|------|------|
| core/ | 新建 | Any | 进行中 |
| plugins/video/ | video_processor.rs + state_machine.rs | OpenCV | 待迁移 |
| plugins/http/ | api_server.rs | warp | 待迁移 |
| plugins/ble/ | ble_service.rs | Linux dbus | 待迁移 |
| plugins/screen/ | screen_wake_lock.rs | Linux | 待迁移 |
| plugins/wifi/ | api_server.rs WiFi部分 | Linux nmcli | 待迁移 |

未来 Phase 的插件 (render/, avatar/, vr/, ar/, voice/, ai/, singer/) 只需定义接口预留，不实现。

---

## 提交计划

### Commit 1: 项目骨架 + 愿景文档
- [x] PROGRESS.md 平台愿景与架构
- [x] Cargo.toml, rust-toolchain.toml
- [ ] core/plugin.rs — Plugin trait + PluginInfo + PluginContext + Platform
- [ ] core/message.rs — Message/Envelope/Destination (通用消息，不限于宠物)
- [ ] core/service_manager.rs — ServiceManager 骨架
- [ ] core/config.rs — AppConfig 类型定义
- [ ] core/mod.rs, lib.rs
- [ ] plugins/ 空桩 (video, http, ble, screen, wifi)
- [ ] main.rs 入口
- 验证: `cargo check` 通过

### Commit 2: 配置系统完整实现
- [ ] core/config.rs 完整验证逻辑
- [ ] configs/dog_state_machine.json, cat_state_machine.json

### Commit 3: ServiceManager 消息路由
- [ ] register(), start_all(), run(), stop_all()
- [ ] mpsc 通道消息循环 + Broadcast 支持

### Commit 4: VideoPlugin 视频播放
- [ ] plugins/video/processor.rs (VideoTransformer + VideoProcessor)
- [ ] plugins/video/state_machine.rs (StateMachine)
- [ ] plugins/video/mod.rs (Plugin trait impl)

### Commit 5: HttpPlugin HTTP API
- [ ] plugins/http/routes.rs (warp 路由)
- [ ] plugins/http/mod.rs (Plugin trait impl)
- [ ] 内嵌 Web UI HTML

### Commit 6: BlePlugin (含 LocalName 修复)
- [ ] plugins/ble/gatt.rs — 双 D-Bus 连接修复
- [ ] plugins/ble/mod.rs (Plugin trait impl)

### Commit 7: ScreenPlugin + WifiPlugin
- [ ] plugins/screen/mod.rs (唤醒锁+光标)
- [ ] plugins/wifi/mod.rs (nmcli)

### Commit 8: 集成 main.rs + 编译验证
- [ ] 串联所有插件
- [ ] cargo build --release

---

## 关键决策记录
1. **Rust edition 2018** — 兼容设备 stable toolchain
2. **std::sync::mpsc** 消息传递 — VideoPlugin 在阻塞线程运行，不能全异步
3. **BLE 双连接修复** — conn_server 处理回调, conn_client 同步注册
4. **Message 枚举通用化** — 不绑定特定内容类型，Custom 变体支持未来插件
5. **Platform 枚举** — 插件声明自己适用的平台，main.rs 按运行时平台选择
6. **项目名 ShowenV2** — 不叫 hologram_player，因为不止全息