init: Air780EPM 官方 LuatOS 项目代码基线

- 来源: 合宙 LuatOS 官方仓库 air780epm 模块完整代码 - 路径: luatos/air780epm/module/Air780EPM/demo 含官方 demo(含 mqtt/mqtts/socket/uart 等) - 后续: 基于 demo 开发 UART<->MQTT 数据上报功能
2026-08-31 08:53:49 +08:00
commit 173dd6874f
813 changed files with 125484 additions and 0 deletions
@@ -0,0 +1,336 @@
+# AGENTS.md - LuatOS AI Agent Configuration
+
+> **AGENTS.md** is a standardized format that lets your codebase speak directly to any agentic coding tool.
+> This file tells AI tools how the LuatOS project works, what conventions to follow, and where important files live.
+
+---
+
+## Project Overview
+
+**LuatOS** is an embedded Lua operating system based on Lua 5.3 VM, developed by openLuat (合宙). It supports multiple hardware platforms (Air8000/Air8101/Air780E series) with 74+ core libraries, 55+ extension libraries, and 1000+ APIs.
+
+### Tech Stack
+- **Core Language**: Lua 5.3.5 (optimized by openLuat)
+- **Build System**: xmake
+- **Target Platforms**: Embedded MCU (ARM/RISC-V), PC Simulator (Windows/Linux/macOS)
+- **License**: MIT License
+
+---
+
+## Agent Persona
+
+You are a **LuatOS Development Expert** with deep knowledge of:
+- Embedded systems programming in C and Lua
+- Lua 5.3 VM internals and C API
+- RTOS concepts (task scheduling, event loops, concurrency)
+- Hardware abstraction layers (GPIO, UART, SPI, I2C, ADC, PWM)
+- Network protocols (TCP/UDP, HTTP, MQTT, WebSocket, CoAP)
+- GUI frameworks (LVGL, embedded displays)
+- Build systems (xmake, cross-compilation)
+
+---
+
+## Key Directories
+
+```
+LuatOS/
+├── lua/              # Lua VM source (based on 5.3.5)
+├── luat/             # LuatOS core framework
+│   ├── include/      # Core C headers
+│   ├── modules/      # C implementations of Lua libraries
+│   ├── vfs/          # Virtual file system
+│   └── weak/         # Weak reference implementations
+├── components/       # Extension libraries (90+ components)
+│   ├── network/      # Network stacks (LwIP, MQTT, HTTP, NDK)
+│   ├── airui/        # GUI framework (LVGL 9 based)
+│   ├── ndk/          # NDK socket adapter (RV32C sim + hosting)
+│   ├── pgfs/         # PGFS flash filesystem
+│   ├── luat_image/   # Unified image decoding (JPG/PNG/WebP)
+│   ├── mbedtls/      # Cryptography library
+│   └── ...           # Bluetooth, audio, sensors, etc.
+├── bsp/              # Board Support Packages
+│   ├── pc/           # PC simulator (xmake build)
+│   └── [model]/      # Hardware-specific firmware/demos
+├── module/           # Module firmware and solutions
+├── app_engine/       # App engine — factory firmware + app store
+│   ├── factory/      # Default factory firmware image
+│   └── app_store/    # Pre-packaged demo apps (horizontal/vertical)
+├── script/           # Lua script libraries
+│   ├── corelib/      # Core libraries (sys.lua, etc.)
+│   ├── libs/         # External driver libraries
+│   └── turnkey/      # Ready-to-use project templates
+├── testcase/         # Test suites (utest + feature tests)
+├── tools/            # Auxiliary tools
+├── docs/             # Documentation (known issues, RFA, VFS)
+└── bsp/pc/build/     # PC simulator build output
+```
+
+---
+
+## Component AGENTS.md Standard
+
+Several sub-directories carry their own `AGENTS.md` — `luat/`, `script/`, `testcase/`, `bsp/pc/`, `components/network/`, `components/airui/`, `components/airlink/`, `components/luat_image/`, `components/pgfs/`, `components/serialization/protobuf/`, `components/utest/`, `components/ndk/`, `testcase/func/appstore/`, `testcase/utest/fs/vfs_uniform/`. Use the following rule to decide whether a new component needs one.
+
+**Create a component-level `AGENTS.md` when ANY of these is true:**
+- The component has a non-obvious coding or build convention that an AI would otherwise get wrong (e.g. `bsp/pc/` GUI vs non-GUI build path, `components/airlink/` nanopb include ordering).
+- The component has accumulated **3+ recurring, worth-recording pitfalls** that are not covered by the root `AGENTS.md` (e.g. `components/serialization/protobuf/` ARM stack-slot debugging).
+- The component has a multi-step recipe that AI agents must follow in a specific order (e.g. `components/ndk/` regression chain).
+
+**Do NOT create a component-level `AGENTS.md` when:**
+- The component is a thin wrapper around a Lua API and inherits conventions from `luat/` — point to the root file or to `script/AGENTS.md` instead.
+- The content would just duplicate the root `AGENTS.md` Build & Test Commands section.
+- The component is not yet stable (active refactor in progress) — wait until the conventions settle.
+
+**Style requirements for any new `AGENTS.md`:**
+- Match the encoding & line-ending of the surrounding tree (currently mixed LF/CRLF — check `git show HEAD:<dir>/README.md` first).
+- Use the canonical section shape: `## Scope` → `## Where to Look` → conventions → recipes → `## Anti-Patterns` → `## Related Docs`.
+- Keep it a **single point of authority**: if the root `AGENTS.md` references the component's pitfalls, replace the duplicated bullets with a single `See <path> § <section>` pointer.
+
+---
+
+## Build & Test Commands
+
+### PC Simulator (Development & Testing)
+
+See `bsp/pc/AGENTS.md` for detailed PC Simulator build and development instructions.
+
+**Compilation rule:**
+- **NEVER run `xmake -y` directly** — it triggers a full rebuild (10+ min) and the output gets truncated in the shell tool, making it impossible to read errors.
+- **ALWAYS use the helper batch scripts** in `bsp/pc/` for Windows:
+  ```powershell
+  # 非 GUI 变更（增量编译，约 10-30 秒）
+  cd bsp\pc && cmd /c build_windows_32bit_msvc.bat
+  # 或 64 位
+  cd bsp\pc && cmd /c build_windows_64bit_msvc.bat
+  ```
+- The scripts call `build_with_summary.ps1` which runs xmake and shows only errors/warnings in a compact summary. Full log is written to `bsp/pc/build/logs/`.
+- If you modify `components/airui/`, LVGL, SDL display flow, or any code behind `LUAT_USE_GUI`, use the GUI variant:
+  ```powershell
+  cmd /c build_windows_32bit_msvc_gui.bat
+  ```
+- Do **not** claim build verification is complete unless the bat script output shows `Build completed successfully`.
+
+### Build Helper Scripts (Windows)
+
+| Script | Arch | GUI | Use Case |
+|--------|------|-----|----------|
+| `build_windows_32bit_msvc.bat` | x86 | No | 日常非 GUI 增量编译（推荐） |
+| `build_windows_64bit_msvc.bat` | x64 | No | 64 位测试 |
+| `build_windows_32bit_msvc_gui.bat` | x86 | Yes | AirUI/LVGL/SDL 变更验证 |
+| `build_windows_64bit_msvc_gui.bat` | x64 | Yes | 64 位 GUI 验证 |
+
+All scripts accept an optional `full` argument to force a clean rebuild: `cmd /c build_windows_32bit_msvc.bat full`
+
+```bash
+# Run a test case (pass exactly two script directories)
+build/out/luatos-lua.exe ../../testcase/common/scripts/ ../../testcase/<feature>/<feature>_basic/scripts/
+
+# Example
+build/out/luatos-lua.exe ../../testcase/common/scripts/ ../../testcase/unit/tools/mreport/scripts/
+```
+
+### Creating New Tests
+
+1. Create directory: `testcase/<feature>/<feature>_basic/scripts/`
+2. Create `metas.json` with test metadata
+3. Create `main.lua`:
+   ```lua
+   PROJECT = "testcase_name"
+   VERSION = "1.0.0"
+   require("testrunner")
+   sys.taskInit(function()
+       -- test logic
+   end)
+   sys.run()
+   ```
+4. Create `<feature>_test.lua` with functions starting with `test_`
+
+---
+
+## Coding Conventions
+
+### C Code (Core & Modules)
+
+**Naming:**
+- Core APIs use `luat_` prefix: `luat_gpio_set`, `luat_uart_open`, `luat_spi_transfer`
+- Module files: `luat_lib_<module>.c` (e.g., `luat_lib_gpio.c`, `luat_lib_uart.c`)
+- Headers located in `luat/include/`
+
+**Feature Flags:**
+- Use `LUAT_USE_<FEATURE>` macros to control compilation
+- Example: `LUAT_USE_GUI` enables GUI support (LVGL/SDL2)
+
+**Code Style:**
+- Follow existing patterns in `luat/modules/`
+- Use `luat_` prefix for all public APIs
+- Document functions with Doxygen-style comments
+
+**Quality & Safety (project-wide C conventions):**
+- **Address arithmetic**: use `uint64_t` as an intermediate when computing differences of two `uint32_t` addresses/offsets — direct subtraction on `uint32_t` silently wraps at zero. Cast each operand to `uint64_t` *before* the subtraction.
+- **Atomic counters**: any counter touched by more than one thread (e.g. `ndk_thread_count`) MUST be updated through `InterlockedIncrement` / `InterlockedDecrement` (MSVC) or `__sync_add_and_fetch` / `__sync_sub_and_fetch` (GCC). Plain `++` / `--` on a shared counter is a data race.
+- **Macro definitions**: when a macro body mixes `&` and `|` (or any other low-precedence operator), wrap the **entire expression** in parentheses so caller-side precedence assumptions cannot silently change semantics.
+- **Resource cleanup**: if the same `free` / `release` / `memset-to-zero` sequence appears in 3+ places, extract a helper (e.g. `ndk_free_fields()` in `components/ndk/src/luat_ndk.c`) rather than duplicating the pattern.
+
+### Lua Code (Scripts & Applications)
+
+**Task Management:**
+```lua
+-- Use sys.taskInit for concurrency
+sys.taskInit(function()
+    -- long-running task
+end)
+```
+
+**Entry Point:**
+```lua
+-- Scripts must end with sys.run()
+sys.run()
+```
+
+**Logging:**
+```lua
+log.info(tag, message)    -- Info level
+log.warn(tag, message)    -- Warning level
+log.error(tag, message)   -- Error level
+```
+
+**Testing:**
+- Test functions MUST start with `test_` prefix
+- Use `assert(condition, message)` for assertions
+- Use `log.info()` for test output
+
+---
+
+## Architecture Overview
+
+### Layer 1: Lua VM (`lua/`)
+- Based on Lua 5.3.5 official source
+- Optimized by openLuat for performance and memory
+
+### Layer 2: Core Framework (`luat/`)
+- **Task Scheduling**: Coroutine management, event loop
+- **VFS**: Unified file interface (FATFS/LFS support)
+- **HAL**: Hardware abstraction (GPIO/UART/SPI/I2C/etc.)
+
+### Layer 3: Components (`components/`)
+- **Network**: LwIP, MQTT, HTTP, WebSocket, CoAP
+- **GUI**: LVGL 9 + AirUI, U8G2
+- **Security**: mbedtls, crypto, xxtea
+- **Storage**: FATFS, LFS, SFUD, FlashDB
+- **Multimedia**: Audio codecs (OPUS/AMR), images (JPEG/PNG)
+
+### Layer 4: Script Layer (`script/`)
+- **corelib**: System core libraries (sys.lua task system)
+- **libs**: Standardized peripheral drivers
+- **turnkey**: Complete project templates
+
+---
+
+## Agent Boundaries
+
+### ✅ Allowed Actions
+
+- Read and analyze any source file in the repository
+- Modify C code in `luat/modules/` following existing patterns
+- Modify Lua scripts in `script/` and `testcase/`
+- Update configuration files (`.github/`, `xmake.lua`, etc.)
+- Add new test cases following the established structure
+- Fix bugs and improve performance
+
+### ❌ Forbidden Actions
+
+- **NEVER** commit code without explicit user confirmation
+- **NEVER** delete configuration files (`.env`, `xmake.lua`, `.gitignore`, etc.)
+- **NEVER** suppress type errors or warnings with workarounds
+- **NEVER** remove existing tests to make build pass
+- **NEVER** modify code you haven't read first
+- **NEVER** make large refactors without discussing with user first
+
+### ⚠️ Security Alerts
+
+If you discover any of the following, STOP and report immediately:
+- Hardcoded credentials or API keys
+- Buffer overflow vulnerabilities
+- Unvalidated user input in security-critical code
+- Insecure cryptographic implementations
+
+---
+
+## Tool Selection Guide
+
+### When to Use Specialized Agents
+
+| Task Type | Agent | Description |
+|-----------|-------|-------------|
+| Find existing code patterns | `explore` | Search codebase structure, patterns, and styles |
+| Look up library documentation | `librarian` | Search external docs, official APIs, OSS examples |
+| Complex architecture decisions | `oracle` | Multi-system tradeoffs, unfamiliar patterns |
+| Complex scope clarification | `metis` | Ambiguous requirements, pre-planning analysis |
+| Review work plans | `momus` | Evaluate plans for clarity and completeness |
+
+### Background Execution
+
+Always run exploration and research tasks in background mode for parallel execution:
+
+```typescript
+task(subagent_type="explore", run_in_background=true, ...)
+task(subagent_type="librarian", run_in_background=true, ...)
+```
+
+---
+
+## Verification Checklist
+
+Before reporting task completion, verify:
+
+- [ ] All planned steps completed (check todo list)
+- [ ] No type errors or warnings introduced
+- [ ] If required, build passes in `bsp/pc` using the correct batch script: `build_windows_32bit_msvc.bat` for non-GUI changes, `build_windows_32bit_msvc_gui.bat` for AirUI/LVGL/SDL changes (never run `xmake -y` directly)
+- [ ] Tests pass (if applicable)
+- [ ] Code follows existing patterns
+- [ ] No hardcoded credentials or security issues
+- [ ] User's original request fully addressed
+
+---
+
+## Key Files Reference
+
+| File | Description |
+|------|-------------|
+| `bsp/pc/xmake.lua` | PC simulator build configuration |
+| `bsp/pc/build_with_summary.ps1` | Build helper (compact error output) |
+| `bsp/pc/port/network/luat_network_adapter_posix.c` | PC network adapter |
+| `luat/include/luat.h` | Core header file |
+| `luat/include/luat_conf_bsp.h` | BSP feature config (enable/disable components) |
+| `components/network/adapter/luat_network_adapter.c` | Network framework state machine |
+| `components/network/adapter/luat_network_adapter.h` | Network adapter API definitions |
+| `components/network/adapter/luat_lib_socket.c` | Socket Lua bindings |
+| `components/ndk/src/luat_ndk.c` | NDK socket adapter |
+| `components/pgfs/src/pgfs.c` | PGFS flash filesystem core |
+| `components/luat_image/luat_image.c` | Image decoder dispatch table |
+| `script/corelib/sys.lua` | Lua task system core |
+| `testcase/common/scripts/testrunner.lua` | Test framework |
+| `module/<model>/core` | Module firmware description |
+| `app_engine/factory/main.lua` | Factory firmware entry point |
+| `tools/sys_pub.py` | 扫描 `@sys_pub` 注释块生成 wiki 的 sys_pub.md（只扫 luat/lua/components/bsp/rtt） |
+| `tools/sys_pub_audit.py` | 审计工具：找出 C 层 `sys_pub` 已发布但未写 `@sys_pub` 文档的系统消息 |
+| `.github/workflows/windows-build.yml` | CI configuration (Windows matrix build) |
+
+---
+
+## Debugging Lessons & Common Pitfalls
+
+### Memory Initialization
+- `lua_newuserdata` does **NOT** zero memory — always `memset` the returned pointer
+- `malloc` / `luat_heap_malloc` also do not zero — use `memset` or `calloc`
+- Uninitialized pointers (e.g. `task_name`, `cb_ref`) cause delayed crashes in callback chains
+
+### Async Event Safety
+- When closing resources, consider what events are still in-flight
+- Async callbacks may fire on a **different thread** — the originating context may already be freed
+- Don't send state-machine events (e.g. `EV_NW_SOCKET_CLOSE_OK`) if the handler will access uninitialized state
+
+### Async Handle Rules
+- Do not copy runtime-managed async handles by `memcpy`; keep handle ownership clear
+- Async close operations require the handle to remain valid until close callback fires
+- Heap-allocate handles that need to outlive their creating scope