Files
AndroidDeviceStreaming/AGENTS.md
T

128 lines
12 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.
# 项目约定与待实施方案
## 目录维护约定
- 新增目录时,必须说明该目录的作用,并给出主要编程语言;对于配置、文档、资源或构建产物目录,注明实际格式或“无业务源码”。
- 新增或调整根目录、主要模块/子项目目录时,必须在同一次变更中同步更新本文件与根目录 `README.md` 的目录说明。模块内部的新目录应在所属模块 README 中说明用途与语言;若没有模块 README,则补充到根目录文档。
- 移动、重命名、删除目录或变更目录职责/主要语言时,同步维护对应说明,不将规划中的目录写成已存在的目录。
- 自动生成的缓存、构建输出及第三方源码内部目录不逐项维护;说明其父目录用途、格式和生成/第三方属性即可。
## 目录说明
下表覆盖项目根目录及主要自有子项目;第三方源码的内部目录由其自身文档说明。语言列为主要语言或文件格式,产物目录不视为源码模块。
| 目录 | 作用 | 主要语言/格式 |
| --- | --- | --- |
| `android_agent/` | 手机直接联网的 Android 设备端,Kotlin 传统 View、前台服务与 Rust JNI 网关;不申请运行时权限 | Kotlin、Rust、Gradle Kotlin DSL、XML、TOML |
| `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 PE 依赖检查及安装包、Linux deb 打包及本地启动脚本 | PowerShell、Shell、Python |
| `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 权限获批和验证完成之前宣称正式支持。
### 链路与适配边界
预期链路:
```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、授权、签名与分发要求。
## 发布打包约定
每次新发布打包将版本号的补丁位增加 1(例如 0.2.0 → 0.2.1),同步 Cargo 工作区与锁文件、Avalonia、Flutter 和安装包版本。Windows 必须生成 Setup.exe,Linux 采用 deb 安装包;普通开发编译不增加版本。同一版本的 Windows/Linux 安装包只递增一次,另一平台使用复用版本选项。打包失败后重试复用已分配版本,避免重复递增。发布产物不包含私有凭据。
`scripts/release-version.py` 为共享版本分配脚本(Python)。Windows 使用 `scripts/build-installers.ps1` 自动递增并重建后端与桌面安装包;同一次发布的重试或第二平台使用 `-ReuseVersion`。Linux 使用 `bash scripts/build-linux-packages.sh` 自动递增,另一平台已分配版本时设置 `ADS_REUSE_VERSION=1`,须提供该版本重新构建的原生产物。