ai-passport-agent

面向 FoloToy AI Passport（ESP32-C3 + ESP-IDF 5.5.x + LVGL）固件的引导式、任务化开发 Agent —— 一个可独立安装、可发布的 DeepSeek Harness agent preset。

让任何一个开发者拿到官方 fork 仓库，就能让 AI 一步步、可编译、可验证地把这块工牌改造成他想要的产品——而无需手动描述硬件细节或反复强调流程纪律。

它能做什么

固定硬件已内置：MCU / 屏幕 / 按键 / 音频 / 电池 / 总线等板级事实对这块板是固定的，agent 直接当作权威，不重复推导、不猜。
产品功能由引导得出：页面数、功能、交互、配色等软规格不预设，agent 用提问引导你描述开发目标，再落地成计划。
任务化渐进实现：确认计划后，严格按 READ → PLAN → MODIFY → BUILD → UI → FUNCTION → HARDWARE → DOCUMENT → COMMIT → STOP 一步步推进，每步保证能编译。
诚实报告：绝不虚构 PASS——未连接板子 = Hardware: NOT TESTED，只编译通过 = Build: PASS，UI 仅代码审查 = UI: STATIC REVIEW PASS。

工作原理（一次会话）

Step 0  探测 docs/ 下有无实施计划文档
        ├─ 有 → 「进行中项目」模式：严格按计划执行
        └─ 无 → 「新项目」模式：引导 + 脚手架

新项目引导（问的是产品，不是硬件）：

只读探索仓库，确认硬件与起始状态
ask_user_question 引导：产品愿景 → 功能清单与 MVP → 交互设计 → 软件栈 → 约束 → 交付
脚手架化三份文档：docs/<PLAN>.md、docs/UI_DESIGN_SPEC.md、docs/HARDWARE_REFERENCE.md
请用户明确确认计划后才开始 TASK-00（对话里一句"好"不算确认）

目录结构

ai-passport-agent/
├── preset/                          ← 可安装的 preset 本体
│   ├── agent.cordis.yml             ← AGENT-PLANE 组合（persona + 全部工具/领域行）
│   ├── preset.yml                   ← 展示名与描述
│   └── skills/
│       └── ai-passport-firmware/    ← 随包携带的专属 skill（引导 + 实施规范）
│           └── SKILL.md
├── docs/
│   └── agent-preview.md             ← 面向使用者的能力预览/开场话术
├── install.ps1                      ← Windows 一键安装
├── install.sh                       ← macOS/Linux 一键安装
├── CHANGELOG.md
├── LICENSE
└── README.md

前置要求

已安装 DeepSeek Harness（dsh），并具备编辑/装载 preset 的权限。
目标仓库为 FoloToy AI Passport（ESP32-C3）源码树——官方 fork 或用户仓库均可；{{cwd}} 即该仓库。
本机装有 ESP-IDF 5.5.x 工具链（构建本固件用），路径在 persona 中配置。
官方固件模板：https://github.com/FoloToy/ai-passport

安装

预设安装目录按部署配置而定（默认 ~/.dsh/.agent-presets/）。建议用自带脚本：

Windows（PowerShell）

.\install.ps1

macOS / Linux

chmod +x install.sh && ./install.sh

或手动拷贝：

cp -r preset "$HOME/.dsh/.agent-presets/ai-passport"

安装后重启 Host 或在 DSH 中刷新 preset 列表，选择该 preset 即可。

配置：ESP-IDF 工具链

persona 的「Build & flash」段通过一个变量控制工具链，装载前按你的机器改一次。打开已安装的 agent.cordis.yml（例如 ~/.dsh/.agent-presets/ai-passport/agent.cordis.yml），找到 persona 的 text 中：

$IDFHome = "D:\software\Espressif"   # ← 改成你的 ESP-IDF 工具根目录
$IDFVersion = "5.5.5"                # ← 按需改成你的版本

$IDFHome 是包含 frameworks/、python_env/、tools/ 的根目录；其余路径全部由此推导。

使用

在 DSH 中新建会话，选择本 preset。
把工作目录设置为固件仓库根（仓库根即 {{cwd}}）。
确认工具列表齐全（shell、文件、检索、jobs、skills、goals、plan mode、delegation、web 等）。
描述你的开发目标，agent 会先引导、给计划、你确认后再实现。

首次使用前，请确认已装载的 agent.cordis.yml 中 $IDFHome 指向本机真实路径。

固定硬件

以下板级事实对 FoloToy AI Passport 固定不变，agent 视为权威：

项	规格
MCU	ESP32-C3，8MB Flash，无 PSRAM
屏幕	ST7789P3 240×320 RGB565，SPI2 @40MHz，无触摸
按键	三按键，GPIO0 ADC 分压阶梯（`BSP_BTN_MV_TABLE`）
音频	ES8311，I2S0 全双工
电池	CW2017 共享 I2C0（0x63），可选
注意	GPIO18/19 保留；UART0 TX（GPIO21）与背光冲突

引脚/I2C/屏幕/按键窗口的单一权威是 components/bsp/include/bsp_pins.h。

常见问题（FAQ）

Q：拿到的官方 fork 里没有 docs/ 计划文档怎么办？ A：正常。agent 会走「新项目引导」——它只读探索确认硬件，再用提问帮你确定开发目标，脚手架化计划文档，你确认后才开始实现。

Q：我不想让它大改硬件驱动/屏幕初始化怎么办？ A：在引导的「约束」环节明确告诉它哪些不许动即可；persona 也会默认保留已验证的初始化/时钟序列。

Q：换了一台电脑要改什么？ A：只改 agent.cordis.yml 里 persona 的 $IDFHome 和 $IDFVersion 两个变量。

Q：它会不会一次重写整个固件？ A：不会。persona 和 skill 都硬性禁止「一次重写整个项目」与「一次改多个主要模块」，且每一步必须能编译。

开发与发布

板级硬件写死（对该板固定）；产品规格完全引导（不预设）。
修改组合后请用 DSH 的 preset 装载校验（standingKeyFor）验证可用，再做发布。
发布到公共仓库前，检查 persona 中是否残留本机路径、密钥或隐私信息。

变更记录

见 CHANGELOG.md。

License

MIT

AI Passport Firmware Agent

项目 README（英文原文）