tirtc-device-builder 0.10.1 → 0.11.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",
@@ -13,6 +13,9 @@
     "tirtc",
     "esp32",
     "esp-idf",
+    "beken",
+    "bk7258",
+    "bk7259",
     "embedded",
     "ai-intercom"
   ],
@@ -29,6 +32,7 @@
     ],
     "defaultPrompt": [
       "Analyze my ESP32 board and generate a TiRTC project.",
+      "Probe my BK7258 or BK7259 board and assess XiaoTai capabilities.",
       "Check ESP-IDF and build my TiRTC ESP32 firmware.",
       "Assess whether this board can support H5 live view and AI intercom."
     ]

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 This project follows Semantic Versioning.
 
+## 0.11.0
+
+- Add the `tirtc-beken-builder` Skill and CLI platform aliases for BK7258 and
+  BK7259, covering evidence-first board intake, SDK pinning, hardware
+  capability reports and XiaoTai feature gating.
+- Add a BK7258 `bk_avdk_smp` release/v3.1.1 on-device probe component plus a
+  host collector, schema validator and deterministic capability assessor for
+  display/touch, speaker/microphone formats, Flash and memory diagnostics.
+- Document a separate BK7259 release/v4.0.1 adapter boundary instead of
+  assuming BK7258/BK7259 peripheral or ABI compatibility, and package Doctor,
+  fixtures, tests and official-source research with the Skill.
+
 ## 0.10.1
 
 - Add a knowledge-only Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3-C V1.0 package

package/README.md

@@ -2,11 +2,17 @@
 
 TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Agent Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立的 ESP-IDF 工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
 
-当前仓库提供一个 Skill：
+当前仓库提供两个平台 Skill：
 
 | Skill | 平台 | 主要用途 |
 |---|---|---|
 | `tirtc-esp32-builder` | ESP32-S3 / ESP32-P4、ESP-IDF 5.5.x | 板型识别、Hardware IR、工程生成/移植、H5/AI/设备互呼/微信 VoIP、AEC 门禁、编译烧录和分层验收 |
+| `tirtc-beken-builder` | BK7258 / BK7259、Beken Armino | 运行时硬件探测、显示/触摸/音频/内存能力判定、小钛业务移植与实机验收 |
+
+BK7258 多媒体项目优先从 Beken 官方 `bk_avdk_smp` 的正式
+`release/v3.1.1.x` tag 开始；移动的 `release/v3.1.1` 分支用于需要最新
+维护改动的开发。BK7259 使用前应按官方支持矩阵选择对应 release，不把
+BK7258 的 BSP、分区或二进制直接套用。
 
 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 预编译库。
 

package/bin/tirtc-device-builder.js

@@ -34,6 +34,20 @@ const PLATFORMS = new Map([
       summary: "ESP32-S3 / ESP-IDF 5.5.x",
     },
   ],
+  [
+    "beken",
+    {
+      aliases: new Set([
+        "beken",
+        "bk",
+        "bk7258",
+        "bk7259",
+        "tirtc-beken-builder",
+      ]),
+      skill: "tirtc-beken-builder",
+      summary: "BK7258 / BK7259 / Beken Armino",
+    },
+  ],
 ]);
 
 function printHelp() {
@@ -50,9 +64,11 @@ Usage:
 
 Platforms:
   esp32       ESP32-S3 / ESP-IDF 5.5.x
+  beken       BK7258 / BK7259 / Beken Armino
 
 Examples:
   npx tirtc-device-builder install esp32
+  npx tirtc-device-builder install beken
   npx tirtc-device-builder install esp32 --client qwen-code
   npx tirtc-device-builder setup esp32
   npx tirtc-device-builder setup esp32 --install --client gemini

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Install and run TiRTC device-development Agent Skills across popular coding clients.",
   "license": "MIT",
   "author": {
@@ -38,6 +38,9 @@
     "tirtc",
     "esp32",
     "esp-idf",
+    "beken",
+    "bk7258",
+    "bk7259",
     "embedded",
     "ai-intercom"
   ],
@@ -52,7 +55,7 @@
     "pack:esp32-kit": "node scripts/pack-esp32-kit.js",
     "test": "npm run test:node && npm run test:python && npm run validate && npm run validate:tarball && npm run test:package",
     "test:node": "node --test test/*.test.js",
-    "test:python": "python3 -m unittest discover -s skills/tirtc-esp32-builder/scripts -p 'test_*.py'",
+    "test:python": "python3 -m unittest discover -s skills/tirtc-esp32-builder/scripts -p 'test_*.py' && python3 -m unittest discover -s skills/tirtc-beken-builder/scripts -p 'test_*.py'",
     "validate": "python3 scripts/validate_package.py",
     "validate:tarball": "node scripts/validate-tarball.js",
     "test:package": "node scripts/test-packed-package.js",

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

@@ -0,0 +1,128 @@
+---
+name: tirtc-beken-builder
+description: Diagnose, port, build, flash, and validate XiaoTai/TiRTC firmware for BK7258, BK7259, and closely related Beken boards using an official Beken SDK project, board evidence, and on-device probes. Use for display/touch, microphone/speaker, Flash/RAM, media/AEC capability, or XiaoTai H5/AI/call integration; exclude ESP32 projects and unsupported guesswork from a SoC name alone.
+---
+
+# TiRTC Beken Builder
+
+Turn a physical BK board into an evidence-backed XiaoTai port. A probe report is
+the boundary between documentation hypotheses and what the exact firmware saw on
+the exact board. Never infer carrier-board wiring, fitted peripherals, or PCB
+revision from `BK7258`/`BK7259` alone.
+
+Read [architecture](references/architecture.md) when planning a new product or
+explaining the platform split and delivery stages.
+Read [BK probe research](references/bk-research.md) when selecting an SDK line,
+implementing a probe, or checking the primary-source basis for an API.
+
+## 1. Establish the target
+
+1. Read this Skill's `VERSION`, then read
+   [hardware diagnostics](references/hardware-diagnostics.md) and
+   [TiRTC integration](references/tirtc-integration.md).
+2. Record the exact board model/PCB marking, SoC, official SDK or BSP repository
+   and revision, toolchain, bootloader/partition layout, and the requested
+   XiaoTai features. Keep unavailable facts `null`.
+3. Prefer the board vendor's working SDK project. Treat a similar board's pin
+   map only as a hypothesis. Preserve its bootloader, partition table, RF
+   calibration, secure-boot data, and factory data unless the user explicitly
+   authorizes changing them.
+4. Inspect the selected SDK headers and examples before naming APIs. Beken SDK
+   branches differ; source-visible symbols in the pinned checkout outrank prose
+   and this Skill. Start discovery from <https://docs.bekencorp.com/> and
+   <https://github.com/bekencorp/>, then pin the concrete page and revision.
+
+Run the read-only environment check when a checkout is available:
+
+```bash
+python3 <skill-dir>/scripts/doctor.py --sdk-root <bk_avdk_smp>
+```
+
+## 2. Build the diagnostic firmware
+
+Follow [probe porting](references/probe-porting.md). Add a small diagnostic task
+to the known-working board project and implement the adapter against that pinned
+SDK. It emits one framed JSON object beginning with `TIRTC_BK_PROBE `.
+
+Probe in three layers:
+
+- **Intrinsic:** chip/revision, Flash JEDEC ID and usable partition bytes, SRAM
+  and optional PSRAM totals/free/largest block.
+- **Enumerated:** compiled board profile, initialized LCD/touch/audio drivers,
+  controller or codec identities, buses, dimensions and advertised formats.
+- **Active:** LCD pattern, touch coordinates, microphone capture statistics,
+  speaker test tone, simultaneous capture/playback, playback reference and AEC.
+
+Use targeted, BSP-approved buses and addresses. Generic GPIO toggling, blind
+bus scans, destructive Flash writes, and audio output without an explicit test
+action are outside discovery. A linked driver is `declared`; only a successful
+runtime transaction is `detected`, and only an active observation is `verified`.
+
+Collect and assess the report:
+
+```bash
+python3 <skill-dir>/scripts/bk_probe_report.py init probe-report.json
+python3 <skill-dir>/scripts/bk_probe_report.py collect serial.log probe-report.json
+python3 <skill-dir>/scripts/bk_probe_report.py validate probe-report.json
+python3 <skill-dir>/scripts/bk_probe_report.py assess probe-report.json
+```
+
+The probe run is complete when every required field is a measured value,
+explicitly unsupported, or an `unknown` with a named next action. Compilation is
+not evidence that a peripheral exists.
+
+## 3. Decide the product shape
+
+Read [capability rules](references/capability-rules.md). Run assessment before
+porting business code. Preserve separate conclusions for display-only UI,
+touch UI, button/voice control, H5 uplink, H5 talkback, AI conversation, device
+call, and WeChat VoIP.
+
+Do not manufacture a click UI for a display without verified touch. Prefer a
+status/voice UI; use buttons only when the enclosure exposes enough verified
+controls and the product interaction has an unambiguous mapping. Missing screen
+or touch does not by itself block audio-only XiaoTai.
+
+AI and call flows require simultaneous capture/playback, a physical playback
+reference, and an evidenced AEC implementation. A half-duplex demo may prove
+basic audio but cannot certify duplex conversation.
+
+## 4. Integrate XiaoTai
+
+Keep one process-wide TiRTC lifecycle and reuse the stable product architecture:
+Router -> Arbiter -> Coordinator. SDK callbacks copy bounded events and return;
+one state-owning task performs HTTP/MQTT, connection lifecycle, generation
+checks and monotonic deadlines.
+
+Put LCD/touch, microphone, codec, amplifier, audio DMA, camera, buttons, memory
+pools and AEC behind a Beken board adapter. Keep service discovery, credentials,
+stream IDs, negotiated formats and H5/AI/CALL/VOIP state outside board code.
+
+First prove business protocol behavior with the repository's Linux C reference
+when it is available. Then bind the pinned Beken TiRTC library/header and build
+contract. If no compatible Beken TiRTC binary exists, report `BLOCKED_SDK_ABI`;
+do not substitute an ESP32 archive or claim source compatibility.
+
+## 5. Build and verify
+
+Build with the exact vendor toolchain and board project. Record the application
+artifact path, version, byte size and SHA-256. Flash only after the user names
+the exact device and authorizes it; preserve factory partitions by default.
+
+Re-run the diagnostic report in the same product firmware because standalone
+probe results do not prove final memory margin or driver coexistence. Verify
+startup, network/onboarding, local media, each requested XiaoTai flow, session
+switching/recovery, weak network, and stability separately. Bind runtime results
+to the exact artifact SHA-256 and mark each `PASS`, `FAIL`, or `SKIP`.
+
+Return the pinned SDK/BSP revision, probe report, contradictions, capability
+matrix, integration changes, exact artifact identity, HIL results, and remaining
+blockers. Promote a board profile for reuse only after the exact PCB revision
+and its required active probes pass.
+
+## Security boundary
+
+Keep device keys, Wi-Fi passwords, MQTT/WHIP tokens, certificates, calibration
+data, MAC-derived identifiers and captured user audio outside source and reports.
+Redact logs. Downloads, account access, flashing, erasing, factory-partition
+changes and publishing a reusable board profile retain separate authorization.

package/skills/tirtc-beken-builder/VERSION

@@ -0,0 +1 @@
+0.11.0

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TiRTC Beken Builder"
+  short_description: "诊断 BK7258/BK7259 硬件并集成小钛业务"
+  default_prompt: "Use $tirtc-beken-builder to probe my BK7258/BK7259 board, assess supported XiaoTai features, and create an evidence-backed TiRTC port."

package/skills/tirtc-beken-builder/assets/bk-avdk-smp-v3.1.1/tirtc_bk_probe.c

@@ -0,0 +1,151 @@
+#include "tirtc_bk_probe.h"
+
+#include <driver/flash.h>
+#include <driver/lcd.h>
+#include <driver/tp.h>
+#include <modules/chip_support.h>
+#include <os/os.h>
+
+#if CONFIG_SOC_BK7258
+#define TIRTC_BK_SOC "BK7258"
+#else
+#error "this probe asset is for the BK7258 bk_avdk_smp v3.1.1 line"
+#endif
+
+__attribute__((weak)) const void *tirtc_bk_probe_active_lcd(void)
+{
+    return NULL;
+}
+
+__attribute__((weak)) bool tirtc_bk_probe_audio(tirtc_bk_audio_snapshot_t *out)
+{
+    (void)out;
+    return false;
+}
+
+__attribute__((weak)) uint32_t tirtc_bk_probe_application_usable_bytes(void)
+{
+    return 0;
+}
+
+static const char *test_name(tirtc_bk_test_t value)
+{
+    switch (value) {
+    case TIRTC_BK_TEST_PASS:
+        return "pass";
+    case TIRTC_BK_TEST_FAIL:
+        return "fail";
+    default:
+        return "not_run";
+    }
+}
+
+static void emit_endpoint(const tirtc_bk_audio_endpoint_t *endpoint)
+{
+    if (!endpoint->present) {
+        os_printf("{\"state\":\"unknown\",\"method\":null,\"source\":null,"
+                  "\"channels\":null,\"sample_rates_hz\":[],\"sample_bits\":[],"
+                  "\"formats\":[],\"test\":\"not_run\"}");
+        return;
+    }
+    os_printf("{\"state\":\"detected\",\"method\":\"board_audio_adapter\","
+              "\"source\":\"pinned-bsp\",\"channels\":%u,"
+              "\"sample_rates_hz\":[%u],\"sample_bits\":[%u],"
+              "\"formats\":[\"pcm_s16le\"],\"test\":\"%s\"}",
+              endpoint->channels, (unsigned)endpoint->sample_rate_hz,
+              endpoint->sample_bits, test_name(endpoint->test));
+}
+
+void tirtc_bk_probe_emit(void)
+{
+    const lcd_device_t *lcd = (const lcd_device_t *)tirtc_bk_probe_active_lcd();
+    tp_device_t *tp = bk_tp_get_device();
+    tirtc_bk_audio_snapshot_t audio = {0};
+    bool has_audio = tirtc_bk_probe_audio(&audio);
+    uint32_t app_bytes = tirtc_bk_probe_application_usable_bytes();
+
+    os_printf("TIRTC_BK_PROBE {");
+    os_printf("\"schema_version\":1,\"artifact_sha256\":null,");
+    os_printf("\"identity\":{\"soc\":\"%s\",\"chip_revision\":\"%u\","
+              "\"board_model\":null,\"pcb_revision\":null,"
+              "\"sdk\":{\"name\":\"bk_avdk_smp\",\"version\":null,"
+              "\"revision\":null},\"board_config_sha256\":null},",
+              TIRTC_BK_SOC, (unsigned)bk_get_hardware_chip_id_version());
+    os_printf("\"flash\":{\"state\":\"measured\","
+              "\"method\":\"bk_flash_get_id/current_total_size\","
+              "\"source\":\"runtime\",\"jedec_id\":\"0x%08x\","
+              "\"recognized\":null,\"physical_bytes\":null,"
+              "\"mapped_bytes\":%u,\"application_usable_bytes\":",
+              (unsigned)bk_flash_get_id(),
+              (unsigned)bk_flash_get_current_total_size());
+    if (app_bytes) {
+        os_printf("%u},", (unsigned)app_bytes);
+    } else {
+        os_printf("null},");
+    }
+    os_printf("\"memory\":{\"internal_sram\":{\"state\":\"measured\","
+              "\"total_bytes\":%u,\"free_boot_bytes\":%u,"
+              "\"minimum_free_bytes\":%u,\"largest_free_block_bytes\":null},",
+              (unsigned)rtos_get_total_heap_size(),
+              (unsigned)rtos_get_free_heap_size(),
+              (unsigned)rtos_get_minimum_free_heap_size());
+    os_printf("\"psram\":{\"state\":\"measured\",\"present\":%s,"
+              "\"total_bytes\":%u,\"free_boot_bytes\":%u,"
+              "\"minimum_free_bytes\":%u,\"largest_free_block_bytes\":null}},",
+              rtos_get_psram_total_heap_size() ? "true" : "false",
+              (unsigned)rtos_get_psram_total_heap_size(),
+              (unsigned)rtos_get_psram_free_heap_size(),
+              (unsigned)rtos_get_psram_minimum_free_heap_size());
+
+    if (lcd) {
+        os_printf("\"display\":{\"state\":\"detected\","
+                  "\"method\":\"active-board-lcd\",\"source\":\"pinned-bsp\","
+                  "\"controller\":null,\"bus\":null,\"width_px\":%u,"
+                  "\"height_px\":%u,\"width_mm\":null,\"height_mm\":null,"
+                  "\"pixel_format\":null,\"test\":\"not_run\"},",
+                  lcd->width, lcd->height);
+    } else {
+        os_printf("\"display\":{\"state\":\"unknown\",\"method\":null,"
+                  "\"source\":null,\"controller\":null,\"bus\":null,"
+                  "\"width_px\":null,\"height_px\":null,\"width_mm\":null,"
+                  "\"height_mm\":null,\"pixel_format\":null,"
+                  "\"test\":\"not_run\"},");
+    }
+
+    if (tp) {
+        os_printf("\"touch\":{\"state\":\"detected\","
+                  "\"method\":\"bk_tp_get_device\",\"source\":\"runtime\","
+                  "\"controller\":null,\"bus\":\"i2c\",\"points\":%u,"
+                  "\"test\":\"not_run\"},", tp->tp_num);
+    } else {
+        os_printf("\"touch\":{\"state\":\"unknown\",\"method\":null,"
+                  "\"source\":null,\"controller\":null,\"bus\":null,"
+                  "\"points\":null,\"test\":\"not_run\"},");
+    }
+
+    os_printf("\"camera\":{\"state\":\"unknown\",\"method\":null,"
+              "\"source\":null,\"sensor\":null,\"output_profiles\":[],"
+              "\"test\":\"not_run\"},\"audio\":{\"microphone\":");
+    emit_endpoint(&audio.microphone);
+    os_printf(",\"speaker\":");
+    emit_endpoint(&audio.speaker);
+    if (has_audio) {
+        os_printf(",\"duplex\":{\"simultaneous\":%s,\"playback_reference\":%s,"
+                  "\"aec_available\":%s,\"aec_test\":\"%s\"}},",
+                  audio.simultaneous ? "true" : "false",
+                  audio.playback_reference ? "true" : "false",
+                  audio.aec_available ? "true" : "false",
+                  test_name(audio.aec_test));
+    } else {
+        os_printf(",\"duplex\":{\"simultaneous\":null,"
+                  "\"playback_reference\":null,\"aec_available\":null,"
+                  "\"aec_test\":\"not_run\"}},");
+    }
+    os_printf("\"controls\":{\"verified_buttons\":0,"
+              "\"intent_map_approved\":false},\"integration\":{"
+              "\"tirtc_sdk_compatible\":null,\"audio_uplink_pipeline\":null,"
+              "\"audio_downlink_pipeline\":null,\"video_uplink_pipeline\":null,"
+              "\"session_arbiter\":null,\"device_call_protocol\":null,"
+              "\"wechat_voip_protocol\":null},\"requested_features\":[],"
+              "\"issues\":[]}\r\n");
+}

package/skills/tirtc-beken-builder/assets/bk-avdk-smp-v3.1.1/tirtc_bk_probe.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+
+typedef enum {
+    TIRTC_BK_TEST_NOT_RUN = 0,
+    TIRTC_BK_TEST_PASS,
+    TIRTC_BK_TEST_FAIL,
+} tirtc_bk_test_t;
+
+typedef struct {
+    bool present;
+    uint8_t channels;
+    uint32_t sample_rate_hz;
+    uint8_t sample_bits;
+    tirtc_bk_test_t test;
+} tirtc_bk_audio_endpoint_t;
+
+typedef struct {
+    tirtc_bk_audio_endpoint_t microphone;
+    tirtc_bk_audio_endpoint_t speaker;
+    bool simultaneous;
+    bool playback_reference;
+    bool aec_available;
+    tirtc_bk_test_t aec_test;
+} tirtc_bk_audio_snapshot_t;
+
+/* Override these weak hooks in the exact board project. Returning NULL/false
+ * preserves unknown rather than claiming that a peripheral is absent. */
+const void *tirtc_bk_probe_active_lcd(void);
+bool tirtc_bk_probe_audio(tirtc_bk_audio_snapshot_t *out);
+uint32_t tirtc_bk_probe_application_usable_bytes(void);
+
+/* Run after board peripheral initialization. Active speaker/touch tests remain
+ * explicit board commands; this snapshot never plays audio or writes Flash. */
+void tirtc_bk_probe_emit(void);

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

@@ -0,0 +1,16 @@
+请使用 `$tirtc-beken-builder` 诊断并接入这块 BK 开发板。
+
+- 厂商、完整型号、PCB 丝印/版本：
+- SoC（BK7258/BK7259/其他）：
+- 官方 SDK/BSP 路径、仓库 revision：
+- 原理图、BOM、屏幕/触摸/音频器件资料：
+- 已经能运行的 LCD、触摸、录音、播放示例：
+- 目标功能：H5 音频/视频/对讲、AI 对话、设备互呼、微信 VoIP：
+- 输出工程目录：
+
+请先实现并运行程序探测，输出 `probe-report.json`：芯片、Flash、内部
+RAM/PSRAM、显示分辨率与主动色块测试、触摸控制器与坐标测试、麦克风
+实际采集格式与统计、扬声器测试、全双工/回采参考/AEC。把 BSP 声明、
+运行时检出和主动实测分开；未知项不要猜。随后按能力矩阵决定小钛产品
+形态并完成可安全执行的移植和构建。本轮未明确授权时不要烧录、擦除或
+改写工厂分区，不要把凭证或用户音频写入仓库和报告。

package/skills/tirtc-beken-builder/assets/probe-report.example.json

@@ -0,0 +1,73 @@
+{
+  "schema_version": 1,
+  "artifact_sha256": null,
+  "identity": {
+    "soc": "BK7258",
+    "chip_revision": null,
+    "board_model": null,
+    "pcb_revision": null,
+    "sdk": {"name": "Beken SDK", "version": null, "revision": null},
+    "board_config_sha256": null
+  },
+  "flash": {
+    "state": "unknown",
+    "method": null,
+    "source": null,
+    "jedec_id": null,
+    "recognized": null,
+    "physical_bytes": null,
+    "mapped_bytes": null,
+    "application_usable_bytes": null
+  },
+  "memory": {
+    "internal_sram": {"state": "unknown", "total_bytes": null, "free_boot_bytes": null, "minimum_free_bytes": null, "largest_free_block_bytes": null},
+    "psram": {"state": "unknown", "present": null, "total_bytes": null, "free_boot_bytes": null, "minimum_free_bytes": null, "largest_free_block_bytes": null}
+  },
+  "display": {
+    "state": "unknown",
+    "method": null,
+    "source": null,
+    "controller": null,
+    "bus": null,
+    "width_px": null,
+    "height_px": null,
+    "width_mm": null,
+    "height_mm": null,
+    "pixel_format": null,
+    "test": "not_run"
+  },
+  "touch": {
+    "state": "unknown",
+    "method": null,
+    "source": null,
+    "controller": null,
+    "bus": null,
+    "points": null,
+    "test": "not_run"
+  },
+  "camera": {
+    "state": "unknown",
+    "method": null,
+    "source": null,
+    "sensor": null,
+    "output_profiles": [],
+    "test": "not_run"
+  },
+  "audio": {
+    "microphone": {"state": "unknown", "method": null, "source": null, "channels": null, "sample_rates_hz": [], "sample_bits": [], "formats": [], "test": "not_run"},
+    "speaker": {"state": "unknown", "method": null, "source": null, "channels": null, "sample_rates_hz": [], "sample_bits": [], "formats": [], "test": "not_run"},
+    "duplex": {"simultaneous": null, "playback_reference": null, "aec_available": null, "aec_test": "not_run"}
+  },
+  "controls": {"verified_buttons": 0, "intent_map_approved": false},
+  "integration": {
+    "tirtc_sdk_compatible": null,
+    "audio_uplink_pipeline": null,
+    "audio_downlink_pipeline": null,
+    "video_uplink_pipeline": null,
+    "session_arbiter": null,
+    "device_call_protocol": null,
+    "wechat_voip_protocol": null
+  },
+  "requested_features": [],
+  "issues": []
+}

package/skills/tirtc-beken-builder/references/architecture.md

@@ -0,0 +1,75 @@
+# BK7258/BK7259 XiaoTai architecture
+
+This is the implementation plan delivered with the Skill.
+
+## Platform boundary
+
+Keep Beken in an independent Skill because its SDK, AP/CP image layout,
+toolchain, partitions, media drivers and binary ABI differ from ESP32. Reuse
+Hardware IR ideas, evidence grades, the business state model and acceptance
+levels; do not reuse ESP-IDF board code or an ESP32 TiRTC archive.
+
+BK7258 multimedia work starts from official `bk_avdk_smp`. Pin a formal
+`release/v3.1.1.x` tag and match the upper solution tag. Use the moving
+`release/v3.1.1` branch only to evaluate newer maintenance changes. Select
+BK7259 from its own official support matrix and release line.
+
+## Diagnostic pipeline
+
+```text
+documents/schematic/BSP declaration
+               -> compiled driver registry
+               -> read-only runtime probe
+               -> bounded active tests
+               -> probe-report.json
+               -> UI/media/business capability matrix
+               -> Beken adapter + XiaoTai runtime
+               -> artifact-bound HIL
+```
+
+Use `unknown`, `declared`, `detected`, `measured`, `verified`, and
+`unsupported`. Documentation never becomes runtime proof. Preserve
+contradictions and bind active evidence to exact board and firmware identity.
+
+## Product decisions
+
+- A verified display with verified touch may expose a touch UI.
+- A verified display without verified touch exposes status, QR or animation;
+  it has no click targets.
+- Buttons are used only when the physical controls and intent map are verified.
+  Otherwise select voice/headless interaction.
+- Audio-only XiaoTai remains valid without a display.
+- AI conversation and call/VoIP require simultaneous capture/playback, a real
+  playback reference and AEC verified in far-end, near-end and double-talk.
+
+Flash detection reports JEDEC identity, physical bytes and separately usable
+application-partition bytes. Memory reports internal SRAM and PSRAM separately,
+including boot free, minimum free and largest block where supported. Repeat
+measurements in the final firmware's worst requested session.
+
+## Integration seam
+
+Stable modules own provisioning/binding, service discovery, one TiRTC lifecycle,
+HTTP/MQTT, stream contracts, Router -> Arbiter -> Coordinator, generations and
+deadlines. The Beken adapter owns LCD/touch, audio/camera DMA, codecs, amplifier,
+buttons, memory pools and the AEC reference path. Callbacks enqueue bounded
+copies; the state-owning task performs lifecycle and network work.
+
+Before porting, obtain a TiRTC header/library or source package matching the
+Beken CPU ABI, compiler, C library, RTOS and TLS/network stack. With no matching
+package, diagnosis may complete but integration is `BLOCKED_SDK_ABI`.
+
+## Delivery stages
+
+1. Run Doctor against the pinned SDK.
+2. Add the supplied v3.1.1 read-only probe component and board hooks.
+3. Run LCD/touch/capture/playback/duplex active tests and assess the JSON report.
+4. Prove business protocols with the Linux C reference.
+5. Port the Beken adapter and compatible TiRTC package.
+6. Build, hash, and rerun resource/probe measurements in the final image.
+7. With explicit authorization, flash the exact board and verify each requested
+   flow, switching, reconnect, weak network and stability.
+
+The shipped implementation is a reusable diagnosis and decision framework. A
+concrete board still needs its exact model/PCB revision, BSP, pin map or
+schematic, requested businesses and a compatible TiRTC SDK package.