tt/VibeCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1918e5738e20ea3f14a784067e6ac33b53e85d3f
VibeCoding/AGENTS.md
tongtongstudio 1918e5738e docs: add project AGENTS.md and Flutter AGENTS.md, fix appName 
- 添加根目录 AGENTS.md 定义全仓工程总览及各端开发规范
- 添加 webrtc_controller_flutter/AGENTS.md 定义 Flutter 项目技术栈、架构与编码规范
- 修正 WebRTCController app/build.gradle 中 appName 返回值
2026-08-03 15:37:47 +08:00

196 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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）。
### 代码修改
- 优先做**最小化定向修改**，不要对既有大文件做整体重写或重构。
- 修改前先读取文件当前内容，避免基于陈旧上下文编辑。
- 不要主动创建 `*.md` 文档、示例文件或临时脚本；临时产物用完即删。
- 编辑后修复自己引入的 lint / 编译错误。
- 注释与提交说明使用**简体中文**。
### 禁止事项
- 不改动 `vue-vben-admin-origin/`。
- 不删除 `.codebuddy/` 目录。
- 不擅自升级 AGP、Spring Boot、Flutter SDK、Vue 等大版本。
- 不在 Java 工程中混入 Kotlin 源码。
- 不提交构建产物（`build/`、`dist/`、`*.class`、`*.flat`、`*.dex`、`*.dumpstream`）。
Reference in New Issue View Git Blame Copy Permalink