182 lines
11 KiB
Markdown
182 lines
11 KiB
Markdown
# 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）
|