这篇文章把 AI Passport 官方的“从想法到玩法”路径整理成一套可执行流程：先保留出厂玩法并确认设备能正常连接，再定义一个足够小的需求，让 AI Agent 在完整项目中完成开发和构建，最后用官方 Web Flasher 安装到测试设备上。

自定义玩法不等于官方兼容性验证。真正安装前，请保留可以恢复的官方玩法，并把构建通过、设备安装成功和真实使用通过分别记录。

AI Passport 与 AI Agent 共同完成玩法开发、构建和安装的流程

先认识 AI Passport：从出厂身份卡开始

AI Passport 的官方定位不是只能运行一个固定程序的电子摆件，而是一台可以佩戴、体验玩法并继续创造内容的开放式设备。官网给出的三条使用路径可以概括为：

  • Wear：出厂即有身份卡玩法，可以同步名称、头像、简介和全屏图片；
  • Play：从官方玩法社区选择小游戏、随身工具和互动体验，并通过浏览器安装；
  • Create：使用 Codex、Claude Code、TRAE 或其他 AI 编程工具，创造自己的玩法。

第一次拿到设备时，不建议马上刷入自定义固件。先按官方首次使用指南 完成开机、按键和充电检查：

  • 左侧是电源键，按住约 0.5 秒开机，长按约 2 秒关机；
  • 右侧是上、下、确定三个功能键；
  • 一段时间无操作后屏幕会休眠，按任意功能键唤醒；
  • 手机打开蓝牙后，可以通过官方微信小程序或 App 连接设备；
  • 名称、头像、简介和全屏图片通过本地蓝牙同步；
  • 充电时以绿色指示灯判断状态，屏幕界面不显示充电进度。

出厂身份卡里还内置了一款小游戏。先用它确认屏幕、按键和设备状态正常，再进入玩法安装或开发阶段，排查问题会简单很多。

自定义玩法前，先用官方玩法验证连接

AI Passport 的官方玩法社区位于玩法库 。在做自己的项目之前，建议先安装一款已经发布的玩法。这一步的目的不是体验更多内容，而是建立一个可靠基线：

  1. 使用支持数据传输的 USB 数据线连接设备；
  2. 打开最新版本的 Chrome 或 Edge；
  3. 从玩法库进入一个玩法详情页；
  4. 点击“在线安装玩法”；
  5. 在浏览器弹窗中选择对应串口并授权；
  6. 等待写入和校验完成，再重启设备确认玩法能运行。

如果官方玩法都无法安装，先检查数据线、USB 端口、浏览器权限和设备状态，不要直接修改应用代码或怀疑 Agent。官方指南明确说明，网页只能访问用户主动授权的串口。

安装玩法会覆盖设备当前的全部内容。刷写前确认当前身份卡或其他玩法已经不再需要；如果设备里有重要配置，先记录或备份恢复方案。

把“做个小游戏”改成一份可验收的需求

AI Agent 最容易处理的不是一句“做得有趣一点”，而是一个有边界、有输入、有结果的硬件任务。官方的 AI Agent 指南建议从一个真实场景开始，并明确场景、目标和第一版范围。

可以先写这样一份需求单：

项目：AI Passport 离线习惯打卡器

场景：用户每天拿起设备，快速记录一次习惯完成。
第一版目标：只实现计数、查看和清零，不加入联网、录音或复杂动画。
启动页面：显示今日次数和当前操作提示。
按键：
- 上键短按：次数加 1；
- 下键短按：次数减 1，最低为 0；
- 确定键：进入清零确认或返回主页面。
反馈：每次计数变化都要有清晰的屏幕反馈。
存储：计数变化后保存，重启设备可以恢复；没有变化时不要重复写入。
完成标准：构建成功，生成可安装玩法文件，并在测试设备上完成按键、显示和重启恢复验收。

需求中至少要写清楚五件事：谁使用、什么时候使用、屏幕显示什么、三个按键分别做什么、什么结果算完成。第一版只保留一个核心体验，后面再增加声音、蓝牙、网络或统计页面。

把想法收敛成屏幕、三个按键和反馈的最小需求单

让 AI Agent 在完整项目中工作

官方指南提供了一个简单起点：把 FoloToy/ai-passport 项目交给 AI 编程 Agent，并让它在完整项目中理解已有代码、硬件约束和构建方式。可以使用 Codex、Claude Code、TRAE，或任何能够读取项目、修改文件和运行命令的工具。

不要只把一段孤立代码粘贴给 Agent。更稳妥的提示词是先要求它检查项目，再开始实现：

请在 FoloToy AI Passport 官方项目中开发一个离线习惯打卡玩法。

开始前先读取项目说明、已有示例、BSP、分区表和构建脚本，复述：
1. 当前项目的硬件能力和按键输入方式；
2. 适合本需求的页面和状态机；
3. 需要修改的文件；
4. 构建、测试和输出玩法文件的命令；
5. 可能影响设备身份数据或恢复流程的风险。

实现要求：
- 复用项目已有的板级支持和界面能力，不猜测 GPIO；
- 首版只实现计数、清零确认、屏幕反馈和持久化；
- 不加入网络、录音、蓝牙或无关动画；
- 确保按键回调不阻塞，存储只在数据真正变化时更新；
- 不修改受保护的设备身份分区，不提交任何密钥。

完成后运行项目规定的构建和测试命令，并报告：
- 修改了哪些文件；
- 构建和测试是否通过；
- 实际生成的玩法文件路径和大小；
- 哪些项目仍然需要在真实 AI Passport 上确认。

如果使用仓库中的 ESP-IDF 开发流程，还要让 Agent 遵守项目的版本和验证要求。当前仓库资料以 ESP-IDF 5.5.3 为基线；固件开发应在 feature/* 分支进行，不能直接把新玩法写在 main 上。

板级事实应从仓库 BSP 和硬件指南读取，而不是套用普通 ESP32-C3 开发板经验。当前资料确认的关键边界包括：ESP32-C3、8 MB Flash、无 PSRAM、240 × 320 竖屏、上/下/确定按键，以及 USB Serial/JTAG 连接方式。UART、背光、按键 ADC 和受保护分区之间存在板级约束，Agent 必须先读项目文件再决定实现方式。

构建：确认真的生成了可安装文件

官方 AI Agent 指南把“源代码生成”与“构建成功”分开。Agent 报告“代码写好了”并不代表浏览器已经有可安装文件。交付前至少确认：

  • 构建命令以 0 状态码结束；
  • 测试结果没有被错误日志掩盖；
  • 生成文件确实存在，大小合理；
  • 文件来自这次构建，不是旧目录中的残留；
  • 版本号、源码状态和玩法文件能够对应起来。

如果直接使用官方仓库的验证入口，优先运行：

./tools/validate.sh --static
./tools/validate.sh --firmware

固件验证脚本会检查构建和 Flash 布局，并生成：

build/FoloToy-AI-Passport-full.bin

这个文件可作为后续安装流程的输入，但仍需结合项目当前说明确认 Web Flasher 接受的文件格式。构建通过只能说明自动化检查通过，不能代替设备上的屏幕、按键、声音和重启恢复测试。

AI Agent 从源码、构建命令到可安装固件文件的开发流水线

使用 Web Flasher 安装自定义玩法

官方的玩法安装工具 适合把本地构建出的玩法文件写入 AI Passport。官方“更换官方小游戏”指南和“用 AI Agent 创造专属玩法”指南给出的流程可以合并为以下步骤。

1. 准备浏览器和设备

使用最新版本的 Chrome 或 Edge 打开 Web Flasher。准备一根支持数据传输的 USB 线，连接 AI Passport，并让设备保持可用状态。

2. 选择本地文件

在刷机工具中选择 Agent 实际生成的玩法文件。不要直接选择项目源码、旧版本文件或不确定来源的二进制文件。官方说明中，自定义玩法文件完全由当前浏览器读取，不上传到服务器。

3. 授权串口

点击连接后，在浏览器弹窗中选择对应串口。网页只能访问主动授权的端口；如果没有看到设备，依次检查 USB 线、端口、设备是否开机，以及浏览器是否支持 Web Serial。

4. 核对后开始安装

安装前核对玩法名称、版本和文件来源。确认无误后开始写入。安装过程中：

  • 不要拔掉 USB 线；
  • 不要关闭 Web Flasher 页面；
  • 不要让设备进入不稳定的供电状态；
  • 第一次安装优先使用测试设备；
  • 保留可以恢复的官方玩法。

写入完成后等待校验，再重启设备。不要在进度条尚未结束时根据屏幕暂时无变化判断失败。

Web Flasher 页面有“清除设备数据”之类的高风险选项时，只在明确需要时启用。清除数据会删除当前配置和用户数据，普通玩法安装不应随意勾选。

笔记本通过 USB 连接 AI Passport，在浏览器中授权串口并完成安装校验

真机验收：按预期逐项记录

刷写成功后，不要只看设备能否亮屏。按需求单逐项记录预期和实际结果。

启动与显示

  • 是否能稳定进入主页面；
  • 文字和数字是否在竖屏范围内完整显示；
  • 页面切换后是否有残留控件；
  • 是否出现持续重启、卡死、assert 或 watchdog。

按键与状态

  • 上键每次短按是否只增加一次；
  • 下键在 0 时是否保持为 0；
  • 确定键在每个页面是否都有明确结果；
  • 连续快速按键是否会重复触发或跳过确认；
  • 休眠唤醒后按键和页面状态是否仍然正常。

存储与恢复

  • 改变计数后重启，数据是否按设计恢复；
  • 没有变化时是否避免重复写入；
  • 清零后重启，结果是否仍为 0；
  • 重新安装其他玩法前，是否已经记录当前版本和恢复方式。

真实场景

离开电脑再使用一次，检查单手操作是否顺畅、文字是否清楚、反馈是否及时、电量是否满足场景。官方指南建议把最影响核心流程的问题优先交给 Agent 修复，每轮只改变少量可验证内容。

建议保留这样的版本记录：

v0.1：完成屏幕和三键交互
v0.2：加入持久化，验证重启恢复
v0.3：加入清零确认，验证边界状态
v0.4：再评估音效、联网或其他外设

出问题时，先判断属于哪一层

现象优先检查不要先做的事
浏览器看不到设备USB 数据线、端口、设备状态、串口权限不要先改按键 GPIO
串口权限被拒绝浏览器授权、系统设备权限和当前端口不要反复更换固件
安装中断数据线、供电、页面是否被关闭不要在未确认状态时重复写入
构建找不到 idf.pyESP-IDF 环境是否为 5.5.3不要用另一版本工具链硬顶
编译通过但按键异常BSP 按键实现、状态机和真机复现不要同时改字体、动画和按键阈值
安装后无法进入玩法文件来源、版本、日志和恢复固件不要立即清除设备数据

如果需要通过命令行观察设备，先使用项目文档规定的实际端口；不要把某个机器上的 /dev/ttyACM0 当作所有设备都固定相同。已有设备身份的刷写还要保护 cardid 分区，不能为了合并镜像方便而覆盖它。

完成标准：三种“成功”要分开

一个完整的自定义玩法交付，至少要有三条独立结论：

Build：构建和自动检查是否通过
Install：Web Flasher 是否完成写入和校验
Device：真实设备上的显示、按键、存储和场景验收是否通过

只有 Build 通过，不能写成“玩法已经完成”；只有 Install 成功，也不能推断按键和数据恢复没有问题。每个可用版本都应保存源码状态、玩法文件、安装时间和验收记录。

官方入口

本文根据上述官方页面及官方仓库资料整理，核对时间为 2026-09-12。设备固件、玩法文件格式、浏览器行为和网站页面可能更新；遇到差异时，以设备当前页面和官方文档为准。