QH 固件平台工具

源码统一维护在 GitHub 私有仓库 qihaokaigong/qh-firmware-platform；产品开发使用本地 checkout。

本仓库也是固件体系的统一控制面。机器可读的仓库目录和关系位于 workspace/repositories.json，跨仓状态、补齐 checkout 和迭代流程见 docs/workspace-management.zh-CN.md。

当前版本隔离设计见 产品版本隔离方案：优先复用官方工具。 新产品默认通过完整 Git commit SHA 和 ESP-IDF 官方锁文件固定组件与板卡；升级由产品显式提交依赖变更。

node bin/workspace.mjs context
node bin/workspace.mjs status --workspace /path/to/workspace
node bin/workspace.mjs check --workspace /path/to/workspace --require-clean
node bin/workspace.mjs bootstrap --workspace /path/to/workspace --dry-run

0.1.8 生成的产品入口固定 runtime 0.3.1，并让 context 和依赖策略检查在普通 Python 3.11+ 环境中运行；ESP-IDF 解析工具仍单独固定。它补齐 ESP-IDF YAML flow mapping、带引号依赖名和空 lock 兼容性，并携带已同步的跨仓库发布目录。runtime 会明确处理本地配置会话过期。流程见 产品发布指南。归档交付回归：node tests/installer-consumer.mjs /qh-firmware-installer绝对路径；仅使用本地包和 npm 缓存，不烧录、不发布。

发布包：@qhkg/create-firmware。产品仓库只保留组装与业务；此仓库拥有生成器、Python 构建/测试/打包工具及小型模板。平台版本锁定在产品的 package-lock.json，不会随其他产品自动升级。

给 Codex 安装开发 Skill

在本仓库执行，首次安装和以后更新使用同一命令：

npm run skill:install

该 npm 命令分别安装/更新 qh-product-onboarding（新产品接入）与 qh-product-development（功能迭代）， 安装到 $CODEX_HOME/skills/（未设置时为 ~/.codex/skills/）下各自同名目录；每个 Skill 独立保留升级备份。 也可 node bin/create-firmware.mjs skill install --name qh-product-development --skill-dir /自定义技能目录。 CLI 不指定 --name 时仍只安装接入 Skill，保持已有命令兼容。 下一轮对话可调用；若客户端未刷新列表，重开会话。

调用示例：

使用 $qh-product-onboarding 创建 qh-product-air-monitor，使用已有 esp32-c3-mini-v1 板卡。 基础仓库父目录为 /我的工作区。先完成测试和编译，不烧录、不发布。

接入完成后：

使用 $qh-product-development 为当前产品增加暂停和继续功能。没有屏幕和按键，先实现纯逻辑并测试，不烧录。

功能流程与业务测试接入见 功能迭代指南。 仓库职责、本地 workspace 调用和新业务接入见 架构与业务接入指南。 新产品自动获得该指南，旧产品按需参考，不自动覆盖其文档或业务代码。

这是开发者通用 Skill，不替代各产品的终端用户固件安装 Skill。 Skill 仅按需读取相关文档，调用已有生成器和产品脚本；不引入代理编排、常驻服务或自动发布。 node bin/create-firmware.mjs doctor 输出有界的环境预检 JSON，不安装软件、不连接设备； 请先在同一 shell 激活已安装的 ESP-IDF 6.1 export.sh。预检通过仍需 resolve/test/build。

更新规则

• 本地：更新此仓库源码并通过 npm test 后，再执行 npm run skill:install，安装该源码的最新快照。
• npm 发布以后：npx @qhkg/create-firmware@latest skill install 更新接入 Skill； npx @qhkg/create-firmware@latest skill install --name qh-product-development 更新功能 Skill，均安装 npm 的 latest 版本。 ESP 组件和板卡当前从私有 Git 固定完整提交，不发布 Registry；该命令只安装开发工具，不升级已有产品依赖。
• 同版本同内容重复安装不变更；升级保留旧目录到技能根目录的 .qh-skill-backups/，输出备份路径。 人工修改、额外文件或符号链接会拒绝覆盖；先保留/移走自己的内容，再安装，无强制覆盖开关。
• 安装包含独立工具快照，不引用易失的 npx 缓存或原仓库。快照仅在执行时使用，不要求 AI 读取。 版本和内容摘要记录于 .qh-install.json。它用于识别本工具管理的文件，不是安全签名。
• 更新 Skill 不升级已有产品的 npm/ESP 依赖、不重写产品源码、不自动拉取仓库或定时联网更新。 新产品使用所安装生成器版本；已有产品继续用自己的锁定版本。
• 若安装进程被中断并遗留 .qh-product-onboarding.lock，先确认没有安装进程，再人工移走锁后重试； 如旧版已移入备份而目标缺失，可先将输出/备份目录中的旧版恢复到原路径。

新建产品

npm 工具包发布后：

npx @qhkg/[email protected] product ./qh-product-air-monitor --product-id air-monitor --display-name 空气仪 --board [email protected]

维护平台源码时也可直接运行尚未发布的生成器：

node bin/create-firmware.mjs product /tmp/qh-product-air-monitor --product-id air-monitor --display-name 空气仪 --board [email protected]

默认模式写入组件和板卡私有 Git 地址、子目录和完整 commit SHA；基础仓库以后更新不会改变已生成产品。--workspace /path/to/repository-parent 只用于候选公共能力的临时跨仓联调，会生成本地 override_path，不能作为产品的正式依赖提交。已有目录一律拒绝覆盖。生成后按产品 README 激活 ESP-IDF 6.1、安装工具、解析锁、测试并编译。

首次使用先执行 python3 scripts/project.py resolve，由 IDF 官方组件管理器生成锁并下载板卡包，然后 generate/test/build。此步骤不依赖已经生成的 board Kconfig/CMake。

所有权与更新

python/qh_platform 是工具单一来源，产品内 scripts/project.py 仅为入口。不要把工具源码复制回产品。基础运行时使用 qh/connected_runtime，板卡包使用 qh/board_*；产品特性放进产品仓库 components/product_logic，main 只做组装。

升级在产品分支中显式修改一个依赖版本，重新解析并提交 lock，再运行 test/build；保留上一组清单和锁文件用于源码回退。不要删除设备 NVS 作为升级步骤；持久化 schema 必须有迁移/拒绝策略。

运行 npm test 验证生成器；完整 Python 工具回归目前位于参考产品 scripts/tests，执行参考产品的 project.py test。打包命令 npm pack --dry-run，不等于公开发布成功。

边界：软件支持的板卡不是硬件认证；example-esp32s3 是模板板，不应作为用户设备发布。首版主机支持 macOS；其他系统尚未验收。