121 lines
10 KiB
Markdown
121 lines
10 KiB
Markdown
# 项目约定与待实施方案
|
||
|
||
## 目录维护约定
|
||
|
||
- 新增目录时,必须说明该目录的作用,并给出主要编程语言;对于配置、文档、资源或构建产物目录,注明实际格式或“无业务源码”。
|
||
- 新增或调整根目录、主要模块/子项目目录时,必须在同一次变更中同步更新本文件与根目录 `README.md` 的目录说明。模块内部的新目录应在所属模块 README 中说明用途与语言;若没有模块 README,则补充到根目录文档。
|
||
- 移动、重命名、删除目录或变更目录职责/主要语言时,同步维护对应说明,不将规划中的目录写成已存在的目录。
|
||
- 自动生成的缓存、构建输出及第三方源码内部目录不逐项维护;说明其父目录用途、格式和生成/第三方属性即可。
|
||
|
||
## 目录说明
|
||
|
||
下表覆盖项目根目录及主要自有子项目;第三方源码的内部目录由其自身文档说明。语言列为主要语言或文件格式,产物目录不视为源码模块。
|
||
|
||
| 目录 | 作用 | 主要语言/格式 |
|
||
| --- | --- | --- |
|
||
| `agent/` | 无界面多手机守护程序 ads-agent、独立监督进程、私有 IPC 和远程管理;兼容单设备参数;源码在 `src/` | Rust、TOML |
|
||
| `ctl/` | adsctl 命令行管理端,本机/远程设备、配置、日志、重启及系统启动托管;源码在 `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 |
|
||
| `server/internal/relay/` | 中继票据、数据通道、租约撤销、STUN 与测试 | Go |
|
||
| `crates/` | Rust 工作区共享库容器 | Rust、TOML |
|
||
| `crates/ads-management/` | Agent 配置及管理协议、Windows 命名管道/Unix socket、私有文件与系统服务操作;源码在 `src/` | Rust、TOML |
|
||
| `crates/ads-core/` | 共用网络与协议代码,包括 WSS、WebRTC P2P、节点回退、ADB smart socket 和流式转发;源码在 `src/` | Rust、TOML |
|
||
| `flutter_manager/` | 独立 Flutter Windows 管理中心,提供设备/中继总览、Agent 管理、多设备连接、本机 ADB、托盘与独立 scrcpy 窗口 | Dart、C++、CMake、YAML、ICO |
|
||
| `desktop/` | 跨平台桌面客户端及其测试项目、.NET SDK 配置与使用说明 | C#、Avalonia XAML(AXAML)、JSON、Markdown |
|
||
| `desktop/Ads.Desktop/` | Avalonia 多设备工作台,管理独立连接、自动端口分配、USB 模拟、多个 scrcpy 窗口及托盘;`Assets/` 保存图标资源 | C#、AXAML、XML(csproj)、PNG |
|
||
| `desktop/Ads.Desktop.Tests/` | 桌面客户端单元测试 | C#、XML(csproj) |
|
||
| `desktop/Ads.Desktop.Smoke/` | 桌面离屏布局、连接及可选真机冒烟验证入口 | C#、XML(csproj) |
|
||
| `deploy/` | 服务器/设备端部署脚本与 Caddy、Nginx、systemd、launchd 配置示例 | Shell、服务/代理配置、XML(plist)、Markdown |
|
||
| `deploy/windows/` | Windows 设备端准备与计划任务部署、桌面安装包定义及配置示例 | PowerShell、Inno Setup(ISS)、JSON、Markdown |
|
||
| `scripts/` | 项目构建、打包及本地启动脚本 | PowerShell、Shell |
|
||
| `tests/` | Python 桥接测试、三端集成测试及可选真机验证 | Python |
|
||
| `docs/` | 协议、部署、验证及旧局域网桥接说明 | Markdown |
|
||
| `config/` | 本地配置容器;`private/` 保存私有凭据等配置,已被 Git 忽略,不纳入发布包 | 环境变量文件等配置格式,无业务源码 |
|
||
| `adb/` | 本地第三方 AOSP ADB 源码检出,用于参考与研究;已被 Git 忽略,不是 adb 可执行文件目录 | 主要为 C++,另含 Python、Shell、Android.bp |
|
||
| `scrcpy/` | 本地第三方 scrcpy 源码检出;已被 Git 忽略,不是可直接运行的发行包 | C(客户端)、Java(Android 服务端)、Meson、Gradle |
|
||
| `QtScrcpy/` | 本地第三方 QtScrcpy 源码检出,供参考与研究;已被 Git 忽略 | C++、Qt、CMake |
|
||
| `bin/` | 编译/分发产物和运行工具,如 ads 三端程序、桌面包、Linux 产物及 `tools/`;已被 Git 忽略 | 可执行文件、运行库及资源,无独立源码语言 |
|
||
| `target/` | Cargo 生成的编译产物与缓存;已被 Git 忽略 | Rust 构建产物,无独立源码语言 |
|
||
| `work/` | 本地联调、测试输出、截图、日志、工具下载与临时脚本;已被 Git 忽略,不作为正式源码入口 | 混合格式,含 Python、PowerShell、日志及图片 |
|
||
| `__pycache__/` | Python 自动生成的字节码缓存;已被 Git 忽略 | Python 字节码,无手写源码 |
|
||
| `.git/` | 当前仓库的版本控制元数据,由 Git 管理 | Git 内部数据,无业务源码 |
|
||
|
||
桌面项目下的 `bin/`、`obj/` 同样是 .NET 生成的构建产物与中间文件,已被 Git 忽略。根目录的 `adb_bridge.py` 与 `start-bridge.ps1` 是旧局域网桥接入口,分别使用 Python 和 PowerShell,不属于上述目录。
|
||
|
||
## 可选 USB 模拟功能(Windows 已开始实现)
|
||
|
||
用户于 2026-11-12 授权新增可选 USB 模拟,先实现 Windows。当前采用独立 Rust USB/IP 虚拟 ADB 设备 + 已签名的 USBip UDE 控制器,复用现有网络隧道,包含桌面开关、驱动检测和安装脚本;详见 docs/windows-usb.md。Linux/macOS 仍仅记录方案,未经后续要求不实现其后端。以下跨平台内容保留为设计依据。
|
||
|
||
### 目标与范围
|
||
|
||
- 在现有端口转发/网络 ADB 能力之外,提供可选 USB 模拟模式,让本机原版 ADB 将远端 Android 设备识别为本地 USB ADB 设备。
|
||
- 覆盖 Windows、Linux、macOS,但分别实现平台后端;跨平台应用可运行,不等于所有平台均已支持 USB 模拟。
|
||
- 该能力不是修改转发端口即可完成,需要操作系统层面的虚拟 USB 控制器/设备,以及 ADB 桥接。
|
||
- 实际链路仍然经过网络,USB 模拟不会消除网络延迟。
|
||
|
||
### 产品设计
|
||
|
||
- 默认模式:网络 ADB 自动连接。转发建立后自动连接本地映射端点,目标是在三端提供一致的设备发现体验,减少手动输入 `adb connect` 的操作。
|
||
- 可选模式:USB 模拟。按平台检测支持情况和必要组件,安装并满足权限条件后才能启用。
|
||
- 共享网络隧道、设备管理和断线重连逻辑,分别实现 Windows、Linux、macOS 的 USB 后端。
|
||
- 未安装组件、权限不足或平台尚未验证时,应清楚展示 USB 模拟的可用状态;保留默认网络 ADB 模式。
|
||
- 不承诺三端均能免安装、一键变成 USB 设备;尤其不能在 macOS 权限获批和验证完成之前宣称正式支持。
|
||
|
||
### 链路与适配边界
|
||
|
||
预期链路:
|
||
|
||
```text
|
||
本机原版 adb
|
||
↕ USB 接口与端点
|
||
平台虚拟 USB 控制器/Android ADB USB 设备
|
||
↕
|
||
本机 ADB 桥接服务
|
||
↕ 现有网络隧道
|
||
远端设备的 ADB 通道
|
||
```
|
||
|
||
- 需要处理 USB 描述符、控制请求、端点传输、设备枚举、连接/断开和恢复行为。
|
||
- 不能把现有 TCP 字节流直接当作 USB/IP;USB 请求语义与 ADB 数据流之间需要适配。
|
||
- 实施前必须检查本项目实际转发层:设备端 ADB 通道与 ADB server 的 `5037` 服务不是同一协议层。若转发的是 `5037`,不能直接将其接到模拟 USB 端点,需另行设计适配。
|
||
- 如果需求仅为 Android Studio、scrcpy 等工具发现设备,优先采用默认自动连接模式。
|
||
- 如果需求包含 USB 专用筛选/只认 USB 的第三方软件,例如 `adb -d`,则需要验证真正的 USB transport 兼容性,自动执行 `adb connect` 不能代替。
|
||
|
||
### 平台路线与主要成本
|
||
|
||
| 平台 | 候选路线 | 成本与限制 |
|
||
| --- | --- | --- |
|
||
| 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;获批与实际验证前不承诺正式支持 |
|
||
|
||
macOS 是正式交付的最大不确定性。不能把存在 API 或实验原型等同于可以正常签名、分发并面向用户发布。
|
||
|
||
### 功能边界
|
||
|
||
- 首期设想仅模拟 ADB USB 接口。
|
||
- 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 的范围及验证记录为准;其余平台仍仅记录设计。
|
||
|
||
### 参考资料
|
||
|
||
- Windows UDE:https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/developing-windows-drivers-for-emulated-usb-host-controllers-and-devices
|
||
- ADB Windows USB 实现:https://android.googlesource.com/platform/packages/modules/adb/+/refs/heads/main/client/usb_windows.cpp
|
||
- Linux USB/IP 内核配置:https://github.com/torvalds/linux/blob/master/drivers/usb/usbip/Kconfig
|
||
- Apple IOUSBHostControllerInterface:https://developer.apple.com/documentation/iousbhost/iousbhostcontrollerinterface
|
||
- Apple 关于受管理 entitlement 申请的官方答复:https://developer.apple.com/forums/thread/802495
|
||
|
||
上述为方案记录时查阅的资料;正式实施前应重新核实平台 API、授权、签名与分发要求。
|