# meow_sysui — MeowOS 系统进程总监

系统进程**总监**：监管系统进程（launcher / meow_svcd / meow_mdns / 未来媒体服务 / MeowPanel），
**一个崩 → 只拉起它，绝不级联、绝不拖垮自身**。自身**最小依赖、不渲染、不承载重逻辑** → 最稳。
由开机启动链 `etc/init.d/S70meow_sysui` 拉起（早于 S89meow_svcd），居顶层监管。

权威锚点：`FRAMEWORK_DESIGN §10.1`（进程角色/Supervisor 树）、`docs/MEOWOS_SPEC_REF §4`、
`devdocs/plan/SYS_BASELINE.md`（本线方案）。

二进制入口：`patch_v2/meow_sysui/meow_sysui`（mipsel 静态，~113KB，<200KB 固件阈值）。
宿主编译：`patch_v2/meow_sysui/meow_sysui_host`。

---

## 1. 定位与监管模型

- **只监护自己 fork+exec 出来的进程**：`waitpid` 需为父进程，这是「一个崩只拉起它」的可靠前提；
  sysui **不做**「adopt 外部 pid」式监护（那只 probe `kill(pid,0)`、无法真正 waitpid/重启）。
- 要监管什么由配置决定；**默认配置只开启 `meow_svcd`**（符合定案「sysui 总监 → svcd 被监管 →
  服务为 svcd 子进程」）。`launcher` 当前由 S90meow_bootmenu 的 `exec` 拥有，配置中登记但
  `enabled=0`（避免双重拉起；真正移交需 bootmenu 让位，见 §6）。
- `meow_mdns` 是 svcd 的服务子进程（svcd 负责 spawn/restart），sysui 本阶段**不直接监管**它
  （避免与 svcd 双重管理）；`§10.1` 的「mdns 崩→svcd 拉起（或 sysui 兜底）」——兜底可后续
  在 `sysui.d/` 加一条 meow_mdns 条目实现（默认关）。

## 2. 配置：`/usr/data/meow/sysui.d/<name>.conf`（板载权威，目录式）

复用 services.d 语义：一个被监管进程一个 `<name>.conf`，`key=value`，`#`/`;` 注释，未知键忽略（前向兼容）。

| 字段 | 必填 | 说明 | 默认 |
|---|---|---|---|
| `exec` | ✅ | 被监管二进制绝对路径 | 无（缺省 → 跳过该条目） |
| `args` | 否 | 空格切分，支持单/双引号与 `\` 转义 | 无 |
| `env` | 否 | `K=V`，可多条；exec 前 `setenv` | 无 |
| `enabled` | 否 | `1`=监护该进程；`0`=只登记不拉起 | 0 |
| `restart` | 否 | `always`/`on-fail`/`never` | `on-fail` |
| `backoff_ms` | 否 | 崩溃后重启退避毫秒（固定） | 2000 |
| `max_restart` | 否 | 连续重启上限，超限 → `failed` 停止自动重启；`-1`=无限 | 5 |

> **无 `trigger`**：sysui 只管**常驻系统进程**（launcher/svcd/mdns），`enabled=1` 即拉起/常驻监管，
> 拔卡无关（系统进程不认卡）。卡相关服务归 svcd 的 `services.d`。
> TF 卡 `MeowOS/sysui.d/` 作为扩展点本阶段不读（代码只读板载，最小化）。

示例（`svcd.conf`，由 S70 首启预置）：

```ini
# 系统进程总监 → svcd 被监管 → 服务为 svcd 子进程
exec = /usr/bin/meow_svcd
args = -f
enabled = 1
restart = always
backoff_ms = 3000
max_restart = 5
```

## 3. 状态机

```
DISABLED   enabled=0，永不自动拉起
STOPPED    未运行（被停 / 等待退避）
RUNNING    子进程存活
STOPPING   已发 SIGTERM，等退出（SYSUI_STOP_GRACE_MS=2500 后 SIGKILL 兜底）
FAILED     反复崩/起不来且超 max_restart，停止自动重启（有限次兜底）
```

转换（主循环事件驱动 + 周期 tick，同 svcd）：

- **子进程死亡**（`waitpid` 匹配）：无 `stop_requested`/`restart_pending` → 按该条目 `restart`
  策略决定重建（先进 `backoff_ms` 退避）或落 `FAILED`/`STOPPED`；稳定运行 `SYSUI_STABLE_MS=30s`
  清零 `restart_count`。**只处理该条目，无级联。**
- **`kill(pid,0)` 存活探测**：`tick` 里对 `RUNNING` 条目做 `kill(pid,0)`；若 `ESRCH`（子进程已死
  未收尸/异常）→ 视同死亡走重建策略（对应「kill(pid,0)/waitpid 探测」定案）。
- **`stop` 命令**：`STOPPING → STOPPED`（置 `user_stopped`，抑制自动拉起）。
- **`restart` 命令**：收尸后原地 respawn（清零计数）。
- **配置变更**：`reload` 命令重读 `sysui.d/`；新增→监护，移除→停，配置变更→重启该条。

## 4. 崩溃隔离 / 护固件（防开不了机）

- **独立进程**：每个被监管进程 `fork()+execv()` + `setpgid(0,0)`，sysui 只经 `waitpid`/`SIGCHLD`
  感知；无中间层内存共享、无 dlopen。
- **一个崩不全部崩**：`reap_children()` 只命中死掉的那条；重启只作用于该条；主循环绝不在子进程
  死亡时 `exit`。
- **有限次兜底**：某进程起不来/反复崩 → `restart_count++`，超 `max_restart` → `FAILED` **停止自动重启**，
  仅记日志（`sysui: <name> exceeded max_restart -> FAILED`）；绝不崩溃-重启热循环拖垮系统。
  重新尝试需 `reload`/配置变更（`scan_and_reconcile` 仅在启动与 reload 执行——**不在每 tick 调用**，
  否则会每秒重置 FAILED、破坏「有限次」语义）。
- **自身不死**：主循环只在 `SIGTERM/SIGINT` 退出；`SIGPIPE` 置 `SIG_IGN`；poll `EINTR` 续跑。
- **空配置可跑**：无 `sysui.d/` 或全 `enabled=0` → 空转存活（只写日志/status），不报错、不阻塞后续 S84/S89/S90。
- **子进程回收者**：`PR_SET_CHILD_SUBREAPER`——被监管进程若派生孙进程，在直接子进程退出后由 sysui
  收尸而非 reparent 到 init，强化「孤儿/僵死隔离」（失败仅日志，不硬失败）。

## 5. CLI / 控制协议 / 日志

守护默认后台常驻（无子命令即启动）；`-f/--foreground` 供 init/调试。控制走 AF_UNIX 单行文本
（默认 `/tmp/meow_sysui.sock`）：

```
meow_sysui status [name|all]       # 列出各被监管进程 + 全局（daemon 未运行则打印状态文件）
meow_sysui reload                 # 重读 sysui.d/
meow_sysui start  <name|all>
meow_sysui stop   <name|all>
meow_sysui restart <name|all>
meow_sysui pid
```

- 状态文件 `/tmp/meow_sysui.status`；pidfile `/tmp/meow_sysui.pid`。
- status 回显：每条目 服务名/状态/pid/重启次数+max_restart/backoff_ms/最近退出码/是否启用/exec；
  TTY 带 ANSI 配色（表头 dim、服务名加粗青、RUNNING=绿、FAILED=红、STOPPED·STOPPING=黄、DISABLED=灰），
  非 TTY 自动去色。
- 日志：stderr（`-f`）+ 默认追加 `/tmp/meow_sysui.log` + `syslog(LOG_DAEMON)` 尝试。

## 6. 迁移说明 / 边界（诚实标注）

- **launcher 监管**：现网 launcher 由 `S90meow_bootmenu` 的 `exec` 拉起（bootmenu 拥有其生命周期）。
  sysui **本阶段不拉起 launcher**（`sysui.d/launcher.conf` 默认 `enabled=0` + 注释）；
  launcher 真正归 sysui 需 bootmenu 让位（后续迁移）。sysui 代码完全支持加一条 launcher 条目即可。
- **mdns 监管**：由 svcd 负责；sysui 兜底条目默认关。

## 7. 编译

```bash
./build_sysui.sh        # mipsel 静态 → meow_sysui（0 warning）
./build_sysui.sh host   # 宿主编译 → meow_sysui_host（集成测试）
```

## 后续（不在本阶段）

- launcher 正式移交 sysui 监管（依赖 bootmenu 让位）。
- `MeowOS/sysui.d/` TF 双源扩展（复用 svcd 板载优先语义）。
- 与 meow_watchdog / 崩溃捕获的职责对齐（见 WORK_STATE SDK 缺失清单 #5）。