Files
QFT/docs/V05_EXECUTION_PLAN.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

9.8 KiB
Raw Blame History

QFT v0.5 执行计划

配套设计文档:V05_MULTIPEER_PLAN.md


0. 三个默认决策(未经确认,可推翻)

设计文档结尾留了三个待定问题,为了让计划能往下排,先按以下默认执行。任一项改变都会影响排期,改之前先说。

问题 默认决策 理由
M1 先做还是直接上 v3? M1 先做 零协议风险,做完立刻拿到真实 PC↔PC 体验;v3 的很多设计细节需要真实使用反馈才定得准
加密在哪一版做? 放到 v3(P2),M1 维持现状明文 TLS 与新协议一起做只需改一次握手层;分两次做要动两遍,且 M1 的目的是尽快验证对称节点模型
共享核心怎么做? 桌面共享 Rust + 移动端原生 + conformance/ 一致性套件 桌面三平台本来就是同一份代码(实测仅 3 处平台耦合),共享零成本;移动端 FFI 要等 v3 定型才划算

1. 总体流程

flowchart TD
    P0["P0 收尾验证<br/>把半成品编译掉"] --> P1["P1 桌面跨平台 + PC↔PC<br/>走现有 v2 协议"]
    P1 --> P2["P2 QFT-Stream v3<br/>目录直传 + 加密"]
    P2 --> P3["P3 移动端接入 v3"]
    P3 --> P4["P4 手机 ↔ 手机"]
    P2 -.并行.-> P5["P5 一致性套件<br/>+ 性能回归"]
    P0 -.独立并行轨.-> OPT["QFT5 光学<br/>阻塞于楔形标定"]

    style P0 fill:#7a2020,color:#fff
    style OPT fill:#5a4a20,color:#fff

P0 是硬阻塞。 当前有三处「写了但没验证」的代码,在其之上继续叠加会让问题定位成本指数上升。


2. P0 · 收尾验证(阻塞,必须先做)

# 任务 涉及 验收标准 谁做
P0.1 Android bug 修复编译 DownloadClient.kt WifiConnector.kt MainActivity.kt ./gradlew :app:assembleDebug 通过 你(我没有 Android SDK)
P0.2 Android bug 修复实测 — 大文件传输走完全程;断网时 3 秒内报「临时网络已断开」而非等满重试;空间不足在开始前就提示 你(需真机 + Windows 主机)
P0.3 iOS 模拟器编译 ios/QFT/App/*.swift Xcode 选 iPhone 模拟器,⌘B 无红色错误 你
P0.4 xcode-select 指向 Xcode — xcodebuild -version 可用 你(需 sudo)
P0.5 修掉 P0.1/P0.3 暴露的编译错误 视情况 同上重跑通过 我
P0.6 提交并推送 — 工作区干净 我

门禁:P0.1 与 P0.3 全绿才进入 P1。

P0.4 做完之后我可以直接在命令行编译 iOS 工程,后续 Swift 改动就不再是盲写——这一项虽然可选,但会显著提升后面所有 iOS 相关工作的质量。


3. P1 · 桌面跨平台 + PC↔PC

目标:mac ↔ win、linux ↔ win 能互传单个文件,仍走现有 v2 HTTP 协议。

# 任务 涉及 规模 验收标准
P1.1 windows/ → desktop/,crate 更名 qft-desktop 目录 + Cargo.toml + CI 脚本 + VERIFY_WINDOWS_HOST.ps1 S cargo check 在 macOS 上通过
P1.2 平台抽象层 platform.rs 新增;改 direct_ap.rs pairing.rs:148 protocol.rs:194 M 三平台各自 cargo test 通过
P1.3 配置/下载目录跨平台 pairing.rs + 新增 S mac 写到 ~/Library/Application Support/QFT,linux 写到 $XDG_CONFIG_HOME/qft
P1.4 桌面客户端 client.rs 新增(当前完全缺失) L 单元测试:对本进程起的 receiver 完成一次上传 + 一次下载
P1.5 mDNS 发现 discovery.rs 新增,mdns-sd crate M 两台机器互相出现在列表里;TXT 含 v/id/name/platform/port
P1.6 6 位配对码 pairing.rs M 跨网段场景下输码可连;错码 3 次锁定
P1.7 UI:「附近的设备」页 + 拖拽发送 main.rs L 拖文件到窗口即发送
P1.8 macOS / Linux 打包 新增 CI M 产出 .app(未签名)与 AppImage/tar.gz

P1 验收门

✅ mac → win  传 1GB 单文件,SHA-256 一致
✅ win → mac  同上
✅ linux → win 同上
✅ 三平台各自能在「附近的设备」里看到另外两台
✅ 拔网线重插后能续传(v2 的 Range 续传)

这一门通过之前不进 P2。 因为 v3 的价值全部建立在「对称节点模型成立」之上,先用最简单的协议把这个模型验证掉。


4. P2 · QFT-Stream v3

目标:目录直传可用,先只在两台 PC 之间。

# 任务 规模 验收标准
P2.1 帧编解码 + 黄金测试向量 M 向量文件 conformance/frames.json,编解码往返一致
P2.2 Ed25519 身份 + 信任库 M 首次运行生成密钥;重启后身份不变
P2.3 TLS 1.3(rustls)+ 按公钥验证对端 L 错误公钥必须握手失败;6 位校验码两端一致
P2.4 会话层:SESSION_OPEN / INDEX_* / HAVE L 断开重连后不重传已完成文件
P2.5 流式并行索引 M 10 万文件树:首字节传输在遍历完成前就开始
P2.6 小文件合批 L 见下方性能门
P2.7 大文件分块并发 + 流控反压 M 接收端磁盘限速时内存不超过 连接数 × 8MiB
P2.8 路径安全层 M 见下方安全门
P2.9 每文件 SHA-256 + 单遍哈希 S 单个坏文件只重传自己

P2 性能门(在千兆有线上实测)

场景 目标 现状对照
5 万小文件 / 0.95 GB < 15 s v2 约 608 s
3 千文件 / 11.7 GB < 120 s v2 约 138 s
单文件 10 GB < 95 s v2 约 87 s(不得退化)
峰值内存 < 200 MB —

P2 安全门(跨系统路径用例,全部必须通过)

linux → win : 目录含 CON.txt / aux.log / "a<b>.txt" / 结尾带空格的名字
linux → win : 同目录下 README.md 与 readme.md(大小写冲突)
linux → mac : 文件名含 "é"(NFC/NFD 归一化)
任意 → 任意 : 路径含 ../、绝对路径、指向根目录外的符号链接 → 整会话拒绝
win  → 任意 : 路径长度超过 260

每条都要有自动化用例,不能靠手测。


5. P3 · 移动端接入 v3

# 任务 端 规模
P3.1 Android NodeServer.kt(ServerSocket + v3 帧) Android L
P3.2 Android NsdManager 发现 Android M
P3.3 Android 前台服务 + WakeLock Android M
P3.4 Android 目录接收(SAF OPEN_DOCUMENT_TREE) Android M
P3.5 iOS PeerLink 并入 v3 帧格式 iOS M
P3.6 iOS 目录接收 + 「文件」App 导出 iOS M

门禁:手机 ↔ 电脑走 v3 传一个 5000 文件的目录成功。

P3.3 是现有隐患的正式修复——当前只有 FLAG_KEEP_SCREEN_ON,息屏或切后台就有被系统掐断的风险。


6. P4 · 手机 ↔ 手机

组合 任务 备注
iOS ↔ iOS 已实现,接 v3 即可 PeerLink.swift 复用
Android ↔ Android WifiP2pManager 或 Local Only Hotspot,回落同 LAN 新增
Android ↔ iOS 仅同一局域网 UI 必须明确提示,不给假希望

门禁:三种组合各传一个含子目录的相册目录成功。


7. P5 · 一致性套件(与 P2 并行)

把 ios/CoreTests/MockPCServer.py 的做法推广成 conformance/:

conformance/
  vectors/          黄金测试向量(帧编解码、路径规范化、合批边界)
  reference_peer.py 参考对端,任一端实现都能对着它跑
  run.sh            三端各自跑一遍

接入 scripts/run_all_selftests.py。这是目前防三端协议漂移最有效的手段,在 iOS 端已验证有效。


8. 验证责任分工

这个项目的返工大多来自「写完没法验证」。明确分工:

我能在这台 Mac 上做 只有你能做
Rust cargo check/test(装了 Rust 之后) Windows 上的 cargo build --release 与真机跑
Swift 核心层编译 + 单测 iOS 真机(相机、AWDL)
Swift 全量编译(需你先做 P0.4) Android 编译与真机
Python 工具与一致性套件 千兆有线上的性能实测
协议设计、黄金向量、代码审查 楔形标定拍照

Kotlin 目前我完全无法编译(本机无 Android SDK,装 kotlinc 会连带拉一个多余的 JDK)。所以 Android 侧改动我会尽量小步、单文件,每次都请你编译一次再继续——不要攒一大批。


9. 并行轨:QFT5 光学

与 v0.5 无依赖关系,可随时插入。当前阻塞于楔形标定:

你拍标定图 → 跑 wedge_analyze.py → 得到实测 px/模块
    ↓
  ≤3.2 → 按 OPTICAL_V5_PLAN 原样实施
  3.2~4.0 → 目标 B 不可达,需下调指标
  >4.0 → 先排查对焦/曝光,不要动协议

标定之前可以做的(不依赖该数值):相机帧率三级锁定、手动短曝光、关 EIS/抗闪烁、锁对焦、陀螺仪前馈。这几项对现有 QFT2 链路也立刻有收益(3px/模块下 33ms 自动曝光会产生 8.7px 运动模糊,等于抹掉近 3 个模块)。


10. 回滚点与风险

阶段 回滚点 触发条件
P1 保留 windows/ 分支 tag 跨平台抽象破坏了 Windows 行为
P2 v2 与 v3 并存,节点协商版本 v3 性能门不达标
P3 移动端可继续用 v2 v3 在移动端内存/耗电不可接受

每个阶段结束打一个 tag,v3 与 v2 全程并存,任一阶段失败都不影响已发布版本可用。


11. 下一步

按顺序,现在只需要做三件事:

  1. cd android && ./gradlew :app:assembleDebug —— 把 bug 修复编译掉,报错发我
  2. Xcode 选模拟器 ⌘B —— iOS UI 层编译掉,报错发我
  3. (可选但强烈建议)sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

这三件完成后我开始 P1.1。