本文于 2026-11-12 对照当前工作区脚本核对,主程序与驱动管理器项目版本为 1.8.5-pre5(源码基线 1eb833a)。
以下命令均从仓库根目录运行。模块关系见架构说明,文档入口见索引。
| 工具 | 要求与用途 |
|---|---|
| 系统 | Windows 10/11 x64;WPF 运行时测试需要交互桌面;虚拟摄像头运行需要 Windows 11 |
| Visual Studio C++ Build Tools | MSVC、Windows SDK、CMake;默认 CMake preset 指向 Visual Studio 18 2026,build.ps1 会查找已安装的工具链 |
| CMake | 项目最低 3.25;优先使用 Visual Studio 随附版本 |
| .NET | global.json 指定 10.0.301,允许 latestFeature 向前滚动,不启用预发布 SDK |
| Python | 桥接配方和 CI 使用 Python 3.13 x64,构建时创建隔离虚拟环境 |
| MSYS2 UCRT64 | 默认构建 UxPlay 可选组件和定制 FFmpeg;需要 CMake、Ninja、toolchain、pkgconf、GStreamer base/good/bad/libav、libplist、OpenSSL 及编解码依赖;完整包名见 Windows workflow |
| 网络 | 首次还原 NuGet/Python 包以及准备 FFmpeg、VC Runtime、UxPlay、Inno Setup 等依赖时需要网络 |
Apple USB 支持和实机信任是运行有线功能的条件,不是离线协议单元测试的条件。
标准 ZIP 和 Setup 内置固定版本的 Personalized 与 Cryptex DDI;构建时下载并按 config/ddi-bundles.json 校验,打包缺失或损坏时失败。Apple 个性化签名的网络需求见桥接使用说明。
| 路径 | 职责 |
|---|---|
src/App |
WPF 主程序、设备会话、输入路由、媒体输出及更新器 |
src/Core |
C++20 C ABI、USB/QuickTime、解码、D3D11、WASAPI 与无线 IPC |
src/WirelessHost / src/UxPlayHost |
原始 AirPlay/DLNA 宿主、UxPlay 备用适配进程 |
src/VirtualCamera |
Windows 11 Media Foundation 媒体源、帧交换及注册助手 |
src/DriverInstaller |
独立驱动管理器与提权操作入口 |
src/Shared / src/SharedUI |
共享下载/提权安全逻辑、主题、控件、窗口行为 |
tools/usb_touch_bridge.py / tools/iostouch |
当前 Python 反控桥及 QuickTime 配置下的 USBMux 共存支持 |
src/App/Automation / docs/api |
本地 HTTP Automation API、接入说明及 Python/curl 示例 |
scripts / installer / .github/workflows |
构建依赖、验证、打包、安装器与 CI |
src/*.Tests / tests |
托管、Python 及专项恢复测试;原生测试在各模块的 tests 下 |
docs / updates |
文档与版本说明、应用备用更新清单 |
build / dist / outputs / work |
构建目录、桥接载荷、发布产物和临时依赖;不是唯一源码来源 |
本机持续开发使用 C:/Users/Ray/Documents/iphoneMirror 的 main,开始前检查状态、近期提交并获取远端更新,保留未提交修改;未经明确要求不另建分支或 worktree。
work/main-consolidation 仅为历史恢复备份,不是开发或交付来源。
当前主线交付目录为 outputs/iPhoneMirror-main。下方 build.ps1 的默认输出仍是
outputs/iPhoneMirror,脚本没有自动改用主线交付目录;构建后将验证过的完整载荷整理到主线交付目录。
更新交付前检查程序是否运行,不覆盖运行中的程序;停止或更新运行实例需有相应任务授权。
-TestBuild 会清理整个 outputs,也可能影响主线交付和历史验证产物,不应作为保留现有交付的日常构建方式。
# 默认 Release:构建、测试,并发布自包含应用
./build.ps1 -Configuration Release
# 调试构建和测试,不生成自包含发布目录
./build.ps1 -Configuration Debug -NoPublish-NoPublish 仍会构建桥接器并准备原生依赖,不是只编译 C# 的快捷入口。
常规 Release 产物为 outputs/iPhoneMirror;安装器载荷为
outputs/iPhoneMirror.Installer,主程序使用外置 .NET 运行时,驱动管理器独立自包含,
安装器通过统一压缩减少重复数据。
二者都包含独立桥接器的完整 onedir 载荷。
| 参数 | 行为与限制 |
|---|---|
-SkipTests |
跳过 build.ps1 的测试段;不能据此报告测试通过 |
-OmitUxPlayRuntime |
缺少 MSYS2 时可生成省略 UxPlay 的测试包;原始无线接收端仍保留 |
-IncludeUxPlayRuntime |
将默认独立下载的 UxPlay 组件也内置,适合离线包 |
-OmitMediaOutputRuntime |
省略内置 FFmpeg;应用仍校验候选 FFmpeg 的固定 SHA-256,任意系统 FFmpeg 不能替代 |
-Version |
显式覆盖此次构建的产品版本;常规构建默认取项目版本 |
-TestBuild |
根据源码、版本记录及已有输出递增 -testN,重新整理 outputs 并将测试版发布到其根目录;使用前保存需要保留的产物;不能与 -NoPublish 或 -Version 同用 |
默认使用仓库内 scripts/usb-bridge-recipe,将当前 tools/usb_touch_bridge.py 和
tools/iostouch 暂存后打包。不会自动克隆上游最新分支。配方来源及固定提交见
SOURCE.md,直接依赖版本见
requirements.txt。
IPHONE_MIRROR_USB_BRIDGE_ROOT 覆盖的是构建配方目录;它必须兼容当前 Python 源码。
上游新 Rust 后端采用不同运行时 schema,不能直接替换。应用当前要求运行时清单
schema 1,而 ready 的应用协议号为 2,二者含义不同。
必须一起保留 iUsbBridge.exe、iUsbBridge.runtime.json 和 _internal;只复制 EXE 会
破坏运行时。构建环境位于 work/usb-touch-bridge-python,打包产物位于 dist。
默认构建依次运行 CTest、Python unittest、桥接源码暂存与三个提权启动脚本、三个托管测试程序、
Automation 生命周期专项、VC Runtime 版本解析和 Apple 支持包验证。CI=true 时,脚本明确跳过
App.Runtime.Tests;它并非自动检测所有无桌面环境。本地运行 WPF 测试会创建窗口。
本地化校验由 Windows workflow 单独执行,不包含在 build.ps1 的测试段中。
本地构建还分别在新进程中运行主程序和驱动管理器的 --grid-layout-entry 探针,
验证各自的应用入口在首次 Grid 布局前启用兼容算法。两者不能在同一进程中合并验证,
因为 WPF 会缓存兼容开关。默认运行时套件同时覆盖 2,784 组 Grid 边界及混合布局;
也可单独执行 App.Runtime.Tests --grid-layout-compatibility。故障证据见
启动布局闪退分析。
build.ps1 先编译托管测试,再直接执行测试程序集,并仅为测试子进程清除
SDK/CI 注入的 CLR/.NET 环境覆盖。dotnet run 会注入 DOTNET_ROOT_X64,
触发更新器和驱动的提权环境保护;单独运行涉及提权的测试时,应使用干净环境下的
dotnet <测试程序集.dll>。应用的安全检查和拒绝注入的回归测试保持启用。
若 ctest 不在 PATH 中,使用 Visual Studio 随附 ctest.exe 的绝对路径运行相同参数;
build.ps1 会自动定位它,单独输入 ctest 的终端则需要正确的工具路径。
./scripts/verify_localization.ps1
# 先完成一次同配置构建,确保原生 DLL 与测试程序匹配
ctest --test-dir build/native -C Release --output-on-failure
# 在未设置 CLR/.NET 注入变量的终端中执行;完整构建会自动净化测试子进程环境
dotnet ./src/App.Logic.Tests/bin/Release/net10.0-windows10.0.19041.0/IPhoneMirror.App.Logic.Tests.dll
dotnet ./src/App.Runtime.Tests/bin/Release/net10.0-windows10.0.19041.0/win-x64/IPhoneMirror.App.Runtime.Tests.dll
dotnet ./src/DriverInstaller.Tests/bin/Release/net10.0-windows10.0.19041.0/iPhoneMirror.DriverInstaller.Tests.dll
# 使用构建创建的 Python 环境,避免缺少桥接依赖
$env:PATH = (Join-Path $PWD 'third_party/libusb/bin/x64') + ';' + $env:PATH
& ./work/usb-touch-bridge-python/Scripts/python.exe -m pip install -r tests/requirements.txt
& ./work/usb-touch-bridge-python/Scripts/python.exe -m unittest discover -s tests -p '*test.py'完整构建会在运行 Python 测试前安装 测试依赖,包含手机边框验证使用的 Pillow、NumPy 和 SciPy;这些依赖不属于 HID 桥接运行时。
静态预览回归使用合成 NV12 帧,不连接手机或启动无线接收器:
# 需要可访问的交互桌面;验证静态画面、重绘、缩放、隐藏恢复和故障重试
./build/native/src/Core/Release/iPhoneMirror.Core.Tests.exe --preview-static-frame-only
# DXGI 可呈现但桌面像素不可读取时,仅验证 Present 和重试;不验证显示
./build/native/src/Core/Release/iPhoneMirror.Core.Tests.exe --preview-static-frame-retry-only
# 验证同一 HWND 的公开预览接管、并发停止/销毁、构造失败回滚及核心重启
./build/native/src/Core/Release/iPhoneMirror.Core.Tests.exe --preview-ownership-only
# 验证旧预览释放后立即创建新翻转模型交换链
./build/native/src/Core/Release/iPhoneMirror.Core.Tests.exe --preview-handoff-only测试为每个预览单独注入呈现繁忙、窗口遮挡和上传失败,始终保持同一帧时间戳。
故障注入仅编入原生测试程序,不进入发布用 Core DLL。
若运行环境使窗口始终处于 DXGI_STATUS_OCCLUDED,两种模式都需要改在可呈现的
交互桌面运行;重试模式不会把被遮挡状态当作成功。
| 测试 | 主要覆盖 |
|---|---|
| CTest | QuickTime/CoreMedia 解析、USB 恢复策略、输出状态、无线/UxPlay IPC 与虚拟摄像头组件 |
| App.Logic.Tests | 设备身份、选择、更新解析、输出参数、媒体及输入路由等逻辑 |
| App.Runtime.Tests | 实际 WPF 加载、窗口交互、本地化、焦点、布局及运行时回归 |
| DriverInstaller.Tests | 驱动识别、错误分类、父驱动确认及恢复策略;模拟测试不等于完成真实驱动变更验证 |
| Python unittest | 触控/键盘消息、桥接安全边界、USBMux 与恢复逻辑 |
| PowerShell 验证 | 暂存源、依赖载荷、签名/哈希和安装器规则等专项检查 |
App.Runtime.Tests --automation-lifecycle 包含后台准备/打开窗口的取消、管理锁释放、
已有会话保护及新建会话清理回归。--automation-lifecycle-long-startup 另外运行一次
46 秒的模拟反控启动,验证 API 不再用短于 DDI 准备期限的 45 秒超时中断启动;不连接手机。
当前另有未接入默认构建的专项入口,例如:
./scripts/test_driver_cleanup_safety.ps1
./scripts/test_cleanup_localization.ps1
dotnet run --project tests/UsbRecovery.Tests/UsbRecovery.Tests.csproj -c Release前两个脚本只载入被测定义并使用模拟调用,不执行实际清理入口。
UI smoke、Test-WiredRecoveryDevice.ps1、Test-WiredControlUia.ps1 和
tools/srs-lab/Start-SrsLab.ps1 属于交互/实机场景,先阅读参数及前置条件,再按改动范围选择。
reset_driver_test_environment.ps1、驱动删除脚本和原生 USB 探针可能改变系统或设备状态,
不能当成普通测试批量执行。原生实机探针默认由
IPHONEMIRROR_BUILD_DANGEROUS_USB_TOOLS=OFF 排除。
# 默认从主程序项目读取版本,并要求驱动管理器版本一致
./scripts/package_release.ps1 -GenerateSbom脚本生成 outputs/releases 下的 Setup、ZIP、SHA256SUMS.txt 和 SPDX SBOM。
标准包另附 UxPlay 可选组件 ZIP;应用首次选用时通过镜像下载并显示进度弹窗。
安装包默认以 100,000,000 字节为优化目标,超出时只提醒,组件完整可用优先。
需要强制限制的构建可显式传入 -EnforceInstallerSizeLimit。
不指定旧的 -Version 1.8.3,可避免与当前源码版本冲突。-SkipBuild 仅适用于已有匹配
载荷;它仍执行版本和完整性检查。构建与打包应使用一致的运行时省略选项。
每次交付必须分别测试同一版本的最终 ZIP 和 Setup 安装包,两者都通过后才能报告 “发布包正常”。源码测试、构建成功、打包成功或发布目录中的运行结果,均不能代替 实际交付产物的运行验证。验收至少覆盖以下项目:
| 产物 | 必测项目 |
|---|---|
| ZIP 便携版 | 将最终 ZIP 完整解压到独立目录,核对版本、必需文件与哈希;从解压目录启动主程序和驱动管理器,验证首次启动、设置保存、关闭及再次启动。 |
| Setup 安装包 | 使用最终安装 EXE 在隔离测试环境中全新安装,从安装目录启动主程序和驱动管理器;验证快捷方式、版本与文件完整性、覆盖升级及设置保留、卸载与重新安装。 |
| 两者分别执行 | 验证本次修改涉及的功能;有实机条件时分别验证有线/无线连接、投屏、键鼠控制、断开重连,以及退出后无需人工拔插即可再次连接和控制。需要按需下载的组件,应分别验证下载后可用。 |
scripts/test_installer.ps1 可补充安装、升级、卸载回归,但它会重新生成隔离测试安装器,
不能替代对最终交付安装 EXE 的验证,也不能替代 ZIP 验收。
测试记录应分别列出 ZIP 与 Setup 的版本、SHA-256、测试环境、场景、结果及日志位置。
任何一项失败或因环境限制未执行,都必须明确记录为失败或待验证;修复后重新打包,
并重新验证受影响的两种最终产物,不能沿用旧包的通过结果。
待上传资产确定后,可加 -UpdateReleaseManifest 同步 updates/releases.json 中
对应版本的大小与哈希。打包脚本不会代替维护者上传 GitHub Release。
-AllowVersionOverride 是显式覆盖,不应拿来掩盖主程序与驱动管理器的版本分歧。
Apple 支持包只在拥有再分发权时显式提供;参数及校验要求见
驱动依赖说明。通常公开包不包含 Apple USB 支持 MSI;
DDI 是另一项载荷,当前标准包按 config/ddi-bundles.json 内置并校验 Personalized 与 Cryptex 镜像。
其分发状态见组件来源说明。
发布说明放在 docs/releases,根目录变更记录汇总版本;不要把工作区验证结果写成已发布事实。
- 文档检查:
python scripts/verify_docs.py离线检查本地链接、图片、锚点、围栏及索引覆盖; 外部链接可用性、命令实际行为和真机结论需另行验证。 - 用户设置由
UpdateSettingsStore保存到%LOCALAPPDATA%/iPhoneMirror/settings.json; 设备绑定位于同目录的device-binding-profiles.json。 - 主程序诊断位于
%LOCALAPPDATA%/iPhoneMirror/Logs;驱动 UI 日志位于%LOCALAPPDATA%/iPhoneMirror.Driver/Logs/driver-ui.log。 - 父驱动快照与提权日志位于
%ProgramData%/iPhoneMirror.Driver;快照不等于完整驱动备份。 - 修改 C ABI 或 IPC 时同步两端结构、版本校验和对应测试;原生 API、无线 IPC、桥接运行时 清单、输入 JSON schema 是不同契约,参见架构说明。
- 变更记录注明实际执行的命令、结果及未覆盖的实机环境;脱敏 UDID、配对记录和个人屏幕内容。