内容
<p align="center">
<img src="Clipth/Assets.xcassets/AppLogo.imageset/AppLogo@2x.png" width="96" alt="Clipth logo" />
</p>
<h1 align="center">Clipth</h1>
<p align="center">
<strong>English</strong> · <a href="README.zh-CN.md">中文</a>
</p>
<p align="center">
面向 macOS 的本地剪贴板历史管理器及 AI 工具。
</p>
<p align="center">
<a href="https://wavever.github.io/Clipth/"><img src="https://img.shields.io/badge/website-clipth-7AA487" alt="Website" /></a>
<a href="https://github.com/wavever/Clipth/actions/workflows/ci.yml"><img src="https://github.com/wavever/Clipth/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://github.com/wavever/Clipth/releases/latest"><img src="https://img.shields.io/github/v/release/wavever/Clipth" alt="Latest release" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT License" /></a>
<img src="https://img.shields.io/badge/macOS-14%2B-blue" alt="macOS 14+" />
</p>
Clipth 是一款开源的 macOS 剪贴板管理器，具备离线语义搜索功能，并内置 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器。它允许您在本地搜索剪贴板历史，组织有用的剪贴内容，并可选地让 AI 客户端（如 Claude Desktop、Claude Code 或 Cursor）查询您的剪贴板。云同步功能默认关闭，仅在您配置的目标上连接。
该名称源自“剪贴路径”：您复制的内容轨迹。
## 为什么选择 Clipth？
- **默认本地优先** - 剪贴板历史、OCR 文本、标签和嵌入式内容保留在您的 Mac 上，除非您明确启用加密同步。
- **冲突恢复的加密同步** - 可选地通过 iCloud Drive、WebDAV、S3 兼容存储或本地文件夹同步，而不暴露剪贴板明文。
- **离线语义搜索** - Apple `NLEmbedding` 支持基于语义的搜索，无需托管嵌入式 API。
- **AI 原生工作流** - 应用程序二进制文件可以作为 MCP stdio 服务器运行，配备可搜索和可写的剪贴板工具。
- **原生 macOS 实用程序** - 菜单栏应用程序、全局热键、快速粘贴、预览、代码片段和 SwiftUI 界面。
- **内容保护** - 默认情况下，敏感值（如电话号码和 API 密钥）在整个 UI、导出和 MCP 中被编辑，而原始内容仍在您的 Mac 上保留以供重复使用。
- **隐私控制** - 暂停捕获、排除源应用程序、忽略敏感剪贴板标记、剥离 URL 跟踪器、禁用 MCP 工具和删除历史。
## 亮点：加密同步，合并而非覆盖
Clipth 不会用另一台 Mac 的整个数据库替换一个 Mac 的数据库。它会发送加密的增量操作，独立合并每个字段，并在两个设备更改不可合并的内容时保留可恢复的副本。
选择自动同步或手动同步。主窗口始终显示一个紧凑的同步状态：当自动化关闭时单击同步，显示进行中的进度指示器，并在运行完成时提供明确的成功或失败反馈。
| 情况 | Clipth 如何保护它 |
|---|---|
| 两台 Mac 编辑不同的字段 | 混合逻辑时钟和字段版本保留两个更改 |
| 两个设备同时写入 | 不变的加密日志在快照竞争中幸存 |
| 标签或组隶属关系独立更改 | 收敛集合并组合添加并保留删除 |
| 设备返回带有过期数据 | 认可的墓碑防止已删除的剪辑无声重新出现 |
所有内容都使用 AES-256-GCM 在本地加密，然后再传输到 iCloud Drive、WebDAV、S3 兼容存储或您选择的同步文件夹。丢失的版本保留为加密冲突副本，保留 30 天，同时旧日志和孤立附件被谨慎地清理。 [阅读同步架构 →](docs/sync-architecture.md)
## 预览
<p align="center">
<img src="docs/assets/screenshot-main.png" alt="主窗口" width="720" />
<br/>
<em>主窗口 - 历史记录、全文和语义搜索、标签</em>
</p>
<p align="center">
<img src="docs/assets/screenshot-stats.png" alt="活动统计" width="720" />
<br/>
<em>活动统计 - 每日计数和年度热图</em>
</p>
<p align="center">
<img src="docs/assets/screenshot-mcp.png" alt="MCP 集成" width="720" />
<br/>
<em>MCP 服务器 - 连接 Claude Desktop、Claude Code 或 Cursor</em>
</p>
## 功能
### 捕获和重用
- 自动捕获文本、图像、视频、文件、URL 和富文本
- 双击将条目复制回剪贴板
- 重复刷新保留重新复制的项目在顶部，而不是创建重复项
- 可选的粘贴为纯文本和尾部空格修剪
- 软删除回收站，支持恢复、永久删除和保留控制
- 主窗口和代码片段的全局热键
- 高效的图像存储 — 剪贴板图像保持压缩状态，使用外部二进制存储，因此即使图像历史记录很长，内存和磁盘使用量仍然很低
- 在列表和网格布局之间切换：主窗口使用响应式网格，而快速粘贴和菜单栏面板提供独立配置的双列网格，位于设置中。网格图像预览保留其纵横比，并显示图像名称作为就地叠加。
### 搜索和组织
- 具有类型过滤器的全文搜索
- 文本和 OCR 内容的离线语义搜索
- 源应用程序和时间过滤器，例如 `app:Safari`、`since:2d` 和 `before:2026-05-01`
- 收藏、固定剪辑、标签、自定义标题和标签自动完成
- 相同类型的剪辑的多选合并
### 内容感知
- 丰富的预览弹出窗口
- 图像的 OCR 索引
- 时间戳、Base64 和 JSON 的智能文本解析
- 视频预览，带有缩略图或内联播放器模式
- URL 跟踪参数剥离，用于 `utm_*`、`fbclid`、`gclid` 等
- 应用程序窗口的屏幕录制隐藏模式
### 内容保护
- 自动、谨慎地编辑敏感字段：中国大陆电话号码 (`13812345678` → `138****5678`) 和 API 密钥、令牌、机密和密码 — 标记值，例如 `appkey=…` 加上高置信度前缀，如 `sk-`、`ghp_`、`AKIA`
- 仅遮蔽敏感值，同时保留周围的标签和结构；谨慎到足以让 UUID、哈希、时间戳和普通 URL 保持不变
- 在历史记录列表、预览、菜单栏、动态岛、快速粘贴、快速查找和搜索代码片段中，以及在保护剪辑上的锁定徽章中，显示编辑后的内容
- 存储的原始值从未被修改；复制、快速粘贴、粘贴为纯文本和编辑仍然使用原始剪辑
- 默认导出和 MCP 响应返回编辑后的内容，带有 `isProtected` 元数据；原始出口需要明确选择加入
- 设置中的主开关和一个可编辑的规则列表 → 隐私：内置的电话/应用密钥规则可以编辑、重置或关闭，以及您自己的关键字或正则表达式规则
### 导出和统计
- 具有类型、日期、收藏和固定过滤器的 JSON 导出
- 按原始格式导出单个项目，例如文本和 PNG
- 复制统计数据、14 天图表和 GitHub 样式的年度热图
### 加密同步
- 通过 iCloud Drive、WebDAV、S3 兼容的对象存储或本地文件夹（包括 Dropbox、OneDrive、Syncthing 和网络驱动器管理的目录）的可选双向同步
- 具有紧凑的主窗口状态、即时进度反馈和明确的成功或失败通知的手动或自动同步
- 在数据离开 Mac 之前使用 AES-256-GCM 端到端加密；WebDAV 密码、S3 机密凭据和 256 位恢复密钥存储在 Keychain 中
- 混合逻辑时钟合并独立编辑的字段；标签和组隶属关系使用收敛集合并，而丢失的内容作为 30 天的冲突副本保留
- 加密增量日志保护并发写入者，并压缩为条件写入快照；确认删除的墓碑、旧日志和孤立附件被谨慎地垃圾回收
- 同步历史记录、图像、标签、组、收藏、固定、回收站状态和单个文件附件（高达 25 MB）；设备设置、统计数据和语义向量保留本地
- 另一台 Mac 需要相同的恢复密钥。丢失它将使现有的远程数据无法恢复。
- 现有 v1 清单在下一次成功同步时在本地升级；恢复密钥被重用，远程 `.clipth-sync-v1` 位置对于 Clipth 版本保持稳定。
- 有关合并、提交、迁移和保留不变式的详细信息，请参见 [同步架构](docs/sync-architecture.md)。
## MCP 服务器
应用程序二进制文件兼作 MCP stdio 服务器。配置兼容的客户端：
```json
{
"mcpServers": {
"clipboard": {
"command": "/Applications/Clipth.app/Contents/MacOS/Clipth",
"args": ["--mcp"]
}
}
}
```
可用工具：
| 工具 | 描述 |
|---|---|
| `search_clipboard` | 剪贴板历史的关键字或语义搜索 |
| `list_recent` | 列出最近的条目，可选按类型过滤 |
| `get_clip` | 通过 UUID 获取具有完整内容和元数据的条目 |
| `list_tags` | 列出所有标签和使用计数 |
| `list_recent_activity` | 列出自 ISO 日期或相对时间（如 `30m`、`2h`、`3d`、`1w`）以来添加的条目 |
| `tag_clip` / `untag_clip` | 添加或删除标签 |
| `favorite_clip` / `pin_clip` | 更新收藏或固定状态 |
| `delete_clip` / `restore_clip` | 软删除、永久删除或恢复条目 |
| `create_snippet` | 创建具有可选标题和标签的代码片段 |
受保护的剪辑在 MCP 响应中默认被编辑，并带有 `isProtected` 元数据；返回原始受保护内容需要在设置 → 隐私中明确选择加入。在为敏感工作流启用 MCP 之前，请阅读 [PRIVACY.md](PRIVACY.md)。
## 安装
从 [GitHub Releases](https://github.com/wavever/Clipth/releases/latest) 下载最新的 DMG，打开它，然后将 Clipth 拖到 Applications。
当前公共版本使用稳定的自签名身份签名，因此 macOS 可以在更新之间保持辅助功能权限。公共 notarization 在路线图中。如果 macOS 阻止下载的构建，您可以使用未签名本地签名禁用构建。
## 系统要求
- macOS 14.0 Sonoma 或更高版本
- 推荐使用 Xcode 16.0 或更高版本进行开发
## 从源代码构建
在 Xcode 中打开 `Clipth.xcodeproj`，选择“My Mac”，然后运行。
命令行：
```bash
xcodebuild \
-project Clipth.xcodeproj \
-scheme Clipth \
-configuration Debug \
-destination 'platform=macOS' \
-derivedDataPath build \
-skipMacroValidation \
CODE_SIGN_IDENTITY="-" \
CODE_SIGNING_REQUIRED=NO \
CODE_SIGNING_ALLOWED=NO \
build
```
### 维护者的代码签名
版本使用稳定的自签名证书，因此 macOS 可以在重建和更新之间保持辅助功能权限。没有稳定的签名标识，权限可能会在每次构建后失效，即使系统设置切换仍然启用。
运行一次以创建和安装证书：
```bash
scripts/generate-signing-cert.sh
```
脚本打印 `SIGNING_CERT_P12_BASE64` 和 `SIGNING_CERT_PASSWORD` 值作为 GitHub Actions 机密。
## 快捷键
| 快捷键 | 操作 |
|---|---|
| `⌘⇧V` | 打开主窗口 |
| `⌘,` | 打开设置 |
| `⌘N` | 新建代码片段 |
| `⌘⏎` | 在代码片段编辑器中保存 |
| `Esc` | 取消预览、返回或取消编辑 |
## 项目文档
- [隐私](PRIVACY.md)
- [安全策略](SECURITY.md)
- [贡献](CONTRIBUTING.md)
- [路线图](ROADMAP.md)
- [行为准则](CODE_OF_CONDUCT.md)
## 贡献
欢迎提出问题和拉取请求。良好的起点包括文档、本土化、MCP 资源/提示、URL 净化器测试、搜索解析器测试和隐私润色。
在贡献之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。有关私人安全或隐私报告，请遵循 [SECURITY.md](SECURITY.md)。
## 许可证
Clipth 在 [MIT License](LICENSE) 下发布。
