Files
QFT/README.md
T
zhy200308 99be46acf7 release: v0.4.8 跨端 PC 互传封版;修复发送端进度直到结束才更新
实测 1.01 GB / 23.11 MB/s 传输成功,但发送端进度条全程 0%、
最后才跳到 100%,接收端却是实时的。两处原因,都已修复。

1. 请求体一次性写出
   16 MiB 的分块用单次 write_all 送出,中途没有任何可上报的点。
   改为 256 KiB 一片:足够小让进度看起来连续,又足够大不拖慢吞吐。
   put_chunk 逐片累加共享计数;失败重试时把本次尝试已计的字节扣回去,
   否则重试会让进度虚高甚至越过 100%。

2. on_progress 只在所有 worker 结束后调用一次
   主线程改为在 worker 运行期间轮询上报(40 ms 一次,对 UI 足够,
   代价可忽略),而不是等 thread::scope 返回。

测试拆成两层
- 确定性单测 body_progress_is_reported_incrementally:5 片请求体必须
  上报 5 次、总量吻合。回环速度太快时集成测试采样不到中间进度,
  只有这一层能稳定拦住回归
- 集成测试改为断言稳健性质:进度单调不减、且不超过文件总长
  (后者正是重试重复计数会破坏的)
- 配套的 mock 服务端按 Content-Length 精确读取。此前用 read_to_end
  会一直等客户端关闭写端,而客户端在等响应,两边互等直接死锁

封版
- 版本 0.5.0-m1 → 0.4.8,接续既有编号
- 界面与 README 里残留的「6 位配对码」文案更新为连接码

本版可用范围:mac / win / linux 桌面端互传,连接码内含地址,
不要求同一网段,只要 IP 层可路由到达即可。
2026-08-11 19:37:21 +08:00

286 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.
# 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.4.8:跨平台桌面端 + 电脑 ↔ 电脑互传
### macOS:请用 QFT.app 启动,不要直接跑裸二进制
`./package.sh` 在 macOS 上会同时产出 `QFT-Desktop`(裸二进制)和 `QFT.app`,
**推荐用 `QFT.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。
也可以自己加规则。两个必须注意的点:
1. 二进制已从 `qft-windows.exe` 改名为 `qft-desktop.exe`,**此前给旧名字
放行的规则对新程序不生效**。
2. **profile 必须是 `Any`**。Windows 对没见过的 Wi-Fi 默认归类为
「公用网络」,此时只覆盖 `Private,Domain` 的规则根本不适用——
规则建了、`Get-NetFirewallRule` 也显示 Enabled,但连接照样被拦。
```powershell
$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
```
排查时先看这两列:
```powershell
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:
```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
扫描器状态机现在是:
```text
搜索大二维码
↓
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
```powershell
cd desktop
cargo check
cargo test
cargo build --release
cargo run --release
```
### Android
JDK 17,compileSdk/targetSdk 35,minSdk 24:
```powershell
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:
```bat
package.bat
```
```bash
./package.sh
```
## 字体
桌面端 UI 优先读取 `desktop/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。
## 自动验证
```bash
python scripts/run_all_selftests.py
```
Windows 主机建议直接:
```powershell
.\VERIFY_WINDOWS_HOST.ps1
```
它会继续执行 Rust `cargo check/test/build` 和 Android Gradle 单测/APK 构建。物理相机/屏幕和 Wi‑Fi Direct 项目见 `TEST_REPORT.md`。