tirtc-device-builder 0.2.0 → 0.4.0

package/README.md

@@ -1,369 +1,447 @@
 # TiRTC Device Builder
 
-TiRTC Device Builder 是一个面向设备开发者的 Codex Plugin 仓库。它把不同芯片平台的开发流程拆成独立 Skill，根据开发板型号、原理图、BSP、引脚表和外设示例生成、移植、编译和验证 TiRTC 设备工程。
+TiRTC Device Builder 用于把 ESP32-S3 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Codex Skill 会先检查环境、整理有依据的硬件事实，再生成独立的 ESP-IDF 工程并完成板级移植和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
 
-仓库当前包含：
+当前仓库提供一个 Skill：
 
-| Skill | 平台 | 能力 |
+| Skill | 平台 | 主要用途 |
 |---|---|---|
-| `tirtc-esp32-builder` | ESP32-S3 / ESP-IDF 5.5.x | 环境诊断、Hardware IR、H5 实时查看/对讲、AI 对讲工程生成、编译、烧录和分层验收 |
+| `tirtc-esp32-builder` | ESP32-S3、ESP-IDF 5.5.x | 环境检查、Hardware IR、工程生成、板级媒体移植、编译、烧录和分层验收 |
 
-后续平台以新的同级 Skill 加入，例如 `skills/tirtc-taixin-builder/`。每个平台独立维护 SDK、构建工具、板级适配和验收约束。
+开发者不需要克隆 `tirtc-server-example`，也不用登录 npm。工程模板、协议文档和 TiRTC SDK 已打包在独立的 ESP32 Device Kit 中，安装命令会自动下载并校验。
 
-## 能力边界
+- npm 包：[tirtc-device-builder](https://www.npmjs.com/package/tirtc-device-builder)
+- GitHub 仓库：[tangeai/tirtc-device-builder](https://github.com/tangeai/tirtc-device-builder)
+- ESP32 Device Kit：[kit-esp32s3-v1.0.0](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.0.0)
 
-ESP32 Skill 使用公开的 [ThingConnect 示例仓库](https://github.com/tangeai/tirtc-server-example) 作为协议、模板、生成器和 TiRTC ESP32 SDK 的事实源。这个仓库不复制服务端源码、预编译 TiRTC SDK、设备凭证或媒体样本。
+文档导航：
 
-模板工程提供配网、绑定、MQTT、TiRTC、H5 和 AI 会话骨架。具体开发板仍需接入摄像头、H.264 编码器、麦克风、扬声器、Codec、I2S 和按键。工程编译成功不等于 Web 已经出图或 AI 对讲已通过实机验收。
+- [新用户快速开始](#新用户快速开始)
+- [准备板卡资料](#准备板卡资料)
+- [依赖和支持范围](#依赖和支持范围)
+- [安装方式和默认目录](#安装方式和目录)
+- [检查、生成和编译](#常用检查和开发命令)
+- [烧录和实机验收](#烧录和验收)
+- [常见问题](#常见问题)
 
-## 新人从零开始：一次跑通 ESP32-S3 H5/AI
+## 新用户快速开始
 
-推荐先跑通“安装 → 环境 → 板卡分析 → 生成 → 编译”，确认报告无误后再单独授权烧录和实机验收。整个过程使用同一份板卡事实，避免在代码生成阶段猜测引脚、器件或媒体能力。
+### 1. 确认 Node.js
 
-```text
-板卡型号/原理图/BSP
-        ↓
-Hardware IR（硬件事实与来源）
-        ↓
-能力门禁（READY_TO_PORT 才进入实现）
-        ↓
-独立 ESP-IDF 工程 + 板级媒体适配
-        ↓
-编译 → 授权烧录 → 配网绑定 → H5/AI 验收
-        ↓
-TIRTC_PORTING_REPORT.md
+安装命令依赖 Node.js 18 或更高版本：
+
+```bash
+node --version
+npm --version
 ```
 
-### 第 0 步：确认当前支持范围
+`node --version` 应输出 `v18.x` 或更高版本。如果终端提示找不到 `node` 或 `npm`，先从 [Node.js 官方下载页](https://nodejs.org/en/download) 安装受支持版本，再打开一个新终端。
 
-当前可直接生成的基线是：
+### 2. 安装并检查开发环境
 
-| 项目 | 当前基线 |
-|---|---|
-| 芯片 | ESP32-S3 |
-| 模组 | ESP32-S3-WROOM-1-N16R8，或资源与配置经过确认的兼容板 |
-| ESP-IDF | 5.5.x |
-| TiRTC SDK | `espressif-esp32s3/2.3.0` |
-| 业务 | H5 实时音视频、H5 对讲、AI 双向语音 |
-| 工程生成 | 需要一次本地 ThingConnect 工作区 |
-| 烧录 | 必须明确给出串口并授权 |
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install
+```
 
-“板上有摄像头”不等于可以输出 H5 视频。H5 视频还需要可用的 H.264 Annex-B 编码输出、SPS/PPS、IDR 和关键帧请求控制；对讲还需要完整的麦克风采集、G.711 A-law 8 kHz 编码、下行解码、I2S/Codec/功放和扬声器路径。
+这条命令会：
 
-当前生成器只支持 ESP32-S3，TiRTC SDK 也必须匹配 `espressif-esp32s3` 平台。Flash/PSRAM 不是 16 MB/8 MB 时，需要先调整 `sdkconfig.defaults`、分区表和板级资源预算并重新评估；Skill 不会把相似型号静默当作当前板卡。
+- 把 `tirtc-esp32-builder` 安装到 Codex Skill 目录；
+- 下载 ESP32 Device Kit 并校验 SHA-256；
+- 复用当前可用的 ESP-IDF 5.5.x，找不到时安装 ESP-IDF 5.5.4；
+- 安装 Espressif 管理的 ESP32-S3 工具链；
+- 写入只包含本地路径的 `config.json` 和 `env.sh`；
+- 激活托管环境并运行 Doctor。
 
-### 第 1 步：固定工作路径
+安装器只写入当前用户有权限的目录，不执行 `sudo`，也不修改 `.bashrc`、`.zshrc` 等 shell 配置。如果缺少系统软件，它会停下来说明缺少什么；补齐后重新执行同一条命令即可继续。
 
-下面的命令以 Linux、Ubuntu 或 WSL 的 Bash 为例。先把所有路径改成自己的绝对路径；路径可以不同，但后续必须始终使用同一组值。
+安装成功时，输出末尾应包含：
 
-```bash
-export TIRTC_WORKSPACE=/home/your-user/workspace
-export TIRTC_THING_CONNECT_ROOT="$TIRTC_WORKSPACE/tirtc-server-example/thing-connect"
-export TIRTC_BOARD_DOCS="$TIRTC_WORKSPACE/board-materials"
-export TIRTC_PROJECT_DIR="$TIRTC_WORKSPACE/my-esp32-device"
+```text
+OVERALL: PASS
+SETUP: READY
+Start a new Codex session and invoke $tirtc-esp32-builder.
 ```
 
-逐项确认：
+如果看到 `OVERALL: NEEDS_SETUP`、`MISS` 或 `FAIL`，先看[常见问题](#常见问题)。
 
-```bash
-printf 'workspace: %s\n' "$TIRTC_WORKSPACE"
-printf 'ThingConnect: %s\n' "$TIRTC_THING_CONNECT_ROOT"
-printf 'board docs: %s\n' "$TIRTC_BOARD_DOCS"
-printf 'output project: %s\n' "$TIRTC_PROJECT_DIR"
-```
+### 3. 重新打开 Codex
 
-注意：
+Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex 会话，再打开一个新会话。
 
-- `TIRTC_PROJECT_DIR` 是待生成的新目录，生成前不能已经存在；生成器不会覆盖旧工程。
-- 板卡资料和输出工程使用不同目录。
-- 不要把 Wi-Fi 密码、设备密钥、MQTT/WHIP token 或真实用户音视频放入板卡资料目录和 Git 仓库。
-- 新开终端后需要重新设置这些变量，除非开发者自行把它们加入 shell 配置。
+### 4. 把板卡和目标告诉 Codex
 
-### 第 2 步：准备板卡资料包
+把你已经掌握的信息填进下面的提示词即可，不用先查齐所有硬件参数。路径请使用绝对路径，不确定的内容写“未知”。可直接复制的版本见[开发板接入提示词](skills/tirtc-esp32-builder/assets/developer-intake-prompt.md)。
 
-创建资料目录，把原始资料按来源保存，不要先手工改写原理图或 BSP：
+```text
+请使用 $tirtc-esp32-builder 完成这块开发板的 TiRTC 移植。
 
-```bash
-mkdir -p "$TIRTC_BOARD_DOCS"
+开发板：
+- 厂商、完整型号、PCB/硬件版本：<填写>
+- 资料与手中实物是否对应：<是/否/未知>
+
+资料：
+- <原理图、BSP/厂商示例、数据手册或产品页；一行一个>
+
+目标：
+- 功能：<例如 H5 实时音视频、H5 对讲、AI 双向语音>
+- 视频：<MJPEG/H264/H265/根据合同和硬件证据选择>
+- Wi-Fi：<指定方案/根据 BSP 选择>
+- 设备绑定：<指定方案/根据平台合同选择>
+
+工程：<输出目录或现有工程的绝对路径>
+
+请先运行 Doctor，分析全部资料并生成 Hardware IR v2。资料不足时列出最小补充项；达到 READY_TO_PORT 后再生成、适配和编译，并输出 TIRTC_PORTING_REPORT.md。
+本轮不访问串口、不烧录、不擦除 NVS，也不要把任何凭证写入源码或报告。
 ```
 
-最有利于一次完成的资料如下：
+手头只有型号也可以开始：
 
-| 优先级 | 资料 | 需要明确的内容 |
+```text
+$tirtc-esp32-builder
+
+分析 <厂商> <完整型号> <PCB 版本>，目标是 H5 实时音视频、
+H5 对讲和 AI 双向对讲。
+先给出板卡资料清单、Hardware IR、能力结论和最小缺失项；
+本轮不生成工程、不烧录。
+```
+
+只有型号时，Skill 会先调查公开资料并列出缺口，不会猜测 GPIO、器件或媒体能力。要进入代码移植，通常还需要准确的板卡版本、原理图，以及能在实物上运行的 BSP 或外设示例。
+
+## 工作范围
+
+整个流程从板卡资料核对开始，以分层验收报告结束：
+
+```text
+开发板型号、原理图、BSP、数据手册
+                  │
+                  ▼
+      Hardware IR：硬件事实、来源和未知项
+                  │
+                  ▼
+       能力门禁：能否支持 H5 / AI
+                  │
+                  ▼
+      独立 ESP-IDF 工程与板级媒体适配
+                  │
+                  ▼
+       编译 → 授权烧录 → 分层实机验收
+                  │
+                  ▼
+            TIRTC_PORTING_REPORT.md
+```
+
+Skill 负责：
+
+- 检查 Node.js 之外的 ESP-IDF、编译器、TiRTC SDK、工程配置和串口；
+- 从原理图、BSP、数据手册和实测示例中提取有来源的硬件事实；
+- 生成并校验 `hardware-ir.json`，把冲突和未知项留在报告里；
+- 判断视频、上行音频、下行播放和 AI 会话是否具备移植条件；
+- 生成带 TiRTC SDK 的独立 ESP-IDF 工程；
+- 把摄像头、所选 MJPEG/H.264/H.265 路径、麦克风、Codec、I2S、功放和按键接到板级 adapter；
+- 运行测试和 `idf.py build`，记录固件路径、版本和 SHA-256；
+- 在用户明确给出芯片、工程和串口后烧录；
+- 分别验证启动、上线、本地媒体、H5、AI 和稳定性；
+- 输出 `TIRTC_PORTING_REPORT.md`，每一层都标成 `PASS`、`FAIL` 或 `SKIP`。
+
+### Skill 不猜硬件
+
+模板工程提供配网、绑定、MQTT、TiRTC、H5 和 AI 会话骨架，但不会内置所有开发板的产品驱动。每块开发板仍要根据自身资料接入：
+
+- 摄像头和所选 MJPEG/H.264/H.265 完整媒体路径；
+- 麦克风采集路径；
+- Codec、I2S、功放和扬声器播放路径；
+- 板级电源、时钟、复位和使能控制；
+- 需要用于 AI 会话的实体按键或其他触发方式。
+
+编译成功只代表构建层通过。只有拿到浏览器画面、实体扬声器声音和双向 AI 音频的实测证据，报告才能把对应能力标为 `PASS`。
+
+## 准备板卡资料
+
+板卡资料要和手上的实物版本对应。建议为每块板、每个 PCB 版本单独建目录，避免混入相似型号的文档。
+
+建议按下面的结构整理：
+
+```text
+board-materials/
+├── BOARD.md
+├── schematic/
+│   └── board-rev-a.pdf
+├── bom/
+│   └── board-rev-a.xlsx
+├── bsp/
+│   └── README.md
+├── datasheets/
+│   ├── camera-sensor.pdf
+│   ├── audio-codec.pdf
+│   └── amplifier.pdf
+└── examples/
+    ├── camera/
+    ├── audio-record/
+    └── audio-playback/
+```
+
+`BOARD.md` 至少记录：
+
+```markdown
+# 板卡身份
+
+- 厂商：
+- 完整销售型号：
+- 模组型号：
+- PCB 丝印：
+- 硬件版本：
+- Flash / PSRAM：
+
+# 资料来源
+
+- 产品页：
+- 原理图名称和版本：
+- BSP 仓库、commit 或 tag：
+- 已在实物上验证的示例：
+
+# 开发目标
+
+- H5 实时视频：
+- H5 实时音频：
+- H5 下行对讲：
+- AI 双向对讲：
+
+# 媒体与接入合同
+
+- H5 支持/选定的视频 profile：
+- 音频格式与 stream ID：
+- 板卡/BSP 支持的 Wi-Fi 凭证方法：
+- 本工程选择的凭证方法和重配入口：
+- ThingConnect 绑定、已绑定跳过和清除方式：
+```
+
+不同能力需要的证据不一样：
+
+| 资料 | 用来确认什么 | 重要程度 |
 |---|---|---|
-| 必需 | 板卡身份 | 厂商、完整型号、模组型号、PCB 丝印和硬件版本 |
-| 必需 | 原理图或网表 | 摄像头、麦克风、Codec、功放、I2S、I2C、SPI、时钟、复位、电源使能和 GPIO |
-| 必需 | BSP 或厂商示例 | 可复现的 Git commit/tag、ESP-IDF 版本、能工作的外设初始化与管脚定义 |
-| 视频必需 | 摄像头/编码资料 | Sensor 型号、输入接口、H.264 编码位置、Annex-B 输出、SPS/PPS、IDR 控制 |
-| 对讲必需 | 音频资料 | 麦克风类型、Codec/ADC/DAC、采样率、位宽、声道、MCLK/BCLK/LRCK、功放使能 |
-| 推荐 | 器件数据手册 | Sensor、Codec、功放、时钟和电源芯片的准确型号与版本 |
-| 推荐 | 最小实测工程 | 已在该 PCB 版本运行的摄像头、录音、播放或编码示例及其构建命令 |
+| 板卡身份 | 厂商、完整型号、模组、PCB 丝印和硬件版本 | 必需 |
+| 原理图或网表 | GPIO、电源、复位、时钟、I2C、I2S、SPI、摄像头和音频链路 | 必需 |
+| BSP 或厂商示例 | 实际初始化顺序、驱动版本、ESP-IDF 版本和可工作的管脚定义 | 必需 |
+| 摄像头和编码资料 | Sensor、输入接口、所选 MJPEG/H.264/H.265 输出边界与刷新/关键帧控制 | H5 视频必需 |
+| 音频资料 | 麦克风类型、Codec/ADC/DAC、采样率、位宽、声道、MCLK/BCLK/LRCK、功放使能 | 对讲必需 |
+| 配网/绑定资料 | 可用 Wi-Fi 凭证方法、凭证存储/重配、可用绑定方法、已有绑定状态和清除入口 | 上线必需 |
+| 数据手册 | 器件寄存器、时序、电气限制和版本差异 | 推荐 |
+| 实测小工程 | 证明摄像头、录音、播放或编码确实在该 PCB 版本工作 | 强烈推荐 |
 
-资料不完整也可以先调用 Skill。它会把未知事实写成 `null`，并列出进入下一步所需的最小补充项。不同 PCB 版本按不同板卡处理；不能只给“ESP32-S3”而省略载板型号和版本。
+提供 BSP 时，请同时注明可复现的 commit、tag 或压缩包版本，以及它使用的 ESP-IDF 版本。只有一个持续变化的仓库首页，后续很难追溯代码与实物不一致的原因。
 
-### 第 3 步：安装 Node.js 和 Skill
+不要放进资料包的内容包括 Wi-Fi 密码、设备密钥、MQTT/WHIP token、证书、生产配置和真实用户音视频。
 
-使用 npm 安装 Skill 只需要 Node.js 18 或更高版本。普通使用者不需要执行 `npm login`；登录只用于维护者发布 npm 包。
+## 依赖和支持范围
 
-先检查版本和 npm 官方源：
+### 当前版本基线
 
-```bash
-node --version
-npm --version
-npm config get registry
-```
+| 项目 | 当前要求 |
+|---|---|
+| 芯片 | ESP32-S3 |
+| 参考模组 | ESP32-S3-WROOM-1-N16R8，或资源和配置经过确认的兼容板 |
+| ESP-IDF | 5.5.x |
+| 自动安装版本 | ESP-IDF v5.5.4 |
+| TiRTC SDK | `espressif-esp32s3/2.3.0` |
+| ESP32 Device Kit | 1.0.0 |
+| Node.js | 18 或更高版本 |
+| 支持自动安装的系统 | Linux、WSL、macOS |
+| 原生 Windows | 使用 Espressif 官方安装器准备 ESP-IDF，再重新运行检查 |
 
-预期：
+当前生成器只支持 ESP32-S3。Flash 或 PSRAM 不是 16 MB / 8 MB 时，需要重新评估 `sdkconfig.defaults`、分区表、DMA 和媒体缓存预算。名称相近的芯片不会被自动当作 ESP32-S3 处理。
 
-- Node.js 输出 `v18.x` 或更高版本；
-- npm registry 输出 `https://registry.npmjs.org/`。
+### 本机软件
 
-如果 `node` 或 `npm` 不存在，先从 [Node.js 官方下载页](https://nodejs.org/en/download) 安装受支持版本，重新打开终端，再重复版本检查。
+`setup esp32 --install` 会检查以下基础命令：
 
-如果 registry 不是官方源，可为当前用户切换：
+| 命令 | 用途 |
+|---|---|
+| `python3` | ESP-IDF、工程生成器和检查脚本 |
+| `git` | 获取固定版本的 ESP-IDF |
+| `bash` | 激活和安装 ESP-IDF |
+| `tar` | 解包并验证 Device Kit |
 
-```bash
-npm config set registry https://registry.npmjs.org/
-```
+Doctor 还会检查 `cmake`、`ninja`、`idf.py` 和 `xtensa-esp32s3-elf-gcc`。安装器不会调用系统包管理器；缺少基础命令时，需要开发者按当前操作系统安装。
 
-确认 npm 包可访问并安装当前稳定版本：
+Ubuntu、Debian 或 WSL 可以参考：
 
 ```bash
-npm view tirtc-device-builder version
-npx tirtc-device-builder@0.2.0 list
-npx tirtc-device-builder@0.2.0 install esp32
+sudo apt-get update
+sudo apt-get install -y git python3 python3-venv bash tar
 ```
 
-成功时最后会看到类似输出：
+### 网络和业务环境
 
-```text
-Installed tirtc-esp32-builder 0.2.0 to /home/.../.codex/skills/tirtc-esp32-builder
-Start a new Codex session, then invoke $tirtc-esp32-builder.
-```
+首次安装通常需要访问：
 
-默认安装位置是 `${CODEX_HOME:-~/.codex}/skills/tirtc-esp32-builder`。安装完成后关闭当前 Codex 会话并启动一个新会话，让 Codex 重新发现 Skill。
+- npm 官方 Registry，用于取得 `tirtc-device-builder`；
+- GitHub Release，用于下载 ESP32 Device Kit；
+- Espressif 的 GitHub 仓库和工具下载地址，用于安装 ESP-IDF 与工具链。
 
-如果目标目录已经存在，安装器会保护已有内容并退出。先确认目录中的本地修改是否需要保留；只有确定要替换时才执行：
+H5 和 AI 的端到端验收还需要可访问的 ThingConnect 服务、可用账号、设备绑定条件、浏览器和外网。缺少其中一项，不影响工程生成和编译，但对应验收层要记录为 `SKIP`。
 
-```bash
-npx tirtc-device-builder@0.2.0 install esp32 --force
-```
+### 媒体约束
 
-自定义 Skill 根目录时使用绝对路径：
+H5 视频要先从前端和服务端支持的合同中选择一种 profile。MJPEG 提交完整 JPEG 帧；H.264/H.265 按合同提交 Annex-B access unit、参数集，并实现刷新或关键帧控制。板上有摄像头 Sensor，只能证明图像有来源，不能证明浏览器一定能持续出图。
 
-```bash
-npx tirtc-device-builder@0.2.0 install esp32 \
-  --skills-dir /absolute/path/to/skills
-```
+当前音频基线使用 G.711 A-law、8 kHz、单声道。对讲还要有可靠的下行队列、A-law 解码、Codec/I2S/功放播放和会话停止清理。没有可用的全双工和 AEC 证据时，应按半双工设计 AI 对讲。
 
-如果 npm 包尚未发布或当前网络无法访问 npm，可从 GitHub 安装固定版本。在 Codex 对话中输入：
+## 安装方式和目录
 
-```text
-$skill-installer
+### 推荐：用 npx 一次检查并安装
 
-安装：
-https://github.com/tangeai/tirtc-device-builder/tree/v0.2.0/skills/tirtc-esp32-builder
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install
 ```
 
-Linux/macOS 也可以执行：
+`npx` 会临时取得最新 CLI 并运行，不要求全局安装。它适合这种低频的安装和诊断工具，也避免用户机器里长期保留旧版本命令。
+
+### 也可以全局安装
 
 ```bash
-python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
-  --repo tangeai/tirtc-device-builder \
-  --ref v0.2.0 \
-  --path skills/tirtc-esp32-builder
+npm install --global tirtc-device-builder@latest
+tirtc-device-builder setup esp32 --install
 ```
 
-仓库根目录还包含 `.codex-plugin/plugin.json`，可作为 skills-only Plugin 使用。直接从 npm 或 GitHub 安装不依赖 Plugin Directory 审核。
+安装命令是 `npm install`，不要写成 `npm --install`。
 
-### 第 4 步：准备 ThingConnect 工作区
+只执行 `npm install --global tirtc-device-builder` 会安装 CLI，不会准备完整开发环境。随后还要运行 `setup esp32 --install`，由它安装 Codex Skill、下载 Device Kit，并在需要时安装 ESP-IDF。npm 包没有 `preinstall`、`install` 或 `postinstall` 生命周期脚本，因此不会在安装 CLI 时改动这些目录。
 
-当前 Skill 不复制 ThingConnect 服务端源码和 TiRTC 预编译库。生成新工程时，以下内容来自公开的 ThingConnect 仓库：
+安装公开包不需要执行 `npm login`；这个命令只和维护者发布新版本有关。
 
-- ESP32-S3 H5/AI 工程生成器；
-- 起步模板和平台公共组件；
-- TiRTC ESP32-S3 SDK 头文件、静态库和构建契约；
-- H5、AI、设备接入和会话协议文档。
+### 只安装 Skill
 
-只需准备一次，后续多个工程可以共用同一工作区：
+如果 ESP-IDF 和 Device Kit 已经由团队统一准备，可以只复制 Codex Skill：
 
 ```bash
-mkdir -p "$TIRTC_WORKSPACE"
-git clone https://github.com/tangeai/tirtc-server-example.git \
-  "$TIRTC_WORKSPACE/tirtc-server-example"
+npx --yes tirtc-device-builder@latest install esp32
 ```
 
-验证关键文件：
+这条命令不安装 ESP-IDF，也不下载 Device Kit。完整的新用户环境仍建议使用 `setup esp32 --install`。
+
+### 默认目录
+
+| 内容 | 默认位置 |
+|---|---|
+| Codex Skill | `${CODEX_HOME:-~/.codex}/skills/tirtc-esp32-builder` |
+| 托管根目录 | `~/.tirtc-device-builder` |
+| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.0.0` |
+| ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
+| Espressif 工具 | `~/.tirtc-device-builder/espressif` |
+| 安装记录 | `~/.tirtc-device-builder/config.json` |
+| 环境入口 | `~/.tirtc-device-builder/env.sh` |
+
+新开终端后，用下面的命令激活托管环境：
 
 ```bash
-ls -l "$TIRTC_THING_CONNECT_ROOT/device-sim/scripts/create_esp32_project.py"
-ls -l "$TIRTC_THING_CONNECT_ROOT/device-sim/sdk/espressif-esp32s3/2.3.0/include/tirtc/tiRTC.h"
-ls -l "$TIRTC_THING_CONNECT_ROOT/device-sim/sdk/espressif-esp32s3/2.3.0/lib/libTiRTC.a"
-ls -l "$TIRTC_THING_CONNECT_ROOT/device-sim/sdk/espressif-esp32s3/2.3.0/manifest/build-contract.env"
+source ~/.tirtc-device-builder/env.sh
+idf.py --version
+printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 ```
 
-四条命令都应显示真实文件。记录当前源码版本，便于报告和复现：
+`env.sh` 只设置 ESP-IDF、工具链和 Device Kit 路径，不包含设备凭证。
+
+### 自定义目录或复用已有环境
+
+把所有托管文件放到指定目录：
 
 ```bash
-git -C "$TIRTC_WORKSPACE/tirtc-server-example" rev-parse HEAD
+npx --yes tirtc-device-builder@latest setup esp32 --install \
+  --root /absolute/path/tirtc-dev
 ```
 
-生成器会把必要模块和 TiRTC SDK 复制到新工程的 `third_party/tirtc/`，所以已生成的工程可以移动并独立编译。安装 Skill、列出平台、分析本地板卡资料，以及诊断一个已经自带 SDK 的生成工程，不要求每次重新拉取 ThingConnect。
+自定义根目录后，环境入口也随之变为 `/absolute/path/tirtc-dev/env.sh`。
 
-### 第 5 步：检查或安装 ESP-IDF 5.5.x
-
-先检查当前终端，不要因为环境未激活而重复安装：
+复用已有 ESP-IDF 5.5.x：
 
 ```bash
-command -v idf.py
-idf.py --version
-command -v xtensa-esp32s3-elf-gcc
+npx --yes tirtc-device-builder@latest setup esp32 --install \
+  --idf-dir /absolute/path/esp-idf
 ```
 
-如果 `idf.py --version` 输出 `ESP-IDF v5.5.x`，并且能找到 `xtensa-esp32s3-elf-gcc`，直接进入第 6 步。
+复用已经解包的 Device Kit，或维护者本地的完整 ThingConnect 工作区：
 
-如果 ESP-IDF 已安装但当前终端找不到 `idf.py`，执行该安装目录自带的 `export.sh`。例如：
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install \
+  --thing-connect-root /absolute/path/to/device-kit-or-thing-connect
+```
+
+从本地 Device Kit 压缩包安装，适合内网或离线转交：
 
 ```bash
-source /absolute/path/to/esp-idf/export.sh
-idf.py --version
-command -v xtensa-esp32s3-elf-gcc
+npx --yes tirtc-device-builder@latest setup esp32 --install \
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.0.0.tar.gz
 ```
 
-每个新终端都需要重新执行 `source .../export.sh`。Skill 的环境检查不会自动修改 `.bashrc`、`.zshrc` 等持久 shell 配置。
+安装器仍会核对固定的 SHA-256、目录结构、清单和每个资源文件，不接受未经验证的同名压缩包。
+
+### 更新已安装的 Skill
 
-在 Ubuntu/Debian/WSL 中首次安装时，以下命令安装当前基线 `v5.5.4`。下载、系统包安装和磁盘写入应由开发者在确认目录后执行：
+默认安装不会覆盖已有 Skill，以免丢失本地修改。确认这些修改不需要保留后，可用最新 npm 包替换：
 
 ```bash
-sudo apt-get update
-sudo apt-get install -y git wget flex bison gperf python3 python3-pip \
-  python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util \
-  libusb-1.0-0
+npx --yes tirtc-device-builder@latest setup esp32 --install --force-skill
+```
 
-mkdir -p "$TIRTC_WORKSPACE/toolchains"
-git clone -b v5.5.4 --recursive \
-  https://github.com/espressif/esp-idf.git \
-  "$TIRTC_WORKSPACE/toolchains/esp-idf-v5.5.4"
+该命令只替换 Skill；同版本且已通过校验的 Device Kit 和 ESP-IDF 会继续复用。自定义脚本或规则请提前备份。
 
-"$TIRTC_WORKSPACE/toolchains/esp-idf-v5.5.4/install.sh" esp32s3
-source "$TIRTC_WORKSPACE/toolchains/esp-idf-v5.5.4/export.sh"
+## 常用检查和开发命令
 
-idf.py --version
-command -v xtensa-esp32s3-elf-gcc
+### 查看当前状态
+
+```bash
+npx --yes tirtc-device-builder@latest setup esp32
 ```
 
-最后两条命令必须分别显示 ESP-IDF 5.5.x 和 ESP32-S3 编译器路径。macOS、原生 Windows 或依赖版本有变化时，以 [Espressif ESP-IDF 5.5.4 Get Started](https://docs.espressif.com/projects/esp-idf/en/v5.5.4/esp32s3/get-started/index.html) 为准。
+`setup esp32` 的检查逻辑不会安装开发组件、修改 shell 配置、生成工程或烧录。第一次运行 `npx` 时，npm 可能会把 CLI 下载到自己的缓存。
 
-### 第 6 步：生成工程前运行 Doctor
+环境完整时，它会运行 Doctor 并输出 `SETUP: READY`。环境不完整时，它输出 `OVERALL: NEEDS_SETUP` 和下一条建议命令。
 
-不安装 Skill 也可以通过 npm CLI 调用同一个检查脚本：
+查看 CLI 和当前平台：
 
 ```bash
-npx tirtc-device-builder@0.2.0 doctor esp32 \
-  --expected-idf 5.5 \
-  --target esp32s3 \
-  --thing-connect-root "$TIRTC_THING_CONNECT_ROOT" \
-  --require-workspace
+npx --yes tirtc-device-builder@latest --help
+npx --yes tirtc-device-builder@latest list
+npx --yes tirtc-device-builder@latest setup esp32 --help
 ```
 
-已经安装 Skill 时也可以直接执行：
+### 生成工程前运行 Doctor
 
 ```bash
-python3 ~/.codex/skills/tirtc-esp32-builder/scripts/doctor.py \
+source ~/.tirtc-device-builder/env.sh
+
+npx --yes tirtc-device-builder@latest doctor esp32 \
   --expected-idf 5.5 \
   --target esp32s3 \
   --thing-connect-root "$TIRTC_THING_CONNECT_ROOT" \
   --require-workspace
 ```
 
-生成前的合格结果应满足：
+生成前应看到：
 
-| 检查项 | 期望 |
+| 检查项 | 合格结果 |
 |---|---|
 | Python、Git | `PASS` |
 | `idf.py` | `PASS`，版本为 5.5.x |
 | target compiler | `PASS`，找到 ESP32-S3 编译器 |
-| ThingConnect workspace | `PASS` |
+| ESP32 Device Kit | `PASS` |
 | TiRTC SDK | `PASS` |
-| serial discovery | 还未接板时允许 `WARN` |
+| serial discovery | 未接板时允许 `WARN` |
 | OVERALL | `PASS` |
 
-`doctor.py` 是只读检查：不安装软件、不修改 shell 配置、不生成工程，也不烧录设备。
-
-常见检查失败：
+已经安装 Skill 时，也能直接调用同一份脚本：
 
-- `idf.py not found`：当前终端没有激活 ESP-IDF，先执行 `source <idf-dir>/export.sh`。
-- `target compiler ... not found`：ESP-IDF 环境未激活，或安装时没有包含 `esp32s3`。
-- `ThingConnect workspace ... not found`：传入的路径必须是仓库根目录或其 `thing-connect/` 子目录，并且其中存在生成器。
-- `TiRTC SDK ... missing`：检查仓库是否拉取完整，以及 SDK 的头文件、静态库和 `manifest/build-contract.env` 是否存在。
-- `serial discovery: no serial device detected`：生成和编译阶段可以继续；烧录前必须解决。
-
-不要在一个空目录上提前使用 `--project`。如果看到：
-
-```text
-FAIL TiRTC build contract [required]: no sdkconfig or sdkconfig.defaults in ...
-```
-
-表示传入目录还不是已生成的 ESP-IDF 工程，或者 `--project` 路径给错了。先让 Skill/生成器创建工程；生成后目录中应有 `sdkconfig.defaults`，再运行项目级 Doctor。
-
-### 第 7 步：在新 Codex 会话中调用 Skill
-
-只给出板卡型号也可以启动分析，但提供完整资料更容易一次进入开发。建议复制下面的提示词，逐项替换尖括号内容和绝对路径：
-
-```text
-请使用 $tirtc-esp32-builder 完成这块板的 TiRTC 移植。
-
-板卡：
-- 厂商：<厂商>
-- 完整型号：<型号>
-- 模组：<例如 ESP32-S3-WROOM-1-N16R8>
-- PCB 丝印/硬件版本：<版本>
-
-输入资料：
-- 原理图或网表：/absolute/path/board-materials/<file>
-- BOM：/absolute/path/board-materials/<file>
-- BSP/厂商示例：/absolute/path/vendor-bsp
-- 摄像头/Codec/功放数据手册：/absolute/path/board-materials/<files>
-- ThingConnect：/absolute/path/tirtc-server-example/thing-connect
-
-目标：
-- H5 实时视频和音频
-- H5 下行语音对讲
-- AI 双向语音对讲
-
-输出：
-- 新工程目录：/absolute/path/my-esp32-device
-- Hardware IR：放在新工程同级或工程内的明确路径
-- 报告：/absolute/path/my-esp32-device/TIRTC_PORTING_REPORT.md
-
-执行要求：
-1. 先运行环境 Doctor，并核对 ESP-IDF 5.5.x、esp32s3 工具链和 TiRTC SDK。
-2. 完整分析我提供的每份资料，记录来源、版本、冲突和未知项。
-3. 生成、校验并严格评估 Hardware IR；不要从相似板型猜测管脚或器件。
-4. 每项能力达到 READY_TO_PORT 后，生成独立工程并把板级采集、编码、播放、按键放在 starter_media/板级 adapter。
-5. 运行相关测试和 idf.py build，保留实际命令、结果、固件路径和 SHA-256。
-6. 本轮不烧录、不写设备凭证；需要下载、安装或修改系统环境时先说明具体动作。
-7. 最后生成 TIRTC_PORTING_REPORT.md，所有验收层级使用 PASS、FAIL 或 SKIP，不能用编译成功代替 H5/AI 实机通过。
-```
-
-如果只有型号和网页资料，可先用：
-
-```text
-$tirtc-esp32-builder
-
-分析 <厂商> <完整型号> <PCB 版本>，目标是 H5 实时音视频、H5 对讲和 AI 双向对讲。
-先输出板卡资料清单、Hardware IR、能力结论和最小缺失项；本轮不生成工程、不烧录。
+```bash
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/doctor.py \
+  --expected-idf 5.5 \
+  --target esp32s3 \
+  --thing-connect-root "$TIRTC_THING_CONNECT_ROOT" \
+  --require-workspace
 ```
 
-Skill 会选择以下三条分支之一：
-
-- 已支持板卡：校验已有 Hardware IR 和 adapter 后重新生成、编译和验收；
-- 新板卡：逐份提取原理图/BSP/数据手册事实，建立 Hardware IR，再决定是否实现；
-- 已有 ESP-IDF 工程：先检查目标、配置、组件、驱动和最小外设示例，再隔离可复用板级代码。
-
-### 第 8 步：检查 Hardware IR 和能力门禁
+### 检查 Hardware IR
 
-默认 Hardware IR 工具位于：
+下面的工具通常由 Codex 调用，开发者也可以手工复核：
 
 ```bash
 python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py init \
@@ -376,196 +454,362 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess --stri
   /absolute/path/hardware-ir.json
 ```
 
-通常由 Codex 执行这些命令，开发者只需检查结果：
+能力门禁有四种状态：
 
-| 状态 | 含义 | 下一步 |
+| 状态 | 含义 | 怎么处理 |
 |---|---|---|
-| `NEEDS_CONFIRMATION` | 关键事实未知或只有单一来源 | 补原理图、BSP、数据手册或实测证据 |
-| `BLOCKED` | 已确认当前硬件/SDK 不满足 | 换硬件、补编码/播放路径或取得匹配 SDK |
-| `READY_TO_PORT` | 资料已足够，可以生成并实现板级适配 | 进入生成和编译 |
-| `HIL_VERIFIED` | 该功能已完成端到端实机验证 | 保存证据和版本 |
+| `NEEDS_CONFIRMATION` | 关键事实未知、冲突或只有单一来源 | 补原理图、BSP、数据手册或实测证据 |
+| `BLOCKED` | 现有硬件或 SDK 已确认不满足 | 更换硬件，补编码/播放路径，或取得匹配 SDK |
+| `READY_TO_PORT` | 资料足以开始生成和板级实现 | 进入工程生成与编译 |
+| `HIL_VERIFIED` | 已完成端到端实机验证 | 固定版本并保存证据 |
 
-`assess --strict` 返回非零不一定表示脚本坏了；当任一请求能力尚未达到 `READY_TO_PORT` 时，它会用退出码阻止过早生成。先处理输出中的具体原因。
+`assess --strict` 在条件不足时返回非零，这是门禁在阻止过早生成，不代表脚本损坏。
+
+Hardware IR v2 只有在运行证据绑定到同一固件 SHA-256 时才会给出 `HIL_VERIFIED`：
+
+```bash
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess \
+  /absolute/path/hardware-ir.json \
+  --artifact-sha256 <64-character-sha256> --strict
+```
 
-### 第 9 步：生成、实现和编译
+### 生成和编译
 
-推荐让 Skill 自动执行。需要人工复现生成步骤时，确保 `TIRTC_PROJECT_DIR` 不存在，再运行：
+建议让 Skill 完成生成、适配和编译。需要人工复现时，先激活环境，并确认输出目录尚不存在：
 
 ```bash
+source ~/.tirtc-device-builder/env.sh
+
 python3 "$TIRTC_THING_CONNECT_ROOT/device-sim/scripts/create_esp32_project.py" \
-  "$TIRTC_PROJECT_DIR" \
+  /absolute/path/my-esp32-device \
   --name my_esp32_device
 ```
 
-`--name` 只能包含小写字母、数字和下划线。生成器拒绝覆盖已存在目录；需要重做时应先选择新的输出目录或人工备份旧工程。
+`--name` 只能包含小写字母、数字和下划线。生成器不会覆盖已有目录。
 
-进入工程，激活 ESP-IDF，再检查 SDK 构建契约。下面的 `source` 路径只适用于按第 5 步安装到示例目录的情况；已有安装应替换为其真实 `export.sh` 路径：
+工程生成后再做项目级检查：
 
 ```bash
-cd "$TIRTC_PROJECT_DIR"
-source "$TIRTC_WORKSPACE/toolchains/esp-idf-v5.5.4/export.sh"
-
 python3 ~/.codex/skills/tirtc-esp32-builder/scripts/doctor.py \
   --expected-idf 5.5 \
   --target esp32s3 \
-  --project "$TIRTC_PROJECT_DIR"
+  --project /absolute/path/my-esp32-device
 ```
 
-项目级 Doctor 的 `TiRTC build contract` 必须为 `PASS`。随后构建：
+`TiRTC build contract` 为 `PASS` 后编译：
 
 ```bash
+cd /absolute/path/my-esp32-device
 idf.py set-target esp32s3
 idf.py build
 ```
 
-构建成功只证明 L1 Build 通过。真正的板卡移植还要完成 `components/starter_media/` 中的产品适配点：
+生成器会把 TiRTC SDK 复制到工程的 `third_party/tirtc/`。此后工程不再依赖 `tirtc-server-example`，但换机编译仍需准备兼容的 ESP-IDF 5.5.x 工具链。
 
-- 麦克风采集并提交 G.711 A-law、8 kHz、单声道帧；
-- 摄像头采集并提交 H.264 Annex-B access unit；
-- 收到关键帧请求时让编码器产生 IDR；
-- 把下行 A-law 音频放入有界队列，解码后写入 Codec/I2S/功放；
-- 把实体按键映射到 AI 开始/停止；
-- 停止会话时有界停止采集/播放任务并清空旧 generation 数据。
-
-检查仍未完成的产品适配点：
+检查尚未完成的产品适配点：
 
 ```bash
 rg -n 'TODO\(product-' main components
 ```
 
-编译产物位于 `build/`。报告至少记录 ESP-IDF、TiRTC SDK、BSP/adapter 版本，实际构建命令、返回码、固件文件和 SHA-256。
+常见适配内容包括麦克风采集、G.711 A-law 编码、所选视频 profile 输出与刷新请求、下行音频播放、实体按键和会话停止后的资源清理。
+
+## 烧录和验收
 
-### 第 10 步：明确授权后烧录
+### 烧录前确认串口
 
-先连接开发板并确定唯一串口。Linux 常见端口为 `/dev/ttyACM0` 或 `/dev/ttyUSB0`：
+Linux 常见串口是 `/dev/ttyACM0` 或 `/dev/ttyUSB0`：
 
 ```bash
 ls -l /dev/ttyACM* /dev/ttyUSB*
 ```
 
-用实际端口运行 Doctor：
+把实际端口交给 Doctor：
 
 ```bash
 python3 ~/.codex/skills/tirtc-esp32-builder/scripts/doctor.py \
   --expected-idf 5.5 \
   --target esp32s3 \
-  --project "$TIRTC_PROJECT_DIR" \
+  --project /absolute/path/my-esp32-device \
   --serial-port /dev/ttyACM0
 ```
 
-`serial port` 必须为 `PASS`。如果设备存在但无权限，按系统规范配置串口用户组并重新登录；不要用长期放宽所有设备权限的方式绕过。
-
-让 Skill 烧录时发起第二次、独立且明确的请求：
+`serial port` 为 `PASS` 后，再单独向 Skill 授权：
 
 ```text
 $tirtc-esp32-builder
 
-我确认目标芯片是 ESP32-S3，目标工程是 /absolute/path/my-esp32-device，
-目标串口是 /dev/ttyACM0。授权本轮烧录该设备并打开串口监视；
+我确认目标芯片是 ESP32-S3，工程是 /absolute/path/my-esp32-device，
+串口是 /dev/ttyACM0。授权本轮烧录该设备并打开串口监视。
 不要擦除其他串口设备，不要在日志中输出 Wi-Fi 密码或设备密钥。
 烧录后执行 L2 Boot 检查并更新 TIRTC_PORTING_REPORT.md。
 ```
 
-也可以人工执行：
+也可以人工烧录：
 
 ```bash
-cd "$TIRTC_PROJECT_DIR"
+cd /absolute/path/my-esp32-device
 idf.py -p /dev/ttyACM0 flash monitor
 ```
 
-ESP-IDF Monitor 中使用 `Ctrl+]` 退出。多个串口同时存在时，必须根据 USB 拔插、设备标识或芯片探测结果确认目标，不能选择第一个端口直接写入。
+使用 `Ctrl+]` 退出 ESP-IDF Monitor。多个串口同时存在时，需要通过 USB 拔插、设备标识或芯片探测确认目标，不能默认烧录第一个端口。
 
-WSL 不一定自动获得 USB 串口。Doctor 看不到端口时，先按 [Microsoft 的 WSL USB 连接说明](https://learn.microsoft.com/windows/wsl/connect-usb) 把目标设备附加到当前 WSL 实例，再重新运行串口检查。
+### Wi-Fi 凭证和设备绑定
 
-### 第 11 步：首次配网和绑定
+SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。SSID 和密码不应写死在源码中。
 
-固件首次启动且没有 Wi-Fi 配置时：
+无论选择哪种方法，都要有当前 PCB/BSP 的支持证据，凭证不能进入 Git、源码或报告，并且要保留清除或重配入口。没有 SoftAP、但支持工厂 NVS 注入的设备同样可以接入。只要工程提交了明文密码，Hardware IR v2 门禁就会判为 `BLOCKED`。
 
-1. 在手机或电脑连接 `TiRTC-Setup-XXXX`。
-2. 输入默认密码 `tirtc1234`。
-3. 打开 `http://192.168.4.1`，填写设备要连接的 Wi-Fi。
-4. 设备重启并联网后，在串口查看绑定验证码和体验平台地址。
-5. 登录体验平台，在设备绑定入口输入验证码。
-6. 回到串口输入 `status`，确认 platform、MQTT、TiRTC 均已就绪，runtime 处于 `waiting`。
+Wi-Fi 配网和 ThingConnect 设备绑定是两套独立流程。绑定可以选择验证码、工厂预绑定、开发凭证，或平台合同允许的 custom 方案。验收时要分开检查：
 
-也可以在串口输入：
+1. 没有 Wi-Fi 凭证时，设备进入选定的配网或注入流程。
+2. 已联网但尚未绑定时，设备进入选定的绑定流程；只有验证码方案需要显示验证码。
+3. NVS 已保存绑定时，日志应明确说明复用已有绑定并跳过首次绑定，不能据此判断“绑定流程缺失”。
+4. 分别验证只清设备绑定和只清 Wi-Fi 凭证的入口。
+5. `status` 确认 platform、MQTT、TiRTC 和 runtime 状态。
 
-```text
-wifi-set <ssid> <password>
-wifi-clear
-status
-restart
-```
+具体命令和 UI 由生成工程及所选方案决定，不能直接照搬另一块板。生产凭证、设备 secret 和 token 不得写入源码、脚本、Hardware IR、报告或 Git。
 
-`tirtc-set <device_id> <device_secret> [client_id]` 只用于受控底层联调。正常流程使用验证码绑定，真实凭证不能写入源码、脚本、报告或 Git。
+### 验证 H5 实时查看和对讲
 
-### 第 12 步：按层验收 H5 和 AI
+1. 串口 `status` 显示 runtime 为 `waiting`。
+2. 在体验平台打开该设备的实时查看入口。
+3. 确认所选 MJPEG/H.264/H.265 视频持续显示，音频和视频发送计数持续增长。
+4. 发起 H5 对讲，确认 stream 14 下行计数增长，实体扬声器可以听到声音。
+5. 触发浏览器重连或刷新请求，确认 MJPEG 提交下一张完整 JPEG，或 H.264/H.265 产生合同要求的刷新/关键帧，画面能够恢复。
 
-验收时不要跨级宣告成功。缺少账号、浏览器、服务、外网、板卡或仪器时，对应项记录为 `SKIP`，并写明补测条件。
+视频、声音和重连要分别保留证据。浏览器偶尔出现一帧，不能算作持续实时查看通过。
 
-| 层级 | 必须看到的证据 |
-|---|---|
-| L-1 Environment | Doctor 的必需项和项目构建契约通过 |
-| L0 Generate | 新工程和 Hardware IR 存在，未覆盖旧目录 |
-| L1 Build | `idf.py build` 成功并记录固件及 SHA-256 |
-| L2 Boot | 指定串口烧录成功，无 panic/反复重启 |
-| L3 Online | 配网、验证码绑定、MQTT、TiRTC 就绪 |
-| L4 Media | 摄像头、麦克风、扬声器本地路径和计数正常 |
-| L5 H5 | 浏览器持续收到声明的视频/音频，对讲到达设备扬声器 |
-| L6 AI | token、WHIP、`start_session`、双向音频、停止和 H5 恢复正常 |
-| L7 Stability | 按需求完成反复会话、弱网、资源和长稳测试 |
+### 验证 AI 对讲
 
-H5 验收：
+1. 先确认 H5 或其他会话没有占用媒体资源。
+2. 串口输入 `ai-start`，观察状态从 `ai-connecting` 进入 `ai-active`。
+3. 确认 `start_session` 成功后，设备才开始发送麦克风音频。
+4. 确认上行语音被 AI 接收，下行 AI 音频能从实体扬声器播放。
+5. 输入 `ai-stop`，确认发送 `end_session`，媒体任务停止，状态回到 `waiting`。
+6. 再次打开 H5，确认实时音视频可以重新连接。
 
-1. 串口 `status` 显示 runtime 为 `waiting`。
-2. 在体验平台打开该设备的实时查看入口。
-3. 确认 H.264 视频持续显示，音频/视频发送计数持续增长。
-4. 发起 H5 对讲，确认 stream 14 下行计数增长且实体扬声器可听。
-5. 触发浏览器重连或关键帧请求，确认板端编码器产生新的 IDR，画面恢复。
+如果产品使用实体按键启动 AI，会话状态和验收条件相同，只是触发方式从串口命令换成板级按键。
 
-AI 验收：
+### 分层验收
 
-1. 确认 H5/其他会话没有占用媒体资源。
-2. 串口输入 `ai-start`，观察状态从 `ai-connecting` 进入 `ai-active`。
-3. 确认只有 `start_session` 成功后才开始发送麦克风音频。
-4. 确认上行麦克风被 AI 接收，下行 AI 音频在扬声器播放。
-5. 输入 `ai-stop`，确认发送 `end_session`、媒体任务停止，状态回到 `waiting`。
-6. 再次打开 H5，确认 H5 可以重新连接并恢复音视频。
+每一层都要有独立证据。缺少硬件、账号、浏览器、服务或网络时，写 `SKIP`，并注明后续补测条件。
 
-### 第 13 步：检查最终交付物
+| 层级 | 通过条件 |
+|---|---|
+| L-1 Environment | Doctor 必需项和项目构建契约通过 |
+| L0 Generate | 新工程和 Hardware IR 存在，没有覆盖旧目录 |
+| L1 Build | `idf.py build` 成功，固件和 SHA-256 已记录 |
+| L2 Boot | 指定串口烧录成功，无 panic 或反复重启 |
+| L3 Online | 所选 Wi-Fi 凭证和设备绑定流程、MQTT 与 TiRTC 就绪 |
+| L4 Media | 摄像头、麦克风、扬声器的本地路径和计数正常 |
+| L5 H5 | 浏览器持续收到声明的音视频，下行对讲到达实体扬声器 |
+| L6 AI | token、WHIP、`start_session`、双向音频、停止和 H5 恢复正常 |
+| L7 Stability | 按需求完成反复会话、弱网、资源和长稳测试 |
 
-一次完整交付至少包含：
+一份完整交付通常包含：
 
-- 生成的 ESP-IDF 工程绝对路径；
-- `hardware-ir.json` 及每条关键事实的来源；
-- 能力评估结果和剩余阻塞项；
-- `build/` 中的固件产物及 SHA-256；
+- 生成工程的绝对路径；
+- `hardware-ir.json` 和关键事实来源；
+- 能力评估与剩余阻塞项；
+- 固件文件、构建命令、版本和 SHA-256；
 - 明确到芯片和串口的烧录记录；
 - 脱敏后的构建、启动和验收日志；
 - `TIRTC_PORTING_REPORT.md`；
-- L-1 到 L7 的 `PASS`、`FAIL` 或 `SKIP` 证据。
+- L-1 到 L7 的 `PASS`、`FAIL` 或 `SKIP`。
+
+任务只做到生成和编译时，报告应明确停在 L1。
+
+## 常见问题
+
+### 找不到 `node`、`npm` 或 `npx`
+
+安装 Node.js 18 或更高版本，重新打开终端，再检查：
+
+```bash
+node --version
+npm --version
+npx --version
+```
+
+### npm 使用了镜像源，提示 404 或找不到包
+
+查看当前 Registry：
+
+```bash
+npm config get registry
+```
+
+如果不是 `https://registry.npmjs.org/`，切回官方源后重试：
+
+```bash
+npm config set registry https://registry.npmjs.org/
+npm view tirtc-device-builder version
+```
+
+### `npm login` 提示无法打开浏览器
+
+普通使用者不需要登录 npm。直接执行：
 
-如果只完成生成和编译，报告应明确停在 L1；不能写成“Web 已出图”或“AI 对讲已完成”。
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install
+```
+
+`npm login` 只供维护者发布包，与安装公开包无关。
+
+### 输出 `OVERALL: NEEDS_SETUP`
+
+这表示只读检查发现环境尚未准备完整。按输出提示执行安装：
+
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install
+```
 
-### 一次成功检查清单
+### 提示缺少 `python3`、`git`、`bash` 或 `tar`
 
-开始下一阶段前逐项确认：
+安装器不会运行 `sudo`。请用当前系统的包管理器补齐这些命令，再执行 `setup esp32 --install`。安装可以续跑，已经完成的部分会被复用。
 
-- [ ] 板卡厂商、完整型号、模组、PCB 版本一致。
-- [ ] 原理图/BOM/BSP/数据手册路径均为绝对路径且可读。
-- [ ] Node.js 版本不低于 18，Skill 已安装并重启 Codex。
-- [ ] ThingConnect 生成器、TiRTC 头文件、静态库和构建契约存在。
-- [ ] 当前终端已激活 ESP-IDF 5.5.x 和 ESP32-S3 工具链。
-- [ ] 生成前 Doctor 的 `OVERALL` 为 `PASS`。
-- [ ] 所有请求能力均为 `READY_TO_PORT` 或 `HIL_VERIFIED`。
-- [ ] 输出目录不存在，旧工程未被覆盖。
-- [ ] 项目级 Doctor 的 `TiRTC build contract` 为 `PASS`。
-- [ ] `idf.py build` 成功，但尚未把它当作实机功能通过。
-- [ ] 烧录前已确认唯一串口并明确授权。
-- [ ] 配网、绑定、H5、AI 分层验收均保留脱敏证据。
-- [ ] 最终报告中的每个 `SKIP` 都有原因和最小下一步。
+### `idf.py not found`
 
-## 开发与验证
+当前终端没有激活 ESP-IDF。使用一键环境时执行：
+
+```bash
+source ~/.tirtc-device-builder/env.sh
+idf.py --version
+```
+
+使用已有 ESP-IDF 时执行它自己的 `export.sh`：
+
+```bash
+source /absolute/path/esp-idf/export.sh
+```
+
+### ESP-IDF 版本不是 5.5.x
+
+不要用错误版本继续编译预编译 SDK。让安装器使用新的托管目录，或明确传入正确版本：
+
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install \
+  --idf-dir /absolute/path/esp-idf-v5.5.4
+```
+
+如果指定目录已存在但内容不完整或版本错误，安装器会拒绝覆盖。换一个空的新路径，或先人工备份原目录。
+
+### 安装完成后 Codex 找不到 Skill
+
+关闭当前 Codex 会话并重新打开。再检查默认文件是否存在：
+
+```bash
+ls -l ~/.codex/skills/tirtc-esp32-builder/SKILL.md
+```
+
+设置过 `CODEX_HOME` 或 `--skills-dir` 时，要检查对应目录。不要同时把 Skill 安装到多个位置。
+
+### 已有 Skill，安装器拒绝覆盖
+
+安装器检测到本地已有 Skill，因此没有直接覆盖。确认可以替换后执行：
+
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install --force-skill
+```
+
+如果只使用 `install esp32` 子命令，对应选项是 `--force`。
+
+### Device Kit 下载失败
+
+确认能访问 npm 和 GitHub Release。受限网络中，可以在另一台机器下载公开 Release 附件，再传到开发机：
+
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install \
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.0.0.tar.gz
+```
+
+安装器会校验 SHA-256 和内部文件清单。如果校验不一致，请重新获取官方 Release 附件，不要跳过校验。
+
+### 提示 `refusing to overwrite incomplete directory`
+
+目标路径已经存在，但不是完整的 Device Kit 或 ESP-IDF。安装器不会删除或覆盖该目录。请先检查并备份，再改用新的 `--root` 或 `--idf-dir` 路径。
+
+### Doctor 报 `no sdkconfig or sdkconfig.defaults`
+
+典型输出是：
+
+```text
+FAIL TiRTC build contract [required]: no sdkconfig or sdkconfig.defaults in ...
+```
+
+`--project` 指向的目录还不是已生成的 ESP-IDF 工程，或者路径写错了。生成前不要传 `--project`；生成后确认工程中存在 `sdkconfig.defaults`，再运行项目级 Doctor。
+
+### `WARN serial discovery: no serial device detected`
+
+没有连接开发板时，这是正常警告，不影响生成和编译。烧录前必须让串口检查变成 `PASS`。
+
+设备已连接但没有权限时，按操作系统规范把当前用户加入串口用户组并重新登录。Ubuntu 常见用户组是 `dialout`。不要长期把串口权限放宽给所有用户。
+
+WSL 默认不一定能看到 USB 设备。按 [Microsoft WSL USB 连接说明](https://learn.microsoft.com/windows/wsl/connect-usb) 将设备附加到当前 WSL 实例，再运行 Doctor。
+
+### Hardware IR 一直是 `NEEDS_CONFIRMATION`
+
+先查看各个未知项要求什么来源。常见缺口包括准确的 PCB 版本、摄像头数据格式、所选视频 profile 的完整输出路径、Codec 时钟、功放使能脚、配网方法和可工作的厂商示例。不要从相似开发板复制管脚来填补这些信息。
+
+### 工程能编译，浏览器没有画面
+
+先确认摄像头输出是否真正进入选定的视频路径。MJPEG 要逐次提交完整 JPEG；H.264/H.265 要符合合同规定的 Annex-B、参数集和刷新帧行为。同时检查持续发送计数、丢帧和队列水位。Sensor 能输出 JPEG、RGB 或裸 YUV，不等于 H5 视频链路已经打通。
+
+### 工程能编译，但 H5 或 AI 没有声音
+
+分别检查上行和下行，不要把它们当成同一条链路：
+
+- 上行：麦克风、采样率、声道、G.711 A-law 编码、发送时机；
+- 下行：stream 14、队列边界、A-law 解码、I2S/Codec、功放使能、扬声器；
+- AI：`start_session` 成功后才发送音频，停止时清理旧 generation 数据；
+- 全双工：没有 AEC 和硬件证据时先验证半双工。
+
+### 原生 Windows 无法自动安装 ESP-IDF
+
+自动安装当前支持 Linux、WSL 和 macOS。原生 Windows 请使用 Espressif 官方安装器准备 ESP-IDF 5.5.x 和 ESP32-S3 工具链，再运行：
+
+```powershell
+npx --yes tirtc-device-builder@latest setup esp32
+```
+
+也可以在 WSL 中完成整个流程，但烧录前要先把 USB 设备连接到 WSL。
+
+## 使用边界
+
+### 必须克隆 `tirtc-server-example` 吗？
+
+不需要。普通开发所需的生成器、模板、协议文档、TiRTC 头文件和 `libTiRTC.a` 都在版本化的 ESP32 Device Kit 中。一键安装会下载公开 Release，并把路径写进 `env.sh`。
+
+`--thing-connect-root` 主要用于维护模板、协议或 Device Kit 的开发者复用完整源码工作区。
+
+### 为什么推荐 `npx`，不是安装一个 npm 包就结束？
+
+`npx` 适合运行低频的安装和诊断命令，也可以明确选择 `@latest`。全局 `npm install` 同样可用，但只负责安装 CLI。
+
+Skill、Device Kit 和 ESP-IDF 会写到 npm 包目录之外，也可能占用较多磁盘和下载时间，因此统一由显式命令 `setup esp32 --install` 安装。开发者可以提前看到安装计划和目标目录；以后卸载或升级 CLI，也不会误删开发环境。
+
+### 只给开发板型号能不能自动完成全部代码？
+
+可以先分析，但不能保证直接完成硬件移植。型号足以定位候选资料；GPIO、器件版本、所选视频 profile、音频时钟和配网能力仍需可信来源。资料不足时，Skill 会给出最小补充清单，不会拿相似板型的数据填空。
+
+### 能接入已有 ESP-IDF 工程吗？
+
+可以。把现有工程路径、目标芯片、ESP-IDF 版本、BSP 和已验证的外设示例交给 Skill。它会先检查组件、配置、SDK 构建合同和媒体接入边界，再决定复用哪些板级代码。
+
+### 生成的工程可以移走吗？
+
+可以。TiRTC SDK 会复制到工程的 `third_party/tirtc/`。移动后仍需在新机器上激活兼容的 ESP-IDF 5.5.x，并重新运行项目级 Doctor 和构建。
+
+### 能支持 ESP32 之外的芯片吗？
+
+仓库允许每个平台使用独立 Skill，但当前公开版本只实现 ESP32-S3。泰芯或其他平台需要新增 `skills/<platform-skill>/`，并分别维护 SDK、工具链、板级 adapter 和验收约束。
+
+## 给仓库维护者
+
+以下命令只供仓库维护者使用。
+
+### 本地验证
 
 ```bash
 npm ci --ignore-scripts
@@ -573,10 +817,9 @@ npm test
 npm pack --dry-run
 ```
 
-`npm pack --dry-run` 展示实际进入公开 tarball 的文件；发布前必须确认其中没有
-SDK 二进制、凭证、板卡私有资料、构建产物或用户媒体。
+`npm pack --dry-run` 用于核对公开 tarball。包内不应出现 Device Kit 二进制、设备凭证、板卡私有资料、构建产物或用户媒体。
 
-本地安装了 Codex 系统校验器时，还可以运行：
+本机安装了 Codex 系统校验器时，还可以运行：
 
 ```bash
 python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
@@ -585,20 +828,72 @@ python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
 python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
 ```
 
-## 增加新平台
+### 打包 ESP32 Device Kit
+
+```bash
+npm run pack:esp32-kit -- \
+  --source /absolute/path/tirtc-server-example/thing-connect \
+  --kit-version 1.0.0
+```
+
+输出位于 `dist/`：
+
+```text
+tirtc-esp32s3-kit-1.0.0.tar.gz
+tirtc-esp32s3-kit-1.0.0.tar.gz.sha256
+```
+
+校验后使用独立的 `kit-esp32s3-v<version>` 标签发布 GitHub Release：
+
+```bash
+gh --version
+gh release --help
+
+cd dist
+sha256sum -c tirtc-esp32s3-kit-1.0.0.tar.gz.sha256
+cd ..
+
+git tag -a kit-esp32s3-v1.0.0 -m "TiRTC ESP32-S3 Device Kit 1.0.0"
+git push origin kit-esp32s3-v1.0.0
+
+gh release create kit-esp32s3-v1.0.0 \
+  dist/tirtc-esp32s3-kit-1.0.0.tar.gz \
+  dist/tirtc-esp32s3-kit-1.0.0.tar.gz.sha256 \
+  --repo tangeai/tirtc-device-builder \
+  --verify-tag \
+  --latest=false \
+  --title "TiRTC ESP32-S3 Device Kit 1.0.0" \
+  --notes "ESP-IDF 5.5.x；TiRTC SDK 2.3.0；包含 H5/AI 工程生成资源。"
+```
+
+`gh release --help` 如果提示 `No such command 'release'`，当前系统安装的不是 GitHub 官方 CLI。先按 [GitHub CLI 官方安装说明](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) 安装或替换，再登录并发布 Release。
+
+### 发布 npm
+
+`package.json` 版本与 Git 标签必须一致。推送 `v<package-version>` 标签后，`.github/workflows/publish.yml` 通过 npm Trusted Publishing 发布：
+
+```bash
+npm test
+git tag -a v0.4.0 -m "v0.4.0"
+git push origin v0.4.0
+```
+
+不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。
+
+### 增加新平台
 
-每个平台使用 `skills/<platform-skill>/` 独立目录。新 Skill 需要：
+每个平台放在独立的 `skills/<platform-skill>/` 目录，并写清楚：
 
-- 明确芯片、SDK、工具链和不适用范围；
-- 使用来源可追溯的硬件事实，不从相似型号静默推断；
-- 把平台驱动隔离在板级 adapter，不复制 H5/AI 会话状态机；
-- 区分编译、烧录启动、设备上线、媒体链路和端到端业务验收；
-- 对下载、工具链安装、串口烧录和凭证写入保留明确授权边界。
+- 芯片、SDK、工具链和不适用范围；
+- Hardware IR 需要的事实和来源；
+- 板级媒体 adapter 与公共会话逻辑的边界；
+- 编译、启动、上线、媒体、业务和稳定性验收；
+- 下载、工具链安装、串口烧录和凭证写入的授权边界。
 
-共享逻辑只在两个以上平台出现相同不变量后抽取，避免形成只转发参数的公共层。
+等两个以上平台出现相同且稳定的约束后，再提取共享逻辑，避免公共层只做参数转发。
 
 ## 安全与许可证
 
-不要在 Issue、日志或报告中提交设备密钥、Wi-Fi 密码、MQTT/WHIP token、证书或用户音视频。安全问题按 [SECURITY.md](SECURITY.md) 私下报告。
+不要在 Issue、日志或报告中提交设备密钥、Wi-Fi 密码、MQTT/WHIP token、证书、生产配置或用户音视频。安全问题按 [SECURITY.md](SECURITY.md) 私下报告。
 
-本仓库源码使用 MIT License，见 [LICENSE](LICENSE)。ThingConnect、TiRTC SDK、ESP-IDF、厂商 BSP、芯片资料和其他第三方内容使用各自的许可证；本仓库许可证不会替代它们。
+本仓库源码使用 [MIT License](LICENSE)。ThingConnect、TiRTC SDK、ESP-IDF、厂商 BSP、芯片资料和其他第三方内容使用各自的许可证，本仓库许可证不会替代它们。版本差异见 [CHANGELOG.md](CHANGELOG.md)。