# MeowOS TF 卡目录布局与"固件/卡"分头原则

> 状态：设计稿 v1（2026-08-28）。对齐"资源紧张（板载/RAM）"与"TF 卡热插拔"约束。

## 0. 一句话

**固件 rootfs 只装"稳定框架"（运行时零卡依赖）；TF 卡承载一切可扩展/大体积内容。** 拔卡 → 框架不死、优雅降级；插卡 → 自动重建。MeowOS 各类非必要文件统一收在 `MeowOS/` 下。

## 1. TF 卡目录规范

```
/usr/data/mnt/sd_0/
├── Music/              # 音乐库（播放器标准索引目录）
├── MeowData/           # 用户数据（歌曲、封面缓存、下载等）
├── MeowAPPs/           # 应用
│   ├── <app>/          #   app.json + 二进制 + 资源
│   ├── fonts/          #   默认字库 font.png + font.idx（font.file 缺省指此处；可由 MeowOS 加载）
│   └── backgrounds/    #   可选背景图
├── MeowOpt/            # 板载外部工具/二进制（如 mdnsd/；卡上加载，拔卡降级不崩。与 MeowOS/opt 命名待归一，见 SPEC_REF 矛盾 §A-11[源:审计 2026-08-30]）
└── MeowOS/             # MeowOS 专属（一切非必要文件）
    ├── backups/
    │   └── settings/
    │       └── setting.bak   # 设置导出默认路径（SYSTEM_SETTINGS 一致）
    ├── fonts/<family>/<weight>/ # 多字体库（每 <family>/<weight> 一套三件套；font.file 选默认套=default/regular）
    ├── logs/           # 统一日志：系统 meow_<bootts>.log + 应用 apps/<app_id>/logs/<ts>_<pid>.log
    ├── services.d/     # 服务配置（meow_svcd 的 <name>.conf；TF 源——与板载 /usr/data/meow/services.d 双源，同名板载优先）`[meow_svcd.md]`
    ├── opt/             # 外围可选工具（curl/socat/tmux/jq/rsync/nano/htop/ncdu/file/xxd…）
    ├── lib/             # 可选共享库（opt 工具的依赖 .so）
    ├── tools/           # 调试/运维（可不设，并入 opt）
    └── <其他 MeowOS 非必要资源…>
```

## 2. 固件 rootfs 只保留（稳定框架）

- `meow_launcherd`（MeowOS 核心）、`meow_bootmenu`（引导选单）、`meow_watchdog`
- `meow_svcd`（服务管理器，M2.54 进固件）+ `meow_mdns`（自研 IPv4-only mDNS 应答器，M2.54 进固件 `/usr/bin`）
- `dropbear`/`dropbearkey`（SSH 必需）、`sftp-server`（小，保留）
- 调试三件套：`gdbserver`/`strace`/`tcpdump` + `sqlite3`（DB 调试）
- 系统依赖库（libc/libstdc++/libcrypto/glib/asound 等——播放器/服务需要，不能动）
- 启动器只读 `/data`（settings）+ rootfs；**不读卡**才能保证拔卡不死

> 其余 CLI（curl/socat/tmux/jq/rsync/nano/htop/ncdu/file/xxd）→ `MeowOS/opt/`（卡）；依赖 `.so` → `MeowOS/lib/`（卡）。

## 3. 拔卡/插卡行为

| 事件 | 行为 |
|---|---|
| **拔卡** | 框架核心（launcher/选单/SSH）不受影响（零卡依赖）；应用列表"未插卡"；日志回退内存环；字体回退点阵；opt/lib 工具不可用（PATH 里卡上的没了）；**不崩不死** |
| **插卡** | 侦测 `mmcblk0` → 自动 mount → 重扫 MeowAPPs → 载字库 → 恢复 opt PATH → 日志迁回卡；自动重建 |

## 4. 实现要点

- **移工具**：从 rootfs 移除 `MeowOS/opt/` 对应二进制；MeowOS 启动时若卡在则 PATH 前插 `/usr/data/mnt/sd_0/MeowOS/opt/bin:$PATH`（卡不在跳过）。用 `meowtool` 包装提供绝对路径引用。
- **框架零卡依赖审查**：确认 launcher/bootmenu 没有任何"卡必须在"的硬依赖（settings 在 /data、字体/应用/日志对卡可缺省/回退）。
- **字库**：多字体库 `MeowOS/fonts/<family>/<weight>/`（每套 `font.png/font.idx/font.json`；`font.file` 选默认套 = `<family>/<weight>/font.png`，缺省 `MeowOS/fonts/default/regular/font.png`；无卡回退点阵，已有。[源:审计 2026-08-30]）。
- **日志**：卡 `MeowOS/logs/`（系统日志 `meow_<bootts>.log` + 应用日志 `apps/<app_id>/logs/<ts>_<pid>.log`；无卡内存环，已有。[源:审计 2026-08-30]）。
- **设置**：板载 `/data/meow/settings.conf`（小文件跨卡保留），导出默认 `MeowOS/backups/settings/setting.bak`。

## 5. 体积收益
移除 MeowOS/opt 工具后 rootfs 压缩预算省约 3-5MB（curl/socat 大头），回到 ~41MB，远离 45MB 上限。

> **M2.12 落地确认**：rootfs `/usr/bin` 的 curl/socat/tmux/jq/rsync/nano/htop/ncdu/file/xxd 已迁至卡 `MeowOS/opt/bin/`（均**静态 MIPS**，无 `.so` 依赖，故 `MeowOS/lib/` 暂为空占位）；固件 rootfs 由 44,343,296 B → **37,724,160 B（≈36.98MB）**。MeowOS 启动器在卡在时把 `MeowOS/opt/bin` 前插自身及子进程 PATH；SSH 登录会话由 `/etc/profile.d/meow_card_path.sh` 前插（卡不在跳过）。零卡依赖：launcher/bootmenu 运行时只读 `/data`（settings）+ rootfs，卡不在则字库回退点阵、应用示"未插卡"、日志回退内存环、opt 工具不可用——**均不崩不死**。

## 6. 后续
- 应用/工具管理：MeowAPPs 扫描（已有）；`MeowOS/opt`/`lib` 由 MeowOS 或 web 面板管理（下载/更新）。
- 阶段 C MeowPanel 文件管理页直接映射这些目录。