tirtc-device-builder 0.9.0 → 0.9.2

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This project follows Semantic Versioning.
 
+## 0.9.2
+
+- Pin ESP32 Device Kit 1.1.3 with captive portal discovery through DHCP option
+  114, wildcard DNS, and HTTP fallback redirects.
+- Require `captive_portal: true` in the selected SoftAP Hardware IR contract and
+  reject Kit packaging when the runtime, component wiring, or instructions omit
+  automatic portal discovery.
+
+## 0.9.1
+
+- Pin ESP32 Device Kit 1.1.2 with an open `TiRTC-` SoftAP and provisioning at
+  `http://192.168.6.1`.
+- Reject Device Kit packaging when implementation or documentation retains the
+  legacy SSID, password, or `192.168.4.1` provisioning contract.
+- Make the Hardware IR SoftAP defaults and validation match the device runtime.
+
 ## 0.9.0
 
 - Add native Skill-directory installation for Codex, Claude Code, OpenCode,

package/README.md

@@ -12,7 +12,7 @@ H5/AI 的 ESP32-S3 托管模板、协议文档和 TiRTC SDK 已打包在独立
 
 - 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.1](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.1)
+- ESP32 Device Kit：[kit-esp32s3-v1.1.3](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.3)
 
 文档导航：
 
@@ -283,7 +283,7 @@ board-materials/
 | ESP-IDF | 5.5.x |
 | 自动安装版本 | ESP-IDF v5.5.4 |
 | TiRTC SDK | `espressif-esp32s3/2.3.0` |
-| ESP32 Device Kit | 1.1.1 |
+| ESP32 Device Kit | 1.1.3 |
 | Node.js | 18 或更高版本 |
 | 支持自动安装的系统 | Linux、WSL、macOS |
 | 原生 Windows | 使用 Espressif 官方安装器准备 ESP-IDF，再重新运行检查 |
@@ -392,7 +392,7 @@ Cline 当前还需要在 `Settings → Features → Enable Skills` 中启用实
 |---|---|
 | Agent Skill | 上表中所选目录下的 `tirtc-esp32-builder` |
 | 托管根目录 | `~/.tirtc-device-builder` |
-| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.1` |
+| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.3` |
 | ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
 | Espressif 工具 | `~/.tirtc-device-builder/espressif` |
 | 安装记录 | `~/.tirtc-device-builder/config.json` |
@@ -437,7 +437,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.1.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.3.tar.gz
 ```
 
 安装器仍会核对固定的 SHA-256、目录结构、清单和每个资源文件，不接受未经验证的同名压缩包。
@@ -652,7 +652,7 @@ bootloader、分区表和应用镜像；无需手工维护多条 `esptool.py`
 
 ### Wi-Fi 凭证和设备绑定
 
-SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。SSID 和密码不应写死在源码中。
+SoftAP 是可选方案，不是接入前提。Hardware IR 要根据 BSP 的实际能力和产品要求，选择 SoftAP、BLE、SmartConfig、安全工厂/NVS 注入、不纳入版本控制的开发配置，或有文档的自定义方案。若选择 SoftAP，热点名必须以 `TiRTC-` 开头、使用开放认证（无需密码），AP 网关和配网页面地址固定为 `192.168.6.1`（`http://192.168.6.1`），并通过 DHCP Option 114、通配 DNS 和 HTTP 回退启用 captive portal 自动发现。系统没有自动弹窗时仍可手动打开该 HTTP 地址；HTTPS 不能透明重定向。这些值要写入 Hardware IR 并通过门禁；目标 WLAN 的 SSID 和密码仍不得写死在源码中。
 
 无论选择哪种方法，都要有当前 PCB/BSP 的支持证据，凭证不能进入 Git、源码或报告，并且要保留清除或重配入口。没有 SoftAP、但支持工厂 NVS 注入的设备同样可以接入。只要工程提交了明文密码，Hardware IR v2 门禁就会判为 `BLOCKED`。
 
@@ -820,7 +820,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.1.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.3.tar.gz
 ```
 
 安装器会校验 SHA-256 和内部文件清单。如果校验不一致，请重新获取官方 Release 附件，不要跳过校验。
@@ -932,25 +932,25 @@ python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
 ```bash
 npm run pack:esp32-kit -- \
   --source /absolute/path/tirtc-server-example/thing-connect \
-  --kit-version 1.1.1
+  --kit-version 1.1.3
 ```
 
 输出位于 `dist/`：
 
 ```text
-tirtc-esp32s3-kit-1.1.1.tar.gz
-tirtc-esp32s3-kit-1.1.1.tar.gz.sha256
+tirtc-esp32s3-kit-1.1.3.tar.gz
+tirtc-esp32s3-kit-1.1.3.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.1.tar.gz.sha256
+sha256sum -c tirtc-esp32s3-kit-1.1.3.tar.gz.sha256
 cd ..
 
-git tag -a kit-esp32s3-v1.1.1 -m "TiRTC ESP32-S3 Device Kit 1.1.1"
-git push origin kit-esp32s3-v1.1.1
+git tag -a kit-esp32s3-v1.1.3 -m "TiRTC ESP32-S3 Device Kit 1.1.3"
+git push origin kit-esp32s3-v1.1.3
 ```
 
 metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地可复现打包结果一致；工作流不会从浮动的 `main` 取发布内容。
@@ -961,8 +961,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.9.0 -m "v0.9.0"
-git push origin v0.9.0
+git tag -a v0.9.2 -m "v0.9.2"
+git push origin v0.9.2
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/esp32-kit-metadata.js

@@ -1,9 +1,9 @@
 export const ESP32_KIT = Object.freeze({
-  archiveName: "tirtc-esp32s3-kit-1.1.1.tar.gz",
-  archiveRoot: "tirtc-esp32s3-kit-1.1.1",
-  releaseTag: "kit-esp32s3-v1.1.1",
-  sha256: "d9818b1caf73b039d46b7f973ad675ac750d259940db4ef22b35a76896a0cdf3",
-  sourceCommit: "35acd405ffb0ed0917fc0671033b844739fe93dd",
-  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.1/tirtc-esp32s3-kit-1.1.1.tar.gz",
-  version: "1.1.1",
+  archiveName: "tirtc-esp32s3-kit-1.1.3.tar.gz",
+  archiveRoot: "tirtc-esp32s3-kit-1.1.3",
+  releaseTag: "kit-esp32s3-v1.1.3",
+  sha256: "3239d3045a82082beb73b9bbbd2217e9da278bf8fbbe2941ae9131a20830d45c",
+  sourceCommit: "e685e33c6622fedfed66e9132447ddaae1e2a40e",
+  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.1.3/tirtc-esp32s3-kit-1.1.3.tar.gz",
+  version: "1.1.3",
 });

package/package.json

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

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

@@ -70,6 +70,10 @@ implementation and build facts. Stop before code only for a genuine user choice,
 unknown wiring/identity, unavailable matching SDK, or required public-contract
 change.
 
+When SoftAP is the selected Wi-Fi method, carry the fixed SSID, open-auth, IPv4
+and captive-portal [product contract](references/hardware-ir.md#softap-product-contract)
+into the IR, generated adapter, user-facing instructions and build checks.
+
 ## 5. Generate and port
 
 Generate a new project without overwriting an existing path. Keep platform

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

@@ -74,7 +74,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.1 \
+  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.3 \
   --require-workspace
 ```
 

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.9.0
+0.9.2

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

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

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

package/skills/tirtc-esp32-builder/references/capability-rules.md

@@ -47,7 +47,7 @@ The intake phase requires:
 
 At intake, `corroborated` on these fields means the design is resolved from authoritative sources and is safe to implement. After compilation, promote a field to `build_verified` only when the generated source, component lock, semantic gate, compile result, or post-link gate establishes it. Build assessment reruns the applicable project-relative [audio contract](audio-contract.md), [video contract](video-contract.md), and mandatory [runtime contract](runtime-contract.md); self-declared `resolved=true`, `pipeline_safe=true`, or memory-budget booleans cannot replace them. The build phase requires an exact on-disk artifact SHA-256 and returns `BUILD_VERIFIED` only when every requested feature passes. Runtime measurements never need to be invented to pass intake or build.
 
-SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, factory NVS, development configuration, or a documented custom method can satisfy intake when the selected path is evidenced. Committed plaintext credentials are always `BLOCKED`.
+SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, factory NVS, development configuration, or a documented custom method can satisfy intake when the selected path is evidenced. A selected SoftAP must satisfy the product contract in [Hardware IR](hardware-ir.md#softap-product-contract). Committed plaintext credentials are always `BLOCKED`.
 
 ## Non-negotiable runtime checks
 

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.1 --target esp32s3 --require-workspace'
+bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.3 --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.1 \
+  --expected-kit 1.1.3 \
   --target esp32s3 \
   --require-workspace
 ```

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

@@ -61,6 +61,31 @@ assessment also requires the project audio semantic gate to prove enabled AEC.
 
 The selected Wi-Fi method must be available and corroborated, credentials must remain outside tracked source, and reprovisioning must be defined. A board without SoftAP is valid when another selected method meets those conditions.
 
+### SoftAP product contract
+
+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
+  within the ESP32 32-byte limit;
+- configure an open network (`WIFI_AUTH_OPEN`) with an empty AP password so a
+  user can connect directly;
+- assign the AP netif, gateway and provisioning server `192.168.6.1/24`, serve
+  the setup page at `http://192.168.6.1`, and lease clients from that subnet.
+  With ESP-IDF, stop DHCP before changing the AP netif IP information and
+  restart it afterward;
+- enable captive portal discovery with DHCP option 114, wildcard DNS resolving
+  names to `192.168.6.1`, and an HTTP fallback redirect to the setup page. Keep
+  the direct HTTP address documented because client auto-popup is not
+  guaranteed and HTTPS cannot be transparently redirected.
+
+Record these values on the selected SoftAP method as `ssid_prefix: "TiRTC-"`,
+`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.
+Keep the provisioning endpoints available only while onboarding is active, and
+disable the AP or restart into STA mode after credentials are accepted.
+
 The selected video profile controls assessment. An unselected H.264 fallback cannot make an MJPEG target pass, and missing H.264 cannot block an evidenced MJPEG target.
 
 ## Artifact-bound HIL

package/skills/tirtc-esp32-builder/references/porting-risks.md

@@ -30,7 +30,7 @@ Turn every discovered invariant that can regress into a focused test or post-lin
 
 Wi-Fi provisioning and ThingConnect binding are separate state machines.
 
-Select one evidenced Wi-Fi credential method from SoftAP, BLE, SmartConfig, secure factory/NVS provisioning, development configuration, or a documented custom path. SoftAP is not mandatory. A board without AP provisioning can reach `READY_TO_PORT` through another available method when credentials remain outside source control and a reprovisioning path is defined.
+Select one evidenced Wi-Fi credential method from SoftAP, BLE, SmartConfig, secure factory/NVS provisioning, development configuration, or a documented custom path. SoftAP is not mandatory. A board without AP provisioning can reach `READY_TO_PORT` through another available method when credentials remain outside source control and a reprovisioning path is defined. When SoftAP is selected, implement and record the fixed [SoftAP product contract](hardware-ir.md#softap-product-contract).
 
 Development configuration may inject credentials through an untracked sdkconfig, environment, or provisioning artifact. Treat committed plaintext credentials as `BLOCKED`. Never copy SSIDs/passwords into Hardware IR, reports, examples, or source.
 

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

@@ -61,6 +61,10 @@ WIFI_METHOD_TYPES = {
     "development_config",
     "custom",
 }
+SOFTAP_SSID_PREFIX = "TiRTC-"
+SOFTAP_AUTH_MODE = "open"
+SOFTAP_IPV4_ADDRESS = "192.168.6.1"
+SOFTAP_CAPTIVE_PORTAL = True
 BINDING_METHOD_TYPES = {
     "verification_code",
     "factory_bound",
@@ -444,6 +448,14 @@ def validate_onboarding(
                 errors.append(
                     f"{prefix}.type must be one of " + ", ".join(sorted(WIFI_METHOD_TYPES))
                 )
+            if method_type == "softap":
+                for field in ("ssid_prefix", "auth_mode", "ipv4_address"):
+                    nullable_string(method.get(field), f"{prefix}.{field}", errors)
+                nullable_bool(
+                    method.get("captive_portal"),
+                    f"{prefix}.captive_portal",
+                    errors,
+                )
             nullable_bool(method.get("available"), f"{prefix}.available", errors)
             validate_verification(
                 method.get("verification"), f"{prefix}.verification", errors
@@ -926,6 +938,27 @@ def wifi_requirement(onboarding: dict[str, Any]) -> Requirement:
         return "NEEDS_CONFIRMATION", "selected Wi-Fi method availability is unknown", 0
     if available is False:
         return "BLOCKED", "selected Wi-Fi method is unavailable", 0
+    if method.get("type") == "softap":
+        softap_fields = (
+            ("ssid_prefix", SOFTAP_SSID_PREFIX, "SSID prefix"),
+            ("auth_mode", SOFTAP_AUTH_MODE, "authentication mode"),
+            ("ipv4_address", SOFTAP_IPV4_ADDRESS, "IPv4 address"),
+            ("captive_portal", SOFTAP_CAPTIVE_PORTAL, "captive portal"),
+        )
+        for field, expected, label in softap_fields:
+            value = method.get(field)
+            if value is None:
+                return (
+                    "NEEDS_CONFIRMATION",
+                    f"SoftAP {label} is unknown; expected {expected!r}",
+                    0,
+                )
+            if value != expected:
+                return (
+                    "BLOCKED",
+                    f"SoftAP {label} must be {expected!r}, got {value!r}",
+                    0,
+                )
     verification = method.get("verification")
     level = VERIFICATION_LEVELS.get(verification, 0)
     if level < VERIFICATION_LEVELS["corroborated"]: