中文 | English

Clipboard

Clipboard 是一个原生 macOS 剪贴板管理器，使用 SwiftPM、SwiftUI、AppKit 和 SQLite 构建。

当前状态是 public beta，最新发布版本 v0.3.1（2026-08-03，通过 Homebrew cask clipboardapp 与 GitHub release 分发）。它已经适合给熟悉 macOS 辅助功能权限和自签名 App 安装流程的开发者/尝鲜用户日常使用；还不是面向陌生大众用户的 notarized 稳定版。

各版本变更见 CHANGELOG.md。使用 v0.3.0 的用户请升级到 v0.3.1：v0.3.0 在打包机以外的机器上打开快捷面板会闪退，v0.3.1 已修复。

当前可用能力

• 中英双语界面：语言跟随系统，也可在 系统设置→通用→语言与地区 为本 App 单独设置语言。
• GitHub 主题：暗色采用 GitHub Soft Dark、浅色采用 GitHub Light（Primer 官方配色），随外观模式（跟随系统/强制亮色/强制暗色）切换。
• 菜单栏 App，默认不显示 Dock 图标；设置窗口打开期间临时显示 Dock 图标与 Command+Tab 条目，便于切走后找回，关闭设置后恢复纯菜单栏形态。
• 通过菜单栏图标或 Command+Shift+V 打开 QuickPanel（快捷键可自定义）。
• 模糊搜索：按字符子序列匹配（中文可用），完整子串命中优先排序，列表行内命中字符高亮。
• 键盘导航、Tab 类型过滤循环、来源 App 图标、Command+Y 详情预览。
• 支持文本、富文本、链接、图片、文件 URL 历史。
• 历史排序可选：最近复制（默认）/ 首次复制 / 复制次数。
• 支持自动粘贴模式和仅复制模式；可选"粘贴后保留面板"用于连续粘贴多条到不同目标 App。
• 支持 Option+Shift+Enter 对文本、链接、富文本执行无格式粘贴。
• 支持数字快捷键选择或粘贴当前可见记录。
• 开机自启（SMAppService 登录项，状态与系统设置实时同步）。
• 菜单栏图标快捷操作：Option+点击 暂停/恢复采集（暂停时图标变化），Option+Shift+点击 忽略下一次复制。
• 使用 SQLite 持久化历史记录。
• 支持置顶、删除、清除历史和 payload 清理。
• 支持基础隐私控制：暂停采集、忽略下一次复制、忽略剪贴板类型、忽略来源 App、可选忽略 Universal Clipboard。
• 已有 Maccy / Clipaste 导入代码路径和自动化覆盖。
• 通过 Homebrew tap 分发稳定自签名构建，升级走 brew update && brew upgrade（同证书版本间辅助功能权限保持；v0.3.0 起更换了签名证书，从 v0.2.x 升级需重新授权一次，v0.3.0 → v0.3.1 为同一证书、权限保持）。

详细验收矩阵和历史记录见 docs/manual-acceptance-checklist.md。

当前限制

• 公开分发包尚未使用 Developer ID 签名和 notarization；通过 Homebrew 安装时 cask postflight 会移除 quarantine（信任本 tap 的前提下无 Gatekeeper 首开拦截），直接下载 zip 仍需手动处理 Gatekeeper 提示。
• 自动粘贴依赖 macOS 辅助功能权限；未授权时仅复制模式仍可把记录写入剪贴板，但不会模拟 Command+V。
• 开机自启在 ad-hoc 签名的开发构建下不可靠（签名身份不稳定），请使用发布包或稳定自签名构建。
• 部分手工验收仍未完成：Intel/多系统版本矩阵、外接显示器、部分来源 App 采集（微信/飞书/Word/Pages/远程桌面）、超大内容长时间性能观察；brew uninstall --zap 仅在干净测试机验收（可选项）。Universal Clipboard 与主要失败状态 UI 已于 v0.3.0 验收周期覆盖。
• 项目定位是开源 public beta：功能与文档已面向公开用户，但仍非 notarized 的商业化成熟产品。

环境要求

• macOS 14 或更新版本。
• Xcode 或 Xcode Command Line Tools，支持 Swift 5.10。
• Apple Silicon 是当前主要验证环境；Intel 覆盖仍在手工验收清单中跟踪。

安装

推荐使用 Homebrew:

brew tap anlostsheep/clipboard
brew install --cask clipboardapp

本 cask 在安装后通过 postflight 移除 quarantine 属性,App 直接打开,不会遇到 Gatekeeper 首次打开拦截(尽管本构建是自签名、未公证)。这会绕过 Gatekeeper 对该 App 的校验,前提是你 信任本 tap。

更新:

brew update && brew upgrade --cask clipboardapp

brew update 不能省:它会先刷新本地的 tap 副本。省略时 Homebrew 只比对本地缓存的 cask, 即使已有新版本发布,也可能报告"已经是最新版"。

不使用 Homebrew 时,也可以从发布包安装。

从发布包安装

如果已经有 release zip：

1. 解压 ClipboardApp.app。

2. 移动到 /Applications。

3. 首次打开时使用 Finder 右键 -> Open，或在终端清除 quarantine：

   xattr -dr com.apple.quarantine /Applications/ClipboardApp.app
   open /Applications/ClipboardApp.app

4. 按提示在系统设置中授予辅助功能权限。

5. 运行快速检查：

   swift run ClipboardManualProbe accessibility

授权后期望输出：

accessibility: authorized

更完整的安装、更新和卸载说明见 docs/install.md。

从源码构建

克隆仓库后运行：

swift build
swift test

主验证门禁：

Scripts/verify.sh

该脚本会运行：

• swift test
• swift build
• Scripts/test-automation.sh

构建本地 App 包：

CODE_SIGN_IDENTITY=- Scripts/build-app-bundle.sh
open .build/app-bundles/release/ClipboardApp.app

ad-hoc 签名适合本地开发，但代码变化后 macOS 可能要求重新确认辅助功能权限。

稳定自签名构建

给小范围 beta 用户分发时，建议使用稳定自签名流程：

Scripts/setup-self-signed-signing.sh

CODE_SIGN_KEYCHAIN="$HOME/Library/Keychains/clipboard-signing.keychain-db" \
LOCAL_CODE_SIGN_IDENTITY="ClipboardApp Local Code Signing" \
REQUIRE_STABLE_CODE_SIGNING=1 \
Scripts/build-app-bundle.sh

验证签名：

codesign -dv --verbose=4 .build/app-bundles/release/ClipboardApp.app

期望包含：

Authority=ClipboardApp Local Code Signing

更多说明见 docs/release-signing.md。

无付费发布流程

不购买 Apple Developer Program 时，推荐发布稳定自签名 zip 和 SHA-256 校验文件：

VERSION=0.3.1 Scripts/package-release.sh

产物默认写入 dist/：

ClipboardApp-v0.3.1-macos.zip
ClipboardApp-v0.3.1-macos.zip.sha256

该流程不能消除 Gatekeeper 首次打开提示，但能把构建、签名检查、打包和校验文件生成固定下来。维护者流程见 docs/release-process.md。

手工探针

ClipboardManualProbe 是真实剪贴板和隐私策略的轻量诊断工具：

swift run ClipboardManualProbe self-check
swift run ClipboardManualProbe accessibility
swift run ClipboardManualProbe read-once

常用隐私策略检查：

swift run ClipboardManualProbe policy-universal-ignore
swift run ClipboardManualProbe policy-ignore-type com.example.secret
swift run ClipboardManualProbe policy-ignore-app com.example.Passwords

隐私模型

Clipboard 只在本机读取系统剪贴板，并把历史记录保存在本机。

• 元数据：~/Library/Application Support/<bundle-id>/clipboard.sqlite
• 大 payload：~/Library/Application Support/<bundle-id>/payloads/
• 导入报告：~/Library/Application Support/<bundle-id>/imports/reports/
• 偏好设置：macOS UserDefaults
• 当前代码库不使用网络 API。

默认隐私过滤会忽略常见 concealed / transient pasteboard types，包括部分 1Password 相关剪贴板标记。用户可以暂停采集、忽略下一次复制、忽略 Universal Clipboard、添加忽略剪贴板类型，以及添加忽略来源 App bundle id。

剪贴板历史可能包含敏感数据。提交 issue、PR、截图、日志、benchmark 报告或数据库文件前，必须先确认其中没有真实隐私内容。

项目结构

Sources/ClipboardApp              macOS App、QuickPanel、设置页、状态栏
Sources/ClipboardCore             模型、存储、导入、隐私、粘贴逻辑
Sources/ClipboardPlatform         NSPasteboard 和 macOS 平台桥接
Sources/ClipboardManualProbe      手工剪贴板和隐私探针
Sources/ClipboardBenchmarkProbe   benchmark 报告生成器
Tests/                            Core、App、Platform 的 XCTest 覆盖
Scripts/                          验证、签名、benchmark、性能辅助脚本
docs/                             发布签名、验收清单、设计和计划文档

截图

QuickPanel（多类型历史 + 置顶 + GitHub Soft Dark 主题）

菜单栏图标与面板弹出位置

English 界面

设置 → 通用

设置 → 隐私

辅助功能权限引导

截图使用演示数据采集，不包含真实敏感剪贴板内容。

发布前验证

发布 beta 包前至少运行：

git diff --check
VERSION=0.3.1 Scripts/package-release.sh
cd dist
shasum -a 256 -c ClipboardApp-v0.3.1-macos.zip.sha256

然后更新 docs/manual-acceptance-checklist.md 中对应的手工验收记录。

贡献

见 CONTRIBUTING.md。

安全

见 SECURITY.md。不要在 issue 或 PR 中提交剪贴板数据库、payload 文件、导入报告、私有签名材料或包含真实剪贴板内容的截图。

License

Apache License 2.0. See LICENSE.