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-30 · 基于仓库提交
c26db4d(客户端 2.7.4)状态:P1~P4 已实现并在本机完成端到端验证(见第 8 节)。第 1~7 节是当时定的方案, 实际实现与方案有出入的地方记在第 8 节「实现与方案的差异」。
背景:2.7.4 及更早的安卓 App 在功能声明里说「我能收隔空传送」,但手机端的 Go 核心根本没有隔空传送, 电脑发文件过去会 30 秒后「对方没有应答」,然后每次重连再试一次,永远发不过去(见第 2 节 Q1)。 本文给两件事:把隔空传送真正移植到安卓;以及今天查到的其余问题怎么处理。
1. 结论
能移植,而且 Go 核心几乎不用改。 隔空传送(internal/send)本来就是平台无关的,手机端缺的只是「组装」:
| 层 | 现状 | 移植要做的 | 难度 |
|---|---|---|---|
| Go 核心 | 手机端 mobile.start 没创建 send.Engine |
在 mobile.go 里照桌面 pasteferryd 的方式创建并接线 |
小,约 120 行 |
| 收到文件的落盘 | — | 存 App 私有目录,配置里把 ReceiveDir 指过去 |
小 |
| RPC 面 | Transfers 为 nil,相关方法返回 隔空传送不可用 |
把引擎挂上 deps.Transfers |
极小 |
| Android 宿主 | 已有 save / share 通道、前台服务 |
接收通知(可选)、接收目录的权限说明 | 小 |
| Flutter 界面 | 手机端只有「记录 / 发送 / 设备 / 设置」四个标签,SendTab 只能发剪贴板内容给所有设备 |
新增「隔空传送」页:选设备发文件、收文件进度、接受/拒绝、保存/分享 | 中,占大头 |
AppState 里传输相关的接口(transfers、sendFiles、answerIncoming、checkReceiveDir、
传输事件)桌面上已经全都有,手机端界面只是没接;MobileHost.save() / MobileHost.share()
也已经存在,收到的文件直接就能保存到「下载」或分享出去。所以界面虽有工作量,但没有新的底层能力要造。
建议分两期(第 6 节):一期做「局域网内手机 ↔ 电脑互传文件」,二期做陌生人、通知、后台接收。
2. 今天查到的问题
按「要不要修」逐条给结论。Q1 已经改完(未提交),其余待你确认后一起做。
Q1 手机端声明了它没有的能力(必修,已实现)
- 证据:
release/PasteFerry-android-arm64.apk里send.(*Engine).handleOffer、send.(*Engine).runOutgoing、对方没有应答这三个符号都是 0 处;同一份 APK 里send_files_v1、send_files_tcp_v1各 1 处。 桌面pasteferryd.exe对照是 5 / 3 / 1 处。 - 机制:
peers.featuresFor无条件声明这三个能力,发送端send.SendFiles只按声明放行 (p.Supported),发送页也只看receivesFiles。手机收到SendOffer后在sync.(*Engine).HandlePeerMessage的 switch 里没有分支,静默丢弃,不回绝也不打日志。 - 现场:本机复现,桌面 → 手机 22 KB 文件,
state=direct之后正好 30.0 秒打对方没有应答 模块=隔空传送,传输 30.1 秒变interrupted,与用户日志 (22:37:11.583 direct→22:37:41.585 对方没有应答)一致。 - 已改:
peers.Options.SendFiles控制声明;手机端不打开。另加send_files_recv_v1:手机平台必须额外声明它才算真的能收,挡住已经装出去的 2.7.4 安卓包。 改完后同一脚本:能收文件=false、SendFiles 被拒绝:unsupported,不再挂 30 秒。 - 和本次移植的关系:
send_files_recv_v1正是「安卓真的能收了」的开关。移植完成后手机端声明它, 电脑就会正常允许发送,不需要再改判定逻辑。
Q2 接收方超时失败是静默的(已修)
sync.newReceiveLocked有 30 秒看门狗,超时走failReceive,它只改数据库状态,一行日志都不打。- 后果:现场日志里
22:11:05、22:14:24两条kind=4 status=3之后再无下文,用户看到 「只有复制记录、没有文件」,而诊断报告里查不到任何原因。 - 修法:
failReceive加一行Warn(记录 ID、原因、来源设备)。纯日志,不影响行为。
Q3 自动推送失败后不会重试(已修)
pushOrRequeue推流失败后走queueMissed,而它要求cfg.SyncBacklog为真, 这个开关默认关(「补发离线期间的内容(默认关)」)。- 后果:一次网络抖动=这条内容永久丢失,接收端留一个永远完不成的记录(配上 Q2 就是静默失败)。
- 已修:拆成两个队列。「offer 根本没发出去」(
offerToPeers里send失败)仍归SyncBacklog管; 「offer 发出去了、推流失败」进新的pushRetry队列(internal/sync/backlog.go),PeerReady时无条件重推,重发的是原样的 offer(不带backlog标记), 对端已有这条记录,只会接着收,不会被当成旧内容而跳过自动写入剪贴板。
Q4 诊断报告缺关键字段(已修)
diag的 Devices 段只有「名字 / 平台 / 连接状态」,没有对端版本号和能力声明。 这次定位靠的是猜 + 反编译 APK,如果有这两项,一条报告就能定案。- 修法:
DiagInput带上每个 peer 的app_version、features、receives_files, 报告里加两列。只加字段,不影响替换规则。
Q5 本机复制文件读不到时用户不知道(已修)
- 现场
22:15:23有记录本机复制失败 err=剪贴板中的文件都不可访问,HandleClipboardChange只写Warn就返回,界面上什么都不显示。 - 典型场景:从压缩包预览、邮件附件、某些网盘客户端复制文件时,剪贴板里是虚拟路径。
- 已修:新增
Event.notice(只带一个固定代码),桌面端一分钟内最多提示一次,两端界面弹 toast。
Q6 「对方没有应答」时用户只看到「中断」(已修)
- 目前 30 秒没应答就
interrupt,界面文案是「中断」,用户点「继续」还是同样结果。 - 已修:新增
interruptWith(t, reason),超时那一路带上peer_unreachable,界面显示 「{对方} 没有应答」(复用已有的reasonTimeout文案,没新增翻译),状态仍是「中断」, 点「继续」照常能接着发。
Q7 陌生设备列表把 receives_files 写死为 true(本次不动)
peers.Stranger()直接返回ReceivesFiles: true。目前 Flutter 界面不读这个字段 (只有Device.receivesFiles和Friend.receivesFiles被用在发送判定里),所以不影响用户。- 记着,等二期做「陌生人发给我」时一并改成按声明判断。
3. 移植方案
3.1 Go 核心:把引擎组装起来
新增 client-core/mobile/send.go,内容与 cmd/pasteferryd 的组装对应,去掉只有桌面才有的部分:
sender = send.New(send.Options{
Store: db,
LoadConfig: loadCfg,
Send: peerMgr.P2P().Send,
OpenStream: peerMgr.P2P().OpenStream,
ListenLAN: listenLAN, // lantcp,同桌面 lanHooks
DialLAN: dialLAN,
Peer: func(id string) send.Peer { return sendPeer(peerMgr, id) },
// Admit 一期留空:只收自己设备发来的,陌生人一律 not_allowed(见 3.6 二期)
OnChange: func(t *pb.Transfer) { hub.Publish(rpc.EventTransferChanged(t)) },
OnRemoved: func(id string) { hub.Publish(rpc.EventTransferRemoved(id)) },
OnNotice: func(kind send.NoticeKind, t *pb.Transfer) { notify.transfer(kind, t) },
})
要点:
Inhibit、Thumbnail、Delivered、RelayQuotaExhausted、Connect、ListenLAN、DialLAN全部留空即可,internal/send里每一处都做了 nil 判断(已核对send.go:485、ask.go:165、outgoing.go:91、pipe.go:61、pipe.go:120)。手机端一期只走局域网,没有官方中转,RelayQuotaExhausted本来也用不上。ListenLAN/DialLAN直接抄cmd/pasteferryd/send_lan.go的lanHooks(id, peerMgr)。 已实测GOOS=android GOARCH=arm64 CGO_ENABLED=0 go build ./internal/send ./internal/transport/lantcp ./internal/peers全部通过:android同时满足linux构建约束,复用fs_linux.go的unix.Statfs,不需要新增平台文件。 (cmd/*交叉编译只会在链接期因 pion 依赖的net.zoneCache报错,出包脚本的-ldflags=-checklinkname=0就是为这个;./mobile本身能编译。)peers.Options改成:SendFiles: trueShareableStream: send.IsStream(现在是func(string) bool { return false })InUse: func(id string) bool { return sender != nil && sender.Busy(id) }OnPeerReady里同时调engine.PeerReady和sender.PeerReady(现在是前者)
sendPeer只在有好友/陌生人的桌面上才需要完整实现;手机端一期只用到RoleSelf分支, 照抄桌面cmd/pasteferryd/friends.go的同名函数即可(约 20 行)。
3.2 收到文件放哪里
- 手机端把
cfg.ReceiveDir固定成<dataDir>/received(dataDir是filesDir/pasteferry,App 私有,不需要任何存储权限)。写法和现在强制cfg.ServiceMode = "lan"一样,放在mobile.start里,saveCfg也一并守住。 - 界面上隐藏「保存位置」设置(
send_settings.dart的那一项在手机端不显示), 用户拿文件走「保存到下载」或「分享」。 - 现有
MobileHost.save(paths)(MediaStore,Android 10+ 无需权限)和MobileHost.share(paths)直接可用,不需要新的平台通道。
3.3 能力声明
移植完成后手机端声明:send_files_v1、send_files_tcp_v1、send_files_ask_v1、send_files_recv_v1。
SendFiles: true 已经在 Q1 的改动里接好这三者;send_files_recv_v1 也一并在同一处声明,
电脑端的平台兜底(Q1)随之放行,不需要再改判定逻辑。
版本兼容(沿用 friends-send.md 10.2 的规矩):
| 手机 | 电脑 | 结果 |
|---|---|---|
| 新版(声明 recv) | 2.7.5 及以后 | 正常隔空传送,局域网直连时走 TCP 快速通道 |
| 新版 | 2.7.4 及以前 | 走剪贴板同步(旧电脑只认 send_files_v1,而旧电脑没有 Q1 的兜底,行为与今天相同) |
| 2.7.4 及以前 | 2.7.5 及以后 | 电脑认为它不能收,发送页显示「需要更新」 |
| 2.7.4 及以前 | 2.7.4 及以前 | 今天的样子:30 秒「对方没有应答」 |
3.4 RPC 面
deps.Transfers 挂上引擎即可,SendFiles / CancelTransfer / ResumeTransfer /
ListTransfers / DeleteTransfers / MarkTransfersSeen / CheckReceiveDir /
AnswerIncoming 自动可用(桌面用的 transfersAPI 包装在 cmd/pasteferryd/friends.go,
手机端只需要 SendFiles 这一层薄包装,或把包装挪到共用位置)。Flutter 侧 AppState 已经在调这些接口。
3.5 Android 宿主
一期(必须):
- 无新增。保存/分享复用现有通道。
二期(体验,见 6):
- 新增通知渠道
transfers(IMPORTANCE_DEFAULT),用于「有人要发给你 N 个文件(点开接受)」和 「收到 N 个文件」;点通知打开 App 并切到隔空传送页。 - 实现方式:
mobile.Host接口加一个TransferNotice(kind, name, detail string), 由OnNotice调用;Kotlin 的Core.kt里实现,SyncService负责发通知。 注意 gomobile 只会用基本类型,参数用字符串拼。 - 后台接收:现在有前台服务,传输期间不会有问题;系统杀后台的风险与剪贴板同步相同, 文档里已有的「自启动白名单」提示照样适用。
3.6 Flutter 界面
一期(必须):
ui/lib/mobile/新增transfers_tab.dart(或并入设备页):- 设备卡片上一个「发送文件」按钮 →
file_selector选文件 →AppState.sendFiles(deviceId, paths)。 手机端选文件已经有现成的_pickFiles()(send_tab.dart:82)可以抽出来复用。 - 传输列表:进行中(进度、速度、取消)、已完成(保存 / 分享)、失败(原因 + 继续)。
桌面
send_page.dart里的条目渲染可以抽成共用 widget,但手机端样式要按触控重做。
- 设备卡片上一个「发送文件」按钮 →
- 收到请求时的确认:复用
widgets/incoming_dialog.dart(桌面上就是它), 在MobileShell里按state.askingIncoming弹窗或弹底部面板。 - 设置页隐藏「保存位置」(见 3.2)。
二期:陌生人收发、通知、后台。
3.7 不做的事(一期)
- 手机收「文件夹」原样落地:按文件夹整体接收,导出时逐个文件走 MediaStore(
FileSaver已支持目录)。 - 手机之间的隔空传送:协议上通,但一期不验收。
- 官方中转 / 跨网:手机仍然只走局域网。
- iOS:本文不涉及。
4. 改动清单
| 文件 | 改什么 |
|---|---|
client-core/mobile/mobile.go |
创建 send.Engine、挂 deps.Transfers、SendFiles: true、ShareableStream、InUse、PeerReady |
client-core/mobile/send.go(新) |
sendPeer、lanHooks(lantcp)、ReceiveDir 默认值 |
client-core/internal/peers/{manager,friends}.go |
已完成:Options.SendFiles、send_files_recv_v1、ReceivesSendFiles |
client-core/internal/sync/receive.go |
Q2:failReceive 加日志 |
client-core/internal/sync/backlog.go |
Q3:推流失败的重试队列 |
client-core/internal/diag/* |
Q4:报告加对端版本与能力 |
client-core/internal/sync/engine.go |
Q5:本机文件读不到时给界面一次性提示 |
client-core/internal/send/{outgoing.go,send.go} + ui 文案 |
Q6:peer_unreachable 错误码与提示 |
ui/lib/mobile/{transfers_tab.dart, mobile_app.dart, send_tab.dart} |
一期界面 |
ui/lib/mobile/settings_tab.dart |
隐藏保存位置 |
ui/android/.../{Core.kt, SyncService.kt} |
二期:传输通知 |
5. 测试计划
自动测试(必须)
mobile:起核心后ListDevices/GetStatus正常;SendFiles不再返回Unimplemented; 收到的文件落进<dataDir>/received;AnswerIncoming能接受和拒绝。peers:已有的TestFeaturesWithoutSendFiles、TestOldAndroidPackageDoesNotReceiveFiles保留; 新增「声明了 recv 的手机平台允许发送」。send:不动现有用例;Q3 加「推流失败后连接恢复会重试」、Q6 加错误码断言。diag:Q4 的报告快照。
端到端(本机,用已经搭好的复现脚本)
/tmp/pf-repro 里已经能用真实的 client-core/mobile 组装跑起一台「手机」,与桌面守护进程配对:
- 改造前:桌面发 22 KB 文件 → 30.1 秒
interrupted(已复现)。 - 改造后:同一命令应当
done,并且文件真的出现在手机的接收目录、SHA-256 一致。 - 反向:手机 → 桌面(现在走剪贴板同步已经能通,改成隔空传送后再验一次)。
- 断点续传:传输中杀掉手机端进程再起,桌面重连后应自动续传完成。
真机(需要你在手机和电脑上跑)
| 场景 | 看什么 |
|---|---|
| 电脑 → 手机 单文件 / 多文件 / 文件夹 | 进度、保存到下载、分享到微信 |
| 手机 → 电脑 | 进度、电脑侧文件完整 |
| 手机锁屏、切后台 | 前台服务是否撑住;被系统杀掉后重连能否续传 |
| 同一 WiFi 千兆 | 是否走 TCP 快速通道(日志 不是局域网直连,用数据通道 不应出现) |
| 手机拒绝 / 取消 | 两端状态一致,不留半截文件 |
| 存储不足 | 提示 no_space,不给用户写一半的残文件 |
界面:flutter analyze 加桌面端手点(手机端页面同时会被桌面构建编译,语法/类型错误能在这里挡住)。
6. 分期与工作量
| 阶段 | 内容 | 估计 |
|---|---|---|
| P1 | Go 核心组装 + RPC + 接收目录 + 能力声明 + Q1 收尾 | 半天 |
| P2 | 手机端隔空传送页(发文件、列表、进度、保存/分享)+ 收到请求的确认 | 1~1.5 天 |
| P3 | Q2~Q6 的修复 | 半天 |
| P4 | 传输通知、陌生人收发 | 1 天 |
| P5 | 真机联调、出包抽查(APK 里 send_files_v1 应为 1 处、send.(*Engine).handleOffer 应为 0 处→改为非 0) |
半天 |
建议 P1 与 P3 一起发一版(2.7.5,PATCH:手机端不能收文件属于缺陷),P2 完成后随 2.8.0 发。
7. 待你决定
- 分期:按上面 P1→P5 走,还是你希望一次做完(P2 的界面工作量最大,且我这边没有安卓设备,
只能靠
flutter analyze和桌面端回归,真机效果要你验)。 - Q3 的做法:给「已经发出去但没送到」单独做一个重试队列(我倾向),还是把
SyncBacklog默认打开(会顺带改变「离线补发」的行为,影响面更大)。 - 安卓接收目录:固定成 App 私有目录 + 用户点「保存到下载」(我倾向,权限最干净), 还是直接写系统下载目录(Android 10+ 走 MediaStore,需要额外处理重名和用户删改)。
- 通知:一期就要传输通知(要多改 Kotlin 与
Host接口),还是放二期。
8. 实现记录(2026-10-30)
8.1 做完了什么
| 阶段 | 内容 | 状态 |
|---|---|---|
| P1 | Go 核心组装、RPC 面、接收目录、能力声明 | 完成 |
| P2 | 手机端隔空传送页(设备发文件、传输列表、保存/分享) | 完成 |
| P3 | Q2~Q6 | 完成 |
| P4 | 陌生人收发、传输状态进常驻通知 | 完成(通知是折中方案,见 8.3) |
| P5 | 真机联调 | 待你在手机上验 |
8.2 端到端验证结果(本机,用真实的 client-core/mobile 组装起一台「手机」)
| 场景 | 结果 |
|---|---|
| 改造前:电脑 → 手机 22 KB | state=direct 后 30.0 秒「对方没有应答」,30.1 秒中断,与用户日志一致 |
| 改造后:电脑 → 手机 22 KB | 0.5 秒 done,接收目录里的文件 SHA-256 与源文件一致 |
| 改造后:电脑 → 手机 4.8 MB 文件夹(含子目录) | 0.5 秒 done,逐文件 SHA-256 一致,走了局域网快速通道 |
| 改造后:电脑 → 手机 2 GB | 传输中杀掉手机进程 → interrupted;手机重新启动后自动续传,2 GB 完成后 SHA-256 一致 |
| 改造后:手机 → 电脑 4.8 MB 文件夹 | 0.5 秒 done,电脑侧逐文件 SHA-256 一致 |
| 能力声明 | 电脑看到手机「能收文件=true、版本 2.7.4」;send_files_recv_v1 让平台兜底放行 |
8.3 实现与方案的差异
- 功能声明的开关 用了
peers.Options.SendFiles(手机端打开),而不是在featuresFor里按平台判断。 平台兜底只保留给「已经装出去的 2.7.4 安卓包」(send_files_recv_v1)。 - 对端状态的映射抽成了共用包
internal/sendpeer(Peer/Admit/LANHooks), 桌面cmd/pasteferryd和手机mobile用同一份,cmd/pasteferryd/send_lan.go已删除。 两端的判定不会跑偏。 - 接收目录 固定成
<数据目录>/received(App 私有),并且必须由mobile.start先建好:internal/send只建它下面的 partial 目录,保存位置不存在时会直接回绝dest_unavailable。 - 界面没有新增文案:设备组用
navDevices、列表用friendHistory、发文件按钮用sendChooseFiles、保存/分享/继续/删除都用现有键。新增的下拉提示用了新键noticeFilesUnreadable(5 种语言)。 - 传输通知是折中方案:手机端没有新增通知渠道,也没有改
mobile.Host的 gomobile 接口 (改它必须用 Android 工具链重新编译 AAR 才能验证,本机没有 NDK)。 现在收到传输时会把「来自 X 的文件」写进已有的常驻通知,用户拉开通知栏能看到。 单独的传输通知(带「点开接受」动作)留在后面,见 8.5。 - 陌生人:手机端把
Admit接上了sendpeer.Admit,附近的陌生设备发文件时会弹确认 (复用桌面的showIncomingDialog)。手机主动发给陌生设备(lan:实例名)还不支持—— 手机界面上没有陌生设备列表。
8.4 已知的边界
- 手机在后台被系统杀掉后,正在进行的传输会中断,重连后自动续传(已验证);但用户不会收到提醒, 直到打开 App。
spaceReserve(200 MB)是桌面的常量:手机剩余空间不足 200 MB 时会回绝no_space。 手机上这个余量偏保守,但不会写半截文件,暂不调整。- 局域网快速通道需要两端都声明
send_files_tcp_v1(本次都声明了),防火墙/睡眠仍可能退回数据通道。
8.5 还没做的
- 单独的传输通知渠道 + 点开接受(要改
mobile.Host接口与 Kotlin,必须在有 NDK 的机器上验证)。 - 手机端主动给「附近的陌生设备」发文件(需要陌生设备列表界面)。
- 手机接收文件夹后的「整体导出为 ZIP」(现在逐个文件保存/分享)。
- Q7(
peers.Stranger()里ReceivesFiles写死为 true):界面目前不读这个字段,留到做陌生人界面时一起改。