QFT · 超速二维码文件传输 v0.4.16
Windows + Android 双向正式版。v0.4 的核心目标不是继续堆“4 码理论吞吐”,而是解决 Android 端实际识别慢的问题:删除 2×2/4 通道,改成一个大二维码 + 动态 ROI 锁定 + 高频局部解码。
v0.4.16 提供两套互不依赖的传输方式:
- 电脑 → 手机(纯光学):文件数据只经过 Windows 屏幕 → Android 摄像头;Wi‑Fi、蓝牙、局域网和互联网都不参与文件数据传输。
- 扫码本地直传(双向):Windows 为“手机上传”和“电脑下发”分别生成方向明确的二维码。Android 扫码后连接 QFT 本地网络、通过 UDP/网关/子网探测定位电脑,并按二维码指定方向自动进入选文件上传或接收下载;文件数据不经过外网。
v0.4.16 直传稳定性与并发策略
- 双向均使用并行分块:每个可分块文件以 8 路为目标并发数;分块大小根据文件大小自适应,范围为 64 KiB–16 MiB。小于一个最小分块的文件会自然只有一个请求。
- 手机 → 电脑:Android 使用 offset 定位的 Parallel v2 上传;Windows 对每块进行定位写入,重复块与完成请求可安全重试,最终以 SHA-256 校验后原子改名。
- 电脑 → 手机:Windows 支持精确的 HTTP
Range(206 Partial Content);Android 对未完成块创建多个独立 Range 请求,并用.qftpart与完成位图恢复中断传输。每块最多重试 5 次,完成后校验 SHA-256 再保存至Downloads/QFT。 - 连接稳定性:Windows 监听器保持非阻塞以便及时停止服务,但已连接的文件套接字会切换为带读写超时的阻塞模式,避免 Windows
WSAEWOULDBLOCK (10035)造成大文件中途失败。
v0.4.16 已完成协议、图像合成解码、ROI、双向并发传输、专用 Wi-Fi 快速发现、队列拖动稳定性和关键 Kotlin 源码测试。当前生成环境没有真实 Windows 显示器、Android 相机或 Wi‑Fi Direct 适配器,因此物理 30/45/60 FPS 和真实扫码配网仍需在你的设备上跑
VERIFY_WINDOWS_HOST.ps1后做最终验收;详见TEST_REPORT.md。
v0.5.0-dev5:Android → Android 手机互传
当前开发版新增 Android 手机之间的扫码直传闭环:
- 发送手机选择多个文件、删除或拖动调整顺序,然后生成
QFTPHONE2二维码; - Android 8+ 优先创建系统 LocalOnlyHotspot,接收手机扫码后自动加入;
- Android 7 或临时热点不可用时,自动回落到两台手机当前同一 Wi-Fi;
- 二维码只携带一次性会话和网络身份,文件队列通过会话认证后读取,避免多文件让二维码过密;
- 每个文件复用现有最高 8 路 HTTP Range、断点位图和 SHA-256 校验,按发送队列顺序保存到
Downloads/QFT; - 发送页面必须保持打开,返回首页会立即关闭发送服务和临时热点。
- 发送二维码按当前应用窗口的实际可用宽高动态生成并居中,手机、平板和分屏窗口都不会再被
match_parent放大溢出。 - Android 7–9 接收端每次扫码都会用二维码中的新密码刷新临时 Wi-Fi 配置,不再复用同名热点的旧密码;Android 10+ 也只复用完整凭据一致的系统配网请求。
- 当高版本发送机只能创建旧设备不支持的纯 WPA3 热点时,接收端会跳过无效的系统搜索,并自动尝试二维码内经过认证的原局域网地址。
- 手机发送端建立自适应 Wi‑Fi Direct 接入点:Android 10+ 先使用自动频段争取 5 GHz 高速链路;12 秒未收到认证连接时,才以同一 SSID/密码切换至 2.4 GHz 兼容旧机,无需重新扫码。
- 手机互传使用顺序 Range 接收以规避部分 Android 7–9 文件提供器并发读取损坏,并在生成二维码前校验文件选择器报告的大小与实际内容一致。
此阶段只实现 Android → Android;Android ↔ iOS 尚未接入。
v0.5.0:iOS 客户端全面接入
iOS 端补齐到与 Windows / macOS / Android 对齐的四条链路,改动只在 ios/ 目录内,
未触碰 desktop/ 与 android/ 的任何实现:
- 光学接收(电脑 → iPhone):Swift 实现的 QFT2 + Base45 + CRC32 解码链路, AVFoundation 取帧、Vision 解码、与 Android 同一套「居中搜索 → ROI 锁定 → 丢失逐级放大 → 重新搜索」状态机。文件数据只经过屏幕和摄像头,不碰任何网络。
- iPhone ↔ Windows(专用网络):接受只带 Wi-Fi 凭据、不带地址的 QFT Direct 二维码;
有 HotspotConfiguration entitlement 时用
NEHotspotConfiguration自动加入, 没有时显示 SSID/密码引导手动连接——不会假装成功。加入后从sysctl路由表 认出网关即电脑,判据是协议层/qft/ping握手成功而非系统回调。 - iPhone ↔ Mac / Linux(局域网):既可扫二维码,也可直接输电脑上的连接码
(
QFTBROWSE3广播列出附近的电脑,POST /qft/pair换令牌)。电脑下发改成 8 路并行 Range + 断点账本,对端不支持分段时自动回落单流。 - iPhone ↔ iPhone(隔空):沿用 AWDL 点对点 + TLS-PSK,升级为 多文件队列(QFTP2P2)。清单不进二维码,只放摘要,扫码依然锁定 「你看到的就是你收到的」。
最低系统 iOS 15.0(iPhone 6s 及以后),与 Android 端 minSdk 24 覆盖的机型年代相当;
iOS 16/17 才有的 API 全部走 ios/QFT/App/Compatibility.swift 分叉。
详见 ios/README.md。核心层 180 项检查可在没有 Xcode 的机器上直接跑:
./ios/CoreTests/run.sh
v0.4.8:跨平台桌面端 + 电脑 ↔ 电脑互传
macOS:请用 QFT超速文件传输.app 启动,不要直接跑裸二进制
./package.sh 在 macOS 上会同时产出 QFT超速文件传输(裸二进制)和
QFT超速文件传输.app,推荐使用 .app 版本。
直接运行裸二进制时,AppKit 的部分行为会不稳定——最典型的是点「选择文件」时
+[NSOpenPanel openPanel] 返回 NULL:
panicked at objc2-app-kit/src/generated/NSOpenPanel.rs:
unexpected NULL returned from +[NSOpenPanel openPanel]
程序侧已经兜住了这个 panic(不会再崩溃,只提示"对话框没有返回结果"),
但要彻底避免,用 .app 启动即可。
任何情况下都可以直接把文件拖进窗口——拖拽不经过系统文件对话框。
Windows 构建报 os error 5 拒绝访问
error: failed to remove file `...\target\release\qft-desktop.exe`
Caused by: 拒绝访问。 (os error 5)
QFT 窗口还开着,正在运行的 exe 锁住了产物文件。关掉窗口再构建即可。
VERIFY_WINDOWS_HOST.ps1 会在构建前检测并询问是否结束进程。
若关掉后仍然报错,通常是 Windows Defender 正在扫描刚生成的 exe,
稍等几秒重试;也可以把 desktop\target 加入 Defender 排除目录。
防火墙放行(手动)
接收端要监听入站 TCP,Windows 防火墙默认会拦截未授权程序,表现是 「对方能解析连接码但连接一直超时」。
程序在「电脑 ↔ 电脑 → 我要接收」页会只读检测防火墙状态,并提供 「放行防火墙(需要管理员授权)」按钮——提权只在你点击时发生, 不会在启动时自动弹 UAC。
也可以自己加规则。两个必须注意的点:
- 二进制已从
qft-windows.exe改名为qft-desktop.exe,此前给旧名字 放行的规则对新程序不生效。 - profile 必须是
Any。Windows 对没见过的 Wi-Fi 默认归类为 「公用网络」,此时只覆盖Private,Domain的规则根本不适用—— 规则建了、Get-NetFirewallRule也显示 Enabled,但连接照样被拦。
$exe = "<完整路径>\qft-desktop.exe"
# 先清掉可能存在的阻止规则:Windows 里 Block 永远优先于 Allow
Get-NetFirewallApplicationFilter -Program $exe -ErrorAction SilentlyContinue |
Get-NetFirewallRule | Where-Object Action -eq 'Block' | Remove-NetFirewallRule
New-NetFirewallRule -DisplayName "QFT Desktop" -Direction Inbound `
-Program $exe -Action Allow -Profile Any
排查时先看这两列:
Get-NetConnectionProfile | Format-List Name,NetworkCategory
Get-NetFirewallApplicationFilter | Where-Object Program -like "*qft*" |
ForEach-Object { $r = $_ | Get-NetFirewallRule
[PSCustomObject]@{ 规则=$r.DisplayName; 动作=$r.Action; 配置=$r.Profile } } | Format-Table
若 NetworkCategory 是 Public 而规则的 配置 只有 Domain, Private,
就是这个原因。
管理员 PowerShell:
New-NetFirewallRule -DisplayName "QFT Desktop" -Direction Inbound `
-Program "<完整路径>\qft-desktop.exe" -Action Allow -Profile Private,Domain
或在「允许应用通过 Windows Defender 防火墙」里勾选 qft-desktop.exe 的专用网络。
排查顺序:对端 ping 不通且 TCP 端口连不上,但 arp -a 能看到对方 MAC,
基本可以判定是对端主机在丢包(防火墙),而不是网络不通。
桌面端目录从 windows/ 改名为 desktop/,crate 更名 qft-desktop,
现已可在 macOS / Linux / Windows 三平台编译运行。平台差异全部收敛在
desktop/src/platform.rs(配置目录、下载目录、设备名、Direct AP 能力),
其余模块不再出现 #[cfg(target_os)]。
新增两块此前完全缺失的能力:
desktop/src/client.rs—— 桌面端的发起侧。此前桌面只有服务端,TcpStream::connect仅存在于测试中,因此 PC 无法主动连接另一台 PC。desktop/src/discovery.rs—— 局域网节点浏览(UDP 广播QFTBROWSE3)。 既有的QFTDISC2是「已知令牌找机器」,用于手机扫码之后; PC↔PC 没有摄像头,必须先能列出附近有哪些节点。
配对方式:接收方启动后显示 6 位配对码,发送方搜索到对方后输入该码
换取会话令牌(POST /qft/pair)。6 位约 20 bit 熵,靠严格失败计数兜底——
错 5 次即作废整个码,需要重新启动接收。
已知限制:UDP 广播只覆盖同一广播域,跨网段或开了 AP 隔离的 Wi-Fi 搜索不到对方,此时在界面上手动输入对方 IP。
v0.4 光学链路改动
单码替代 4 码
4 码已从主链路彻底删除。原因是实际手机相机里,每个 QR 变小后会同时带来:
- 每模块像素下降;
- finder 搜索次数增加;
- Android 同帧多次 ZXing 解码;
- 更高的摩尔纹/滚动快门敏感度;
- Windows 理论 B/s 提升,但 Android “有效新帧/s”可能反而下降。
v0.4 把全部屏幕和解码预算投入一个大 QR。
QFT2 + Base45 低密度帧
活跃光学协议升级为 QFT2::
- 二进制帧仍包含 session / sequence / total / payload / CRC32;
- 文本层使用 RFC 9285 Base45;
- Base45 字符集属于 QR 字母数字模式可编码范围;
- DATA payload 默认 450 B;
- QR 使用 L 级纠错和完整 4-module quiet zone;
- 合成测试中的 450 B DATA 帧为 QR-L v15,旧 QFT1/Base64 480 B 对照约为 v18;
- 60 显示帧/s 的理论纯 payload 为
450 × 60 = 27,000 B/s ≈ 26.4 KiB/s,真实速度取决于相机真实分析 FPS 和有效新帧率。
Android 仍保留 QFT1 解析用于旧发送端兼容。
Android 识别优化
Acquire → Lock → Expand → Reacquire
扫描器状态机现在是:
搜索大二维码
↓
ZXing finder points
↓
建立方形 ROI
↓
后续只复制/解码 ROI
↓
轻微移动:平滑跟随
↓
连续 miss:逐级扩大 ROI
↓
持续丢失:重新全局搜索
Android UI 会实时画出真正使用的锁定区域:
- 未锁定:白色搜索角标;
- 稳定锁定:绿色框 + 外围暗化;
- 临时 miss:黄色框;
- 锁定区域随 finder points 平滑移动,减少抖动;
- 锁定后周期性在 ROI 中心重新触发 AF/AE。
高频解码热路径
ImageAnalysis固定为 640×480;STRATEGY_KEEP_ONLY_LATEST,不追赶过时相机帧;- Camera2Interop 从后摄实际公布的 AE FPS ranges 里选择最高不超过 60 的范围,并同时应用到 Preview/ImageAnalysis;若 OEM 拒绝该流组合,会自动回退相机默认 FPS,而不是让扫描器启动失败;
- 单个
QRCodeReader,无 4-reader 线程池; - 锁定后只复制 Y 平面 ROI;
GrayFrameBuffer复用 grow-onlyByteArray,降低 Android 7/8 GC;- 常态使用
GlobalHistogramBinarizer;Hybrid 只在周期性 miss 时兜底; - 重复显示帧虽然计入“成功解码”,但不再重复送入文件 assembler;UI 单独显示“解码/s”和“新帧/s”。
Windows 光学 UI
Windows 光传页面已经改成“二维码优先”:
- 左侧控制区 / 右侧二维码区;
- 中间分隔条可拖动,压缩控制区后 QR 自动变大;
- “专注二维码”一键收起大部分控制 UI;
- QR 画面占比可调;
- FPS 5~60,快捷 30 / 45 / 60;
- 单个大 QR,NEAREST 纹理采样,避免插值模糊;
- 1024×1024 预编码画布,使用整数 module 像素和完整静区;
- 后台 Rayon 并行预编码未来帧,前台只复用一个 GPU TextureHandle。
推荐初次真机测试从 30 FPS 开始,看 Android 的“新帧/s”,再切 45、60。目标不是 Windows 数字最大,而是 Android 实际新帧/s 最大。
扫码本地直传(Android ↔ Windows)
v0.3 的稳定性优化继续保留:
- QFTPAIR2 紧凑配对 QR;
- QFT Direct 或当前局域网;
- Android 10+
WifiNetworkSpecifier;Android 7~9 legacy Wi-Fi; - 扫码连接后 UDP
QFTDISC2快速发现; - gateway / endpoint / 当前子网 fallback;
- HTTP 请求明确绑定扫码建立的
Network; - 配网请求在传输页持续持有,仅返回首页时释放;短暂网络波动会自动接入新的
Network; - 手机上传和电脑下发均以 8 路为目标并发数;
- 64 KiB–16 MiB 自适应分块;
- 电脑下发使用精确 Range 响应,手机以
.qftpart+ 位图断点续传; - 手机上传使用定位写入和幂等完成确认;
- Windows positioned writes +
.qftpart+ SHA-256 + 最终 rename。
Android 版本
minSdk = 24,即 Android 7.0;- Android 7~9:旧 Wi-Fi 与 Downloads 写入兼容;
- Android 10+:WifiNetworkSpecifier + MediaStore;
- Android 13+:NEARBY_WIFI_DEVICES 权限。
构建
Windows
cd desktop
cargo check
cargo test
cargo build --release
cargo run --release
Android
JDK 17,compileSdk/targetSdk 35,minSdk 24:
cd android
.\gradlew.bat :app:testDebugUnitTest :app:assembleDebug
APK:
android/app/build/outputs/apk/debug/app-debug.apk
一键打包
脚本执行锁定依赖的 Rust 测试和正式构建,随后把桌面程序、中文说明、协议及 SHA-256 校验收集到带时间戳的 dist/QFT-正式版-* 目录。脚本不会安装、下载或调用 Android SDK、Java、Gradle;如果已经在 Windows 上构建好 APK,则会自动将它收集进同一个中文正式包:
package.bat
./package.sh
字体
桌面端 UI 优先读取 desktop/assets/qft-ui.ttf,也可用 QFT_FONT_PATH 指向你自己的中文 TTF。仓库不附带第三方字体文件。
自动验证
python scripts/run_all_selftests.py
Windows 主机建议直接:
.\VERIFY_WINDOWS_HOST.ps1
它会继续执行 Rust cargo check/test/build 和 Android Gradle 单测/APK 构建。物理相机/屏幕和 Wi‑Fi Direct 项目见 TEST_REPORT.md。