add initial AI ball protocol docs

docs/architecture.md

@@ -0,0 +1,72 @@
+# AI球项目架构初稿
+
+本文档描述 AI球项目的初版系统架构，用于后续设备端、PC 上位机、应援脚本、资源包和出厂测试协作对齐。
+
+## 1. 目标
+
+- 支持 AI球设备播放灯效、音效、表情或动作反馈。
+- 支持 PC 上位机进行设备管理、内容同步和测试控制。
+- 支持演唱会/活动现场通过应援脚本驱动多台设备同步表现。
+- 支持资源包分发和版本管理。
+- 支持出厂测试流程记录设备是否合格。
+
+## 2. 模块划分
+
+### 2.1 设备端
+
+设备端运行在 AI球硬件上，负责：
+
+- 接收 PC 上位机或同步播放器下发的控制命令。
+- 管理本地状态机，例如空闲、连接、同步播放、测试、异常。
+- 播放资源包中的灯效、音频、表情或动作资源。
+- 执行出厂自检项目并返回结果。
+
+### 2.2 PC 上位机
+
+PC 上位机用于生产、调试和现场运行：
+
+- 扫描并连接 AI球设备。
+- 下发设备控制命令和同步播放状态。
+- 导入、校验和分发应援脚本及资源包。
+- 执行出厂测试并导出测试报告。
+
+### 2.3 应援脚本
+
+应援脚本描述指定时间点的表现动作：
+
+- 以 `content_id` 标识一场内容或曲目。
+- 以 `time_ms` 表示相对播放时间。
+- 动作类型可包括灯效、音效、表情、震动或组合动作。
+- 脚本应能被 PC 上位机校验，并被设备端按时间轴执行。
+
+### 2.4 资源包
+
+资源包用于承载设备端执行所需资源：
+
+- 包含资源清单、版本号、资源路径和校验信息。
+- 可被 PC 上位机导入并分发到设备。
+- 设备端应校验资源包版本和资源完整性。
+
+### 2.5 出厂测试
+
+出厂测试用于首批设备生产验证：
+
+- 覆盖烧录、自检、屏幕/灯效、喇叭、麦克风、按键、无线充电、通信和应援脚本播放。
+- 每台设备应产生唯一测试记录。
+- 不合格设备应记录失败项和复测结果。
+
+## 3. 初版数据流
+
+1. 内容制作方生成应援脚本和资源包。
+2. PC 上位机导入并校验脚本/资源包。
+3. PC 上位机将资源包分发到 AI球设备。
+4. 演出或测试时，PC 上位机下发同步状态和播放进度。
+5. 设备端根据本地资源和脚本时间轴执行表现动作。
+6. 生产阶段 PC 上位机采集出厂测试结果并生成报告。
+
+## 4. 待确认问题
+
+- 设备端通信链路采用 USB、BLE、Wi-Fi 还是组合方案。
+- 多设备同步精度目标。
+- 资源包压缩格式和签名机制。
+- 出厂测试报告的最终存储位置和格式。

docs/concert_sync_protocol.md

@@ -1,3 +1,58 @@
 # 演唱会播放同步协议
 
-用于定义 PC 同步播放器如何向 AI球同步 content_id、position_ms、state、speed。
+本文档定义 PC 同步播放器如何向 AI球设备同步 `content_id`、`position_ms`、`state` 和 `speed`。
+
+## 1. 目标
+
+- 支持多台 AI球在演唱会或活动现场按同一时间轴执行应援脚本。
+- 支持播放、暂停、停止、跳转和倍速等基础同步控制。
+- 允许设备端根据本地资源包和应援脚本独立执行动作。
+
+## 2. 同步消息
+
+```json
+{
+  "content_id": "concert-demo-001",
+  "state": "playing",
+  "position_ms": 30000,
+  "speed": 1.0,
+  "sent_at_ms": 1710000000000
+}
+```
+
+## 3. 字段说明
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `content_id` | string | 当前曲目、节目或应援内容 ID。 |
+| `state` | string | `playing`、`paused`、`stopped` 之一。 |
+| `position_ms` | integer | 当前内容播放进度，单位毫秒。 |
+| `speed` | number | 播放速度，默认 `1.0`。 |
+| `sent_at_ms` | integer | PC 上位机发送时间戳，用于延迟估计。 |
+
+## 4. 设备端处理流程
+
+1. 校验 `content_id` 是否存在于本地资源包和应援脚本中。
+2. 根据 `state` 进入播放、暂停或停止逻辑。
+3. 使用 `position_ms` 对齐本地脚本时间轴。
+4. 根据 `speed` 调整后续动作触发时间。
+5. 若资源缺失或状态冲突，返回错误码并保持安全状态。
+
+## 5. 同步策略初稿
+
+- PC 上位机应周期性发送同步消息，例如每 500ms 一次。
+- 设备端可根据最近一次消息校准本地播放进度。
+- 当进度跳变超过阈值时，设备端应跳转到新的 `position_ms`。
+- 当状态变为 `stopped` 时，设备端应停止当前表现并清理临时动作。
+
+## 6. 与应援脚本关系
+
+- 应援脚本定义 `time_ms` 和动作内容。
+- 同步协议只负责广播当前播放位置和状态。
+- 设备端根据同步位置选择应执行的脚本动作。
+
+## 7. 待确认问题
+
+- 多设备同步精度目标，例如 50ms、100ms 或 200ms。
+- 时钟同步方案是否需要 NTP、主机时间戳或设备本地校准。
+- 丢包、断连和重连后的补偿策略。

docs/device_api.md

@@ -1,3 +1,79 @@
 # AI球设备控制协议
 
-用于定义上位机、播放器、测试工具如何控制 AI球。
+本文档定义 PC 上位机、同步播放器和测试工具控制 AI球设备的初版 API 约定。
+
+## 1. 设计原则
+
+- 命令结构简单，便于串口、USB、BLE 或网络传输适配。
+- 每条请求应包含 `request_id`，便于上位机匹配响应。
+- 设备响应应包含 `ok`、`error_code` 和必要数据。
+- 不在协议中传输 token、密码或 API key。
+
+## 2. 通用消息格式
+
+### 请求
+
+```json
+{
+  "request_id": "req-001",
+  "command": "device.ping",
+  "params": {}
+}
+```
+
+### 响应
+
+```json
+{
+  "request_id": "req-001",
+  "ok": true,
+  "error_code": null,
+  "data": {}
+}
+```
+
+## 3. 初版命令
+
+| 命令 | 方向 | 用途 |
+| --- | --- | --- |
+| `device.ping` | PC -> 设备 | 检查设备在线状态。 |
+| `device.info` | PC -> 设备 | 读取设备型号、固件版本、序列号。 |
+| `device.state.get` | PC -> 设备 | 读取当前状态机状态。 |
+| `resource.pack.info` | PC -> 设备 | 读取当前资源包信息。 |
+| `resource.pack.prepare` | PC -> 设备 | 准备接收或校验资源包。 |
+| `play.sync` | PC -> 设备 | 下发同步播放状态。 |
+| `play.stop` | PC -> 设备 | 停止当前播放并回到可控状态。 |
+| `factory.test.start` | PC -> 设备 | 开始出厂测试。 |
+| `factory.test.result` | PC -> 设备 | 读取出厂测试结果。 |
+
+## 4. 示例：同步播放
+
+```json
+{
+  "request_id": "req-100",
+  "command": "play.sync",
+  "params": {
+    "content_id": "concert-demo-001",
+    "state": "playing",
+    "position_ms": 12345,
+    "speed": 1.0
+  }
+}
+```
+
+## 5. 错误码初稿
+
+| 错误码 | 说明 |
+| --- | --- |
+| `INVALID_COMMAND` | 未知命令。 |
+| `INVALID_PARAMS` | 参数缺失或格式错误。 |
+| `RESOURCE_NOT_READY` | 资源包未准备好。 |
+| `STATE_CONFLICT` | 当前状态不允许执行该命令。 |
+| `FACTORY_TEST_FAILED` | 出厂测试存在失败项。 |
+| `INTERNAL_ERROR` | 设备内部错误。 |
+
+## 6. 待确认问题
+
+- 传输层帧格式和最大消息大小。
+- 大资源包传输是否独立于控制协议。
+- 设备序列号和生产批次字段格式。

docs/factory_test_spec.md

@@ -1,3 +1,67 @@
 # AI球出厂测试标准
 
-用于定义首批 100 台设备的烧录、自检、屏幕、喇叭、麦克风、按键、无线充电和应援脚本测试标准。
+本文档定义 AI球设备出厂测试的初版项目、流程和判定标准，用于首批设备生产验证。
+
+## 1. 测试目标
+
+- 确认每台设备完成固件烧录和基础配置。
+- 确认核心硬件模块可用。
+- 确认设备能与 PC 上位机通信并执行应援脚本。
+- 输出可追溯的测试结果，区分合格、失败和待复测。
+
+## 2. 测试环境
+
+- PC 上位机测试工具。
+- 标准测试资源包。
+- 标准应援脚本。
+- 设备序列号或生产批次标识。
+
+## 3. 测试项目
+
+| 项目 | 说明 | 初版判定 |
+| --- | --- | --- |
+| 固件烧录 | 写入指定版本固件。 | 版本读取一致。 |
+| 设备自检 | 启动后执行内部自检。 | 返回 `ok=true`。 |
+| 灯效/屏幕 | 显示指定颜色、亮度或图案。 | 观察或传感器检测通过。 |
+| 喇叭 | 播放标准提示音。 | 音频输出正常。 |
+| 麦克风 | 采集测试音频。 | 音量或频率检测达标。 |
+| 按键 | 检测按下和释放事件。 | 事件顺序正确。 |
+| 无线充电 | 检测充电状态。 | 能进入充电状态。 |
+| 通信 | PC 上位机连接和命令往返。 | ping 和 info 命令正常。 |
+| 资源包 | 导入并校验标准资源包。 | 校验成功。 |
+| 应援脚本 | 执行标准脚本片段。 | 动作按时间轴触发。 |
+
+## 4. 测试流程
+
+1. 扫描或录入设备序列号。
+2. 烧录固件并读取版本。
+3. 执行设备自检。
+4. 分项测试灯效/屏幕、喇叭、麦克风、按键和无线充电。
+5. 连接 PC 上位机并执行通信测试。
+6. 下发标准资源包和应援脚本。
+7. 执行短时同步播放测试。
+8. 生成测试结果并标记合格或失败。
+
+## 5. 测试结果格式初稿
+
+```json
+{
+  "device_sn": "AIBALL-000001",
+  "firmware_version": "0.1.0",
+  "result": "pass",
+  "failed_items": [],
+  "tested_at": "2026-01-01T00:00:00Z"
+}
+```
+
+## 6. 失败处理
+
+- 单项失败时记录失败项和错误码。
+- 允许维修后复测，并保留复测次数。
+- 关键项失败的设备不得进入包装流程。
+
+## 7. 待确认问题
+
+- 自动化检测设备的型号和接口。
+- 测试报告最终保存格式：JSON、CSV 或数据库。
+- 首批 100 台设备的抽检和全检策略。

docs/state_machine.md

@@ -1,3 +1,45 @@
 # AI球状态机
 
-用于定义 AI球设备端状态、状态切换和默认反馈。
+本文档定义 AI球设备端的初版状态机，用于统一设备行为、PC 上位机控制和出厂测试流程。
+
+## 1. 状态列表
+
+| 状态 | 说明 |
+| --- | --- |
+| `BOOTING` | 设备启动中，初始化硬件和本地配置。 |
+| `IDLE` | 空闲待机，可被发现或等待连接。 |
+| `CONNECTED` | 已连接 PC 上位机或同步播放器。 |
+| `RESOURCE_READY` | 已完成资源包校验，可执行应援脚本。 |
+| `SYNC_PLAYING` | 正在按同步协议执行应援脚本。 |
+| `PAUSED` | 播放暂停，保留当前进度。 |
+| `FACTORY_TEST` | 正在执行出厂测试。 |
+| `ERROR` | 发生错误，需要上报错误码并等待恢复。 |
+
+## 2. 主要状态切换
+
+| 当前状态 | 事件 | 下一状态 | 说明 |
+| --- | --- | --- | --- |
+| `BOOTING` | 初始化成功 | `IDLE` | 设备完成启动。 |
+| `IDLE` | 建立连接 | `CONNECTED` | PC 上位机接入。 |
+| `CONNECTED` | 资源包校验成功 | `RESOURCE_READY` | 可进入同步播放。 |
+| `RESOURCE_READY` | 收到播放命令 | `SYNC_PLAYING` | 根据 `content_id` 和 `position_ms` 开始执行。 |
+| `SYNC_PLAYING` | 收到暂停命令 | `PAUSED` | 暂停当前表现。 |
+| `PAUSED` | 收到继续命令 | `SYNC_PLAYING` | 从指定进度继续。 |
+| 任意状态 | 进入出厂测试 | `FACTORY_TEST` | 生产或维修流程触发。 |
+| 任意状态 | 发生严重错误 | `ERROR` | 记录错误码并停止危险动作。 |
+| `ERROR` | 重置成功 | `IDLE` | 清理错误后恢复待机。 |
+
+## 3. 设备端默认行为
+
+- 进入 `BOOTING` 时执行硬件初始化和配置加载。
+- 进入 `IDLE` 时关闭非必要高功耗模块。
+- 进入 `SYNC_PLAYING` 时按应援脚本时间轴触发动作。
+- 进入 `FACTORY_TEST` 时禁止普通播放命令干扰测试流程。
+- 进入 `ERROR` 时上报错误码，并尽量保持安全可恢复状态。
+
+## 4. 与其他模块关系
+
+- PC 上位机负责触发连接、资源分发、播放控制和出厂测试。
+- 应援脚本定义 `SYNC_PLAYING` 状态下的时间轴动作。
+- 资源包必须在 `RESOURCE_READY` 前完成完整性校验。
+- 出厂测试应覆盖主要状态切换是否可靠。

schemas/call_script_schema.json

@@ -1,23 +1,65 @@
 {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "AI Ball Call Script Schema",
+  "description": "Initial schema for AI球 concert/support call scripts executed by devices according to a playback timeline.",
   "type": "object",
-  "required": ["content_id", "title", "duration_ms", "actions"],
+  "additionalProperties": false,
+  "required": ["content_id", "title", "version", "duration_ms", "actions"],
   "properties": {
-    "content_id": { "type": "string" },
-    "title": { "type": "string" },
-    "duration_ms": { "type": "integer" },
+    "content_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique content or song identifier."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "duration_ms": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "resource_pack_id": {
+      "type": "string",
+      "description": "Optional expected resource pack id."
+    },
     "actions": {
       "type": "array",
       "items": {
         "type": "object",
+        "additionalProperties": false,
         "required": ["time_ms", "type", "value"],
         "properties": {
-          "time_ms": { "type": "integer" },
-          "type": { "type": "string" },
-          "value": { "type": "string" },
-          "duration_ms": { "type": "integer" },
-          "intensity": { "type": "number" },
-          "silent_alt": { "type": "string" }
+          "time_ms": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "type": {
+            "type": "string",
+            "enum": ["light", "sound", "expression", "vibration", "combo"]
+          },
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Resource id, preset name, or simple command value."
+          },
+          "duration_ms": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "intensity": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "silent_alt": {
+            "type": "string",
+            "description": "Fallback behavior when sound output should be muted."
+          }
         }
       }
     }

schemas/resource_pack_schema.json

@@ -1,19 +1,53 @@
 {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "AI Ball Resource Pack Schema",
+  "description": "Initial schema for AI球 resource packs used by devices and the PC host application.",
   "type": "object",
+  "additionalProperties": false,
   "required": ["pack_id", "version", "resources"],
   "properties": {
-    "pack_id": { "type": "string" },
-    "version": { "type": "string" },
+    "pack_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "target_firmware": {
+      "type": "string",
+      "description": "Optional compatible firmware version or range."
+    },
+    "description": {
+      "type": "string"
+    },
     "resources": {
       "type": "array",
       "items": {
         "type": "object",
+        "additionalProperties": false,
         "required": ["id", "type", "path"],
         "properties": {
-          "id": { "type": "string" },
-          "type": { "type": "string" },
-          "path": { "type": "string" }
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "type": {
+            "type": "string",
+            "enum": ["audio", "image", "animation", "light_preset", "expression", "other"]
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[A-Fa-f0-9]{64}$"
+          },
+          "size_bytes": {
+            "type": "integer",
+            "minimum": 0
+          }
         }
       }
     }