9.8 KiB
ADS Flutter 管理中心(Windows)
独立 Flutter 工程,复用现有控制中心 API 与 ads-client 子进程,不修改原有 Avalonia、Rust 或 Go 实现。
运行
需要 Flutter 3.50 / Dart 3.14 与 Visual Studio C++ 桌面开发工具。
在本目录执行:
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 等,无业务源码 |
检查
flutter analyze
flutter test
托盘使用 tray_manager,窗口生命周期使用 window_manager,版本通过 pubspec.lock 固定。
本目录提供启动脚本(PowerShell):首次执行 .\start-windows.ps1 -Build,后续执行 .\start-windows.ps1。
可选真实服务验证(仅连接空闲设备,不接管占用设备):
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 管理。
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 的迁移仍需专门验收。
原生自动冒烟(使用已授权设备,会临时投屏,不操作手机应用):
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 均退出,主实例正常保留。