MeowOS-For-R3P2/MEOWOS_API.md

MeowOS API 参考（MEOWOS_API.md）

状态：设计稿 v1（2026-08-28）。作为后续开发（系统设置 / 通知中心 / MeowPanel / Activity 框架）的统一 API 蓝本。 原则：命名统一、类型明确、返回码一致、可扩展。所有新增 API 必须按本文命名与返回约定，保证多端（实体 UI / Web / CLI/MCP）一致。

---

0. 命名约定（全局）

范畴	规则	例
C API 前缀（后端）	meow_<域>_<动作>（下划线，小写）	meow_settings_get_int、meow_notify_push
域（domain）	全局命名空间：settings / notify / act / svc / nav / media / sys / panel	—
设备属性	属 sys 域子域 device（meow_sys_devattr + meow_devattr_*）；只读属性 + 可控 kcontrol 白名单	meow_devattr_set("out.port", 3)
结构体	meow_<域>_t（typedef 别名），字段下划线	struct meow_settings_bool { int v; }
枚举	MEOW_<域>_<NAME>	MEOW_BOOT_MEOW
常量/宏	MEOW_<DOMAIN>_<NAME>	MEOW_LOG_LEVEL_INFO、MEOW_SET_MAX_LEN
键名（设置/配置）	小写点分：域.子.名	display.brightness、boot.default、input.hotkey_seq
REST 路径	/api/<域>/<资源>（kebab-case 资源）	/api/settings、/api/settings/export
HTTP 方法	GET=读、POST=写/动作	—
返回值（C 函数）	int，0=成功，负=错误码	见 §4

1. 返回码（统一错误码）

宏	值	含义
MEOW_OK	0	成功
MEOW_ERR_INVAL	-1	参数/取值非法
MEOW_ERR_NOENT	-2	键/资源不存在
MEOW_ERR_EXISTS	-3	已存在（如重复注册）
MEOW_ERR_PERM	-4	无权限（本机信任模型下少用，保留）
MEOW_ERR_IO	-5	读写（存储/文件）失败
MEOW_ERR_NOMEM	-6	内存不足
MEOW_ERR_NOTINIT	-7	未初始化（如 settings 未 init）
MEOW_ERR_BUSY	-8	忙（如服务已运行）
MEOW_ERR_TIMEOUT	-9	超时
MEOW_ERR_NODEV	-10	设备不存在（如无卡）
MEOW_ERR_INTERNAL	-255	内部错误

C 函数返回上述；HTTP 层映射为 HTTP 状态码 + {"code": <meow_err>, "msg": "..."}。

2. 设置子系统 C API（meow_settings.h）

2.1 类型与初始化

typedef enum { SET_INT, SET_STR, SET_ENUM, SET_BOOL } meow_set_type;

int  meow_settings_init(void);                    /* 加载存储，注册默认；重复调用幂等 */
int  meow_settings_shutdown(void);                /* 保存 + 清理 */
void meow_settings_dump(const char *log_prefix);  /* 调试：打印当前全部键 */

2.2 存取（按类型）

int  meow_settings_get_int (const char *key, int *out);
int  meow_settings_get_str (const char *key, char *buf, int buf_len);
int  meow_settings_get_enum(const char *key, int *out);
int  meow_settings_get_bool(const char *key, bool *out);

int  meow_settings_set_int (const char *key, int v);        /* clamp 到取值域 */
int  meow_settings_set_str (const char *key, const char *v);/* 长度截断 MEOW_SET_MAX_LEN(256) */
int  meow_settings_set_enum(const char *key, int v);        /* 校验枚举合法 */
int  meow_settings_set_bool(const char *key, bool v);

• 所有 clamp/校验集中在 set（亮度 clamp ≥ display.brightness_min 默认 1（M2.39 由 25 改 1，旧持久 25 自动迁移；[源:审计 2026-08-30]）、枚举越界拒绝、str 截断）。
• set 成功后自动 settings_save() 落盘（板载 /usr/data/meow/settings.conf）并通知 listener。

2.3 枚举辅助（供 UI/web 显示中文标签）

int meow_settings_enum_label(const char *key, int idx, char *buf, int buf_len); /* 中文标签 */
int meow_settings_enum_count(const char *key);                                  /* 选项数 */
int meow_settings_enum_index_of_name(const char *key, const char *name);        /* 名字→索引 */
void meow_settings_enum_names(const char *key, const char **out_names, int *n); /* 全名数组 */

2.4 变更通知

typedef void (*meow_settings_listener)(const char *key);   /* key 变化时回调，UI 据此重绘 */
int meow_settings_add_listener(meow_settings_listener cb);
int meow_settings_remove_listener(meow_settings_listener cb);

2.5 枚举/列表

int meow_settings_list(int (*cb)(const char *key, meow_set_type t, void *ctx), void *ctx);
int meow_settings_get_default(const char *key, char *buf, int len);  /* 默认值（复位用） */
int meow_settings_reset(const char *key);                             /* 单键复位默认 */
int meow_settings_reset_all(void);                                    /* 全量复位 */

2.6 导入/导出（备份）

int meow_settings_export(const char *path);   /* 写一份 .conf 到 path（默认 MeowOS/backups/settings/setting.bak） */
int meow_settings_import(const char *path);   /* 从 .conf 读入覆盖；逐键校验，记录损坏键（不中断） */

2.7 设置项注册（扩展规范——新增设置照此）

typedef struct meow_setting_def {
    const char *key;           /* 如 "display.brightness" */
    meow_set_type type;
    const char *def;           /* 默认值字符串（int/str/enum/bool 统一字符串） */
    int min, max;              /* SET_INT 取值域；其他 0 */
    const char *enum_names;    /* SET_ENUM：逗号分隔选项名，如 "panel,black" */
    const char *enum_labels;   /* 对应中文标签，如 "面板下电,背光全黑双击" */
} meow_setting_def;

int meow_settings_register(const meow_setting_def *def);  /* 注册一个设置（启动时批量注册） */

• 新增设置 = 加一个 meow_setting_def 注册 + 存储自动处理；实体 UI / web / CLI 依据 meow_settings_list 与 enum_* 自动生成控件，四端零新增。

3. 设置存储格式

文件（板载 /usr/data/meow/settings.conf）：

# meow-settings 1
display.brightness = 101
display.brightness_min = 1
display.screen_off_mode = panel
boot.default = meow
input.hotkey_seq = volup,volup,volup
log.level = info
...

• 单行 key = value；# 注释；未知键忽略；读入时 clamp/校验 与 set 一致。

4. Web（MeowPanel）HTTP API 映射

REST 路径，HTTP 层调 C API（本机）。

方法	路径	C API	说明
GET	/api/settings	meow_settings_list+get_*	返回全部键值
POST	/api/settings	meow_settings_set_*	body {key,value}
GET	/api/settings/keys	meow_settings_list	键/schema 描述（供前端生成控件）
POST	/api/settings/reset	meow_settings_reset/reset_all	body {key?}
GET	/api/settings/export	meow_settings_export(path)	下载 settings.conf
POST	/api/settings/import	meow_settings_import(path)	上传覆盖
GET	/api/status	meow_sys_status()	实时性能/电量/亮度/WiFi
GET	/api/device	meow_sys_devattr_refresh()	设备属性域全量（输出口/3.5·4.4 插入/按输出口分级音量上限(增益代理)/音量/DAC/蓝牙/电源；采样率·DSD·CPU温度=MEOW_ERR_NOENT，见 SYSTEM_SETTINGS 附B）
POST	/api/device	meow_devattr_set()	body {field,value}；白名单可控（out.port 1-4、vol、filter/nos/dre/dop/mute、bt.powered）
GET	/api/device/outport-label	meow_devattr_enum_label()	out.port 1-4 中文标签
GET	/api/notify	meow_notify_list	通知列表
POST	/api/notify/dismiss	meow_notify_dismiss	清一条
GET	/api/screen	meow_screen_capture()	实时画面（fb → PNG）
POST	/api/key	meow_input_inject()	远程按键（注：播放器级注入受内核限制，MeowOS 菜单/应用可用）

响应统一：{"code":0,"data":...} 或 {"code":-1,"msg":"..."}。

5. CLI/MCP（调试/自动化）

meowcli settings get|set|list|export|import <key> [value]；meowcli notify list|dismiss；meowcli status。与 C API 一一对应。

launcher 自测钩子（M2.16 渲染/刷新率调度/防抖）：meow_launcherd 增加 --scan（state=1 napps=0）、--sysdump（含 render: eff_rate cfg always_max frames，eff_rate=有效帧率 / cfg=display.refresh_rate / always_max=refresh_always_max / frames=累计呈现帧数）、--sim-vol N（音量渐变 N=1/2/5，长按 clamp）、--sim-hotkey/-tap/-exit[-tap]/-power-*/-no-exec、--appinfo <app.json>、--ipc-only N --ipc-sock <path>（配合 meow_ipc 验 HELLO→ACK / ACT_QUERY→链路）。渲染为 RAM 离屏后备缓冲 back_buf + meow_present(vsync+原子 blit 脏区)，刷新率调度入 PERF_SCHEDULER.md（meow_sched_fps() 归口）；设置键 display.refresh_rate(60/30/15)/display.refresh_always_max 见 SYSTEM_SETTINGS.md。

软件包管理另有独立 CLI nyai（与 launcher meow_pkg_install/export 同语义，支持镜像源）：用法见 APPS.md 附录 §5；部署于卡 MeowOS/opt/bin/nyai。

6. 扩展指南（新增功能的必读）

1. 命名单一：新域前缀 meow_<域>_；键名小写点分。
2. 设置项：只加 meow_setting_def（§2.7），勿动手写存取分支。
3. 返回码：复用 §1，不造新码；扩展加在表尾。
4. 线程/内存：设置域单写者（主循环）＋ listener；跨线程用 eventfd（参考 §18.29 并发模型）；字符串拷贝进 MEOW_SET_MAX_LEN 缓冲。
5. 持久化：只写板载 meow/settings.conf（小文件）；大数据（日志/字库/媒体）留 TF 卡。
6. 多端一致性：任何设置/接口改动，同步文档本文件 + 四端（实体 UI/web/CLI）。
7. 单元可用性：新 API 写进 ANALYSIS.md 对应 §，提供 --sim/meowcli 测试钩子。
8. line-out 保守默认（无实测，2026-08-29）：out.port=1(line-out) 按固定满幅电平处理——MeowOS 侧不响应音量键、不套 lock_vol 上限，UI 标注"固定电平输出"；仅设置显式开启"line-out 可调"才放开。out.gain(高/低) 标记 Unsupported/只读（选择值存 user.ini，读不干净、写有完整性风险，禁写）；信息透出只用 out.vol_max_headset/balance（=lock_vol，可读）响应度分级代理。详见 SYSTEM_SETTINGS 附 B。实现前再读该节，避免与 HibyOS 播放器设定冲突。

7. 待实现清单（按此文档开发）

• meow_settings 存储+核心 API+注册机制（阶段 B2a 后端，先于阶段 B）
• 实体系统设置页（分组列表+控件，调 API）
• meowcli settings 命令
• MeowPanel /api/settings*（阶段 C）
• 后续 notify/act/svc/media 域按本规范补充（阶段 D）