diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..275f0f8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,114 @@ +# 项目约定与待实施方案 + +## 目录维护约定 + +- 新增目录时,必须说明该目录的作用,并给出主要编程语言;对于配置、文档、资源或构建产物目录,注明实际格式或“无业务源码”。 +- 新增或调整根目录、主要模块/子项目目录时,必须在同一次变更中同步更新本文件与根目录 `README.md` 的目录说明。模块内部的新目录应在所属模块 README 中说明用途与语言;若没有模块 README,则补充到根目录文档。 +- 移动、重命名、删除目录或变更目录职责/主要语言时,同步维护对应说明,不将规划中的目录写成已存在的目录。 +- 自动生成的缓存、构建输出及第三方源码内部目录不逐项维护;说明其父目录用途、格式和生成/第三方属性即可。 + +## 目录说明 + +下表覆盖项目根目录及主要自有子项目;第三方源码的内部目录由其自身文档说明。语言列为主要语言或文件格式,产物目录不视为源码模块。 + +| 目录 | 作用 | 主要语言/格式 | +| --- | --- | --- | +| `agent/` | 远程设备守护程序 ads-agent,注册设备、连接手机 ADB、建立转发并重连;源码在 `src/` | Rust、TOML | +| `client/` | 本地守护程序 ads-client,维护设备租约、监听本地端口并自动调用 adb connect;源码在 `src/` | Rust、TOML | +| `server/` | 公网中继 ads-server,负责认证、设备注册、独占租约、会话配对及数据转发 | Go | +| `crates/` | Rust 工作区共享库容器 | Rust、TOML | +| `crates/ads-core/` | 共用网络与协议代码,包括 WSS、ADB smart socket 和流式转发;源码在 `src/` | Rust、TOML | +| `desktop/` | 跨平台桌面客户端及其测试项目、.NET SDK 配置与使用说明 | C#、Avalonia XAML(AXAML)、JSON、Markdown | +| `desktop/Ads.Desktop/` | Avalonia 桌面应用,管理配置、设备列表、连接、托盘及 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 设备端准备、安装和运行脚本,通过计划任务托管 agent,附配置示例 | PowerShell、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 模拟功能(方案记录,尚未实现) + +用户要求:将跨平台 USB 模拟的可行性与产品设计记录在此,当前不进行实现。以下内容是后续开发的设计依据,不代表现有产品已经支持。未经用户后续要求,不因本文件而启动驱动、桥接或 UI 开发。 + +### 目标与范围 + +- 在现有端口转发/网络 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 | 使用 UDE 模拟 USB 控制器/ADB USB 设备,并连接本机桥接服务 | 需要内核驱动开发、驱动签名、管理员安装、ADB 接口绑定和兼容性验证 | +| 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 功能的透明透传。 + +### 后续分阶段验证(尚未启动) + +1. 检查现有转发协议层、设备端接入方式,以及可复用的隧道和设备生命周期管理能力。 +2. 优先完成 Windows、Linux 的最小原型验证,确认原版 ADB 能发现模拟设备并建立 USB transport。 +3. 同期为 macOS 申请必要 entitlement 并验证原型;权限和兼容性验证通过后,再列为正式支持。 +4. 验证 ADB 命令、USB 筛选、目标第三方软件、多设备、断线重连及组件安装/卸载行为,再决定正式产品范围。 + +当前仅记录设计,不修改运行逻辑,不添加驱动或安装组件,不启动上述验证工作。 + +### 参考资料 + +- 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、授权、签名与分发要求。 diff --git a/README.md b/README.md index ba402ad..642ab5f 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,40 @@ ads-agent (Rust) → 手机 adbd TCP:5555 ``` +## 目录说明 + +下表覆盖项目根目录及主要自有子项目;第三方源码的内部目录由其自身文档说明。语言列为主要语言或文件格式,产物目录不视为源码模块。 + +| 目录 | 作用 | 主要语言/格式 | +| --- | --- | --- | +| `agent/` | 远程设备守护程序 ads-agent,注册设备、连接手机 ADB、建立转发并重连;源码在 `src/` | Rust、TOML | +| `client/` | 本地守护程序 ads-client,维护设备租约、监听本地端口并自动调用 adb connect;源码在 `src/` | Rust、TOML | +| `server/` | 公网中继 ads-server,负责认证、设备注册、独占租约、会话配对及数据转发 | Go | +| `crates/` | Rust 工作区共享库容器 | Rust、TOML | +| `crates/ads-core/` | 共用网络与协议代码,包括 WSS、ADB smart socket 和流式转发;源码在 `src/` | Rust、TOML | +| `desktop/` | 跨平台桌面客户端及其测试项目、.NET SDK 配置与使用说明 | C#、Avalonia XAML(AXAML)、JSON、Markdown | +| `desktop/Ads.Desktop/` | Avalonia 桌面应用,管理配置、设备列表、连接、托盘及 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 设备端准备、安装和运行脚本,通过计划任务托管 agent,附配置示例 | PowerShell、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,不属于上述目录。 + +新增或调整目录时,需按 `AGENTS.md` 的目录维护约定同步说明用途和主要语言/格式。 + ## 程序划分 | 目录 | 输出 | 职责 |