Clipth: Instructions file for Codex

AGENT.md

给 AI 助手（以及人类）在本仓库工作时的指引。构建、发布、改 UI 之前先读这份。

这是什么

剪迹 / Clipth —— 原生 macOS 菜单栏剪贴板管理器。

• SwiftUI + SwiftData (SQLite)，macOS 14.0+，Swift 5（Xcode 16）。
• Bundle id com.wavever.clipth；仓库 wavever/Clipth。
• 默认本地 / 离线：语义搜索用 Apple NLEmbedding，OCR 用 Vision，本地 MCP 服务走 stdio。无遥测；网络仅用于 Sparkle 更新检查和用户主动配置的端到端加密同步 （iCloud 云盘 / WebDAV / 本地同步文件夹）。
• 依赖（SPM）：Sparkle（自动更新）、KeyboardShortcuts（全局快捷键）。

目录结构

Clipth/
  Models/       SwiftData @Model 类型 + 偏好存储（AppearancePreferences 等）
  ViewModels/   ClipboardViewModel（列表/搜索/选择的核心）
  Views/        SwiftUI 视图 + Theme.swift（设计系统）
  Services/     单例：ClipboardMonitor、QuickPasteController、AutoPasteService、
                ToastCenter、Localization、MCPServer、UpdaterService 等
scripts/        generate-signing-cert.sh（一次性签名配置）
.github/workflows/  ci.yml（PR 构建）、release.yml（按 tag 发布）

约定：UI 与服务单例都是 @MainActor，以 .shared 暴露。SwiftData 统一走 AppContainer.shared 这唯一一个 ModelContainer（见 QuickPasteController.swift）， 保证浮动面板和主窗口读写同一份数据。代码注释解释为什么而非做了什么——改代码时 保持同样的注释密度。

本地构建运行

xcodebuild -project Clipth.xcodeproj -scheme Clipth -configuration Debug \
  -derivedDataPath build build
open build/Build/Products/Debug/Clipth.app

准则：开发阶段，每次完成代码开发后都必须构建并把 App 运行起来。 不要只报告编译通过； 构建失败就先修复，不算“完成”。构建成功后先杀掉旧实例，再启动刚生成的 .app，在真实 App 里验证：

pkill -f "Clipth.app/Contents/MacOS/Clipth" || true
open build/Build/Products/Debug/Clipth.app

若本次构建使用了不同的 -derivedDataPath 或 Xcode 默认 DerivedData，必须启动对应路径下 最新生成的 Clipth.app，不要启动旧产物。

本地构建会自动用 Clipth Self-Signed 身份签名（见下）。若该身份不在钥匙串里，构建会 失败——要么运行一次 scripts/generate-signing-cert.sh，要么用 CODE_SIGNING_ALLOWED=NO 做无签名构建。

代码签名（动签名相关的任何东西前必读）

App 使用固定的自签名证书（CN = Clipth Self-Signed）签名，而不是 ad-hoc。 这是关键，不能退回 ad-hoc：

• macOS 把**辅助功能（TCC）**授权绑定在 bundle 的代码签名*指定要求（designated requirement）*上。ad-hoc 签名会让这个要求退化成每次构建都变的 cdhash，于是每次 重建/更新都会静默作废授权，而系统设置里的开关还亮着 → App 不断弹「想要使用辅助功能 控制这台电脑」。固定证书让要求变成 identifier + 证书指纹，在重建、更新、换机器后都 保持不变，授权得以保留。
• ENABLE_HARDENED_RUNTIME = NO。真实签名（不同于 ad-hoc）会真正启用硬化运行时，进而 打开库校验，导致启动崩溃（Xcode 16 的 *.debug.dylib / 框架 Team-ID 不匹配）。硬化 运行时只有公证才需要，而免费自签名阶段并不公证。只有在升级到 Developer ID + 公证时 才重新开启它。