开发指南

开发前阅读固件仓库的 AGENTS.md、platformio.ini 和对应模块源码，检查 git status --short，保留已有修改。设备端文档维护在独立的 FastBee-doc 仓库 src/device/。

环境与目录

使用 Node.js 20+、Python 3、PlatformIO，以及 Native 测试需要的主机 C++ 工具链。Windows 上先确认 Python 解释器，可优先使用 PlatformIO 虚拟环境；避免系统旧版 Python。依赖存在且可用时无需重复安装。

固件支持的正式环境包括 ESP32、ESP32-C3、ESP32-C6、ESP32-S3 的九种 Flash/PSRAM 组合，详见构建配置。板卡及专用RGB屏幕仍需匹配板级配置。

源码在 src/、include/，Web源码在 web-src/，默认配置在 data/config/。修改 HTML/JS/CSS 后通过现有构建流程生成 data/www/，不直接编辑压缩包。目录详见项目结构。

增加传感器

先判断能否复用通用 SENSOR=38 及现有驱动体系。普通新增传感器不必再分配一个外设类型；已有枚举值不能重用，例如50已用于DS1302。

在 include/core/interfaces/ISensorDriver.h 核对接口，实现 getName/getChannelCount/getChannelName/getChannelUnit/init/read/deinit，以及必要的 getMinInterval/getLastError。参数是JSON编码字符串，读取输出为 SensorReading，不是任意返回一个float。
参考 src/peripherals/ 中同类驱动，通过 FASTBEE_REGISTER_SENSOR 和 DriverRegistry 注册，核对注册容量、编译依赖、驱动描述与别名。注册名称存在不代表实例已初始化。
同步 SensorConfigSupport、驱动元数据、缓存及执行读取入口；I2C/SPI等资源通过既有总线服务处理。初始化失败需清理自身资源，退出不能破坏共享总线。
读数成功标记、通道数、字段、单位、时间和诊断必须一致。转换需要等待时参考现有协作读取接口；失败不能返回有效零值。
同步 Web 表单、中文与英文文案、能力与功能门控。新增可选资源默认关闭，配置保存失败保留原有效版本。
补充真实驱动/序列化/生命周期回归，覆盖有效零、超时、无效读数、重复启停、预算拒绝和旧配置兼容。随后按影响范围构建与实机验证。

外设类型、动作和参数详见外设指南、传感器指南。文档中的接线仅为示例，不能直接套到所有芯片。

协议与 API

当前 ProtocolManager 管理 MQTT 和 Modbus，源码没有通用 ProtocolHandler 插件接口。增加协议时须检查真实接口、网络传输与资源生命周期，避免根据旧文档的伪代码创建并不存在的继承关系。

API 在 src/network/handlers/ 中实现，复用认证、JSON响应、参数桥接和资源门控。新增或修改路由时同步 Web 调用、scripts/device-api-test-matrix.json、契约测试及API参考。

设备写入接口通常还要求开发者模式；当前出厂默认关闭。诊断与设备测试前核对身份和用户授权，不自动操作任何已连接设备。

构建与本地验证

同一工作区构建、Native/Host测试、Web资源生成须串行获取 scripts/firmware-build-lock.ps1 中的同一把锁。Native、固件测试及部署入口已接入锁；Host阶段仍需在外层包同一构建锁。下面命令不烧录：

powershell

# 主机门禁和 Native 回归
npm run test:regression

# 指定环境固件和 LittleFS 构建
npm run test:firmware -- esp32s3-F16R8

# 仅构建，保留可审核产物
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy.ps1 -Env esp32s3-F16R8 -BuildOnly

# 浏览器收集及离线交互
npm run test:e2e:collect
npm run test:e2e:offline

直接运行 npm test 或 Web 构建须按仓库AGENTS说明在外层包构建锁。完整本地发布矩阵见测试指南，通过构建不代表已部署、设备通过或长期稳定。

修改与交付

遵循 .editorconfig、.clang-format 及邻近代码风格，不格式化无关文件。界面改动同时核对窄屏、加载/失败提示及离页后的异步回调。

逻辑变更新增能复现原问题的行为测试，并按 scripts/validate-test-coverage.js 登记相关脚本。测试位于 test/unit、test/helpers、test/mocks、test/browser、test/e2e；设备测试入口不能作为默认离线回归运行。

交付记录源码与产物摘要、配置、退出码、验证范围和未完成项目。编译、API确认、动作入队及寄存器读回均不能替代实物反馈。公开样例不携带现场凭据；部署前按配置保全核对目标并备份。

相关文档：架构、核心框架、修改规范、资源调优。

开发指南 ​

环境与目录 ​

增加传感器 ​

协议与 API ​

构建与本地验证 ​

修改与交付 ​