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 quick paste, favorites and link filter

baiyuze0b68cbb57ee1
diff --git a/design/quick-paste-and-favorites.md b/design/quick-paste-and-favorites.md
new file mode 100644
index 0000000..e340ad8
--- /dev/null
+++ b/design/quick-paste-and-favorites.md
@@ -0,0 +1,819 @@
+# 隔空贴:快捷粘贴、收藏与复制记录改进
+
+> 方案稿 · 2026-10-20 · 尚未实现
+>
+> - 标「待验证」的条目,要在第 12 节的原型里确认后再定。
+> - 本文合并了之前分开写的快捷粘贴窗口与收藏两份方案。
+
+## 1. 概览
+
+这次一共四项改动:
+
+1. **快捷粘贴窗口**
+ - 在任何程序里按 ⌥V(Mac)/ Alt+V(Windows、Linux),弹出一个小窗口,列出复制记录,从其他设备收到的也在里面。
+ - 可以用数字键、方向键加回车或者鼠标单击来选。选中后写回剪贴板,并自动粘贴到原来的输入位置。
+ - 默认开启,设置里可以关闭。
+2. **收藏**
+ - 和微信的收藏一样,收藏时另存一份,永远不会被自动清理。
+ - 取消收藏时,这一条放回复制记录,点错了也找得回来。
+3. **悬停显示完整内容**:鼠标在一行上停一会儿,弹出提示框,显示全文、大图或完整的文件列表。快捷窗口和主窗口都有。
+4. **类型筛选**:主窗口和快捷窗口都按「全部 · 文字 · 链接 · 图片 · 文件」筛选,快捷窗口再多一个「收藏」页签。「链接」是新加的一类,见第 5 节。
+
+**实现上**:
+
+- 快捷窗口由一个新的常驻进程提供:
+ - 它和界面用同一套 Flutter 代码,开机由系统拉起,平时隐藏,按下快捷键后 0.1 秒内出现。
+ - 全局快捷键、记下并还原原来的窗口、模拟粘贴,由各平台很薄的原生外壳完成。
+ - 列表、搜索、按键逻辑写在 Dart 里,三个平台共用。
+- 收藏、悬停提示框、链接筛选只改后台服务和主界面,不涉及原生代码(第 13 节的一期 A)。
+- 设备之间的协议不变。后台服务的本机接口要加几个字段和 RPC(第 8.3 节)。每一期按新功能升 MINOR。
+
+**各平台的快捷粘贴支持程度**:
+
+| 平台 | 全局快捷键 | 自动粘贴 | 需要用户授权 |
+|---|---|---|---|
+| macOS 13+ | ✓ | ✓ | 「辅助功能」,模拟 ⌘V 要用 |
+| Windows 10 / 11 | ✓ | ✓,目标窗口以管理员身份运行时除外 | 无 |
+| Linux X11 会话 | ✓ | ✓ | 无 |
+| Linux Wayland,GNOME 48+ / KDE Plasma 5.27+ | ✓,经系统的全局快捷键门户 | 首版不做:选中后放进剪贴板,提示按 Ctrl+V | 首次注册时系统弹窗确认 |
+| Linux Wayland,GNOME 46(Ubuntu 24.04) | 设置页一键写入系统的自定义快捷键 | 同上 | 无 |
+
+**示意图里的符号**(全文通用):
+
+- 类型:`¶` 文字,`↗` 链接,`▣` 图片,`▤` 文件,`⇣` 还没下载的大文件;
+- 收藏:`★` 已收藏,`☆` 未收藏;
+- 操作:`⧉` 放进剪贴板,`⌫` 删除;
+- `▌` 当前选中的一行,实际是系统蓝色的高亮。
+
+## 2. 快捷粘贴窗口:交互
+
+### 2.1 呼出与关闭
+
+- 按快捷键后:
+ - 窗口出现在鼠标所在屏幕的中上方,位置和聚焦搜索一样。Wayland 上位置由系统决定,一般在屏幕中央。
+ - 停在「全部」页签,选中第 1 条,搜索框为空。
+- 下面几种情况都会关闭窗口,不粘贴任何内容:
+ - 再按一次快捷键;
+ - 按 Esc(搜索框里有字时,第一次按 Esc 先清空搜索);
+ - 点窗口外面,或者切到别的程序。
+- 选中一条后:窗口立即消失,焦点回到原来的窗口,然后粘贴。
+
+### 2.2 列表与页签
+
+- 内容和主窗口「复制记录」页是同一份数据,按时间倒序,本机复制的和其他设备发来的都在。
+- 搜索框下方是一行页签:**全部 · 文字 · 链接 · 图片 · 文件 · 收藏**。
+ - 前五个按类型筛选复制记录,和主窗口的筛选一致(第 5 节)。
+ - 「收藏」列出所有收藏,不分类型(第 3.4 节)。
+ - 按 Tab / ⇧Tab 依次切换,也可以用鼠标点。
+ - 搜索只在当前页签的范围里进行。
+- 每一行显示:
+ - 类型图标;
+ - 内容预览:文字一行、图片缩略图、文件名和文件个数;
+ - 来源设备(只有从其他设备收到的才显示);
+ - 时间。
+- 每行最左边是序号:
+ - 当前列表的前 9 条标 1–9,按对应数字就粘贴那一条。第 10 条起不标序号。
+ - 切换页签、搜索时,都按新的列表重新编号。
+ - 搜索时序号显示成 ⌘1–⌘9(Windows、Linux 上是 Alt+1–Alt+9),这时直接按数字是在搜索框里打字。
+ - 序号跟着条目走,不随滚动变化。
+- 一屏大约 9 行,可以滚动。
+- 搜索:
+ - 先在已加载的记录里过滤,结果即时出现;
+ - 同时用 `ListHistory` 的 `query` 搜索当前页签的全部历史。
+- 只有元数据的大文件(`REMOTE_ONLY`):
+ - 选中后先下载,进度显示在这一行里,下载完自动粘贴。
+ - 按 Esc 只取消粘贴,下载照常继续。下载完会照现有逻辑覆盖剪贴板,和点「下载」按钮的效果相同。
+- 已过期或失败的记录显示为灰色,不能选。
+
+### 2.3 按键
+
+| 按键 | 作用 |
+|---|---|
+| 1–9 | 粘贴对应的一条(只在搜索框为空时有效) |
+| ⌘1–9(Mac)/ Alt+1–9 | 任何时候都能粘贴对应的一条,搜索时用这个 |
+| ↑ ↓(Mac 上还有 ⌃P ⌃N) | 移动选择 |
+| 回车 | 粘贴选中的一条 |
+| ⇧回车 | 以纯文本粘贴,去掉网页格式 |
+| ⌘回车 / Ctrl+回车 | 只放进剪贴板,不粘贴 |
+| Tab / ⇧Tab | 切换页签:全部 → 文字 → 链接 → 图片 → 文件 → 收藏,到头后回到第一个 |
+| ⌘D / Ctrl+D | 收藏选中的一条;在「收藏」页签里是取消收藏,放回复制记录 |
+| ⌘⌫ / Shift+Delete | 删除这条记录(「收藏」页签里没有这个操作) |
+| Esc | 关闭窗口 |
+| 其他字符 | 输入到搜索框 |
+
+### 2.4 鼠标
+
+- 单击一行就粘贴,和回车一样。
+- 鼠标移到哪一行,高亮就跟到哪一行;停留约 0.5 秒,弹出完整内容的提示框(第 4 节)。
+- 右键菜单:只复制、收藏 / 取消收藏、删除。
+
+### 2.5 不能自动粘贴时
+
+以下情况下,选中后照样写进剪贴板,但不模拟按键:
+
+- Mac 没有授予辅助功能权限;
+- Wayland 会话;
+- 目标窗口以管理员身份运行;
+- 用户在设置里选了「只放进剪贴板」。
+
+窗口关闭后不另外弹提示。窗口底部一直显示当前的模式,用户在选之前就能看到,例如「回车粘贴」或「选中后按 ⌘V 粘贴」。
+
+### 2.6 界面示意
+
+下面以 Mac 为例。
+
+**呼出时**(「全部」页签):
+
+```
+╭──────────────────────────────────────────────────────╮
+│ ⌕ 搜索
+│ [全部] 文字 链接 图片 文件 收藏
+├──────────────────────────────────────────────────────┤
+│▌ 1 ¶ 会议改到周四下午 3 点,地点不变 · 刚刚
+│ 2 ↗ https://github.com/baiyuze/pasteferry · 2 分钟前
+│ 3 ▣ 截图 14.32.png ★ · Windows 台式机 · 5 分钟前
+│ 4 ▤ 合同扫描件.pdf 等 3 个 · 1 小时前
+│ 5 ¶ docker compose up -d --build · 1 小时前
+│ 6 ⇣ PasteFerry.dmg · 812 MB · 未下载 · MacBook Air · 昨天
+│ 7 ¶ 收货地址:上海市徐汇区漕溪北路 … ★ · 昨天
+│ 8 ¶ SELECT id, status FROM orders WHERE … · 昨天
+│ 9 ¶ pnpm install · 昨天
+│ ¶ git push origin main · 昨天
+├──────────────────────────────────────────────────────┤
+│ ↩ 粘贴 ⇧↩ 纯文本 ⌘↩ 只复制 ⌘D 收藏 esc 关闭
+╰──────────────────────────────────────────────────────╯
+```
+
+图片行的左边是一个小缩略图,示意图里画不出来。
+
+**「图片」页签**:
+
+```
+╭──────────────────────────────────────────────────────╮
+│ ⌕ 搜索
+│ 全部 文字 链接 [图片] 文件 收藏
+├──────────────────────────────────────────────────────┤
+│▌ 1 ▣ 截图 14.32.png ★ · Windows 台式机 · 5 分钟前
+│ 2 ▣ 图片 · 1280 × 720 · 今天 11:20
+│ 3 ▣ IMG_2041.HEIC · 3.2 MB · MacBook Air · 昨天
+├──────────────────────────────────────────────────────┤
+│ ↩ 粘贴 ⌘↩ 只复制 ⌘D 收藏 esc 关闭
+╰──────────────────────────────────────────────────────╯
+```
+
+**搜索时**:输入「docker」后,序号变成 ⌘1、⌘2……
+
+```
+╭──────────────────────────────────────────────────────╮
+│ ⌕ docker▏
+│ [全部] 文字 链接 图片 文件 收藏
+├──────────────────────────────────────────────────────┤
+│▌⌘1 ¶ docker compose up -d --build · 1 小时前
+│ ⌘2 ¶ docker logs -f gateway · 2 天前
+│ ⌘3 ¶ 把 docker 镜像源换成国内的 … · 2 天前
+├──────────────────────────────────────────────────────┤
+│ ↩ 粘贴 ⇧↩ 纯文本 ⌘↩ 只复制 ⌘D 收藏 esc 清空搜索
+╰──────────────────────────────────────────────────────╯
+```
+
+**「收藏」页签**:
+
+```
+╭──────────────────────────────────────────────────────╮
+│ ⌕ 搜索
+│ 全部 文字 链接 图片 文件 [收藏]
+├──────────────────────────────────────────────────────┤
+│▌ 1 ¶ 收货地址:上海市徐汇区漕溪北路 … · 收藏于 10-18
+│ 2 ▣ 截图 14.32.png · 收藏于 10-20
+│ 3 ▤ 营业执照.pdf · 收藏于 10-02
+├──────────────────────────────────────────────────────┤
+│ ↩ 粘贴 ⌘D 取消收藏(放回复制记录) esc 关闭
+╰──────────────────────────────────────────────────────╯
+```
+
+**不能自动粘贴时**,只换掉底栏:
+
+```
+├──────────────────────────────────────────────────────┤
+│ 选中后按 ⌘V 粘贴 · 授予「辅助功能」权限后可直接粘贴 [去授权]
+╰──────────────────────────────────────────────────────╯
+```
+
+- Wayland 上,底栏写「选中后按 Ctrl+V 粘贴」。
+- Windows 和 Linux 上,底栏的按键写成 Enter、Shift+Enter、Ctrl+Enter、Ctrl+D,搜索时的序号写成 Alt+1……
+
+## 3. 收藏
+
+### 3.1 规则
+
+- **收藏时另存一份**,和微信的收藏一样。
+ - 收藏和复制记录里原来那一条互不影响:原记录过期被清理、被删除、被清空,收藏都还在。
+ - 本机复制的文件也另存一份。之后改动、移动或删除原文件,收藏里的内容都不变。
+- **永远不会被自动清理**,不受「记录保留时间」和「文件保留时间」的限制。
+- **取消收藏就放回复制记录**:
+ - 这一条挪到复制记录的最上面,保留期从取消的那一刻重新计算。
+ - 点错了也找得回来,到复制记录里再点一下星标就行。
+- **收藏里没有「删除」**:真想删掉,就先取消收藏,再到复制记录里删除。
+- **「清空」**只清复制记录,和收藏无关。
+- **只在本机**:每台设备收藏自己的,不同步给其他设备。
+
+### 3.2 另存什么
+
+| 记录 | 怎么另存 |
+|---|---|
+| 文字、链接、网页格式 | 把全文复制到收藏里。内容完全相同的不重复收藏,只把已有的那条挪到收藏的最上面 |
+| 图片、从其他设备收到的文件 | 从缓存里复制。缓存和收藏在同一块磁盘上,用硬链接,不占额外空间,也不耗时 |
+| 本机复制的文件 | 从原文件复制。Mac 上用 APFS 的 clonefile,Linux 的 btrfs、XFS 上用 reflink:几乎瞬间完成,改原文件也不影响副本。用不上时整份复制,复制期间这一条显示「正在保存」 |
+| 只有元数据的大文件(`REMOTE_ONLY`) | 先在后台下载,不覆盖剪贴板(和预览下载一样),下载完再另存。下载失败时这条收藏照样留着,显示失败原因,可以重试 |
+| 已过期、已失败的图片和文件 | 不能收藏,内容已经不在本机了。文字只要还在列表里,就总能收藏 |
+
+- 整份复制超过 1 GB 时,先弹窗确认:「会在本机另存一份,占用 x GB」。能用硬链接、clonefile 或 reflink 的不弹。
+- 副本放在数据目录下的 `favorites/` 里,和 `cache/` 是并列的两个目录。不能放进 `cache/`:GC 会把 `cache/` 里不认识的文件夹当成孤儿,整个删掉。
+
+### 3.3 主窗口
+
+**侧边栏**:新增「收藏」,放在「复制记录」下面。
+
+```
+◆ 隔空贴
+ ◷ 复制记录 128
+ ☆ 收藏 12 ← 新增
+ ▭ 设备
+ ⚙ 设置
+```
+
+**复制记录页**:
+
+- 筛选从「全部 / 文字 / 图片 / 文件」变成「全部 / 文字 / 链接 / 图片 / 文件」(第 5 节)。
+- 鼠标悬停的那一行,操作按钮里多一个星标,放在「放进剪贴板」和「删除」旁边。
+ - 点亮星标:另存一份到收藏。
+ - 已收藏的行,不悬停时星标也一直亮着。再点一次就取消收藏,按第 3.1 节的规则处理。
+- 鼠标停留约 0.5 秒,弹出完整内容的提示框(第 4 节)。图片行原来「点一下打开预览」的行为不变。
+
+```
+复制记录 ⌫ 清空
+共 128 条 · 保留 3 天
+⌕ 搜索… [全部] 文字 链接 图片 文件
+────────────────────────────────────────────────────────────
+¶ 会议改到周四下午 3 点,地点不变 ← 鼠标悬停
+ 本机 · 刚刚 ☆ ⧉ ⌫
+↗ https://github.com/baiyuze/pasteferry
+ 本机 · 2 分钟前
+▣ 截图 14.32.png ★
+ 来自 Windows 台式机 · 1.2 MB · 5 分钟前
+```
+
+**收藏页**:
+
+- 布局和复制记录页一样:顶部是搜索和同样的五个筛选,下面是列表,按收藏时间倒序。
+- 每一行显示原来的复制时间、收藏时间和来源设备,不显示过期时间。
+- 每一行的操作只有两个:放进剪贴板、取消收藏。
+- 悬停提示框和复制记录页一样。
+- 取消收藏后,底部提示「已放回复制记录 · 撤销」。
+
+```
+收藏
+12 条 · 不会被自动清理 · 最多占用 86 MB
+⌕ 搜索收藏… [全部] 文字 链接 图片 文件
+────────────────────────────────────────────────────────────
+¶ 收货地址:上海市徐汇区漕溪北路 … ← 鼠标悬停
+ 本机 · 收藏于 10-18 ⧉ ★
+▣ 截图 14.32.png
+ 来自 Windows 台式机 · 1.2 MB · 收藏于 10-20
+▤ 营业执照.pdf
+ 本机 · 2.3 MB · 收藏于 10-02
+```
+
+### 3.4 快捷窗口里的收藏
+
+- 「收藏」是页签行的最后一个,按 Tab 切换过去。
+- 其他页签里,已收藏的条目带一个星标。
+- ⌘D / Ctrl+D,右键菜单里也有:
+ - 在其他页签里,收藏选中的条目;
+ - 在「收藏」里,取消收藏,条目放回复制记录。
+
+## 4. 悬停提示框
+
+快捷窗口、主窗口的「复制记录」页和「收藏」页,共用同一个提示框组件。
+
+- **出现**:鼠标在一行上停留约 0.5 秒时出现。移开就消失,移到别的行就换成那一行的内容。
+- **键盘**:用键盘上下移动时不弹出,免得一路闪。用键盘查看完整内容放在二期。
+- **内容**:
+ - **文字**:全文,保留换行。最多显示 15 行,超出的部分在末尾写「…… 共 3,482 字」。网页格式显示纯文本。
+ - **链接**:完整的网址,太长就折行。不联网抓网页标题和图标。
+ - **图片**:放大的预览图(最大约 360×240),下面是尺寸和大小。
+ - **文件**:所有文件名和各自的大小,最多列 10 个,其余写「还有 N 个」。本机复制的文件,还显示所在的文件夹。
+ - **没下载的大文件**:文件名和大小,再加一句「选中后先下载」。
+ - 最后一行都是来源设备、完整的复制时间,以及总大小或字数。
+- **位置**:画在窗口里面,放在这一行的下面,下面放不下就放到上面。
+ - 快捷窗口里也不画到窗口外面:Wayland 上程序不能自己决定窗口位置,画在窗口里面,三个平台的表现才一致。
+- **数据**:第一次悬停时才向后台服务请求完整内容(`GetClipDetail`,第 8.3 节),按记录 ID 缓存。图片的尺寸由界面解码时得到。
+
+文字的例子(快捷窗口里,提示框盖住了第 4–6 行):
+
+```
+╭──────────────────────────────────────────────────────╮
+│ ⌕ 搜索
+│ [全部] 文字 链接 图片 文件 收藏
+├──────────────────────────────────────────────────────┤
+│ 1 ¶ 会议改到周四下午 3 点,地点不变 · 刚刚
+│ 2 ↗ https://github.com/baiyuze/pasteferry · 2 分钟前
+│▌ 3 ¶ SELECT o.id, o.status, u.name FROM orders o … · 1 小时前 ← 鼠标停在这里
+│ ╭───────────────────────────────────────────────╮
+│ │ SELECT o.id, o.status, u.name
+│ │ FROM orders o
+│ │ JOIN users u ON u.id = o.user_id
+│ │ WHERE o.status = 'paid'
+│ │ AND o.created_at > now() - interval '7 days'
+│ │ ORDER BY o.created_at DESC;
+│ │ ─────────────────────────
+│ │ 本机 · 今天 13:05 · 186 字
+│ ╰───────────────────────────────────────────────╯
+│ 7 ¶ 收货地址:上海市徐汇区漕溪北路 … ★ · 昨天
+├──────────────────────────────────────────────────────┤
+│ ↩ 粘贴 ⇧↩ 纯文本 ⌘↩ 只复制 ⌘D 收藏 esc 关闭
+╰──────────────────────────────────────────────────────╯
+```
+
+图片和文件的提示框(只画提示框本身):
+
+```
+╭────────────────────────────────╮
+│ ┌────────────────────────────┐
+│ │ │
+│ │ (图片预览) │
+│ │ │
+│ └────────────────────────────┘
+│ 1920 × 1080 · 1.2 MB
+│ ─────────────────────────
+│ 来自 Windows 台式机 · 今天 14:32
+╰────────────────────────────────╯
+
+╭────────────────────────────────╮
+│ 合同扫描件.pdf 2.1 MB
+│ 补充协议.pdf 860 KB
+│ 签字页.jpg 1.4 MB
+│ ─────────────────────────
+│ 本机 · ~/Documents/合同 · 今天 10:12 · 共 4.3 MB
+╰────────────────────────────────╯
+```
+
+## 5. 类型筛选与链接
+
+- 主窗口的「复制记录」页、「收藏」页,以及快捷窗口,用同一组类型:**全部 · 文字 · 链接 · 图片 · 文件**。快捷窗口最后再多一个「收藏」页签。
+- 「文字」包括网页格式,但不包括链接。
+- **什么算链接**:去掉首尾空白后,整条文字就是一个 http(s) 网址,中间没有空格,也没有换行。一段话里夹着网址的,仍然算文字。
+- 链接行的图标用 `↗`,只显示网址本身。
+- 不联网抓网页标题和图标。Raycast 会抓,但要访问对方的网站,有隐私顾虑。
+- 判断在后台服务里做:记录入库时算好,存成一个字段。这样搜索时也能按链接筛选全部历史(第 8.1、8.3 节)。
+- 同类软件的做法见附录 A:支持按类型筛选的,大多数都单列了「链接」。
+
+## 6. 快捷窗口的架构
+
+```
+ 快捷键 ─▶ ┌─────────── 快捷窗口进程(常驻,平时隐藏)───────────┐
+ │ 原生外壳:全局快捷键、窗口、记下/还原前台窗口、模拟粘贴 │
+ │ Dart:列表、页签、搜索、按键、悬停提示框 │
+ └───────────────┬──────────────────────────────────┘
+ │ gRPC(与界面相同的本机端口与令牌)
+ ┌───────────────▼──────────────┐ gRPC ┌──────────────┐
+ │ 后台服务 pasteferryd │◀──────▶│ 界面(主窗口) │
+ │ 记录、收藏、剪贴板写入、配置 │ └──────────────┘
+ └──────────────────────────────┘
+```
+
+- 快捷窗口和界面是同一个 Dart 程序。`main()` 收到 `--picker` 参数时运行快捷窗口(`PickerApp`)。
+ - 复用 `daemon_client`、主题、多语言、缩略图,以及悬停提示框组件。
+- 界面和快捷窗口之间不直接通信,都经过后台服务:
+ - 设置写进 `Config`,快捷窗口订阅它的变化。
+ - 快捷窗口把状态报给后台服务(快捷键是否注册成功、能否自动粘贴),设置页再从后台服务读。
+
+### 6.1 各平台的进程形态
+
+- **Mac**:App 包里新增 `Contents/Helpers/PasteFerryPicker.app`,设置 LSUIElement,不在程序坞里出现。
+ - 包里只有一个很小的 Swift 可执行文件。Flutter 引擎和编译好的 Dart 代码,直接用主 App 的 `Contents/Frameworks/`:`FlutterDartProject(precompiledDartBundle:)` 指向主包里的 App.framework。安装包只多几百 KB(待验证)。
+ - 不能直接用主程序加参数运行:同一个包名已经在运行时,点程序坞图标,系统会去激活快捷窗口,主窗口就打不开了。
+ - 由界面登记第二个 LaunchAgent `com.pasteferry.picker`(RunAtLoad + KeepAlive),做法和后台服务相同。
+ - 不让后台服务直接拉起它:系统按拉起它的进程记辅助功能权限,那样授权列表里会显示成 PasteFerryDaemon。
+- **Windows**:同一个 `PasteFerry.exe --picker`。
+ - 单实例互斥量用 `Local\PasteFerry.Picker`。
+ - 窗口标题不能叫「PasteFerry」:主程序再次打开时,就是按这个标题找已有窗口的。
+ - 由后台服务拉起,放进一个 Job Object:后台服务退出时它也跟着结束,守护进程重启后台服务后再重新拉起。
+- **Linux**:同一个 `pasteferry --picker`。
+ - GApplication ID 用 `com.pasteferry.picker`,和主界面的 `com.pasteferry.app` 分开,两者互不激活。
+ - 由后台服务拉起,用 Pdeathsig 保证后台服务退出时它也结束。
+
+### 6.2 为什么不用别的做法
+
+- **按快捷键时再启动 Flutter**:冷启动要 0.5–1 秒,作为快捷键太慢。
+- **让主界面常驻,关窗口时只隐藏**:
+ - 改变了现在「关掉窗口就退出」的行为;
+ - 主界面的所有页面会一直占着内存;
+ - Mac 上还要处理程序坞图标的显示和隐藏。
+- **在 Go 后台服务里画原生窗口**:
+ - 要写三套原生界面;
+ - Linux 上的后台服务是纯 Go 的 X11 实现,没有字体渲染,也没有中文输入法;
+ - 界面代码出错,会把同步一起带崩。
+- **本方案的代价**:快捷窗口常驻,要占一份 Flutter 引擎的内存,预计几十 MB,原型阶段实测。关掉这个功能,这个进程就不运行。
+
+### 6.3 一次粘贴的过程
+
+1. 快捷窗口启动后连上后台服务,订阅事件流,在内存里保留最近 50 条记录、全部收藏和缩略图。这样呼出时不用临时查询。
+2. 按快捷键后:
+ - 原生外壳先记下当前的前台窗口:Mac 上是前台 App,Windows 上是 `GetForegroundWindow`,X11 上是 `_NET_ACTIVE_WINDOW`。
+ - 然后显示窗口,并通知 Dart 重置列表。
+3. 选中一条后:
+ - Dart 调用 `ApplyToClipboard`,由后台服务写剪贴板。已有的 `selfWrites` 机制保证这次写入不会生成新记录,也不会再同步给其他设备。
+ - 写入成功后,原生外壳隐藏窗口,还原焦点。
+ - 等目标窗口确实回到前台(最多等 300 ms),再模拟粘贴键。
+4. 写剪贴板的是后台服务,而不是快捷窗口,原因有两个:
+ - Linux X11 上,剪贴板的内容由持有它的进程提供。后台服务一直在运行,快捷窗口重启也不会让刚复制的内容失效。
+ - 三个平台写 HTML、图片、文件的格式转换,后台服务里都已经做好了。
+
+## 7. 各平台的实现
+
+### 7.1 macOS
+
+- **快捷键**:用 Carbon 的 `RegisterEventHotKey`,不需要任何权限。
+ - macOS 15 起,系统拒绝只用 ⌥ 或 ⌥⇧ 作修饰键的注册,返回 -9868。Apple 的说法是为了防止键盘记录。
+ - 不在沙盒里的 App 不受影响:2026-10-20 在 macOS 15.7.3 上实测,⌥V 能注册,也能触发(第 12 节第 1 条)。
+ - 如果确实受影响:⌥V 改用 CGEventTap 捕获。CGEventTap 需要辅助功能权限,而自动粘贴本来就需要这个权限。授权之前,默认快捷键退到 ⌃⌥V。
+- **窗口**:
+ - 用带 `.nonactivatingPanel` 的 `NSPanel`:它能接收键盘输入,但不会激活隔空贴,原来的 App 一直在前台,所以关窗口后不用还原焦点。聚焦搜索、Raycast 都是这样做的。
+ - 层级用 `.floating`;`collectionBehavior` 包含 `.canJoinAllSpaces` 和 `.fullScreenAuxiliary`,在全屏 App 上面也能出现。
+ - 背景用 `NSVisualEffectView` 毛玻璃,Flutter 视图设为透明。
+- **模拟粘贴**:用 `CGEventPost` 发送 ⌘V。
+ - 标志位只设 ⌘,用户还按着 ⌥ 时也不会带进去。
+ - 键码按当前键盘布局查找「v」所在的键:Dvorak 等布局下,它的物理位置和 QWERTY 不同。
+- **权限**:需要「隐私与安全性 → 辅助功能」。
+ - 用 `AXIsProcessTrusted()` 检查。没有授权时,快捷窗口底部显示提示,设置页有「去授权」按钮。
+ - 授权列表里显示的是 PasteFerryPicker.app,把它 Info.plist 里的显示名设为「隔空贴」。
+- **签名**:改用自签名证书(已定)。
+ - 现在发版用的是临时签名(`codesign --sign -`)。对临时签名的程序,系统按程序的哈希记录辅助功能授权,所以每次更新后授权就失效:列表里看起来还开着,实际不起作用,用户得删掉再重新添加。
+ - 改用自签名的代码签名证书后,系统按「包名 + 这张证书」记录授权,更新后仍然有效(**待验证**,第 12 节第 4 条)。
+ - 证书在这台 Mac 上生成,名称 `PasteFerry Code Signing`,有效期 20 年,私钥放在登录钥匙串里。
+ - 和更新签名私钥一样只在这台 Mac 上,也要同样备份。证书丢了只能换新的,所有用户都得重新授权一次。
+ - 整个 App 包都换成这张证书签名:PasteFerry.app、PasteFerryDaemon.app、PasteFerryPicker.app、pasteferry-cli。
+ - `scripts/build.sh` 和 `scripts/package.sh` 找得到这张证书就用它;找不到时(开发机、Codex)退回临时签名。
+ - Gatekeeper 不认自签名证书,所以首次打开的体验和现在的临时签名一样,不会更好,也不会更差。
+ - 换签名的那一版,后台服务已有的系统授权(本地网络等)可能要重新给一次(**待验证**)。之后的更新不会再丢授权。
+ - 发版规范(`.claude/rules/commits-and-releases.md`)第 6 步的核对加一条:用 `codesign -dv` 确认签名者是这张证书。
+- **输入法**:搜索框要能用中文输入法。Flutter 文本框放在非激活面板里,候选窗能不能正常出现,**待验证**。
+
+### 7.2 Windows
+
+- **快捷键**:`RegisterHotKey(hwnd, id, MOD_ALT | MOD_NOREPEAT, 'V')`,在快捷窗口自己的消息循环里接收 `WM_HOTKEY`。
+ - 快捷键已被其他程序占用时注册会失败,把这个结果报给设置页。
+- **窗口**:
+ - 样式用 `WS_POPUP`、`WS_EX_TOOLWINDOW`(不进任务栏,也不进 Alt+Tab)和 `WS_EX_TOPMOST`。
+ - Windows 11 上设置圆角(`DWMWA_WINDOW_CORNER_PREFERENCE`)。
+ - 收到 `WM_HOTKEY` 的进程可以把自己的窗口切到前台。
+ - 窗口一旦失去激活,就隐藏。
+- **还原焦点与粘贴**:
+ - 先 `SetForegroundWindow(原窗口)`,等 `GetForegroundWindow` 确实变回原窗口后,用 `SendInput` 发送 Ctrl+V。虚拟键码 `'V'` 与键盘布局无关。
+ - 如果用户还按着 Alt,先插入一个没有作用的按键,再释放 Alt。否则目标程序会把单独按下又松开的 Alt 当成「打开菜单」。AutoHotkey 也是这样处理的。
+- **管理员窗口**:系统不允许普通权限的程序向以管理员身份运行的窗口发送按键(UIPI),而且 `SendInput` 被拦下时不报错。所以粘贴前先检查目标进程是否以提升的权限运行(`OpenProcess` + `TokenElevation`)。如果是,就只放进剪贴板并提示。
+
+### 7.3 Linux(X11 会话)
+
+- **快捷键**:在根窗口上调用 `XGrabKey`,抓 Mod1 + v。
+ - 还要再抓加上 NumLock、CapsLock 的几种组合,否则开着数字锁定时快捷键不会触发。
+ - 快捷键已被占用时返回 BadAccess,把结果报给设置页。
+- **窗口**:无边框、不进任务栏、置顶的 GTK 窗口。
+ - 用 `gtk_window_present_with_time` 带上按键事件的时间戳,避免被窗口管理器的防抢焦点机制挡住。
+- **还原焦点与粘贴**:
+ - 先通过 `_NET_ACTIVE_WINDOW` 把焦点交还给原窗口,再用 XTest 发送 Ctrl+V。
+ - 终端里的粘贴键是 Ctrl+Shift+V。按原窗口的 `WM_CLASS` 识别常见终端:gnome-terminal、konsole、xfce4-terminal、tilix、kitty、alacritty、wezterm、terminator 等。
+- **依赖**:不需要额外的权限。GTK 外壳要链接 libX11 和 libXtst,.deb 要加上 `libxtst6` 依赖。
+
+### 7.4 Linux(Wayland 会话)
+
+在 Wayland 上,普通程序不能抓全局按键,不能模拟按键,也不能自己决定窗口的位置。
+
+- **快捷键**:自动判断用哪种方式。
+ - 桌面支持全局快捷键门户(GlobalShortcuts;GNOME 48 起、KDE Plasma 5.27 起)时,经 xdg-desktop-portal 注册。第一次注册时系统弹窗让用户确认或改键,以后也能在系统设置里改。
+ - 不支持门户时(例如 Ubuntu 24.04 的 GNOME 46),设置页提供「添加系统快捷键」按钮,在 GNOME 的自定义快捷键里写一条 `pasteferry --picker --toggle`。再次运行这个命令时,GApplication 会把它转交给已经在运行的快捷窗口,由它显示或收起,几乎没有延迟。
+ - 其他桌面显示手动设置的说明。
+- **粘贴**:首版只放进剪贴板,窗口底部写明「选中后按 Ctrl+V 粘贴」。以后可以评估两种做法:
+ - RemoteDesktop 门户:系统弹窗授权一次,可以记住;
+ - uinput:要装 udev 规则,相当于给程序全局注入按键的能力,倾向不做。
+- **焦点**:从门户或自定义快捷键呼出时,GNOME 的防抢焦点机制可能只弹出「隔空贴已就绪」的通知,而不把窗口提到前面。要用激活令牌(xdg-activation)解决。**待验证**。
+
+## 8. 后台服务与接口
+
+### 8.1 存储
+
+收藏和复制记录存在同一张 `clips` 表里,各占独立的一行。这样粘贴、图片预览、搜索、悬停详情这些逻辑,收藏都能直接用。
+
+- `clips` 表加四列,用现有的 `addColumnIfMissing` 给旧数据库补上:
+ - `favorite INTEGER NOT NULL DEFAULT 0`:这一行是收藏;
+ - `favorited_at INTEGER NOT NULL DEFAULT 0`:收藏时间;
+ - `source_clip_id TEXT NOT NULL DEFAULT ''`:从复制记录里哪一条收藏来的,用来给原记录点亮星标;
+ - `is_link INTEGER NOT NULL DEFAULT 0`:整条文字是一个网址。
+ - 入库时算好。
+ - 已有的文字记录在升级后第一次启动时补算一次,`meta` 表里记一个标记,以后不再重复。
+- 收藏行:
+ - `created_at` 保留原来的复制时间。
+ - `expires_at` 设成很远的将来,而不是 0,这样降级后也不会被立刻删掉(第 8.5 节)。
+ - `cache_path` 是相对于 `favorites/` 的路径。`favorites/` 由 `cache` 包另开一个根目录管理;`localPaths` 遇到收藏行,就去 `favorites/` 里找。
+- GC:
+ - `ExpiredClips` 和 `expireStaleCaches` 都跳过收藏行;
+ - 孤儿对账只管 `cache/`,不碰 `favorites/`;
+ - `favorites/` 自己也要对账:删掉没有收藏行引用的副本,用来从中途崩溃里恢复。
+- 查询:
+ - `ListClips` 和 `SearchClips` 加参数,指定查复制记录还是查收藏,以及是否只要链接。
+ - `DeleteAllClips` 只删复制记录。
+
+### 8.2 取消收藏的过程
+
+1. 如果复制记录里原来那一条(`source_clip_id`)还在,先删掉它,免得出现两条一样的。
+2. 把收藏行改回普通记录:
+ - `favorite` 清零;
+ - `created_at` 和 `expires_at` 改成「现在」和「现在 + 记录保留时间」,所以它出现在复制记录的最上面;
+ - 副本从 `favorites/` 挪进 `cache/`。两个目录在同一块磁盘上,用重命名完成,很快。
+3. 推送 `clip_updated`;如果第 1 步删了原记录,再推送 `clip_removed`。放回来的记录不会再发给其他设备。
+4. 撤销就是对这一条再执行一次收藏。
+
+### 8.3 接口(`daemon.proto`)
+
+```proto
+message Config {
+ // ...已有的 1–19...
+ // 快捷粘贴窗口。写成反向的:旧配置没有这一项时就是开启
+ bool quick_paste_disabled = 20;
+ // 快捷键,如 "alt+v"、"ctrl+alt+v"。空字符串表示默认:Mac 上 ⌥V,其他平台 Alt+V
+ string quick_paste_hotkey = 21;
+ // 选中后只放进剪贴板,不模拟粘贴
+ bool quick_paste_copy_only = 22;
+}
+
+message ClipRecord {
+ // ...已有的 1–13...
+ bool favorite = 14; // 这一条是收藏
+ bool favorited = 15; // 复制记录里的这一条已经收藏过,星标亮着
+ int64 favorited_at_unix = 16;
+ bool is_link = 17; // 整条文字是一个网址
+ // 收藏的 expires_at_unix 返回 0,表示不会过期
+}
+
+message ListHistoryRequest {
+ // ...已有的 1–4...
+ // true 时只返回收藏,按收藏时间倒序,不分页;false 时只返回复制记录,和现在一样
+ bool favorites = 5;
+ // 只返回链接。kind_filter 为 TEXT 时不含链接
+ bool links_only = 6;
+}
+
+message ApplyToClipboardRequest {
+ string clip_id = 1;
+ bool plain_text = 2; // 只写纯文本,去掉网页格式(⇧回车)
+}
+
+// DeleteHistoryRequest 不加字段:ids 和 all 只作用于复制记录;ids 里有收藏时返回 INVALID_ARGUMENT。
+// 更新期间旧版界面发来 all=true,也不会误删收藏。
+
+message SetFavoriteRequest {
+ string clip_id = 1; // 收藏时传复制记录的 ID;取消收藏时,传收藏的 ID 或原记录的 ID 都可以
+ bool favorite = 2;
+}
+
+message GetClipDetailRequest {
+ string clip_id = 1;
+}
+
+// ClipRecord 里的 text_preview 最多 120 个字,而且换行被压平了,不够在提示框里显示全文
+message ClipDetail {
+ string text = 1; // 文字的全文;网页格式给纯文本。最多返回前 4000 个字,保留换行
+ int32 text_length = 2; // 全文的字数
+ repeated string source_paths = 3; // 本机复制的文件在本机的完整路径
+}
+
+// 快捷窗口报给后台服务,设置页从后台服务读
+message QuickPasteStatus {
+ bool running = 1; // QuickPasteSession 连着
+ string hotkey_error = 2; // 空表示注册成功;in_use、invalid、unsupported,或平台给的原文
+ string hotkey = 3; // 实际生效的快捷键;Wayland 门户里是用户设定的组合
+ bool paste_available = 4; // 能否自动粘贴
+ string paste_unavailable_reason = 5; // not_trusted(Mac 未授权)、wayland、copy_only
+ string hotkey_source = 6; // native、portal、system_shortcut
+ string version = 7; // 快捷窗口的版本:App 更新后还在跑旧版的,界面让它重新启动
+}
+
+message QuickPasteCommand {
+ // request_permission、suspend_hotkey、resume_hotkey(设置页录制快捷键期间)、show
+ string command = 1;
+}
+
+message Event {
+ oneof payload {
+ // ...已有的 1–8...
+ Config config_changed = 9; // 快捷窗口据此重新注册快捷键
+ QuickPasteStatus quick_paste_changed = 10;
+ }
+}
+
+service DaemonService {
+ // ...
+ // 收藏时返回新的收藏记录,取消时返回放回复制记录的那一条。
+ // 过程中推送 clip_added / clip_updated / clip_removed。
+ // 已过期或已失败的图片、文件返回 FAILED_PRECONDITION
+ rpc SetFavorite(SetFavoriteRequest) returns (ClipRecord);
+ // 悬停提示框用
+ rpc GetClipDetail(GetClipDetailRequest) returns (ClipDetail);
+ // 快捷窗口进程启动后一直保持这个调用:往上报状态,往下收设置页的命令。
+ // 调用断开就当作快捷窗口没在运行,不用另外判断进程是否存活
+ rpc QuickPasteSession(stream QuickPasteStatus) returns (stream QuickPasteCommand);
+ rpc GetQuickPasteStatus(Empty) returns (QuickPasteStatus); // 设置页调用
+ rpc SendQuickPasteCommand(QuickPasteCommand) returns (Empty); // 设置页调用;快捷窗口没运行时 FAILED_PRECONDITION
+}
+```
+
+快捷窗口进程与原生外壳之间用 Flutter 的通道 `pasteferry/picker`,三个平台的方法相同,见 `ui/lib/picker/picker_host.dart`。
+
+### 8.4 快捷窗口进程的照看
+
+- Windows 和 Linux 上,后台服务按配置拉起或结束快捷窗口进程;它崩溃后过 10 秒重新拉起,和守护进程照看后台服务的做法一样。
+- Mac 上由 LaunchAgent 照看(第 6.1 节)。
+- 配置变化时推送 `config_changed`。
+
+### 8.5 降级
+
+用户手动装回旧版本时(自动更新只会升级,不会降级):
+
+- 旧版后台服务不认识新加的几列:
+ - 收藏会以普通记录的样子出现在复制记录里。因为 `expires_at` 在很远的将来,它们不会被清理。
+ - 旧版找不到 `favorites/` 里的副本,所以图片和文件类的收藏粘贴不了;文字类正常。
+- 再升级回新版后,一切恢复原样。
+
+## 9. 设置页
+
+**新增「快捷粘贴」一节**,现有的各节都不动:
+
+- 开关:快捷粘贴窗口,默认开启。
+ - 新安装和从旧版升级上来的都是开启的:配置项写成反向的 `quick_paste_disabled`,旧配置里没有这一项。
+ - 关闭后,快捷窗口进程不再运行,快捷键也随之注销。
+- 快捷键:显示当前的组合,点一下可以录制新的。注册失败时,在这一行下面用红字写明原因,例如「⌥V 已被其他程序占用,换一个组合」。
+- 选中后:直接粘贴 / 只放进剪贴板。
+- Mac:显示辅助功能权限的状态,以及「去授权」按钮。
+- Linux Wayland:显示门户里注册的快捷键(改键要去系统设置),或者「添加系统快捷键」按钮。
+
+示意(Mac):
+
+```
+快捷粘贴
+ 快捷粘贴窗口 [● 开]
+ 在任何程序里按快捷键呼出复制记录,选中即粘贴
+
+ 快捷键 [ ⌥V ] 点击录制
+ 选中后 ◉ 直接粘贴 ○ 只放进剪贴板
+ 辅助功能权限 未授权,授权后才能直接粘贴 [去授权]
+```
+
+**收藏占用的空间**:在「记录保留时间」和「文件保留时间」下面加一行说明:「收藏不受此限制,最多占用 xx MB」。
+
+- 由界面计算:把收藏的 `total_size` 加起来,不需要新接口。
+- 用硬链接、clonefile 或 reflink 保存的副本,实际占用比这个数小,所以写「最多」。
+
+## 10. 安装、更新与卸载
+
+- **Mac**:
+ - 界面首次启动或升级后,登记 `com.pasteferry.picker` 的 LaunchAgent,并和后台服务的 LaunchAgent 一起修复。
+ - 自动更新替换 App 后,要像后台服务一样对快捷窗口执行 `kickstart`。否则旧进程会继续运行旧代码;框架文件被替换后,还可能直接崩溃。
+- **Windows**:
+ - 快捷窗口运行的就是 `PasteFerry.exe`,运行期间这个文件被占用。
+ - 更新助手是按程序所在的文件夹找进程并结束的(`processInDir`),要确认快捷窗口也包括在内。
+ - 卸载程序同样要先结束它。
+- **Linux**:
+ - .deb 升级后,由后台服务重新拉起快捷窗口。
+ - 卸载脚本现在会结束后台服务,要加上结束快捷窗口。
+
+## 11. 默认快捷键与冲突
+
+默认快捷键按需求用 ⌥V / Alt+V,用户可以改。已知的冲突:
+
+- **Mac**:
+ - ⌥V 在 ABC / 美式键盘布局下输入「√」,注册后打不出这个字符。
+ - macOS 15 的限制见第 7.1 节。
+- **Windows**:
+ - Win+V 是系统自带的剪贴板历史,我们不占用。
+ - 在带传统菜单栏的程序里(比如记事本),Alt+V 打开「查看(V)」菜单。注册后,这些程序里就用不了这个菜单快捷键了。
+- **Linux**:
+ - GNOME 终端等程序里,Alt+V 是「查看(V)」菜单的助记符。
+ - Super+V 是 GNOME 的通知列表;KDE 的 Klipper 用 Meta+V。
+
+## 12. 原型阶段要先验证的
+
+1. macOS 15 / 26 上,不在沙盒里的 App 能否用 `RegisterEventHotKey` 注册 ⌥V。**已验证**:2026-10-20 在 macOS 15.7.3 上,注册返回 0,模拟按下 ⌥V 后回调被调用。macOS 26 还没测。
+2. Flutter 视图放在非激活的 NSPanel 里时,键盘输入和中文输入法的候选窗是否正常。
+3. PasteFerryPicker.app 共用主包的 Frameworks:能否正常启动,能否通过 `codesign --verify --deep --strict`。
+4. 签名方式对辅助功能授权的影响:
+ - 临时签名和自签名证书分别测试,更新后授权是否保留;
+ - 从临时签名换到自签名证书的那一版,本地网络等已有授权要不要重新给。
+5. 在 macOS 的剪贴板隐私机制下,模拟的 ⌘V 会不会被目标 App 当成用户自己按的粘贴,从而不弹「允许粘贴」。
+6. 三个平台上:快捷窗口常驻的内存占用;从按键到窗口出现的延迟,目标是 100 ms 以内。
+7. Windows:Alt+V 呼出后能否还原焦点,`SendInput` 能否粘贴。在这些程序里测试:记事本、Word、微信、浏览器、Windows Terminal,以及管理员命令行(应该降级为只放进剪贴板)。
+8. Linux:
+ - 在现有的 Ubuntu 24.04 GNOME Wayland 虚拟机上:用自定义快捷键呼出时,窗口能否拿到焦点。
+ - 同一台虚拟机的 X11 会话:`XGrabKey` 和 XTest 是否可用。
+ - GNOME 48+ 或 KDE 上的全局快捷键门户:需要新建虚拟机。
+9. 收藏的另存方式:Mac 上 clonefile、Linux 上 reflink 能否用;不能用时,能否正确退回整份复制。从缓存硬链接到 `favorites/`,在三个平台上是否都能用。
+
+## 13. 分阶段
+
+- **零期**:Mac 签名换成自签名证书(第 7.1 节),单独发一个补丁版 2.3.x。
+ - 换签名带来的一次性重新授权,不会和新功能挤在同一版里。
+ - 等自动粘贴发布时,签名已经固定,用户授予的辅助功能权限不会随更新失效。
+- **一期 A**:收藏、悬停提示框(主窗口)、类型筛选(含链接)。只改后台服务和主界面,不涉及原生代码。
+- **一期 B**:快捷粘贴窗口,先做第 12 节的验证。
+ - 包括第 2 节的全部交互,以及快捷窗口里的页签、收藏和悬停提示框。
+ - Mac、Windows、Linux X11 上自动粘贴;Wayland 上能呼出窗口,选中后只放进剪贴板。
+ - A、B 都做完后合在同一版发(已定)。
+- **二期**:
+ - 快捷窗口跟随文字光标的位置:Mac 用辅助功能 API,Windows 用 `GetGUIThreadInfo` 或 UI Automation;
+ - 用键盘也能看完整内容,比如按空格弹出选中那一行的提示框;
+ - 按住 Alt 连按 V 逐条往下移,松开 Alt 就粘贴;
+ - Wayland 上自动粘贴(RemoteDesktop 门户);
+ - 收藏同步到其他设备(需要在设备之间的协议里加消息);
+ - 收藏分组、手动排序,以及给收藏改名或加备注。
+
+## 14. 测试
+
+- **Go**:
+ - 配置的默认值:旧配置没有新字段时,快捷粘贴是开启的,快捷键是默认值;
+ - `ApplyToClipboard` 的纯文本写入;
+ - 快捷窗口进程的拉起和重启;
+ - 收藏:
+ - 原记录过期、删除、清空后,收藏还在,内容也能粘贴;
+ - 收藏本机文件后,改动或删除原文件,收藏里的内容不变;
+ - 取消收藏后,放到复制记录的最上面,保留期重新计算;原记录还在时不会出现两条;
+ - 内容相同的不重复收藏;
+ - 收藏 `REMOTE_ONLY` 记录时先下载再另存,而且不覆盖剪贴板;
+ - `favorites/` 的对账;
+ - 链接的判断:整条是网址才算;夹在一段话里的不算;首尾有空白的去掉后再判断;
+ - 旧数据库补列,以及 `is_link` 的一次性补算;
+ - 降级:用旧版的查询语句读新的数据库,收藏不会被当成过期记录;
+ - `GetClipDetail` 的截断与字数。
+- **Dart**(widget 测试,后台服务用假实现):
+ - 快捷窗口:
+ - 按键表里的每个按键;
+ - 数字键在搜索框为空和不为空时的不同行为;
+ - 页签切换,以及切换后重新编号、只在当前页签里搜索;
+ - `REMOTE_ONLY` 记录下载完后粘贴;
+ - 悬停提示框:停留多久才出现;文字超过 15 行时截断;下面放不下时改放上面;用键盘移动时不出现;
+ - 主窗口:
+ - 星标切换;
+ - 收藏页的筛选和搜索;
+ - 取消收藏后的撤销;
+ - 五个筛选项在最小窗口宽度下放得下。
+- **快捷键字符串**:`"alt+v"` 和 ⌥V / Alt+V 之间的解析与显示,Go 和 Dart 各写一份测试。
+- **手动测试矩阵**:第 12 节列出的平台和程序。
+
+## 15. 已定事项
+
+已定(2026-10-20):
+
+1. 快捷粘贴窗口默认开启,设置里可以关闭。
+2. Mac 先按 ⌥V 做原型。第 12 节第 1 条验证不通过,再在 ⌃⌥V 和其他组合里选。
+3. Mac 改用自签名证书签名,在零期单独发版。
+4. 保留数字键,列表前 9 条显示序号。
+5. 快捷窗口有页签筛选,鼠标悬停显示完整内容;主窗口的「复制记录」页、「收藏」页也有悬停提示框。
+6. 收藏时另存一份,包括本机复制的文件。
+7. 取消收藏就放回复制记录的最上面;收藏里没有删除;「清空」不影响收藏。
+8. 收藏是侧边栏里单独的一项。
+9. 收藏只在本机,不同步。
+10. 加「链接」这一类(第 5 节),理由见附录 A。
+11. 一期 A、B 都做完再发。
+
+## 附录 A:同类软件的类型筛选
+
+| 软件 | 能否按类型筛选 | 有没有「链接」 |
+|---|---|---|
+| Raycast 剪贴板历史(Mac、Windows) | 能,按 ⌘P 选类型 | 有:文字、图片、文件、链接、邮箱、颜色 |
+| Paste(Mac) | 能,可按类型、App、日期、设备筛选 | 有 |
+| Copy 'Em、PastePal、ClipBook、Clipfinity、Supaste | 能 | 有 |
+| Freepaste(开源,仿 Paste) | 搜索框下一排标签,Tab / ⇧Tab 切换 | 有:全部、置顶、文字、链接、图片、文件、颜色 |
+| CopyQ | 用标签页自己分 | 每一行用图标标出是不是网址,没有现成的筛选 |
+| Ditto(Windows) | 能,按文字、图片、文件、网页格式筛选 | 没有,只能用正则搜 `https?://` |
+| Maccy | 不能按类型筛选,只能搜索 | 没有 |
+| Windows 自带的 Win+V | 不能筛选 | 没有 |
+
+- 支持按类型筛选的软件,大多数都单列了「链接」,Raycast 和 Paste 这两个最主流的都有。
+- 没有「链接」的几个,要么根本不能按类型筛选,要么是老牌的 Windows 工具。
+
+## 参考
+
+- [Apple 开发者论坛:macOS Sequoia 上 RegisterEventHotKey 不接受只有 ⌥ 的组合](https://developer.apple.com/forums/thread/763878)
+- [Shottr:Sequoia 与 ⌥ 快捷键(提到非沙盒 App 似乎不受影响)](https://shottr.cc/kb/sequoia)
+- [sindresorhus/KeyboardShortcuts#176](https://github.com/sindresorhus/KeyboardShortcuts/issues/176)
+- [GNOME Discourse:GNOME 48 起的全局快捷键](https://discourse.gnome.org/t/how-do-you-enable-disable-global-shortcuts-in-gnome-48/29119)
+- [ArchWiki:XDG Desktop Portal 各后端支持的门户](https://wiki.archlinux.org/title/XDG_Desktop_Portal)
+- [Raycast 手册:Clipboard History](https://manual.raycast.com/clipboard-history)
+- [Raycast:Clipboard History 功能页](https://www.raycast.com/core-features/clipboard-history)
+- [Paste(App Store)](https://apps.apple.com/us/app/paste-limitless-clipboard/id967805235)
+- [Freepaste](https://github.com/bluehatkeem/freepaste)
+- [ClipBook](https://clipbook.app/)
+- [Clipfinity](https://clipfinity.app/)
+- [Supaste](https://www.supaste.com/)
+- [Maccy](https://github.com/p0deje/Maccy)、[Maccy #206](https://github.com/p0deje/Maccy/issues/206)
+- [Ditto](https://github.com/sabrogden/Ditto)
+- [CopyQ](https://copyq.net/)