PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.
Dart airdrop-alternativeclipboardclipboard-sharingclipboard-synccopy-pastecross-platformend-to-end-encryptionfile-syncfile-transferfluttergolanglinuxmacosnat-traversalp2pself-hostedtailscaleuniversal-clipboardwebrtcwindows
docs: design sending files to a paired device
baiyuzeeccce7b4b47b
diff --git a/design/send-files.md b/design/send-files.mdnew file mode 100644index 0000000..50c5955--- /dev/null+++ b/design/send-files.md@@ -0,0 +1,868 @@+# 隔空贴:隔空传送——把文件直接发到另一台电脑++> 方案稿 · 2026-10-21 · 待审核,尚未实现 · 已按 2.4.1(快捷粘贴、收藏已发布)的代码核对+>+> - 标「待验证」的条目,要先在第 12 节的原型里确认。+> - 标「待定」的条目需要你拍板,汇总在第 15 节,每条都附了建议。+> - 和 2.4.0 新加的快捷粘贴、收藏有交集的地方单独注明。++## 1. 概览++### 1.1 要做的事++左侧菜单栏加一个「隔空传送」页:++1. 页面中间是雷达,已配对的设备排在雷达上。+2. 点一台设备,弹出发送窗口,把文件或文件夹拖进去,松手就开始发。也可以直接把文件拖到雷达上的设备上。+3. 对方自动接收,存到它设置的保存位置(默认是「下载」文件夹),并弹出系统通知。+4. 两边的隔空传送页下方都有传输列表:收到的、发出的。收到的每一条都可以「在访达中显示」。+5. 设置页加「隔空传送」一组,可以改保存位置。++**不设大小上限。** 单个文件、文件夹、文件个数都不限,靠断点续传保证大文件能传完(第 6.4 节)。++### 1.2 和现在的「同步文件」有什么不同++现在复制文件也会同步到其他设备。隔空传送不替代它,两者各管各的:++| | 复制文件(现有) | 隔空传送(新) |+|---|---|---|+| 触发 | 在任何地方复制,自动广播给所有设备 | 主动拖给某一台设备 |+| 发给谁 | 所有在线设备 | 选中的那一台 |+| 大小 | 超过「自动同步上限」(默认 50 MB)只同步文件名,要对方手动接收 | 不限,直接发 |+| 存到哪里 | 缓存目录,过期后被清理 | 用户的保存位置,永久保留 |+| 剪贴板 | 收到后写进对方的剪贴板 | 不碰剪贴板 |+| 复制记录 | 进复制记录 | 不进,单独的传输列表 |+| 中断后 | 从头重来 | 从断点继续 |++### 1.3 你没提到、方案里补上的++下面这些是梳理时发现必须考虑的,详细内容在各节里:++1. **官方中转有额度。** 官方服务每台机器每天 100 MB、限速约 0.25 MB/s。「不限大小」在局域网和打洞直连时成立,走官方中转时要先提示、额度用完就暂停,等直连或第二天自动继续(第 10 节)。+2. **断点续传。** 现有的文件同步断了只能从头再传。隔空传送不限大小,必须能续传,否则 20 GB 传到一半断网就白传了(第 6.4 节)。+3. **对方版本太旧。** 旧版本不认识隔空传送的消息,会静默丢掉。需要设备之间交换能力标记,雷达上把旧版本设备标成「需要更新」(第 6.1 节)。+4. **传输期间不让电脑睡眠。** 两边都要阻止系统空闲睡眠,否则大文件传一会儿就断(第 9 节)。+5. **macOS 的文件夹权限。** 后台服务是单独的程序,第一次读「桌面」「文稿」、写「下载」时,系统会弹窗问一次。要配好说明文字,并且在用户看着的时候触发,不能等对方发文件时才弹(第 9.1 节)。+6. **对方磁盘空间、重名、保存位置不可用。** 发送前对方先检查空间;重名自动改名;保存位置被删了或外置盘拔了,直接回绝并说明(第 7 节)。+7. **安全。** 只有已配对的设备能发;在 Mac 上,收到的文件按隔空投送的做法打上「来自网络」的标记(待定,第 7 节)。+8. **拖不进来的东西。** 照片 App、邮件附件这类「承诺文件」首版不支持,窗口里有「选择文件…」按钮兜底(第 9 节)。+9. **不在同一个网络也能发。** 和隔空投送不同,隔空传送走的是已有的设备通道:同一局域网直连,跨网络打洞直连,都不行时中转。雷达的内圈放同一网络的设备,外圈放其他网络的(第 2.2 节)。++### 1.4 实现上++- 设备之间的通道完全复用:同一个加密的 WebRTC 连接,每次传输新开一条数据通道,沿用现有的 60 KB 分块、1 MB 背压和 zstd 压缩。+- 要新增的是:隔空传送自己的几条控制消息、一种能续传的数据流格式、落盘到用户目录、传输记录表、几个本机接口,以及界面。+- 设备之间的协议只增不改,旧版本收到新消息会忽略,所以升 MINOR。++## 2. 交互++**示意图里的符号**(全文通用):++- 设备:`(▭)` Mac 笔记本,`(▥)` Windows,`(◇)` Linux,`(◉)` 本机。实际是现有雷达里的圆形图标。+- 列表:`▤` 文件,`▣` 文件夹,`↓` 收到的,`↑` 发出的。+- `┄┄` 虚线框,`━━` 实线框(拖着文件经过时)。++### 2.1 入口++- 侧边栏顺序:**复制记录 · 收藏 · 隔空传送 · 设备 ·(官方服务)· 设置**。前两项都是复制的内容,放在一起;隔空传送排在它们后面。图标用纸飞机(Fluent `send`),和官网的纸飞机动画呼应。+- 「隔空传送」右边的标记:+ - 有收发正在进行时,显示一个小进度环(所有进行中的批次合起来的总进度),在其他页面也能看到还在传。悬停提示「正在发给 MacBook Air · 64%」,有多批时列出每一批。+ - 没有进行中的传输,但有新收到、还没看过的,显示个数,打开隔空传送页后清零。+ - 都没有时不显示。+- 名称(待定):简体「隔空传送」,繁体「隔空傳送」,英文「Send Files」,日文「ファイル送信」。++```+ ◷ 复制记录 128+ ☆ 收藏 12+ ▌✈ 隔空传送 ◔ ← 传输中:小进度环+ ▭ 设备+```++### 2.2 雷达++沿用「搜索附近设备」的雷达(`ui/lib/widgets/nearby_dialog.dart`):几圈很淡的同心圆,两道波纹从本机向外慢慢扩散。系统设置里关掉动画时雷达静止。++- **本机在中间。** 已配对的设备排在两圈椭圆上:+ - **内圈**:在同一个局域网里,能直接找到的设备。+ - **外圈**:其他网络里的设备(打洞直连或中转),以及离线的设备。+ - 设备换了网络(比如笔记本带出门),会平滑地从内圈移到外圈。+ - 每台设备占一个固定位置,别的设备上线、下线时,已有的不会挪动。+ - 最多显示 8 台。超过时,雷达下方多一行「其他设备」,以小标签列出,同样可以点、可以拖。+- **每台设备显示:** 图标、名字,名字下面一行小字是状态:++| 状态 | 小字 | 能不能点、能不能拖 |+|---|---|---|+| 同一局域网 | 局域网 | 能 |+| 跨网络直连 | 直连 | 能 |+| 中转(官方服务) | 中转 · 今日剩 62 MB | 能,发之前确认一次(第 2.5 节) |+| 中转(自己的服务器) | 中转 | 能 |+| 正在发给它 | 64% | 能,再拖进来的排在后面 |+| 刚发完 | ✓ 已送达(3 秒后恢复) | 能 |+| 离线 | 离线 | 不能,变淡(待定:显示还是隐藏) |+| 对方版本太旧 | 需要更新 | 不能,变淡;悬停提示「对方更新到 2.x 后才能接收」 |+| 对方关闭了接收 | 不接收文件 | 不能,变淡 |++- 正在发给某台设备时,它的图标外面有一圈细的蓝色进度环。+- 没有已配对的设备时,雷达位置换成空状态:「还没有配对的设备」,下面是「添加设备」「搜索附近设备」两个按钮,和设备页一样。++### 2.3 发送++**方式一:点设备,在窗口里拖。**++1. 点雷达上的一台设备,弹出「发送到 MacBook Air」窗口,标题下是连接方式(局域网 / 直连 / 中转)。+2. 窗口里是一个大的虚线框:「把文件或文件夹拖到这里」,下面有「选择文件…」「选择文件夹…」两个按钮。+3. 拖着文件经过虚线框时,框变成蓝色实线,文字换成「松手发送到 MacBook Air」。+4. 松手立即开始发送(按你的描述,不再多一步确认;待定)。+5. 窗口变成进度视图:每一批一行,显示名称、大小、进度、速度、剩余时间、取消按钮。虚线框缩小到下方,可以继续拖入,排在后面发。+6. 关掉窗口不影响发送,进度在隔空传送页的「发出的」列表里继续显示。++**方式二:直接拖到雷达上。**++- 从访达拖着文件进入隔空传送页时,所有能接收的设备图标描边变亮,提示「拖到一台设备上」。+- 移到哪台设备上,那台变成系统蓝、略微放大,松手即发送。+- 拖到雷达空白处松手:不发送,提示「拖到一台设备上发送」。++**一次拖了多个东西**(比如 3 个文件加 1 个文件夹)算一批,在列表里是一行:「合同扫描件.pdf 等 4 项」。++**统计阶段:** 拖进来的文件夹很大时,先统计文件个数和总大小,这一行显示「正在统计… 已找到 12,408 个文件」,统计完才开始发。++**同一台设备同时只传一批**,后面的排队,显示「排队中」。发给不同设备的可以同时进行。++### 2.4 进度、取消、中断++- 进度:百分比、已传 / 总量、速度、剩余时间,每 0.2 秒刷新(沿用现有的进度节流)。收发两边显示的是同一套数字。+- 一批里不止一个文件时,进度条下面多一行小字,说明正在传哪个:「正在传:IMG_2041.HEIC(第 128 / 412 个)」。文件很多、每个都很小时,这一行每 0.5 秒才换一次,不会闪得看不清。+- 取消:任何一边点「取消」,两边都停,接收方删掉没收完的部分。已经完整收到并移到保存位置的文件保留。+- 中断(断网、对方睡眠、后台服务重启):+ - 两边显示「已中断,等待重新连接」。+ - 30 分钟内重新连上,自动从断点继续,不用操作。+ - 超过 30 分钟,发送方那一行出现「继续」按钮;接收方显示「已中断 · 等对方继续」。+ - 接收方没收完的部分保留 7 天,之后清理。+- 失败的原因用一句话写清楚,比如「MacBook Air 的磁盘空间不足,还差 1.2 GB」「源文件在发送过程中被修改了」。++能看到进度的地方:++| 地方 | 发送方 | 接收方 |+|---|---|---|+| 发送窗口 | ✓ 每批一行 | — |+| 雷达上的设备 | ✓ 进度环加百分比 | — |+| 隔空传送页的列表 | ✓「发出的」 | ✓「收到的」 |+| 侧边栏「隔空传送」 | ✓ 小进度环 | ✓ 小进度环 |+| 系统通知 | — | ✓ 较大的传输开始时一条(第 2.6 节) |++### 2.5 走中转时++**官方服务中转**有每日额度和限速,发之前确认一次:++- 要发的总量在剩余额度以内:确认框说明「经官方服务中转,约 0.25 MB/s,预计 4 分钟,会用掉今天 62 MB 额度中的 58 MB」,按钮「仍然发送」「取消」。+- 超出剩余额度:说明「会在发到 62 MB 时暂停,之后连上直连或明天额度恢复时自动继续」。+- 额度已经用完:不能发,提示「今天的中转额度已用完,北京时间 0 点恢复;两台设备连上直连后不受限制」。+- 同一台设备一天只确认一次,勾选「今天不再询问」后不再弹。++**自己的服务器中转**没有额度,不弹确认,只在窗口标题下写「中转,速度取决于你的服务器带宽」。++发送过程中连接从中转换成了直连(打洞稍后成功),会短暂中断,然后自动续传,速度随之变快。++### 2.6 接收++- **默认自动接收**,不询问。能发文件的只有已配对的设备,也就是用户自己的电脑(待定:要不要加「接收前询问」,建议放二期)。+- **较大的传输开始时**弹一条系统通知,让接收方知道有东西正在传过来:+ - 条件:开始传输 3 秒后,按实测速度估算还要 30 秒以上。小文件几秒就传完,不发这条,免得打扰。+ - 标题:「MacBook Air 正在发来文件」+ - 正文:「照片 2026-10 · 2.1 GB · 预计 1 分钟」+ - 点通知本身:打开主窗口的隔空传送页,能看到进度。+ - 系统通知里不显示实时进度(各平台的通知都不适合频繁刷新),收完后由下面那条替换掉。+- **全部收完后**弹一条系统通知:+ - 标题:「收到 MacBook Air 发来的 3 个文件」+ - 正文:「合同扫描件.pdf 等 · 18.4 MB · 已存到『下载』」+ - 按钮:「在访达中显示」(Windows 是「在文件夹中显示」,Linux 是「打开文件夹」)+ - 点通知本身:打开主窗口的隔空传送页。+ - 和开始时那条用同一个通知 ID,替换而不是再多一条。+- 界面没开时照样接收:接收、通知都在后台服务里完成。+- 接收失败也通知一次,比如「MacBook Air 发来的文件没收完:磁盘空间不足」。++### 2.7 传输列表++隔空传送页下半部分,雷达下面:++- 顶部是分段控件:**收到的 · 发出的**,默认「收到的」。右边是「全部清除」(只清记录,不删文件)。+- 每一行:+ - 图标、名称(多项时「xx 等 N 项」)、总大小;+ - 第二行:来自 / 发给哪台设备 · 时间 · 状态;+ - 右侧操作:+ - 收到的、已完成:「在访达中显示」;双击这一行用默认程序打开(只有一项时);+ - 进行中:进度条和「取消」;+ - 已中断(发出的):「继续」;+ - 失败:原因 + 「重新发送」(发出的)。+- 收到的文件被用户移走或删除后,这一行显示「已移动或删除」,「在访达中显示」变灰。每次显示列表时检查一次路径是否还在。+- 右键菜单:在访达中显示、拷贝路径、从列表中移除。+- 多项的一批,鼠标停在这一行上约 0.5 秒,弹出提示框列出全部文件和文件夹。这里只是借用复制记录、收藏页的悬停提示框(2.4.0)的样式和组件,隔空传送的记录仍然只在隔空传送页里,不进复制记录。「在访达中显示」选中这一批的第一项,其余的都在同一个文件夹里。+- 列表保留 30 天或最近 500 条(待定)。++### 2.8 界面示意++**隔空传送页**(Mac,局部省略侧边栏的其他部分):++```+┌──────────────────┬───────────────────────────────────────────────────────────+│ │ 隔空传送+│ ◷ 复制记录 128 │ 把文件拖到一台设备上,直接发过去+│ ☆ 收藏 12 │+│ ▌✈ 隔空传送 ◔ │ MacBook Air+│ ▭ 设备 │ (▭)+│ ⚙ 设置 │ 局域网+│ │ · · · · · · · · · · · ·+│ │ · ·+│ │ Windows 台式机 (◉) Ubuntu 笔记本+│ │ (▥) 这台 Mac (◇)+│ │ 中转 · 今日剩 62 MB 离线+│ │ · ·+│ │ · · · · · · · · · · · ·+│ │+│ │ [收到的] 发出的 全部清除+│ │ ──────────────────────────────────────────────────────+│ │ ↓ ▤ 合同扫描件.pdf 等 3 项 · 18.4 MB+│ │ 来自 MacBook Air · 刚刚 [在访达中显示]+│ │ ↓ ▣ 照片 2026-10 · 412 个文件 · 2.1 GB+│ │ 来自 MacBook Air · 正在接收+│ │ ████████████░░░░░░ 68% · 42 MB/s · 还剩 18 秒 [取消]+│ │ 正在传:IMG_2041.HEIC(第 281 / 412 个)+│ │ ↓ ▤ PasteFerry.dmg · 812 MB+│ │ 来自 Windows 台式机 · 昨天 · 已移动或删除+├──────────────────┤+│ ● 2 台设备在线 │+└──────────────────┴───────────────────────────────────────────────────────────+```++MacBook Air 在内圈(同一局域网),Windows 台式机和 Ubuntu 笔记本在外圈。侧边栏「隔空传送」右边的 `◔` 是进度环:正在接收照片文件夹。++**拖着文件进入隔空传送页时**:++```+│ MacBook Air+│ ┏━━━━━┓+│ ┃ (▭) ┃ ← 鼠标在它上面:系统蓝描边,略微放大+│ ┗━━━━━┛+│ 松手发送+│+│ Windows 台式机 (◉) Ubuntu 笔记本+│ (▥) 这台 Mac (◇)+│ 中转 · 今日剩 62 MB 离线+│+│ 拖到一台设备上发送+```++能接收的设备(这里是 Windows 台式机)描边变亮;离线的 Ubuntu 笔记本保持变淡。++**点设备后的发送窗口**:++```+╭──────────────────────────────────────────────────────────╮+│ 发送到 MacBook Air ✕+│ 局域网+│+│ ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐+│ ┆+│ ┆ 把文件或文件夹拖到这里+│ ┆ 松手就开始发送+│ ┆+│ ┆ [选择文件…] [选择文件夹…]+│ ┆+│ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘+│+│ 文件存到 MacBook Air 设置的位置,默认是「下载」文件夹。+╰──────────────────────────────────────────────────────────╯+```++**发送中**(同一个窗口):++```+╭──────────────────────────────────────────────────────────╮+│ 发送到 MacBook Air ✕+│ 局域网+│+│ ▤ 合同扫描件.pdf 等 3 项 · 18.4 MB ✓ 已送达+│ ▣ 照片 2026-10 · 412 个文件 · 2.1 GB+│ ██████████████░░░░░░░░ 64% · 1.3 / 2.1 GB · 41 MB/s · 还剩 20 秒 [取消]+│ 正在传:IMG_2041.HEIC(第 264 / 412 个)+│ ▤ 演示视频.mov · 3.4 GB 排队中 [移除]+│+│ ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐+│ ┆ 继续拖入文件,排在后面发送 [选择文件…]+│ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘+│+│ 关闭窗口不影响发送+╰──────────────────────────────────────────────────────────╯+```++**经官方服务中转、超出剩余额度时**:++```+╭──────────────────────────────────────────────────────────╮+│ 经官方服务中转发送?+│+│ Windows 台式机现在和这台 Mac 没有直连,文件要经官方服务中转,+│ 速度约 0.25 MB/s。+│+│ 照片 2026-10 · 2.1 GB,超出今天剩余的 62 MB 中转额度。+│ 发到 62 MB 时会暂停;两台连上直连,或明天额度恢复后,自动继续。+│+│ ☐ 今天发给这台设备时不再询问+│ [取消] [仍然发送]+╰──────────────────────────────────────────────────────────╯+```++**接收方的系统通知**:较大的传输开始时一条,收完后被第二条替换。++```+┌──────────────────────────────────────────────┐+│ ▣ 隔空贴 现在+│ MacBook Air 正在发来文件+│ 照片 2026-10 · 2.1 GB · 预计 1 分钟+└──────────────────────────────────────────────┘+```++```+┌──────────────────────────────────────────────┐+│ ▣ 隔空贴 现在+│ 收到 MacBook Air 发来的 3 个文件+│ 合同扫描件.pdf 等 · 18.4 MB · 已存到「下载」+│ [在访达中显示]+└──────────────────────────────────────────────┘+```++**发送方看到对方回绝**(列表里这一行):++```+│ ↑ ▣ 照片 2026-10 · 2.1 GB+│ 发给 MacBook Air · 没有发出:对方的磁盘空间不足,还差 1.2 GB [重新发送]+```++## 3. 设置++设置页加一组「隔空传送」,放在「同步」组后面:++```+隔空传送+╭────────────────────────────────────────────────────────────────────╮+│ 接收其他设备发来的文件 [● 开]+│ 保存到 ~/Downloads [更改…] [在访达中显示]+│ 收到文件时通知 [● 开]+╰────────────────────────────────────────────────────────────────────╯+只有已配对的设备能给这台 Mac 发文件。传输期间这台 Mac 不会自动睡眠。+```++- **接收其他设备发来的文件**:关掉后,对方的雷达上这台设备显示「不接收文件」,发来的请求直接回绝。默认开。+- **保存到**:+ - 默认是系统的「下载」文件夹。Linux 按 XDG 设置取(可能叫「下载」),Windows 用系统 API 取(「下载」被 OneDrive 重定向时也对)。+ - 「更改…」打开系统的选择文件夹窗口。选完立即检查能不能写入,不能写入时不保存,并说明原因。+ - 外置盘上的文件夹也可以选;盘拔掉后,收到请求时回绝,并通知本机用户去设置里改。+ - 已经收完的文件不会因为改了位置而挪动。+- **收到文件时通知**:默认开。系统通知权限没给时,这一行下面提示「系统通知已关闭」,和现有的通知设置一致。++## 4. 和现有功能的关系++- **复制记录**:隔空传送的文件不进复制记录,复制记录里也没有隔空传送的东西。+- **剪贴板**:收到的文件不写进剪贴板,不影响对方正在用的剪贴板。+- **「同步文件」开关、自动同步上限**:只管复制同步,和隔空传送无关。关掉「同步文件」也能隔空传送。+- **清理(GC)**:收到的文件在用户目录里,GC 不碰;只清理过期的传输记录和超过 7 天没续上的半成品。+- **复制同步和隔空传送同时进行**:走同一个连接的不同数据通道,复制的文字仍走控制通道,不排在大文件后面(待验证:大文件传输期间复制文字的延迟)。+- **快捷粘贴、收藏(2.4.0)**:+ - 隔空传送的文件不进复制记录,所以快捷粘贴窗口里也没有,也不能收藏。+ - `daemon.proto` 的字段编号接在它们后面(第 8.2 节)。+ - 快捷粘贴窗口是另一个进程,和主窗口共用 Dart 代码。隔空传送用到拖放、文件选择插件的代码只放在主窗口的页面里,快捷窗口不引用(第 9.4 节)。+- **设备页**:不改。按「新功能做成单独入口,原有流程不动」的原则,设备页只多显示一个「需要更新才能接收文件」的提示(如果对方版本太旧)。++## 5. 复用什么、补什么++### 5.1 直接复用++| 现有部分 | 位置 | 隔空传送里怎么用 |+|---|---|---|+| 加密的设备连接(WebRTC + DTLS,配对时的公钥认证) | `transport/p2p` | 原样使用,不新建连接 |+| 每次传输新开一条数据通道 | `p2p.Peer.OpenStream` | 隔空传送的数据流也这样开,通道名带 `send:` 前缀以便区分 |+| 60 KB 分块、1 MB 高水位背压 | `sync/chunkwriter.go` | 原样使用 |+| zstd 流式压缩 | `pack` | 原样使用(待验证:局域网下是否成为瓶颈) |+| 防目录穿越、Windows 非法文件名替换、Windows 上跳过 `.DS_Store`、`Thumbs.db` 这类系统文件 | `pack/pack.go`、`pack/names.go` | 落盘时复用同样的规则 |+| 直连 / 中转的判断 | `LinkInfo`、`Device.connection` | 雷达的状态、发送前的确认 |+| 官方服务的额度查询 | `Status.official_usage` | 发送前的确认、额度用完时暂停 |+| 后台服务里的系统通知(带按钮) | `internal/notifications` | 开始和收完的通知,沿用现有大文件接收「开始一条、完成时按同一 ID 替换」的做法。现在的通知都挂在复制记录上,要加一种挂在传输记录上的;按钮加一个 `reveal` 动作(在访达中显示);点通知本身的 `open` 现在只打开主窗口,要能带上「切到隔空传送页」 |+| 在访达 / 资源管理器里显示文件 | `ui/lib/platform.dart` 的 `revealFile` | 列表里的按钮 |+| 雷达绘制 | `ui/lib/widgets/nearby_dialog.dart` 的 `_RadarPainter`、设备节点 | 抽成公共组件,两处共用 |+| 「下载」文件夹的位置(Linux XDG) | `ui/lib/platform.dart` 的 `downloadsDir` | 逻辑移到后台服务(Go),界面不再自己算 |++### 5.2 需要新做的++| 新增 | 原因 |+|---|---|+| 设备之间的能力标记 | 旧版本会静默丢掉隔空传送消息,发送方必须提前知道 |+| 隔空传送的控制消息:发起、应答、取消、结果 | 现有的 `ClipOffer` 会广播给所有设备并进复制记录,语义不同 |+| 能续传的数据流格式 | 现有格式是整个 tar 包,断了只能重来 |+| 落盘到用户目录:临时目录、重名改名、空间检查 | 现有的只写缓存目录 |+| 传输记录表 | 列表、续传、重启后恢复都要用 |+| 传输期间阻止睡眠 | 现在没有 |+| macOS 后台服务的文件夹权限说明文字 | 现在的 Info.plist 只有本地网络的说明 |+| 拖放与文件选择窗口的依赖 | 界面现在没有拖放能力,也没有文件夹选择器(第 9.4 节) |+| 本机接口:发送、取消、继续、列表、清除 | 第 8.2 节 |++## 6. 协议++### 6.1 能力协商++连接就绪后,两边各发一次 `PeerFeatures`,和现有的 `LinkInfo` 同时发:++```proto+message PeerFeatures {+ // 本端支持的功能。"send_files_v1":能接收隔空传送。+ // 关闭了「接收其他设备发来的文件」时不带这一项,再带上 "send_files_off",+ // 对方的雷达据此显示「不接收文件」而不是「需要更新」+ repeated string features = 1;+}+```++- 没收到 `PeerFeatures` 的对端(旧版本)一律当作不支持。+- 改了「接收」开关后立即再发一次。+- 以后其他新功能也用这一条,不必每次加消息。++### 6.2 一次传输的过程++```+发送方 接收方+ │ SendOffer(批次 ID、顶层项目、总大小、文件数) │+ │ ─────────────────────────────────────────▶ │ 检查:接收开关、保存位置可写、+ │ │ 磁盘空间、单文件上限+ │ SendAnswer(接受 + 从哪里开始 / 回绝 + 原因) │+ │ ◀───────────────────────────────────────── │+ │ 新开数据通道 send:<批次 ID>:<第几次> │+ │ ═════════════ 数据流(第 6.3 节)════════════▶ │ 写进临时目录,边收边算哈希+ │ │ 全部校验通过 → 移到保存位置+ │ SendResult(成功 / 在第几个文件失败) │+ │ ◀───────────────────────────────────────── │+```++控制消息(`wire.proto` 的 `PeerMessage`,现有 1–7 不变):++```proto+message PeerMessage {+ oneof payload {+ // ...已有的 1–7...+ PeerFeatures features = 8;+ SendOffer send_offer = 9;+ SendAnswer send_answer = 10;+ SendCancel send_cancel = 11;+ SendResult send_result = 12;+ }+}++message SendOffer {+ string transfer_id = 1; // 发送方生成,续传时不变+ repeated ClipItem items = 2; // 顶层的文件和文件夹,显示用;文件夹的 size 是总大小+ int64 total_bytes = 3;+ int64 file_count = 4;+ int64 largest_file = 5; // 接收方据此判断 FAT32 这类单文件 4 GB 的上限+ int64 created_at_unix = 6;+ bool resume = 7; // 续传:同一个 transfer_id 再次发起+}++message SendAnswer {+ string transfer_id = 1;+ bool accepted = 2;+ // disabled / no_space / dest_unavailable / file_too_large / busy / unknown_transfer+ string reason = 3;+ int64 shortfall_bytes = 4; // no_space 时还差多少+ int64 resume_index = 5; // 从第几个文件开始(全新传输为 0)+ int64 resume_offset = 6; // 这个文件已经收到多少字节+}++message SendCancel {+ string transfer_id = 1;+ string reason = 2; // cancelled / source_changed / source_missing / read_error+}++message SendResult {+ string transfer_id = 1;+ bool ok = 2;+ string error = 3; // hash_mismatch / write_failed / dest_unavailable+ int64 failed_index = 4;+}+```++- 回绝的原因都是固定的代码,界面按代码显示本地化文案,不显示对方传来的原文。+- 接收方同一时间只接收来自同一台设备的一批,另一批到来时回 `busy`,发送方排队等。+- `ClipItem` 复用现有定义(名称、大小、是否文件夹)。++### 6.3 数据流格式++数据通道里是一个 zstd 流,解压后是一串「帧」:++```+FileStart{index, rel_path, size, mode, mtime, offset} ← 4 字节长度 + protobuf+<size - offset 个字节的文件内容>+FileEnd{sha256} ← 整个文件的 SHA-256+FileStart{index+1, ...}+...+StreamEnd{}+```++- 接收方从帧里就知道每个文件放在哪、多大,不需要单独传清单。文件个数再多,控制消息也只有一条 `SendOffer`,不会超过单条消息的大小限制。+- 空文件夹也是一帧(`size` 为 0,标记为目录),保证文件夹结构完整。+- `mode` 保留可执行位;`mtime` 保留修改时间。扩展属性、Finder 标签、资源分支不传(和现有的复制同步一致)。+- 符号链接:用户直接拖进来的是链接时,发送它指向的文件;文件夹里面的链接保持为链接(和现有规则一致),Windows 上不能建链接时跳过,并在结果里列出。+- **发送方在发起时把文件清单按顺序存进本地数据库**,续传时按存下的清单发,不重新遍历,顺序不会变。+- 每个文件发之前重新检查大小和修改时间,和清单里不一致就停止,回 `SendCancel{source_changed}`。++### 6.4 断点续传++- 接收方把每个文件收到了多少字节记在数据库里(每收 8 MB 或每 2 秒记一次),没收完的文件就在临时目录里。+- 续传时发送方再发一次 `SendOffer{resume: true}`,接收方在 `SendAnswer` 里回「从第几个文件、第几个字节开始」。+ - 为保险,接收方回的位置退回到最近一次记录的位置,并把那个文件截断到这里。+- 两边都要算整个文件的哈希:续传的那个文件,双方各自把已有的部分从磁盘再读一遍算进哈希,然后接着算。+- 触发续传:+ - 连接恢复(现有的 `PeerReady`)时,发送方自动续传 30 分钟内中断的批次;+ - 后台服务重启后同样处理;+ - 超过 30 分钟,等用户在发送方点「继续」。+- 接收方没收完的批次保留 7 天,之后删掉临时文件,记录标为「已过期」。发送方这时再点「继续」,对方回 `unknown_transfer`,从头再发。++### 6.5 校验++- 传输路上的完整性由 DTLS 保证;文件级的 SHA-256 防的是磁盘写入出错和续传拼接出错。+- 某个文件哈希不对:删掉这个文件,从这个文件的开头重传一次;第二次还不对就失败,`SendResult{hash_mismatch}`。++### 6.6 兼容++- 旧版本:不发 `PeerFeatures`,雷达上显示「需要更新」,不会给它发任何隔空传送消息。+- 万一发了:旧版本按现有逻辑忽略不认识的消息;数据通道因为没有对应的传输头,10 秒后被它关掉。不会崩溃。+- 现有的复制同步协议一字不改。++## 7. 接收端落盘++- **临时目录**:`<保存位置>/.pasteferry-partial/<批次 ID>/`。和保存位置在同一块盘上,收完用重命名移过去,大文件也是瞬间完成,不会多占一份空间。Windows 上给这个目录设隐藏属性。+- **移到保存位置**:一批里的顶层项目各自移过去。+ - 重名时改名:`报告.pdf` → `报告 (2).pdf`,`照片` → `照片 (2)`。和访达、资源管理器的习惯一致。+ - 文件名在本机不合法时(比如 Mac 的文件名里有 `:` 发到 Windows),沿用 `pack/names.go` 的替换规则。+- **空间检查**:接受之前看保存位置所在磁盘的剩余空间,要大于「总大小 + 200 MB」,否则回绝 `no_space` 并带上差额。续传时只算剩下的部分。+- **单文件上限**:保存位置是 FAT32 时,大于 4 GB 的文件放不下,回绝 `file_too_large`。+- **传输中保存位置没了**(外置盘拔了):停止,回 `SendResult{dest_unavailable}`,本机通知用户。+- **Windows 路径过长**:超过 260 个字符的路径用 `\\?\` 前缀写入。+- **「来自网络」标记**(待定,建议只在 macOS 上打):+ - macOS:给收到的文件加 `com.apple.quarantine`,和隔空投送一样。普通文档打开时没有任何变化,只有打开收到的程序或脚本时,系统会先确认一次。+ - Windows:不写 `Zone.Identifier`。写了的话,Word、Excel 会以「受保护的视图」只读打开每一份收到的文档,要点「启用编辑」才能改。发文档是隔空传送最常见的用途,这个代价太大;发过来的又是用户自己的设备。++## 8. 后台服务与接口++### 8.1 存储++新增两张表,和 `clips` 无关:++```sql+CREATE TABLE IF NOT EXISTS transfers (+ id TEXT PRIMARY KEY,+ direction INTEGER NOT NULL, -- 1 发出,2 收到+ device_id TEXT NOT NULL,+ device_name TEXT NOT NULL DEFAULT '',+ status INTEGER NOT NULL, -- 见下+ total_bytes INTEGER NOT NULL,+ done_bytes INTEGER NOT NULL DEFAULT 0,+ file_count INTEGER NOT NULL,+ dest_dir TEXT NOT NULL DEFAULT '', -- 收到的:当时的保存位置+ error TEXT NOT NULL DEFAULT '',+ seen INTEGER NOT NULL DEFAULT 0,-- 收到的:用户看过没有,用于侧边栏的数字+ relayed INTEGER NOT NULL DEFAULT 0,+ created_at INTEGER NOT NULL,+ updated_at INTEGER NOT NULL,+ finished_at INTEGER NOT NULL DEFAULT 0+);++CREATE TABLE IF NOT EXISTS transfer_files (+ transfer_id TEXT NOT NULL REFERENCES transfers(id) ON DELETE CASCADE,+ idx INTEGER NOT NULL,+ rel_path TEXT NOT NULL,+ size INTEGER NOT NULL,+ is_dir INTEGER NOT NULL DEFAULT 0,+ mode INTEGER NOT NULL DEFAULT 0,+ mtime INTEGER NOT NULL DEFAULT 0,+ source_path TEXT NOT NULL DEFAULT '', -- 发出的:本机原路径+ done_bytes INTEGER NOT NULL DEFAULT 0,-- 收到的:续传位置+ top INTEGER NOT NULL DEFAULT 0,-- 顶层项目+ final_path TEXT NOT NULL DEFAULT '', -- 收到的顶层项目:改名后的最终位置+ PRIMARY KEY (transfer_id, idx)+);+```++- 状态:排队、等待对方、统计中、传输中、已暂停(中转额度)、已中断、已完成、失败、已取消、被回绝、已过期。+- 十万个文件的文件夹,`transfer_files` 就有十万行。完成后只保留顶层项目那几行,其余删掉。+- 发出的批次不复制源文件,只记路径,不占额外空间。++### 8.2 接口(`daemon.proto`)++快捷粘贴(2.4.0)已经占用了 `Config` 的 20–22 和 `Event` 的 9–10,下面接着编号。`Device` 与 `wire.proto` 这次没有变化,编号照旧。++```proto+service DaemonService {+ // ...已有的...+ // 发给一台设备。立即返回这一批的记录,进度走事件流。+ // 走官方中转而 allow_relay 为 false 时返回 FAILED_PRECONDITION(relay),界面确认后再调一次+ rpc SendFiles(SendFilesRequest) returns (Transfer);+ rpc CancelTransfer(TransferRef) returns (Empty);+ // 发出的、已中断的批次从断点继续;对方已清掉半成品时从头再发+ rpc ResumeTransfer(TransferRef) returns (Empty);+ rpc ListTransfers(ListTransfersRequest) returns (ListTransfersResponse);+ // 只删记录,不删文件;进行中的不能删+ rpc DeleteTransfers(DeleteTransfersRequest) returns (Empty);+ // 打开隔空传送页时调用,侧边栏的数字清零+ rpc MarkTransfersSeen(Empty) returns (Empty);+ // 设置页选完保存位置后调用:检查能否写入,在 macOS 上顺带触发系统的文件夹授权+ rpc CheckReceiveDir(CheckReceiveDirRequest) returns (CheckReceiveDirResponse);+}++message SendFilesRequest {+ string device_id = 1;+ repeated string paths = 2;+ bool allow_relay = 3;+}++message TransferRef { string id = 1; }++enum TransferDirection {+ TRANSFER_DIRECTION_UNSPECIFIED = 0;+ TRANSFER_DIRECTION_OUTGOING = 1;+ TRANSFER_DIRECTION_INCOMING = 2;+}++message Transfer {+ string id = 1;+ TransferDirection direction = 2;+ string device_id = 3;+ string device_name = 4;+ string status = 5; // queued / waiting / scanning / active / paused / interrupted / done / failed / cancelled / declined / expired+ repeated ClipItem items = 6; // 顶层项目+ repeated string paths = 7; // 收到的:顶层项目的最终路径;发出的:源路径+ int64 total_bytes = 8;+ int64 done_bytes = 9;+ int64 file_count = 10;+ double bytes_per_second = 11;+ string error = 12; // 固定代码,界面翻译+ int64 shortfall_bytes = 13;+ bool relayed = 14;+ bool seen = 15;+ int64 created_at_unix = 16;+ int64 finished_at_unix = 17;+ int64 scanned_files = 18; // 统计阶段已找到的文件数+ string current_file = 19; // 正在传的文件,一批里的相对路径;最多每 0.5 秒换一次+ int64 current_index = 20; // 它是第几个文件,从 1 开始+}++message ListTransfersRequest {+ TransferDirection direction = 1;+ int32 limit = 2;+ int64 before_unix = 3;+}+message ListTransfersResponse { repeated Transfer transfers = 1; }++message DeleteTransfersRequest {+ repeated string ids = 1;+ bool all = 2;+ TransferDirection direction = 3; // all 时只清这一类+}++message CheckReceiveDirRequest { string path = 1; }+message CheckReceiveDirResponse {+ bool ok = 1;+ string error = 2; // not_found / not_writable / permission_denied+ int64 free_bytes = 3;+}++message Device {+ // ...已有的 1–8...+ bool receives_files = 9; // 对方声明了 send_files_v1+ bool receive_disabled = 10; // 对方关闭了接收+ bool lan_reachable = 11; // 在同一局域网里能直接找到,雷达据此放内圈+}++message Config {+ // ...已有的 1–19,快捷粘贴的 20–22...+ string receive_dir = 23; // 空表示系统的「下载」文件夹+ bool receive_disabled = 24; // 写成反向的:旧配置没有这一项时就是开启+ bool receive_notify_disabled = 25;+}++message Event {+ oneof payload {+ // ...已有的 1–8,快捷粘贴的 9–10...+ Transfer transfer_changed = 11; // 新建、状态变化、进度(0.2 秒节流)+ string transfer_removed = 12;+ }+}+```++- `paths` 由界面从拖放或文件选择窗口拿到后原样交给后台服务,由后台服务读文件。+- 后台服务的配置文件(`config.json`)对应加 `receive_dir`、`receive_disabled`、`receive_notify_disabled`。++### 8.3 代码放在哪++- 新包 `client-core/internal/send`:发起、应答、数据流、续传、落盘。不塞进现有的 `sync` 包,那里只管剪贴板同步。+- 数据流的帧格式放在 `pack` 包里(`pack/frames.go`),和现有的 tar 格式并列。+- `p2p.Peer` 收到 `send:` 开头的数据通道交给 `send` 包,其余照旧交给 `sync`。+- `PeerFeatures` 和 `LinkInfo` 一样在连接层处理,结果挂在 `Device` 上。+- 防睡眠放在新包 `client-core/internal/power`,按平台实现。++## 9. 各平台注意事项++### 9.1 macOS++- **文件夹权限**(待验证):后台服务是单独的 `PasteFerryDaemon.app`。它第一次读「桌面」「文稿」「下载」、iCloud 云盘、外置盘、网络盘里的文件时,系统会弹窗问一次。+ - 在 `scripts/build.sh` 给后台服务的 Info.plist 加说明文字,五种语言:`NSDesktopFolderUsageDescription`、`NSDocumentsFolderUsageDescription`、`NSDownloadsFolderUsageDescription`、`NSRemovableVolumesUsageDescription`、`NSNetworkVolumesUsageDescription`。`localize` 函数要改成能写多条。+ - **写入保存位置的授权要在用户看着的时候触发**:第一次打开隔空传送页、以及在设置里选完保存位置时,界面调 `CheckReceiveDir`,后台服务试写一次,系统在这时弹窗。否则会等到别人发文件过来时才弹,接收方可能根本不在电脑前,传输就卡住了。+ - 读取的授权在拖文件进来的那一刻触发,用户正看着,没问题。+ - 用户点了「不允许」:接收时回绝 `dest_unavailable`;本机界面提示去「系统设置 → 隐私与安全性 → 文件与文件夹」打开,按钮直接打开那个面板。+ - 2.4.0 起,Mac 版用固定的「PasteFerry Code Signing」证书签名(`scripts/sign.sh`),系统按「包名 + 证书」记录授权,按这个机制,更新后授权应当保留(见 `design/quick-paste-and-favorites.md` 第 7.1 节)。文件夹授权用的是同一套记录方式,原型阶段用两个连续的版本实测一次(第 12 节)。之前担心的「要等零期」已经不成立。+- **防睡眠**:传输期间用 `IOPMAssertionCreateWithName(kIOPMAssertionTypePreventUserIdleSystemSleep)`,结束就释放。合上盖子照样会睡,这是系统行为。+- **拖不进来的**:照片 App、邮件附件拖出来的是「承诺文件」(由源程序稍后写出),首版不支持。拖进来时提示「请先把它存成文件,或用『选择文件…』」。+- **iCloud 云盘里「仅在云端」的文件**:读取时系统会先下载,统计阶段可能变慢,进度照常。++### 9.2 Windows++- 后台服务以当前用户身份运行,读写用户目录没有额外授权。+- 「下载」文件夹用 `SHGetKnownFolderPath(FOLDERID_Downloads)` 取,OneDrive 重定向时也对。界面现在的 `downloadsDir()` 写死了 `%USERPROFILE%\Downloads`,一并改成从后台服务取。+- 防睡眠:`SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED)`。+- 从 Outlook 拖出的附件是虚拟文件,首版不支持,提示同上。+- 托盘菜单(由后台服务绘制)首版不加隔空传送入口。++### 9.3 Linux++- 「下载」文件夹按 `user-dirs.dirs` 取,逻辑从界面移到后台服务。+- 防睡眠:经 D-Bus 调 `org.freedesktop.login1.Manager.Inhibit("sleep:idle", ...)`,没有 logind 时跳过。+- 通知的按钮:现有通知在 Linux 上支持按钮时显示「打开文件夹」,不支持时点通知本身打开隔空传送页。+- 「在文件夹中显示」:沿用 `revealFile`,打开所在的文件夹(各家文件管理器不统一,没法选中文件)。+- Wayland 下从文件管理器拖进 Flutter 窗口(待验证)。++### 9.4 界面依赖++界面现在没有拖放能力,也没有文件 / 文件夹选择窗口,要新加两个依赖。这会是应用的**第一批原生插件**(`GeneratedPluginRegistrant` 现在是空的),所以要多注意几件事:++- `desktop_drop`:接收从访达、资源管理器、文件管理器拖进来的文件,三个平台都支持,纯插件,不需要额外的工具链。不选 `super_drag_and_drop`:它要 Rust 工具链,构建变复杂,而我们只需要「接收文件路径」这一种能力。+- `file_selector`(Flutter 官方维护):「选择文件…」「选择文件夹…」和设置里的「更改…」。+- 打包:+ - Windows(`build-windows.ps1`)与 Linux(`package-linux.sh`)都是整个复制 Flutter 的构建目录,插件的 DLL / .so 会自动带上。+ - Mac 由 Xcode 把插件嵌进 `Contents/Frameworks`,再由 `sign.sh` 签名。`check_signed` 现在只核对 App 和三个组件,要确认插件的签名也是这张证书。+ - 自动更新替换的是整个 App / 文件夹,不用改。+- 快捷粘贴窗口:Mac 上的 `PasteFerryPicker` 没有注册插件,Dart 代码里调用插件会抛 `MissingPluginException`。所以用到插件的代码只放在隔空传送页和设置页,快捷窗口的代码不引用它们。+- 替代办法:不用插件,三个平台各写一点原生代码(Mac 的拖放与 `NSOpenPanel`,Windows 的 `IDropTarget` 与 `IFileOpenDialog`,Linux 的 GTK 拖放与 `GtkFileChooserNative`),走自己的 MethodChannel。工作量大约是三个平台各一两百行,好处是不引入外部依赖。建议先用插件,原型里有问题再换。++## 10. 中转与额度++| 连接方式 | 额度 | 速度 | 隔空传送的处理 |+|---|---|---|---|+| 同一局域网 | 无 | 取决于网络(待验证实测) | 直接发 |+| 跨网络打洞直连 | 无 | 取决于两边的上传带宽 | 直接发 |+| 官方服务中转 | 每台机器每天 100 MB(上传加下载),北京时间 0 点恢复 | 约 0.25 MB/s,同组设备共享 | 发前确认;额度用完暂停,等直连或额度恢复后自动续传 |+| 自己的服务器中转 | 无 | 取决于服务器带宽,实测过约 0.6 MB/s | 直接发,窗口里注明是中转 |++- 额度按中转的加密字节算,比文件本身大约 6%,预计用量按文件大小乘 1.06 估算。+- 官方中转只在直连失败 8 秒后才建立。之后打洞成功会换回直连,换的时候数据通道会断一下,隔空传送自动续传。+- 额度用完时,网关会停止转发,连接断开,批次标为「已暂停:今天的中转额度已用完」。后台服务本来就在定期查询额度(没有中转时每 60 秒,有中转时每 15 秒),查到额度恢复(过了 `reset_at`)或换成了直连时自动继续。++## 11. 安全与隐私++- 只有已配对的设备能发:隔空传送的消息走已认证的设备通道,未配对的设备连不上这个通道。+- 文件内容和文件名只在两台设备之间加密传输,不经过服务器;中转时服务器只看到加密后的数据包。+- 接收方不执行、不打开任何收到的文件,只在用户点击时打开。+- 回绝原因、错误都是固定代码,界面翻译后显示,不显示对方传来的原文。+- 帧里的 `rel_path` 按现有的防穿越规则检查,含 `..`、绝对路径的直接失败。+- 诊断报告里的文件名已经会被替换成占位符(`internal/diag`),隔空传送的日志沿用。+- 官网的隐私说明加一句:隔空传送的文件只在你的设备之间传输。+- 「来自网络」标记见第 7 节(待定)。++## 12. 原型阶段要先验证的++| # | 验证什么 | 为什么 | 不行的话 |+|---|---|---|---|+| 1 | 局域网实测吞吐:千兆有线、Wi-Fi 6,Mac ↔ Windows ↔ Linux | pion 的 SCTP 吞吐一直偏低,现在没有实测数据 | 先调 SCTP 接收缓冲;仍不够就一批开几条数据通道并行;最后才考虑局域网里另开 TCP 连接 |+| 2 | zstd 在已压缩文件(视频、zip、dmg)上会不会拖慢局域网传输 | 压缩吃 CPU,对这类文件没用 | 按扩展名或前 1 MB 的压缩率跳过压缩 |+| 3 | 大文件传输期间,复制文字同步的延迟 | 两者共用一个连接 | 给隔空传送的数据通道降低优先级,或压低它的高水位 |+| 4 | macOS 文件夹授权:何时弹、授权记在谁名下、用固定证书签名后更新会不会丢 | 第 9.1 节 | 弹的时机不对就调整 `CheckReceiveDir` 的调用时机 |+| 5 | `desktop_drop` 在三个平台、Wayland 和 X11 下能否拿到路径;加了插件后 Mac 的签名核对、快捷粘贴窗口是否照常 | 应用还没有用过原生插件 | 换成自己写的原生代码(第 9.4 节),或在该平台只保留「选择文件…」 |+| 6 | 十万个小文件的文件夹(如 `node_modules`):统计用时、传输速度、数据库写入 | 每个文件都有固定开销 | 合并记录写入;`transfer_files` 改成批量插入 |+| 7 | 中转换直连时的续传 | 第 10 节 | — |++### 12.1 原型结果(2026-10-21)++**数据通道吞吐**(`client-core/internal/transport/p2p/throughput_test.go`,默认跳过,`PF_THROUGHPUT=1` 才跑):两台设备的连接在同一台电脑(i9-12900HK,macOS)的本机回环上互发 512 MB,分块与背压和生产代码相同。++| 条件 | 结果 |+|---|---|+| 生产参数(60 KB 分块、1 MB 高水位) | 25–45 MB/s,多次运行在两档之间跳 |+| 高水位 4 MB、16 MB | 同上,没有提升 |+| 4 条数据通道并行 | 同上,没有提升 |+| SCTP 接收缓冲 4 MB、16 MB | 同上,没有提升 |++- CPU 剖析:时间几乎都花在逐包的 UDP 系统调用与 Go 调度上(`syscall.rawsyscalln` 约 38%),DTLS 加密几乎不占时间。pion 的 SCTP 包大小固定为 1191 字节,没有对外的设置,512 MB 要发四十多万个包。+- 回环上两端挤在同一台电脑,真实局域网里两边各自只做一半,预计会好一些,要在实机上再量。+- **结论**:首版沿用现有通道,局域网里预计 25–45 MB/s(约 200–370 Mbps),1 GB 约半分钟。Wi-Fi 下基本已到网络本身的速度;千兆有线网只用到约三分之一。+- 以后如果要跑满千兆有线网,办法是在局域网里另开一条用配对密钥认证的 TCP 连接专门传隔空传送的数据。要新开端口、Windows 防火墙要放行,工作量不小,不放进一期。++**真实后台服务实测**(2026-10-22,同一台 Mac 上两个隔离的后台服务,局域网直连):2 GB 单个文件 44 MB/s;2 万个小文件的文件夹约每秒 1900 个文件;杀掉任一方再重启都能从断点续传。和上面回环的上限一致。++**zstd**:对不可压缩的随机数据,`SpeedFastest` 约 1.8 GB/s,比传输快几十倍,不是瓶颈。保留压缩,不按格式跳过。++## 13. 分阶段++**一期**(一个 MINOR 版本,即 2.5.0):++- 隔空传送页:雷达(内外圈、各种状态)、传输列表、侧边栏入口和数字。+- 发送:点设备弹窗拖入、直接拖到设备上、选择文件 / 文件夹、排队、取消。+- 接收:自动接收、保存位置、空间检查、重名改名、系统通知。+- 断点续传(自动和手动)、防睡眠、能力协商、中转确认与额度暂停。+- 设置页「隔空传送」一组。+- macOS 文件夹授权的说明文字与引导。+- 官网:功能页(`tools/site/content/features.py`)加一节隔空传送,首页按需加一句;隐私说明、`llms.txt` 同步更新;截图用 `tools/screenshots/render.sh` 的演示数据重新生成。++**二期**(看一期的反馈再定):++- 接收前询问(设置里的开关,通知上带「接收」「拒绝」)。+- 在访达 / 资源管理器里右键「用隔空贴发送」:Windows 的「发送到」菜单,macOS 的服务菜单或共享菜单。+- 一次发给多台设备。+- 复制记录里的文件行,右键「隔空传送给…」。+- 托盘菜单入口。+- 程序坞图标(Mac)和任务栏按钮(Windows)上的进度条。两个平台各要写原生代码,而且只在窗口开着时有效,一期先不做。+- 手机客户端(见 `design/mobile-clients.md`),协议本身没有桌面专属的假设。++## 14. 测试++**自动测试**:++- `pack`:帧的编解码;续传时从任意位置开始;哈希;含 `..` 和绝对路径的条目被拒;Windows 非法文件名;空文件夹;符号链接。+- `send`:两个进程内的后台服务经 pion 本机回环互发:正常完成、取消(两边各自)、中途断开后续传、源文件被改、磁盘空间不足、保存位置不可写、重名改名、回绝(关闭接收)、旧版本(不发 `PeerFeatures`)。+- `store`:新表的建表与旧库升级;完成后只保留顶层项目。+- 界面:隔空传送页的组件测试(雷达各状态、列表各状态、拖放高亮、侧边栏的进度环与数字),用注入的演示状态。+- 通知:小文件不发「正在发来」;大文件发一条,收完后被替换,不会留下两条。++**实机**(沿用以往的做法,用隔离的后台服务实例,不动和真实 Mac 的配对):++| 场景 | Mac ↔ Windows 虚拟机 | Mac ↔ Linux 虚拟机 | Windows ↔ Linux |+|---|---|---|---|+| 局域网,单个 20 GB 文件 | ✓ | ✓ | ✓ |+| 局域网,十万个小文件的文件夹 | ✓ | ✓ | |+| 传输中拔网线 / 关 Wi-Fi,恢复后自动续传 | ✓ | ✓ | |+| 传输中杀掉后台服务、重启电脑 | ✓ | ✓ | |+| 官方中转:额度内、超出额度暂停、恢复后继续 | ✓(用 `envcheck` 的强制中转办法) | ✓ | |+| 接收方保存位置在外置盘,传输中拔掉 | ✓ | | |+| macOS 新用户首次接收:授权弹窗的时机与文案 | ✓ | | |+| 传输期间不睡眠,结束后正常睡眠 | ✓ | ✓ | |+| 中文、日文、带空格和 emoji 的文件名 | ✓ | ✓ | ✓ |++## 15. 待你拍板的事项++| # | 问题 | 建议 |+|---|---|---|+| 1 | 名称:隔空传送 / 隔空傳送 / Send Files / ファイル送信 | 照此。英文用直白的说法,避免和 AirDrop 混淆 |+| 2 | 侧边栏位置 | 收藏之后、设备之前,第三个 |+| 3 | 离线的设备在雷达上显示还是隐藏 | 显示,变淡、不能点。用户能看出来「它不在线」,而不是「它去哪了」 |+| 4 | 拖进窗口后立即发送,还是先列出来再点「发送」 | 立即发送(你的描述),排队中的可以「移除」 |+| 5 | 默认保存位置:「下载」文件夹本身,还是「下载/隔空贴」子文件夹 | 「下载」本身,和隔空投送一样 |+| 6 | 默认自动接收、不询问 | 是;「接收前询问」放二期 |+| 7 | 官方中转时允许发送,但先确认、额度用完就暂停 | 是 |+| 8 | 收到的文件打「来自网络」标记 | 只在 macOS 上打(和隔空投送一致,文档不受影响);Windows 不打,否则 Office 文档都会以受保护的视图只读打开 |+| 9 | 收到的文件不进复制记录、不写剪贴板 | 是 |+| 10 | 传输列表保留多久 | 30 天或最近 500 条,先到为准 |+| 11 | 发布顺序 | 单独发 2.5.0。快捷粘贴和固定证书签名都已在 2.4.0 发布,不再有前置条件 |diff --git a/task.md b/task.mdnew file mode 100644index 0000000..5ee5f45--- /dev/null+++ b/task.md@@ -0,0 +1,86 @@+# 隔空传送开发任务(2.5.0)++> 方案:[design/send-files.md](design/send-files.md)+> 基线:main `ed09502`(2.4.1)。版本号从 2.5.0 起。+> 2026-10-22:按用户要求改名为「隔空传送」(繁体「隔空傳送」,英文 Send Files,日文 ファイル送信)。+> 第 15 节的待定事项按文档里的建议执行:拖进来立即发送、默认自动接收、存到「下载」本身、+> 离线设备变淡显示、只在 Mac 上打隔离标记、官方中转先确认、列表保留 30 天或 500 条。++状态:`[ ]` 未开始 · `[~]` 进行中 · `[x]` 完成++## 0. 准备与原型++- [x] 拉取最新 main+- [x] 测速原型:本机回环 25–45 MB/s,瓶颈是 pion 逐包的系统调用;调水位、多通道、接收缓冲都没用。首版沿用现有通道(结果见方案第 12.1 节)+- [x] zstd:不可压缩数据约 1.8 GB/s,不是瓶颈,保留压缩+- [x] 确认 `desktop_drop` 0.8.4、`file_selector` 1.1.0 能装上;Mac 版带插件编译通过(以 Swift Package 静态链接,App 包里不多框架)++## 1. 协议与接口++- [x] `wire.proto`:`PeerFeatures`、`SendOffer`、`SendAnswer`、`SendCancel`、`SendResult`(`PeerMessage` 8–12)+- [x] `daemon.proto`:+ - [x] RPC:`SendFiles`、`CancelTransfer`、`ResumeTransfer`、`ListTransfers`、`DeleteTransfers`、`MarkTransfersSeen`、`CheckReceiveDir`+ - [x] `Transfer` 等消息+ - [x] `Config` 23–25、`Device` 9–11、`Event` 11–12+- [x] 生成 Go 与 Dart 代码(`scripts/gen-proto.sh`)++## 2. 后台服务(Go)++- [x] `pack/frames.go`:帧格式编解码、从任意位置续传、逐文件 SHA-256+- [x] `store`:`transfers`、`transfer_entries` 两张表与查询+- [x] `config`:`receive_dir`、`receive_disabled`、`receive_notify_disabled`;各平台的「下载」文件夹+- [x] 连接层:连上后交换 `PeerFeatures`,结果挂到 `Device`;`send:` 开头的数据通道交给隔空传送+- [x] `internal/send`:+ - [x] 发送:统计、清单入库、排队(同一设备一次一批)、发起、开数据流、发帧+ - [x] 接收:检查(开关、保存位置、空间、单文件上限)、应答、写临时目录、校验、移到保存位置、重名改名+ - [x] 取消(两边)、中断与自动续传(30 分钟内)、手动继续+ - [x] 进度(0.2 秒节流)、当前文件(0.5 秒)+ - [x] 官方中转:`allow_relay`,额度用完暂停、恢复后继续+- [x] `internal/power`:传输期间阻止空闲睡眠(Mac、Windows、Linux)+- [x] 通知:较大传输开始时一条、完成或失败替换它;`reveal` 动作;点通知打开隔空传送页+- [x] `rpc`:新接口、事件、`Device` 新字段+- [x] 清理:没续上的半成品 7 天后删除;记录保留 30 天或 500 条+- [x] Mac:收到的文件打 `com.apple.quarantine`+- [x] `scripts/build.sh`:后台服务 Info.plist 加文件夹权限说明,五种语言++## 3. 界面(Flutter)++- [x] 依赖:`desktop_drop`、`file_selector`;快捷粘贴窗口不引用它们+- [x] 雷达抽成公共组件,「搜索附近设备」改用它,外观不变+- [x] 侧边栏「隔空传送」:进度环 / 新收到的个数+- [x] 隔空传送页:雷达(内外圈、各状态、进度环)、拖到设备上发送+- [x] 发送窗口:拖入、选择文件 / 文件夹、进度、排队、取消+- [x] 官方中转确认框+- [x] 传输列表:收到的 / 发出的、悬停列出文件、在访达中显示、继续、重新发送、清除+- [x] 设置页「隔空传送」一组:接收开关、保存位置、通知+- [x] 第一次打开隔空传送页时检查保存位置(触发 Mac 的文件夹授权)+- [x] 五种语言的文案++## 4. 自动测试++- [x] `pack`:帧编解码、续传、路径穿越、Windows 文件名+- [x] `send`:两个后台服务互发:完成、取消、断开续传、源文件被改、保存位置不可用、重名、关闭接收、旧版本、离线、官方中转需同意(磁盘空间不足只在实机上测)+- [x] `store`:建表、重开、标为已看、清理旧记录、删除时连带条目+- [x] 界面组件测试:雷达各状态、列表各状态、侧边栏标记+- [x] `go test ./...`、`go vet`、`flutter analyze`、`flutter test` 全部通过++## 5. 实机验证(第 14 节)++- [x] 本机两个隔离的后台服务(假剪贴板构建,数据与保存位置都在 /tmp),用 `pasteferry-cli send` 实测(2026-10-22):+ - 2 GB 单个文件:46 秒,44 MB/s,逐字节一致+ - 2 万个小文件(含空文件夹、中文与 emoji 文件名):10.6 秒,`diff -r` 完全一致,临时目录清干净+ - 传到 892 MB 时杀掉接收方、重启:发送方自动从断点续传,内容一致+ - 传到 667 MB 时杀掉发送方、重启:33 秒内自动续传完成,内容一致+ - 重名自动改成「(2)」;传输期间有 `caffeinate` 的防睡眠声明,传完即撤+- [x] `pasteferry-cli` 加 `send`、`transfers` 两个命令++- [ ] Mac ↔ Windows 虚拟机、Mac ↔ Linux 虚拟机:大文件、海量小文件、断网续传、杀进程续传+- [ ] 官方中转:额度内、超额暂停、恢复+- [ ] Mac 首次接收的文件夹授权弹窗;连续两个版本之间授权是否保留+- [ ] 传输期间不睡眠++## 6. 发版(2.5.0,等用户说发再做)++- [~] 截图(`tools/screenshots` 已加 send、send-dark、send-dialog 三张,还没生成到 docs/)、官网功能页、隐私说明、`llms.txt`+- [ ] 版本号、`CHANGELOG.md`、`tools/release/notes.py`+- [ ] 按 `.claude/rules/commits-and-releases.md` 发布