tirtc-device-builder 0.9.6 → 0.10.0

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 This project follows Semantic Versioning.
 
+## 0.10.0
+
+- Align the Kit's provisioning and device-binding implementation with the
+  reference XiaoTai product firmware (ships in the ESP32-S3 Device Kit
+  1.2.0 release, tagged separately):
+  - Wi-Fi provisioning: the embedded setup page gains a live scan list
+    (`POST /api/scan`, `GET /api/networks`), saved-network history with
+    `use_saved` password reuse, portal isolation to the SoftAP interface and
+    Origin checks on writes, exponential retry (1/2/4/8/15/30 s) with the
+    portal opened alongside retries after 5 consecutive failures, a manual
+    `wifi-change` entrance that retains credentials, and a station fallback
+    DNS slot (`CONFIG_WIFI_MANAGER_FALLBACK_DNS_IPV4`, default 223.5.5.5).
+  - Device binding: fresh-boot SNTP is required before any authentication;
+    the verification-code TTS endpoint (`GET /v1/device/tts`) is supported
+    behind a prompt callback (NULL by default; headless devices keep the
+    serial code); binding failures and rebinds can be retried without a
+    reboot (`bind-retry`); an `unbind` signal or a 6006 token response now
+    triggers identity reconciliation and a signed rebind that retains the
+    stored identity instead of clearing NVS and restarting.
+  - Shared components (`wifi_manager`, `platform_client`, `runtime_config`)
+    keep dual-target ESP32-S3/ESP32-P4 conditionals so future P4 ports can
+    reuse them unchanged.
+- Extend the Kit packing contract and generator tests to cover the new
+  portal endpoints, history component, embedded setup page, and portal
+  isolation; keep the `XiaoTai-` / open-auth / 192.168.6.1 SoftAP contract.
+- Add the ESP32-P4 Device Kit: TiRTC P4 SDK 2.5.0 (vendor baseline
+  `9b4e35c7`, IDF 5.5.4 / 1000 Hz / LWIP_MAX_SOCKETS=10 contract), the
+  XiaoTai P4 1.4.0 reference firmware imported as `device-sim-p4` (shared
+  transport components resolve from the S3 reference; the P4 `tirtc_sdk`
+  wrapper re-pins the archive), generator `--target esp32p4` copy mode,
+  per-target pack/metadata/installer plumbing, a `publish-p4` release job
+  that fails until the P4 kit is pinned, and P4-aware Doctor SDK resolution
+  and contract keys. Managed `setup` stays ESP32-S3-only.
+- Device Kit releases (1.2.0 for S3, 1.0.0 for P4) and checksum pinning
+  are deferred to their release workflows; no sha256 is fabricated in this
+  changelog. Until the S3 Kit 1.2.0 is tagged, managed setup keeps
+  installing the pinned 1.1.7 Kit.
+
+## 0.9.7
+
+- Pin ESP32-S3 Device Kit 1.1.7 with the `XiaoTai-` SoftAP name and the
+  provisioning DHCP state fix; keep TiRTC C SDK 2.5.0.
+- Align generated-project instructions, Hardware IR validation, and Kit
+  packaging checks with the SoftAP name, and cover DHCP initial states.
+
 ## 0.9.6
 
 - Pin ESP32-S3 Device Kit 1.1.6 with TiRTC C SDK 2.5.0 and verify the

package/README.md

@@ -8,11 +8,12 @@ TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入
 |---|---|---|
 | `tirtc-esp32-builder` | ESP32-S3 / ESP32-P4、ESP-IDF 5.5.x | 板型识别、Hardware IR、工程生成/移植、H5/AI/设备互呼/微信 VoIP、AEC 门禁、编译烧录和分层验收 |
 
-H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立的 ESP32 Device Kit 中，安装时会自动下载并校验。ESP32 示例源码由本仓库的 `kit-src/` 维护；设备互呼或微信 VoIP 的移植可参考其中的独立示例。ESP32-P4 必须使用匹配的 P4 SDK、BSP 与网络方案，不能复用 S3 预编译库。
+H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立的 ESP32 Device Kit 中，安装时会自动下载并校验。ESP32 示例源码由本仓库的 `kit-src/` 维护；设备互呼或微信 VoIP 的移植可参考其中的独立示例。ESP32-P4 使用独立发布的 `tirtc-esp32p4-kit`（小钛 P4 参考固件：hosted C6 Wi-Fi + LVGL UI + 摄像头 + P4 SDK 2.5.0），通过生成器 `--target esp32p4` 复制生成，不能复用 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)
-- ESP32 Device Kit：[kit-esp32s3-v1.1.6](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.6)
+- ESP32 Device Kit：[kit-esp32s3-v1.1.7](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.7)
+- ESP32-P4 Device Kit：`tirtc-esp32p4-kit`（首次发布前以 `kit-esp32p4-v*` tag 发布的 GitHub Release 为准）
 
 文档导航：
 
@@ -283,7 +284,7 @@ board-materials/
 | ESP-IDF | 5.5.x |
 | 自动安装版本 | ESP-IDF v5.5.4 |
 | 本仓库源码与本地打包使用的 TiRTC SDK | `espressif-esp32s3/2.5.0` |
-| ESP32 Device Kit | 1.1.6（内含 TiRTC SDK 2.5.0） |
+| ESP32 Device Kit | 1.1.7（内含 TiRTC SDK 2.5.0） |
 | Node.js | 18 或更高版本 |
 | 支持自动安装的系统 | Linux、WSL、macOS |
 | 原生 Windows | 使用 Espressif 官方安装器准备 ESP-IDF，再重新运行检查 |
@@ -394,7 +395,7 @@ Cline 当前还需要在 `Settings → Features → Enable Skills` 中启用实
 |---|---|
 | Agent Skill | 上表中所选目录下的 `tirtc-esp32-builder` |
 | 托管根目录 | `~/.tirtc-device-builder` |
-| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.6` |
+| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.7` |
 | ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
 | Espressif 工具 | `~/.tirtc-device-builder/espressif` |
 | 安装记录 | `~/.tirtc-device-builder/config.json` |
@@ -439,7 +440,7 @@ npx --yes tirtc-device-builder@latest setup esp32 --install \
 
 ```bash
 npx --yes tirtc-device-builder@latest setup esp32 --install \
-  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.6.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.7.tar.gz
 ```
 
 安装器仍会核对固定的 SHA-256、目录结构、清单和每个资源文件，不接受未经验证的同名压缩包。
@@ -654,7 +655,7 @@ bootloader、分区表和应用镜像；无需手工维护多条 `esptool.py`
 
 ### Wi-Fi 凭证和设备绑定
 
-SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。若选择 SoftAP，热点名必须以 `TiRTC-` 开头、使用开放认证（无需密码），AP 网关和配网页面地址固定为 `192.168.6.1`（`http://192.168.6.1`），并通过通配 DNS 和 HTTP 回退启用 captive portal 自动发现。DHCP Option 114 只用于 RFC 8908 HTTPS/JSON API，不能指向本地 HTML 页面。系统没有自动弹窗时仍可手动打开该 HTTP 地址；HTTPS 不能透明重定向。这些值要写入 Hardware IR 并通过门禁；目标 WLAN 的 SSID 和密码仍不得写死在源码中。
+SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。若选择 SoftAP，热点名必须以 `XiaoTai-` 开头、使用开放认证（无需密码），AP 网关和配网页面地址固定为 `192.168.6.1`（`http://192.168.6.1`），并通过通配 DNS 和 HTTP 回退启用 captive portal 自动发现。DHCP Option 114 只用于 RFC 8908 HTTPS/JSON API，不能指向本地 HTML 页面。系统没有自动弹窗时仍可手动打开该 HTTP 地址；HTTPS 不能透明重定向。这些值要写入 Hardware IR 并通过门禁；目标 WLAN 的 SSID 和密码仍不得写死在源码中。
 
 无论选择哪种方法，都要有当前 PCB/BSP 的支持证据，凭证不能进入 Git、源码或报告，并且要保留清除或重配入口。没有 SoftAP、但支持工厂 NVS 注入的设备同样可以接入。只要工程提交了明文密码，Hardware IR v2 门禁就会判为 `BLOCKED`。
 
@@ -822,7 +823,7 @@ npx --yes tirtc-device-builder@latest setup esp32 --install --force-skill
 
 ```bash
 npx --yes tirtc-device-builder@latest setup esp32 --install \
-  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.6.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.7.tar.gz
 ```
 
 安装器会校验 SHA-256 和内部文件清单。如果校验不一致，请重新获取官方 Release 附件，不要跳过校验。
@@ -933,25 +934,25 @@ python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
 
 ```bash
 npm run pack:esp32-kit -- \
-  --kit-version 1.1.6
+  --kit-version 1.1.7
 ```
 
 输出位于 `dist/`：
 
 ```text
-tirtc-esp32s3-kit-1.1.6.tar.gz
-tirtc-esp32s3-kit-1.1.6.tar.gz.sha256
+tirtc-esp32s3-kit-1.1.7.tar.gz
+tirtc-esp32s3-kit-1.1.7.tar.gz.sha256
 ```
 
 校验后推送独立的 `kit-esp32s3-v<version>` 标签。`publish-kit.yml` 会从 metadata 固定的本仓库源码 commit 重建压缩包、核对 SHA-256，并使用 GitHub Actions token 创建 Release：
 
 ```bash
 cd dist
-sha256sum -c tirtc-esp32s3-kit-1.1.6.tar.gz.sha256
+sha256sum -c tirtc-esp32s3-kit-1.1.7.tar.gz.sha256
 cd ..
 
-git tag -a kit-esp32s3-v1.1.6 -m "TiRTC ESP32-S3 Device Kit 1.1.6"
-git push origin kit-esp32s3-v1.1.6
+git tag -a kit-esp32s3-v1.1.7 -m "TiRTC ESP32-S3 Device Kit 1.1.7"
+git push origin kit-esp32s3-v1.1.7
 ```
 
 metadata 中的版本、标签、本仓库源码 commit 和期望 SHA-256 必须与本地可复现打包结果一致；工作流不会从浮动的 `main` 取发布内容。
@@ -962,8 +963,8 @@ metadata 中的版本、标签、本仓库源码 commit 和期望 SHA-256 必须
 
 ```bash
 npm test
-git tag -a v0.9.6 -m "v0.9.6"
-git push origin v0.9.6
+git tag -a v0.9.7 -m "v0.9.7"
+git push origin v0.9.7
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/esp32-kit-metadata.js

@@ -1,10 +1,37 @@
 export const ESP32_KIT = Object.freeze({
-  archiveName: "tirtc-esp32s3-kit-1.1.6.tar.gz",
-  archiveRoot: "tirtc-esp32s3-kit-1.1.6",
-  releaseTag: "kit-esp32s3-v1.1.6",
-  sha256: "61243703bdee3e1b492fcc6f5245143f419efbd2310127d180875f0708e91d8b",
+  target: "esp32s3",
+  platform: "espressif-esp32s3",
+  archiveName: "tirtc-esp32s3-kit-1.1.7.tar.gz",
+  archiveRoot: "tirtc-esp32s3-kit-1.1.7",
+  releaseTag: "kit-esp32s3-v1.1.7",
+  sha256: "61be93e5b3648c067a581195d2146ac57f748c2f356e9b681a0926f301cf6a8b",
   sdkVersion: "2.5.0",
-  sourceCommit: "68a3b34054ea933d5ea5bfd8acf71e5ff07a7a61",
-  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.6/tirtc-esp32s3-kit-1.1.6.tar.gz",
-  version: "1.1.6",
+  sourceCommit: "50be0b4b6ad83ca376e010ebb7256db4fb6debcd",
+  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.7/tirtc-esp32s3-kit-1.1.7.tar.gz",
+  version: "1.1.7",
+  released: true,
+});
+
+/*
+ * The ESP32-P4 Device Kit is pinned by its first release. Until the release
+ * workflow publishes and pins it, sha256/sourceCommit/url stay null and the
+ * publish-p4 job fails any premature kit-esp32p4-v* tag. Nothing is fabricated.
+ */
+export const ESP32_P4_KIT = Object.freeze({
+  target: "esp32p4",
+  platform: "espressif-esp32p4",
+  archiveName: "tirtc-esp32p4-kit-1.0.0.tar.gz",
+  archiveRoot: "tirtc-esp32p4-kit-1.0.0",
+  releaseTag: "kit-esp32p4-v1.0.0",
+  sha256: null,
+  sdkVersion: "2.5.0",
+  sourceCommit: null,
+  url: null,
+  version: "1.0.0",
+  released: false,
+});
+
+export const ESP32_KITS = Object.freeze({
+  esp32s3: ESP32_KIT,
+  esp32p4: ESP32_P4_KIT,
 });

package/bin/install-esp32-kit.js

@@ -16,15 +16,30 @@ import {
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ESP32_KIT } from "./esp32-kit-metadata.js";
+import { ESP32_KIT, ESP32_KITS } from "./esp32-kit-metadata.js";
 
-const REQUIRED_FILES = [
-  "manifest.json",
-  "device-sim/scripts/create_esp32_project.py",
-  "device-sim/templates/esp32-h5-ai/CMakeLists.txt",
-  "device-sim/templates/esp32-h5-ai/platform-media-contract.json",
-  "device-sim/templates/esp32-h5-ai/tirtc-runtime-contract.json",
-];
+const REQUIRED_FILES_BY_TARGET = {
+  esp32s3: [
+    "manifest.json",
+    "device-sim/scripts/create_esp32_project.py",
+    "device-sim/templates/esp32-h5-ai/CMakeLists.txt",
+    "device-sim/templates/esp32-h5-ai/platform-media-contract.json",
+    "device-sim/templates/esp32-h5-ai/tirtc-runtime-contract.json",
+  ],
+  esp32p4: [
+    "manifest.json",
+    "device-sim/scripts/create_esp32_project.py",
+    "device-sim/device-sim-p4/CMakeLists.txt",
+    "device-sim/device-sim-p4/sdkconfig.defaults",
+    "device-sim/device-sim-p4/dependencies.lock",
+    "device-sim/device-sim-esp32/components/wifi_manager/src/wifi_manager.c",
+  ],
+};
+
+const SDK_VERSION_PATTERN_BY_TARGET = {
+  esp32s3: /^(?:2\.3\.0|2\.5\.0)$/,
+  esp32p4: /^2\.5\.0$/,
+};
 
 function hashFile(path) {
   return createHash("sha256").update(readFileSync(path)).digest("hex");
@@ -77,7 +92,8 @@ function assertNoLinks(root, current = root) {
 }
 
 function validateExtractedKit(root, metadata) {
-  const missing = REQUIRED_FILES.filter((path) => !existsSync(join(root, path)));
+  const requiredFiles = REQUIRED_FILES_BY_TARGET[metadata.target] ?? [];
+  const missing = requiredFiles.filter((path) => !existsSync(join(root, path)));
   if (missing.length > 0) {
     throw new Error(`Device Kit is incomplete: ${missing.join(", ")}`);
   }
@@ -95,12 +111,15 @@ function validateExtractedKit(root, metadata) {
       `Device Kit version mismatch: expected ${metadata.version}, got ${manifest.kit_version}`,
     );
   }
-  if (manifest.target !== "esp32s3" ||
-      !/^(?:2\.3\.0|2\.5\.0)$/.test(manifest.tirtc_sdk_version) ||
+  const sdkPattern = SDK_VERSION_PATTERN_BY_TARGET[metadata.target];
+  if (!sdkPattern ||
+      manifest.target !== metadata.target ||
+      manifest.platform !== metadata.platform ||
+      !sdkPattern.test(manifest.tirtc_sdk_version) ||
       (metadata.sdkVersion && manifest.tirtc_sdk_version !== metadata.sdkVersion)) {
     throw new Error("Device Kit target or TiRTC SDK version is incompatible");
   }
-  const sdkRoot = `device-sim/sdk/espressif-esp32s3/${manifest.tirtc_sdk_version}`;
+  const sdkRoot = `device-sim/sdk/${metadata.platform}/${manifest.tirtc_sdk_version}`;
   const sdkFiles = [
     `${sdkRoot}/include/tirtc/tiRTC.h`,
     `${sdkRoot}/lib/libTiRTC.a`,
@@ -170,17 +189,20 @@ async function download(url, destination) {
 function parseArgs(args) {
   let archive = null;
   let target = null;
+  let kit = "esp32s3";
   for (let index = 0; index < args.length; index += 1) {
     const argument = args[index];
-    if (argument === "--archive" || argument === "--target") {
+    if (argument === "--archive" || argument === "--target" || argument === "--kit") {
       const value = args[index + 1];
       if (!value || value.startsWith("--")) {
-        throw new Error(`${argument} requires a path`);
+        throw new Error(`${argument} requires a value`);
       }
       if (argument === "--archive") {
         archive = resolve(value);
-      } else {
+      } else if (argument === "--target") {
         target = resolve(value);
+      } else {
+        kit = value;
       }
       index += 1;
       continue;
@@ -190,20 +212,29 @@ function parseArgs(args) {
   if (!target) {
     throw new Error("--target is required");
   }
-  return { archive, target };
+  if (!(kit in ESP32_KITS)) {
+    throw new Error(`unknown Device Kit target selector: ${kit}`);
+  }
+  return { archive, target, metadata: ESP32_KITS[kit] };
 }
 
 async function main() {
   const options = parseArgs(process.argv.slice(2));
+  const metadata = options.metadata;
   let archive = options.archive;
   let downloadDirectory = null;
   try {
     if (!archive) {
+      if (!metadata.released) {
+        throw new Error(
+          `Device Kit ${metadata.target} metadata is not yet pinned to a release; pass --archive`,
+        );
+      }
       downloadDirectory = mkdtempSync(join(tmpdir(), "tirtc-kit-download-"));
-      archive = join(downloadDirectory, ESP32_KIT.archiveName);
-      await download(ESP32_KIT.url, archive);
+      archive = join(downloadDirectory, metadata.archiveName);
+      await download(metadata.url, archive);
     }
-    installEsp32KitArchive(archive, options.target);
+    installEsp32KitArchive(archive, options.target, metadata);
   } finally {
     if (downloadDirectory) {
       rmSync(downloadDirectory, { force: true, recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.9.6",
+  "version": "0.10.0",
   "description": "Install and run TiRTC device-development Agent Skills across popular coding clients.",
   "license": "MIT",
   "author": {

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

@@ -27,9 +27,10 @@ past build as proof for a new artifact.
    Clone or download it only when the user authorizes that external write.
    Read 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.
+   automates ESP32-S3. For ESP32-P4 use the published `tirtc-esp32p4-kit`
+   (the XiaoTai P4 reference firmware with hosted C6 Wi-Fi and LVGL UI): copy it
+   with `create_esp32_project.py --target esp32p4`, build with the RISC-V
+   toolchain on ESP-IDF 5.5.4, and never link the S3 archive into a P4 image.
 
 ## 2. Identify the board and query knowledge
 

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

@@ -44,6 +44,24 @@ printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 
 已有完整 ThingConnect 工作区仍可通过 `--thing-connect-root` 显式复用，主要用于维护模板或协议时的开发场景。
 
+### ESP32-P4 Device Kit
+
+P4 不上 managed 安装（需要独立的 RISC-V 工具链）。从 GitHub Release 下载
+`tirtc-esp32p4-kit`（小钛 P4 参考固件 1.4.0：hosted C6 Wi-Fi + LVGL UI +
+摄像头，含 P4 SDK 2.5.0 与构建契约）并校验 SHA-256 后：
+
+```bash
+python3 <解包目录>/device-sim/scripts/create_esp32_project.py \
+  /absolute/path/my-p4-device my_p4_device --target esp32p4
+cd /absolute/path/my-p4-device
+idf.py set-target esp32p4
+idf.py build   # 需要 ESP-IDF 5.5.4 与 riscv32-esp-elf（install.sh esp32p4）
+```
+
+诊断使用 `--target esp32p4`；P4 永远不得链接 S3 的 `libTiRTC.a`。板级差异
+（屏幕、摄像头、Codec、按键）位于参考固件的板级组件内，共享传输组件
+（platform_client/runtime_config/wifi_manager）与 S3 同源。
+
 ## 常见输入方式
 
 只有板卡型号：
@@ -74,7 +92,7 @@ printf '%s\n' "$TIRTC_THING_CONNECT_ROOT"
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
   --target esp32s3 \
-  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.6 \
+  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.7 \
   --require-workspace
 ```
 

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.9.6
+0.10.0

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

@@ -27,7 +27,7 @@
 
 接入方式：
 - Wi-Fi：<选择一种，或写“根据 BSP 选择”>
-- 选择 SoftAP 时：热点名以 `TiRTC-` 开头、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`，启用通配 DNS 和 HTTP 重定向进行 captive portal 自动发现，不把 DHCP Option 114 指向本地 HTML 页面，并保留手动打开地址的回退说明
+- 选择 SoftAP 时：热点名以 `XiaoTai-` 开头、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`，启用通配 DNS 和 HTTP 重定向进行 captive portal 自动发现，不把 DHCP Option 114 指向本地 HTML 页面，并保留手动打开地址的回退说明
 - 设备绑定：<选择一种，或写“根据平台合同选择”>
 
 工程：

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -8,7 +8,7 @@
 
 ```bash
 export TIRTC_AGENT_CLIENT=codex
-npx --yes tirtc-device-builder@0.9.6 setup esp32 --install \
+npx --yes tirtc-device-builder@0.9.7 setup esp32 --install \
   --client "$TIRTC_AGENT_CLIENT" --force-skill
 ```
 
@@ -17,11 +17,11 @@ npx --yes tirtc-device-builder@0.9.6 setup esp32 --install \
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.9.6 --version
-npx --yes tirtc-device-builder@0.9.6 setup esp32 --client "$TIRTC_AGENT_CLIENT"
+npx --yes tirtc-device-builder@0.9.7 --version
+npx --yes tirtc-device-builder@0.9.7 setup esp32 --client "$TIRTC_AGENT_CLIENT"
 ```
 
-必须根据命令的实际输出和本机文件确认：npm 包为 0.9.6、已安装 Skill 的 `VERSION` 为 0.9.6、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.6、`tirtc_sdk_version` 为 2.5.0，并且 Doctor 对 `--expected-kit 1.1.6` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.9.7、已安装 Skill 的 `VERSION` 为 0.9.7、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.7、`tirtc_sdk_version` 为 2.5.0，并且 Doctor 对 `--expected-kit 1.1.7` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
 - 将启动 Agent 客户端时的当前目录定义为 `WORKSPACE_ROOT`。
@@ -60,7 +60,7 @@ npx --yes tirtc-device-builder@0.9.6 setup esp32 --client "$TIRTC_AGENT_CLIENT"
 - AI 对讲必须实现全双工和 AEC；构建阶段必须证明同时采集播放、真实播放参考与 `echo_cancellation.enabled=true`，实机结果仍只能在 L2-L7 验证后声明。
 
 接入要求：
-- SoftAP 配网：热点名使用 `TiRTC-` 前缀、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`；启用通配 DNS 和 HTTP 重定向进行 captive portal 自动发现，不把 DHCP Option 114 指向本地 HTML 页面；Hardware IR 记录 `captive_portal: true`；目标 Wi-Fi 凭证保存 NVS。
+- SoftAP 配网：热点名使用 `XiaoTai-` 前缀、开放认证无需密码，AP 网关和配网页面为 `192.168.6.1` / `http://192.168.6.1`；启用通配 DNS 和 HTTP 重定向进行 captive portal 自动发现，不把 DHCP Option 114 指向本地 HTML 页面；Hardware IR 记录 `captive_portal: true`；目标 Wi-Fi 凭证保存 NVS。
 - 验证码绑定，并复用已有绑定。
 - 分别实现 `wifi-clear` 和 `tirtc-clear`。
 - 平台发现本轮先使用 HTTP；HTTPS 留待独立验收。

package/skills/tirtc-esp32-builder/knowledge/waveshare-esp32-p4-wifi6-touch-lcd-3.5/knowledge.md

@@ -5,6 +5,15 @@ contains source-correlated observations and targeted regressions, not an
 installable adapter or complete Hardware IR. A matching sales name does not
 authorize pin reuse. No credentials, raw call logs or user media are retained.
 
+## Current kit status (2026-09-22)
+
+The builder repository now ships the XiaoTai P4 reference firmware (product
+1.4.0, source `f33b7d2`) in `kit-src/device-sim/device-sim-p4/` and packs the
+TiRTC ESP32-P4 SDK 2.5.0 vendor baseline (libTiRTC.a sha256
+`9b4e35c7…`) into the `tirtc-esp32p4-kit` release. The historical observations
+below (TiRTC 2.3.0, archive `a7a01ffd…`, IDF 5.5.4-dirty) remain historical
+artifacts and do not describe the current kit baseline.
+
 ## Read only the needed source
 
 | Baseline | Pinned source | Locate next |

package/skills/tirtc-esp32-builder/references/environment.md

@@ -16,7 +16,7 @@ The automatic branch never runs `sudo` or modifies a persistent shell profile. W
 When `<setup-root>/env.sh` exists, use it only as an activation prefix for the current command:
 
 ```bash
-bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.6 --target esp32s3 --require-workspace'
+bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.7 --target esp32s3 --require-workspace'
 ```
 
 The helper contains paths, not device or network credentials. Read `<setup-root>/config.json` when exact managed paths are needed; the environment helper does not authorize unrelated downloads, shell-profile changes, flashing, or credential writes.
@@ -26,7 +26,7 @@ Run the doctor before generation, build, flash, or monitor:
 ```bash
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
-  --expected-kit 1.1.6 \
+  --expected-kit 1.1.7 \
   --target esp32s3 \
   --require-workspace
 ```
@@ -47,7 +47,7 @@ For an explicitly selected legacy workspace, omit `--expected-kit`; otherwise re
 4. an ancestor whose `kit-src/` or `thing-connect/` child contains that generator.
 
 The default managed root is `<setup-root>/kits/esp32s3/<kit-version>`. The `tirtc-device-builder/kit-src` directory is the ESP32 development source; the doctor also accepts an installed Device Kit root. Older `thing-connect/` layouts remain accepted as legacy inputs.
-Resolve the SDK from the selected Kit manifest or generated project. Kit 1.1.6
+Resolve the SDK from the selected Kit manifest or generated project. Kit 1.1.7
 and this repository's source generator use the ESP32-S3 SDK 2.5.0.
 
 The managed Kit currently contains the ESP32-S3 H5/AI starter. When the requested
@@ -59,10 +59,19 @@ protocols and non-ESP32 simulators. Cloning is an external write and requires
 user authorization. Do not track a moving default branch as build evidence.
 
 ESP32-P4 uses a separate `espressif_esp32p4` SDK archive and RISC-V toolchain.
-The managed setup does not install that archive or generate a P4 starter. A P4
-task therefore needs an explicit BSP/network project plus the exact P4 SDK and
-`manifest/build-contract.env`; run Doctor with `--target esp32p4` and never accept
-the packaged S3 archive as a compatible fallback.
+The managed setup does not install that archive; P4 projects come from the
+published `tirtc-esp32p4-kit` (the XiaoTai P4 reference firmware, released
+alongside the S3 Kit). The P4 flow is:
+
+1. Download the `tirtc-esp32p4-kit` GitHub release, verify its SHA-256, and
+   extract it (or point `--thing-connect-root` at this repository's `kit-src`).
+2. `python3 device-sim/scripts/create_esp32_project.py <out> <name> --target esp32p4`
+   (copies the full reference firmware and materializes the shared transport
+   components and the P4 SDK under `third_party/tirtc`).
+3. `idf.py set-target esp32p4`, build with the RISC-V toolchain
+   (`install.sh esp32p4`; the pinned SDK requires ESP-IDF 5.5.4 exactly).
+4. Run Doctor with `--target esp32p4` and never accept the packaged S3 archive
+   as a compatible fallback.
 
 SDK resolution is independent after generation: an explicit `--sdk-dir` wins, followed by `<project>/third_party/tirtc`, then the SDK packaged in the resolved Device Kit or legacy workspace. The generated project remains diagnosable after it is moved away from the Kit.
 

package/skills/tirtc-esp32-builder/references/hardware-ir.md

@@ -65,8 +65,8 @@ The selected Wi-Fi method must be available and corroborated, credentials must r
 
 When the selected method is SoftAP:
 
-- generate the SSID as `TiRTC-<device suffix>` so its exact, case-sensitive
-  prefix is `TiRTC-`; use a stable non-secret suffix and keep the complete SSID
+- generate the SSID as `XiaoTai-<device suffix>` so its exact, case-sensitive
+  prefix is `XiaoTai-`; use a stable non-secret suffix and keep the complete SSID
   within the ESP32 32-byte limit;
 - configure an open network (`WIFI_AUTH_OPEN`) with an empty AP password so a
   user can connect directly;
@@ -81,7 +81,7 @@ When the selected method is SoftAP:
   client auto-popup is not guaranteed and HTTPS cannot be transparently
   redirected.
 
-Record these values on the selected SoftAP method as `ssid_prefix: "TiRTC-"`,
+Record these values on the selected SoftAP method as `ssid_prefix: "XiaoTai-"`,
 `auth_mode: "open"`, `ipv4_address: "192.168.6.1"`, and
 `captive_portal: true`. The Hardware IR gate returns `NEEDS_CONFIRMATION` when
 one is missing and `BLOCKED` when one differs.

package/skills/tirtc-esp32-builder/scripts/doctor.py

@@ -22,10 +22,29 @@ CONTRACT_KEYS = {
     "CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS",
     "CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS",
 }
+# The P4 archive additionally pins the socket budget (absent from the S3 contract).
+CONTRACT_KEYS_P4 = CONTRACT_KEYS | {"CONFIG_LWIP_MAX_SOCKETS"}
 THING_CONNECT_ENV = "TIRTC_THING_CONNECT_ROOT"
 GENERATOR_RELATIVE_PATH = Path("device-sim/scripts/create_esp32_project.py")
-SDK_RELATIVE_ROOT = Path("device-sim/sdk/espressif-esp32s3")
 DEVICE_KIT_MANIFEST = "manifest.json"
+SDK_FALLBACK_VERSIONS = {
+    "esp32s3": ("2.5.0", "2.3.0"),
+    "esp32p4": ("2.5.0",),
+}
+
+
+def sdk_relative_root(platform: str | None, target: str) -> Path:
+    """SDK root inside the Kit; the manifest platform wins, the target is the
+    fallback. A P4 target never resolves the ESP32-S3 SDK archive."""
+    if platform == "espressif-esp32p4" or target == "esp32p4":
+        return Path("device-sim/sdk/espressif-esp32p4")
+    return Path("device-sim/sdk/espressif-esp32s3")
+
+
+def contract_keys(target: str) -> set[str]:
+    if target == "esp32p4":
+        return CONTRACT_KEYS_P4
+    return CONTRACT_KEYS
 
 
 def check(name: str, status: str, detail: str, required: bool = True) -> dict[str, Any]:
@@ -115,10 +134,10 @@ def parse_kconfig(path: Path) -> dict[str, str]:
 
 
 def compare_contract(
-    contract: dict[str, str], config: dict[str, str]
+    contract: dict[str, str], config: dict[str, str], keys: set[str] | None = None
 ) -> list[str]:
     mismatches: list[str] = []
-    for key in sorted(CONTRACT_KEYS):
+    for key in sorted(keys if keys is not None else CONTRACT_KEYS):
         expected = contract.get(key)
         actual = config.get(key)
         if expected is None:
@@ -238,6 +257,7 @@ def resolve_sdk_dir(
     explicit: Path | None,
     project: Path | None,
     thing_connect_root: Path | None,
+    target: str = "esp32s3",
 ) -> tuple[Path | None, str]:
     if explicit is not None:
         return explicit.expanduser().resolve(), "explicit --sdk-dir"
@@ -251,15 +271,22 @@ def resolve_sdk_dir(
             try:
                 manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
                 version = manifest.get("tirtc_sdk_version")
+                platform = manifest.get("platform")
                 if isinstance(version, str) and re.fullmatch(r"\d+\.\d+\.\d+", version):
-                    return thing_connect_root / SDK_RELATIVE_ROOT / version, "Device Kit"
+                    return (
+                        thing_connect_root / sdk_relative_root(platform, target) / version,
+                        "Device Kit",
+                    )
             except (OSError, json.JSONDecodeError):
                 pass
-        for version in ("2.5.0", "2.3.0"):
-            candidate = thing_connect_root / SDK_RELATIVE_ROOT / version
+        for version in SDK_FALLBACK_VERSIONS.get(target, SDK_FALLBACK_VERSIONS["esp32s3"]):
+            candidate = thing_connect_root / sdk_relative_root(None, target) / version
             if candidate.is_dir():
                 return candidate, "ESP32 source workspace"
-        return thing_connect_root / SDK_RELATIVE_ROOT / "2.5.0", "ESP32 source workspace"
+        return (
+            thing_connect_root / sdk_relative_root(None, target) / "2.5.0",
+            "ESP32 source workspace",
+        )
     return None, "not found"
 
 
@@ -373,6 +400,7 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
         args.sdk_dir,
         args.project,
         thing_connect_root,
+        args.target,
     )
     if sdk_dir is None:
         sdk_files: list[Path] = []
@@ -427,7 +455,9 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
             checks.append(check("TiRTC build contract", "FAIL", detail))
         else:
             mismatches = compare_contract(
-                parse_env_file(contract_path), parse_kconfig(config_path)
+                parse_env_file(contract_path),
+                parse_kconfig(config_path),
+                contract_keys(args.target),
             )
             checks.append(
                 check(

package/skills/tirtc-esp32-builder/scripts/hardware_ir.py

@@ -61,7 +61,7 @@ WIFI_METHOD_TYPES = {
     "development_config",
     "custom",
 }
-SOFTAP_SSID_PREFIX = "TiRTC-"
+SOFTAP_SSID_PREFIX = "XiaoTai-"
 SOFTAP_AUTH_MODE = "open"
 SOFTAP_IPV4_ADDRESS = "192.168.6.1"
 SOFTAP_CAPTIVE_PORTAL = True