Files
AndroidDeviceStreaming/flutter_manager/README.md
T

116 lines
9.8 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.
# ADS Flutter 管理中心(Windows)
独立 Flutter 工程,复用现有控制中心 API 与 ads-client 子进程,不修改原有 Avalonia、Rust 或 Go 实现。
## 运行
需要 Flutter 3.50 / Dart 3.14 与 Visual Studio C++ 桌面开发工具。
在本目录执行:
```powershell
flutter pub get
flutter run -d windows
# 或构建发布版
flutter build windows --release
.\build\windows\x64\runner\Release\ads_manager.exe
```
## 功能与使用
- 设备工作台:显示网关在线设备和租约占用,搜索设备,同时连接多台设备,自动分配回环端口,断开与复制地址。
- 中继节点:显示控制中心 /v2/nodes 的健康与通道使用情况;旧服务器无该接口时为空。
- 本机 ADB:启动本地 ADB Server、读取 devices -l,包括本机 USB 及网络设备。
- 投屏:Windows 下点击“内嵌投屏”,将官方 scrcpy 窗口嵌入管理端,鼠标键盘直接控制;返回设备页后隐藏画面,点击“查看投屏”恢复。可停止投屏而保留设备连接。使用 --force-adb-forward,最大边长 1920、60 FPS、关闭音频。
- 托盘:关闭主窗口后保留连接,托盘打开窗口、断开全部、退出。完全退出会停止本应用启动的进程并断开所属 ADB 地址。
- 配置:保存非敏感设置、导入 client.env、检查三个可执行程序;凭据不写入设置,子进程通过环境变量接收令牌。
- 自动每 12 秒同步控制中心,每 3 秒检查 ADB 状态,连接重试由 ads-client 负责。
开发环境自动向上查找仓库,使用 bin/ads-client.exe、bin/tools/scrcpy/ 中的工具与 config/private/client.env。发行时请在应用旁放置 ads-client.exe、tools/scrcpy/ 完整发行目录,或在配置页填写绝对路径,并导入自己的凭据文件。配置在 %LOCALAPPDATA%/TTSTD/ADS-Flutter/settings.json,与原客户端分开。
服务地址支持 /ads 路径前缀和可选直连源站地址,HTTPS 仍按原域名校验证书。令牌仅使用 client 角色。Agent 管理使用独立 admin.env 管理角色,支持多 Agent/多手机、配置、日志及受监督重启;本机使用 adsctl 私有 IPC。用户账号和角色编辑不在此版本范围。Windows 支持可选虚拟 USB ADB;连接配置中勾选启用。
## 目录
| 目录 | 用途 | 语言/格式 |
| --- | --- | --- |
| lib/ | 应用入口及分层业务源码 | Dart |
| lib/data/ | 配置、HTTP API、工具发现、ADB 与子进程生命周期 | Dart |
| lib/ui/ | ChangeNotifier 状态与管理界面 | Dart |
| assets/ | 托盘图标资源 | ICO,无业务源码 |
| windows/ | Flutter Windows 原生宿主、scrcpy 子窗口承载与插件注册 | C++、CMake、资源文件;部分自动生成 |
| test/ | 凭据、URL 与不同窗口宽度的界面验证 | Dart |
| build/ | Flutter 生成的 Windows 发行与缓存(忽略) | 构建产物,无业务源码 |
| .dart_tool/ | Dart/Flutter 生成缓存(忽略) | JSON 等,无业务源码 |
## 检查
```powershell
flutter analyze
flutter test
```
托盘使用 [tray_manager](https://pub.dev/packages/tray_manager/versions/0.5.1),窗口生命周期使用 [window_manager](https://pub.dev/packages/window_manager/versions/0.5.1),版本通过 pubspec.lock 固定。
本目录提供启动脚本(PowerShell):首次执行 .\start-windows.ps1 -Build,后续执行 .\start-windows.ps1。
可选真实服务验证(仅连接空闲设备,不接管占用设备):
```powershell
dart run test/live_smoke.dart
dart run test/live_smoke.dart --connect --screen
```
2026-11-12:已验证真实设备/节点 API、本机 ADB 列表;真实远端设备当时被占用,因此跳过远端连接与投屏验收。原生 UI 自动化工具初始化失败,托盘点击行为仍需人工验收。
## Agent 管理
导航“Agent 管理”可选择多台被控电脑,添加/移除/启停手机,修改配置、跟随日志和重启。也可管理本机 Agent,初始化并安装无界面开机任务。发行包旁放置 adsctl.exe 和 ads-agent.exe;两者与 Avalonia 共用同一配置和后台,不应重复启动。详见 [Agent 管理](../docs/agent-management.md)。
`lib/data/agent_models.dart` 使用 Freezed 生成不可变快照(生成文件一并提交);`agent_service.dart` 封装 HTTP/本机 CLI,`agent_repository.dart` 解析数据,`lib/ui/agent_model.dart` 持有页面状态。模型变化后运行 `dart run build_runner build`。`test/agent_test.dart` 验证选择范围、日志脱敏、响应竞争和布局;`agent_live_smoke.dart` 仅面向显式提供的隔离测试 Agent。
## Windows 内嵌投屏
使用本机官方 scrcpy 5.0.1,以独立进程运行,画面窗口通过原生平台通道 ads/scrcpy_host 挂到 Flutter 视图。lib/ui/embedded_screen.dart 按设备像素比同步画面矩形;windows/runner/scrcpy_host.cpp 按 PID 发现、挂载、隐藏及释放窗口。不修改手机端、隧道或 scrcpy 源码。
一次在页面中显示一台设备的画面,其他投屏进程可保留。返回设备页切换另一台;关闭主窗口后,画面随父窗口隐藏。退出会停止本应用启动的 scrcpy。布局采用原生子窗口,Flutter 控件放在画面外;暂不支持画面上叠加 Flutter 弹窗、原生画面全屏快捷键及其他系统的窗口嵌入。首版采用已验证的软件解码和软件渲染路径;硬件加速尚未验收。高 DPI 使用 Flutter 实际设备像素比,多显示器不同 DPI 的迁移仍需专门验收。
原生自动冒烟(使用已授权设备,会临时投屏,不操作手机应用):
```powershell
flutter run -d windows --release -t test/windows_embed_smoke.dart --dart-define=ADS_EMBED_SERIAL=<adb序列号>
# 冒烟产物会覆盖同一输出目录,完成后重新构建正式入口
flutter build windows --release -t lib/main.dart
```
验证报告位于仓库 work/flutter-embed-smoke.json,检查原生父窗口、画面尺寸同步、页面隐藏、主窗口隐藏/恢复和释放。不等同于鼠标键盘与输入法的人工交互验收。
2026-11-12 Windows 真机内嵌验证通过:scrcpy 5.0.1,H.264 1920×1200;原生子窗口挂载、窗口缩放、切页隐藏、主窗口隐藏/恢复和释放均通过。内嵌模式使用本轮验证通过的软件解码及 software 渲染器,硬件加速路径尚未验收。鼠标键盘直接交给原生 scrcpy,输入法、全屏快捷键和多显示器混合 DPI 未完成自动交互验收。
## Windows 便携包
在本目录执行 .\package-windows.ps1,自动分析、测试、构建正式 lib/main.dart 入口,并输出带北京时间戳的 bin/flutter-win-x64-YYYYMMDD-HHmmss/ 与对应 ZIP、SHA-256 文件。该脚本为 PowerShell,无新增源码目录。
包内包含 Flutter 运行资源、现有 bin/ 中的 ads-client/ads-agent/adsctl、完整 scrcpy 工具目录、已安装 Visual Studio 的 x64 C++ 可再分发运行库,以及逐文件校验清单 manifest.json。不会覆盖已运行的旧包;不包含凭据或用户设置。解压整个目录后运行 ads_manager.exe,无需 Flutter SDK、Rust 工具链或 .NET。目标机器需自行导入凭据。
## 可选虚拟 USB 与驱动安装
连接配置勾选“挂载为 USB 设备 · Windows”;缺少驱动时提示安装,点击安装后验证 SHA-256 与发布者签名,再由 Windows 请求管理员确认。安装可能短暂重启 USB 集线器并要求重启 Windows,应用不强制重启。重新检测组件后勾选并保存,对下一次连接生效。默认 usbip.exe 路径为 C:\Program Files\USBip\usbip.exe。
Windows 便携包和安装器包含 ads-usb.exe 及 drivers/ 下的原版已签名 USBip 安装器,主安装器不自动安装驱动;drivers/ 为分发产物目录(EXE、TXT,无业务源码)。lib/data/windows_usb.dart 封装组件检测、校验、安装启动及每台设备的 USB 生命周期(Dart)。
USB 模式禁用网络 adb connect,等待租约后挂载,ADB 与 scrcpy 使用 ADS-设备ID 序列号。每台设备独立分配回环端口,断开只移除本次虚拟 USB,不操作物理 USB 手机或卸载驱动。仅支持 ADB,不包含 MTP/fastboot。Linux、macOS 后端未实现。
真机验证:dart run test/live_smoke.dart --connect --usb --screen,仅连接空闲设备,验证原版 ADB 的 -d USB 专用筛选、远程 shell、scrcpy 进程及断开后的设备移除与端口回收。
2026-11-12 Flutter USB 验证:16 项自动测试通过,包含缺少驱动时的安装提示与取消行为。真实远端 ADS-home-phone 的原版 ADB USB 筛选、远程 shell、scrcpy 与断开回收通过;USB 模式下的 Windows 内嵌画面、缩放、切页隐藏、主窗口隐藏恢复及释放亦通过。本机驱动已预装,未为测试卸载/重装驱动;真实 UAC 安装交互仍由用户完成。
## 投屏窗口切换与单实例
内嵌投屏页提供“独立投屏”,切换后提供“返回内嵌”。切换仅重启该设备的 scrcpy 进程,保留网络隧道、租约和可选虚拟 USB;停止投屏同样保留设备连接。虚拟 USB 的驱动检测与安装提示保持可用。
Windows 下 Flutter 和 Avalonia 两个桌面入口共享会话级单实例锁,安装版、便携版和 Agent 托盘入口都不能重复启动第二个 ADS 桌面实例。重复启动会退出新进程并唤起已有窗口(包括托盘隐藏或最小化状态)。仅限制桌面管理 UI,不限制无界面 Agent/client 或多个设备的 scrcpy 子进程。非 Windows 平台尚未接入此单实例机制。
本轮验证:Flutter 17 项测试与 Avalonia 20 项测试通过。真实虚拟 USB 上验证内嵌转独立窗口实际显示、USB 连接与桥接进程保持不变;重复启动退出并恢复隐藏主窗口通过。Avalonia 作为主实例时,重复启动 Avalonia 或 Flutter 均退出,主实例正常保留。