diff --git a/AGENTS.md b/AGENTS.md index cbeaf92..d04309c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,7 @@ | 目录 | 作用 | 主要语言/格式 | | --- | --- | --- | | `agent/` | 远程设备守护程序 ads-agent,注册设备、连接手机 ADB、建立转发并重连;源码在 `src/` | Rust、TOML | +| `usb/` | 可选 ads-usb 本机虚拟 ADB USB 设备,提供回环 USB/IP、描述符和 ADB 帧适配;Windows 使用已签名 USBip 虚拟控制器 | Rust、TOML | | `client/` | 本地守护程序 ads-client,维护设备租约、监听本地端口并自动调用 adb connect;源码在 `src/` | Rust、TOML | | `server/` | ads-server 控制中心、旧协议兼容转发及独立 ads-relay 中继节点 | Go | | `server/cmd/ads-relay/` | 独立中继入口,提供短期票据认证、WSS 数据配对及可选 STUN | Go | @@ -41,9 +42,9 @@ 桌面项目下的 `bin/`、`obj/` 同样是 .NET 生成的构建产物与中间文件,已被 Git 忽略。根目录的 `adb_bridge.py` 与 `start-bridge.ps1` 是旧局域网桥接入口,分别使用 Python 和 PowerShell,不属于上述目录。 -## 可选 USB 模拟功能(方案记录,尚未实现) +## 可选 USB 模拟功能(Windows 已开始实现) -用户要求:将跨平台 USB 模拟的可行性与产品设计记录在此,当前不进行实现。以下内容是后续开发的设计依据,不代表现有产品已经支持。未经用户后续要求,不因本文件而启动驱动、桥接或 UI 开发。 +用户于 2026-11-12 授权新增可选 USB 模拟,先实现 Windows。当前采用独立 Rust USB/IP 虚拟 ADB 设备 + 已签名的 USBip UDE 控制器,复用现有网络隧道,包含桌面开关、驱动检测和安装脚本;详见 docs/windows-usb.md。Linux/macOS 仍仅记录方案,未经后续要求不实现其后端。以下跨平台内容保留为设计依据。 ### 目标与范围 @@ -84,7 +85,7 @@ | 平台 | 候选路线 | 成本与限制 | | --- | --- | --- | -| Windows | 使用 UDE 模拟 USB 控制器/ADB USB 设备,并连接本机桥接服务 | 需要内核驱动开发、驱动签名、管理员安装、ADB 接口绑定和兼容性验证 | +| Windows | 使用已签名 USBip UDE 控制器 + 本项目虚拟 ADB USB/IP 设备 | 已实现并验证 USB 枚举与远程 shell;安装控制器需管理员权限,不自行编写内核驱动 | | Linux | 使用 USB/IP 的 `vhci_hcd`,配合模拟 ADB USB 设备的服务 | 需要内核模块支持、权限配置、USB/IP 请求适配及发行版兼容性验证 | | macOS | 使用 `IOUSBHostControllerInterface` 实现虚拟 USB 控制器 | 需要向 Apple 申请 `com.apple.developer.usb.host-controller-interface` 受管理 entitlement;获批与实际验证前不承诺正式支持 | @@ -96,14 +97,14 @@ macOS 是正式交付的最大不确定性。不能把存在 API 或实验原型 - MTP 文件传输、fastboot 以及其他 USB 功能不自动获得支持,需要独立设计与实现。 - 不将该方案描述为整台手机所有 USB 功能的透明透传。 -### 后续分阶段验证(尚未启动) +### 原跨平台分阶段方案(Windows 验证进度见 docs/windows-usb.md) 1. 检查现有转发协议层、设备端接入方式,以及可复用的隧道和设备生命周期管理能力。 2. 优先完成 Windows、Linux 的最小原型验证,确认原版 ADB 能发现模拟设备并建立 USB transport。 3. 同期为 macOS 申请必要 entitlement 并验证原型;权限和兼容性验证通过后,再列为正式支持。 4. 验证 ADB 命令、USB 筛选、目标第三方软件、多设备、断线重连及组件安装/卸载行为,再决定正式产品范围。 -当前仅记录设计,不修改运行逻辑,不添加驱动或安装组件,不启动上述验证工作。 +当前 Windows 实现以 docs/windows-usb.md 的范围及验证记录为准;其余平台仍仅记录设计。 ### 参考资料 diff --git a/Cargo.lock b/Cargo.lock index cdec041..343071a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -43,6 +43,17 @@ dependencies = [ "webrtc", ] +[[package]] +name = "ads-usb" +version = "0.1.0" +dependencies = [ + "anyhow", + "clap", + "tokio", + "tracing", + "tracing-subscriber", +] + [[package]] name = "aead" version = "0.5.2" diff --git a/Cargo.toml b/Cargo.toml index e6e4f18..521566a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ [workspace] -members = ["crates/ads-core", "agent", "client"] +members = ["crates/ads-core", "agent", "client", "usb"] resolver = "2" [workspace.package] diff --git a/README.md b/README.md index 60c4a90..2716964 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ relay-1 / relay-2 / … ``` +Windows 现支持可选的 [USB ADB 模拟](docs/windows-usb.md),默认网络模式保持不变。 + 已部署的集群和使用方法见 [集群部署与协议](docs/cluster.md)。不配置集群时保留原有 v1 单中继模式,供兼容旧客户端;以下原有单机启动命令也仍可使用。 ## 目录说明 @@ -19,6 +21,7 @@ | 目录 | 作用 | 主要语言/格式 | | --- | --- | --- | | `agent/` | 远程设备守护程序 ads-agent,注册设备、连接手机 ADB、建立转发并重连;源码在 `src/` | Rust、TOML | +| `usb/` | 可选 ads-usb 本机虚拟 ADB USB 设备,提供回环 USB/IP、描述符和 ADB 帧适配;Windows 使用已签名 USBip 虚拟控制器 | Rust、TOML | | `client/` | 本地守护程序 ads-client,维护设备租约、监听本地端口并自动调用 adb connect;源码在 `src/` | Rust、TOML | | `server/` | ads-server 控制中心、旧协议兼容转发及独立 ads-relay 中继节点 | Go | | `server/cmd/ads-relay/` | 独立中继入口,提供短期票据认证、WSS 数据配对及可选 STUN | Go | @@ -58,7 +61,7 @@ | `crates/ads-core/` | 共用 Rust 库 | WSS、协议、ADB smart socket、流式转发 | | `deploy/` | 部署示例 | Caddy、systemd、launchd 示例 | -四个后端程序均为独立可执行文件;另有 Avalonia 桌面工作台,不依赖 Python 运行正式程序。两端守护程序当前作为前台长运行进程,启动安装交给各平台进程管理器;尚未实现原生 Windows Service 安装器。 +四个网络后端与可选 ads-usb 均为独立可执行文件;另有 Avalonia 桌面工作台,不依赖 Python 运行正式程序。两端守护程序当前作为前台长运行进程,启动安装交给各平台进程管理器;尚未实现原生 Windows Service 安装器。 ## 编译 @@ -77,7 +80,7 @@ Linux / macOS: sh scripts/build.sh ``` -产物在 `bin/`,Windows 是四个后端 `.exe`。Go 服务器和 Rust 核心使用跨平台 API;Rust 两端和桌面在 Windows x64 验证,Go 控制中心与中继已部署到 Linux amd64;其余平台仍需验证构建、进程托管和 ADB 权限。 +产物在 `bin/`,Windows 是四个网络后端及一个可选 ads-usb `.exe`。Go 服务器和 Rust 核心使用跨平台 API;Rust 两端和桌面在 Windows x64 验证,Go 控制中心与中继已部署到 Linux amd64;其余平台仍需验证构建、进程托管和 ADB 权限。 ## 1. 公网服务器 diff --git a/client/README.md b/client/README.md index a7048c5..8794657 100644 --- a/client/README.md +++ b/client/README.md @@ -22,3 +22,5 @@ $env:ADS_CLIENT_TOKEN = '<本地端令牌>' - `--status-file `:输出当前 p2p/relay/mixed/negotiating/idle、通道数和节点 ID,供桌面展示。 节点断线会中断现有 TCP 流;本地 ADB 在重试后创建新通道,重新选择路线,不支持将原 TCP 流无缝迁移。旧中心或旧 agent 会协商回 v1 模式。 + +可选 `--lease-status-file <路径>` 输出 true/false,供虚拟 USB 启动器等待租约,不包含票据。USB 模式需加 `--no-auto-connect`,由 ads-usb 使用本地原始 adbd 端点,不能把 USB/IP 接到 5037。见 docs/windows-usb.md。 diff --git a/client/src/main.rs b/client/src/main.rs index 6a9e531..a5e3de9 100644 --- a/client/src/main.rs +++ b/client/src/main.rs @@ -42,6 +42,9 @@ struct Args { /// Machine-readable active transport state for desktop clients #[arg(long)] status_file: Option, + /// Optional lease readiness file for virtual USB consumers (no secret tickets) + #[arg(long)] + lease_status_file: Option, } #[derive(Clone)] @@ -50,6 +53,15 @@ struct LeaseState { protocol: u8, } +fn publish_lease(args: &Args, ready: bool) { + if let Some(file) = &args.lease_status_file { + let temp = file.with_extension("tmp"); + if std::fs::write(&temp, if ready { "true" } else { "false" }).is_ok() { + let _ = std::fs::rename(temp, file); + } + } +} + async fn lease_once(args: &Args, state: &watch::Sender>) -> Result<()> { let mut ws = dial( args.network @@ -63,6 +75,7 @@ async fn lease_once(args: &Args, state: &watch::Sender>) -> R bail!("expected leased response"); } let id = response.lease.context("missing lease ticket")?; + publish_lease(args, true); state.send_replace(Some(LeaseState { id, protocol: response.protocol, @@ -80,6 +93,7 @@ async fn maintain_lease(args: Arc, state: watch::Sender if let Err(error) = lease_once(&args, &state).await { warn!(%error, "lease unavailable; reconnecting"); } + publish_lease(&args, false); state.send_replace(None); if started.elapsed() > Duration::from_secs(30) { delay = 1; @@ -164,6 +178,7 @@ async fn accept_connections( async fn main() -> Result<()> { init_logging(); let args = Arc::new(Args::parse()); + publish_lease(&args, false); validate_token(&args.token)?; if !valid_device_id(&args.device) { bail!("invalid device ID"); diff --git a/desktop/Ads.Desktop.Smoke/Program.cs b/desktop/Ads.Desktop.Smoke/Program.cs index b96f719..aff542b 100644 --- a/desktop/Ads.Desktop.Smoke/Program.cs +++ b/desktop/Ads.Desktop.Smoke/Program.cs @@ -23,7 +23,7 @@ internal static class Program Exception? failure = null; Dispatcher.UIThread.Post(async () => { - try { await RunAsync(args.Contains("--live"), args.Contains("--screen")); } + try { await RunAsync(args.Contains("--live"), args.Contains("--screen"), args.Contains("--usb")); } catch (Exception error) { failure = error; } finally { finished.Cancel(); } }); @@ -47,7 +47,7 @@ internal static class Program } } - private static async Task RunAsync(bool live, bool screen) + private static async Task RunAsync(bool live, bool screen, bool usb) { var root = DesktopPaths.ProjectRoot() ?? throw new InvalidOperationException("Project root not found"); var folder = Path.Combine(root, "work", "desktop-smoke", Guid.NewGuid().ToString("N")); @@ -55,6 +55,11 @@ internal static class Program // Avoid collisions with the interactive application or another local ADB device. var temporary = new System.Net.Sockets.TcpListener(System.Net.IPAddress.Loopback, 0); temporary.Start(); vm.Port = ((System.Net.IPEndPoint)temporary.LocalEndpoint).Port; temporary.Stop(); + vm.UsbMode = usb; + if (usb) { + var usbProbe = new System.Net.Sockets.TcpListener(System.Net.IPAddress.Loopback, 0); + usbProbe.Start(); vm.UsbPort = ((System.Net.IPEndPoint)usbProbe.LocalEndpoint).Port; usbProbe.Stop(); + } var window = new MainWindow { DataContext = vm }; window.Show(); await Task.Delay(60); @@ -105,6 +110,7 @@ internal static class Program await UntilAsync(() => vm.Ready && vm.Model != "—", "Device did not become ready: " + vm.Notice); await UntilAsync(() => vm.TransportStatus.Contains("P2P") || vm.TransportStatus.Contains("中继连接"), "Transport status was not updated"); Require(window.FindControl("TransportStatusText")?.Text == vm.TransportStatus, "Actual route binding failed"); + if (usb) Require(vm.Endpoint?.StartsWith("ADS-") == true, "USB mode did not select the USB serial"); Console.WriteLine("PASS: two healthy nodes and actual transport shown: " + vm.TransportStatus); Require(window.FindControl("ModelText")?.Text == vm.Model, "Model UI binding failed"); Require(window.FindControl