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.
隔空贴:隔空传送——把文件直接发到另一台电脑
方案稿 · 2026-10-21 · 待审核,尚未实现 · 已按 2.4.1(快捷粘贴、收藏已发布)的代码核对
- 标「待验证」的条目,要先在第 12 节的原型里确认。
- 标「待定」的条目需要你拍板,汇总在第 15 节,每条都附了建议。
- 和 2.4.0 新加的快捷粘贴、收藏有交集的地方单独注明。
1. 概览
1.1 要做的事
左侧菜单栏加一个「隔空传送」页:
- 页面中间是雷达,已配对的设备排在雷达上。
- 点一台设备,弹出发送窗口,把文件或文件夹拖进去,松手就开始发。也可以直接把文件拖到雷达上的设备上。
- 对方自动接收,存到它设置的保存位置(默认是「下载」文件夹),并弹出系统通知。
- 两边的隔空传送页下方都有传输列表:收到的、发出的。收到的每一条都可以「在访达中显示」。
- 设置页加「隔空传送」一组,可以改保存位置。
不设大小上限。 单个文件、文件夹、文件个数都不限,靠断点续传保证大文件能传完(第 6.4 节)。
1.2 和现在的「同步文件」有什么不同
现在复制文件也会同步到其他设备。隔空传送不替代它,两者各管各的:
| 复制文件(现有) | 隔空传送(新) | |
|---|---|---|
| 触发 | 在任何地方复制,自动广播给所有设备 | 主动拖给某一台设备 |
| 发给谁 | 所有在线设备 | 选中的那一台 |
| 大小 | 超过「自动同步上限」(默认 50 MB)只同步文件名,要对方手动接收 | 不限,直接发 |
| 存到哪里 | 缓存目录,过期后被清理 | 用户的保存位置,永久保留 |
| 剪贴板 | 收到后写进对方的剪贴板 | 不碰剪贴板 |
| 复制记录 | 进复制记录 | 不进,单独的传输列表 |
| 中断后 | 从头重来 | 从断点继续 |
1.3 你没提到、方案里补上的
下面这些是梳理时发现必须考虑的,详细内容在各节里:
- 官方中转有额度。 官方服务每台机器每天 100 MB、限速约 0.25 MB/s。「不限大小」在局域网和打洞直连时成立,走官方中转时要先提示、额度用完就暂停,等直连或第二天自动继续(第 10 节)。
- 断点续传。 现有的文件同步断了只能从头再传。隔空传送不限大小,必须能续传,否则 20 GB 传到一半断网就白传了(第 6.4 节)。
- 对方版本太旧。 旧版本不认识隔空传送的消息,会静默丢掉。需要设备之间交换能力标记,雷达上把旧版本设备标成「需要更新」(第 6.1 节)。
- 传输期间不让电脑睡眠。 两边都要阻止系统空闲睡眠,否则大文件传一会儿就断(第 9 节)。
- macOS 的文件夹权限。 后台服务是单独的程序,第一次读「桌面」「文稿」、写「下载」时,系统会弹窗问一次。要配好说明文字,并且在用户看着的时候触发,不能等对方发文件时才弹(第 9.1 节)。
- 对方磁盘空间、重名、保存位置不可用。 发送前对方先检查空间;重名自动改名;保存位置被删了或外置盘拔了,直接回绝并说明(第 7 节)。
- 安全。 只有已配对的设备能发;在 Mac 上,收到的文件按隔空投送的做法打上「来自网络」的标记(待定,第 7 节)。
- 拖不进来的东西。 照片 App、邮件附件这类「承诺文件」首版不支持,窗口里有「选择文件…」按钮兜底(第 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 发送
方式一:点设备,在窗口里拖。
- 点雷达上的一台设备,弹出「发送到 MacBook Air」窗口,标题下是连接方式(局域网 / 直连 / 中转)。
- 窗口里是一个大的虚线框:「把文件或文件夹拖到这里」,下面有「选择文件…」「选择文件夹…」两个按钮。
- 拖着文件经过虚线框时,框变成蓝色实线,文字换成「松手发送到 MacBook Air」。
- 松手立即开始发送(按你的描述,不再多一步确认;待定)。
- 窗口变成进度视图:每一批一行,显示名称、大小、进度、速度、剩余时间、取消按钮。虚线框缩小到下方,可以继续拖入,排在后面发。
- 关掉窗口不影响发送,进度在隔空传送页的「发出的」列表里继续显示。
方式二:直接拖到雷达上。
- 从访达拖着文件进入隔空传送页时,所有能接收的设备图标描边变亮,提示「拖到一台设备上」。
- 移到哪台设备上,那台变成系统蓝、略微放大,松手即发送。
- 拖到雷达空白处松手:不发送,提示「拖到一台设备上发送」。
一次拖了多个东西(比如 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 同时发:
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 不变):
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)。和访达、资源管理器的习惯一致。 - 文件名原样保留,只有接收方是 Windows、名字里有 Windows 不允许的字符时才改(2026-10-22 与用户确认):
: * ? " < > | \换成相近的全角字符(a:b?c.txt→a:b?c.txt),控制字符换成_,结尾的点和空格后面补_,设备保留名(CON、NUL等)前面加_;只差大小写的同名文件加(2)。沿用pack/names.go,和复制同步一致。- 只改文件名,文件内容一个字节都不动。Mac、Linux 上收到时名字原样落盘。
- 收到的那一行写明「N 个文件名含 Windows 不支持的字符,已换成相近的全角字符」(
Transfer.renamed_files)。 - Windows 上的
.DS_Store、._开头的 AppleDouble 文件不落盘,也和复制同步一致。
- 重名时改名:
- 空间检查:接受之前看保存位置所在磁盘的剩余空间,要大于「总大小 + 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 会以「受保护的视图」只读打开每一份收到的文档,要点「启用编辑」才能改。发文档是隔空传送最常见的用途,这个代价太大;发过来的又是用户自己的设备。
- macOS:给收到的文件加
8. 后台服务与接口
8.1 存储
新增两张表,和 clips 无关:
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 这次没有变化,编号照旧。
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 / 文件夹,不用改。
- Windows(
- 快捷粘贴窗口: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 个文件;杀掉任一方再重启都能从断点续传。和上面回环的上限一致。
正式版实机(2026-10-22,2.5.0):
| 线路 | 内容 | 速度 |
|---|---|---|
| Mac(千兆有线)→ 同一局域网的 Windows 台式机(真实电脑,延迟 0.2 ms) | 1 GB 随机数据 | 53 秒,平均 19.3 MB/s |
| Mac → Linux 虚拟机 | 1 GB 随机数据 | 14.8~17.4 MB/s |
| Mac → Linux 虚拟机 | 2003 个文件(2000 个小文件、中文与 emoji 名、空文件夹)+ 300 MB | 24.6 秒,两边逐个校验一致 |
| Windows 虚拟机 → Linux 虚拟机 | 300 MB | 9.2 MB/s |
真实千兆局域网只用到约六分之一。传输时 Mac 发送方的后台服务占约 2.2 个核,Linux 接收方占 1~1.7 个核,瓶颈是两端 WebRTC 协议栈逐包处理(DTLS、SCTP)的 CPU 开销,不是网络。要跑满千兆,还是第 12.1 节说的局域网专用 TCP 通道。
局域网 TCP 原型(2026-10-22,.scratch/tcpbench,不在仓库里):TLS 1.3,两端用 Ed25519 证书互相验证;每次写 60 KB,与隔空传送相同;两端都算 SHA-256。1 GB 随机数据:
| 线路 | 现在的数据通道 | TCP + TLS | TCP + TLS + zstd |
|---|---|---|---|
| Mac 本机回环(2 GB) | 44 MB/s | 732 MB/s | 611 MB/s |
| Mac → Linux 虚拟机 | 15~17 MB/s | 218 MB/s | 246 MB/s |
| Linux 虚拟机 → Mac | — | 205 MB/s | 199 MB/s |
| Mac → Windows 虚拟机 | 约 18 MB/s | 135 MB/s | 129 MB/s |
| Windows 虚拟机 → Mac | — | 99 MB/s | 101 MB/s |
虚拟机之间就有 7~14 倍的差距,而且都超过了千兆网的上限(约 110 MB/s),换到真实千兆局域网应该能跑满。加密和 zstd 不是瓶颈,所以正式实现可以保留它们。
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 发布,不再有前置条件 |