Ditto 剪贴板管理器：Windows 剪贴板历史扩展的原理与实战指南

导读

Ditto 是标准 Windows 剪贴板的扩展工具：你复制到剪贴板的每一份内容都会被它保存到本地数据库，之后可以随时调取、搜索并重新粘贴。本文以仓库根目录 ReadMe.md 为核心骨架，结合 src/ 下的源码实现，系统讲解 Ditto 的安装方式、基本用法、底层剪贴板监听原理、数据存储机制与常用配置项，帮助你不仅会用，还能理解它"为什么能记住剪贴板"。

1. Ditto 是什么

按官方文档的定义：Ditto 是标准 Windows 剪贴板的扩展。它保存每一个放入剪贴板的条目，使你能在之后的任意时间访问其中任何一条；并且支持保存任意类型的剪贴板数据——文本、图片、HTML 以及自定义格式。

从仓库结构看，Ditto 是一个基于 MFC 的 Windows 桌面应用，核心工程位于 src/，主入口为 src/CP_Main.cpp。项目还自带了 SQLite（src/sqlite/）、zlib 压缩库（src/zlib/）、QR 码生成（src/QRCode/）与 ChaiScript 脚本引擎（src/chaiscript/），后者用于支撑复制时的脚本处理能力。

1.1 本地优先（Local First）

官方文档明确列出了 Ditto 的三个特性承诺：

• 无需登录（No login）
• 无云端（No cloud）
• 无遥测（No telemetry）

也就是说，Ditto 的所有剪贴板历史都保存在本机，不需要账号，不依赖云服务，也不会上传使用数据。

1.2 代码签名策略

文档同时说明：Ditto 的 Windows 二进制免费代码签名由 SignPath.io 提供，证书由 SignPath Foundation 签发。这是仓库内官方声明的内容，方便用户在下载安装时核对签名信息。

2. 安装方式

官方文档给出了 6 种安装途径，覆盖最常见的分发渠道：

方式	说明	安装命令 / 入口
安装包	官方发布的 exe 安装程序（DittoSetup）	运行安装程序即可
便携版	ZIP 形式的绿色版，解压即用	解压 DittoPortable_*.zip
Chocolatey	Windows 包管理器安装	choco install ditto
Chocolatey 便携版	Chocolatey 安装便携版	choco install ditto.portable
Winget	Windows 自带包管理器	winget install -e --id Ditto.Ditto
Microsoft Store	商店版应用（Ditto-CP）	商店内搜索 Ditto

仓库内对应的安装相关资源包括：DittoSetup 目录下的安装脚本工程（DittoSetup/，内含 *.iss 安装脚本与 BuildPortableZIP.bat）、Chocolatey 打包配置（DittoSetup/Chocolatey/ditto.nuspec）以及 Windows 应用商店的 appx 打包文件（DittoSetup/appx/appxmanifest.xml）。

3. 基本用法

官方文档给出的使用流程只有四步，这也是 Ditto 的核心操作闭环：

1. 运行 Ditto：启动后 Ditto 常驻系统托盘，静默监听剪贴板；
2. 复制内容到剪贴板：例如在文本编辑器里选中文字后按 Ctrl-C；
3. 打开 Ditto：点击系统托盘图标，或按下默认热键 Ctrl + ``（Ctrl 加反引号/波浪号键，即键盘左上角 ~` 键）；
4. 粘贴到上一个窗口：在列表中对目标条目双击，或按回车键，即可将其粘贴回之前活动的窗口。

这套流程背后对应两条核心链路：剪贴板监听（自动保存复制内容）与热键唤起（弹出历史列表）。下面结合源码分别深入展开。

4. 原理一：剪贴板监听与保存链路

4.1 监听机制：从 SetClipboardViewer 到 AddClipboardFormatListener

Ditto 通过 src/ClipboardViewer.cpp 中的 CClipboardViewer 类完成剪贴板监听。该类在创建时（OnCreate）即建立连接，并根据系统版本选择两种监听方式（src/ClipboardViewer.cpp）：

• 在 Vista 及更新系统上，优先动态加载 USER32.dll 中的 AddClipboardFormatListener，通过 WM_CLIPBOARDUPDATE 消息感知剪贴板变化；
• 若该 API 不可用，则回退到经典的 SetClipboardViewer() 剪贴板查看器链，接收 WM_DRAWCLIPBOARD 消息，并在 OnDrawClipboard 中把事件转发给链上的下一个查看器（src/ClipboardViewer.cpp）。

为保证长期运行不掉线，Connect() 会设置一个每 5 分钟触发一次的保活定时器（TIMER_ENSURE_VIEWER_IN_CHAIN，见 src/ClipboardViewer.cpp），定时通过写入专用 Ping 格式来确认剪贴板链仍然通畅。

4.2 过滤与节流：避免无意义的保存

监听事件到达后并不会立即入库，而是经过多层过滤：

• 忽略自身产生的变更：Ditto 定义了自己的私有剪贴板格式 m_cfIgnoreClipboard（"Clipboard Viewer Ignore"，注册于 src/CP_Main.cpp），当它自己执行粘贴、把内容写回剪贴板时会附带该格式，GetIgnoreClipboardChange() 检测到后直接忽略（src/ClipboardViewer.cpp），从而避免"保存-粘贴-再保存"的死循环；
• 去抖延迟：收到 WM_DRAWCLIPBOARD 后先启动 TIMER_DRAW_CLIPBOARD 定时器，默认延迟 100 ms（配置项 ProcessDrawClipboardDelay，见 src/Options.cpp）；
• 防连击过滤：同一时刻内多次快速复制会被合并，默认仅在距上次复制超过 500 ms（配置项 SaveClipDelay，见 src/Options.cpp）时才保存，用于过滤诸如拖拽窗口、切换程序时产生的"假复制"；
• 按应用过滤：ValidActiveWnd() 通过 GetClipboardOwner() 与前台窗口识别来源进程，再与用户配置的"包含/排除应用"通配符列表匹配，决定是否保存（src/ClipboardViewer.cpp）。

4.3 数据抓取：支持任意剪贴板格式

过滤通过后，CClip::LoadFromClipboard（src/Clip.cpp）开始抓取数据：它通过 OLE 数据对象附加到剪贴板，读取 CF_UNICODETEXT / CF_TEXT 生成描述文本，并保存文本、图片、HTML 及各类自定义格式——这正是官方文档所说"保存任意类型剪贴板数据"的实现支撑。

值得注意的细节：当检测到第三方设置 ExcludeClipboardContentFromMonitorProcessing（Win10 剪贴板历史的排除标志）且用户开启"Enforce clipboard ignore formats"时，Ditto 也会遵循该标志跳过保存；若检测到 CanIncludeInClipboardHistory = 0，同样跳过（src/Clip.cpp）。

5. 原理二：热键唤起与快速粘贴

5.1 全局热键的注册与分发

Ditto 的热键体系在 src/HotKeys.h 与 src/HotKeys.cpp 中实现。CHotKey 封装单个热键，核心字段 m_Key 的高字节存修饰键、低字节存虚拟键码；Register() 最终调用 Win32 API RegisterHotKey() 注册系统级热键（src/HotKeys.cpp），注册前还会用临时 Atom 调用 ValidateHotKey 做冲突预检（src/HotKeys.cpp）。

默认热键在 src/CP_Main.cpp 中创建：m_pDittoHotKey 的默认键值为 704，源码注释明确标注 "704 is ctrl-tilda"，即 Ctrl + ``，与官方文档描述的默认值完全一致。此外还有用于直接粘贴列表前 10 条记录的 Position1~Position10` 热键。

热键消息统一由 CMainFrame::OnHotKey 分发（src/MainFrm.cpp）：

• 若热键触发时修饰键（Ctrl/Shift）仍被按住，则仅移动列表选中项，待松开后自动粘贴；
• 若 Ditto 窗口已处于顶层且配置了 m_HideDittoOnHotKeyIfAlreadyShown，则隐藏窗口（再次按热键即收起）；
• 否则显示快速粘贴窗口，并记录当前活动窗口作为粘贴目标。

5.2 粘贴的完整调用链

从双击条目到内容进入目标窗口，调用链为：

1. CMainFrame::PasteOrShowGroup（src/MainFrm.cpp）：先查询数据库判断条目是否为分组，若为普通剪贴条目则构造 CProcessPaste；
2. CProcessPaste::DoPaste（src/ProcessPaste.cpp）：将选中内容渲染到 OLE 数据源、写回剪贴板（同时附带"忽略"标志防止被自己再次保存），然后调用 theApp.m_activeWnd.SendPaste() 向前一活动窗口发送粘贴命令。

用户还可以为任意条目单独设置全局热键（GlobalClip: %d，见 src/CP_Main.cpp）：之后无论在任何程序中，按下该热键都能立即粘贴这条内容；分组条目也支持"再按一次"的双击式热键，用于把当前选中内容直接存入该分组（见 src/MainFrm.cpp）。

6. 原理三：本地数据库存储

Ditto 的数据存储在 SQLite 数据库中，默认库名为 Ditto.db（定义于 src/DatabaseUtilities.h），打开逻辑在 src/DatabaseUtilities.cpp，SQLite 引擎来自仓库自带的 src/sqlite/（内含 CppSQLite3 封装与 SQLite 加密扩展 sqlite3mc_amalgamation.c）。

这也是"Local First"承诺的落地体现：所有历史数据只存在于本机数据库文件，不依赖任何云账号。Ditto 同时提供多数据库切换能力（src/SelectDB.cpp），并支持在"通用选项"中开启数据库自动清理（PRAGMA auto_vacuum = 1，见 src/AdvGeneral.cpp）。

7. 实用配置与扩展能力

7.1 与保存行为相关的关键配置

综合源码中的默认值与官方设置面板，与"保存剪贴板"直接相关的配置有：

配置项	默认值	作用
SaveClipDelay	500 ms	两次复制时间间隔低于此值视为假复制，不保存
ProcessDrawClipboardDelay	100 ms	收到剪贴板变化消息后延迟处理的时间
Enforce clipboard ignore formats	关	是否尊重第三方应用设置的剪贴板排除标志
包含/排除应用列表	空	通过通配符指定只保存/不保存哪些应用产生的复制

以上默认值均可从 src/Options.cpp 的 GetProfileLong 调用中核实。

7.2 可深入学习的仓库资源

若想继续深入，仓库内值得阅读的关联模块包括：

• 多语言与主题：Debug/Language/ 下 31 种语言的 XML 翻译文件，Debug/Themes/ 下的多种配色主题；
• 插件机制：Addins/ 目录内的 DittoUtil 工具集（如"粘贴为纯文本"PasteAnyAsText、"去除换行"RemoveLineFeeds、SelectPasteFormat 等），以及 src/DittoAddin.cpp 中的插件加载框架；
• 脚本能力：基于 ChaiScript 的复制/粘贴脚本（src/DittoChaiScript.cpp、src/ChaiScriptOnCopy.cpp），可在复制事件发生时执行自定义逻辑；
• 网络传输：SendSocket/RecieveSocket（src/SendSocket.cpp、src/RecieveSocket.cpp）实现的多机剪贴板共享。

8. 结语

Ditto 的价值不在于复杂，而在于把"剪贴板历史"这件事做到了本地、快速且格式完备。读完本文，你应该已经掌握：如何安装与通过四步操作完成复制-唤起-粘贴闭环、剪贴板监听与防自触发过滤的底层实现、热键体系的注册与分发逻辑，以及 SQLite 本地存储的"Local First"设计。以此为线索，可以继续沿 src/ 源码深入探索插件、脚本与网络共享等进阶能力。