Files
QFT/README.md
T
zhy200308 376ffba96e feat(desktop): 跨平台桌面端 + 电脑↔电脑互传(v0.5.0-m1)
对应 V05_EXECUTION_PLAN 的 P1。核心改动是把「PC 只能当服务端」
这个写死的角色拆开——此前 TcpStream::connect 只出现在测试里,
桌面端根本无法主动连接另一台桌面端,PC↔PC 因此完全不可用。

跨平台
- windows/ → desktop/,crate 更名 qft-desktop
- 新增 platform.rs 收敛全部平台差异:配置目录(LOCALAPPDATA /
  Application Support / XDG)、下载目录(含 Linux 本地化的 ~/下载)、
  设备名、Direct AP 能力。约定:其余模块不得再出现 #[cfg(target_os)]
- direct_ap.rs 的 Context 导入按平台条件化,非 Windows 上不再告警
- macOS 上已实测编译并链接出可执行文件(65 MB Mach-O arm64),
  这是本仓库首次在非 Windows 平台构建成功

电脑 ↔ 电脑
- 新增 client.rs:桌面端发起侧。手写 HTTP,不引入客户端依赖——
  服务端本来就是手写的,两边同一套解析更容易与 Android/iOS 对齐。
  含并发分块上传(自适应 4/8/16 MiB、最多 8 worker)与 Range 断点续传
- 新增 discovery.rs:UDP 广播 QFTBROWSE3 浏览局域网节点。
  既有的 QFTDISC2 是「已知令牌找机器」,用于扫码之后;
  PC 没有摄像头,必须先能列出附近有谁
- receiver.rs 新增 POST /qft/pair:用 6 位配对码换会话令牌。
  这是唯一不校验令牌的端点。6 位仅约 20 bit 熵,配严格失败计数兜底——
  错 5 次即作废,需重启接收;比较用定长实现,不做短路返回
- 新增「电脑 ↔ 电脑」界面:接收方显示配对码与本机地址;
  发送方搜索/手动输入地址 → 输码连接 → 多选文件 → 带进度发送

验证(macOS,Rust 1.97.1)
- cargo check 0 错误,cargo test 17/17 通过
- 新增端到端用例:真实起接收服务 → 配对(含错误码必须被拒)→
  9 MB 跨多分块并发上传 → 校验落盘内容逐字节一致且 SHA-256 与
  接收端返回值相同。这就是 PC↔PC 的完整链路
- 11 项 Python 自检全部通过

顺带修复
- single_channel_guard_selftest 长期为红:它断言
  DEFAULT_CHUNK_SIZE = 450,而代码早已改为 320。改名前即存在,
  已用 git stash 验证与本次无关。改为范围检查(128~4096)并在
  PASS 信息里打印实际值,既挡住"退回多通道小块"又不会因调参误报

已知限制
- UDP 广播只覆盖同一广播域。跨网段或 AP 隔离的 Wi-Fi 上搜索不到,
  需手动输入对方 IP(界面已说明)。mDNS 留待后续
- 本阶段仍走 v2 明文 HTTP,加密随 QFT-Stream v3 一起做(见 P2)
2026-08-11 16:36:33 +08:00

8.6 KiB
Raw Blame History

QFT · 超速二维码文件传输 v0.4.7

Windows + Android 双向候选版。v0.4 的核心目标不是继续堆“4 码理论吞吐”,而是解决 Android 端实际识别慢的问题:删除 2×2/4 通道,改成一个大二维码 + 动态 ROI 锁定 + 高频局部解码。

v0.4.7 提供两套互不依赖的传输方式:

  • 电脑 → 手机(纯光学):文件数据只经过 Windows 屏幕 → Android 摄像头;Wi‑Fi、蓝牙、局域网和互联网都不参与文件数据传输。
  • 扫码本地直传(双向):Windows 为“手机上传”和“电脑下发”分别生成方向明确的二维码。Android 扫码后连接 QFT 本地网络、通过 UDP/网关/子网探测定位电脑,并按二维码指定方向自动进入选文件上传或接收下载;文件数据不经过外网。

v0.4.7 直传稳定性与并发策略

  • 双向均使用并行分块:每个可分块文件以 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.7 已完成协议、图像合成解码、ROI、双向并发传输、UDP 发现、内存预算和关键 Kotlin 源码测试。当前生成环境没有真实 Windows 显示器、Android 相机或 Wi‑Fi Direct 适配器,因此物理 30/45/60 FPS 和真实扫码配网仍需在你的设备上跑 VERIFY_WINDOWS_HOST.ps1 后做最终验收;详见 TEST_REPORT.md。

v0.5-m1:电脑 ↔ 电脑互传(新增)

桌面端目录从 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-only ByteArray,降低 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

一键打包

脚本只打包 desktop/ 下的 Rust 桌面端:执行 cargo test 和 cargo build --release,随后把 Rust 二进制、协议说明和 SHA-256 校验文件收集到带时间戳的 dist/QFT-Rust-* 目录并生成压缩包。脚本不检查、下载或调用 Android SDK、Java、Gradle:

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。