核心定位
uiflow2-coder 是专为 M5Stack UIFlow2 平台设计的 MicroPython 编程助手，覆盖从入门到高级硬件开发的全场景需求。其核心价值在于强制文档优先——所有代码生成前必须查阅官方文档，杜绝经验主义导致的 API 误用。
核心用法
开发流程四步闭环：
1. 需求分析：提取硬件/功能关键词，在 120+ 文档文件中定位目标模块（docs/unit/、docs/module/、docs/hardware/ 等 14 个分类）
2. 文档查阅：读取目标 .md 文件，提取构造函数、方法签名、参数类型、返回值说明及官方示例
3. 代码生成：严格遵循导入规范（from M5 import * 初始化、from unit import * 外接模块）、主循环必须包含 M5.update()、区分内置设备（M5.Imu）与外接模块（I2C 初始化）
4. 质量检查：验证显示性能（禁止循环 fillScreen()）、资源管理（单次初始化）、API 返回值处理（tuple 解包）
专项能力：
- 硬件抽象层：ADC、I2C、SPI、UART、CAN、LoRa、GPS、IMU、触摸、电源管理等全系列驱动
- UI 开发：m5ui（LVGL 封装）控件系统，含 30+ 组件（button、chart、keyboard、canvas 等）
- 网络与协议：WiFi STA/AP、ESP-NOW、BLE UART、MQTT、TCP/UDP、Modbus RTU/TCP、HTTP 请求
- 高级功能：摄像头（CoreS3 专属）、AI 推理（DL 模块）、OCR、二维码、音频录制与播放
显著优点
1. 权威性保障：强制绑定官方文档体系，代码与硬件手册 1:1 对应，消除版本漂移风险
2. 性能导向：内置 MicroPython 优化范式（批量解包、缓冲区复用、memoryview 零拷贝、DMA 音频）
3. 设备适配智能：自动识别内置 vs 外接硬件，避免总线冲突（如 CoreS3 摄像头限制、系统 I2C 保护）
4. UI 工程化：LVGL 最佳实践集成（分层重绘、局部更新、parent=page0 强制约束）
5. 调试友好：错误模式对照表（I2C.scan() 为空→检查系统总线占用）
潜在局限
- 硬件锁定：严格限定 M5Stack 生态，非 UIFlow2 设备（如 UIFlow1、原生 ESP-IDF）支持有限
- 文档依赖：离线场景下若文档缺失则无法生成代码（设计上拒绝"幻觉式"编程）
- 版本敏感：UIFlow2 持续迭代，文档滞后可能导致新 API 暂时不可用
- 摄像头限制：仅 CoreS3 支持摄像头 API，其他设备（Core2、Core 等）强行生成会导致系统崩溃
- 内存约束：未自动处理 MicroPython 堆内存分配，复杂场景需用户手动优化
适合人群
| 用户类型 | 典型场景 |
|---------|---------|
| 物联网开发者 | 快速原型传感器数据采集、LoRa/WiFi 通信 |
| 嵌入式工程师 | 工业 Modbus 网关、电机控制（PWM/步进/BLDC） |
| 教育者 | 硬件编程课程、MicroPython 教学项目 |
| 创客/DIY | 交互装置、手持设备（Cardputer）、HMI 面板 |
| 企业开发者 | M5Stack 商业项目交付、批量固件开发 |
常规风险
| 风险等级 | 场景 | 后果 |
|---------|------|------|
| **高** | 未读文档生成 `from m5stack import *` | 代码在 UIFlow2 直接报错 |
| **高** | 非 CoreS3 设备调用摄像头 API | SDIO 总线冲突，系统死机 |
| **中** | 循环中重复 `Speaker.begin()` | 内存泄漏，音频异常 |
| **中** | m5ui 控件未传 `parent=page0` | 界面切换后黑屏 |
| **中** | 触摸 API 返回值未按 tuple 处理 | `AttributeError` 崩溃 |
| **低** | 全屏 `fillScreen()` 高频调用 | 刷新率低下，视觉闪烁 |
最佳实践建议
- 始终先运行
./scripts/find_doc.sh <关键词>确认文档存在 - 复杂项目采用
setup()+loop()结构分离初始化与业务逻辑 - 高频数据场景预分配缓冲区，避免 GC 压力
- 多设备项目使用
docs/controllers/针对性优化（Cardputer 键盘、Paper 墨水屏等）