MeowOS-For-R3P2/patch_v2/meow_sysui/meow_sysui.md

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 + meow_launcherd（launcher 于 M2.83 launcher 监管迁移落地：由 S70 预置 launcher.conf 且 enabled=1，bootmenu 在 MeowOS 模式让位）。 bootmenu 仅在 sysui 不在时兜底 exec launcher；HibyOS 模式下 bootmenu 会让 sysui 停 launcher （不与播放器抢 fb0）。详见 §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 首启预置）：

# 系统进程总监 → 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 监管（✅ M2.83 已落地）：launcher 生命周期已由 S90meow_bootmenu 的 exec 移交 sysui。sysui.d/launcher.conf 现 enabled=1（restart=always/backoff_ms=3000/max_restart=5）。
  • sysui 在 S70 拉起并监管 launcher（崩→按策略重启，稳定 30s 清零次数，超 max_restart→FAILED 停）。
  • bootmenu（meow_bootmenu.c）MeowOS 模式：sysui 在 → meow_sysui start launcher + 让位退出 （不 exec launcher）；sysui 不在 → bootmenu 照旧 exec launcher（兜底，防开不了机）。
  • bootmenu HibyOS 模式：sysui 在 → meow_sysui stop launcher（会话级 user_stopped）再 fork 播放器， 避免 launcher 与播放器抢 fb0。
  • 已部署设备兼容：S70 检测旧 launcher.conf enabled=0 → 升级为 enabled=1。
• mdns 监管：由 svcd 负责；sysui 兜底条目默认关。

7. 编译

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

后续（不在本阶段）

• MeowOS/sysui.d/ TF 双源扩展（复用 svcd 板载优先语义）。
• 与 meow_watchdog / 崩溃捕获的职责对齐（见 WORK_STATE SDK 缺失清单 #5）。
• launcher 已在 S70 由 sysui 拉起（bootmenu 让位，见 §6）；真机待验证：①MeowOS 模式 bootmenu 让位后 rcS 推进到 S92 是否稳定跳过播放器 ②HibyOS 模式 sysui stop launcher 与播放器 fork 的 短暂共存无 fb0 冲突 ③launcher 在 S70 早启动（先于选单）与 boot_menu=1 选单的 fb 共存。