# ADS 桌面客户端 C# / .NET 8 + Avalonia 11 + CommunityToolkit.Mvvm,Windows、Linux、macOS 共用代码。本次在 Windows 构建与启动验证。 ## 启动 在 `desktop` 目录运行: ```powershell dotnet run --project Ads.Desktop -c Release ``` 或运行 `desktop/Ads.Desktop/bin/Release/net8.0/Ads.Desktop.exe`。 1. 默认公网中继已同步为 `wss://ttstd.com/ads`,直连服务器为 `175.178.213.60:443`。设备 API 和 Rust 子进程都使用同一套地址、路径前缀和直连设置;TLS 仍按 `ttstd.com` 验证。直连留空时使用正常域名解析,不使用系统 HTTP 代理。 2. 自动读取 `ADS_CLIENT_TOKEN` 环境变量,或项目 `config/private/client.env`,也支持应用旁的 `client.env`。也可在“连接配置”导入文件;拒绝仅有 agent 角色令牌的文件。发布包不包含令牌。 3. 自动查找 ads-client、ADB 和 scrcpy。Windows 分发包附带 ads-client 和完整 scrcpy 官方运行目录(包含 ADB);也可选择自己的工具路径,并使用“检查工具”。仓库 `adb/`、`scrcpy/` 是源码,不能作为可执行文件使用。 4. 自动每 10 秒刷新在线设备,状态每 3 秒从本机 ADB 检查。支持连接、断开、重新连接、读取型号/Android/API 等级、复制本地 ADB 地址。当前占用标记区分“本机正在使用”和其他客户端占用。 本地端口被占用时,可点击“清理占用端口”。它会记录进程名和 PID,结束所选端口的监听进程,并验证端口已释放;本工作台当前连接优先正常断开。不会按进程名批量结束,不结束无关端口进程,也不允许一键结束系统/工作台自身或清理 ADB 主服务端口 5037。权限不足时会显示具体原因;Linux/macOS 需要 lsof,尚未在对应平台验收。 5. 手机允许调试后,点击“打开手机控制”。scrcpy 使用独立窗口,支持鼠标、键盘操作;可设置分辨率、帧率、音频与只读模式。强制 `--force-adb-forward`,避免反向连接无法穿过中继。 6. 关闭窗口默认进入托盘,右键托盘可重新打开、断开连接或退出。取消托盘选项后关闭窗口会退出。退出会停止本应用启动的 scrcpy、ads-client,并只断开所用 ADB 端点;远程守护程序继续运行。 请从 scrcpy 官方发行包安装程序及配套 server、DLL 等文件,不要只复制 scrcpy.exe。首次调试必须在手机端授权。 ## 边界 UI 使用 `/v1/devices` 的 Bearer 认证接口并管理现有 Rust ads-client 子进程,不承担 ADB 数据转发,也未新增本机 HTTP 管理 API。一次管理一个远程连接;断线重连由 ads-client 负责。完全退出 UI 后不保留后台守护进程。连接配置修改在下次连接生效。 令牌仅保存在内存,通过 `ADS_CLIENT_TOKEN` 子进程环境变量传递,不出现在命令参数、配置或日志中。配置保存在系统 LocalApplicationData 下 `TTSTD/ADS/settings.json`,只记住非敏感连接配置和凭据文件路径。旧的默认子域名配置会自动迁移到当前公网地址,自定义中继地址保持不变。日志最多保留 1000 条,可导出到同目录;不自动落盘。子进程不继承远程 ADB Server 或 agent 角色凭据环境变量。 托盘需要桌面环境支持;Linux 桌面可能需要 AppIndicator。当前在 Windows 完成构建、Avalonia 离屏布局和真实公网手机连接测试;Linux/macOS 尚未运行验收。设备列表表示网关在线,实际手机就绪状态以本地 ADB 检测为准。一次管理一个远程连接,不提供远程守护重启、SSH 或服务器管理。USB 模拟仍仅为 AGENTS.md 中的后续方案,没有在本次加入。 ## 发布 ```powershell # 在项目根目录运行 .\scripts\build-desktop.ps1 .\scripts\start-desktop.ps1 ``` 产物:`bin/desktop-win-x64/Ads.Desktop.exe`,Windows 自包含包无需另装 .NET。构建脚本会复制已准备好的 `bin/ads-client.exe` 和 `bin/tools/scrcpy/`,不会复制凭据。将整个目录分发,不要只复制 exe。离开项目目录使用时,导入用户自己的 client.env。 当前随项目准备的 scrcpy 为官方 5.0.1 Windows x64 包,下载 ZIP 的 SHA-256 已对照官方说明验证:`b12a2c4ee8be317422451fc7dcf8ee20a71b5ea7ef9ad73ddd825a25316227a5`。来源:[scrcpy 官方 Windows 说明](https://github.com/Genymobile/scrcpy/blob/master/doc/windows.md)。 ## 验证 在 `desktop/` 运行: ```powershell dotnet test Ads.Desktop.Tests -c Debug dotnet run --project Ads.Desktop.Smoke -c Debug # 会连接真实 home-phone,仅在设备空闲且本地具有 client.env 时运行: dotnet run --project Ads.Desktop.Smoke -c Debug -- --live --screen ``` 单元测试覆盖路径前缀、源站配置、旧默认地址迁移、角色凭据隔离、不可信证书拒绝、环境变量与保存配置。离屏测试加载真实 XAML,覆盖按钮可用状态、实际设备发现/连接/型号显示/重连/释放、scrcpy 视频纹理启动与停止。示例布局图片写入 `work/`。原生 Windows 自动化运行时本次初始化失败,因此未自动点击真实原生窗口或验证托盘菜单;不是把无头测试当作原生点击验收。 ## 集群连接 地址指向控制中心。默认 P2P 优先,连接配置的“仅使用中继”可跳过直连;修改在下次连接生效。连接管理显示实际 P2P/中继节点,控制中心配置卡显示节点健康及通道数。节点健康约每 5 秒由中心探测,桌面刷新设备时读取。 ## Windows USB 模拟 连接配置提供可选 USB 模式、usbip.exe 路径和回环 USB/IP 端口;需要已签名的 USBip UDE 控制器。启动时等待设备租约,再导入虚拟设备;监控、设备信息和 scrcpy 使用 USB 序列号。安装与限制见 [Windows USB 文档](../docs/windows-usb.md)。 ## 同时管理多台手机 工作台支持同时连接多台设备。左侧切换仅改变当前详情;右侧总览保留所有连接、实际 P2P/中继路线、网络/USB 模式及标识,并提供各自的查看、控制、重连和断开。可以连接全部空闲设备、投屏全部就绪设备、断开全部;托盘与退出操作管理全部连接。 ADB、USB/IP 和 scrcpy 转发端口分别自动分配,避开其他连接和外部进程占用。配置页端口是起始值;已连接设备保留启动时的配置,之后可改变 USB 开关,为下一台选择另一种模式。多个投屏为独立控制窗口。 实现分工:MainViewModel 管理设备发现、连接集合、当前选择与批量操作;DeviceConnection 为每台设备持有进程、独立操作锁、USB 导出、状态文件和生命周期;ConnectionPorts 负责不终止外部监听者的端口分配。监控每个 ADB 可执行文件每轮仅查询一次 devices,再分别更新所有设备。 验证:`dotnet run --project Ads.Desktop.Smoke -c Debug -- --multi`,USB 模式加 `--usb`。需要 home-phone 与 smoke-multi-phone(可用 ADS_MULTI_SECOND_DEVICE 指定第二个已授权设备 ID),测试不会接管已占用设备。2026-11-12 使用两个独立设备别名映射到同一台测试手机,验证双 ADB/双 USB、不同端口/序列号、两个真实 scrcpy 视频、总览按钮绑定、重连/断开一个保留另一个以及释放全部租约。此验证覆盖并发通道,未作为多台物理手机的大规模负载测试。 ## Agent 管理 工作台新增 Agent 管理页,与 Flutter 共用控制中心 v3 接口。支持多 Agent/多手机、本机私有 IPC、配置与日志、受监督重启;`--agent-tray` 可单独打开本机 Agent 管理窗口。发行包同时包含 adsctl 和 ads-agent,后台运行不依赖 GUI。完整安装及 CLI 示例见 [Agent 管理](../docs/agent-management.md)。 ## Windows 单实例 Windows 桌面入口与 Flutter 共用同一会话级单实例锁(包括 --agent-tray 入口和不同安装路径)。重复启动会唤起正在运行的桌面窗口并退出新进程,避免重复托盘及重复设备管理。后台 Agent 和设备连接进程不受该 UI 锁限制。DesktopInstance.cs 使用 Windows 命名事件通知,由 Avalonia UI 线程恢复窗口。非 Windows 暂保留原启动行为。 ## 路径选择与 USB 自动恢复 本机工具、USBip、客户端凭据及本机 Agent 配置提供文件选择对话框,选取后立即记忆文件位置。Agent 管理记忆管理员及初始化凭据文件位置,令牌内容仍仅在内存。URL/IP/端口继续按网络地址填写。 USB 连续缺失 3 轮、USB 后端退出或投屏报告设备断开后,自动等待租约、选择新回环端口重挂载;必要时重启本次 ads-client,并按原分辨率、帧率和控制设置恢复 scrcpy。重试带 2/4/8/16/30 秒退避,等待手机授权时暂停重挂载。主动停止投屏、关闭投屏窗口、主动断开和退出取消相应恢复。其他设备与物理 USB 手机不受影响。 ## Linux 桌面 USB USB 会话后端已按操作系统选择:Windows 使用已签名 USBip 控制器,Linux 使用系统 usbip/vhci_hcd,挂载时通过 pkexec 请求桌面授权。转发和 ads-usb 仍以当前用户运行,断开时关闭本次导出,避免按可能复用的控制器端口误断其他设备。Linux 需安装 usbip、polkit、ADB 和兼容版本 scrcpy;首次授权需在手机确认。 192.168.5.224 工程位于 `/home/tt/TongTongStudio/AndroidDeviceStreaming`,自包含发行目录为 `bin/desktop-linux-x64/`。已在 TT 的 X11 会话启动成功;已有 .NET 8.0.16 runtime 和 SDK 8.0.409 位于 `/home/tt/.dotnet`,SSH PATH 未包含此目录。工程要求 SDK 8.0.428,远程源码构建尚需安装该版本;自包含发行版无需安装 runtime。 桌面日志界面提供“打开日志文件夹”。Avalonia 与 Flutter 均按天保存日志,单文件达到 5 MiB 后滚动,每日最多 5 份,保留最近 14 天。设备列表显示所属电脑及 Agent。Windows 安装包默认安装到 `%LOCALAPPDATA%/Programs/TongTongStudio/ADS-{Edition}`;用户配置和日志位置保持兼容。升级保持原 AppId,安装目录不再自动沿用旧的 TTSTD 路径。 Windows 自包含发布把托管程序集打包到主程序,保留原生图形 DLL 和独立 Rust/ADB/scrcpy 工具;不启用反射裁剪,不要求安装 .NET,也不将全部应用压为单文件。发布使用全新暂存目录。`Ads.Desktop.exe --package-check` 可在隔离配置、无设备连接和不占用正式客户端互斥锁的条件下创建窗口后退出,用于验证发布包。 升级安装目录后会修复保存的旧工具位置;有效自定义可执行文件保留。启动时将解析后的路径写回已有设置,避免仍使用已删除的 TTSTD 安装目录。 Avalonia 使用锁定的 Semi.Avalonia 11.3.7.3(兼容 Avalonia 11.3.8)。`Ads.Desktop/WorkbenchStyles.axaml`(AXAML)统一侧边导航、卡片、表单和文本样式,颜色引用 Semi 语义资源,支持浅色/深色切换;Agent 托盘窗口共享主题。`dotnet run --project Ads.Desktop.Smoke -- --theme-preview` 可离线渲染 4 个页面的明暗主题和最小窗口尺寸,结果写入根目录 work(PNG)。 子进程 stdout/stderr 显式按 UTF-8 解码,包含 Rust、ADB、scrcpy 及 USB 工具;Agent JSON stdin 也使用 UTF-8。已生成的历史乱码日志保留,不猜测或改写丢失的字符。测试覆盖中文和 emoji 的一次性输出、流式日志及中文配置输入。