docs(repo): 仓库公开文档同步到 M2.73/0.7.68 + 修 fw_content.conf 过期 md5(meow_svcd da6ebc66/meow_svc_perf fa073bf9, 否则打包 md5 强校验失败中止) (agent-171)

docs/MEOWOS_SPEC_REF.md

@@ -15,6 +15,7 @@
 - `/tmp`：tmpfs，开机清空；开机模式标记 `/tmp/meow_boot_mode`、电源菜单 `/tmp/meow_power_menu{,_active}`、app 沉浸 `/tmp/meowapp_state` `[BOOT_SELECTOR §1][KEY_CONTROL §9][APPS §3.5]`
 - 日志启动缓冲 `/tmp/meow_boot.log`（256KB 滚动，卡出现后自动迁卡）`[APPS §4.5]`
 - IPC socket：`/usr/data/meow_ipc.sock`（AF_UNIX SOCK_STREAM，0666，backlog 4）`[FRAMEWORK_DESIGN §1][WORK_STATE]`
+- 专项服务 IPC socket：`/usr/data/meow_perf.sock`（meow_svc_perf，收 `MSG_PERF_QUERY→RESULT`）与 `/usr/data/meow_power.sock`（meow_svc_power，收 `MSG_POWER_ACTION→STATUS`），均 0666、可 `--sock`/`MEOW_IPC_{PERF,POWER}_SOCK` 覆盖；power 服务端以 `SO_PEERCRED uid==0` 基础鉴权 `[meow_svc_perf.c][meow_svc_power.c][meow_ipc.h]`
 - seccomp/分区（勿写）：mtd0=uboot mtd1=kernel mtd2=rootfs mtd3=kernel2 mtd4=rootfs2 mtd5=ota(8M 标记) mtd6=userdata `[WORK_STATE]`
 
 ### 1.2 TF 卡（挂载点 `/usr/data/mnt/sd_0`，exFAT）
@@ -56,7 +57,7 @@
 
 ### 2.2 meow_ipc 消息协议（AF_UNIX，全小端 LE）
 - 帧头 16B：`magic=0x4D4F5701`('MEOW'|1)/`version=1`/`type`/`req_id`/`len`；`len` 上限 **MEOW_IPC_MAX=4096**；列表编码 `[u16 count]`+NUL 串 `[FRAMEWORK_DESIGN §1]`
-- 消息类型：`MSG_HELLO 0x0001↑ / ACK 0x0002↓ / ERR 0x0003↓ / REGISTER 0x0010↑ / SERVICE_OK 0x0011↓ / SERVICE_STOP 0x0012↑ / MSG_NOTIFY 0x0020↑ / NOTIFY_ACK 0x0021↓ / NOTIFY_DISMISS 0x0022↑ / NOTIFY_LIST 0x0023↓ / ACT_DECLARE 0x0030↑ / ACT_QUERY 0x0031↑ / ACT_RESULT 0x0032↓ / NAV 0x0040↑ / SHOW_ACTIVITY 0x0041↓ / SYS 0x00F0↓` `[FRAMEWORK_DESIGN §1]`
+- 消息类型：`MSG_HELLO 0x0001↑ / ACK 0x0002↓ / ERR 0x0003↓ / REGISTER 0x0010↑ / SERVICE_OK 0x0011↓ / SERVICE_STOP 0x0012↑ / MSG_NOTIFY 0x0020↑ / NOTIFY_ACK 0x0021↓ / NOTIFY_DISMISS 0x0022↑ / NOTIFY_LIST 0x0023↓ / NOTIFY_PROGRESS 0x0024↑ / ACT_DECLARE 0x0030↑ / ACT_QUERY 0x0031↑ / ACT_RESULT 0x0032↓ / ACT_FOCUS 0x0033↑ / ACT_BACK 0x0034↑ / NAV 0x0040↑ / SHOW_ACTIVITY 0x0041↓ / PERF_QUERY 0x0050↑ / PERF_RESULT 0x0051↓ / POWER_ACTION 0x0060↑ / POWER_STATUS 0x0061↓ / SYS 0x00F0↓` `[FRAMEWORK_DESIGN §1][meow_ipc.h]`
 - 媒体：`MSG_META`（元数据）、`MSG_PLAYCTL`(cmd 1=播放2=暂停3=上一首4=下一首5=seek)、`MSG_PROGRESS` `[附录 B]`
 - IPC 线程**只读帧+解析+入队**；状态变更主循环单写者（eventfd 唤醒，10ms 热键轮询非阻塞排空）`[FRAMEWORK_DESIGN §0][§6]`
 
@@ -119,6 +120,7 @@
 > 定位：把 §5（最小控件集）与设计模板（§5.2-§5.7）收敛到**统一控件架构**；实现分两批（§5.8.8）。
 - **第一批 = 通用基座（M2.70/0.7.65）**：`meow_widget` 基座统一标准控件/自定义画布；`meow_widget_opts`（Modifier 式 Options，`meow_widget_set_opts`/`meow_widget_opts_get`，0/-1 用默认）；统一状态机 `MEOW_WS_ENABLED/SELECTED/FOCUSED/PRESSED`（`meow_widget_set_state`/`meow_widget_state`/`meow_widget_enabled`/`selected`）；`meow_widget_custom_create`（自定义画布，App 给 render/hit 回调，`W_CUSTOM`）；布局 `meow_row/column/box`+`meow_layout_add/arrange`+`spacer`；MD3 语义色板（§5.8.4）+ 主题接口 `meow_ui_set_style`（`MEOW_STYLE_MD3/MIUIX`）`/meow_theme_get`。
 - **第二批 = Material 组件子集（M2.71/0.7.66）**：`meow_btn_create_variant`（五型）/`meow_textfield_create`（IME）/`meow_card_create`/`meow_divider_create`/`meow_badge_create`/`meow_checkbox_create`/`meow_radio_create`/`meow_progress_create`/`meow_progress_circular_create`/`meow_fab_create`/`meow_topappbar_create`/`meow_navigationbar_create`/`meow_tabbar_create`/`meow_lazycolumn_create`/`meow_lazyrow_create`/`meow_dialog_create`/`meow_sheet_create`。
+- **M2.73 控件库修复（`meow_ui.a` md5 `e8341975`，`[meow_ui_widget.c][meow_ui_ime.c]`）**：① `W_LIST`（含 LazyColumn/LazyRow，`meow_widget_draw` case W_LIST）**视口裁剪**——按 `vx0/vx1/vy0/vy1` 只绘制落在视口内的行/分隔线/文本，杜绝「行滚出视口仍画/标脏上屏」的标题栏/底部脏区（SDK 全局，非 App 侧）；② **z 序**：App 侧 `hello_app/hello.c` 的 `d_paint_region` 局部刷新改按 z 栈重画（内容→标题→slider 值→chrome），根治「层动态控件实时重绘盖住/抹掉上层 FAB」；**SDK 级全局 z 序方案在评估，暂未落定**（未正式纳入 SDK 公共 API 前不要写成正式规范）；③ 渲染残影/脏区：局部刷新不再「清底+只画单个控件」（改 z 栈重画），消除重叠区残留；④ **IME 行为**（`meow_ui_ime.c`）：键盘区背景快照/恢复（`ime_capture`/`ime_restore`，无残影）、配色走主题（不再硬编码黑底白键）、shift 大小写、阻塞 `meow_ui_text_input` 在打字循环喂 `meow_ui_activity_ping`（重置息屏计时，进度条不卡死）、OK（回车）=提交并关闭 / ESC（X）/背景点=取消；回显条=**实时输入回显**（`"%s_"` 拼接，非候选/联想），**候选框留中文输入法再做**。
 - **兼容**：既有 `meow_btn/slider/switch/list_create` 签名一字不改（Options/状态机走新增挂载器）；`meow_ui_theme`/`meow_widget` 结构变化 = **`meow_ui.a` ABI 变化** → 需同步重编 hello（§5.8.8）。
 - **主题增强（§8.1）**：主题 = **顶级风格族 `ui.style`（md3/miuix）× 明暗 `display.theme`（dark/light）** 共同决定「整套配色+控件形态+背景底」；`display.background` 为「style×mode」派生的**可选背景底选项集**（非独立维度）；状态栏图标随 `ui.style` 换集。⚠️ **`miui`/`miuix` 命名待定案（保留，勿拍板）**：`MEOW_APP_SDK §8.1` 用 `miuix`；`SYSTEM_SETTINGS §1` 注明 `meow_settings.c g_defs` 现值 `"md3,miui"`（label "Material You,MIUI"），实现时把 `g_defs` 的 `miui` 对齐为 `miuix`（**MIUIx 未实现，当前仅 md3 生效**）。
 
@@ -126,7 +128,7 @@
 
 ## 4. SDK 之外系统组件
 - **系统进程 supervisor 树（源:2026-08-30 定案；M2.71 已落地 `meow_sysui`）**：`meow_sysui`（`patch_v2/meow_sysui/meow_sysui.c`，~113KB；`etc/init.d/S70meow_sysui` 开机拉起，早于 S89）监管系统进程，**一个崩→只拉起它，绝不级联**；`meow_launcherd`=系统 UI 渲染宿主（状态栏/通知中心/电源菜单/全局手势，与 APP 进程独立）；`meow_svcd`=服务管理器（服务全子进程化，svcd 自身不死）；APP 进程只渲染自己内容，崩不连累系统 UI。**系统组件渲染归系统进程（launcher），APP 进程不渲染系统 UI**（SDK 系统组件 API 仅系统进程可链，App 不可自建悬浮层）；通知中心 UI 渲染主体=系统进程，数据经 IPC 从通知存储读。现网（bootmenu execv launcher + S89 svcd 自启）→ 定案（sysui 统一监管）为渐进迁移，属系统基建线。**sysui 当前默认只监护 `meow_svcd`**（`/usr/data/meow/sysui.d/<name>.conf`，目录式复用 services.d 语义；launcher 由 S90meow_bootmenu 的 execv 拥有，登记但 `enabled=0` 防双重拉起；mdns 是 svcd 服务子进程，不双重管理）。`[FRAMEWORK_DESIGN §10][MEOW_APP_SDK §6.1][NOTIFICATION_SYSTEM §9][patch_v2/meow_sysui/meow_sysui.md]`
-- **专项子服务（一期在跑，规划见 `devdocs/plan/SYSTEM_FRAMEWORK_SERVICES.md`）**：两个 **svcd 托管、板载 `trigger=boot`** 的专项子服务——`meow_svc_perf`（性能/系统只读聚合）、`meow_svc_power`（关机/重启/升级/回 HiBy 系统动作）。launcher 电源菜单与 MeowPanel 均改经这些服务 IPC 触发（不再直连 `sys_do_reboot`/爬 `/proc`）。**电源 CLI `meow_svc_power <cmd>`**（root 免鉴权、单一命令、不覆盖系统 shutdown/reboot）：`shutdown`/`reboot`（强制回 MeowOS）/`upgrade`（写 mtd5=`ota:kernel2`）/`set-default-hiby`/`reboot --hiby` + `status`/`screen`/`dac`/`battery`/`reboot-reason`/`upgrade-status`。**二期**：关键 IPC 只接受 **`os.meow.*`** 鉴权 + `.mpk` 打包签名验签（解包验签/导出保留签名）。`[SYSTEM_FRAMEWORK_SERVICES][APPS 附录 §3]`
+- **专项子服务（一期在跑 + M2.73 落地，规划见 `devdocs/plan/SYSTEM_FRAMEWORK_SERVICES.md`）**：两个 **svcd 托管、板载 `trigger=boot`** 的专项子服务——`meow_svc_perf`（性能/系统只读聚合）、`meow_svc_power`（关机/重启/升级/回 HiBy 系统动作）。launcher 电源菜单与 MeowPanel 均改经这些服务 IPC 触发（不再直连 `sys_do_reboot`/爬 `/proc`）。**IPC**：perf 走 `/usr/data/meow_perf.sock` `MSG_PERF_QUERY→RESULT`；power 走 `/usr/data/meow_power.sock` `MSG_POWER_ACTION→STATUS`（服务端 `SO_PEERCRED uid==0` 基础鉴权）。**M2.73**：perf 增 **network** 子集（SYSTEM 子集输出：真实 WiFi `wpa_cli`/`ip` + 蓝牙 `hci0`/sysfs + `hostname_local`，单点权威源）；power **升级写保护**（`upgrade` 写 mtd5 前校验卡根 `r3proii.upt` 存在+可读+常规文件+size>0，失败不写 mtd5/不重启；**只完整性不签名**，海贝官方固件无签名，期望 md5/hash 二期）与 **`dac status` 读板载 `settings.conf` 的 `audio.volume` 真实值**（`settings_get_int_trim`，弃 amixer dummy；`dac on/off` 因 cs43198 `pwr_gpio=-1` 无控制点→`MEOW_ERR_NODEV`）。新 md5：perf `fa073bf9`、power `f3e653d5`。**电源 CLI `meow_svc_power <cmd>`**（root 免鉴权、单一命令、不覆盖系统 shutdown/reboot）：`shutdown`/`reboot[--hiby]`（强制回 MeowOS）/`upgrade`（写 mtd5=`ota:kernel2`，含写保护）/`set-default-meow`/`set-default-hiby` + `status`/`battery`/`reboot-reason`/`upgrade-status`/`screen on|off|timeout<秒>`/`dac on|off|status`。**二期**：关键 IPC 只接受 **`os.meow.*`** 鉴权 + `.mpk` 打包签名验签（解包验签/导出保留签名）。`[SYSTEM_FRAMEWORK_SERVICES][APPS 附录 §3][meow_svc_perf.c][meow_svc_power.c]`
 - 通知（SDK `meow_notify_*`，M2.53 最小版 `[meow_ui.h §9.1]`）：
   - 常量：`MEOW_NOTIFY_MAX_TYPES=4`/`MEOW_NOTIFY_MAX_PER_TYPE=4`/`MEOW_NOTIFY_MAX_MEDIA=1`/`MEOW_NOTIFY_TIMEOUT_ONGOING=-1`/`MEOW_NOTIFY_TIMEOUT_NEVER=0`
   - 分类：`CAT_GENERAL/MESSAGE/EMAIL/EVENT/PROGRESS/MEDIA(=5)/COUNT`；紧急度 `URG_LOW/NORMAL/HIGH/CRITICAL`
@@ -143,7 +145,9 @@
   - **服务目录规则**：**固件工具**→板载 `/usr/data/meow/services.d/<name>.conf`（Data 区，拔卡保留）；**TF 工具/第三方**→TF `MeowOS/services.d/<name>.conf`（随卡存在/消失）；**双源板载优先**（TF 同名被板载屏蔽 + WARN「<name> 板载与 TF 都存在，采用板载」）。
   - 崩溃隔离：服务=svcd **独立子进程**（`fork+execv`），svcd 只 `waitpid`/`SIGCHLD` 感知；服务死不影响 svcd/supervisor；重启受 `backoff_ms` 退避防热循环。
   - 状态机：`DISABLED/STOPPED/RUNNING/STOPPING/FAILED`；稳定运行 30s 清零 restart_count。CLI（systemctl 式，SSH 直呼）：`status/reload/start|stop|restart <name|all>/pid`，示例 `meow_svcd status`/`meow_svcd restart mdnsd`/`meow_svcd stop all`/`meow_svcd reload`；控制走 AF_UNIX 单行文本 `/tmp/meow_svcd.sock`；守护默认后台，`-f/--foreground` 前台供 supervisor 托管。
-- **卡上外部工具 = `MeowOS/opt/`**（`{bin,nyai,sources.list}, lib/, tools/`）：MeowOS 启动时从卡加载，拔卡降级不崩。**`MeowOpt` 已废弃并入此处**；mDNS 已改为自研 `meow_mdns`（固件 `/usr/bin`），不再放卡。`[DEV_NOTES][meow_svcd.md]`。
+  - **M2.73 悬垂指针修复（md5 `da6ebc66`）**：`scan_and_reconcile` 用 `*s=tmp` 整体拷贝后，`s->argv[]` 仍指向已销毁的 `tmp` 栈帧 → `execv`/`/proc/pid/cmdline` 错乱。修法：新增 `svc_rebuild_argv(s)`，赋值/`memmove` 左移后把 `s->argv[]` 重定位到 `s->exec`/`s->argbuf` 自身成员（删除一个服务后同 tick 内被拉起不再用错位 argv）。`[meow_svcd.c]`
+- **卡上外部工具 = `MeowOS/opt/`**（`{bin,nyai,sources.list}, lib/, tools/`）：MeowOS 启动时从卡加载，拔卡降级不崩。**`MeowOpt` 已废弃并入此处**；mDNS 已改为自研 `meow_mdns`（固件 `/usr/bin`），不再放卡。`[DEV_NOTES][meow_svcd.md]`。**MeowPanel 本体 = `MeowOS/opt/MeowPanel/`**（后端+前端，svcd 托管 `MeowOS/services.d/meowpanel.conf`，无卡跳过、系统核心不依赖，不进固件；md5 `11ed76ec`，详见 `patch_v2/meowpanel/README.md`）。
+- **MeowPanel（外置 TF 卡 Web 面板，M2.73 已落地）**：单进程 HTTP/JSON 后端（8080）+ 静态托管（`/`→index.html、`/assets/*`）+ `meow_svc_perf`/`meow_svc_power` IPC 客户端（读侧透传 perf 聚合、动作侧经 power）+ `settings.conf` 设置镜像（`key = value` 带空格 + 精确匹配）+ 文件白名单（`MeowOS/Music/MeowData/MeowAPPs/book`，`..` 逃逸→403）+ 应用（`nyai install/export/remove`，包名=`app.json.package`）+ 按键注入（evdev，只音量/电源/播放/上下曲，**禁返回158/主页172/确认28/退出96**）+ 日志（`MeowOS/logs`）。M2.73：系统页「以太网」→「**蓝牙**」栏（无网口有蓝牙）；**OTA 检查升级 bug 已修**（改读 `GET /api/system` 的 `ota`，不再误触 `POST /api/system/ota` 升级）。**⚠️ 无鉴权**（内网信任模型；`reboot/shutdown/ota/apps/删除/上传` 危险端点勿暴露公网，power 侧有 `SO_PEERCRED uid==0` 基础校验）。`[patch_v2/meowpanel/][devdocs/plan/MEOWPANEL_PROTOCOL.md]`
 - **mDNS 应答器 = `meow_mdns`（自研，已拍板替代完整 mdnsd）**：`mips-repo/bins/meow_mdns/`，**IPv4-only**（内核无 IPv6，完整 mDNSResponder/SAResponder 均 `socket(AF_INET6)` 失败），mipsel 静态 ~79KB（md5 b23de7ce）。**进固件 `/usr/bin/meow_mdns`**（不入卡），由 meow_svcd 托管（板载 `/usr/data/meow/services.d/mdnsd.conf`，`trigger=boot`、root 即可绑 5353/组播，`cap=` 空）。功能：join `224.0.0.251:5353`，应答 `<host>.local` A（wlan0 IPv4）/`_ssh._tcp` PTR/SRV/TXT/`_services._dns-sd` PTR；支持 `MEOW_MDNS_HOST`/`_ADDR`/`_PORT`/`_TTL`/`_CF`/`_QD`/`_MCAST`/`_MIF`/`_DBG`。⚠️ **手机热点隔离**：设备→主机组播被热点丢弃，avahi 只收组播应答 → 该热点下 `avahi-resolve <host>.local` 超时（网络层限制，非应答器缺陷），主机需 DNS 兜底 `[mips-repo/bins/meow_mdns/manifest.md][meow_svcd.md]`。
 - `meow_settings_*`（设置后端，已定）/`meowcli`/`meow_sys_devattr`/`meow_devattr_set` `[MEOWOS_API]`
 - 后台权限：`MSG_HELLO/MSG_REGISTER.flags` 扩展 `MF_BACKGROUND`/`MF_PLAYBACK`；`PERF_BACKGROUND`/`PERF_AUDIO_BACKGROUND`（规划）`[FRAMEWORK_DESIGN 附录 A]`
@@ -199,7 +203,7 @@
 - **⑨ 面板「跟手下拉、半程可回」（launcher 侧，M2.65）**：面板打开/关闭由触发式 180ms 过渡升级为**手指拖动实时跟手**——顶部热区下拉 `progress = 手指位移映射`（复用 `mnp_anim_off`，∈[0,1024]，1:1 跟手）；松手 `progress≥40%×1024≈410` → 时间轴补到 1024（展开）；`<阈值 或 反向拖回` → 回弹到 0 收回（半程取消）；关闭同理可跟手。与行左滑（⑦ 横向主导）/列表滚动（竖向溢出）/`meow_edge_back`（左缘）互斥分流。`[NOTIFICATION_SYSTEM §9]`
 
 ### 5.4 配置版本单点 / 刷新率 / 息屏
-- **现行：M2.71（`/etc/meowos_version` = `0.7.66`；M2.70/0.7.65、M2.69/0.7.64、M2.68/0.7.63 …）**；版本单点 = `/etc/meowos_version`（见 §1.1，`build_fw_apps.sh -v` 写入）`[DEV_NOTES #4][fw_content.conf]`
+- **现行：M2.73（`/etc/meowos_version` = `0.7.68`，已推卡真机验收；M2.74 / 0.7.69 待打）（M2.72/0.7.67、M2.71/0.7.66、M2.70/0.7.65、M2.69/0.7.64 …）**；版本单点 = `/etc/meowos_version`（见 §1.1，`build_fw_apps.sh -v` 写入）`[DEV_NOTES #4][fw_content.conf]`
 - 刷新率：`display.refresh_rate` enum 60/30/15（默认 60）；`display.refresh_always_max` bool false（关=允许 60→30→15 降档）。governor：连续 12 帧超预算降一档，连续 4 批≈48 帧远低预算升一档 `[SYSTEM_SETTINGS §1][PERF_SCHEDULER][MIGRATION_AC §12.1]`
 - 息屏：`display.screen_off_timeout` int 秒 默认 **30**（0=常亮）；`display.screen_off_mode` enum `panel`(面板下电+背光0+FBIOPBLANK)/`black`(背光0全黑+双击亮屏) `[SYSTEM_SETTINGS §1]`
 - 亮度 clamp：`display.brightness` 0-255 默认 101（clamp ≥ `display.brightness_min`）；`display.brightness_min` 默认 **1**（M2.39 由 25 改 1）——**与旧文档 25 冲突见 §A** `[SYSTEM_SETTINGS §1]`