Files
AndroidDeviceStreaming/flutter_manager/README.md
T

163 lines
16 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 / Linux)
独立 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、关闭音频。
- 托盘:Windows 关闭主窗口后保留连接;Linux 关闭主窗口时正常退出。托盘可打开窗口、断开全部、退出。完全退出会停止本应用启动的进程并断开所属 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、PNG,无业务源码 |
| windows/ | Flutter Windows 原生宿主、scrcpy 子窗口承载与插件注册 | C++、CMake、资源文件;部分自动生成 |
| linux/ | Flutter Linux GTK 原生宿主及构建入口 | C++、CMake |
| linux/runner/ | GTK 应用、窗口与 Dart 入口参数传递 | C++、CMake |
| linux/flutter/ | Flutter SDK 桥接、生成的插件注册和临时缓存;ephemeral/ 为自动生成产物 | C++、CMake;部分自动生成,无手写业务逻辑 |
| test/ | 凭据、URL 与不同窗口宽度的界面验证 | Dart |
| build/ | Flutter 生成的 Windows/Linux 发行与缓存(忽略) | 构建产物,无业务源码 |
| .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 均退出,主实例正常保留。
## 文件位置与 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` 验证电脑名和刷新布局不移位。
桌面日志界面提供“打开日志文件夹”。Avalonia 与 Flutter 均按天保存日志,单文件达到 5 MiB 后滚动,每日最多 5 份,保留最近 14 天。设备列表显示所属电脑及 Agent。Windows 安装包默认安装到 `%LOCALAPPDATA%/Programs/TongTongStudio/ADS-{Edition}`;用户配置和日志位置保持兼容。升级保持原 AppId,安装目录不再自动沿用旧的 TTSTD 路径。
Windows 宿主、Flutter C++ 包装库和源码插件统一使用静态 MSVC CRT,保留 Flutter 引擎及插件 DLL。安装打包使用 `scripts/check-windows-crt.py`(Python 标准库 PE 导入及延迟导入检查),只附带实际需要的 MSVC 运行库及其传递依赖,缺失则拒绝发布;Rust 工具仍需的运行库不会被误删。
工具位置由 `lib/data/tool_paths.dart`(Dart)统一解析:识别 TTSTD/TongTongStudio 旧安装路径,优先使用当前应用附带工具;有效自定义工具保持不变,失效路径可回退当前安装或 PATH。启动和每次连接时迁移并保存 client/adb/scrcpy 路径;缺少工具先提示重新安装或选择文件,尚未分配连接端口。用户配置与凭据位置不随安装目录变化。
## Linux 原生构建与 deb
需要 Linux Flutter 3.50 / Dart 3.14、clang、cmake、ninja、pkg-config、GTK 3 开发库和 libayatana-appindicator3-dev。Windows bundle 不能转换为 Linux 应用,必须在 Linux 原生编译。
```sh
bash scripts/build-flutter-linux.sh
# 一次新发布,自动递增补丁版本、构建 Rust 工具和 Flutter 并打 deb
bash scripts/build-linux-packages.sh flutter
```
上面的脚本从仓库根目录运行。可设置 `FLUTTER_BIN` 指定 SDK,`ADS_SCRCPY_BUNDLE` 指定已校验的原生 Linux scrcpy 完整目录(包含 adb、scrcpy、scrcpy-server 和 LICENSE);脚本检查 ELF 架构。当前 amd64 发行包自带 scrcpy 5.0.1/ADB 工具,避免系统旧 scrcpy 不支持 `--no-audio`。若不提供工具 bundle,deb 依赖系统 adb 和 scrcpy >=2.0。
Linux 配置位于 `${XDG_CONFIG_HOME:-$HOME/.config}/ads-flutter/settings.json`,日志位于 `${XDG_STATE_HOME:-$HOME/.local/state}/ads-flutter/logs/`,按天滚动。Windows 继续使用现有 LOCALAPPDATA 位置。凭据通过界面导入,不包含在发布包中。
Linux 使用独立 scrcpy 窗口,网络 ADB、多设备和 Agent 管理复用现有后端;Windows 专属内嵌投屏和 USB 驱动入口在 Linux 禁用,Linux USB 可使用独立 ads-usb CLI。安装 deb 后自动提供 /usr/bin 的四个 CLI 链接及应用菜单,支持共存和卸载回退。
`ads-flutter --package-check` 可在有桌面会话的 Linux 中验证原生窗口与插件:使用临时日志,跳过真实配置、凭据和设备初始化,随后自行退出。CLI 本身可在无 GUI 的机器运行。