PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.
Dart airdrop-alternativeclipboardclipboard-sharingclipboard-synccopy-pastecross-platformend-to-end-encryptionfile-syncfile-transferfluttergolanglinuxmacosnat-traversalp2pself-hostedtailscaleuniversal-clipboardwebrtcwindows
好友开发任务(2.5.4、2.6.0)
方案:design/friends-send.md(定稿 2026-10-26) 基线:main
4b38b70(2.5.3)。2.5.4 先发,2.6.0 在它之上做。 上一份任务清单(隔空传送 2.5.0)在 git 历史里(b24cbf6),唯一没做完的一项挪到了第 9 节。 界面文案直接加到 ARB 文件里,不要运行ui/tool/l10n/strings.py:它落后于 ARB,运行会删掉 100 多个键。
状态:[ ] 未开始 · [~] 进行中 · [x] 完成
0. 准备
- 提交设计稿
design/friends-send.md(docs(design): plan sending files to friends) - 拉取最新 main,确认
go test ./...、flutter test在基线上是绿的
1. 2.5.4:「需要更新」误报(设计稿第 10.1 节)
- 写测试复现:在线(服务器在线通知或局域网可达)但 P2P 还没连上时,
Device.receives_files为 false -
daemon.proto:Device增加功能声明状态(unknown/known)和app_version -
wire.proto:PeerFeatures增加app_version -
peers.Manager:- P2P 连通后 5 秒仍没收到声明,才判定为旧版本
- 声明与版本号存进
devices(新增features、app_version列),启动时读回 - 连不上时报「暂时连不上」,不报旧版本
- 界面:
send_page.dart三态:还不知道 →「连接中…」(可点,点了先连);旧版本 →「需要更新」并提示版本;连不上 →「暂时连不上」 - 测试:在线未连通 →
unknown;连通不发声明 → 旧版本;重启后读出上次的声明;界面组件测试覆盖三态
2. 2.5.4:「官方服务」改叫「服务」(第 12 节)
- 五种语言 ARB:
officialService、useOfficialService、officialPrivacy、relayConfirmTitle、relayConfirmBody以及其他含「官方服务」的键(简体「服务」、繁体「服務」、英文 Service、日文 サービス) - 官网
tools/site/content/{zh,zh-tw,zh-hk,en,ja}.py与 README(中英)同步改,运行python3 tools/site/build.py - 内部标识符(
Official()、service_mode = official)和official-gateway.md不改 - 截图里如果有「官方服务」字样,重新生成
3. 2.5.4 发版(等用户说发再做)
-
go test ./...、go vet、flutter analyze、flutter test全部通过 - 本机两个隔离的后台服务:P2P 还没连上时雷达显示「连接中…」,不再闪「需要更新」
- 版本号、
CHANGELOG.md、tools/release/notes.py,按.claude/rules/commits-and-releases.md发布
4. 2.6.0:协议与接口(第 13 节)
-
wire.proto:FriendCard、FriendRequest、FriendAnswer、FriendRemove、AvatarRequest、AvatarData;SendOffer.note;SendAnswer.reason新代码(pending、declined、timeout、not_allowed、rate_limited) - 功能标记
friends_v1、send_files_ask_v1 -
daemon.proto:名字与头像、好友、发送(note、AnswerIncoming)、接收设置的 RPC;Friend、IncomingOffer等消息;新事件 - 好友码格式:
F加 6 位,放在proto/pairingcode(识别、规范化) - 生成 Go 与 Dart 代码(
scripts/gen-proto.sh)
5. 2.6.0:后台服务(Go)
5.1 存储与配置
-
store:contacts、contact_addrs、pending_notices、blocked_devices;transfers增加peer_role、note、thumb_path -
config:receive_from(默认friends)、everyone_until、display_name、avatar_path - 显示名默认值:macOS
NSFullUserName、Windows 显示名、Linux GECOS
5.2 角色与安全(第 11 节,最先做)
-
peers.Manager给每个连接带角色:self/friend_pending/friend/stranger - P2P 消息与数据流的入口白名单,新消息默认不放行;单测逐条覆盖每种消息类型
- 剪贴板广播、
PeerDisplay等只发给self -
signed.Verifier:公钥来源扩展到好友与本次局域网会话里的陌生设备,并带出角色 - 服务器关注列表(Hello 的
paired_device_ids)加上好友的设备 ID
5.3 好友
- 好友码:复用配对码代理(服务器)与局域网配对通道;
intent区分加好友与配对 - 「待定好友」连接上交换名片和头像,两边都确认后写入
contacts - 已配对的电脑不能加为好友;在「添加设备」里输入好友码自动转到加好友
- 删除好友:双向通知,对方不在线时写入
pending_notices,连上后补发(最多 30 天) - 屏蔽陌生设备
- 按需连接:只看在线状态时不建连接;发送、补发通知时才连,空闲 2 分钟断开
- 名片里的服务类型与自建服务器地址哈希;第 9.2 节的可达状态(
friend_reachability)
5.4 头像
-
SetAvatar:裁剪、缩到 256×256 JPEG、≤ 64 KB、去掉 EXIF;ResetAvatar - 名片带头像哈希,变了才请求
AvatarData;收到后重新解码再编码,坏数据退回默认头像 - 陌生人不交换头像
5.5 发送与接收
- 发给好友:对方必须声明
send_files_ask_v1;note校验(≤ 200 字符、单行、无控制字符、必须有文件) - 接收方:按
receive_from和角色决定直接拒绝、弹窗确认或自动接收(好友的auto_accept) - 等待确认:先回
pending,60 秒超时;发送方等最终结果 - 防打扰:同一台电脑 1 分钟内被拒 3 次,之后 10 分钟自动拒绝
- 非
self发来的文件:去掉可执行权限;Mac 上一律打隔离标记;核对路径穿越与符号链接 - 收到的图片:用
internal/imagepreview重新编码生成缩略图,写到thumb_path - 通知:接收请求带「接受」「拒绝」按钮与备注;能换图标的平台用对方头像;60 秒后换成「已忽略」
5.6 「所有人」模式
- 只在局域网:打开期间 mDNS 广播带显示名,关掉就撤下
- 10 分钟后自动回到「仅限好友」,发
receive_policy_changed事件 - 陌生设备公钥只存内存,关掉「所有人」就清掉
5.7 其他
-
rpc:新接口与事件 -
pasteferry-cli:friends、friend add | code | remove、send --to <好友> --note、accept、decline
6. 2.6.0:界面(Flutter)
- 隔空传送页顶部:头像、显示名(可改)、「好友 N」、「+」
- 头像菜单(选择、粘贴、拖入、恢复默认)与裁剪窗口
- 默认头像组件:圆形色块加首字,颜色由设备 ID 算出
- 雷达:好友排在最外圈,显示头像与第 8 节表格里的各种状态;「所有人」模式下的陌生设备(虚线圈)
- 好友列表窗口与右键菜单
- 添加好友:显示好友码、输入好友码、确认框(可展开安全码)、不在同一网络时的提示
- 发送窗口:好友标题、备注框(没选文件时不能用)、⌘V / Ctrl+V 粘贴图片和文件、等待接受 / 拒绝 / 没有回应
- 接收弹窗:对方头像、文件、备注、「以后自动接收」、倒计时
- 传输列表:好友的行带头像与备注,图片显示缩略图
- 和某个好友的传输记录窗口
- 底部「允许这些人给我发文件」菜单;「所有人 · 还剩 N 分钟」
- 第 9.2 节的「打开服务」提示,按钮跳到服务设置页
- 五种语言的文案(按第 6.5 节的口径:写「给好友发文件」,不写「聊天」)
7. 2.6.0:自动测试(第 15 节)
- 单测:角色白名单、接收设置三档 × 三种角色、60 秒超时、防打扰、备注校验、图片与头像、路径穿越、好友码识别、可达提示
- 本机端到端(
-tags fakeclip、隔离的-data-dir、receive_dir在 /tmp),A1/A2 配对、B1 另一个人:- A1 和 B1 加好友后互相发,备注与头像正确;A2 和 B1 互相发不了
- A1 复制文字、图片、文件后,B1 的剪贴板与复制记录没有变化
- B1 选「均不允许」时 A1 得到「不接收文件」
- 删除好友,含对方离线时补发
- 2.5.3 对端:显示「需要更新」,好友码报「配对码无效」
- 界面组件测试:雷达好友状态、发送窗口备注、接收弹窗
-
go test ./...、go vet、flutter analyze、flutter test全部通过
8. 2.6.0:实机验证与发版
- Mac(A)↔ Linux 虚拟机(B,隔离的 HOME,不用和真 Mac 配对过的数据):
- 双方打开服务、关掉局域网:跨网络发送、中转确认、额度扣减
- 一方关掉服务:第 9.2 节的提示
- Windows 虚拟机:接收弹窗、通知按钮与头像
- 官网:功能页加「给好友发文件」一节、截图(示例内容用 example.com、虚构的人名,不用真实公司名或地址)、常见问题、
llms.txt、README - 隐私说明补充:好友能看到的信息(显示名、电脑名、系统、服务类型、头像)
- 版本号、
CHANGELOG.md、tools/release/notes.py,按.claude/rules/commits-and-releases.md发布(等用户说发再做)
8.5 2.6.0:追加
- 设置页改成类别列表 + 二级页(通用、连接、同步、快捷粘贴、隔空传送、存储、关于),「打开服务…」直达「连接」
- 好友页:点好友列表的一行(或右键雷达下的头像)打开,含状态、自动接收开关、发送按钮与传输记录
9. 遗留(来自 2.5.0)
- 官方中转额度用完时暂停、恢复后继续:会用掉当天的中转额度,等用户同意再测