【免费下载链接】ai-passportFOLOTOY AI Passport develop resources for Agent项目地址https://gitcode.com/gh_mirrors/ai/ai-passport点击查看免费下载AI Passport 是一款基于ESP32-C3 8 MB Flash 无 PSRAM的开放式可穿戴 AI 开发板。它的构建与测试体系全部收敛在一个入口脚本 tools/validate.sh 里静态门禁负责仓库卫生检查与主机逻辑测试固件门禁负责在隔离环境中完成 ESP32-C3 构建、merge-bin合并镜像与逐字节校验。本文完整拆解这套本地与 CI 共用的质量门禁帮你在不烧录、不连板的情况下也能验证大部分固件逻辑。为什么 AI Passport 需要三道质量门禁AI Passport 的硬件预算非常紧张8 MB Flash 装下 Bootloader、分区表和整个应用且没有 PSRAM 兜底见 docs/hardware-design/specifications.zh_CN.md。这决定了能编译通过不等于能正常启动、正常休眠、正常烧录。为此项目把验证分成三层层级检查内容工具① 静态门禁仓库卫生 主机逻辑测试validate.sh --static② 固件门禁ESP32-C3 构建 合并镜像校验validate.sh --firmware③ 完整门禁① ② 全部通过validate.sh --all默认三层检查在本地与 CI 中共用同一套命令不存在CI 一套、本地另一套的双轨制这也是项目文档明确要求的约定见 docs/development/ci/CI-validation.zh_CN.md。第一道门禁validate.sh 静态检查全解析--static模式tools/validate.sh#L11-L75按顺序执行三类检查仓库卫生检查check_repo.py 扫描全部文件tools/check_repo.py 是一个零依赖的 Python 脚本它会扫描 Git 跟踪的所有文件检查双语 Markdown 配对每篇文档必须有英文默认版.md与.zh_CN.md中文版且互相链接相对链接有效性文档中的本地链接必须指向真实存在的文件GitHub Actions 固定完整 SHA工作流中的 Action 必须用 40 位完整 commit SHA 锁定版本依赖锁文件、合并冲突标记、疑似敏感信息如 token、私钥、AWS key一律拦截。这一步把文档写错链接、误提交密钥这类低级错误挡在合并之前。Workflow 语法检查actionlint 自动安装若系统没有actionlint脚本会通过 tools/install-actionlint.sh 自动安装再对.github/workflows/*.yml做语法校验避免工作流文件本身写错。主机逻辑测试不烧板也能验证的 C 单元测试这是整个体系最巧妙的部分。AI Passport 要求可测试的状态机、协议、时序和布局计算与 ESP-IDF/LVGL 解耦见 AGENTS.md于是这些纯逻辑模块可以直接用系统自带 C 编译器在主机上编译运行主机测试验证目标tests/test_ui_pixel_math.c像素布局/换算数学对应 main/ui_pixel_math.ctests/test_demo_navigation.c演示菜单的页面状态机tests/test_key_guard.c按键唤醒防护逻辑tests/test_bsp_display_rounding.c显示刷新取整策略tests/test_bsp_es8311_sleep_check.cES8311 音频芯片休眠寄存器校验tests/test_bsp_button.c按键事件去抖与识别tests/test_bsp_lvgl_init.cLVGL 显示初始化参数tests/test_bsp_audio_recovery.c音频链路故障恢复test_demo_{audio,low_power,ble,wifi}_runtime.c四大演示的运行时时序与失败路径其中 demo 类测试配合 tests/demo_stubs/ 里的一套轻量桩stub头文件把 FreeRTOS 任务、I2S、Wi-Fi、BLE 等硬件依赖全部替换成可注入失败场景的模拟实现。例如 tests/test_demo_audio_runtime.c 会故意让任务创建失败、录音中途断开断言演示代码在每种故障下都不会死锁或误报完成。所有 C 测试都以-Wall -Wextra -Werror编译警告即失败——代码质量门禁从编译期就开始了。Python 契约测试锁定关键硬件行为主机测试之外还有 6 个 Python 脚本tools/validate.sh#L67-L72其中两个契约测试值得注意tests/test_deep_sleep_contract.py直接解析 components/bsp/src/ 中的源码断言 ES8311 强制休眠的寄存器序列逐条且顺序完全正确芯片必须先静音再关时钟顺序错了设备将无法从深睡唤醒tests/test_key_wake_contract.py断言 main/main.c 中按键回调必须先解除唤醒防护再做就绪检查防止按键事件被错误丢弃。这类静态契约测试的价值在于把实测过的硬件时序钉死在仓库里任何人改动 BSP 源码、破坏了正确时序都会立刻被门禁拦下。第二道门禁固件构建与合并固件校验全新隔离的 ESP-IDF 构建--firmware模式tools/validate.sh#L77-L101的关键设计是隔离要求环境已激活ESP-IDF 5.5.3否则直接报错退出用mktemp -d创建一次性临时构建目录退出时自动清理避免污染本地build/指定SDKCONFIG_DEFAULTS指向 sdkconfig.defaults保证配置来源唯一执行idf.py build后用idf.py merge-bin生成FoloToy-AI-Passport-full.bin合并镜像Bootloader 分区表 应用拼成一个文件。合并镜像之所以重要它就是用户用烧录器一次性写进 8 MB Flash 的最终产物验证它等价于验证了整块 Flash 的内容。verify_firmware.py逐字节校验 8 MB Flash 布局tools/verify_firmware.py 是合并固件校验的核心它把flash_args烧录参数文件当作纯数据解析而不是执行逐项核对校验项失败意味着flash_args必须选择--flash_size 8MB烧录配置与硬件不符Bootloader 必须位于0x0设备无法启动必需镜像齐全bootloader / 分区表 / 应用合并产物不完整各镜像偏移互不重叠、不超出 8 MB 边界烧录后会互相覆盖合并文件中每个镜像逐字节与原文件一致合并过程损坏分区表 MD5 标记正确、分区标签唯一、无重叠分区表非法应用大小不超过 partitions.csv 中factory分区容量升级/烧录溢出应用偏移处存在 ESP 镜像魔数0xE9应用区没有真实固件对照 partitions.csv 可以看到默认布局nvs(0x9000) →phy_init(0xF000) →factory(0x10000约 8 MB 剩余空间全部给应用)。校验器还会把flash_args中的额外自定义镜像如资源分区数据限制在单个分区内部绝不允许跨分区边界——这是对衍生应用自定义分区布局的兼容支持。archive_firmware.py保留可信的构建产物tools/archive_firmware.py 在校验通过后把关键调试产物.elf、.map、应用.bin、合并镜像、Bootloader、分区表、flash_args按显式白名单归档到build/firmware/并生成带 SHA256 的manifest.json。两个安全细节值得学习flash_args只解析、绝不执行杜绝参数注入所有路径经safe_path()审查拒绝目录穿越和任意符号链接归档过程可独立复核固件布局。CI 工作流如何复用同一套门禁CI 侧只有两条工作流且都只读、不用任何 secret因此来自 fork 的 Pull Request 也能被安全验证静态检查.github/workflows/static-checks.yml每个 PR 都运行安装固定版本的 actionlint 后执行./tools/validate.sh --static固件检查.github/workflows/firmware-checks.yml在 ESP-IDF 5.5.3 官方 Docker 环境esp-idf-ci-action中针对esp32c3执行./tools/validate.sh --firmware用 ccache 加速编译产物保留 7 天供下载。两条工作流都有讲究的路径过滤固件检查会忽略docs/**、skills/**和*.md纯文档 PR 不会触发昂贵的固件构建但assets/**刻意不忽略——因为assets/存放字体、图片、音乐等可能被嵌入固件的资源任何变更都必须重建固件。所有 GitHub Action 均锁定到完整 commit SHA升级时需人工核对官方版本再由actionlint兜底检查。更多设计细节见 docs/development/ci/CI-validation.md。本地复现完整验证流程三条命令跑齐全部门禁本地验证流程与 CI 完全一致这也是排查CI 挂了本地却正常这类问题的正确姿势git clone https://gitcode.com/gh_mirrors/ai/ai-passport cd ai-passport # ① 静态门禁仓库检查 全部主机测试无需 ESP-IDF ./tools/validate.sh --static # ② 固件门禁需要 ESP-IDF 5.5.3 环境 source path-to-esp-idf-v5.5.3/export.sh ./tools/validate.sh --firmware # ③ 完整门禁① ② ./tools/validate.sh日常迭代时建议先跑最小的--static快、零依赖交付前再跑完整门禁。若未安装工具链可按 docs/development/engineering/environment-setup.zh_CN.md 搭建环境。总结这套门禁体系对嵌入式开发的启示AI Passport 的构建与测试体系给出了三个可复用的实践单一入口本地与 CI 共用 tools/validate.sh杜绝两套命令漂移逻辑下沉可测把状态机、时序、布局计算与硬件框架解耦用主机 C 测试 Python 契约测试覆盖大部分逻辑缺陷显著减少烧录试错验证最终产物而非中间产物verify_firmware.py直接校验merge-bin输出的合并镜像保证能编译和能烧录启动之间没有盲区。对新手来说只需记住一句话改完代码先跑./tools/validate.sh --static交付前跑完整门禁再谈上板验证。赞分享【免费下载链接】ai-passportFOLOTOY AI Passport develop resources for Agent项目地址https://gitcode.com/gh_mirrors/ai/ai-passport点击查看免费下载相关推荐prediction-market-backtesting 测试体系全解标准门禁、烟雾测试与文档校验如何保障质量prediction market backtesting 测试体系全解标准门禁、烟雾测试与文档校验如何保障质量 prediction market backvue-admin-better单元测试入门组件测试与逻辑测试vue admin better单元测试入门组件测试与逻辑测试 测试环境搭建 vue admin better项目默认未集成单元测试环境需通过以下步骤手动搭前端认证鉴权RustPBX测试体系揭秘E2E测试框架、SIP机器人回归套件与媒体保真度验证RustPBX测试体系揭秘E2E测试框架、SIP机器人回归套件与媒体保真度验证 RustPBX 是一款用 Rust 编写的开源 PBX企业电话交换系统。要上一篇Sapper 静态站点导出指南使用 sapper export 将 Svelte 应用发布为纯静态文件下一篇photoo 低质量图片识别揭秘拉普拉斯算子如何快速揪出模糊废片创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考