# AGENTS.md — WebRTCController（Android 控制端） 本文件是 `WebRTCController/` 工程的 **AI 协作规则与开发规范**。它是仓库根 `AGENTS.md` 中 Android 控制端条目的细化与补充，**当两者冲突时以本文件为准**（但安全与协议一致性约束始终以根文件最高优先级为准）。 --- ## 一、工程定位 | 项 | 值 | |---|---| | 角色 | **控制端**（观看被控端投屏 + 通过 DataChannel 下发控制指令） | | 应用 ID / namespace | `com.ttstd.controller` | | 主语言 | **Java**（全部源码为 `.java`；Kotlin 插件仅用于注解处理，禁止新增 Kotlin 源文件） | | 语言级别 | Java 8（`sourceCompatibility/targetCompatibility = VERSION_1_8`，`jvmTarget = 1.8`） | | SDK | `compileSdk 34` / `minSdk 24` / `targetSdk 34` | | 构建系统 | Gradle + AGP `8.13.2`（Kotlin 插件仅作注解处理器） | | 构建变体 | `debug` / `release` / `zhanRuiDebug` / `zhanRuiRelease` / `CrosshatchDebug` / `CrosshatchRelease` | | 协议通道 | 信令 = WebSocket + **JSON**；控制指令 = WebRTC DataChannel + **Protobuf 二进制** | --- ## 二、技术栈（当前已采用，遵循 Google 推荐与业内标准） ### 2.1 官方 Jetpack 与 Google 标准库 - **架构组件**：`androidx.lifecycle`（ViewModel / LiveData / LifecycleService）、`androidx.room`（本地持久化）、`androidx.appcompat` + `com.google.android.material`（Material Design 3 基础组件）。 - **安全存储**：`androidx.security:security-crypto:1.1.0`，用于加密保存 `deviceSecret` / `deviceUid` / `accessToken`。**绝不明文 SharedPreferences 或硬编码**。 - **并发 / 异步**：`io.reactivex.rxjava3`（RxJava3 + RxAndroid），配合 `com.trello.rxlifecycle4` 做生命周期自动解绑。禁止裸 `Thread` / `AsyncTask`。 - **图片加载**：`com.github.bumptech.glide:4.15.1`（含 `kapt` 注解处理器）。 - **轻量 KV**：`com.tencent:mmkv-static:2.4.0`（仅用于非敏感运行态缓存；敏感数据必须用 security-crypto）。 ### 2.2 网络与序列化 - **HTTP / REST**：`Retrofit 3.0.0` + `OkHttp 5.3.2`（`logging-interceptor`）+ `converter-gson` + `adapter-rxjava3`。 - **JSON**：`Gson 2.14.0`（信令消息 JSON 解析）。 - **Protobuf**：`com.google.protobuf:protobuf-java:3.25.1`，由 `com.google.protobuf` Gradle 插件按 `*.proto` 生成 Java 类（DataChannel 控制指令二进制）。 - **WebRTC**：`io.github.webrtc-sdk:android:144.7559.09`。 ### 2.3 构建与代码生成 - **DataBinding**：`buildFeatures.dataBinding = true`（视图绑定统一用 DataBinding 或 ViewBinding，避免 `findViewById`）。 - **BuildConfig**：`API_BASE`（HTTP 基址）、`WS_URL`（信令 WebSocket 地址），均为开发占位值，部署时由 flavor / CI 注入。 - **AIDL**：`buildFeatures.aidl = true`（如需跨进程通信）。 > 注：仓库当前使用 `moshi` 依赖但未实际用于信令/指令编解码（信令用 Gson、指令用 Protobuf）。新增 JSON 解析请优先统一到 Gson，避免双序列化栈。 --- ## 三、推荐目录结构（Google 应用架构指南 + 现代 Android 开发） 采用 **单一 Activity + 多 Fragment（Navigation Component）** 的应用结构，按 **UI / Domain / Data** 分层。源码位于 `app/src/main/java/com/ttstd/controller/` 下，建议如下布局： ``` com.ttstd.controller ├── App.java // Application 子类：初始化 MMKV、Room、全局依赖 │ ├── ui/ // 表现层 UI （按 Feature 分包） │ ├── base/ // 基类 │ ├── main/ // 主功能 │ │ ├── MainActivity.java │ │ ├── MainViewModel.java │ │ └── MainUiState.java │ ├── home/ // 首页 / 设备列表 │ │ ├── HomeFragment.java │ │ └── HomeViewModel.java │ ├── control/ // 远程控制界面（投屏观看 + 触控下发） │ │ ├── ControlFragment.java │ │ └── ControlViewModel.java │ ├── login/ // 激活 / 登录 │ └── common/ // 共享 UI（BaseFragment、适配器、自定义 View） │ ├── domain/ // 领域层（可选，纯 Java 用例 / 业务规则） │ ├── model/ // 业务模型（与 data 层实体解耦的纯对象） │ └── usecase/ // 交互器（封装单一业务动作） │ ├── data/ // 数据层 │ ├── local/ // Room（实体、DAO、Database）、MMKV、security-crypto 封装 │ │ ├── db/ // @Entity / @Dao / @Database │ │ ├── secure/ // EncryptedSharedPreferences 封装（凭据存储） │ │ └── pref/ // MMKV 封装（非敏感） │ ├── remote/ // 网络（Retrofit API 接口、WebSocket 信令客户端） │ │ ├── api/ // REST 接口定义 │ │ ├── model/ │ │ └── signaling/ // WebSocket 信令连接与消息收发 │ ├── signaling/ // 信令消息（JSON）数据类 / 解析 │ ├── proto/ // 由 app/src/main/proto/*.proto 生成的指令类 + 编解码封装 │ └── repository/ // 仓储：向 UI 暴露单一数据源（组合 local + remote） │ ├── webrtc/ // WebRTC 封装 │ ├── PeerConnectionClient.java // RTCPeerConnection / SDP / ICE 管理 │ ├── DataChannelManager.java // 控制指令收发（Protobuf 编码） │ ├── WebSocketSignalingClient.java// 信令（JSON） │ └── IceServerProvider.java // ICE 服务器配置 │ ├── controller/ // 远端控制指令业务逻辑 │ ├── CommandDispatcher.java // 指令分发（TOUCH / SWIPE / KEY 等） │ └── ControlCommandFactory.java // 构造 Protobuf 控制指令 │ ├── service/ // 前台 / 后台 Service（如保活、长连接） │ └── SignalingService.java │ ├── receiver/ # 全局 BroadcastReceiver（系统级广播） │ ├── BootCompletedReceiver.java # 开机启动 │ └── NetworkChangeReceiver.java # 网络变化 │ └── utils/ // 工具类（线程、日志、权限、网络状态） ``` **资源目录**（已存在 `app/src/main/res/`）： - `layout/`：Fragment/Activity 布局（DataBinding 布局以 `fragment_xxx.xml` / `activity_xxx.xml` 命名）。 - `navigation/`：NavGraph（`nav_graph.xml`，单一 Activity 路由）。 - `values/`、`drawable/`、`mipmap-*`、`xml/`（网络/备份配置）等按 Android 规范组织。 **Proto 目录**：`app/src/main/proto/*.proto`（与 `WebRTCControlled` 及 Flutter / iOS / Web 端字段号一致）。 ### 分层约束（Google 架构基线） - **单向数据流**：UI 不直接访问 `remote`/`local`，统一经 `repository`。 - **ViewModel 持有状态**：用 `LiveData`/`RxJava` 暴露可观察数据；UI 只负责渲染与事件上报。 - **依赖方向**：`ui → domain → data`，`data` 不反向依赖 `ui`。 - 不要在 `Activity`/`Fragment` 中直接持有 `RTCPeerConnection`；WebRTC 逻辑收敛到 `webrtc/` 包。 --- ## 四、编码规范（Google Java Style + Android 实践） 1. **Java 8 限制**：禁止 `List.of`、`var`、switch 表达式等 Java 9+ API（除非确认脱糖支持）。 2. **架构模式**：UI 用 MVVM（ViewModel + LiveData / RxJava）；单 Activity + Navigation。 3. **视图绑定**：使用 DataBinding / ViewBinding，禁止 `findViewById` 裸用。 4. **异步**：所有后台任务走 RxJava3，`.compose(rxlifecycle)` 绑定生命周期，避免内存泄漏。 5. **网络请求**：统一走 Retrofit 接口 + OkHttp 拦截器；JSON 用 Gson，DataChannel 指令用 Protobuf。 6. **敏感数据**：`deviceSecret` / `deviceUid` / `accessToken` 一律存 `security-crypto` 加密 SP，禁止明文。 7. **线程**：主线程只做 UI；IO / 网络 / 编解码放 `Schedulers.io()` / 子线程。 8. **日志**：使用统一日志工具（带 TAG），发版变体关闭敏感信息输出。 --- ## 五、协议一致性（最高优先级，跨端约束） 本系统为 **1 被控端 + 5 控制端**，协议改动影响面极大： - 信令通道：WebSocket + **JSON**；控制指令通道：WebRTC DataChannel + **Protobuf 二进制**。两者不可混用。 - 修改 `*.proto` 或信令 JSON 字段，**必须同步**：`WebRTCControlled`、`WebRTCController`、`webrtc_controller_flutter`、`webrtc_controller_ios`、`WebRTCControllerWeb`、`WebRTCSignalServer`。 - Protobuf 字段号**只增不改不删**；废弃字段用 `reserved` 标记。 - 指令类型（TOUCH / SWIPE / KEY 等）新增时，在所有端补齐分支处理（`CommandDispatcher` 与各端解析处）。 --- ## 六、安全与配置 - 禁止在源码、`build.gradle`、`config.gradle`、`local.properties` 中硬编码真实密钥、证书口令、生产地址。 - 现有占位值（`http://192.168.5.224:8080`、`ws://192.168.5.224:8080/ws/signal`、签名密码 `123456`/`Fan1996`）为开发默认值，**不要当作正式配置扩散**。 - 签名文件与密码通过 `config.gradle`（外部）注入，不进版本库；`config.gradle` 已含 `keypub`/`crosshatch`/`zhanxun` 三套签名。 - 客户端凭据一律加密存储（本工程：`androidx.security.crypto`）。 --- ## 七、构建与变体 - **构建**：`gradle assembleDebug` / `gradle assembleRelease`；产物名由 `appName()`（`WebRTCController`）+ 版本 + 日期生成。 - **变体说明**： - `debug` / `release`：公开签名 `keypub`。 - `zhanRui*`：展锐平台，使用 `zhanxun` 签名（系统签名场景）。 - `Crosshatch*`：Crosshatch 设备，使用 `crosshatch` 签名（系统签名场景）。 - 修改 `appName()` 返回值会影响既有 CI 产物名，**先确认**。 - 修改签名配置、变体名或系统签名相关（`src/system/AndroidManifest.xml` 等）前**必须先确认**，涉及系统签名固件适配。 --- ## 八、代码修改通用规则 - 优先做**最小化定向修改**，不对既有大文件整体重写或重构。 - 修改前先 `read_file` 当前内容，避免基于陈旧上下文编辑。 - 不主动创建 `*.md` 文档、示例文件或临时脚本；临时产物用完即删。 - Room 实体/DAO 变更**必须提供 Migration**，禁止 `fallbackToDestructiveMigration`。 - 编辑后修复自己引入的 lint / 编译错误。 - 注释与提交说明使用**简体中文**。 - 新增第三方依赖前说明必要性，并锁定版本；不擅自升级 AGP / Gradle / 大版本库。 - 不在 Java 工程中混入 Kotlin 源码（Kotlin 插件仅用于注解处理）。 --- ## 九、禁止事项 - 不改动根目录 `AGENTS.md` 与 `vue-vben-admin-origin/`。 - 不删除 `.codebuddy/` 目录。 - 不提交构建产物（`build/`、`*.class`、`*.dex`、`*.flat`、`*.dumpstream` 等）。 - 不引入 CocoaPods / 其他平台专属工具链到 Android 工程。