Files
AndroidDeviceStreaming/AGENTS.md
T

11 KiB
Raw Blame History

项目约定与待实施方案

目录维护约定

  • 新增目录时,必须说明该目录的作用,并给出主要编程语言;对于配置、文档、资源或构建产物目录,注明实际格式或“无业务源码”。
  • 新增或调整根目录、主要模块/子项目目录时,必须在同一次变更中同步更新本文件与根目录 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 虚拟控制器,Linux 使用内核 vhci_hcd(CLI) 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 管理中心,使用 Cupertino UI,提供电脑分组设备、Agent 管理、按天滚动日志、多设备连接、虚拟 USB、托盘与内嵌投屏 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/ 项目构建、Windows 安装包、Linux deb/tar.gz 打包及本地启动脚本 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 已按 2026-11-13 新授权完成原生 USB/IP CLI 验证,见 docs/linux-usb.md;Avalonia Linux GUI 已接入 pkexec 挂载;Flutter Linux GUI 尚未接入。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 权限获批和验证完成之前宣称正式支持。

链路与适配边界

预期链路:

本机原版 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 的范围及验证记录为准;其余平台仍仅记录设计。

参考资料

上述为方案记录时查阅的资料;正式实施前应重新核实平台 API、授权、签名与分发要求。