安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install xianmubox-dev
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 xianmubox-dev。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Xianmubox 开发工作流将 AI 编码代理引导至此 MicroPython 和 ESP32-S3 项目变更的完整生命周期，从需求和实现，到模拟器检查、设备调试、部署、文档编写和命令行提交。它有助于让变更符合仓库现有模式、框架服务、硬件限制和项目惯例。
此工作流落实了实用的安全措施：实现前确认范围、在模拟器中验证 UI 变更、构建前要求 python tools/test.py 通过、部署前备份设备设置，并在同一批变更中更新文档。对于在此仓库中工作的 Openclaw Skills 用户，它将项目专属规则转化为可执行的阶段关卡，而非可有可无的建议。

应用场景

确认交互方式、数据来源、字体、硬件要求和持久化需求后，添加新模式或功能。
修改现有屏幕、按钮交互、数据来源或布局，同时检查模拟器行为和回归测试。
通过诊断串口输出和硬件测试调查错误或真实设备故障，再更改代码。
在保护现有
settings.json
配置的同时，构建固件并推送到 ESP32-S3 设备。
使用书面且经过审核的实现计划更改硬件、GPIO 分配、设置结构或架构。
完成变更时同步文档、通过命令行执行 Git 提交，并清楚报告模拟器、测试和设备验证结果。

工作原理

全程遵守阶段 0 规则：烧录前模拟 UI 变更，运行规定的质量检查，在同一批变更中更新相关文档，并且只通过命令行提交。
选择起始阶段：新功能和模式从阶段 1 开始；设备问题和错误修复从阶段 4 开始；要求向设备推送代码时从阶段 5 开始。阶段 6 的最终收尾始终是必需步骤。
明确需求：在与用户确认范围前，检查现有配置档、框架服务、API、字体映射、硬件引脚文档和设置行为。
根据变更规模规划：小型变更可在修复方案明确后直接进行；常规功能需要经批准的计划；重大硬件、架构或设置变更需要书面提案。
实现并注册变更：遵循编码规则，实现模式或服务，更新所需注册点和构建允许列表，并运行模拟器检查和回归脚本。
通过测试关卡：运行 python tools/test.py；若出现意外失败，不要继续构建。文档中所述的缺少 secrets.py 失败属于预期例外。
按需诊断或部署：对于设备问题，使用诊断脚本和串口日志查找根本原因。部署前备份设备设置，构建选定配置档，推送构建产物，并验证设置已恢复。
完成收尾：适用时执行设备回归检查，同步所需文档，通过命令行创建提交，并报告变更和验证状态。

配置指南

在 Xianmubox 仓库中使用此 skill。在执行相应工作前，查看项目说明和相关参考资料：实现前查看 references/coding-rules.md，设备诊断时查看 references/device-debug.md，部署前查看 references/toolchain.md。以下命令是仓库工作流；请使用与设备匹配的端口和配置档。

运行项目质量关卡

python tools/test.py

启动模拟器并列出可用模式

python tools/simulator/run.py --list
python tools/simulator/run.py --mode --zoom 3

部署前备份设备设置

python -m mpremote cp :settings.json ./settings.backup.json

构建配置档并快速推送到 ESP32-S3 设备

python tools/build.py --profile full --device esp32s3_n8r8
python tools/fast_push.py COM5 build/esp32s3_n8r8_full /

使用 UTF-8 消息文件通过命令行提交变更

git add -A
git commit -F
将 COM5 替换为设备的串口。备份 settings.json 前不要部署；部署可能覆盖设备配置。推送后，确认设置已恢复，并在设备上运行目标模式。
Xianmubox 开发工作流 数据架构与分类体系
此 skill 描述的是仓库工作流和现有项目数据惯例；它不定义由 skill 自身管理的独立数据库或生成的元数据格式。
位置或产物 用途
src/modes/.py 模式实现；遵循 BaseMode 契约并提供 enter() 和 loop()。
src/app_config.py 和 src/modes/registry.py 面向模拟器的菜单和模式注册点。
profiles/
.json 部署构建使用的功能声明；生成的构建配置由配置档功能派生。
tools/build.py FRAMEWORK_FILES 允许列表，用于列出运行时所需的框架模块。
settings.json 用于配置的设备持久化数据；更新须通过框架设置服务和验证流程。临时状态不会持久化。
designs/*.json 由模拟器渲染的 UI 设计规范；对于重大 UI 工作，已保存的规范是实现对齐的参考依据。
tools/sim.py 和 tools/shots/ 模式回归脚本和模拟器截图；脚本会报告通过/失败结果和退出码。
doc/ 和 README 功能、硬件、固件历史、项目结构及其他文档；相关变更必须同步更新。
settings.backup.json 部署前创建的本地备份；之后必须恢复设备设置或确认其状态。

高级特性

将工作划分为六个设有质量关卡的阶段，并为功能开发、错误诊断和设备推送提供针对性的入口，同时保留强制收尾步骤。
使用模拟器渲染的 UI 规范和自动回归脚本，其中包含截图、断言以及通过/失败退出码。
编入项目专属架构检查，包括在配置、注册表和配置档文件中注册模式，以及框架构建允许列表检查。
提供硬件诊断工作流，使用
mpremote
、自检脚本、SD 诊断、MP3 诊断和原始 REPL 命令。
支持快速批量部署和较慢的备用部署，也支持在源文件和构建产物保持一致时进行单文件热修复。
通过强制备份设置保护设备状态，并记录固件烧录、分区更改和恢复的其他安全措施。
要求代码随附文档，并强制仅通过命令行执行 Git 提交，以避免已知的文件名编码损坏问题。
对于 Openclaw Skills 用户，将仓库专属检查和操作防护措施整合为可重复的 AI 辅助固件开发工作流。

name: xianmubox-dev description: 闲沐盒子（本仓库）全流程开发工作流——需求梳理、方案制定、实施开发、设备调试、上传部署。凡在本项目提出新功能、新模式、界面改版、修 bug、真机排查、推送设备、构建部署等开发请求时使用，即使用户没有明说"走流程"；本 skill 规定各阶段的门禁与命令，跳过阶段会违反项目强制约定（UI 先仿真、test.py 全绿、文档同批同步、禁 GUI 提交）。

闲沐盒子全流程开发

一个开发请求按六个阶段推进。先按用户请求定位入口阶段： 新功能/新模式从 Stage 1 进入；真机异常、修 bug 从 Stage 4 进入；「把代码推到设备」从 Stage 5 进入。 无论从哪个阶段进入，Stage 0 的门禁贯穿全程，收尾（Stage 6）不可省略。

阶段 做什么 门禁（不过不许往下走） 1 需求梳理 问清交互 / 数据源 / 字库 / 硬件 scope 未与用户确认，不动手 2 方案制定 出方案并获批 非小改动方案未批准，不写码 3 实施开发 写码 + 注册 + 仿真回归 tools/test.py 不全绿，不构建 4 设备调试 串口诊断、定位根因 未定位根因，不盲改代码 5 上传设备 备份 → 构建 → 快推 未备份 settings.json，不部署 6 收尾 文档同步 + 命令行提交 文档未同步 = 任务未完成 Stage 0 · 贯穿全程的门禁

这四条是项目强制约定（AGENTS.md），任何阶段都适用：

UI 一律先仿真后烧录：任何界面改动先过 tools/simulator/（GUI 人工确认或无头截图自检），确认后才上真机。仿真不行就是不行，不存在"真机上看看再说"。

python tools/test.py 必须全绿：提交与构建前的静态质量门。已知例外：secrets.py 缺失导致的 1 项 FAIL 属预期，不算红；其余任何红都不许继续。

文档同批同步：功能 / 接口 / 结构改动必须在同一批提交里更新对应文档（对照 AGENTS.md 的同步表），事后补 = 未完成。
提交只走命令行：git add -A + git commit -F 。禁用 GUI「版本提交」——本仓库 31 个中文名文件会被客户端 UTF-8 分块解码缺陷损坏（与 core.quotepath 无关，勿往该方向排查）。
Stage 1 · 需求梳理

目标：把一句话需求变成可实施的明确 scope。先查现状再提问——很多需求已有现成模式或 framework 服务，避免重复造轮子。

动笔前先自查（读代码 / 文档，不用问用户）：

现有 13 个模式（profiles/full.json features）是否已有近似功能？能否扩展而非新建？
src/framework/ 已有 18 个服务模块能否复用：colors / hal / wifi / settings / http_server(+http_server_state) / http_nb / alarm / cloud / news / audio（play_wav/play_mp3）/ radio / story / weather / sdcard / provision / qrcode / moon。
数据源是否可达：外部 API 现在通不通、返回字段结构、设备端 5s 超时约束。

必须与用户确认的四件事：

交互与按键：内容浏览页 A 短按翻页 / B 主操作 / C 退出；菜单列表页 A 上移 / B 确认 / C 下移。禁止新增长按（全项目唯一例外：swipe 非运行态 A 长按切 BLE 设备）。与规范不符的交互要求要当场指出。
文案用字：240×240 屏用嵌入字库，缺字渲染为空白且真机仿真同款。界面文案确定前查字库 MAP（src/font/），缺字要么换词要么先补字模。状态类小字用 vga 字库同理。
硬件边界：涉及引脚 / 接线时对照 doc/完整接线总表.md（引脚总表见 doc/esp32s3zero引脚说明.md）。本板仅引出 GPIO 1-18 / 38-45，空闲池 = 2（唯一空闲 ADC1 脚）/ 14/15/16（I2S 迁移后释放）/ 41/42；43/44 留作串口调试；板载 WS2812 = GP21。
配置与持久化：需要记住的配置进 settings.json（唯一持久化，经 framework/settings.update() 读写并受校验），临时状态不落盘。

产出：一句话 scope + 预期改动文件清单（草案即可）。

Stage 2 · 方案制定

按改动量分级，不要什么都直通实施：

小改动（改文案、调布局参数、修明显 bug）：说清改法直接进 Stage 3。
常规功能（新页面 / 改交互 / 换数据源）：先给方案——MODE_ID 命名、页面结构、按键表、数据契约、涉及文件清单——用户认可后再写码（用计划模式或对话确认均可）。
重大变更（新硬件 / 改架构 / 改 settings 结构 / 换引脚）：必须先出书面方案：
硬件类：仿照 doc/I2S引脚调整实施方案.md / doc/SD卡模块实施方案.md 写《实施方案》文档（引脚选择依据、接线表、实施/验证状态）。
UI 类：走设计稿流程——设计转 spec JSON 放 designs/，python tools/simulator/run.py --spec designs/xxx.json 渲染，对话内迭代到满意，spec 存档为实现唯一对齐依据。

方案要落定的要素：MODE_ID（= 文件名 = 类名去 Mode 后缀的对应关系）、新增还是复用 framework 服务、数据字段契约、注册点与白名单（见 coding-rules.md）、文档同步清单。

Stage 3 · 实施开发

标准序列（细节与代码契约见 references/coding-rules.md，动手前必读）：

写 src/modes/.py：继承 modes/base.BaseMode，实现 enter() / loop()，文件以中文 docstring 开头。
三处同步注册（缺一处仿真或部署就会对不上）：
src/app_config.py MENU_ITEMS 加一行（仿真器读这里）
src/modes/registry.py _MODULE_MAP 加一行（仿真器读这里）
profiles/
.json features 加一条（部署构建权威；build 产物里的 registry/app_config 由它自动生成）
新增 framework/.py 被运行时用到，须在 tools/build.py 的 FRAMEWORK_FILES 白名单登记，否则部署后 ImportError。
仿真确认：
人工点按：python tools/simulator/run.py --mode --zoom 3（键盘：← 或 a=A，回车/b/空格=B，→/c/Esc=C；--list 看已注册模式）
回归断言：照 tools/_sim_sn.py 模板写 tools/sim.py（stub 环境 + 按键脚本驱动 loop + 截图到 tools/shots/ + PASS/FAIL 计数退出码），运行 python tools/sim.py。
改了已有模式 UI 的，把对应的既有 sim*.py 也跑一遍防回归。
质量门：python tools/test.py 全绿（secrets 1 项预期 FAIL 除外）。不绿不进 Stage 5。

编码红线速记（全文见 coding-rules.md）：禁 f-string；时间用 time.ticks_ms()/ticks_diff()；模式退出 gc.collect() 并卸载自有大模块；颜色只从 framework.colors import；模式之间禁止互相 import。

Stage 4 · 设备调试

从症状到根因，先诊断后改码。连接方式、诊断脚本清单、全部已知坑见 references/device-debug.md，常用入口：

# 硬件/专项诊断（只依赖 machine+json，框架坏了也能跑）
python -m mpremote run tests/hw_selftest.py # 全外设自检 T0-T6
python -m mpremote run tests/sd_diag.py # SD 逐层定位 S0-S3
python -m mpremote run tests/mp3_diag.py # 音频解码链路

# 不打断摆件主程序的 REPL（raw REPL 提交，不软复位）

MPPORT=COM5 python D:/Mycode/MicroPython/esp32-build/repl_util.py exec ""
MPPORT=COM5 python D:/Mycode/MicroPython/esp32-build/repl_util.py run tests/xxx.py 30

调试纪律：一次只改一个变量；网络类异常先区分「接口抖动」与「代码 bug」（设备端 HTTP 5s 超时，重试能恢复的多为抖动）；模式崩溃不会拖垮整机（registry.dispatch 捕获，屏显 MODE ERROR + REPL 打 [DISPATCH] ... crashed），所以黑屏不等于死机，先看串口日志。

Stage 5 · 上传设备

标准部署序列（工具细节与快慢路径对比见 references/toolchain.md）：

# 1. 备份设备配置（部署会用仓库脱敏骨架覆盖设备 settings.json，闹钟/WiFi/云激活会丢！）
python -m mpremote cp :settings.json ./settings.backup.json

# 2. 构建（产物在 build/esp32s3_n8r8_full/，须 BUILD SUCCESS）
python tools/build.py --profile full --device esp32s3_n8r8

# 3. 快推（单连接秒级批量，完成自动软复位进应用）
python tools/fast_push.py COM5 build/esp32s3_n8r8_full /

# 4. 部署后确认 settings.json 已从备份恢复（settings.device-backup.json 为恢复源惯例）

备选路径：

慢路径 python tools/deploy.py --profile full --port COM5：mpremote 每文件一次连接、设备反复重启、易被开机动画抢窗口，仅 fast_push 不可用时用。
单文件热修：python -m mpremote cp src/modes/.py :modes/.py + mpremote reset。只修一个文件时用，注意 src 与 build 产物要保持同源。

涉及固件本身（烧 .bin / 换分区）：先在 doc/固件版本履历.md 登记版本（双归档 MD5 一致）再烧录，烧后回填真机验证状态；erase_flash 或分区表变更会清文件系统，烧完必须重新部署应用并恢复 settings。

部署后必做真机回归：进退出目标模式 5 次确认无内存泄漏与状态残留，核心功能走一遍。

Stage 6 · 收尾（DoD）
文档同步（对照 AGENTS.md 表，未同步 = 任务未完成）：
新增模式：复制 doc/模式功能文档模板.md 建 doc/模式功能文档.md（按键表逐项对照源码核实）→ 登记 doc/功能文档总览.md 索引 → README 功能模块表与目录树 → doc/项目目录结构说明.md。
改既有模式：同步该模式功能文档对应章节；framework / settings / HTTP / 约定类改动按 AGENTS.md 表逐项对号。
提交：git add -A + git commit -F （命令行，禁 GUI）。提交信息用 类型(范围): 描述 格式（feat/fix/docs/chore，参照既有历史）。
向用户报告：改了什么、仿真与测试结果、真机验证还差哪些步骤。
参考文件（按需读）
references/coding-rules.md —— Stage 3 动手前必读：BaseMode 契约、三处注册细则、编码硬约束、按键规范全文。
references/toolchain.md —— Stage 5 部署前必读：build / test / 仿真 / fast_push / deploy / esptool 全参数与坑。
references/device-debug.md —— Stage 4 必读：串口连接选型、诊断脚本清单、mpremote 补丁等已知坑全文。

XianMu Comics

AI Opportunity Navigator