tirtc-device-builder 0.7.3 → 0.8.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 This project follows Semantic Versioning.
 
+## 0.8.1
+
+- Separate rapid `idf.py flash` iteration from portable evidence-bundle export,
+  so active development keeps the normal `build/` tree and does not require a
+  new multi-BIN archive for every device test.
+- Add deterministic ESP-IDF application-descriptor inspection for explicit
+  firmware versions, application-BIN SHA-256, and full ELF SHA-256 matching.
+- Add product-control rules that distinguish MCU buttons, boot straps, reset
+  lines and PMIC/power-latch keys across baseboard and battery-carrier variants,
+  and route button gestures through the runtime's intent queue.
+- Add trace-based diagnosis for repeated AI/H5 downlink audio across SDK
+  callbacks, bounded queues, playback, resampling, and codec/I2S writes.
+
+## 0.8.0
+
+- Add an evidence-backed board identity and curated registry workflow with exact,
+  probable and component-only matching plus reviewable knowledge candidates.
+- Extend Hardware IR and runtime contracts to model device-to-device calls and
+  WeChat VoIP against a pinned business-protocol revision and unified session
+  arbiter.
+- Make simultaneous capture/playback, a physical playback reference and enabled
+  AEC mandatory for AI intercom, device calls and WeChat VoIP at intake, build
+  and artifact-bound HIL assessment.
+- Add conditional ESP32-P4 target/SDK matching while retaining ESP32-S3 as the
+  managed generator path, and document simulator-first four-feature porting.
+
 ## 0.7.3
 
 - Make source export reject missing or Git-ignored Hardware IR, requested-feature

package/README.md

@@ -1,14 +1,14 @@
 # TiRTC Device Builder
 
-TiRTC Device Builder 用于把 ESP32-S3 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Codex Skill 会先检查环境、整理有依据的硬件事实，再生成独立的 ESP-IDF 工程并完成板级移植和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
+TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Codex Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立的 ESP-IDF 工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
 
 当前仓库提供一个 Skill：
 
 | Skill | 平台 | 主要用途 |
 |---|---|---|
-| `tirtc-esp32-builder` | ESP32-S3、ESP-IDF 5.5.x | 环境检查、Hardware IR、工程生成、板级媒体移植、编译、烧录和分层验收 |
+| `tirtc-esp32-builder` | ESP32-S3 / ESP32-P4、ESP-IDF 5.5.x | 板型识别、Hardware IR、工程生成/移植、H5/AI/设备互呼/微信 VoIP、AEC 门禁、编译烧录和分层验收 |
 
-开发者不需要克隆 `tirtc-server-example`，也不用登录 npm。工程模板、协议文档和 TiRTC SDK 已打包在独立的 ESP32 Device Kit 中，安装命令会自动下载并校验。
+H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立的 ESP32 Device Kit 中，安装时会自动下载并校验。设备互呼或微信 VoIP 的模拟/移植若超出当前 Kit 内容，则需要在用户授权后使用固定 commit 的 `tirtc-server-example` 完整仓库。ESP32-P4 必须使用匹配的 P4 SDK、BSP 与网络方案，不能复用 S3 预编译库。
 
 - npm 包：[tirtc-device-builder](https://www.npmjs.com/package/tirtc-device-builder)
 - GitHub 仓库：[tangeai/tirtc-device-builder](https://github.com/tangeai/tirtc-device-builder)
@@ -85,11 +85,12 @@ Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex
 - <原理图、BSP/厂商示例、数据手册或产品页；一行一个>
 
 目标：
-- 功能：<例如 H5 实时音视频、H5 对讲、AI 双向语音>
+- 功能：<例如 H5 实时音视频/对讲、AI 对讲、设备呼设备、微信 VoIP>
 - 平台/Web 视频：MJPEG、H264、H265
 - 板级视频选择：<MJPEG/H264/H265/根据硬件证据选择一种>
 - Wi-Fi：<指定方案/根据 BSP 选择>
 - 设备绑定：<指定方案/根据平台合同选择>
+- AEC：AI 对讲、设备呼设备、微信 VoIP 必须全双工并启用 AEC
 
 工程：<输出目录或现有工程的工作区相对路径>
 
@@ -110,6 +111,35 @@ H5 对讲和 AI 双向对讲。
 
 只有型号时，Skill 会先调查公开资料并列出缺口，不会猜测 GPIO、器件或媒体能力。要进入代码移植，通常还需要准确的板卡版本、原理图，以及能在实物上运行的 BSP 或外设示例。
 
+### 示例对话
+
+新板卡、先做资料评审：
+
+```text
+用户：$tirtc-esp32-builder
+      这是 XX 厂商 ESP32-S3 Camera Board Rev.B，资料在 boards/xx-revb/。
+      目标是 H5 音视频、AI 对讲、设备互呼和微信 VoIP；后三项必须 AEC。
+      先识别板型、生成 Hardware IR 并告诉我还缺什么，不烧录。
+
+Codex：我会先运行 Doctor，读取原理图/BSP/数据手册，生成 board identity，
+       查询已验证板型注册表；无法从 SoC 判断的 PCB 引脚仍保持未知。
+       随后分别评估四类业务能力，并对 AI/CALL/VOIP 强制检查全双工、
+       回采参考和 AEC，不满足时返回 BLOCKED，不自动降级半双工。
+```
+
+同板型复用并完成真机验证：
+
+```text
+用户：$tirtc-esp32-builder
+      使用 boards/identity.json 匹配已验证板型，工程输出到 ports/xx-revb。
+      允许构建和烧录 /dev/ttyACM0，验证 call 另一台设备和 wxcall。
+
+Codex：只有 exact identity 且 safe_registered_reuse=true 才复用板级包。
+       我会重新运行 runtime/audio/video 门禁、构建并绑定新 artifact SHA，
+       然后在该串口验证 AI、设备互呼、微信 VoIP 的 AEC/double-talk、
+       会话切换和重连；旧固件的 HIL 结果不会继承给新固件。
+```
+
 ## 工作范围
 
 整个流程从板卡资料核对开始，以分层验收报告结束：
@@ -121,7 +151,7 @@ H5 对讲和 AI 双向对讲。
       Hardware IR：硬件事实、来源和未知项
                   │
                   ▼
-       能力门禁：能否支持 H5 / AI
+       能力门禁：H5 / AI / CALL / VOIP / AEC
                   │
                   ▼
       独立 ESP-IDF 工程与板级媒体适配
@@ -138,13 +168,13 @@ Skill 负责：
 - 检查 Node.js 之外的 ESP-IDF、编译器、TiRTC SDK、工程配置和串口；
 - 从原理图、BSP、数据手册和实测示例中提取有来源的硬件事实；
 - 生成并校验 `hardware-ir.json`，把冲突和未知项留在报告里；
-- 判断视频、上行音频、下行播放和 AI 会话是否具备移植条件；
+- 判断视频、上行音频、下行播放、AI、设备互呼、微信 VoIP 与 AEC 是否具备移植条件；
 - 生成带 TiRTC SDK 的独立 ESP-IDF 工程；
 - 核验发现地址、SDK callback 生命周期、下行格式过滤和 AI 会话响应等运行协议不变量；
 - 把摄像头、所选 MJPEG/H.264/H.265 路径、麦克风、Codec、I2S、功放和按键接到板级 adapter；
 - 运行测试和 `idf.py build`，记录固件路径、版本和 SHA-256；
 - 在用户明确给出芯片、工程和串口后烧录；
-- 分别验证启动、上线、本地媒体、H5、AI 和稳定性；
+- 分别验证启动、上线、本地媒体、H5、AI、设备互呼、微信 VoIP、AEC/double-talk 和稳定性；
 - 输出 `TIRTC_PORTING_REPORT.md`，每一层都标成 `PASS`、`FAIL` 或 `SKIP`。
 
 ### Skill 不猜硬件
@@ -252,7 +282,7 @@ board-materials/
 | 支持自动安装的系统 | Linux、WSL、macOS |
 | 原生 Windows | 使用 Espressif 官方安装器准备 ESP-IDF，再重新运行检查 |
 
-当前生成器只支持 ESP32-S3。Flash 或 PSRAM 不是 16 MB / 8 MB 时，需要重新评估 `sdkconfig.defaults`、分区表、DMA 和媒体缓存预算。名称相近的芯片不会被自动当作 ESP32-S3 处理。
+当前托管自动生成器只提供 ESP32-S3 模板。ESP32-P4 可由 Skill 在已有、证据完整的 P4 BSP/工程上移植，但必须使用 `espressif-esp32p4` SDK、匹配的构建合同和明确的 ESP-Hosted 或以太网方案。Flash 或 PSRAM 容量变化时，需要重新评估 `sdkconfig.defaults`、分区表、DMA 和媒体缓存预算。
 
 ### 本机软件
 
@@ -288,7 +318,7 @@ H5 和 AI 的端到端验收还需要可访问的 ThingConnect 服务、可用
 
 ThingConnect 平台和 Web 播放端支持 MJPEG、H.264、H.265；具体开发板必须根据其有证据的媒体路径只选择一种输出 profile。MJPEG 提交完整 JPEG 帧；H.264/H.265 按合同提交 Annex-B access unit、参数集，并实现刷新或关键帧控制。某块板只能输出 MJPEG 不代表平台只支持 MJPEG。板上有摄像头 Sensor，只能证明图像有来源，不能证明浏览器一定能持续出图。
 
-当前音频基线使用 G.711 A-law、8 kHz、单声道。对讲还要有可靠的下行队列、A-law 解码、Codec/I2S/功放播放和会话停止清理。没有可用的全双工和 AEC 证据时，应按半双工设计 AI 对讲。
+当前音频基线使用 G.711 A-law、8 kHz、单声道。对讲还要有可靠的下行队列、A-law 解码、Codec/I2S/功放播放和会话停止清理。AI 对讲、设备互呼和微信 VoIP 强制要求全双工、真实播放参考和 AEC；没有证据时必须标记为 `BLOCKED`，不能自动降级为半双工。只有单独请求的 H5 talkback 可在产品合同明确允许时采用半双工。
 
 ## 安装方式和目录
 
@@ -519,7 +549,19 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/install_video_gate.py .
 idf.py build
 ```
 
-只安装实际请求能力的门禁。编译后把 BIN/ELF 的路径、大小和 SHA-256 写入 Hardware IR 的 `build_evidence.artifacts[]`，再运行 build 阶段评估。编译成功但语义门禁缺失或失败时只能记录 `COMPILE_PASS / CAPABILITY_BLOCKED`。
+只安装实际请求能力的门禁。编译后先核对固件内嵌版本、应用 BIN
+SHA-256 和完整 ELF SHA-256：
+
+```bash
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/firmware_identity.py \
+  build/<app>.bin --elf build/<app>.elf --expect-version <expected-version>
+```
+
+随后按
+[`firmware-delivery.md`](skills/tirtc-esp32-builder/references/firmware-delivery.md)
+选择快速真机迭代或可移植证据包；该文档也规定从 `build/` 记录迁移到
+`artifacts/` 时如何保持 Hardware IR 和报告一致。编译成功但语义门禁缺失
+或失败时只能记录 `COMPILE_PASS / CAPABILITY_BLOCKED`。
 
 生成器会把 TiRTC SDK 复制到工程的 `third_party/tirtc/`。此后工程不再依赖 `tirtc-server-example`，但换机编译仍需准备兼容的 ESP-IDF 5.5.x 工具链。
 
@@ -569,7 +611,10 @@ cd /absolute/path/my-esp32-device
 idf.py -p /dev/ttyACM0 flash monitor
 ```
 
-使用 `Ctrl+]` 退出 ESP-IDF Monitor。多个串口同时存在时，需要通过 USB 拔插、设备标识或芯片探测确认目标，不能默认烧录第一个端口。
+普通开发烧录优先使用这一条命令，让 ESP-IDF 从当前构建目录解析
+bootloader、分区表和应用镜像；无需手工维护多条 `esptool.py` 地址参数。
+使用 `Ctrl+]` 退出 ESP-IDF Monitor。多个串口同时存在时，需要通过 USB
+拔插、设备标识或芯片探测确认目标，不能默认烧录第一个端口。
 
 ### Wi-Fi 凭证和设备绑定
 
@@ -621,7 +666,7 @@ Wi-Fi 配网和 ThingConnect 设备绑定是两套独立流程。绑定可以选
 | L3 Online | 所选 Wi-Fi 凭证和设备绑定流程、MQTT 与 TiRTC 就绪 |
 | L4 Media | 摄像头、麦克风、扬声器的本地路径和计数正常 |
 | L5 H5 | 浏览器持续收到声明的音视频，下行对讲到达实体扬声器 |
-| L6 AI | token、WHIP、`start_session`、双向音频、停止和 H5 恢复正常 |
+| L6 AI/CALL/VOIP/AEC | AI、设备互呼、微信 VoIP 的双向音频、AEC/double-talk、停止/超时和 H5 恢复分别通过 |
 | L7 Stability | 按需求完成反复会话、弱网、资源和长稳测试 |
 
 一份完整交付通常包含：
@@ -782,7 +827,7 @@ WSL 默认不一定能看到 USB 设备。按 [Microsoft WSL USB 连接说明](h
 - 上行：麦克风、采样率、声道、G.711 A-law 编码、发送时机；
 - 下行：stream 14、队列边界、A-law 解码、I2S/Codec、功放使能、扬声器；
 - AI：`start_session` 成功后才发送音频，停止时清理旧 generation 数据；
-- 全双工：没有 AEC 和硬件证据时先验证半双工。
+- 全双工：AI、设备互呼和微信 VoIP 缺少回采参考或 AEC 证据时直接阻塞；仅 H5 talkback 可按明确的产品合同验证半双工。
 
 ### 原生 Windows 无法自动安装 ESP-IDF
 
@@ -822,7 +867,7 @@ Skill、Device Kit 和 ESP-IDF 会写到 npm 包目录之外，也可能占用
 
 ### 能支持 ESP32 之外的芯片吗？
 
-仓库允许每个平台使用独立 Skill，但当前公开版本只实现 ESP32-S3。泰芯或其他平台需要新增 `skills/<platform-skill>/`，并分别维护 SDK、工具链、板级 adapter 和验收约束。
+仓库允许每个平台使用独立 Skill。当前公开 Skill 覆盖 ESP32-S3，并支持在证据完整的已有工程上移植 ESP32-P4；托管一键生成仍是 S3。泰芯或其他平台需要新增 `skills/<platform-skill>/`，并分别维护 SDK、工具链、板级 adapter 和验收约束。
 
 ## 给仓库维护者
 
@@ -881,8 +926,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.7.3 -m "v0.7.3"
-git push origin v0.7.3
+git tag -a v0.8.1 -m "v0.8.1"
+git push origin v0.8.1
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/tirtc-device-builder.js

@@ -38,6 +38,7 @@ Usage:
   tirtc-device-builder install <platform> [--skills-dir <path>] [--force]
   tirtc-device-builder setup <platform> [setup options]
   tirtc-device-builder doctor <platform> [doctor options]
+  tirtc-device-builder boards <platform> <list|validate|match|init-identity|candidate> [options]
   tirtc-device-builder --version
 
 Platforms:
@@ -49,6 +50,7 @@ Examples:
   npx tirtc-device-builder setup esp32 --install
   npx tirtc-device-builder install esp32 --skills-dir /absolute/path/skills
   npx tirtc-device-builder doctor esp32 --project /absolute/path/project
+  npx tirtc-device-builder boards esp32 match --identity ./board-identity.json
 
 Install defaults to ${"$"}{CODEX_HOME:-~/.codex}/skills. Existing skills are
 preserved unless --force is explicitly supplied. Setup checks are read-only;
@@ -175,6 +177,28 @@ function runDoctor(platform, args) {
   return Number.isInteger(result.status) ? result.status : 1;
 }
 
+function runBoardRegistry(platform, args) {
+  const script = join(
+    PACKAGE_ROOT,
+    "skills",
+    platform.skill,
+    "scripts",
+    "board_registry.py",
+  );
+  if (!existsSync(script)) {
+    return fail(`package is missing board registry script for ${platform.name}`);
+  }
+
+  const python = process.env.PYTHON || "python3";
+  const result = spawnSync(python, [script, ...args], {
+    stdio: "inherit",
+  });
+  if (result.error) {
+    return fail(`could not run ${python}: ${result.error.message}`);
+  }
+  return Number.isInteger(result.status) ? result.status : 1;
+}
+
 function main(args) {
   if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
     printHelp();
@@ -192,7 +216,12 @@ function main(args) {
   }
 
   const [command, identifier, ...rest] = args;
-  if (command !== "install" && command !== "doctor" && command !== "setup") {
+  if (
+    command !== "install" &&
+    command !== "doctor" &&
+    command !== "setup" &&
+    command !== "boards"
+  ) {
     return fail(`unknown command: ${command}; run with --help`);
   }
   if (!identifier) {
@@ -206,6 +235,9 @@ function main(args) {
   if (command === "doctor") {
     return runDoctor(platform, rest);
   }
+  if (command === "boards") {
+    return runBoardRegistry(platform, rest);
+  }
   if (command === "setup") {
     if (platform.name !== "esp32") {
       return fail(`setup is not available for platform: ${platform.name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "Install and run TiRTC device-development skills for Codex.",
   "license": "MIT",
   "author": {

package/skills/tirtc-esp32-builder/SKILL.md

@@ -1,43 +1,154 @@
 ---
 name: tirtc-esp32-builder
-description: Check or set up ESP-IDF, then generate, port, build, flash, and validate ThingConnect TiRTC ESP32 projects from a board model, schematic, BSP, pin map, or peripheral examples when H5 live view/talkback or AI intercom is requested. Use for environment diagnosis, supported-board generation, and new-board hardware intake; exclude Linux device-sim-c and server-only work.
+description: Identify, generate, port, build, flash, validate, and capture reusable knowledge for TiRTC ESP32-S3 or ESP32-P4 boards from a model, schematic, BSP, pin map, peripheral examples, or an existing ESP-IDF project. Use for H5 live view/talkback, AI intercom, device-to-device calls, WeChat VoIP, board detection, memory/AEC bring-up, or reusable board registration; exclude server-only work and unrelated embedded projects.
 ---
 
-# TiRTC Embedded Builder
-
-Turn board evidence into an evidence-backed ESP-IDF project. Treat the Hardware IR as the single handoff between probabilistic document extraction and deterministic capability, generation, build, and verification steps.
-
-## Start
-
-1. Read this Skill's `VERSION` file and [environment.md](references/environment.md). Record the `VERSION` value as the installed Skill version; never infer it from the prompt or an npm command run elsewhere. For a first-time setup or a request to check/install prerequisites, prefer `npx tirtc-device-builder@latest setup esp32`. Run its `--install` mode only when the user explicitly authorizes installation at the displayed destinations. The installer may create user-space files but never grants permission for `sudo` or persistent shell-profile edits.
-2. Locate the versioned ESP32 Device Kit root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, the managed setup configuration, or workspace discovery. For a managed Kit, read `manifest.json`, require its exact expected `kit_version`, and treat its manifest and packaged protocol documents as generation facts. An older but structurally complete Kit is not compatible. If the user explicitly supplies an unversioned full ThingConnect source workspace, treat it as legacy input and also read its applicable `AGENTS.md`.
-3. Run the Doctor through the managed environment helper when one exists; otherwise run `python3 <skill-dir>/scripts/doctor.py --expected-idf 5.5 --target esp32s3`. Add `--expected-kit <kit-version> --require-workspace` for managed-Kit generation; a self-contained generated project can instead resolve its bundled SDK through `--project`. Resolve every required failure before claiming build readiness.
-4. Read [workflow.md](references/workflow.md). Select the registered-board, new-board intake, or existing-project branch. The branch is selected when every supplied artifact has been accounted for and the exact board revision is known or explicitly unresolved.
-5. Read [hardware-ir.md](references/hardware-ir.md) when a Hardware IR must be created or updated. New intake uses schema v2; schema v1 remains readable for existing H.264 projects. Record a source and verification level for every hardware fact that affects a requested feature.
-6. Run `python3 <skill-dir>/scripts/hardware_ir.py validate <hardware-ir.json>` and then `assess --phase intake --strict`. `READY_TO_PORT` means the evidence is sufficient to design the adapter without guessing wiring or changing an unapproved public contract; it does not require a final ELF or runtime measurements.
-
-Before stopping on `NEEDS_CONFIRMATION`, classify every unresolved fact as `source_resolvable`, `implementation_resolvable`, `build_resolvable`, `hil_resolvable`, or `user_blocked`. Resolve source facts by inspection. For implementation/build facts, record the evidenced design plan at `corroborated`, generate a compile-safe adapter, and verify it at L1. Defer HIL-only measurements to L2-L7 when hardware access is unavailable. Stop before implementation only for `user_blocked` facts such as unknown wiring or identity, a missing product choice, an unavailable SDK, or a required public-contract change.
-
-## Build the project
-
-Run `<device-kit-root>/device-sim/scripts/create_esp32_project.py` for the current ESP32-S3 H5/AI starter. Keep ThingConnect onboarding, H5, AI, TiRTC lifecycle, callback, stream, and generation behavior in the existing deep modules. Put board-specific camera, microphone, encoder, codec, amplifier, GPIO, DMA, and task behavior behind the `starter_media` seam or a board media adapter owned by it.
-
-Before changing media code, read [capability-rules.md](references/capability-rules.md) and [porting-risks.md](references/porting-risks.md), then read the repository documents they route to. For requested audio, read [audio-contract.md](references/audio-contract.md); for requested video, read [video-contract.md](references/video-contract.md); for any H5 or AI project, read [runtime-contract.md](references/runtime-contract.md). Complete every applicable project-local semantic gate. Treat platform/Web codec support and board codec selection as separate facts: the current platform contract accepts MJPEG, H.264, and H.265, while each board contract selects exactly one evidenced output profile. A camera sensor alone does not establish H5 video support. Choose half duplex for AI when the supplied hardware and BSP do not establish a usable full-duplex/AEC path.
-
-Keep the Skill board-agnostic. The prompt supplies product intent and artifact locations; Hardware IR stores evidence; the generated board adapter owns concrete sensors, codecs, pins, clocks, slots, DMA, and task allocation. Never add one board's values to Skill defaults to make an assessment pass.
-
-Run focused tests before ESP-IDF build. Resolve the TiRTC SDK target and `manifest/build-contract.env` against the generated `sdkconfig`; a mismatched precompiled SDK is a blocked build, not a code-generation problem. Resolve managed components with `idf.py reconfigure`, then validate and install every applicable audio, video, and runtime contract gate. The runtime gate is mandatory for generated H5/AI projects and must prove service-endpoint wiring, deferred lifecycle operations, exact stream/media filtering, AI response validation, and remote `end_session` handling. A value copied from a “typical” header comment or a different sample rate is not clock evidence. A self-declared camera realtime or memory boolean is not video evidence.
-
-After a successful build, promote only facts actually established by source, compile, semantic, or post-link gates to `build_verified`. Copy the final BIN/ELF needed for delivery into a project-relative `artifacts/` directory, record the actual file path, byte size, and SHA-256 under `build_evidence.artifacts[]`, and run `hardware_ir.py assess --phase build --project <project> --artifact-sha256 <sha256> --strict`. The assessment reopens the recorded file and rejects a missing, stale, size-mismatched, or hash-mismatched artifact. A design plan at `corroborated` can pass intake but cannot pass the build phase. Report a successful compiler invocation as `COMPILE_PASS` when any requested feature gate is blocked; project-wide `BUILD_VERIFIED` requires every requested feature to pass.
-
-## Flash and verify
-
-Flash only when the user requested hardware mutation and the exact serial port and chip have been resolved. When more than one candidate device exists, obtain the target choice before writing. Keep credentials outside generated files and redact device keys, Wi-Fi passwords, MQTT/WHIP tokens, and user media from logs and reports.
-
-Read [reporting.md](references/reporting.md) before end-to-end verification. Report every acceptance level as `PASS`, `FAIL`, or `SKIP`, with commands and evidence. Bind HIL observations to the exact firmware SHA-256 with `assess --phase hil --artifact-sha256`; an older artifact cannot verify a newer build. A build-only result is not H5 or AI completion; missing hardware, browser, account, service, or network evidence remains an explicit `SKIP` or blocker.
-
-For HIL assessment, run `hardware_ir.py assess --phase hil --artifact-sha256 <sha256> --strict`. The HIL phase first requires build-verified paths, then promotes only features whose L5/L6 runtime evidence matches that exact artifact.
-
-## Finish
-
-After the final assessment, remove the machine-bound `build/` tree without rebuilding, then run `project_portability.py <project> --export` against the source plus the project-relative `artifacts/` copies. Resolve every missing or Git-ignored required input reported by that check; local intermediate artifacts may remain ignored, but retained build evidence must survive export. Return the generated project path, Hardware IR, capability assessment, build artifacts, flash record when applicable, and `TIRTC_PORTING_REPORT.md`. The task is complete only when every requested feature is either verified at the requested level or named as a blocker with the smallest next action that can resolve it.
+# TiRTC ESP32 Builder
+
+Turn board evidence into a verified ESP-IDF product port. Hardware IR is the
+handoff from probabilistic document extraction to deterministic generation and
+gates. The curated board registry preserves reusable results without treating a
+past build as proof for a new artifact.
+
+## 1. Establish the platform and inputs
+
+1. Read this Skill's `VERSION`, then read [environment.md](references/environment.md),
+   [workflow.md](references/workflow.md), and
+   [TiRTC platform contract](references/tirtc-platform.md). Record the installed
+   Skill version rather than inferring it from a prompt or npm output.
+2. Freeze the requested product features independently: H5 live audio/video and
+   talkback, AI intercom, device-to-device calling, and WeChat VoIP. Do not
+   silently remove a requested feature because the current starter lacks it.
+3. Resolve a versioned source of truth. The managed ESP32-S3 Device Kit is the
+   default for its packaged capabilities. Device-call/WeChat simulation or
+   protocol porting requires a pinned full `tirtc-server-example` checkout when
+   those sources are absent from the selected Kit. Clone or download it only
+   when the user authorizes that external write. Read applicable repository
+   instructions and the exact business documents routed by `workflow.md`.
+4. Run Doctor for the exact target and SDK package. Managed generation currently
+   automates ESP32-S3. ESP32-P4 is valid only with an evidenced P4 BSP/network
+   path and the matching `espressif_esp32p4` SDK/build contract; never link the
+   S3 archive into a P4 image.
+
+## 2. Identify the board and query knowledge
+
+Read [board-knowledge.md](references/board-knowledge.md). Combine developer-
+declared vendor/model/PCB revision with safe observations such as SoC, module,
+Flash/PSRAM, camera PID and codec IDs. The SoC cannot determine carrier-board
+wiring or PCB revision by itself.
+
+Run `board_registry.py match` before selecting a workflow branch. Only an exact
+identity with `safe_registered_reuse=true` selects the registered-board branch.
+A probable match supplies hypotheses; a component match supplies only component
+lessons. Any identity conflict creates a new variant and keeps concrete GPIO,
+clock, DMA and task values unresolved.
+
+## 3. Prove the business flows before board porting
+
+When device-call or WeChat VoIP is requested, first build and run the pinned
+Linux C simulator with file-backed media. Verify the requested H5, AI, `call
+<device_id> [video|audio]`, and `wxcall [N] [video|audio]` paths plus accept,
+reject, cancel, hangup, timeout and recovery behavior. This establishes the
+business protocol and state model; it does not verify ESP32 hardware.
+
+Preserve one process-wide TiRTC lifecycle and one unified Router → Arbiter →
+Coordinator path. STREAM is the H5 baseline; VOIP, AI and CALL are foreground
+owners unless the product contract explicitly proves parallel resources.
+Callbacks enqueue bounded events. A single state-owning task handles HTTP,
+MQTT, connection lifecycle, generation checks and monotonic deadlines.
+
+## 4. Create and assess Hardware IR
+
+For a new or changed board, read [hardware-ir.md](references/hardware-ir.md),
+create schema v2, validate it, and run strict intake assessment. Record a source
+and verification level for every identity, pin, clock, slot, media, memory,
+onboarding and business fact. Keep contradictions and unknowns explicit.
+
+Classify unresolved facts as `source_resolvable`, `implementation_resolvable`,
+`build_resolvable`, `hil_resolvable`, or `user_blocked`. Resolve all safe source,
+implementation and build facts. Stop before code only for a genuine user choice,
+unknown wiring/identity, unavailable matching SDK, or required public-contract
+change.
+
+## 5. Generate and port
+
+Generate a new project without overwriting an existing path. Keep platform
+onboarding, MQTT, TiRTC lifecycle, session routing/arbitration and stream
+contracts in stable modules. Put camera, microphone, encoder, codec, amplifier,
+GPIO, DMA, AEC and realtime task behavior behind `starter_media` or its board
+adapter.
+
+Treat AEC as mandatory for `ai_talk`, `device_call`, and `wechat_voip`. Do not
+certify those features through a half-duplex fallback. Hardware IR must prove
+simultaneous capture/playback, a physical playback-reference path, and an
+available AEC implementation. The build gate must additionally prove
+`shared_clock.directions_simultaneous=true` and
+`echo_cancellation.enabled=true`; otherwise the affected feature is `BLOCKED`.
+H5 talkback alone may remain half-duplex only when the requested product
+contract explicitly permits it.
+
+Follow the lifecycle from the locked C header: configure pre-init-only options
+such as `TIRTC_OPT_MAX_SEND_BUFFER`, call `TiRtcInit()`, set the device secret and
+client ID from an untracked runtime source, call `TiRtcStart()`, and wait for
+`TIRTC_EVENT_SYS_STARTED`. `TiRtcStart()` returning zero is not readiness.
+
+Before media work, read [capability-rules.md](references/capability-rules.md) and
+[porting-risks.md](references/porting-risks.md). For requested audio, video or
+H5/AI/call runtime behavior, read and install the applicable semantic contracts.
+Keep concrete board values in Hardware IR, contracts and adapter files rather
+than Skill defaults.
+
+When the product request includes a physical button, touch input, reset, power
+key, wake source or enclosure label, read
+[product-controls.md](references/product-controls.md). Treat the exact physical
+product as baseboard plus any carrier, PMIC and enclosure controls. Board input
+code emits bounded intents to the state-owning runtime; it does not own session
+lifecycle.
+
+## 6. Build and assess
+
+Read [firmware-delivery.md](references/firmware-delivery.md) and select
+`development flash` or `evidence bundle` from the user's current goal. Run
+focused tests, resolve managed components, validate the exact SDK
+`manifest/build-contract.env`, install every applicable semantic gate, then run
+the ordinary ESP-IDF build. Requested call/VoIP features must be represented by
+the runtime/business contract and the unified arbiter implementation; an H5/AI-
+only starter cannot reach `BUILD_VERIFIED` for those features.
+
+Set an explicit firmware version, verify the application descriptor and full
+ELF identity with `firmware_identity.py`, and record the application-BIN hash
+with its exact label. Follow the selected delivery mode's artifact paths and
+retention rules, record actual size and SHA-256 in Hardware IR, then run strict
+build assessment with `--project` and that exact hash. Compiler success with a
+missing feature gate is `COMPILE_PASS`, not product completion.
+
+## 7. Flash, verify, and learn
+
+Flash only with explicit authorization and an exact serial target. Read
+[reporting.md](references/reporting.md). Record every level as PASS, FAIL or SKIP
+and bind HIL observations to the exact artifact SHA-256. Verify local media,
+H5, AI, device-call, WeChat VoIP, AEC/double-talk when requested, recovery,
+weak-network behavior and stability separately.
+
+For every AEC-required flow, run speaker-active near-end speech, far-end-only,
+double-talk, rapid session switching and reconnect cases. Watchdog survival or
+clean audio in one mode cannot substitute for these per-mode observations.
+
+After assessment, generate a project-local board-knowledge candidate. Promotion
+is a reviewed repository change: classify lessons as generic, component or exact
+board; attach artifact evidence; add regression tests for generic invariants;
+then publish a new Skill/registry version. Never let an installed Skill mutate
+itself from conversation history.
+
+Complete the selected mode's retention or export checks from
+`firmware-delivery.md`. Return the project, Hardware IR, identity match,
+capability result, exact artifacts, flash command when applicable, and report.
+
+## Security boundary
+
+Keep AccessKey, SecretKey, device keys, Wi-Fi passwords, MQTT/WHIP tokens,
+certificates, MAC-derived identifiers and user media outside source, prompts,
+registries and reports. Inject secrets through an untracked configuration,
+provisioning store, secure NVS or a product keystore. Redact logs. Installation,
+cloning, flashing, erasing NVS, browser/account use and registry promotion each
+retain their own authorization boundary.

package/skills/tirtc-esp32-builder/USAGE.md

@@ -20,7 +20,8 @@ $tirtc-esp32-builder
 资料：
 - <原理图、BSP/厂商示例、数据手册和产品页；一行一个>
 
-目标：<H5 实时音视频、H5 对讲、AI 双向语音等>
+目标：<H5 实时音视频/对讲、AI 对讲、设备互呼、微信 VoIP>
+AEC：AI、设备互呼、微信 VoIP 必须全双工并启用 AEC
 视频：<MJPEG/H264/H265/根据证据选择>
 Wi-Fi 与设备绑定：<指定方案/根据 BSP 和平台合同选择>
 工程：<输出目录或现有工程的绝对路径>
@@ -53,7 +54,7 @@ $tirtc-esp32-builder 分析 <厂商> <型号> <硬件版本>，目标是 H5 实
 提供本地资料：
 
 ```text
-$tirtc-esp32-builder 使用原理图 /path/board.pdf、BSP /path/vendor-project 和一键安装的 Device Kit，为该板生成 TiRTC H5/AI ESP-IDF 工程并编译。
+$tirtc-esp32-builder 使用原理图 /path/board.pdf、BSP /path/vendor-project 和一键安装的 Device Kit，为该板生成 TiRTC H5/AI/CALL/VOIP ESP-IDF 工程并编译；AI/CALL/VOIP 必须通过 AEC 门禁。
 ```
 
 完整实机流程：
@@ -101,6 +102,20 @@ python3 <skill-dir>/scripts/hardware_ir.py assess --phase hil \
 
 `init` 默认创建 schema v2；v1 仅用于兼容已有 H.264 IR。`BLOCKED` 表示资料已确认硬件/合同/资源或凭证策略不满足；`NEEDS_CONFIRMATION` 表示当前阶段仍有未知项或证据不足；`READY_TO_PORT` 表示可以生成并实现板级适配；`BUILD_VERIFIED` 表示精确 artifact 已通过源码、编译和 post-link 门禁；`HIL_VERIFIED` 还要求同一 SHA-256 的 L5/L6 运行证据。
 
+## 固件身份与烧录方式
+
+顶层 `CMakeLists.txt` 应在 `project()` 前设置明确的 `PROJECT_VER`。编译后
+核对应用 BIN 中的版本和完整 ELF SHA-256：
+
+```bash
+python3 <skill-dir>/scripts/firmware_identity.py build/<app>.bin \
+  --elf build/<app>.elf --expect-version <expected-version>
+```
+
+按 [firmware-delivery.md](references/firmware-delivery.md) 选择快速真机迭代或
+可移植证据包；模式转换时必须同步迁移 Hardware IR 与报告中的 artifact
+路径。普通开发烧录命令为 `idf.py -p <exact-port> flash monitor`。
+
 ## 当前边界
 
 ThingConnect 仓库提供 ESP32-S3 H5/AI 模板和生成器，但默认媒体适配器不包含特定开发板的摄像头、麦克风、选定视频路径、Wi-Fi 凭证方法和扬声器驱动。模板生成和编译成功只证明工程与协议骨架可用，不代表 Web 已经出图或 AI 音频已经通过实机验收。

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.7.3
+0.8.1

package/skills/tirtc-esp32-builder/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "TiRTC ESP32 Builder"
   short_description: "从开发板资料生成并验证 TiRTC ESP32 固件"
-  default_prompt: "Use $tirtc-esp32-builder to analyze my ESP32 board materials and build a TiRTC H5 live-view and AI intercom project."
+  default_prompt: "Use $tirtc-esp32-builder to identify my ESP32 board and build an evidence-backed TiRTC H5, AI, device-call, or WeChat VoIP project with mandatory AEC for duplex sessions."

package/skills/tirtc-esp32-builder/assets/board-audio-contract.example.json

@@ -43,6 +43,9 @@
     "paired_channels": false,
     "handoff": "release_before_claim"
   },
+  "echo_cancellation": {
+    "enabled": false
+  },
   "implementation_assertions": [
     {
       "file": "components/starter_media/src/starter_media.c",

package/skills/tirtc-esp32-builder/assets/board-identity.example.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": 1,
+  "declared": {
+    "vendor": null,
+    "model": null,
+    "hardware_revision": null
+  },
+  "observed": {
+    "target": null,
+    "module": null,
+    "flash_mb": null,
+    "psram_mb": null,
+    "components": [],
+    "probes": []
+  }
+}

package/skills/tirtc-esp32-builder/assets/developer-intake-prompt.md

@@ -20,10 +20,10 @@ $tirtc-esp32-builder
 - <原理图、BSP/厂商示例、数据手册、产品页等工作区相对路径或固定链接；一行一个>
 
 目标：
-- <例如：H5 实时视频和声音、H5 语音对讲、AI 双向语音对讲>
+- <例如：H5 实时音视频/对讲、AI 对讲、设备呼设备、微信 VoIP>
 - 平台/Web 视频能力：<例如 MJPEG、H264、H265；按平台合同填写>
 - 板级视频选择：<MJPEG/H264/H265/根据硬件证据选择一种>
-- 双工或 AEC 的硬要求：<无，初版可半双工/必须全双工或 AEC/未知>
+- 双工或 AEC 的硬要求：AI 对讲、设备呼设备、微信 VoIP 必须全双工并启用 AEC；仅 H5 对讲是否允许半双工：<是/否>
 
 接入方式：
 - Wi-Fi：<选择一种，或写“根据 BSP 选择”>
@@ -37,7 +37,7 @@ $tirtc-esp32-builder
 2. 把每个未知项标为 source_resolvable、implementation_resolvable、build_resolvable、hil_resolvable 或 user_blocked。先通过资料和固定版本源码解决 source_resolvable；只有 user_blocked 会阻止开始 adapter 开发。
 3. READY_TO_PORT 表示硬件身份、连接、媒体合同和资源设计已经有证据，足以开始实现；它不要求最终 ELF 或实机数据。可通过实现或构建解决的项目必须继续生成 compile-safe adapter、锁定依赖、运行门禁并编译。
 4. 移植前核对平台媒体合同、板级选择、板级资源、静态内存预算、配网和绑定状态。音频工程必须生成项目内 `board-audio-contract.json`，在依赖解析后核验每个 codec 的 `(MCLK, sample rate)` 表、I2S mode/controller、TDM slot/物理信号和共享 GPIO handoff；视频工程必须生成项目内 `board-video-contract.json` 并引用 `platform-media-contract.json`，分别证明平台可接受的 profiles 与该板选中的唯一 profile，再核验锁定 camera 组件、传感器白名单、Wi-Fi/camera CPU 隔离、完整帧边界、frame buffers、TiRTC send buffer 和 backpressure。
-5. 所有 H5/AI 工程必须生成 `tirtc-runtime-contract.json`，核验服务发现 endpoint 确实传给 SDK、callback 内不直接调用生命周期 API、下行 stream/media 精确过滤、AI 响应格式和远端 `end_session`。runtime、audio、video 三类适用门禁都要接入普通 `idf.py build`。`resolved=true`、`pipeline_safe=true` 或编译成功不能替代门禁。
+5. 所有 H5/AI/设备呼叫/微信 VoIP 工程必须生成 `tirtc-runtime-contract.json`，核验服务发现 endpoint 确实传给 SDK、callback 内不直接调用生命周期 API、下行 stream/media 精确过滤、AI 响应格式、远端 `end_session` 和统一会话仲裁。设备呼叫/微信 VoIP 还要固定业务协议 revision 并校验 endpoint、MQTT 事件和 `call`/`wxcall` 命令。AI、设备呼叫和微信 VoIP 必须在 Hardware IR 中证明同时采集播放、真实回采参考与可用 AEC，并由 `board-audio-contract.json` 证明 `directions_simultaneous=true`、`echo_cancellation.enabled=true`；缺任一项直接 BLOCKED，不得自动降级半双工。runtime、audio、video 三类适用门禁都要接入普通 `idf.py build`。`resolved=true`、`pipeline_safe=true` 或编译成功不能替代门禁。
 6. 将最终 BIN/ELF 复制到项目内 `artifacts/`，记录真实相对路径、大小和 SHA-256，将所评估的 SHA 写入 Hardware IR 的 `build_evidence.artifacts[]`，再使用 `--project` 运行 build 阶段评估并输出 TIRTC_PORTING_REPORT.md。评估后移除机器绑定的 `build/`，运行 `project_portability.py --export`，不得再次构建。区分 `COMPILE_PASS`、请求能力 `BUILD_VERIFIED` 和 L2-L7 实机验收。
 7. 本轮不访问串口、不烧录、不擦除 NVS；因此缺少启动、浏览器、实体声音和运行时资源数据时，把相应 L2-L7 标为 SKIP，不得阻止 L0/L1。
 8. Wi-Fi 密码、设备密钥、token、私钥和用户音视频不能写入工程或报告。