From 40e184cc6c0626faaab94745ed3682a218abe744 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= <zheromiku@example.com>
Date: Thu, 18 Jun 2026 16:55:47 +0800
Subject: [PATCH] add initial protocol docs and schemas

---
 docs/concert_sync_protocol.md     |  3 +++
 docs/device_api.md                |  3 +++
 docs/factory_test_spec.md         |  3 +++
 docs/state_machine.md             |  3 +++
 schemas/call_script_schema.json   | 25 +++++++++++++++++++++++++
 schemas/resource_pack_schema.json | 21 +++++++++++++++++++++
 6 files changed, 58 insertions(+)
 create mode 100644 docs/concert_sync_protocol.md
 create mode 100644 docs/device_api.md
 create mode 100644 docs/factory_test_spec.md
 create mode 100644 docs/state_machine.md
 create mode 100644 schemas/call_script_schema.json
 create mode 100644 schemas/resource_pack_schema.json

diff --git a/docs/concert_sync_protocol.md b/docs/concert_sync_protocol.md
new file mode 100644
index 0000000..5a531d2
--- /dev/null
+++ b/docs/concert_sync_protocol.md
@@ -0,0 +1,3 @@
+# 演唱会播放同步协议
+
+用于定义 PC 同步播放器如何向 AI球同步 content_id、position_ms、state、speed。
diff --git a/docs/device_api.md b/docs/device_api.md
new file mode 100644
index 0000000..f7ab4a7
--- /dev/null
+++ b/docs/device_api.md
@@ -0,0 +1,3 @@
+# AI球设备控制协议
+
+用于定义上位机、播放器、测试工具如何控制 AI球。
diff --git a/docs/factory_test_spec.md b/docs/factory_test_spec.md
new file mode 100644
index 0000000..eef2604
--- /dev/null
+++ b/docs/factory_test_spec.md
@@ -0,0 +1,3 @@
+# AI球出厂测试标准
+
+用于定义首批 100 台设备的烧录、自检、屏幕、喇叭、麦克风、按键、无线充电和应援脚本测试标准。
diff --git a/docs/state_machine.md b/docs/state_machine.md
new file mode 100644
index 0000000..560ac5c
--- /dev/null
+++ b/docs/state_machine.md
@@ -0,0 +1,3 @@
+# AI球状态机
+
+用于定义 AI球设备端状态、状态切换和默认反馈。
diff --git a/schemas/call_script_schema.json b/schemas/call_script_schema.json
new file mode 100644
index 0000000..b392b74
--- /dev/null
+++ b/schemas/call_script_schema.json
@@ -0,0 +1,25 @@
+{
+  "title": "AI Ball Call Script Schema",
+  "type": "object",
+  "required": ["content_id", "title", "duration_ms", "actions"],
+  "properties": {
+    "content_id": { "type": "string" },
+    "title": { "type": "string" },
+    "duration_ms": { "type": "integer" },
+    "actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "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" }
+        }
+      }
+    }
+  }
+}
diff --git a/schemas/resource_pack_schema.json b/schemas/resource_pack_schema.json
new file mode 100644
index 0000000..aecc9d2
--- /dev/null
+++ b/schemas/resource_pack_schema.json
@@ -0,0 +1,21 @@
+{
+  "title": "AI Ball Resource Pack Schema",
+  "type": "object",
+  "required": ["pack_id", "version", "resources"],
+  "properties": {
+    "pack_id": { "type": "string" },
+    "version": { "type": "string" },
+    "resources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "path"],
+        "properties": {
+          "id": { "type": "string" },
+          "type": { "type": "string" },
+          "path": { "type": "string" }
+        }
+      }
+    }
+  }
+}