Skip to content

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.

58.5 KB
Raw Blame

隔空贴:隔空传送——把文件直接发到另一台电脑

方案稿 · 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 同时发:

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 会以「受保护的视图」只读打开每一份收到的文档,要点「启用编辑」才能改。发文档是隔空传送最常见的用途,这个代价太大;发过来的又是用户自己的设备。

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 / 文件夹,不用改。
  • 快捷粘贴窗口: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 发布,不再有前置条件