VibeCoding/AGENTS.md

AGENTS.md — 项目全局规则

本仓库是一个 WebRTC 远程控制系统 的多端单体仓库（monorepo），包含 Android 被控端、多平台控制端（Android / iOS / Flutter / Web）、Spring Boot 信令服务器及其后台管理前端。

---

一、工程总览

目录	工程类型	主语言	构建工具	角色
WebRTCSignalServer/	Spring Boot 后端	Java 25	Maven	信令服务器 + REST API
WebRTCSignalServerWeb/	Vue3 SPA	TypeScript	Vite	服务器后台管理前端
WebRTCControlled/	Android App	Java	Gradle	被控端（投屏 + 接收指令）
WebRTCController/	Android App	Java	Gradle	控制端（观看 + 发送指令）
webrtc_controller_flutter/	Flutter App	Dart	Flutter CLI	控制端（Android/iOS 跨平台）
webrtc_controller_ios/	iOS App	Swift 5	Xcode + SPM	控制端（原生 iOS）
WebRTCControllerWeb/	Vue3 SPA	JavaScript	Vite	控制端（网页版）
AdbLoopbackController/	Android App	Java	Gradle	ADB 回环控制工具（独立）
vue-vben-admin-origin/	第三方模板	TypeScript	pnpm	只读参考，禁止修改

---

二、各工程详细规则

1. WebRTCSignalServer/ — 信令服务器

• 类型：Spring Boot 4.1.0 应用，spring-boot-starter-parent
• 语言：Java 25（<java.version>25</java.version>）
• 坐标：com.tt:webrtc-signal-server:1.0.0
• 核心依赖：spring-boot-starter-websocket、starter-web、starter-data-jpa（MySQL）、starter-data-redis、starter-validation、spring-security-crypto（仅 BCrypt 编码器，不启用 Security 自动配置）、Jackson
• 测试：spring-boot-starter-test + H2（无外部 MySQL 时上下文可启动）
• 构建：mvn clean package / mvn spring-boot:run

AI 规则

• 使用 Java 25 语法，可用 record、sealed、switch 模式匹配、文本块。
• 持久化统一走 JPA Repository，不要手写 JDBC。
• Redis 用于：在线状态、频控计数、nonce 去重、踢线广播。新增缓存需说明 key 规范与 TTL。
• 密码只允许 BCrypt 编码，禁止明文或可逆加密存储。
• 请求体参数校验统一使用 jakarta.validation 注解，不在 Controller 里手写 if 校验。
• 不要引入 Spring Security 的完整过滤器链（当前设计是刻意只用 crypto 模块）。
• 信令协议改动必须同步更新所有客户端（Android / iOS / Flutter / Web）。

2. WebRTCSignalServerWeb/ — 后台管理前端

• 类型：Vue 3 SPA，ESM（"type": "module"）
• 技术栈：Vue ^3.5.12 + TypeScript ^5.6.3 + Vite ^5.4.10 + Pinia ^2.2.4 + Vue Router ^4.4.5 + Element Plus ^2.8.4 + ECharts ^5.5.1 + axios ^1.7.7
• 脚本：npm run dev / npm run build（含 vue-tsc --noEmit）/ npm run preview（端口 5180）

AI 规则

• 统一使用 <script setup lang="ts"> + Composition API，禁止 Options API。
• UI 组件一律用 Element Plus，图标用 @element-plus/icons-vue，不引入其他 UI 库。
• 状态管理用 Pinia，禁止 Vuex。
• 所有请求走统一封装的 axios 实例，不在组件内直接 fetch。
• 构建前必须通过 vue-tsc 类型检查，禁止用 any 绕过报错。
• 风格可参考 vue-vben-admin-origin/，但只读参考，不得拷贝整块代码或改动该目录。

3. WebRTCControlled/ — Android 被控端

• 类型：Android App，applicationId / namespace = com.ttstd.controlled
• 语言：Java（源码全部为 .java；虽启用了 Kotlin/kapt 插件，但仅用于注解处理）
• SDK：compileSdk 34 / minSdk 24 / targetSdk 34，Java 兼容 VERSION_1_8，jvmTarget = 1.8
• buildFeatures：dataBinding、buildConfig、aidl 均开启
• 核心依赖：WebRTC io.github.webrtc-sdk:android:144.7559.09、Protobuf 3.25.1、Gson 2.14.0、Retrofit 3.0.0 + OkHttp 5.3.2、RxJava3 + RxAndroid、Room 2.8.4、Lifecycle 2.10.0、androidx.security:security-crypto:1.1.0、MMKV 2.4.0、Glide 4.15.1
• BuildConfig 字段：API_BASE、DEVICE_PROVISION_SECRET
• 构建变体：debug / release / zhanRuiDebug / zhanRuiRelease / CrosshatchDebug / CrosshatchRelease；zhanRui 与 Crosshatch 变体使用 src/system/AndroidManifest.xml（系统签名场景）
• 签名：keypub / crosshatch / zhanxun，配置来自 rootProject.ext.signingConfigs（外部 config.gradle）

AI 规则

• 新代码一律用 Java 编写，不要擅自引入 Kotlin 源文件。
• 语言级别限制在 Java 8，禁止使用 Java 9+ 的 API（如 List.of、var 之外的新特性需确认脱糖支持）。
• 异步统一使用 RxJava3 + rxlifecycle4 管理生命周期，禁止裸 Thread / AsyncTask。
• 网络请求走 Retrofit + OkHttp，JSON 用 Gson；DataChannel 控制指令用 Protobuf 二进制，信令消息用 JSON，两者不可混用。
• 敏感数据（deviceSecret / deviceUid / accessToken）必须存 security-crypto 加密 SharedPreferences，禁止明文 SP 或硬编码。
• DEVICE_PROVISION_SECRET 与 API_BASE 是开发期占位值，禁止把真实密钥写入 build.gradle，应通过 flavor / CI 注入。
• 修改签名配置、变体名或 src/system/AndroidManifest.xml 前必须先确认，涉及系统签名固件适配。
• Room 实体/DAO 变更必须提供 Migration，禁止 fallbackToDestructiveMigration。

4. WebRTCController/ — Android 控制端

• 类型：Android App，applicationId / namespace = com.ttstd.controller
• 语言 / SDK / 依赖：与 WebRTCControlled 完全一致（Java、compileSdk 34、minSdk 24、同一套依赖集）
• BuildConfig 字段：API_BASE、WS_URL

AI 规则

• 同 WebRTCControlled 的全部 Android 规则。
• 该模块与被控端共享协议层代码（Protobuf .proto、信令 JSON 结构），任一端修改协议必须双端同步，并同步 Flutter / iOS / Web 三端。
• 修复 appName() 返回值前请先确认，可能影响既有 CI 产物名。

5. webrtc_controller_flutter/ — Flutter 控制端

• 类型：Flutter App（Android + iOS），版本 1.0.0+1
• 语言：Dart SDK ^3.12.2
• 核心依赖：flutter_webrtc: ^1.5.2、web_socket_channel: ^3.0.3、protobuf: ^6.0.0 + fixnum: ^1.1.1、flutter_secure_storage: ^9.0.0、device_info_plus: ^11.0.0、android_id: ^0.5.2+1、http: ^1.2.0、uuid: ^4.4.0、path_provider: ^2.1.5
• Lint：flutter_lints: ^6.0.0
• 入口：lib/main.dart → MyApp（CupertinoApp）→ ControllerHome
• 关键目录：lib/config/ice_servers.dart、lib/signaling/、lib/webrtc/、lib/controller/、lib/widgets/
• iOS：已配置 ios/Podfile 以支持 flutter_webrtc

AI 规则

• 遵循 flutter_lints 规则，提交前跑 flutter analyze，不得有 warning。
• 保持现有分层：config / signaling / webrtc / controller / widgets，新代码放入对应层，不要在 main.dart 堆逻辑。
• UI 使用 Cupertino 风格（项目基调为 CupertinoApp），保持一致性。
• 敏感凭据用 flutter_secure_storage，禁止 SharedPreferences 明文存储。
• 控制指令编码必须与 Android 端 Protobuf schema 保持字段号一致。
• 新增依赖需在 pubspec.yaml 锁定 caret 版本，并说明引入理由。
• 改动 iOS 原生依赖后需提示执行 cd ios && pod install。

6. webrtc_controller_ios/ — 原生 iOS 控制端

• 类型：iOS App，Bundle ID com.ttstd.web-rtc-controller-ios
• 语言：Swift 5.0，IPHONEOS_DEPLOYMENT_TARGET = 15.0
• 依赖管理：Swift Package Manager（远程包 WebRTC），无 CocoaPods
• 架构：UIKit（AppDelegate + SceneDelegate）+ SwiftUI（ContentView）混合
• 代码分组：App/、Signaling/、Control/、WebRTC/、Views/、ViewModel/、Utils/
• 关键文件：WebRTCClient.swift、SignalingClient.swift、ControlMessage.swift、ControllerViewModel.swift、RemoteTouchView.swift、RemoteVideoView.swift、VideoRecorder.swift

AI 规则

• 只用 Swift，不引入 Objective-C 文件。
• 依赖统一走 SPM，禁止添加 Podfile / CocoaPods。
• 遵循 MVVM：视图逻辑放 ViewModel/，网络与 WebRTC 逻辑放 Signaling/ 与 WebRTC/，不要在 View 中直接持有 RTCPeerConnection。
• 保持最低支持 iOS 15.0，禁止使用更高版本独占 API（必要时用 @available 兜底）。
• 修改 project.pbxproj 需谨慎，优先通过 Xcode 操作而非手改文本。
• 控制消息结构（ControlMessage.swift）需与其他端协议对齐。

7. WebRTCControllerWeb/ — 网页控制端

• 类型：Vue 3 SPA，ESM
• 技术栈：Vue ^3.4.21 + Vite ^5.2.0 + protobufjs: ^7.3.2（纯 JavaScript，无 TypeScript）
• 脚本：npm run dev / npm run build / npm run preview

AI 规则

• 该工程未启用 TypeScript，不要擅自引入 .ts 或 tsconfig，除非用户明确要求迁移。
• 使用 <script setup> + Composition API。
• WebRTC 直接用浏览器原生 API（RTCPeerConnection / RTCDataChannel），不要引入 adapter 之外的第三方封装库。
• 控制指令用 protobufjs 编解码，.proto 定义须与 Android / iOS / Flutter 端一致。
• 保持依赖精简，新增依赖前先确认是否有原生 API 替代方案。

8. AdbLoopbackController/ — ADB 回环控制工具

• 类型：Android App，applicationId / namespace = com.ttstd.adbloopback
• 语言：Java（无 Kotlin），Java 兼容 VERSION_1_8
• SDK：AGP 8.1.4，compileSdk 34 / minSdk 24 / targetSdk 34
• 依赖：仅 appcompat:1.6.1、material:1.11.0、constraintlayout:2.1.4
• 入口：MainActivity
• 特色：自实现 ADB 协议栈 —— adb/AdbConnection、AdbPairing、AdbStream、TlsPskClient
• 签名：依赖外部 config.gradle 的 signingConfigs.keypub

AI 规则

• 纯 Java 项目，不要引入 Kotlin。
• 依赖保持极简，新增第三方库前必须说明必要性。
• adb/ 包是手写的 ADB 无线调试协议（含配对与 TLS-PSK 握手）实现，改动需严格对照 ADB 协议规范，任何修改都要说明协议依据。
• 与 WebRTC 系列工程相互独立，不要在两者间引入耦合。

9. vue-vben-admin-origin/ — 第三方模板（只读）

• 类型：上游开源后台模板 vue-vben-admin，TypeScript + Vue 3 monorepo（pnpm）
• 用途：仅作为 WebRTCSignalServerWeb 的风格与实现参考

AI 规则

• 严禁修改该目录下任何文件，也不要为其安装依赖或执行构建。
• 不要将其纳入代码搜索的改动范围；检索到的匹配结果仅供参考。
• 需要复用其能力时，在 WebRTCSignalServerWeb 中重新实现，而非拷贝目录。

---

三、跨工程通用规则

协议一致性（最高优先级）

本系统有 1 个被控端 + 5 个控制端，通信协议改动影响面极大：

• 信令通道：WebSocket + JSON
• 控制指令通道：WebRTC DataChannel + Protobuf 二进制
• 修改 .proto 文件或信令 JSON 字段时，必须同时更新：WebRTCControlled、WebRTCController、webrtc_controller_flutter、webrtc_controller_ios、WebRTCControllerWeb、WebRTCSignalServer。
• Protobuf 字段号只增不改不删；废弃字段用 reserved 标记。
• 指令类型（TOUCH / SWIPE / KEY 等）新增时需在所有端补齐分支处理。

安全

• 禁止在源码、build.gradle、pubspec.yaml、application.yml 中硬编码真实密钥、证书口令、生产地址。
• 现有占位值（dev-device-provision-secret-change-me、192.168.5.224:8080）为开发默认值，不要当作正式配置扩散。
• 签名文件与密码通过 config.gradle / CI 环境变量注入，不进版本库。
• 客户端凭据一律加密存储（Android: security-crypto；Flutter: secure_storage；iOS: Keychain）。

JSON / 序列化库选型规范

• 禁止使用 fastjson。
• 各平台按以下原则选型：

平台 / 语言	推荐库	备选
Spring Boot（Java）	Jackson（spring-boot-starter-web 已内置）	—
Android（Java）	Gson	Jackson（体积稍大但功能更强）
Android（Kotlin）	kotlinx.serialization	Moshi（已有技术积累的项目可沿用）
纯后端 Kotlin（非 Spring Boot）	kotlinx.serialization	Jackson
iOS（Swift）	Codable（系统原生）	—
Flutter（Dart）	json_annotation + json_serializable + freezed	—

• 例外流程：若因第三方依赖必须使用其他库，需提交技术评审并锁定版本、开启安全扫描。

ViewModel 规则

• 绝不持有 Context：ViewModel 中严格禁止持有 Context、Activity、Fragment 或 View 的引用。若需要 Application Context，请继承 AndroidViewModel（但优先推荐使用 Hilt 注入所需依赖）。
• 数据暴露规范：
  • 对外只暴露不可变的 LiveData<T>。
  • 内部维护私有的 MutableLiveData<T>。
  • 示例：

    private final MutableLiveData<UserUiState> _uiState = new MutableLiveData<>();
    public LiveData<UserUiState> getUiState() {
        return _uiState;
    }
    

代码修改

• 优先做最小化定向修改，不要对既有大文件做整体重写或重构。
• 修改前先读取文件当前内容，避免基于陈旧上下文编辑。
• 不要主动创建 *.md 文档、示例文件或临时脚本；临时产物用完即删。
• 编辑后修复自己引入的 lint / 编译错误。
• 注释与提交说明使用简体中文。

禁止事项

• 不改动 vue-vben-admin-origin/。
• 不删除 .codebuddy/ 目录。
• 不擅自升级 AGP、Spring Boot、Flutter SDK、Vue 等大版本。
• 不在 Java 工程中混入 Kotlin 源码。
• 不提交构建产物（build/、dist/、*.class、*.flat、*.dex、*.dumpstream）。