# 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 类型与初始化

```c
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 存取（按类型）

```c
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 显示中文标签）

```c
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 变更通知

```c
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 枚举/列表

```c
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 导入/导出（备份）

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

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

```c
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）