# MeowOS 开发计划（HiBy R3 Pro II）

> 目标：把 R3 Pro II 打造成可扩展的"第二系统"。**MeowOS 作为主控层优先启动、拥有屏幕与输入；HibyOS 播放器降级为 MeowOS 启动的一个内置系统应用**（Android home/launcher 模型）。MeowLauncher（即 MeowOS 核心）、MeowAPPs、MeowPanel 均为其组成部分。
> 本文档是路线图与分阶段计划。当前技术档案见 `ANALYSIS.md`，应用规范见 `APPS.md`，框架协议见 `FRAMEWORK_DESIGN.md`。

---

## 0. 总览与已达成里程碑

**已达成（真机验证）：**
- ✅ 官方固件 v1.4 逆向 / 解包 / 无损重打包链路
- ✅ SSH 固件（dropbear 双认证 + 14 工具）—— 已刷入，长期可用
- ✅ 全量 NAND 备份（TF 卡 `firmware_backup_1.4/`）
- ✅ MeowLauncher 零 patch 架构：热键（按住电源+音量减，窗口 60–2500ms）→ 应用列表菜单
- ✅ 应用列表、5 种边界处理、虚拟返回键、沉浸手势（左缘滑动）、统一日志系统（TF 卡，无卡回退内存缓冲）
- ✅ 纯黑 UI + 状态栏；fb0 双缓冲翻页机制（菜单可见性根因）
- ✅ 应用启动/退出/回列表全链路（让位机制：SIGSTOP/SIGCONT + fb 备份恢复）

**关键约束（教训已固化为纪律）：**
- 严禁对 `hiby_player` 发未注册信号（SIGUSR1 实测导致整机重启）
- `hiby_player` 只能 SIGSTOP/SIGCONT，不能 killall（其 `hiby_player.sh` 看门狗会整机 reboot）
- 播放器为**事件驱动绘制**（无持续刷屏循环）→ 恢复画面必须"备份→还原+翻页→SIGCONT"
- fb0 为**双缓冲**（虚拟高 1440，2×720），显示帧由 `yoffset` 决定，须 `FBIOPAN_DISPLAY` 翻页
- 厂商内核**触摸/按键注入不投递**（`input_inject_event` 需 grab==handle）；uinput 是阉割版
- 播放器「背光时间」会自动息屏（亮度 0 + FBIOBLANK(4)）——任何亮度/面板干预都必须尊重它，只做"兜底+恢复"不做"对抗"
- 板载存储紧张（/data 仅 ~16MB）——日志/资源一律放 TF 卡，无卡绝不用板载

---

## 1. 分阶段路线图

### 阶段 0：双系统引导模型（用户定案，Phase 0 最终方案）—— **隐藏的地基，优先于应用模型**
> 战略方向：开机由 MeowOS 引导选单决定运行哪个系统；两系统互斥运行，任一时刻只管一个，内存充足，绕开 HGL 碎片化问题（MeowOS 界面只用普通 fb0 不需要 sa_hgl_dma，只有播放器需要且须开机连续内存才能启动）。

**双模式**：
- **HibyOS 模式**：选单后尽早拉起播放器（内存连续，双拿 fb0+HGL），全程官方体验。热键(电源+音量减) → **弹确认框** → 「是」**完全杀死播放器** → MeowOS 接管（MeowOS 界面不需要 HGL，接管无缝）；「否」留在 HibyOS。（M2 已实现：**MeowOS 与 HibyOS 永不并发**，MeowOS 不控制 HibyOS 播放器媒体。）
- **MeowOS 模式**：选单后完全不碰播放器，只跑 MeowOS（64MB 全给 MeowOS；音乐由 MeowAPPs 直接出）。
- **切换规则**：HibyOS→MeowOS 用热键（杀播放器即可）；MeowOS→HibyOS 只能重启回到选单（播放器需开机连续内存才能再次启动）。

**关键事实（§18.21 修正应用）**：
- MeowOS 界面路径：/dev/fb0 mmap + pan（不需要 sa_hgl_dma）。
- 播放器路径：需 /dev/fb0 + /dev/sa_hgl_dma（1.32MB 连续 DMA），仅在开机内存连续时可获取；重拉失败。
- ⇒ 单系统互斥运行：无并发内存竞争，无 SIGSTOP 让位需求（该机制退役）。

**实现要点**：
- init 改造：S90 meow_launcherd 变为**引导选单**（轻量 fb 绘制 + 触摸/按键选择）。选 HibyOS → exec/拉起播放器；选 MeowOS → 进入 MeowOS 主屏（不拉起播放器）。
- 参考播放器启动契约（§18.21）：直接 exec `/usr/bin/hiby_player`（勿经 hiby_player.sh，其 `sleep 1; reboot` 看门狗）；cwd=`/`；env -i 注入 11 变量。
- 热键进入 MeowOS（HibyOS 模式）：播放器运行中按 电源+音量减 → 选单守护唤醒 → kill 播放器（SIGKILL？或 SIGTERM——注意 §18.21：SIGTERM 仅运行态有效，T 态需先 SIGCONT；严禁 SIGUSR1）→ MeowOS 接管。
- 待办：引导选单 UI → init 改造 → 两种模式的生命周期 → 热键切换 → 退役旧让位机制。
- 遗留：热键切换时播放器的音频/声卡释放需真机确认；HGL 碎片化 vs rmem 池单次分配未彻底区分（本方案下两种解释均不再关键）。

### 阶段 A：稳定化（当前 bug 批次，基本完成）—— 与各链并行，随时收尾
目标：把 MeowLauncher 日常用的核心链路做到零崩溃、交互顺手。

| 项 | 状态 |
|---|---|
| 热键窗口下限 60ms | ✅ v6.7 |
| 状态栏翻倍 + 加音量/蓝牙 | 🔨 agent-16（v6.8） |
| 应用内返回键"一次即退" | 🔨 agent-16 |
| 列表 "Cannot start" 误标 | 🔨 agent-16 |
| 回列表闪退 | 🔨 agent-16 |
| 物理按键/触摸全面验收 | ⏳ 需用户 |

---

## 阶段拓扑序（按因果依赖，非平行摆放）

> 说明：以下四条链按**依赖因果**排序——每个里程碑/阶段必须先于依赖它的项落地。**决策：按序推进，不在依赖未满足时抢先实现上层**。已达成项标记 ✅。

### 依赖链 A【系统启动模型】（隐藏地基）
```
[阶段0 双系统引导]  ← 决定 MeowOS 默认开机、HibyOS 是否降级为系统app、SIGSTOP 让位机制是否退役
```

### 依赖链 B【UI 基建】
```
[渲染地基 M2.16 ✅]
   └─ [SDK/控件层 meow_ui, B1]  ← 几乎全部 UI 的底座（设置页/通知中心/媒体播放界面/网易云都依赖它）
        └─ [B2a 设置后端 meow_settings_* + settings.conf + listener]  ← 设置的单一数据源
             └─ [B2b 实体设置页 UI]  ──┐
             └─ [C MeowPanel Web 面板] ─┘（B2b 与 C 都消费同一 B2a 后端，天然镜像）
```

### 依赖链 C【应用模型】
```
[M0 IPC 骨架 ✅]
   └─ [M1 路由表+解析 ✅]
        └─ [M2 通知存储+分发]
             └─ [M3 导航栈+前台会话+看门狗返回]  （依赖 M2；且依赖阶段0——SIGSTOP 让位应已退役）
                  └─ [M4 后台服务保活]  （依赖 M3 导航栈 + 阶段0）
                       └─ [媒体会话（hiby适配/元数据/后台播放）]  （依赖 M3+M4+阶段0）
                            └─ [M5 通知中心 UI 整合]  （依赖 B 的 UI + M2 存储）
```

### 依赖链 D【应用主体】
```
[E 网易云客户端]  ← 跑在链C 全链路（M3/M4/媒体会话）+ 链B（SDK）之上
```

### 关键因果修正（相对旧平行表）
1. **B2a 设置在 SDK 之后**——设置控件（开关/滑条/选择器）本身就是 SDK 控件的一种，SDK 是前置。
2. **SDK/控件层（B1）是被低估的底座**——应排在链B 最前（渲染地基之后）。
3. **媒体会话不是独立里程碑，是链C 收官**——依赖 M3 导航栈 + M4 服务保活 + 阶段0（HibyOS 降级）。
4. **M3/M4 依赖阶段 0**——文档强调"单系统互斥，SIGSTOP 让位机制退役"；阶段0 不落地，M3"前台会话"与 M4"服务保活"会建立在新引入的让位机制上并返工。**这是原计划最大的隐性依赖。**
5. **B（通知中心 UI）在 B2a + M2 之后**——它消费设置后端（快捷键）+ 通知存储（通知列表），两头依赖。

### 依赖链 B【UI 基建】详细（旧阶段 B 归并于此）
- **阶段 B（状态栏+通知中心 UI）**：在 B2a 设置后端 + M2 通知存储 + SDK 控件之后。下拉通知中心消费阶段 C 链（M2）的通知存储；顶部快捷按钮行（WiFi/蓝牙/亮度/音量/主题）、亮度滑条（clamp ≥25）、通知列表（应用图标+标题+目标 Activity）——**全部走 `meow_settings_*` 后端，零旁路**。现代 UI 化：MD3（Material You）优先，MIUI/HyperOS 备选。
- **阶段 B2a（设置后端）**：`meow_settings_*` API + `settings.conf` 板载 UBIFS + listener 变更通知。SYSTEM_SETTINGS.md/MEOWOS_API.md 就绪。**为什么先于 B**：B 的快捷按钮/亮度滑条/主题开关全是设置项，后端不定就做 B 会借旧 `settings_load` 手写、后返工。listener 是"实体 UI ↔ Web 镜像"桥梁，也早于 C。
- **阶段 B2b（实体设置页 UI）**：分组列表+开关/滑条/选择器，只走 `meow_settings_*` API，不手写存取。音量跳步/上限/字体/主题/息屏模式等可配。
  - **架构**：独立模块 `meow_settings_page.c` 编译进 launcher（复用渲染/全局按键/meow_settings 后端，无 IPC）；逻辑层（分组/控件/读写 meow_settings_*）稳定，绘制层将来 MD3 重写时整块替换。
  - **MD3 规范**：见 `MD3_UI_SPEC.md`（色调角色/圆角卡片/开关滑条选择器/轻量特效，dark/light 两套接 display.theme）。
  - **入口（用户定案）**：后期 **MD3 重写启动器 UI** 后，在**启动器主页设左滑侧边栏**放设置入口；**当前先做过渡**——应用列表加"系统设置"builtin 项。MD3 重写启动器为独立后续里程碑（阶段 B 之后）。
- **阶段 C（MeowPanel）**：后端内嵌启动器（HTTP/JSON API + 静态文件服务），前端资源放 TF 卡。功能：实时性能、亮度/音量、文件管理、MeowAPPs 管理（.mpk 安装/导出）、设置镜像、实时画面、远程控制。设置页调 `meow_settings_*`；通知管理调链 C 的通知后端。

### 阶段 D（Activity/通知框架）—— 即链 C 的集合
> 通知中心/MeowPanel/应用生态的前置。协议设计已就绪（FRAMEWORK_DESIGN.md）。实现：M0 IPC 骨架 → M1 路由表 → M2 通知存储 → M3 导航/后台服务 → M4 媒体会话。M0/M1 已完成（0.7.10，M2.15）。

### 阶段 E：网易云客户端（链接 C + 链 B 之后，跑在框架上）
- 播放器「背光时间」需在应用内管理；应用退出按阶段 D 的导航语义。

### 阶段 F（可选项/远期）
- HiByLink 协议逆向 → 播放器级无线遥控；音乐库数据库管理（sqlite3 CLI 已具备）；更多应用（播客/TTS/时钟等）。
- 更多应用（播客/TTS/时钟等）

---

## 2. 产品设计要点（已确认需求汇总）

- **让位机制**：应用启动 = SIGSTOP 播放器 + fb 备份/翻页/绘制；退出 = 还原备份 + 翻回 + SIGCONT
- **返回语义**：默认回应用列表；接阶段 D 后按导航栈回上一层
- **虚拟返回键**：启动器看门狗在左上角绘制 48×48；**沉浸模式**（应用声明）隐藏之，改左缘滑动返回（SIGUSR1）；物理强杀组合保留
- **亮度安全**：任何亮度写入 clamp ≥25；不干扰播放器自动息屏
- **日志**：TF 卡 `MeowOS/logs/`（系统日志 `meow_<bootts>.log` + 应用日志 `apps/<app_id>/logs/<ts>_<pid>.log`），开机新文件，1GB 滚动；无卡不写板载（[源:审计 2026-08-30]）
- **应用目录**：TF 卡 `MeowApps/<app>/{app.json, 二进制}`；app.json 含名称/图标/执行路径/路由表（阶段 D）

---

## 3. 开发与测试流程

- 迭代回路：改代码 → 交叉编译（zig + musl.cc）→ SSH 推 `/data` 或 bind-mount 部署 → 真机验证（注入 + 用户物理确认）→ repack 固件刷入
- 注入仅能测逻辑路径（触摸注入不可投递）→ **物理项一律需用户确认**
- 每次部署前后核对：播放器实例数、背光、bind 列表、recovery_all 标志
- 崩溃/异常优先看 `MeowOS/logs/` 与 `/proc/interrupts`（区分软件/硬件）[源:审计 2026-08-30]
- 刷机走官方 SD 卡升级通道；变砖用官方固件刷回 + TF 卡全量备份兜底

---

## 4. 当前 backlog（按优先级）

0. [新] 阶段 0：可行性验证（播放器子进程化）→ init 改造 → MeowOS 主屏 + 播放器生命周期
1. [进行中] 阶段 A bug 批次（agent-16）
2. 阶段 B：状态栏升级 + 通知中心 + 快捷按钮 + 亮度滑条 + MD3 化
3. 阶段 C：MeowPanel（含实时画面 + 远程控制菜单）
4. 阶段 D：Activity/通知 IPC 框架（先协议文档 → FRAMEWORK_DESIGN.md 已就绪）
5. 阶段 E：网易云客户端
6. 阶段 F：HiByLink 逆向、更多应用

> 用户优先级：系统框架（阶段 0 + D）优先，MeowPanel 与网易云随后。