xiaozhi-esp32-dev

name	xiaozhi-esp32-dev
description	辅助 xiaozhi-esp32 项目的需求分析、代码阅读、Bug 修复、新功能开发、外设驱动迁移、BSP 分层、中间件抽象、README 更新和 Git 状态检查。在处理任何代码任务时触发。

xiaozhi-esp32 开发 Skill

目标

本 Skill 用于辅助 xiaozhi-esp32 项目的需求分析、代码阅读、Bug 修复、新功能开发、外设驱动迁移、BSP 分层、中间件抽象、README 更新和 Git 状态检查。 在处理任何代码任务时，必须优先保证代码变更可追踪、需求边界清晰、工程结构合理、实现符合 ESP-IDF 项目的组件化开发习惯。

---

确定性 Hooks（脚本强制执行）

以下 Hook 通过 Node.js 脚本实现，可由支持 Hook 机制的 AI 编码助手自动执行，不依赖 AI 判断，100% 强制执行：

触发时机	脚本	行为
写文件前	hooks/git-status-check.js	工作区有未提交修改时阻止操作
写文件后	hooks/post-edit-reminder.js	提醒检查 CMake / Kconfig / README
任务完成时	hooks/stop-check.js	提醒回复须包含变更清单和 commit 建议

脚本协议：

• 通过 stdin 接收事件上下文（JSON 格式）
• exit 0 表示放行，exit 2 表示阻止（stderr 内容注入对话）
• exit 0 时 stdout 输出 JSON 可注入额外上下文
• 跨平台兼容 Windows / macOS / Linux（依赖 Node.js）

安装 Hooks

将 hooks/ 目录下的脚本集成到你的 AI 编码工具中：

通用方式：复制脚本到项目

# 在目标项目根目录执行
mkdir -p .hooks
cp <skill-path>/hooks/git-status-check.js .hooks/
cp <skill-path>/hooks/post-edit-reminder.js .hooks/
cp <skill-path>/hooks/stop-check.js .hooks/

然后根据你使用的 AI 工具配置对应的 Hook 触发规则。

Qoder 集成示例

如果使用 Qoder，将 hooks/settings.json 复制到项目的 .qoder/settings.json 即可自动注册所有 Hook：

# macOS / Linux
mkdir -p .qoder
cp <skill-path>/hooks/settings.json .qoder/settings.json
mkdir -p .qoder/hooks
cp <skill-path>/hooks/*.js .qoder/hooks/

# Windows PowerShell
mkdir .qoder -Force
copy <skill-path>\hooks\settings.json .qoder\settings.json
mkdir .qoder\hooks -Force
copy <skill-path>\hooks\*.js .qoder\hooks\

其他工具：参考对应工具的 Hook/插件配置文档，将上述脚本注册到相应的触发事件即可。

---

行为准则（AI 智能判断）

以下规则依赖 AI 理解和上下文判断，无法通过脚本强制执行，AI 必须自觉遵守：

需求与 Bug 上下文阅读

当用户提出需求或 Bug 修复时，AI 不得只看报错文件或用户点名的单个文件，必须同时查看调用链、配置文件（Kconfig/CMake）、构建系统和相关组件初始化逻辑。形成方案前须说明已阅读的上下文范围。详见 docs/02-code-reading-principles.md。

需求不明确阻断

当需求缺少关键条件（硬件型号、通信接口、GPIO 接线、目标板子、参考例程、复现步骤等）时，AI 必须先阻断实现并向用户提问，禁止幻想实现。硬件类需求至少问清：型号、接口、接线、目标板子、例程/手册、功能边界。详见 docs/04-unclear-requirements.md 和 docs/05-new-feature-requirements.md。

新硬件资料确认

当用户提出新硬件驱动支持时，AI 必须先确认是否存在可迁移资料（官方例程 > Arduino 例程 > ESP-IDF 例程 > 数据手册）。例程和资料都没有时，禁止编写驱动实现。详见 docs/13-driver-migration.md。

Superpowers 协同

任务开始时检查是否有 Superpowers skills 可用，优先结合使用。如果与本 Skill 冲突，优先遵守本 Skill 的嵌入式工程约束。详见 docs/03-superpowers-collaboration.md。

---

文档索引

本 Skill 的规则拆分为以下 22 个文档，按用户所需阅读（推荐全部阅读）：

序号	文档	说明
1	Git 状态检查	阅读或修改代码前必须先检查 Git 工作区状态，避免覆盖用户已有改动
2	代码阅读原则	不能只看局部代码，必须主动了解项目结构、调用链、组件依赖等上下文
3	Superpowers 协同	与 Superpowers Skill 共存时的协同使用和冲突处理原则
4	需求不明确时提问	硬件型号、接口边界、目标板子不明确时必须先提问，禁止幻想实现
5	新功能需求处理	新硬件驱动支持和 Bug 修复两类需求的完整处理流程和索要信息清单
6	README 与更新日志	代码修改后必须维护 README 更新日志，并给出 commit 建议
7	BSP 分层规则	外设驱动和板级硬件适配必须放入 BSP 层，附目录结构和 CMake 示例
8	Middleware 分层规则	能力二次抽象、状态管理、策略封装必须放入 middleware 层，附依赖方向说明
9	代码归类判断	判断新代码应放在 BSP、middleware 还是 main/app 层的具体判断标准
10	ESP-IDF 组件化要求	组件目录结构、函数命名前缀、错误处理和日志规范
11	CMake 依赖规则	REQUIRES 与 PRIV_REQUIRES 的正确使用，避免依赖泄漏
12	最小变更原则	Bug 修复时必须遵守最小必要变更，禁止大规模重构无关代码
13	硬件驱动迁移流程	用户提供硬件例程后的 16 步迁移流程，从分析到构建验证
14	调试日志增强	BSP、Middleware、App 三层分别应添加哪些类型的调试日志
15	低功耗与定时提醒	休眠/唤醒/本地提醒架构设计，NVS 持久化和离线提醒规则
16	修改后验证流程	代码修改后必须执行构建或静态检查的验证步骤
17	最终回复模板	完成任务后向用户汇报的必备内容清单和 commit message 示例
18	禁止事项	项目中明确禁止的 15 种行为，包括幻想实现、混合分层、忽略 Git 等
19	推荐工作流	每次任务的 15 步完整执行流程，从 Git 检查到总结汇报
20	核心设计原则	项目整体架构思想：app → middleware → bsp → esp-idf drivers
21	调用链追踪	在项目根目录维护 Call_chain.md，用 Mermaid 流程图 + 调用链表 + 文件路径记录每次代码变更的调用逻辑
22	Kconfig 规则：板级配置项的正确放置	新增板级支持时，必须在 main/Kconfig.projbuild 中添加对应的 Kconfig 条目。错误放置会导致配置项在 menuconfig 中不可见。