内容
<p align="center">
<img src="ClipTrace/Assets.xcassets/AppLogo.imageset/AppLogo@2x.png" width="96" alt="ClipTrace logo" />
</p>
<h1 align="center">ClipTrace</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/ClipTrace/"><img src="https://img.shields.io/badge/website-cliptrace-7AA487" alt="Website" /></a>
<a href="https://github.com/wavever/ClipTrace/actions/workflows/ci.yml"><img src="https://github.com/wavever/ClipTrace/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://github.com/wavever/ClipTrace/releases/latest"><img src="https://img.shields.io/github/v/release/wavever/ClipTrace" 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>
ClipTrace是一款开源的macOS剪贴板管理器，具有离线语义搜索和内置的Model Context Protocol服务器。它允许您在本地搜索剪贴板历史，组织有用的剪辑，并可选地让AI客户端（如Claude Desktop、Claude Code或Cursor）查询您的剪贴板，而无需将其上传到云服务。
## 为什么选择ClipTrace？
- **本地优先** - 剪贴板历史、OCR文本、标签和嵌入式内容都存储在您的Mac上。
- **离线语义搜索** - Apple的`NLEmbedding`支持基于含义的搜索，无需托管嵌入式API。
- **AI原生工作流** - 应用程序二进制文件可以作为MCP_stdio服务器运行，带有可搜索和可写入的剪贴板工具。
- **原生macOS实用程序** - 菜单栏应用程序、全局热键、快速粘贴、预览、片段和SwiftUI界面。
- **内容保护** - 默认情况下，敏感值（如电话号码和API密钥）会在UI、导出和MCP中被编辑，而原始内容仍在您的Mac上可用于重复使用。
- **隐私控制** - 暂停捕获、排除源应用程序、忽略敏感剪贴板标记、剥离URL跟踪器、禁用MCP工具和删除历史记录。
## 预览
<p align="center">
<img src="docs/assets/screenshot-main.png" alt="Main window" width="720" />
<br/>
<em>主窗口 - 历史记录、全文搜索和语义搜索、标签</em>
</p>
<p align="center">
<img src="docs/assets/screenshot-stats.png" alt="Activity stats" width="720" />
<br/>
<em>活动统计 - 每日计数和年度热图</em>
</p>
<p align="center">
<img src="docs/assets/screenshot-mcp.png" alt="MCP integration" 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样式的年度热图
## MCP服务器
应用程序二进制文件兼作MCP_stdio服务器。使用以下配置兼容的客户端：
```json
{
"mcpServers": {
"clipboard": {
"command": "/Applications/ClipTrace.app/Contents/MacOS/ClipTrace",
"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仍然可以将其他剪贴板内容暴露给您配置的客户端 - 在启用适用于敏感工作流的MCP之前，请阅读[PRIVACY.md](PRIVACY.md)。
## 安装
从[GitHub Releases](https://github.com/wavever/ClipTrace/releases/latest)下载最新的DMG，打开它，然后将ClipTrace拖到应用程序文件夹。
当前公共版本使用稳定的自签名身份签名，因此macOS可以在更新之间保持辅助功能权限。公共证明是路线图上的内容。如果macOS阻止下载的构建，您可以从源代码构建并禁用_unsigned本地签名。
## 系统需求
- macOS 14.0 Sonoma或更高版本
- Xcode 16.0或更高版本（推荐用于开发）
## 从源代码构建
在Xcode中打开`ClipTrace.xcodeproj`，选择“My Mac”，然后运行。
命令行：
```bash
xcodebuild \
-project ClipTrace.xcodeproj \
-scheme ClipTrace \
-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 secrets。
## 快捷键
| 快捷键 | 操作 |
|---|---|
| `⌘⇧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)。
## 许可证
ClipTrace在[MIT License](LICENSE)下发布。
