From 1918e5738e20ea3f14a784067e6ac33b53e85d3f Mon Sep 17 00:00:00 2001
From: tongtongstudio <tongtongstudio@outlook.com>
Date: Mon, 3 Aug 2026 15:37:47 +0800
Subject: [PATCH] docs: add project AGENTS.md and Flutter AGENTS.md, fix
 appName
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加根目录 AGENTS.md 定义全仓工程总览及各端开发规范
- 添加 webrtc_controller_flutter/AGENTS.md 定义 Flutter 项目技术栈、架构与编码规范
- 修正 WebRTCController app/build.gradle 中 appName 返回值
---
 AGENTS.md                           | 195 ++++++++++++++++++++++++++++
 WebRTCController/app/build.gradle   |   2 +-
 webrtc_controller_flutter/AGENTS.md | 165 +++++++++++++++++++++++
 3 files changed, 361 insertions(+), 1 deletion(-)
 create mode 100644 AGENTS.md
 create mode 100644 webrtc_controller_flutter/AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..210b524
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,195 @@
+# 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`）。
diff --git a/WebRTCController/app/build.gradle b/WebRTCController/app/build.gradle
index 1f00fb5..38e73f7 100644
--- a/WebRTCController/app/build.gradle
+++ b/WebRTCController/app/build.gradle
@@ -10,7 +10,7 @@ def releaseTime() {
 }
 
 def appName() {
-    return "WebRTCControlled"
+    return "WebRTCController"
 }
 
 android {
diff --git a/webrtc_controller_flutter/AGENTS.md b/webrtc_controller_flutter/AGENTS.md
new file mode 100644
index 0000000..dc75fe2
--- /dev/null
+++ b/webrtc_controller_flutter/AGENTS.md
@@ -0,0 +1,165 @@
+# Flutter 项目规范
+
+> 严格遵循本文档定义的架构模式、状态管理标准和代码风格。未经授权不得引入新的第三方包或架构模式。优先组合而非继承，业务逻辑不进入 UI 组件。
+
+---
+
+## 1. 技术栈
+
+- **语言：** Dart（SDK >=3.0.0，严格空安全）
+- **框架：** Flutter（最新稳定通道）
+- **状态管理：** `flutter_riverpod`（v2.x，注解 + 代码生成）
+- **路由：** `go_router`
+- **网络请求：** `dio`（配合 `json_annotation` + `freezed` 进行 JSON 序列化）
+- **数据模型：** `freezed` + `build_runner`
+- **本地存储：** `hive` / `shared_preferences`
+- **依赖注入：** Riverpod Providers（不使用 GetIt）
+- **国际化：** `flutter_localizations`（l10n / ARB 格式）
+
+---
+
+## 2. 目录结构
+
+采用 **特性优先架构（Feature-First）**，特性内部结合 **整洁架构（Clean Architecture）** 分层：
+
+```text
+lib/
+├── app/                      # 全局应用配置
+│   ├── app.dart              # MaterialApp 入口
+│   ├── router/               # 路由定义（GoRouter）
+│   ├── theme/                # 主题、颜色、排版
+│   └── constants/            # 全局常量、API 端点
+│
+├── core/                     # 跨特性共享代码
+│   ├── network/              # Dio 客户端、拦截器、错误处理
+│   ├── storage/              # 本地存储辅助工具
+│   ├── utils/                # 辅助函数、扩展方法
+│   └── widgets/              # 共享 UI 组件（按钮、输入框）
+│
+├── features/                 # 特性模块
+│   ├── auth/                 # 示例：认证模块
+│   │   ├── data/             # 数据源、API 端点、DTO
+│   │   ├── domain/           # 领域模型、仓库接口
+│   │   └── presentation/     # UI 页面、组件、控制器
+│   │       ├── controllers/
+│   │       ├── pages/
+│   │       └── widgets/
+│   └── home/                 # 示例：首页模块
+│       ├── data/
+│       ├── domain/
+│       └── presentation/
+│
+├── l10n/                     # 国际化（.arb 文件）
+└── main.dart                 # 应用入口
+```
+
+---
+
+## 3. 分层职责
+
+### 表示层（`presentation/`）
+
+UI 组件 + Riverpod Notifier / AsyncNotifier 控制器。
+
+- 只能通过 `ref.watch` 或 `ref.listen` 消费状态。
+- 禁止在 `onPressed` 或 `build()` 中直接调用 API 或编写业务逻辑。
+
+### 领域层（`domain/`）
+
+纯 Dart 领域实体（`@freezed`）和仓库接口定义。
+
+- 零 Flutter/UI 依赖。
+
+### 数据层（`data/`）
+
+实现仓库接口，通过 Dio 处理 API 请求，将 JSON DTO 映射为领域实体。
+
+---
+
+## 4. 编码规范
+
+### 状态管理（Riverpod）
+
+- 使用 `@riverpod` 注解 + `build_runner` 代码生成。
+- 异步操作优先使用 `AsyncNotifierProvider`，配合 `AsyncValue`（Loading / Data / Error）。
+
+```dart
+@riverpod
+class UserProfileController extends _$UserProfileController {
+  @override
+  FutureOr<User?> build() async {
+    return _fetchUser();
+  }
+
+  Future<void> updateName(String newName) async {
+    state = const AsyncValue.loading();
+    state = await AsyncValue.guard(
+      () => ref.read(userRepositoryProvider).updateName(newName),
+    );
+  }
+}
+```
+
+### 数据建模（freezed）
+
+所有数据类/实体必须用 `freezed` 实现不可变，并配置嵌套 JSON 映射：
+
+```dart
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'user_model.freezed.dart';
+part 'user_model.g.dart';
+
+@freezed
+class UserModel with _$UserModel {
+  const factory UserModel({
+    required String id,
+    required String email,
+    String? name,
+  }) = _UserModel;
+
+  factory UserModel.fromJson(Map<String, dynamic> json) =>
+      _$UserModelFromJson(json);
+}
+```
+
+### UI 组件
+
+- 尽可能使用 `const` 构造函数，避免不必要的重建。
+- 复杂子树提取为独立私有/公有无状态组件，不要写冗长的内联辅助方法（如 `_buildHeader()`）。
+- 响应式适配使用 `LayoutBuilder` / `MediaQuery` 或项目统一的屏幕适配工具。
+
+---
+
+## 5. 命名约定
+
+| 类别 | 规范 | 示例 |
+|---|---|---|
+| 文件/文件夹 | `snake_case.dart` | `user_profile.dart` |
+| 类/枚举 | `PascalCase` | `UserProfilePage` |
+| 变量/方法 | `camelCase` | `getUserData()` |
+| Provider | 以 `Provider` 结尾 | `userRepositoryProvider` |
+| 私有成员 | `_` 前缀 | `_handleTap()` |
+
+---
+
+## 6. 代码生成
+
+修改或新增带代码生成的模型/控制器后，运行：
+
+```bash
+# 一次性生成
+flutter pub run build_runner build --delete-conflicting-outputs
+
+# 监听模式
+flutter pub run build_runner watch --delete-conflicting-outputs
+```
+
+---
+
+## 7. 完成标准
+
+- 新文件遵循特性优先结构。
+- 代码为空安全、完全类型化，并进行 `const` 优化。
+- 对应创建数据层、领域层和表示层组件。
+- 不存在原始 `setState`（状态统一由 Riverpod 管理）。