tirtc-device-builder 0.5.0 → 0.7.0

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 This project follows Semantic Versioning.
 
+## 0.7.0
+
+- Separate the platform/Web video contract (MJPEG, H.264, and H.265 on stream 11) from the single codec profile selected by a board; keep the LCKFB ESP32-S3 adapter on MJPEG without narrowing platform capability.
+- Add a mandatory runtime semantic gate for service-endpoint wiring, callback-safe lifecycle changes, exact downlink media filtering, authoritative AI session-format validation, and remote session termination.
+- Reject invented, concatenated, absolute, missing, or hash-mismatched Hardware IR source locators and verify recorded build artifacts against the actual project-relative files.
+- Treat the entire ESP-IDF `build/` tree as non-portable, retain verified deliverable copies under `artifacts/`, and strengthen Doctor handling and negative regression tests.
+- Package the hardened generated starter and platform/runtime contracts in ESP32 Device Kit 1.1.1.
+
+## 0.6.0
+
+- Add project-local audio and video semantic contracts that verify codec clock tables, I2S/TDM topology, selected video framing, dependency locks, scheduler isolation, sensor policy, and memory/backpressure before an artifact can reach `BUILD_VERIFIED`.
+- Require build assessment hashes to match `build_evidence.artifacts[]`, and propagate requested-feature failures to the project gate without downgrading an existing `BLOCKED` result.
+- Add portable CMake gate installers, source-export checks, a clean-room LCKFB ESP32-S3 prompt, and regression coverage for MJPEG, H.264, and H.265 video contracts.
+- Distinguish compiler success from capability verification and document source-only transfer to another machine.
+
 ## 0.5.0
 
 - Split Hardware IR assessment into explicit `intake`, `build`, and `hil` phases so implementation- and build-resolvable facts do not require runtime proof before adapter work begins.

package/README.md

@@ -12,7 +12,7 @@ TiRTC Device Builder 用于把 ESP32-S3 开发板接入 TiRTC。输入可以只
 
 - 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 Device Kit：[kit-esp32s3-v1.1.1](https://github.com/tangeai/tirtc-device-builder/releases/tag/kit-esp32s3-v1.1.1)
 
 文档导航：
 
@@ -70,7 +70,7 @@ Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex
 
 ### 4. 把板卡和目标告诉 Codex
 
-把你已经掌握的信息填进下面的提示词即可，不用先查齐所有硬件参数。路径请使用绝对路径，不确定的内容写“未知”。可直接复制的版本见[开发板接入提示词](skills/tirtc-esp32-builder/assets/developer-intake-prompt.md)。
+把你已经掌握的信息填进下面的提示词即可，不用先查齐所有硬件参数。先指定工作区根目录，本地路径尽量相对工作区填写；不确定的内容写“未知”。可直接复制的版本见[开发板接入提示词](skills/tirtc-esp32-builder/assets/developer-intake-prompt.md)。
 
 ```text
 请使用 $tirtc-esp32-builder 完成这块开发板的 TiRTC 移植。
@@ -79,18 +79,21 @@ Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex
 - 厂商、完整型号、PCB/硬件版本：<填写>
 - 资料与手中实物是否对应：<是/否/未知>
 
+工作区：<本机目录；以下本地路径均相对此目录>
+
 资料：
 - <原理图、BSP/厂商示例、数据手册或产品页；一行一个>
 
 目标：
 - 功能：<例如 H5 实时音视频、H5 对讲、AI 双向语音>
-- 视频：<MJPEG/H264/H265/根据合同和硬件证据选择>
+- 平台/Web 视频：MJPEG、H264、H265
+- 板级视频选择：<MJPEG/H264/H265/根据硬件证据选择一种>
 - Wi-Fi：<指定方案/根据 BSP 选择>
 - 设备绑定：<指定方案/根据平台合同选择>
 
-工程：<输出目录或现有工程的绝对路径>
+工程：<输出目录或现有工程的工作区相对路径>
 
-请先运行 Doctor，分析全部资料并生成 Hardware IR v2。把未知项区分为可由资料、实现、构建或 HIL 解决，以及必须由用户补充的阻塞项。READY_TO_PORT 表示资料足以开始设计，不要求最终 ELF；随后生成、适配和编译，以 artifact SHA-256 运行 build 阶段评估，并输出 TIRTC_PORTING_REPORT.md。
+请先运行 Doctor，分析全部资料并生成 Hardware IR v2。把未知项区分为可由资料、实现、构建或 HIL 解决，以及必须由用户补充的阻塞项。READY_TO_PORT 表示资料足以开始设计，不要求最终 ELF；随后生成、适配和编译，运行项目内 runtime、音频和视频语义门禁，把项目内 artifacts/ 的真实大小与 SHA-256 写入 build_evidence 后执行 build 阶段评估，并输出 TIRTC_PORTING_REPORT.md。
 本轮不访问串口、不烧录、不擦除 NVS；缺少串口只让 L2-L7 记为 SKIP，不得阻止 L0/L1。不要把任何凭证写入源码或报告。
 ```
 
@@ -137,6 +140,7 @@ Skill 负责：
 - 生成并校验 `hardware-ir.json`，把冲突和未知项留在报告里；
 - 判断视频、上行音频、下行播放和 AI 会话是否具备移植条件；
 - 生成带 TiRTC SDK 的独立 ESP-IDF 工程；
+- 核验发现地址、SDK callback 生命周期、下行格式过滤和 AI 会话响应等运行协议不变量；
 - 把摄像头、所选 MJPEG/H.264/H.265 路径、麦克风、Codec、I2S、功放和按键接到板级 adapter；
 - 运行测试和 `idf.py build`，记录固件路径、版本和 SHA-256；
 - 在用户明确给出芯片、工程和串口后烧录；
@@ -243,7 +247,7 @@ board-materials/
 | ESP-IDF | 5.5.x |
 | 自动安装版本 | ESP-IDF v5.5.4 |
 | TiRTC SDK | `espressif-esp32s3/2.3.0` |
-| ESP32 Device Kit | 1.0.0 |
+| ESP32 Device Kit | 1.1.1 |
 | Node.js | 18 或更高版本 |
 | 支持自动安装的系统 | Linux、WSL、macOS |
 | 原生 Windows | 使用 Espressif 官方安装器准备 ESP-IDF，再重新运行检查 |
@@ -282,7 +286,7 @@ H5 和 AI 的端到端验收还需要可访问的 ThingConnect 服务、可用
 
 ### 媒体约束
 
-H5 视频要先从前端和服务端支持的合同中选择一种 profile。MJPEG 提交完整 JPEG 帧；H.264/H.265 按合同提交 Annex-B access unit、参数集，并实现刷新或关键帧控制。板上有摄像头 Sensor，只能证明图像有来源，不能证明浏览器一定能持续出图。
+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 对讲。
 
@@ -325,7 +329,7 @@ npx --yes tirtc-device-builder@latest install esp32
 |---|---|
 | Codex Skill | `${CODEX_HOME:-~/.codex}/skills/tirtc-esp32-builder` |
 | 托管根目录 | `~/.tirtc-device-builder` |
-| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.0.0` |
+| Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.1` |
 | ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
 | Espressif 工具 | `~/.tirtc-device-builder/espressif` |
 | 安装记录 | `~/.tirtc-device-builder/config.json` |
@@ -370,7 +374,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.0.0.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.1.tar.gz
 ```
 
 安装器仍会核对固定的 SHA-256、目录结构、清单和每个资源文件，不接受未经验证的同名压缩包。
@@ -462,7 +466,7 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess \
 | `NEEDS_CONFIRMATION` | 当前阶段的关键事实未知、冲突或证据等级不足 | 按资料、实现、构建、HIL 或用户输入来源继续闭环 |
 | `BLOCKED` | 现有硬件或 SDK 已确认不满足 | 更换硬件，补编码/播放路径，或取得匹配 SDK |
 | `READY_TO_PORT` | 资料足以开始生成和板级实现 | 进入工程生成与编译 |
-| `BUILD_VERIFIED` | 精确 artifact 通过源码、编译和 post-link 门禁 | 记录 BIN/ELF SHA-256；按授权进入实机验收 |
+| `BUILD_VERIFIED` | 精确 artifact 通过 runtime、音频、视频、源码、编译和 post-link 门禁 | 记录项目内 BIN/ELF 的真实大小与 SHA-256；按授权进入实机验收 |
 | `HIL_VERIFIED` | 已完成端到端实机验证 | 固定版本并保存证据 |
 
 `assess --strict` 在条件不足时返回非零，这是门禁在阻止过早生成，不代表脚本损坏。
@@ -472,7 +476,8 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess \
 ```bash
 python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess \
   /absolute/path/hardware-ir.json \
-  --phase build --artifact-sha256 <64-character-sha256> --strict
+  --phase build --project /absolute/path/generated-project \
+  --artifact-sha256 <64-character-sha256> --strict
 
 python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess \
   /absolute/path/hardware-ir.json \
@@ -503,14 +508,19 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/doctor.py \
   --project /absolute/path/my-esp32-device
 ```
 
-`TiRTC build contract` 为 `PASS` 后编译：
+`TiRTC build contract` 为 `PASS` 后，先执行 `idf.py reconfigure` 锁定依赖。根据 [音频合同](skills/tirtc-esp32-builder/references/audio-contract.md) 和 [视频合同](skills/tirtc-esp32-builder/references/video-contract.md) 生成、核验并安装请求能力对应的项目内门禁，再编译：
 
 ```bash
 cd /absolute/path/my-esp32-device
 idf.py set-target esp32s3
+idf.py reconfigure
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/install_audio_gate.py .
+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`。
+
 生成器会把 TiRTC SDK 复制到工程的 `third_party/tirtc/`。此后工程不再依赖 `tirtc-server-example`，但换机编译仍需准备兼容的 ESP-IDF 5.5.x 工具链。
 
 检查尚未完成的产品适配点：
@@ -606,7 +616,7 @@ Wi-Fi 配网和 ThingConnect 设备绑定是两套独立流程。绑定可以选
 |---|---|
 | L-1 Environment | Doctor 必需项和项目构建契约通过 |
 | L0 Generate | 新工程和 Hardware IR 存在，没有覆盖旧目录 |
-| L1 Build | `idf.py build` 成功，固件和 SHA-256 已记录 |
+| L1 Build | 请求能力的语义门禁与 `idf.py build` 均成功，固件和已登记 SHA-256 通过 build assessment |
 | L2 Boot | 指定串口烧录成功，无 panic 或反复重启 |
 | L3 Online | 所选 Wi-Fi 凭证和设备绑定流程、MQTT 与 TiRTC 就绪 |
 | L4 Media | 摄像头、麦克风、扬声器的本地路径和计数正常 |
@@ -627,6 +637,8 @@ Wi-Fi 配网和 ThingConnect 设备绑定是两套独立流程。绑定可以选
 
 任务只做到生成和编译时，报告应明确停在 L1。
 
+换机前先创建排除 `build/`、`managed_components/` 和 `.git` 的源码交付副本，再运行 `project_portability.py <source-only-export> --export`。只交付源码、依赖锁和工程内 TiRTC SDK，不携带包含原机器绝对路径的构建缓存。
+
 ## 常见问题
 
 ### 找不到 `node`、`npm` 或 `npx`
@@ -728,7 +740,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.0.0.tar.gz
+  --kit-archive /absolute/path/tirtc-esp32s3-kit-1.1.1.tar.gz
 ```
 
 安装器会校验 SHA-256 和内部文件清单。如果校验不一致，请重新获取官方 Release 附件，不要跳过校验。
@@ -840,40 +852,28 @@ 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.0.0
+  --kit-version 1.1.1
 ```
 
 输出位于 `dist/`：
 
 ```text
-tirtc-esp32s3-kit-1.0.0.tar.gz
-tirtc-esp32s3-kit-1.0.0.tar.gz.sha256
+tirtc-esp32s3-kit-1.1.1.tar.gz
+tirtc-esp32s3-kit-1.1.1.tar.gz.sha256
 ```
 
-校验后使用独立的 `kit-esp32s3-v<version>` 标签发布 GitHub Release：
+校验后推送独立的 `kit-esp32s3-v<version>` 标签。`publish-kit.yml` 会从 metadata 固定的上游 commit 重建压缩包、核对 SHA-256，并使用 GitHub Actions token 创建 Release：
 
 ```bash
-gh --version
-gh release --help
-
 cd dist
-sha256sum -c tirtc-esp32s3-kit-1.0.0.tar.gz.sha256
+sha256sum -c tirtc-esp32s3-kit-1.1.1.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 工程生成资源。"
+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
 ```
 
-`gh release --help` 如果提示 `No such command 'release'`，当前系统安装的不是 GitHub 官方 CLI。先按 [GitHub CLI 官方安装说明](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) 安装或替换，再登录并发布 Release。
+metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地可复现打包结果一致；工作流不会从浮动的 `main` 取发布内容。
 
 ### 发布 npm
 
@@ -881,8 +881,8 @@ gh release create kit-esp32s3-v1.0.0 \
 
 ```bash
 npm test
-git tag -a v0.5.0 -m "v0.5.0"
-git push origin v0.5.0
+git tag -a v0.7.0 -m "v0.7.0"
+git push origin v0.7.0
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/esp32-kit-metadata.js

@@ -1,8 +1,9 @@
 export const ESP32_KIT = Object.freeze({
-  archiveName: "tirtc-esp32s3-kit-1.0.0.tar.gz",
-  archiveRoot: "tirtc-esp32s3-kit-1.0.0",
-  releaseTag: "kit-esp32s3-v1.0.0",
-  sha256: "d2333878ae499a349b125cd81db0a64aef62bfae8fd7c0898c8eaa5ff2a49b65",
-  url: "https://github.com/tangeai/tirtc-device-builder/releases/download/kit-esp32s3-v1.0.0/tirtc-esp32s3-kit-1.0.0.tar.gz",
-  version: "1.0.0",
+  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",
 });

package/bin/install-esp32-kit.js

@@ -22,6 +22,8 @@ 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",
   "device-sim/sdk/espressif-esp32s3/2.3.0/include/tirtc/tiRTC.h",
   "device-sim/sdk/espressif-esp32s3/2.3.0/lib/libTiRTC.a",
   "device-sim/sdk/espressif-esp32s3/2.3.0/manifest/build-contract.env",

package/package.json

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

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

@@ -22,13 +22,13 @@ Before stopping on `NEEDS_CONFIRMATION`, classify every unresolved fact as `sour
 
 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. A camera sensor alone does not establish H5 video support; validate the user-selected MJPEG, H.264, or H.265 profile end to end. Choose half duplex for AI when the supplied hardware and BSP do not establish a usable full-duplex/AEC path.
+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.
+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, or post-link gates to `build_verified`. Hash the exact BIN/ELF and run `hardware_ir.py assess --phase build --artifact-sha256 <sha256> --strict`. A design plan at `corroborated` can pass intake but cannot pass the build phase.
+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
 
@@ -40,4 +40,4 @@ For HIL assessment, run `hardware_ir.py assess --phase hil --artifact-sha256 <sh
 
 ## Finish
 
-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.
+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. 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.

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

@@ -72,7 +72,7 @@ $tirtc-esp32-builder 使用 /path/hardware-ir.json 生成工程，编译后烧
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
   --target esp32s3 \
-  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.0.0 \
+  --thing-connect-root ~/.tirtc-device-builder/kits/esp32s3/1.1.1 \
   --require-workspace
 ```
 

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

@@ -0,0 +1,66 @@
+{
+  "schema_version": 1,
+  "evidence": [
+    "exact-board-schematic",
+    "official-codec-datasheet",
+    "official-board-peripheral-example"
+  ],
+  "clock": {
+    "sample_rate_hz": 8000,
+    "mclk_ratio": 512,
+    "mclk_hz": 4096000,
+    "codec_tables": [
+      {
+        "codec": "ES7210",
+        "source": "managed_components/espressif__es7210/es7210.c"
+      },
+      {
+        "codec": "ES8311",
+        "source": "managed_components/espressif__es8311/es8311.c"
+      }
+    ]
+  },
+  "capture": {
+    "controller": 0,
+    "role": "master",
+    "mode": "tdm",
+    "tdm_enabled": true,
+    "slot_count": 4,
+    "slot_order": ["CH1", "CH3", "CH2", "CH4"],
+    "slot_signals": ["MIC1", "PLAYBACK_REFERENCE", "MIC2", "GROUND"],
+    "selected_slot": 0,
+    "selected_signal": "MIC1",
+    "mapping_evidence": "ES7210 Rev 9.1 Figure 2e plus the exact PCB schematic"
+  },
+  "playback": {
+    "controller": 1,
+    "role": "master",
+    "mode": "standard"
+  },
+  "shared_clock": {
+    "gpios": [38, 14, 13],
+    "directions_simultaneous": false,
+    "handoff": "release_before_claim"
+  },
+  "implementation_assertions": [
+    {
+      "file": "components/starter_media/src/starter_media.c",
+      "contains": [],
+      "contains_compact": [
+        "#defineAUDIO_SAMPLE_RATE_HZ8000U",
+        "#defineAUDIO_MCLK_MULTIPLE512U",
+        "#defineI2S_CAPTURE_PORTI2S_NUM_0",
+        "#defineI2S_PLAYBACK_PORTI2S_NUM_1",
+        "#defineES7210_MIC1_TDM_INDEX0U",
+        ".flags.tdm_enable=true",
+        "I2S_TDM_SLOT0|I2S_TDM_SLOT1|I2S_TDM_SLOT2|I2S_TDM_SLOT3",
+        "i2s_channel_reconfig_tdm_gpio",
+        "i2s_channel_reconfig_std_gpio"
+      ],
+      "absent": [],
+      "absent_compact": [
+        ".flags.tdm_enable=false"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,95 @@
+{
+  "schema_version": 1,
+  "platform_contract": "platform-media-contract.json",
+  "evidence": [
+    "lckfb-schematic-v1.0.1",
+    "lckfb-camera-example",
+    "locked-esp32-camera-source",
+    "managed-device-kit-contract"
+  ],
+  "dependencies": {
+    "espressif/esp32-camera": "2.1.7",
+    "idf": "5.5.4"
+  },
+  "scheduler": {
+    "wifi_core": 0,
+    "camera_core": 1,
+    "config_files": [
+      "sdkconfig.defaults",
+      "sdkconfig"
+    ],
+    "wifi_config_files": [
+      "sdkconfig"
+    ]
+  },
+  "camera": {
+    "codec": "mjpeg",
+    "stream_id": 11,
+    "media": "TIRTC_VIDEO_JPEG",
+    "complete_jpeg_per_send": true,
+    "frame_buffers": 2,
+    "accepted_sensor_pids": [
+      155,
+      8517
+    ],
+    "unknown_sensor_policy": "reject"
+  },
+  "memory": {
+    "max_send_buffer_bytes": 262144,
+    "max_complete_jpeg_bytes": 196608,
+    "video_backpressure_bytes": 196608
+  },
+  "implementation_assertions": [
+    {
+      "file": "main/app_main.c",
+      "contains": [],
+      "contains_compact": [
+        ".max_send_buffer_bytes=256U*1024U"
+      ],
+      "absent": [],
+      "absent_compact": [
+        ".max_send_buffer_bytes=1024U*1024U"
+      ]
+    },
+    {
+      "file": "components/starter_media/src/starter_media.c",
+      "contains": [],
+      "contains_compact": [
+        "#defineVIDEO_BACKPRESSURE_BYTES(192U*1024U)",
+        "#defineVIDEO_MAX_COMPLETE_JPEG_BYTES(192U*1024U)",
+        "starter_tirtc_send_buffer_used()>VIDEO_BACKPRESSURE_BYTES",
+        "jpeg_length>VIDEO_MAX_COMPLETE_JPEG_BYTES",
+        "starter_tirtc_send_jpeg((uint32_t)now_ms,jpeg,jpeg_length)>=0",
+        ".pixel_format=PIXFORMAT_RGB565",
+        ".fb_count=2",
+        "frame2jpg(frame,CAMERA_JPEG_QUALITY,&jpeg,&jpeg_length)"
+      ],
+      "absent": [],
+      "absent_compact": []
+    },
+    {
+      "file": "components/starter_media/include/starter_media_camera_policy.h",
+      "contains": [],
+      "contains_compact": [
+        "returnpid==GC0308_PID||pid==GC2145_PID;"
+      ],
+      "absent": [],
+      "absent_compact": []
+    },
+    {
+      "file": "components/starter_tirtc/src/starter_tirtc.c",
+      "contains": [],
+      "contains_compact": [
+        ".stream_id=H5_VIDEO_STREAM",
+        ".media=TIRTC_VIDEO_JPEG",
+        "jpeg[0]!=0xffU",
+        "jpeg[1]!=0xd8U",
+        "jpeg[length-2U]!=0xffU",
+        "jpeg[length-1U]!=0xd9U",
+        "returnTiRtcSendVideoStream(connection,&frame,data);"
+      ],
+      "absent": [],
+      "absent_compact": []
+    }
+  ]
+}

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

@@ -13,12 +13,16 @@ $tirtc-esp32-builder
 - 厂商、完整型号、PCB/硬件版本：<填写>
 - 资料与手中实物是否对应：<是/否/未知>
 
+工作区：
+- 根目录：<本机路径；以下本地路径均相对此目录>
+
 资料：
-- <原理图、BSP/厂商示例、数据手册、产品页等本地绝对路径或固定链接；一行一个>
+- <原理图、BSP/厂商示例、数据手册、产品页等工作区相对路径或固定链接；一行一个>
 
 目标：
 - <例如：H5 实时视频和声音、H5 语音对讲、AI 双向语音对讲>
-- 视频选择：<MJPEG/H264/H265/根据合同和硬件证据选择>
+- 平台/Web 视频能力：<例如 MJPEG、H264、H265；按平台合同填写>
+- 板级视频选择：<MJPEG/H264/H265/根据硬件证据选择一种>
 - 双工或 AEC 的硬要求：<无，初版可半双工/必须全双工或 AEC/未知>
 
 接入方式：
@@ -26,16 +30,17 @@ $tirtc-esp32-builder
 - 设备绑定：<选择一种，或写“根据平台合同选择”>
 
 工程：
-- 输出目录或现有工程：<绝对路径>
+- 输出目录或现有工程：<工作区相对路径；Skill 在报告中记录解析后的绝对路径>
 
 执行要求：
 1. 先运行 Device Kit Doctor，读完全部资料，再生成 Hardware IR v2。没有证据的器件、GPIO 和媒体能力保持未知。
 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. 移植前核对媒体合同、板级资源、静态内存预算、配网和绑定状态。构建后只把源代码、锁定依赖、编译或 post-link 门禁实际证明的事实升级为 build_verified。
-5. 记录 BIN/ELF 路径、大小和 SHA-256，运行 build 阶段评估并输出 TIRTC_PORTING_REPORT.md。编译结果必须与 L2-L7 实机验收分开。
-6. 本轮不访问串口、不烧录、不擦除 NVS；因此缺少启动、浏览器、实体声音和运行时资源数据时，把相应 L2-L7 标为 SKIP，不得阻止 L0/L1。
-7. Wi-Fi 密码、设备密钥、token、私钥和用户音视频不能写入工程或报告。
+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` 或编译成功不能替代门禁。
+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、私钥和用户音视频不能写入工程或报告。
 ```
 
 ## 只有已知时才补充

package/skills/tirtc-esp32-builder/assets/hardware-ir-v2.example.json

@@ -75,6 +75,9 @@
       "controller_and_gpio_ownership_resolved": null,
       "verification": "extracted"
     },
+    "audio_semantic_contract": "board-audio-contract.json",
+    "video_semantic_contract": "board-video-contract.json",
+    "runtime_semantic_contract": "tirtc-runtime-contract.json",
     "audio_channel_mapping": {
       "required": null,
       "resolved": null,
@@ -110,6 +113,9 @@
       "board-materials"
     ]
   },
+  "build_evidence": {
+    "artifacts": []
+  },
   "runtime_evidence": [],
   "features": {
     "requested": [

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

@@ -0,0 +1,80 @@
+$tirtc-esp32-builder
+
+请在当前工作区完成一次立创·实战派 ESP32-S3 的 ThingConnect TiRTC clean-room L-1/L0/L1 接入验证。
+
+这是 Skill、提示词和开发板资料的独立有效性测试。允许访问外网。先运行：
+
+```bash
+npx --yes tirtc-device-builder@0.7.0 setup esp32 --install
+```
+
+允许该命令在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装后必须使用 managed 环境继续执行。
+
+工作区与 clean-room 边界：
+- 将启动 Codex 时的当前目录定义为 `WORKSPACE_ROOT`。
+- 所有工程输入和输出必须位于 `WORKSPACE_ROOT`。
+- 不得读取 `WORKSPACE_ROOT` 之外的项目、兄弟目录、父目录项目、备份、旧构建、日志、报告或 artifact。
+- 如果目标输出目录已经存在，停止并报告 clean-room 条件不成立；不要读取、覆盖或删除该目录。
+
+允许的证据：
+- `WORKSPACE_ROOT/docs/` 中实际存在的全部资料。
+- 开发板厂商官方网站：https://wiki.lckfb.com/zh-hans/szpi-esp32s3/
+- 芯片、组件和 ESP-IDF 厂商官方资料。
+- managed Device Kit 内的 manifest、协议资料、生成器、锁定组件源码和 codec driver table。
+- 本提示词中的板型、实物观察和产品要求属于用户输入，但提示词本身不得作为 clock、GPIO、I2S、TDM、DMA、camera 调度或内存参数的技术证据。
+
+禁止：
+- 不读取任何 `.bak`、旧项目、旧报告、旧 `build/`、日志或历史 artifact。
+- 不使用社区博客、论坛代码或来源不明的示例替代官方证据。
+- 不记录或生成真实 Wi-Fi、设备、MQTT、WHIP 或 AI 凭证。
+- 不访问串口、不烧录、不 monitor、不擦除 NVS。
+- 不为了通过编译而猜测硬件参数、伪造来源或静默关闭请求的功能。
+
+开发板：
+- 立创·实战派 ESP32-S3，PCB V1.0.1。
+- ESP32-S3-WROOM-1-N16R8，16 MB Flash、8 MB Octal PSRAM。
+- `docs/立创实战派ESP32-S3开发板原理图.pdf` 对应手中实物。
+- 厂商页面可能标称 GC0308，但手中实物观测到 PID `0x2145`，对应 GC2145；必须保留该矛盾。
+- 只能接受资料或锁定驱动明确支持的 PID；必须拒绝未知 PID。
+
+媒体合同：
+- ThingConnect 平台和 Web 播放端支持 MJPEG、H.264、H.265；这属于平台能力。
+- 本开发板初版只选择 MJPEG；这是板级输出选择，不得错误写成平台只支持 MJPEG。
+- H5 MJPEG 实时视频和声音、H5 双向语音对讲、AI 双向语音对讲。
+- 每次视频调用必须发送一张完整 JPEG，禁止截断帧或裸分片。
+- 音频 G.711 A-law、8 kHz、mono。
+- stream：H5 上行 10、视频 11、H5 下行 14、AI 1。
+- 初版允许半双工；不得声明未经实机验证的全双工或 AEC。
+
+接入要求：
+- SoftAP 配网，凭证保存 NVS。
+- 验证码绑定，并复用已有绑定。
+- 分别实现 `wifi-clear` 和 `tirtc-clear`。
+- 平台发现本轮先使用 HTTP；HTTPS 留待独立验收。
+
+输出目录：
+- `WORKSPACE_ROOT/lckfb-szpi-esp32s3-tirtc/`
+
+必须完成：
+1. 运行 Device Kit Doctor，记录实际使用的 npm 包、Skill、ESP32 Device Kit、源模板 commit、ESP-IDF、TiRTC SDK、生成器和所有关键组件版本。
+2. 审查 `docs/` 的实际内容，建立“需求—硬件事实—来源—验证等级”证据矩阵。每个来源只能使用一个可解析定位符；不得把提示词、多个文件或绝对机器路径拼成伪来源。
+3. 生成 Hardware IR v2。每个影响功能的 GPIO、clock、I2S controller/mode、codec slot、camera PID、DMA、task/core、frame buffer、内存和 backpressure 参数必须有精确来源。
+4. 对无法从允许证据确认的事实分类为 `source_resolvable`、`implementation_resolvable`、`build_resolvable`、`hil_resolvable` 或 `user_blocked`。只有真正的 `user_blocked` 才停止安全实现；不得用历史工程补证据。
+5. 生成板级 media adapter 和可独立构建的 ESP-IDF 工程。板级常量只进入项目 Hardware IR、合同或 adapter，不得写入通用 Skill。
+6. 音频生成 `board-audio-contract.json`。在 `idf.py reconfigure` 后，直接检查锁定 codec driver table，证明所选 sample rate、MCLK、I2S 模式和 slot 组合受相关 codec 支持；不得使用注释中的典型值代替驱动能力证明。
+7. 视频生成 `board-video-contract.json`，并引用项目内 `platform-media-contract.json`。门禁必须同时证明平台 stream 11 接受 MJPEG/H.264/H.265，以及本板只选择 MJPEG；还要核验锁定 camera 组件支持允许 PID、完整 JPEG 边界、TiRTC JPEG media type、camera/Wi-Fi 调度、frame buffer、最大 JPEG、send buffer、backpressure、PSRAM 和内部 DMA 内存关系。
+8. 生成并验证 `tirtc-runtime-contract.json`，证明发现得到的 `tirtc-srv` 实际传入 SDK、SDK callback 内不直接执行 disconnect/stop/uninit、H5 下行严格过滤 stream 14 与 A-law/8 kHz、AI `start_session` 严格验证 `session_id` 和输入输出格式、远端 `end_session` 能停止会话。
+9. 用 Skill 的 gate installer 把 runtime、audio、video 三个语义检查接入每次普通 `idf.py build`；合同必须和 adapter 源码及最终 `sdkconfig` 核对。任一适用门禁缺失或失败时，只能报告 `COMPILE_PASS / CAPABILITY_BLOCKED`，不得报告 `BUILD_VERIFIED`。
+10. 执行 `idf.py reconfigure`、全部语义门禁和完整 `idf.py build`。
+11. 将最终 BIN/ELF 复制到项目内 `artifacts/`，记录项目相对路径、实际大小和完整 SHA-256；用同一 SHA-256 执行 build-phase Hardware IR assessment。评估器必须重新读取 artifact 并核对大小和哈希。
+12. build assessment 通过后删除机器绑定的 `build/`，不要再次构建；对源码与 `artifacts/` 交付物运行 `project_portability.py --export`。交付物不得包含旧 `build/` 或本机绝对依赖。
+13. 生成 `TIRTC_PORTING_REPORT.md`，逐项记录 L-1、L0、L1 的 PASS/FAIL/SKIP、完整命令和证据。L2-L7 必须记为 SKIP，不得把编译通过描述成已有实机图像、声音、网络连接或稳定性证据。
+
+报告必须包含“根因归属”章节：
+- 必要硬件事实不在允许资料中：归类为“板卡资料不足”，列出缺失事实和所需官方证据。
+- 资料充分但 Skill 没有读取、校验或正确生成：归类为“Skill 缺陷”。
+- 要求存在歧义、冲突或错误约束：归类为“提示词缺陷”。
+- 只是缺少串口、设备、账号或实机运行证据：归类为“本轮 L2-L7 未执行”，不得错误归责给前三者。
+- 每项结论必须附具体文件、页码、URL、源码位置或命令结果，不能只给主观判断。
+
+即使构建失败，也不要引用历史工程修复。保留失败现场，报告最小阻塞点及下一步所需证据。