全文搜索
加密历史的查询入口、支持的语法、索引生命周期。
UniClipboard 给本地剪贴历史维护了一份 加密的全文搜索索引，"存在本地"和"存得安全"两件事是同时成立的。索引在磁盘上加密，密钥与历史数据库共用一套，详见 同步内容 — 本地存储。
在哪里搜
| 入口 | 当前状态 / 适用场景 |
|---|---|
| 历史页面 | 应用内主入口。 历史视图现在是落地页，其搜索框把自由文本与「内容类型 / 来源设备 / 时间」筛选揉在一起，接入下文同一套查询服务。 |
| 快捷面板 | 全局热键、键盘流的快速入口。即时筛选、复合筛选筹码。详见 快捷面板 |
uniclip search CLI | 脚本、SSH、远程会话。详见 CLI — 搜索 |
查询语法
快捷面板的高级搜索和历史页面的搜索框共用同一套 token 语法，CLI 则用等价的 flag 跑同样的查询 —— 所以下面这些筛选三处都能用：在两个界面搜索框里写成 type: / ext: / # 这类 token，在 CLI 里则是 --type / --ext / --tag 等 flag。
子串匹配
不带任何前缀的 token 都会被当作大小写无关的子串过滤条件。多个 token 之间是 AND：
报告 v2
project meeting notes排序基于 BM25 相关度，不是按时间。需要时间序请改用时间筛选（见下文）。
类型过滤 type:
type:text 邀请
type:richtext 邮件正文
type:image 截图
type:file invoice等价于快捷面板顶部的类型筹码、CLI 的 --type。可选值：text / richtext / image / file。richtext 对应 HTML / 富文本内容，是独立的物理内容类别。网页链接与像源码的片段不是物理类型，而是标签（#link / #code，见下文）。
扩展名过滤 ext:
ext:pdf 合同
ext:ts useReducer只对 文件类 负载生效（基于文件名后缀）。CLI 等价是 --ext。
时间范围
面板里通过下拉选预设（今天 / 近 7 天 / 本月 等），CLI 中用 --from-ms / --to-ms 指定毫秒时间戳：
uniclip search "报告" \
--from-ms 1710000000000 \
--to-ms 1710100000000来源设备过滤
把结果收窄到来自某一台设备的内容 —— 可以是配对的电脑，也可以是 mobile-sync 的手机。在历史页面的搜索框或快捷面板里，从筛选栏选一台设备，或输入 from: 再从列表里挑。在 CLI 里用 --source-device 指定设备名（大小写无关）或设备 id，可重复多次以匹配多台设备。运行 uniclip members 可查看可用的设备名。
标签过滤 #
把结果收窄到带某个内容标签的内容。标签在条目入索引时自动派生：
#link—— 内容里含网页 URL。#code—— 看起来像源代码的纯文本。（富文本 / HTML 是物理类型type:richtext，不属于这个标签。）
历史页面的搜索框和快捷面板都支持 # 标签 —— 输入 # 再从列表里挑。CLI 也能通过 uniclip search --tag 用同样的标签筛选。
不 支持的语法
下列在很多搜索框里习以为常的特性，UniClipboard 当前不支持：
- 引号短语（
"exact phrase"）—— 引号被当作普通字符处理。 - 布尔操作符（
AND/OR/NOT）——OR会被当成子串。 - 通配符 / 正则 —— 同上。
- 在内容类型之间做布尔组合（如 "text 或 link"）。
需要更复杂的查询时，建议把 --detailed --json 输出导出，再在外部脚本里过滤。
索引生命周期
索引随守护进程启动而打开，复制的内容在进入加密历史的同时就会被分词并加索引，对查询结果是 接近实时 的可见。但有几个时刻你会显式碰到它：
首次启动 / 大版本升级后
索引可能处在"重建中"状态。
- GUI：设置 → 存储 → 搜索索引 区域显示当前状态（就绪 / 重建中 / 不可用）、上次重建时间、
重建按钮。 - CLI：
uniclip search status给出同样的状态字段。
手动重建
少数情况下索引会和历史漂出一致（最常见：进程在写索引时被 SIGKILL）。
被中断的重建现在会在守护进程下次启动时（例如重新打开应用）自动续上，所以多数情况下无需手动点重建 —— 除非你不想等一次重启。
- GUI：上面那个
重建按钮，点了之后状态变"重建中"，每 2 秒轮询一次直到结束。 - CLI：
uniclip search rebuild是同步命令 —— 直到重建完成才返回，便于脚本里抓诊断快照。
重建过程中查询不会失败，只是返回的结果集合在补齐之前是不完整的。
损坏修复
索引文件结构受损（极罕见，比如磁盘错误）时，单纯重建可能起不来。删除数据目录下的索引子目录、再 rebuild 即可重新从历史构建一份。剪贴历史本身存在另一个文件，不会受影响。
详见 故障排查 — 搜索与索引。
隐私
- 索引文件在磁盘上加密，密钥放在系统密钥环，与历史数据库共用 KEK / MasterKey。
- 索引 不离开本机，也不参与跨设备同步。每台设备搜索的是本机看到过的内容。
- 这意味着新加入的设备搜不到加入前的历史 —— 这是 快速开始 — 加入不回填历史 那一行设计的直接后果。
查不到内容怎么办
按可能性从大到小：
- 拼写或大小写问题。直接换个更短的 token 试试 —— 子串匹配对噪音敏感。
- 时间过滤太窄。把时间下拉切回 不限 再说。
- 该条目在历史保留策略里被 GC 了。看 设置 — 存储 里的最大条目数 / 保留天数，确认还在窗口里。
- 该条目压根没同步过来 —— 看 设备 — 内容类型白名单 是否在发送端被挡掉。
- 索引尚未就绪。看 GUI 的状态指示灯，或跑
uniclip search status。