From ce2d71d22ef7e97676d9cbdaf9d09df5bc60ed35 Mon Sep 17 00:00:00 2001
From: zijunchiang <miyu@kasugano.cn>
Date: Mon, 14 Sep 2026 19:02:39 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=9D=E5=A7=8B=E5=8C=96=E5=8D=A0?=
 =?UTF-8?q?=E4=BD=8D=E8=AF=B4=E6=98=8E=E4=B8=8E=E5=A5=91=E7=BA=A6=E4=BE=9D?=
 =?UTF-8?q?=E8=B5=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dddc325
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# opendance-android
+
+OpenDance Studio **阶段三**：Android 辅助 App（Kotlin + MediaPipe 端侧推理）。
+
+> **状态：占位仓库**。按《DSH 开发文档：OpenDance Studio》的开发顺序
+> （Web 服务端 → Windows 客户端 → Android 辅助 App），本仓库将在阶段二
+> （`opendance-windows`）冻结 WebSocket 关键点协议后开始开发。
+
+## 计划技术栈
+
+| 组件 | 选型 |
+|---|---|
+| 语言 | Kotlin |
+| 相机 | CameraX (Apache 2.0) |
+| 推理 | MediaPipe Pose (Apache 2.0) |
+| 通信 | OkHttp WebSocket (Apache 2.0) |
+| UI | Jetpack Compose (Apache 2.0) |
+
+## 计划任务
+
+`T-AND-001` 骨架 → `T-AND-002` CameraX 采集 → `T-AND-003` MediaPipe Pose 推理 →
+`T-AND-004` 33 点 → 239 字节帧序列化 → `T-AND-005` WebSocket 推流 + 自动重连 →
+`T-AND-006` 连接页 + 主机发现 → `T-AND-007` 运行页 + 状态指示 →
+`T-AND-008` 关于页 + 开源声明 → `T-AND-009` APK 打包
+
+## 依赖的契约（已冻结于 opendance-web，v0.1.0）
+
+- `contracts/websocket-keypoints.md` — **239 字节关键点帧**编码规则（本端为发送方）
+  - 帧头 8 字节：`magic(u16)=0x4F44` + `version(u8)=1` + `flags(u8)` + `frame_id(u32)`
+  - 33 点 × 7 字节：`x(i16) y(i16) z(i16) conf(u8)`，小端序，归一化系数 32767
+  - 文本控制帧：`hello` / `welcome` / `config` / `stats` / `bye`
+- `contracts/skeleton-topology.md` — MediaPipe 33 点顺序与坐标语义（**顺序一旦冻结不得重排**）
+- `contracts/open-source-credits.md` — 关于页必须展示的开源声明（三端共用）
+
+契约地址：https://gitea.kasugano.cn/zijunchiang/opendance-web/src/branch/main/contracts
+
+参考实现：`opendance-web/web-server/src/preprocess/keypoint-codec.ts` 中的
+`encodeBinaryFrame()` 即本端序列化器的权威参考。
+
+**任何跨端契约变更必须先回到 `opendance-web` 修改 `contracts/` 并提升版本**，
+再在本仓库创建适配任务。
+
+## 关键约束
+
+- 仅使用 MediaPipe 33 点拓扑，**不使用 SMPL**（规避非商用许可限制）
+- 本端不做评分与渲染：只负责采集、端侧推理、编码、推流
+- 视频帧不离开设备，仅发送 33 个关键点
+- 发布产物必须包含关于页开源声明
\ No newline at end of file