# ClipTrace TODO

来源:2026-05-27 对 Maccy / Paste / Pastebot / Raycast / Alfred / CopyQ / VeloxClip 的功能对标。
完成一项就把 `- [ ]` 改成 `- [x]`,需要的话在条目下补一行实施备注。
工作量:S < 1 天,M 1–3 天,L 3+ 天,XL 超过一周。

---

## 对标定位

| 产品 | 它领先在哪儿 | 我们位置 |
|---|---|---|
| Maccy (OSS) | 极简、敏感剪贴板内容自动忽略、Cmd+⇧+C 快开 | 功能更全;敏感内容拦截不完整 |
| Paste (订阅) | Pinboards / 共享白板、iCloud 同步、Apple Intelligence OCR 搜索、Power Search 过滤器 | 单设备、无同步;OCR 索引未做 |
| Pastebot (买断) | 过滤器 / 文本变换链、顺序粘贴 (paste stack)、按 app 过滤 | 我们有合并,缺变换链和粘贴栈 |
| Raycast | 自然语言 Ask Clipboard、按时间区间批删、来源 app 检测可靠、Paste as… | 语义搜索我们也有(且离线);批量 / 时间区间没做 |
| Alfred | Snippet 自动展开(打字触发)、占位符 `{clipboard:N}` / `{cursor}` | 片段只能手动 |
| CopyQ (OSS) | ECMAScript 脚本钩子、加密 Tab、文件夹同步 | 我们用 MCP 做了"现代版脚本接口" |
| VeloxClip | AI 翻译 / 摘要 / 解释代码 | 没做;但 MCP 已能间接做 |
| 我们独占 | URL 跟踪参数剥离(28+)、智能解析(时间戳 / Base64 / JSON)、GitHub 风格热力图、本地 MCP server、软删除回收站 | 别人都没有这套组合 |

---

## P0 — 基本盘漏洞 / 高价值低成本

- [x] **P0-1 敏感剪贴板内容自动忽略** (S)
  - 现状:`ClipboardMonitor.swift` 只看 `changeCount`,不检查 `org.nspasteboard.ConcealedType` / `Transient` / `AutoGenerated`,1Password / Keychain / 银行 OTP 都会被记录。
  - 改:`pollClipboard()` 类型分支前先读 `pasteboard.types`,命中任一即跳过。约 10 行。
  - 影响 README 隐私章节的"诚信度"。
  - 实施:`ClipboardMonitor.swift` 新增 `concealedMarkerTypes` 集(`org.nspasteboard.*` + `com.apple.is-sensitive`),`checkForChanges` 在内部写检查之后立即跳过命中项。

- [x] **P0-2 "粘贴为纯文本"快捷键** (S)
  - 现状:无入口;grep 无 `stripFormatting` / `asPlainText`。
  - 改:QuickPasteView + MenuBarView 行操作加 `⌥⏎` / `⌥⇧⏎`,只写 `.string` 类型,rtf/file 回退到文本。
  - 实施:VM 新增 `copyAsPlainText` + RTF 转纯文本;主列表 / 菜单栏右键加「粘贴为纯文本 ⌥⌘C」;QuickPanel 在按下 commit key 时检测 ⌥,把 plainText flag 传给 `QuickPasteController.writePasteboard`。

- [x] **P0-3 OCR 文本入索引,不再"只能手动看"** (M)
  - 现状:`OCRService` 仅在 `OCRResultView` 按需触发,识别结果未存进 `ClipboardItem`,搜索看不见。
  - 改:`ClipboardItem` 加 `var ocrText: String?`;图片入库时后台异步 OCR,结果回写 + backfill 进语义索引;搜索文本拼上 `ocrText`。
  - 这是 Paste 在 2025-11 主打的差异点,补完即拉平。
  - 实施:模型新增 `ocrText`;新图入库后 `Task` 调用 `OCRService.recognize` 并把识别结果作为 embedding 源;VM 新增 `backfillOCR`,启动时与 `backfillEmbeddings` 并行;`keywordMatchScore`(VM + MCPServer)纳入 `ocrText`,`backfillEmbeddings` 不再跳过有 OCR 的图片。

- [x] **P0-4 来源 app + 时间区间进主搜索栏** (S)
  - 现状:`sourceApp` / `sourceBundleId` 已经存了(`ClipboardMonitor.swift:73-82`),但搜索只能按类型筛;时间区间只在导出面板里有。
  - 改:搜索栏 token 解析支持 `app:vscode` `since:2d` `before:2026-05-01`,复用现成字段,不动 schema。
  - 实施:VM 末尾新增 `ClipboardSearchTokens.parse`,识别 `app:`、`since:`(`m/h/d/w`)和 `before:`(相对或 ISO 日期);`filteredItems` 在交给关键字 / 语义引擎前先剥离这些 token。tooltip 同步更新。

- [x] **P0-5 批量删除"最近 N 分钟"** (S)
  - 现状:只有单条 / 全部。
  - 改:菜单加 "Clear last…" → 5min / 15min / 1h / today,软删进 trash。Raycast / Alfred 都有。
  - 实施:VM 新增 `clearLastMinutes` / `clearToday`(尊重 `trashEnabled`,跳过 pin / favorite);工具栏垃圾桶图标改成 `ToolbarTrashMenu`,主操作仍打开垃圾桶,下拉菜单露出 5/15/60 分钟 + 今日 + 打开垃圾桶,并配 toast。

- [x] **P0-6 列表行加自定义标题 (rename clip)** (S)
  - 现状:无 `customTitle` 字段。
  - 改:`ClipboardItem` 加 `var customTitle: String?`,右键 Rename;列表 / QuickPaste / MCP 优先显示 customTitle。长 URL / token 一眼能认。
  - 实施:模型新增 `customTitle` + `effectiveCustomTitle`;VM 新增 `rename`;主行 / 菜单栏行 / QuickPaste 行展示与排序优先用 customTitle,关键字搜索同上;`MainWindowView` 加 `RenameClipSheet` 与右键 Rename;MCP `get_clip` 输出 `Title`。

---

## P1 — 差异化深耕

- [ ] **P1-1 粘贴栈 (sequential paste)** (M)
  - 多选条目 → 进入"粘贴栈"模式 → 后续每次 `⌘V` 依序输出下一条。
  - Pastebot 招牌、Paste 也有。和"多选合并"互补:合并 = 一条新条目,栈 = 分多次粘贴。
  - `AutoPasteService.swift` 已经在了,扩一个队列状态机即可。

- [ ] **P1-2 文本变换链 (paste filters)** (M)
  - Pastebot 招牌:UPPERCASE / lowercase / slugify / URL encode / strip HTML / 去 BOM …,可链式组合,`⇧⏎` 触发。
  - 把现有的 `URLSanitizer.swift` 抽象成 `TextTransform` 协议 + 一组实现 + 粘贴时挑选 UI。

- [ ] **P1-3 Snippet 占位符 + 自动展开** (M~L)
  - 现状 `SnippetEditorView` 是纯文本。补:
    - `{cursor}` 粘贴后光标定位
    - `{clipboard:0..N}` 引用最近 N 条
    - `{date:yyyy-MM-dd}` / `{uuid}`
    - 可选"打字触发":输入框监听 `abbr`,Accessibility 替换。免费做即差异化。
  - 权衡:需要 Accessibility 权限 + 键盘事件 hook,维护成本不低。

- [ ] **P1-4 MCP server 扩展工具集** (S~M) ★ 我们最大护城河
  - 现状只有 `search_clipboard / list_recent / get_clip` 三个只读工具。补:
    - [x] `tag_clip(id, tags[])` / `untag_clip`
    - [x] `favorite_clip(id, bool)` / `pin_clip(id, bool)`
    - [x] `delete_clip(id, soft?)` / `restore_clip`
    - [x] `create_snippet(content, title?, tags?)`
    - [x] `list_tags()` / `list_recent_activity(since)`(给 LLM 写报告用)
    - [ ] 暴露 MCP **resources** 列出 favorites / pinned / by-tag,LLM 一次拿一组而不是逐条 get。
    - [ ] 暴露 **prompts**:`/clipboard-summary`、`/find-the-link-i-copied-yesterday`。
  - 实施(2026-06-01):`MCPServer.swift` 新增 7 个写工具 + 2 个读工具,共 12 个;`publicTools` 名录 + 本地化 desc 同步,Settings → MCP 自动列出。写操作通过各自 `@MainActor` handler 落库,`tag_clip` 与现有标签大小写去重合并,`untag_clip` 大小写匹配移除,`delete_clip` 默认软删进回收站(`soft:false` 彻底删),`restore_clip` 保留原 `createdAt`(API 不像 GUI 那样浮顶),`create_snippet` 同步 embed 以便即时语义检索。`list_recent_activity` 的 `since` 支持 ISO 8601 与相对量(`m/h/d/w`)。
  - **跨进程局限**:MCP 是独立 `--mcp` 进程,写入即落 SQLite,但已打开的 GUI 窗口在下次 refetch(重启 / 搜索 / 滚动刷新)前不会实时反映。实时跨进程刷新另开任务。
  - 剩余:resources + prompts 两项协议面未做。

- [ ] **P1-5 复制变更直接观察,降低轮询依赖** (S)
  - 现状:`Timer.scheduledTimer` 1.0s 轮询(`SettingsPanelView.swift:12`),Raycast v2 已经"直接监听变更",快速连续复制不会漏。
  - 改:兜底轮询保留,默认间隔从 1s 降到 250–500ms;changeCount 去重保护 CPU。
  - 副作用:解决"快速 `⌘C` 两次只记录一次"潜在 bug。

- [ ] **P1-6 Tags 升级为侧栏"集合 / Pinboards"** (S)
  - 现状有 tags,缺 Paste 那种"项目 A / 研究 / 旅行"的侧栏分组视图。
  - 改:左侧加固定侧栏 "Tags",每 tag 一个可点的过滤项;pin / favorite 之外加 Tag 区。零数据迁移。

- [ ] **P1-7 重复复制累计 + "最常复用"统计** (S)
  - 现状:重复复制会浮顶并刷新时间。
  - 优化:加 `var copyCount: Int` + `var lastCopiedAt: Date`,`createdAt` 不动。统计面板能画"最常复用的 10 条"。

---

## P2 — 大方向,需要更多确认才动

- [ ] **P2-1 iCloud / 端到端可选同步** (L)
  - 用户群两极化,做了要给"完全禁用"开关。优先用 `NSPersistentCloudKitContainer`。先听用户呼声。

- [ ] **P2-2 iOS 配套 app** (XL)
  - 收益大但摊子大;延后到 macOS 端稳定。

- [ ] **P2-3 内置"用 AI 处理这条"** (M)
  - 右键加 Translate / Summarize / Rewrite,走 macOS 26 的 Apple Foundation Models(完全离线、零成本)。比接外部 LLM 更契合我们的离线主张。

- [ ] **P2-4 加密"私密"条目** (M)
  - 类 CopyQ 加密 tab。Lock 标记 → Keychain 派生 key 加密落盘 → 访问需 Touch ID。

- [ ] **P2-5 URL 条目自动抓取 OG / favicon 缩略图** (S)
  - Raycast v2 的"社交卡片预览",纯本地缓存。不联网档位下跳过。

- [ ] **P2-6 Shortcuts.app 集成** (S~M)
  - App Intent:`Get latest clip` / `Get clip at index` / `Append to clipboard`。Paste / Maccy 都做了。

---

## 可靠性 / 维护性

- [ ] **审计 `FileHandle.write(_:)` 与 NSException 易触发点** (S)
  - MCP 路径已修(`eaf86e4`);`ExportService` 等地方 grep 一遍。

- [ ] **验证 `pollInterval` 默认值** (S)
  - 当前默认已调为 0.5s。实测 CPU 后再决定是否开放 0.25s。

- [ ] **SwiftData schema 迁移测试** (M)
  - `copyCount` / `customTitle` / `ocrText` 加字段时不踩坑。

- [ ] **大图复制内存峰值** (M)
  - 当前 `imageData: Data?` 直接进 SwiftData,大图可改"落盘 + 引用"。Maccy 这次大改也是为这个。

---

## 建议起手次序

1. P0-1(敏感内容拦截) — 一小时事,做完隐私章节实至名归。
2. P0-2(粘贴为纯文本) + P0-5(批删 N 分钟) — 半天打包。
3. P0-3(OCR 入索引) — 独立 PR,搜索体感提升最显著。
4. P1-4(MCP 工具扩展) — 差异化护城河,优先级高过任何"追赶项"。

---

## Sources

- [Maccy on GitHub](https://github.com/p0deje/Maccy)
- [Paste – pasteapp.io](https://pasteapp.io/)
- [Paste updates / Power Search & Apple Intelligence](https://pasteapp.io/updates)
- [Pastebot – tapbots.com](https://tapbots.com/pastebot/)
- [Pastebot reborn (MacStories)](https://www.macstories.net/reviews/pastebot-reborn-as-a-powerful-mac-clipboard-manager/)
- [Raycast Clipboard History manual](https://manual.raycast.com/clipboard-history)
- [Raycast v2 What's New](https://manual.raycast.com/new-in-v2)
- [Alfred Clipboard History](https://www.alfredapp.com/help/features/clipboard/)
- [Alfred Snippets & auto-expansion](https://www.alfredapp.com/help/features/snippets/)
- [CopyQ](https://hluk.github.io/CopyQ/)
- [CopyQ scripting API](https://copyq.readthedocs.io/en/latest/scripting-api.html)
- [VeloxClip — AI clipboard with OCR / semantic](https://ilikebug.github.io/VeloxClip/)
- [Best Mac clipboard managers 2026 (TextExpander)](https://textexpander.com/blog/best-clipboard-managers)
- [Clipboard Manager Comparison 2026 (QuietClip)](https://quietclip.app/blog/clipboard-manager-comparison/)
