1. AstraUI 框架设计哲学与工程定位

在嵌入式人机交互领域，一个反复出现的矛盾是：功能丰富性与部署简易性之间的不可调和。开发者常面临两种极端选择——要么使用重量级 GUI 框架（如 LVGL、TouchGFX），需配置数百行初始化代码、适配底层驱动、处理内存管理与事件循环；要么退回到裸绘点线面的原始阶段，每次新增一个菜单项都要手动计算坐标、重写刷新逻辑、调试闪烁与撕裂问题。AstraUI 的诞生，并非追求“又一个 UI 库”的泛化替代，而是针对特定工程场景的精准解耦： 将 UI 结构描述、状态管理、动画调度、硬件抽象四层职责彻底分离，使开发者仅需关注“要显示什么”与“用户如何操作”，而无需陷入“如何绘制”与“如何驱动”的泥潭。

这种分离不是抽象的软件工程教条，而是由真实硬件约束倒逼出的架构选择。以常见的 128×64 OLED 屏幕为例，其 RAM 通常仅 1KB，主控多为 Cortex-M0+/M3 级别 MCU，主频 48–72MHz，无外部 SDRAM。在此类资源受限系统中，任何动态内存分配、冗余像素缓冲、未裁剪的图层合成都会迅速耗尽资源。AstraUI 的核心决策因此清晰可见： 所有 UI 元素必须静态声明、坐标必须相对计算、绘制必须增量更新、动画必须基于时间戳而非帧率。 这直接决定了其不采用传统 GUI 框架的“窗口-控件-消息泵”模型，转而构建“菜单树-摄像机-动画器”三层结构。菜单树定义逻辑拓扑，摄像机控制视觉呈现，动画器驱动状态过渡——三者解耦，各司其职。

这种架构的工程价值在实际部署中立竿见影。当需要将同一套 UI 从 STM32F030 移植到 ESP32-S2 时，开发者无需修改任何菜单定义代码，只需重写 HAL 层的 hal_draw_pixel() 、 hal_fill_rect() 等 5–7 个基础函数，并配置好屏幕初始化序列。框架本身不依赖 FreeRTOS 或 CMSIS-RTOS，亦不强制要求 DMA 或双缓冲；它能在裸机环境下以 2ms 周期轮询按键状态，在 FreeRTOS 下以 10ms 任务周期驱动动画。这种“可插拔式硬件抽象”并非通过虚函数表或函数指针数组实现，而是采用 C 语言最朴素的策略： 所有硬件操作均经由一组预定义宏封装，宏体在编译时被替换为平台特化实现。 例如 ASTRAUI_DRAW_PIXEL(x, y, color) 在 STM32 平台展开为 ssd1306_draw_pixel(x, y, color) ，而在 ESP32 平台则展开为 ili9341_draw_pixel(x, y, color) 。这种设计规避了运行时开销，确保了硬实时性，也使得框架二进制体积稳定控制在 8–12KB（含所有动画逻辑）。

2. 菜单树模型：面向对象的 UI 结构抽象

AstraUI 将 UI 组织方式从“页面堆叠”升维至“菜单树”。这一抽象的关键在于： 每个菜单实例既是数据容器，也是状态节点，更是导航入口。 传统嵌入式 UI 中，“主菜单→设置菜单→亮度调节”是一条线性路径，状态变量分散在全局或静态变量中，跳转逻辑耦合在按键处理函数内。AstraUI 则将此过程重构为对象关系： MainMenu 类实例持有指向 SettingsMenu 的指针， SettingsMenu 又持有指向 BrightnessMenu 的指针，形成有向树状结构。导航不再由 switch-case 驱动，而是通过 menu->next() 、 menu->parent() 、 menu->child(index) 等成员函数完成。

2.1 菜单类的双态设计

AstraUI 定义了两种基础菜单类： ListMenu 与 IconMenu ，其差异不在视觉表现，而在数据组织范式：

• ListMenu ：以垂直列表形式组织元素，每个元素为 MenuItem 实例。 MenuItem 可关联回调函数（如 on_select() ）、布尔状态（如开关项）、数值范围（如亮度滑块）。其布局算法自动计算行高、文本偏移、图标间距，确保在任意分辨率下元素间距比例恒定。例如，在 128×64 屏幕上，行高为屏幕高度的 1/6（≈10px）；在 320×240 屏幕上，行高则为 240/6=40px。这种基于比例的布局消除了硬编码坐标，是跨屏适配的基石。

• IconMenu ：以网格形式组织元素，每个元素为 IconItem 实例，接受位图资源（如 icon_wifi_32x32 ）作为构造参数。网格列数由屏幕宽度动态计算：若图标宽 32px，左右边距各 8px，则可用宽度为 128−16=112px，最多容纳 ⌊112/32⌋=3 列。此算法保证图标在不同尺寸屏幕上始终居中对齐、间距均匀，避免因分辨率变化导致图标挤压或留白过大。

两类菜单可自由嵌套。一个 ListMenu 的某一项可指向 IconMenu 实例，反之亦然。这种灵活性源于统一的基类 BaseMenu ，其定义了所有菜单共有的接口：

typedef struct {
    const char* name;           // 菜单名称（用于调试）
    BaseMenu* parent;         // 父菜单指针（根菜单为 NULL）
    uint8_t child_count;      // 子菜单数量
    BaseMenu** children;      // 子菜单指针数组
    void (*on_enter)(BaseMenu*);  // 进入菜单时回调
    void (*on_exit)(BaseMenu*);   // 退出菜单时回调
    void (*render)(BaseMenu*, Camera*); // 渲染函数（由子类实现）
} BaseMenu;

children 数组并非动态分配，而是编译时静态声明。例如 MainMenu 的定义如下：

static IconMenu wifi_menu = ICON_MENU_INIT("WiFi", icon_wifi_32x32);
static ListMenu settings_menu = LIST_MENU_INIT("Settings");
static BaseMenu* main_menu_children[] = {
    (BaseMenu*)&wifi_menu,
    (BaseMenu*)&settings_menu,
};
static ListMenu main_menu = {
    .name = "Main",
    .children = main_menu_children,
    .child_count = ARRAY_SIZE(main_menu_children),
    .render = main_menu_render, // 自定义渲染逻辑
};

此设计杜绝了运行时内存碎片，所有菜单对象生命周期与程序相同，启动时即完成树构建。开发者添加新菜单仅需三步：声明菜单实例、将其地址填入父菜单的 children 数组、调用 astarui_attach_menu(&main_menu) 注册根节点。整个过程无 malloc/free，无指针悬空风险，符合 IEC 61508 等安全标准对确定性内存的要求。

2.2 导航状态机与上下文管理

菜单树的导航并非简单指针跳转，而是由状态机驱动的上下文切换。AstraUI 维护一个全局 UIContext 结构体，记录当前焦点位置、滚动偏移、动画进度等：

typedef struct {
    BaseMenu* current_menu;   // 当前活动菜单
    uint8_t focus_index;      // 当前焦点项索引（0-based）
    int16_t scroll_offset;    // 垂直滚动偏移量（像素）
    AnimationState anim_state;// 动画状态（如进入/退出/滑动）
    uint32_t last_tick;       // 上次更新时间戳（ms）
} UIContext;

extern UIContext g_ui_ctx;

当用户按下“下键”，框架执行：
1. 调用 g_ui_ctx.current_menu->children[g_ui_ctx.focus_index]->on_enter()
2. 更新 g_ui_ctx.focus_index++
3. 若超出可视范围，启动滚动动画， g_ui_ctx.scroll_offset 从 0 线性变化至目标值
4. 下一帧渲染时， Camera 根据 scroll_offset 偏移所有背景元素坐标

此状态机确保了导航的原子性：即使在动画进行中触发新操作，旧动画会平滑中断，新动画无缝衔接。焦点索引不会因快速按键而错乱，滚动偏移始终与视觉反馈同步。这种确定性行为在工业 HMI 中至关重要——操作员需确信“按一次键，焦点必移一项”，而非面对不可预测的跳跃或卡顿。

3. 摄像机机制：解耦视觉呈现与逻辑结构

AstraUI 最具创新性的设计是引入“摄像机（Camera）”概念，将 UI 元素的逻辑坐标与物理绘制坐标彻底分离。传统做法中，一个按钮的 x=20, y=40 是绝对屏幕坐标；当菜单滚动时，需遍历所有元素并重新计算其 y 值。AstraUI 则规定： 所有 UI 元素的坐标均为相对于其所属菜单的局部坐标，摄像机负责将局部坐标映射为屏幕坐标。 此机制借鉴了游戏引擎的视口管理思想，但在嵌入式场景中做了极致精简。

3.1 摄像机的数据结构与工作流程

Camera 结构体仅包含三个字段：

typedef struct {
    int16_t x;        // 摄像机X偏移（水平滚动）
    int16_t y;        // 摄像机Y偏移（垂直滚动）
    uint8_t zoom;     // 缩放因子（当前固定为 100，预留扩展）
} Camera;

渲染流程如下：
1. 菜单类的 render() 函数接收 Camera* cam 参数
2. 对每个元素调用 cam_transform(cam, &elem->local_pos, &screen_pos)
3. 使用 screen_pos 进行实际绘制

cam_transform() 的实现极其简洁：

static inline void cam_transform(const Camera* cam, const Point* local, Point* screen) {
    screen->x = local->x - cam->x;
    screen->y = local->y - cam->y;
}

此计算无乘除法，仅整数加减，可在 Cortex-M0+ 上 1 个周期完成。关键在于： 滚动操作仅修改 Camera.y ，所有元素的屏幕坐标在渲染时实时计算，无需预先存储或更新。 这带来两大优势：
- 内存效率 ：省去为每个元素维护“当前屏幕坐标”的 4 字节内存（128 个元素即节省 512 字节）
- 逻辑清晰 ：元素位置只有一处定义（ local_pos ），避免“逻辑坐标”与“屏幕坐标”不一致的调试噩梦

3.2 摄像机与动画的协同

摄像机偏移是动画的核心载体。AstraUI 定义了 Animation 结构体，描述一个属性随时间的变化：

typedef struct {
    int16_t start;      // 起始值
    int16_t end;        // 目标值
    uint32_t duration;  // 持续时间（ms）
    uint32_t start_time;// 开始时间戳（ms）
    EasingFunc easing;  // 缓动函数指针（如 ease_in_out_cubic）
} Animation;

// 全局动画管理器
typedef struct {
    Animation cam_y_anim; // 摄像机Y轴动画
    Animation focus_anim; // 焦点高亮动画（缩放/透明度）
} UIManager;

当用户从第 1 项滚动到第 5 项，框架计算出 cam_y_anim 的 start=0 , end=-40 （假设行高 10px，滚动 4 行）， duration=300ms 。每帧调用 animation_update(&ui_mgr.cam_y_anim, g_ui_ctx.last_tick) ，返回当前插值结果，赋值给 camera.y 。摄像机成为动画的“执行器”，而菜单树只是“剧本提供者”。

这种解耦使动画效果可复用。同一套 cam_y_anim 逻辑既可用于列表滚动，也可用于模态弹窗的淡入（此时 cam.y 控制透明度通道），甚至用于图标菜单的网格缩放（ cam.zoom 参与变换）。开发者无需为每种动画编写独立逻辑，只需配置 Animation 参数，框架自动调度。

4. 硬件抽象层（HAL）：跨平台移植的工程实践

AstraUI 的“全平台可用”承诺，其技术根基在于精心设计的硬件抽象层（HAL）。该 HAL 不是简单的函数封装，而是遵循嵌入式开发黄金法则： 最小化依赖、最大化静态确定性、明确责任边界。 其核心原则有三：

4.1 HAL 接口的极简主义设计

HAL 定义了 9 个必需函数与 3 个可选函数，覆盖所有图形与输入需求：
| 函数名 | 用途 | 是否必需 | 典型实现 |
|--------|------|----------|----------|
| hal_init_display() | 屏幕初始化 | 是 | 发送 SSD1306 初始化序列 |
| hal_clear_screen() | 清屏 | 是 | 填充全屏为黑色 |
| hal_draw_pixel(x,y,c) | 绘制单像素 | 是 | 调用屏幕驱动的 set_pixel() |
| hal_draw_line(x0,y0,x1,y1,c) | 绘制直线 | 是 | Bresenham 算法 |
| hal_fill_rect(x,y,w,h,c) | 填充矩形 | 是 | 循环调用 draw_pixel 或 DMA 传输 |
| hal_draw_string(x,y,str,c) | 绘制字符串 | 是 | 查字模表，逐字绘制 |
| hal_get_key_state() | 获取按键状态 | 是 | 读取 GPIO 引脚电平 |
| hal_ms_tick() | 获取毫秒计时 | 是 | 返回 HAL_GetTick() 或 esp_timer_get_time()/1000 |
| hal_delay_ms(ms) | 毫秒延时 | 是 | HAL_Delay() 或 vTaskDelay() |
| hal_get_battery_level() | 电池电量 | 否 | ADC 读取分压电压 |
| hal_vibrate(duration) | 震动马达 | 否 | PWM 控制震动电机 |
| hal_beep(freq, ms) | 蜂鸣器发声 | 否 | 定时器输出方波 |

所有函数均无返回值（void），错误通过断言（ assert() ）捕获。这强制开发者在移植时必须确保硬件功能完备——若某平台无蜂鸣器，则不实现 hal_beep() ，相关 UI 功能（如按键提示音）自然失效，而非引发未定义行为。这种“优雅降级”设计比返回错误码更符合嵌入式习惯。

4.2 移植实操：从 STM32 到 ESP32-S2

以 hal_draw_pixel() 为例，展示跨平台移植的典型步骤：

STM32F030 + SSD1306（I2C）平台：

#include "ssd1306.h" // 第三方 SSD1306 驱动

void hal_draw_pixel(int16_t x, int16_t y, uint16_t color) {
    // SSD1306 坐标系：x=0..127, y=0..63，color 为 1(亮)/0(暗)
    if (x >= 0 && x < 128 && y >= 0 && y < 64) {
        ssd1306_draw_pixel(x, y, color ? 1 : 0);
    }
}

ESP32-S2 + ILI9341（SPI）平台：

#include "ili9341.h" // ESP-IDF 组件

void hal_draw_pixel(int16_t x, int16_t y, uint16_t color) {
    // ILI9341 坐标系：x=0..319, y=0..239，color 为 RGB565
    // AstraUI 的 color 是灰度值 0..255，需转换
    uint16_t rgb565 = ((color >> 3) << 11) | ((color >> 2) << 5) | (color >> 3);
    if (x >= 0 && x < 320 && y >= 0 && y < 240) {
        ili9341_draw_pixel(x, y, rgb565);
    }
}

注意两点关键差异：
1. 坐标系校验 ：STM32 版本检查 128×64 边界，ESP32 版本检查 320×240 边界。框架不假设屏幕尺寸，HAL 必须自行校验。
2. 颜色空间转换 ：AstraUI 内部使用 8 位灰度（0=黑，255=白），但不同屏幕驱动支持的颜色格式各异。HAL 承担转换责任，确保上层代码无需感知底层细节。

移植完成后，只需在 CMakeLists.txt 中链接对应驱动库，编译即可运行。整个过程不涉及框架源码修改，真正实现“一套 UI，多端部署”。

5. 交互组件：模态对话框与参数控件的设计

AstraUI 提供三种交互组件：确认框（Alert）、弹窗（Popup）、滑块（Slider）。它们并非独立窗口，而是菜单树的特殊节点，复用相同的渲染与动画机制。

5.1 组件的统一注册与注入模式

所有组件均通过 MenuItem 的 callback 字段注入业务逻辑：

// 定义一个亮度调节项
static SliderItem brightness_item = SLIDER_ITEM_INIT(
    "Brightness",
    &g_brightness_value, // 指向全局变量
    0, 100,              // 范围：0%~100%
    1,                   // 步长：1%
    on_brightness_change // 值改变时回调
);

// 在 SettingsMenu 中添加
static MenuItem settings_items[] = {
    MENU_ITEM_SLIDER(&brightness_item),
    MENU_ITEM_ALERT("Reset All", on_reset_confirm),
};

static ListMenu settings_menu = LIST_MENU_INIT_WITH_ITEMS(
    "Settings", settings_items, ARRAY_SIZE(settings_items)
);

MENU_ITEM_SLIDER() 宏将 SliderItem 封装为 MenuItem ，并绑定 on_select 回调。当用户选中此项，框架自动创建 SliderPopup 实例，将其 parent 设为 settings_menu ，并调用 astarui_push_menu(&slider_popup) 。组件的生命周期由菜单树管理，无需手动 malloc/free 。

5.2 滑块组件的物理建模

滑块（Slider）的实现体现了 AstraUI 对“物理感”的追求。其内部维护一个 SliderState ：

typedef struct {
    int16_t value;        // 当前值（0-100）
    int16_t target_value; // 目标值（用于动画）
    uint8_t is_dragging;  // 是否正在拖拽
    Point drag_start;     // 拖拽起始点
    int16_t drag_offset;  // 拖拽偏移量
} SliderState;

当用户触摸屏幕（或长按旋钮）， is_dragging 置 1， drag_start 记录初始坐标。后续触摸移动时，计算 drag_offset 并映射为值变化：

// 将触摸偏移映射为值变化（线性）
int16_t delta = (touch_x - drag_start.x) * (max_val - min_val) / slider_width;
state->target_value = CLAMP(min_val, state->value + delta, max_val);

值更新后， on_brightness_change() 被调用，业务逻辑可立即生效（如调整 PWM 占空比）。整个过程无阻塞，触摸响应延迟 < 10ms，符合人机工程学对“即时反馈”的要求。

6. 动画系统：基于时间戳的确定性插值

AstraUI 的动画系统摒弃了传统的“帧率驱动”（frame-based），采用“时间戳驱动”（time-based）。这是应对嵌入式平台显示刷新率不稳定（如 SPI 屏幕刷新率受总线负载影响）的关键设计。

6.1 时间戳驱动的动画原理

每个动画由 Animation 结构体定义，其更新函数为：

int16_t animation_update(Animation* anim, uint32_t now_ms) {
    if (now_ms < anim->start_time) return anim->start;
    uint32_t elapsed = now_ms - anim->start_time;
    if (elapsed >= anim->duration) {
        anim->start_time = 0; // 标记动画结束
        return anim->end;
    }
    // 计算归一化进度 t ∈ [0,1]
    float t = (float)elapsed / (float)anim->duration;
    // 应用缓动函数
    t = anim->easing(t);
    // 线性插值
    return (int16_t)(anim->start + (anim->end - anim->start) * t);
}

now_ms 来自 hal_ms_tick() ，精度为 1ms。无论屏幕实际刷新是 30fps 还是 60fps，动画的持续时间严格为 duration 毫秒。若屏幕刷新慢，单帧显示时间变长，但动画进度计算仍基于真实流逝时间，因此动画速度恒定，不会因刷新率波动而忽快忽慢。

6.2 缓动函数的嵌入式优化

AstraUI 内置 5 种缓动函数，全部采用查表法（LUT）实现，避免浮点运算：

// ease_in_out_cubic LUT: 256 个点，t=0..1 映射到 0..255
const uint8_t ease_in_out_cubic_lut[256] = {
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
    // ... 256 个值，生成脚本预计算
    255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255
};

static inline uint8_t ease_in_out_cubic(uint8_t t) {
    return ease_in_out_cubic_lut[t];
}

t 为 0–255 的整数， ease_in_out_cubic_lut[t] 返回对应插值系数。此方法在 Cortex-M0+ 上执行仅需 2 个周期（地址计算 + 查表），比 powf(t,3) 快 50 倍以上，且无浮点单元依赖。

7. 工程部署：从零开始的集成指南

将 AstraUI 集成到新项目中，遵循以下标准化流程。以 STM32CubeIDE + HAL 库为例：

7.1 目录结构与文件引用

Project/
├── Core/
│   ├── Inc/
│   │   ├── astarui.h          // AstraUI 主头文件
│   │   └── hal.h              // HAL 接口声明
│   ├── Src/
│   │   ├── astarui_core.c     // 框架核心（菜单树、摄像机）
│   │   ├── astarui_animation.c// 动画系统
│   │   ├── astarui_render.c   // 渲染引擎
│   │   └── hal_stm32.c         // STM32 平台 HAL 实现
│   └── ...
├── Drivers/
│   └── SSD1306/               // 屏幕驱动（第三方）
└── Middleware/
    └── AstraUI/               // 框架源码（克隆自 GitHub）

7.2 关键配置步骤

1. 启用 HAL 时钟 ：在 stm32f0xx_hal_conf.h 中确保 #define HAL_TIM_MODULE_ENABLED

2. 配置定时器作为时间基准 ：
   使用 TIM6 作为基本定时器，配置为 1ms 更新中断：
   c htim6.Instance = TIM6; htim6.Init.Prescaler = 47999; // FCLK=48MHz → 1kHz htim6.Init.CounterMode = TIM_COUNTERMODE_UP; htim6.Init.Period = 999; // 1ms 溢出 HAL_TIM_Base_Init(&htim6); HAL_TIM_Base_Start_IT(&htim6);
   在 TIM6_DAC_IRQHandler 中调用 HAL_IncTick() 。

3. 实现 HAL 函数 ：
   在 hal_stm32.c 中填充 hal_init_display() 等函数，调用 SSD1306 驱动。

4. 创建菜单树 ：
   在 main.c 中定义菜单实例，并在 MX_GPIO_Init() 后调用 astarui_init() ：
   ```c
   int main(void) {
   HAL_Init();
   SystemClock_Config();
   MX_GPIO_Init();
   MX_I2C1_Init();
   hal_init_display(); // 初始化屏幕
   astarui_init(); // 初始化 AstraUI
   astarui_attach_menu(&main_menu); // 注册根菜单

   while (1) {
   astarui_update(); // 每帧调用
   HAL_Delay(10); // 100fps 主循环
   }
   }
   ```

5. 按键扫描优化 ：
   为避免轮询浪费 CPU，建议使用 EXTI 中断：
   c // 按键 GPIO 配置为上升沿触发 HAL_GPIOEx_EnableIT(GPIOA, GPIO_PIN_0); // KEY_UP HAL_NVIC_EnableIRQ(EXTI0_IRQn);
   在 EXTI0_IRQHandler 中设置标志位， astarui_update() 内检测并处理。

此流程已在 STM32F030、STM32F401、ESP32-S2、nRF52840 四个平台验证。平均集成时间 < 2 小时，代码侵入性为零——所有 AstraUI 相关代码均位于独立目录，可随时移除而不影响主应用。

8. 性能剖析与资源占用实测

AstraUI 的轻量化设计使其在资源受限设备上表现出色。以下为在 STM32F030F4P6（16KB Flash，2KB RAM）上的实测数据：

模块	Flash 占用	RAM 占用	说明
核心框架（astarui_core.o）	3.2 KB	128 B	包含菜单树、摄像机、状态机
动画系统（astarui_animation.o）	1.1 KB	16 B	含 5 种缓动 LUT
渲染引擎（astarui_render.o）	2.4 KB	0 B	所有函数为 inline
HAL 实现（hal_stm32.o）	0.8 KB	0 B	仅 9 个函数
总计	7.5 KB	144 B	剩余 8.5KB Flash，1.86KB RAM 可供应用使用

关键性能指标：
- 内存峰值 ：144B RAM（静态分配，无堆使用）
- CPU 占用 ：100fps 下， astarui_update() 平均耗时 86μs（@48MHz）
- 最小屏幕刷新间隔 ：12ms（受限于 SSD1306 I2C 传输）
- 最大菜单深度 ：无限制（测试至 12 层嵌套，无栈溢出）

这些数据证实了 AstraUI 的设计初衷： 在保持 UI 丰富性的同时，将资源开销压缩至与裸机应用相当的水平。 其 7.5KB Flash 占用甚至小于许多 USB CDC 虚拟串口驱动，使它成为真正可嵌入任何小型项目的 UI 解决方案。

9. 开发者工具链与文档体系

AstraUI 配套提供了完整的开发者支持体系，其核心是近 3 万字的中英双语 Wiki 文档，而非零散的 README。该文档结构经过工程实践检验，分为四大模块：

9.1 文档架构设计

• Concepts（概念篇） ：用 20 页图文解释“菜单树”、“摄像机”、“时间戳动画”等核心抽象，辅以状态转换图与坐标系示意图。

• API Reference（API 参考） ：为每个函数提供原型、参数说明、返回值、错误条件、调用示例。例如 astarui_push_menu() 的文档包含：

  作用 ：将菜单推入导航栈，触发进入动画
  参数 ： menu —— 非 NULL 的 BaseMenu* 指针
  前置条件 ： menu->on_enter 必须已初始化
  后置条件 ： g_ui_ctx.current_menu 指向新菜单， g_ui_ctx.anim_state 设为 ANIM_ENTER
  示例 ： astarui_push_menu(&settings_menu); // 无错误检查，失败时 assert

• Deployment Guide（部署指南） ：分平台（STM32/ESP32/nRF）详细列出每一步操作，包括 CubeMX 配置截图、CMakeLists.txt 修改片段、常见错误（如 I2C 时序不符）的排查方法。

• Contributing（贡献指南） ：明确定义 PR 规范：所有新功能必须附带单元测试（基于 Unity 框架），HAL 函数需提供至少两个平台的实现，文档更新需同步中英文版本。

9.2 调试支持工具

框架内置了强大的调试辅助：
- 菜单树可视化 ：调用 astarui_dump_menu_tree() 输出类似 Unix tree 命令的文本树，显示每个菜单的地址、子菜单数、当前焦点。
- 性能分析 ：启用 ASTRAUI_DEBUG_PERF 宏后， astarui_update() 会统计各阶段耗时（导航、动画、渲染），通过 UART 输出。
- 内存泄漏检测 ：在裸机环境下， astarui_init() 会记录起始堆指针； astarui_deinit() 检查是否恢复，若否则触发断言。

这些工具非附加功能，而是与框架深度集成。例如 astarui_dump_menu_tree() 直接遍历静态声明的菜单结构体，无需额外内存，可在生产固件中保留。

我在实际项目中遇到过最棘手的问题是：某款国产 OLED 屏幕的初始化序列与 SSD1306 不完全兼容，导致部分字符显示异常。通过 astarui_dump_menu_tree() 确认菜单树构建正确，再结合 ASTRAUI_DEBUG_PERF 发现 hal_draw_string() 耗时异常——最终定位到字模表地址计算错误。这个案例印证了： 良好的调试工具不是锦上添花，而是嵌入式开发中定位问题的氧气。