# 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= # 冒烟产物会覆盖同一输出目录,完成后重新构建正式入口 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 均退出,主实例正常保留。 ## 文件位置与 USB 自动恢复 工具/凭据/Agent 配置的文件路径输入框带文件选择按钮,选中后立即保存位置;取消不修改设置。服务器 URL、IP 和端口仍为网络地址输入。保存的只是文件路径,不保存凭据内容。Agent 路径随连接设置一同记忆。 USB ADB 连续 3 轮监控缺失(约 9 秒)、USB 后端退出或 scrcpy 以设备断开退出时,自动关闭本次旧导出、选择新的回环端口、等待租约并重新挂载。ads-client 异常退出时按该连接启动时的参数重启。失败按 2/4/8/16/30 秒退避,等待手机授权时不循环重挂载;多个恢复不会并行操作同一设备。 记住用户是否希望投屏及原内嵌/独立模式,USB/ADB 就绪后恢复投屏。主动停止投屏、关闭独立窗口、主动断开和退出取消相应恢复,不重启已停止的投屏,也不操作物理 USB 手机或其他客户端的设备。这是断线后的恢复流程,不承诺原有视频/ADB 字节流无缝续传,也不等于已消除网络断开的根因。 内嵌投屏的自动恢复遵循页面可见性:离开投屏页或缩到托盘时继续修复 USB 连接,但暂不重新创建内嵌画面;返回投屏页并显示窗口后恢复。独立窗口模式按原模式恢复。 本轮验证:文件路径选择/取消及立即保存测试、USB 恢复状态机与窗口可见性测试通过。真机主动结束本次 ads-client 后,USB 和软件渲染投屏自动恢复并重新出图;主动停止不再自动启动。测试使用了仅中继对照,恢复逻辑不依赖选择 P2P 或中继。Avalonia 真机亦验证客户端故障后 USB 重挂载及 scrcpy 重新出图。 ## Cupertino UI、电脑归属和本地日志 应用根、按钮、表单、列表选择、开关、展开区域与确认对话框采用官方 cupertino_ui;app_widgets.dart 封装统一的 Cupertino 组件,兼容层只为现有选择菜单、图标、文本选择和插件提供主题/本地化上下文。设备工作台根据控制中心返回的 agent_id/computer_name 按电脑分组,每张手机卡片显示所属电脑,并支持按电脑名搜索。旧单设备 Agent 没有上报主机信息时明确显示未上报,不猜测归属。普通 client 角色即可读取这些字段。 运行日志保存到 `%LOCALAPPDATA%/TTSTD/ADS-Flutter/logs/ads-YYYY-MM-DD.log`。单文件达到约 5 MiB 后滚动,每天最多 5 份(含当天主文件),保留 14 天;应用关闭前等待写入完成。已加载令牌在内存和磁盘日志中均脱敏,单条磁盘日志最多 16384 字符。包括客户端/USB/scrcpy 子进程日志、Agent 管理操作错误,以及主动读取/跟随的 Agent 日志。日志页显示实际路径和写入错误。文件中可能包含设备地址、路径等诊断信息,分享前按需检查。 工作台和 Agent 页的刷新指示器使用固定高度占位。Agent 发现列表保留到切换主机;旧后端不支持 devices_discover 时提示同步更新 CLI 和 Agent。`test/daily_log_test.dart` 验证跨天、大小滚动、保留及脱敏,`test/cupertino_layout_test.dart` 验证电脑名和刷新布局不移位。