对应 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)
9.8 KiB
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. 下一步
按顺序,现在只需要做三件事:
cd android && ./gradlew :app:assembleDebug—— 把 bug 修复编译掉,报错发我- Xcode 选模拟器 ⌘B —— iOS UI 层编译掉,报错发我
- (可选但强烈建议)
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
这三件完成后我开始 P1.1。