3、源码管理规范：目录结构设计、命名规则、版本控制（Git）策略、依赖管理与可复现构建

TinyML 工程与常规嵌入式或纯软件项目最大的差异在于：它同时涉及模型权重、推理框架源码、板级支持包（BSP）、编译工具链、固件链接脚本以及部署脚本。任何一个环节的混乱，都会导致“在我机器上能跑，换台机器就崩”的经典困境。源码管理规范的核心目标，是让项目在人员流动、硬件迭代、框架升级的背景下，依然能够实现可追溯、可复现、可审计的交付。本章将围绕目录结构、命名规则、Git 策略、依赖管理与可复现构建四个维度，建立一套适用于 TinyML 工程的最小可行规范。

上图展示了 TinyML 源码管理的三大支柱：左侧为目录结构的功能分层逻辑，中间为 Git 分支与版本发布流，右侧为依赖锁定与可复现构建的关键动作。三者相互支撑，共同构成工程交付的“铁三角”。下面逐一展开。

3.1 目录结构设计：按功能分层，而非按硬件型号分层

核心原理：TinyML 项目通常需要同时支持多种开发板（如 STM32F746、ESP32-S3、RP2040）和多种推理后端（TensorFlow Lite Micro、CMSIS-NN、Glow）。如果目录按“板子”划分，例如 board_a/src、board_b/src，会导致大量重复代码，且当算法更新时需要在多个目录间同步修改。正确的做法是按功能模块分层，将硬件相关代码隔离在特定子目录中，通过构建系统选择具体实现。

推荐结构：

tiny_ml_app/
├── src/                    # 应用层源码（与硬件无关）
│   ├── app/                # 业务逻辑、状态机、事件循环
│   ├── model/              # 模型加载、推理封装、后处理
│   └── driver/             # 硬件抽象层（HAL）接口定义
├── include/                # 公共头文件
├── tests/                  # 单元测试与集成测试
│   ├── unit/               # 纯软件测试（可在 PC 上运行）
│   └── hardware/           # 需要真实硬件的测试
├── scripts/                # 构建、烧录、打包脚本
├── configs/                # 板级配置（链接脚本、时钟配置、引脚映射）
│   ├── stm32f746/
│   ├── esp32s3/
│   └── rp2040/
├── tools/                  # 模型转换工具、量化工具、签名工具
├── docs/                   # 设计文档、API 文档、部署说明
├── CMakeLists.txt          # 顶层构建文件
├── Makefile                # 便捷入口（封装 CMake 命令）
└── README.md               # 项目简介、快速开始、目录说明

关键原则：

• 硬件隔离：所有直接操作寄存器、外设、DMA 的代码必须放在 src/driver/ 下，并通过统一的 HAL 接口暴露给上层。例如 hal_uart_send()、hal_gpio_write()。
• 模型独立：模型文件（.tflite、.h5）不直接放在源码树中，而是放在 models/ 目录（或 Git LFS 管理），通过构建脚本生成 C 数组或链接到固件中。
• 配置与代码分离：板级引脚映射、时钟频率、内存布局等放在 configs/<board_name>/ 下，构建时通过 -DBOARD=stm32f746 指定。

3.2 命名规则：统一风格，减少认知负担

核心原理：命名规则是团队协作的“语法”。TinyML 项目涉及 C/C++、Python（模型转换脚本）、Shell（构建脚本）、CMake 等多种语言，每种语言应有明确的命名约定，避免混用。

推荐规则：

操作流程：在项目初始化时，将上述规则写入 CONTRIBUTING.md 和 .clang-format（C/C++ 自动格式化）、.editorconfig（跨编辑器统一缩进）。在 CI 中增加命名规范检查（如 clang-tidy 的 readability-identifier-naming 检查）。

3.3 版本控制（Git）策略：从分支模型到提交粒度

核心原理：TinyML 项目的 Git 管理需要同时处理代码演进和模型/配置变更。推荐采用 Git Flow 的简化变体，即：main 分支始终保持可发布状态，develop 分支用于集成测试，功能分支从 develop 拉出，完成后合并回 develop。发布时从 develop 拉出 release/* 分支，测试通过后合并到 main 并打 tag。

关键策略：

• 提交粒度：每次提交只做一件事。例如“添加关键词唤醒模型”和“修复 UART 波特率配置”应分两次提交。避免将格式化改动与逻辑改动混在一起。
• 语义化版本：使用 v主版本.次版本.修订号 格式，例如 v1.2.0。对于硬件相关的修复，可在修订号后加平台后缀，如 v1.2.0-stm32，但主版本号应保持一致。
• 模型版本关联：在提交信息或 model_manifest.json 中记录模型文件的 SHA256 哈希，确保代码与模型版本可对应。
• Tag 与 Release：每个发布 tag 必须包含完整的构建产物（固件、烧录工具、校验和文件），并附上发布说明（变更内容、已知问题、测试结果）。

案例拆解：某智能家居项目团队在开发语音唤醒功能时，遇到“模型更新后，旧固件无法识别新命令”的问题。排查发现，模型文件通过 Git LFS 管理，但团队成员在更新模型时未更新 model_manifest.json 中的哈希值，导致 CI 构建时使用了缓存中的旧模型。复盘后，团队在 CI 脚本中增加了“模型哈希比对”步骤，一旦发现哈希不匹配立即终止构建，并强制要求提交时更新 manifest 文件。此后未再出现类似问题。

3.4 依赖管理与可复现构建：锁定一切可变因素

核心原理：可复现构建意味着“给定相同的源码、工具链和依赖版本，任何时间、任何机器上都能生成字节级一致的固件”。TinyML 项目的依赖不仅包括 C/C++ 库，还包括：

• 编译工具链：如 arm-none-eabi-gcc 的版本、补丁级别。
• 第三方库：如 CMSIS、TensorFlow Lite Micro 的特定 commit。
• Python 环境：模型转换脚本依赖的 TensorFlow、NumPy 版本。
• 模型权重：量化参数、输入归一化系数等。

操作流程：

1. 工具链锁定：在 CMakeLists.txt 中指定编译器路径和版本，或使用 toolchain.cmake 文件。推荐使用 gcc-arm-none-eabi-10.3-2021.10 这类固定版本，避免使用系统默认的 arm-none-eabi-gcc（版本可能随系统更新而变化）。
2. 依赖清单：使用 vcpkg.json 或 CMake FetchContent 锁定第三方库的 Git commit 或 tag。例如：

# CMakeLists.txt 片段
include(FetchContent)
FetchContent_Declare(
  tflite_micro
  GIT_REPOSITORY https://github.com/tensorflow/tflite-micro.git
  GIT_TAG 5e3a2a3  # 锁定到特定 commit
)
FetchContent_MakeAvailable(tflite_micro)

3. Python 环境锁定：使用 requirements.txt 或 Pipfile.lock 锁定 Python 包版本。对于模型转换脚本，建议使用虚拟环境（venv）或 Docker 容器。
4. 构建脚本封装：提供 build.sh 或 Makefile 目标，内部调用 CMake 并传递所有必要的参数（如 -DBOARD=stm32f746 -DCMAKE_BUILD_TYPE=Release）。确保团队成员使用相同的命令构建。
5. CI 缓存策略：在 CI 中使用 ccache 加速编译，但缓存键必须包含工具链版本、编译选项和所有依赖的哈希值，避免缓存污染。

案例拆解：某工业级 TinyML 项目在交付后 6 个月，客户要求重新生成固件以修复一个安全漏洞。团队发现原构建机器已报废，新机器上安装的 arm-none-eabi-gcc 版本从 10.3 升级到了 12.2，导致编译后的固件在 Flash 布局上出现 4 字节偏移，直接覆盖了关键配置区。由于项目当时未锁定工具链版本，团队花费了 3 天时间才定位问题。修复方案是：在 toolchain.cmake 中强制指定工具链路径，并将工具链压缩包上传至内部服务器，同时在 CMakeLists.txt 中增加编译版本检查（if(NOT CMAKE_C_COMPILER_VERSION STREQUAL "10.3.1")）。此后，团队在 CI 中增加了“构建产物哈希比对”步骤，确保每次构建的固件哈希一致。

3.5 常见误区与总结复盘

误区一：将所有文件都纳入 Git 管理。构建产物（build/）、IDE 配置（.idea/、.vscode/）、模型原始权重（*.h5）不应提交。应使用 .gitignore 排除，模型文件通过 Git LFS 或独立存储管理。

误区二：分支策略过于复杂。对于 5 人以下的小团队，完整的 Git Flow 可能过于沉重。可采用 GitHub Flow：main 始终可部署，功能分支直接合并到 main，通过 CI 保证质量。关键是保持简单，并严格执行“小步提交、频繁集成”。

误区三：依赖管理只关注编译时。运行时依赖（如模型输入数据的预处理参数、量化零点和缩放因子）同样需要版本管理。建议在 configs/ 目录下为每个模型版本建立独立的配置文件，并在固件启动时打印配置哈希，便于现场排查。

误区四：认为“可复现构建”等于“CI 能通过”。CI 通过只能说明当前环境可构建，不代表 6 个月后仍可复现。真正的可复现需要：工具链版本锁定、依赖 commit 锁定、模型哈希校验、构建脚本参数固化，以及构建日志的完整归档。

总结复盘：源码管理规范的核心是“确定性”。目录结构决定了代码的组织方式，命名规则降低了沟通成本，Git 策略控制了变更的节奏，依赖管理保证了构建的稳定性。四者缺一不可。建议团队在项目启动的第一周就完成规范制定，并在每次代码评审中检查规范符合性。当遇到“奇怪”的构建问题时，优先怀疑依赖版本漂移，而不是代码逻辑。