tirtc-device-builder 0.11.4 → 0.11.5

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.11.4",
-  "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
+  "version": "0.11.5",
+  "description": "Codex workflows for building, validating, and documenting TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",
     "url": "https://github.com/tangeai"
@@ -34,7 +34,8 @@
       "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."
+      "Assess whether this board can support H5 live view and AI intercom.",
+      "Create a user-facing documentation system for my multi-board TiRTC project."
     ]
   }
 }

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 This project follows Semantic Versioning.
 
+## 0.11.5
+
+- Add the `tirtc-project-docs` Skill for designing and reviewing public
+  documentation in multi-board TiRTC and XiaoTai repositories.
+- Define stable roles for quick-start, architecture, contribution, board and
+  media documents, with evidence grading and approval-first bilingual output.
+- Add `install docs` support and package tests for installing the documentation
+  Skill across supported Agent clients.
+
 ## 0.11.4
 
 - Add artifact-bound BK7258 H5, AI and WeChat VoIP media lessons: directional

package/README.md

@@ -2,12 +2,13 @@
 
 TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 和 BK7258/BK7259 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Agent Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
 
-当前仓库提供两个平台 Skill：
+当前仓库提供两个平台 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 | 运行时硬件探测、显示/触摸/音频/内存能力判定、小钛业务移植与实机验收 |
+| `tirtc-project-docs` | TiRTC / 小钛多开发板项目 | 快速体验、架构、贡献、板卡、构建烧录和音视频参数文档；中文版确认后同步英文版 |
 
 BK7258 多媒体项目固定从 Beken 官方 Gitee `bk_avdk_smp` 的
 `release/v3.1.1.8` tag、commit
@@ -108,6 +109,19 @@ npx --yes tirtc-device-builder@latest doctor beken \
 其中 BK7258 的公开基准应是 `release/v3.1.1.8`、commit
 `1cfd56af09a3cb6470f35f1e0c604035ed1b6ee7`。
 
+#### 项目文档
+
+需要建立、检查或维护 TiRTC/小钛项目文档时，安装
+`tirtc-project-docs`：
+
+```bash
+npx --yes tirtc-device-builder@latest install docs
+```
+
+该 Skill 会先按仓库事实整理中文版，检查根文档导航、板卡目录、构建烧录说明、
+媒体参数和证据等级。只有中文版确认通过后，才同步生成英文版。它不会把日期型排障
+记录或迁移历史混入对外使用手册。
+
 ### 3. 重新打开 Agent 客户端
 
 Skill 通常在 Agent 会话启动时被发现。安装完成后，关闭当前会话，再打开一个新会话。

package/bin/tirtc-device-builder.js

@@ -48,6 +48,14 @@ const PLATFORMS = new Map([
       summary: "BK7258 / BK7259 / Beken Armino",
     },
   ],
+  [
+    "docs",
+    {
+      aliases: new Set(["docs", "documentation", "tirtc-project-docs"]),
+      skill: "tirtc-project-docs",
+      summary: "TiRTC / XiaoTai project documentation",
+    },
+  ],
 ]);
 
 function printHelp() {
@@ -56,19 +64,21 @@ function printHelp() {
 Usage:
   tirtc-device-builder list
   tirtc-device-builder clients
-  tirtc-device-builder install <platform> [--client <name>] [--skills-dir <path>] [--force]
+  tirtc-device-builder install <target> [--client <name>] [--skills-dir <path>] [--force]
   tirtc-device-builder setup <platform> [setup options]
   tirtc-device-builder doctor <platform> [doctor options]
   tirtc-device-builder boards <platform> <list|validate|match|init-identity|candidate> [options]
   tirtc-device-builder --version
 
-Platforms:
+Install targets:
   esp32       ESP32-S3 / ESP-IDF 5.5.x
   beken       BK7258 / BK7259 / Beken Armino
+  docs        TiRTC / XiaoTai project documentation
 
 Examples:
   npx tirtc-device-builder install esp32
   npx tirtc-device-builder install beken
+  npx tirtc-device-builder install docs
   npx tirtc-device-builder install esp32 --client qwen-code
   npx tirtc-device-builder setup esp32
   npx tirtc-device-builder setup esp32 --install --client gemini
@@ -274,9 +284,15 @@ function main(args) {
   }
 
   if (command === "doctor") {
+    if (platform.name === "docs") {
+      return fail("doctor is not available for target: docs");
+    }
     return runDoctor(platform, rest);
   }
   if (command === "boards") {
+    if (platform.name === "docs") {
+      return fail("boards is not available for target: docs");
+    }
     return runBoardRegistry(platform, rest);
   }
   if (command === "setup") {

package/package.json

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

package/skills/tirtc-beken-builder/VERSION

@@ -1 +1 @@
-0.11.4
+0.11.5

package/skills/tirtc-esp32-builder/VERSION

@@ -1 +1 @@
-0.11.4
+0.11.5

package/skills/tirtc-project-docs/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: tirtc-project-docs
+description: Design, audit, and maintain bilingual documentation systems for TiRTC or XiaoTai multi-board firmware repositories. Use for quick-start READMEs, architecture and contribution guides, board catalogs, build/flash instructions, media parameters, navigation/link checks, or Chinese-to-English synchronization; exclude code-only work and historical status logs.
+---
+
+# TiRTC Project Documentation
+
+Build a documentation system that lets a first-time user run the product, lets
+a developer extend it, and gives an agent reliable pointers into repository
+truth. Documentation describes the current product and supported workflows;
+dated investigations and migration diaries belong in an ignored local history
+area when the repository defines one.
+
+## Establish the contract
+
+1. Read repository guidance such as `AGENTS.md`, the existing documentation
+   index, glossary, documentation contract, board architecture, and build/test
+   entrypoints. Project rules override this Skill.
+2. Inventory existing public documents before adding files. Preserve useful
+   paths and repair their role when possible; do not create a parallel document
+   tree for the same audience.
+3. Identify the requested phase: Chinese drafting, Chinese review, English
+   synchronization, or audit. When the user requests Chinese approval first,
+   stop after the verified Chinese result. Do not create English placeholders.
+4. Map every technical claim to a source. Read
+   [evidence and technical claims](references/evidence.md) when the work covers
+   hardware, media, tools, builds, releases, or validation status.
+
+## Select the document layer
+
+Read [document architecture](references/document-architecture.md) when adding,
+splitting, renaming, or reorganizing documents.
+
+- Root `README.md` is the quick-experience path: identify the board, download
+  the matching release artifact, flash it safely, provision it, and try the
+  principal product flows.
+- Root `ARCHITECTURE.md` explains product capabilities, module interfaces,
+  runtime/media flows, repository responsibilities, and secondary-development
+  entrypoints for both humans and agents.
+- Root `CONTRIBUTING.md` explains environment setup, tests, evidence, adding a
+  board or platform, and the submission workflow.
+- `docs/README.md` is the complete task-oriented index.
+- `docs/boards/README.md` catalogs every board; each board has one independently
+  usable guide under `docs/boards/<board-id>/README.md`.
+- Product, development, and board details stay in their subject directories.
+  Root documents summarize and link instead of copying those details.
+
+Keep a compact navigation line at the top of every public root document. Every
+link must resolve from that file, and all root documents must expose the same
+destinations in the same order.
+
+## Draft from repository truth
+
+Write the minimum information needed at the selected layer. Prefer stable
+interfaces, responsibilities, commands, and decision points over source-tree
+tourism. Explain an unavoidable acronym on first use. Keep one topic per
+paragraph and make commands, warnings, status, and next actions easy to scan.
+
+Use available specialist Skills when they materially apply:
+
+- `research` for facts that require official external sources and citations;
+- `codebase-design` for module interfaces, seams, adapters, and extension paths;
+- `domain-modeling` when canonical terms are missing or conflict;
+- `writing-for-agents` for `AGENTS.md`, Skill instructions, and agent-facing
+  pointers;
+- `humanizer-zh` as the final Chinese prose review after facts are stable.
+
+Their absence must not block ordinary maintenance. Preserve the same outcomes:
+primary sources, explicit interfaces, consistent terms, actionable pointers,
+and natural restrained Chinese.
+
+## Verify before translation
+
+Check every changed command against current scripts or `--help`, every local
+link against the filesystem, every board identifier against its manifest, and
+every download/flash instruction against the release artifact manifest. Run the
+repository's documentation, manifest, and host-test gates. A passing structure
+test does not upgrade build evidence into hardware proof.
+
+Review the Chinese documents for facts, terminology, navigation, paragraph
+shape, and duplicated sources of truth. Present the Chinese result for approval
+when requested. Completion for this phase means all requested Chinese documents
+and checks are complete, with English files still untouched.
+
+## Synchronize English after approval
+
+Read [bilingual synchronization](references/bilingual.md) only after the
+Chinese source has been approved. Translate meaning rather than sentence order,
+preserve commands and identifiers exactly, rebuild relative navigation for the
+English files, and rerun the same checks. Record intentional locale differences
+instead of silently dropping Chinese-only instructions.
+
+## Report the result
+
+List the documents created or changed, the sources used for claims, checks run,
+and unresolved evidence gaps. Separate missing documentation from unsupported
+features. Do not present an unverified artifact, inferred pin map, or stale test
+result as a current product capability.

package/skills/tirtc-project-docs/VERSION

@@ -0,0 +1 @@
+0.11.5

package/skills/tirtc-project-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TiRTC Project Docs"
+  short_description: "维护 TiRTC 多开发板项目的中英文文档与证据边界"
+  default_prompt: "Use $tirtc-project-docs to design or audit my TiRTC project documentation, write and verify the Chinese source first, and generate English only after Chinese approval."

package/skills/tirtc-project-docs/references/bilingual.md

@@ -0,0 +1,37 @@
+# Bilingual synchronization
+
+Use this reference only after the project owner has approved the Chinese source.
+
+## File policy
+
+Keep Chinese as the source language unless the repository declares another
+policy. Use stable English siblings such as `README.en.md`,
+`ARCHITECTURE.en.md`, and `CONTRIBUTING.en.md`. Subject documents may use the
+same suffix convention or separate language trees, but one repository should
+use one convention.
+
+Add language selectors only after both targets exist. The Chinese root
+navigation points to Chinese destinations; the English navigation points to
+English destinations where available and to a clearly labelled Chinese page
+only when no English counterpart exists.
+
+## Translation rules
+
+- Preserve commands, paths, board IDs, artifact names, checksums, log fragments,
+  configuration keys, and protocol constants exactly.
+- Use official English vendor and product names. Do not translate identifiers.
+- Translate the meaning and reader task, not Chinese word order.
+- Keep warnings, evidence qualifications, limitations, and follow-up items at
+  the same strength as the Chinese source.
+- Explain acronyms on first use in each independently readable document.
+- Recheck relative links because an English sibling can have different targets.
+
+## Drift review
+
+Compare section coverage rather than raw line count. Every Chinese section must
+have an English counterpart or a recorded locale-specific reason. Verify tables
+row by row, then rerun link, manifest, documentation, and host-test gates.
+
+Translation is complete when the English reader can perform the same supported
+task and sees the same capability and evidence status as the approved Chinese
+reader.

package/skills/tirtc-project-docs/references/document-architecture.md

@@ -0,0 +1,58 @@
+# Document architecture
+
+Use this reference when deciding where information belongs or when a repository
+has accumulated duplicate guides.
+
+## Entry hierarchy
+
+The root is a small set of durable entrypoints:
+
+| Document | Reader question | Content boundary |
+| --- | --- | --- |
+| `README.md` | How do I run this now? | Board choice, release download, safe flashing, provisioning, first experience |
+| `ARCHITECTURE.md` | How does it work and where do I extend it? | Product flows, module interfaces, data/lifecycle paths, repository responsibilities |
+| `CONTRIBUTING.md` | How do I make and verify a change? | Environment, tests, evidence, board/platform intake, submission checks |
+| `docs/README.md` | Where is the complete documentation? | Task-oriented index to product, development, board, test, and reference material |
+
+Do not turn the root README into a complete hardware manual. It may show a
+compact card or table for a small set of primary boards. Each row links to the
+release artifact and the board's full guide. As the catalog grows, keep only the
+primary boards in the root and link the complete catalog.
+
+## Detail ownership
+
+- `docs/product/` owns current user-visible behavior, interaction, protocols,
+  and media contracts.
+- `docs/development/` owns architecture details, toolchains, builds, tests,
+  porting, release mechanics, and AI-assisted development.
+- `docs/boards/<board-id>/` owns model-specific specifications, dependencies,
+  schematics, build/flash steps, first use, verification, and limitations.
+- `boards/<vendor>/<board>/` owns build-participating board facts and a short
+  pointer README when the repository uses this layout.
+- `references/` indexes external SDKs, schematics, examples, and datasheets that
+  are inputs rather than maintained product documentation.
+- Local ignored history owns dated investigations and superseded status
+  snapshots. Public documents state only current behavior and current limits.
+
+## Root navigation
+
+Place navigation immediately after the title or language selector. Keep it
+short and identical across public root documents. A typical Chinese set is:
+
+```markdown
+[快速体验](README.md) · [架构与二次开发](ARCHITECTURE.md) ·
+[参与开发](CONTRIBUTING.md) · [完整文档](docs/README.md)
+```
+
+Add language links only when the target files exist and have passed review.
+Do not publish dead “English coming soon” links.
+
+## Single-source rule
+
+Summaries may repeat a conclusion, but volatile values have one owner. Board
+memory, SDK version, stream identifiers, sample rates, checksums, and build
+commands should be read from manifests, contracts, lock files, release
+metadata, or their designated documentation owner. Other pages link there.
+
+When duplication is unavoidable for a quick-start step, keep the detailed page
+authoritative and add a test that detects drift in the copied value.

package/skills/tirtc-project-docs/references/evidence.md

@@ -0,0 +1,70 @@
+# Evidence and technical claims
+
+Read this reference when documentation states hardware facts, product
+capabilities, media parameters, build requirements, release contents, or test
+status.
+
+## Source order
+
+Use the closest authoritative source:
+
+1. Product behavior and protocol contracts in the maintained product source or
+   product documentation.
+2. Board manifest for identity and build metadata.
+3. Hardware IR, schematic, probe report, or vendor primary source for wiring,
+   fitted devices, memory, clocks, buses, and power sequencing.
+4. Lock files, SDK manifests, compiler output, and build scripts for toolchain
+   and dependency versions.
+5. Release manifest and checksums for downloadable artifacts and flash layout.
+6. Artifact-bound hardware-in-the-loop evidence for runtime claims.
+
+A board manifest is build metadata, not proof that hardware or a product flow
+worked. A successful compile is not a hardware validation result. Evidence from
+one printed-circuit-board revision does not automatically apply to another.
+
+## Board guide minimum
+
+Each supported board guide should independently explain:
+
+- exact public model and printed-circuit-board revision;
+- processor, memory, display, touch, camera, audio, and network specifications;
+- product functions and technical media parameters;
+- operating system, SDK, compiler, libraries, and locked versions;
+- official product page, schematic, and source identity;
+- root-level build command and expected artifacts;
+- safe flash method, offsets, boot mode, and protected factory data;
+- provisioning, binding, and first product experience;
+- verification level, artifact identity, limitations, and explicit follow-up
+  evidence.
+
+Use `unknown` or a clearly scoped follow-up item when a fact lacks evidence.
+Do not fill gaps from a visually similar board or another board using the same
+processor.
+
+## Media and session details
+
+For each H5, AI, device-call, WeChat VoIP, or room flow that the project claims,
+document the applicable direction and parameters:
+
+- stream identifiers;
+- encoding, sample rate, channel count, frame duration, samples and payload
+  relationship;
+- video format, resolution, frame rate, target bitrate, keyframe/refresh rule;
+- AEC input, playback reference, processing frame, delay treatment, and modes
+  where AEC is required;
+- ownership, readiness, stop, reconnect, and resource-release behavior.
+
+Network packet duration and an AEC processing block are different units. State
+both when software splits or aggregates them.
+
+## Release download and flashing
+
+Quick-start pages link to an immutable release or a release selector that makes
+board identity explicit. A release bundle should carry its board ID, version,
+source revision, files, flash offsets, verification status, and SHA-256 values.
+Explain the difference between complete flash images and over-the-air images.
+
+Never infer a flash command from a filename alone. Read the bundle manifest or
+the board's authoritative flash guide, and preserve calibration, credentials,
+keys, and factory partitions unless the product process explicitly replaces
+them.