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.

docs: design sending files to a paired device

baiyuzeeccce7b4b47b
diff --git a/design/send-files.md b/design/send-files.md
new file mode 100644
index 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.md
new file mode 100644
index 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` 发布