在 macOS 应用中集成 Capso 的截图、录屏、标注…

当你需要在 macOS 15+ 应用中快速添加截图、屏幕录制、摄像头 PiP、标注、OCR、导出等功能，或想构建/贡献 Capso 开源项目时使用。

适用场景

解决思路

1. 安装预构建 App：运行 `brew tap lzhgus/tap`，然后 `brew install --cask capso`；或从 GitHub Releases 下载签名 DMG。
2. 从源码构建：要求 Xcode 16+、macOS 15.0+、XcodeGen；安装 `brew install xcodegen`；克隆 `git clone https://github.com/lzhgus/Capso.git`；进入 `cd Capso`；生成 `xcodegen generate`；打开 `open Capso.xcodeproj`；按 Cmd+R 构建运行。
3. CLI 构建：运行 `xcodegen generate`；然后运行 `xcodebuild -project Capso.xcodeproj -scheme Capso -configuration Release build`。
4. 了解项目架构：App 目录是薄 SwiftUI + AppKit 壳；Packages 包含 SharedKit、CaptureKit、RecordingKit、CameraKit、AnnotationKit、OCRKit、ExportKit、EffectsKit；所有逻辑在包中，可单独通过 SPM 嵌入自己的 app。
5. 在自己的 app 中使用 Capso 包：在 `Package.swift` 中添加 `.package(path: "../Capso/Packages/CaptureKit")` 等依赖，并在 target 的 dependencies 中加入 `"CaptureKit"`、`"AnnotationKit"`、`"OCRKit"` 等。
6. 使用 CaptureKit 截图：导入 `CaptureKit`；创建 `let captureManager = CaptureManager()`；全屏截图调用 `try await captureManager.captureFullscreen()` 返回 `NSImage`；窗口截图先用 `SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)` 获取 `SCWindow`，再调用 `try await captureManager.captureWindow(window)`；区域截图传入 `CGRect` 调用 `try await captureManager.captureArea(rect)`。
7. 使用 RecordingKit 录屏：导入 `RecordingKit`；创建 `let recorder = ScreenRecorder()`；配置 `RecordingConfiguration`（`includesSystemAudio`、`includesMicrophone`、`outputFormat` 如 `.mp4`/`.gif`、`quality` 如 `.maximum`/`.social`/`.web`）；调用 `try await recorder.startRecording(region:to:configuration:)`；调用 `recorder.pause()`、`recorder.resume()`；调用 `try await recorder.stopRecording()` 获取最终 URL。
8. 使用 CameraKit 摄像头 PiP：导入 `CameraKit`；创建 `let cameraManager = CameraManager()`；调用 `await cameraManager.requestPermission()`；调用 `try await cameraManager.startCapture()` 获取 `AVCaptureVideoPreviewLayer`；设置 `cameraManager.pipShape = .circle`（或 `.square`/`.portrait`/`.landscape`）；调用 `cameraManager.stopCapture()`。
9. 使用 AnnotationKit 标注：导入 `AnnotationKit`；用 `AnnotationCanvas(image:)` 创建画布；添加 `ArrowAnnotation(from:to:color:strokeWidth:)`、`RectangleAnnotation(frame:color:strokeWidth:filled:)`、`TextAnnotation(text:position:fontSize:color:)`；调用 `canvas.addAnnotation(...)`；调用 `canvas.undo()`/`canvas.redo()`；调用 `canvas.renderToImage()` 导出 `NSImage`。
10. 使用 AnnotationKit 美化截图：创建 `let beautifier = ScreenshotBeautifier(image: rawImage)`；设置 `backgroundColor`、`padding`、`cornerRadius`、`shadowRadius`、`shadowOpacity`；调用 `beautifier.render()` 返回美化后 `NSImage`。
11. 使用 OCRKit 文字识别：导入 `OCRKit`；创建 `let ocrEngine = OCREngine()`；调用 `try await ocrEngine.recognizeText(in: image)` 返回 `String`，可复制到 `NSPasteboard.general`；调用 `try await ocrEngine.recognizeBlocks(in: image)` 返回 `[OCRTextBlock]`，含 `text` 和 `boundingBox`。
12. 使用 ExportKit 导出视频/GIF：导入 `ExportKit`；创建 `let exporter = MediaExporter()`；调用 `try await exporter.exportVideo(from:to:quality:)`（quality 如 `.social`/`.maximum`/`.web`）；调用 `try await exporter.exportGIF(from:to:fps:scale:)`。
13. 使用 SharedKit 权限与设置：导入 `SharedKit`；创建 `let permissionManager = PermissionManager()`；调用 `await permissionManager.requestScreenRecordingPermission()`、`requestCameraPermission()`、`requestMicrophonePermission()`；通过 `CapsoSettings.shared` 设置 `screenshotShortcut`、`defaultSaveLocation`、`showCountdownBeforeRecording`、`countdownSeconds`。
14. SwiftUI 集成模式：在 `ContentView` 中用 `@State private var capturedImage: NSImage?` 和 `private let captureManager = CaptureManager()`；按钮中 `Task { capturedImage = try? await captureManager.captureFullscreen() }`；用 `.sheet` 展示 `AnnotationEditorView(image: img) { annotated in ... }`。
15. 运行包测试：运行 `swift test --package-path Packages/SharedKit`；对 CaptureKit、AnnotationKit、OCRKit、RecordingKit、CameraKit、ExportKit、EffectsKit 同理运行。
16. 配置所需 Entitlements 和 Info.plist：Info.plist 添加 `NSScreenCaptureUsageDescription`、`NSCameraUsageDescription`、`NSMicrophoneUsageDescription`；App.entitlements 添加 `com.apple.security.device.camera` 和 `com.apple.security.device.microphone`；屏幕捕获通过运行时 TCC，无需 entitlement。
17. 固定截图到屏幕（始终置顶）：用 `NSPanel` 创建窗口，`styleMask: [.nonactivatingPanel, .titled, .closable, .resizable]`；设置 `window.level = .floating`、`isFloatingPanel = true`、`hidesOnDeactivate = false`；`window.contentView = NSImageView(image: image)`；`window.makeKeyAndOrderFront(nil)`。
18. 注册全局键盘快捷键：用 `NSEvent.addGlobalMonitorForEvents(matching: .keyDown)` 监听；检查 `event.modifierFlags.contains([.command, .shift])` 和 `event.keyCode == 21`（'4'）；通过 `NotificationCenter.default.post(name: .startAreaCapture, object: nil)` 发送通知，并定义 `Notification.Name` 扩展。
19. 故障排除 xcodegen generate 失败：运行 `brew upgrade xcodegen` 确保 ≥ 2.40；检查 `project.yml` YAML 语法；运行 `xcodegen generate --spec project.yml`。
20. 故障排除屏幕录制权限被拒：在系统设置 → 隐私与安全性 → 屏幕录制 中启用 Capso；自己的 app 使用 CaptureKit 时先调用 `PermissionManager.requestScreenRecordingPermission()` 触发提示。
21. 故障排除 Swift 6 并发构建错误：确保所有触及 UI 的闭包标记 `@MainActor`；添加 `@preconcurrency import ScreenCaptureKit` 消除 Xcode 16 警告。
22. 故障排除 GIF 导出慢：在 ExportKit 中降低 `fps`（如 `fps: 10`）和 `scale`（如 `scale: 0.5`）；使用 `.web` 质量预设加快编码。
23. 故障排除相机不显示 PiP：在系统设置中授予相机权限；先调用 `CameraManager.requestPermission()` 再 `startCapture()`；确保 entitlement 包含 `com.apple.security.device.camera`。
24. 遵守许可证：Capso 使用 BSL 1.1；允许个人使用、内部公司使用、fork、修改；禁止销售基于此代码的竞争性屏幕捕获产品；2029 年自动转为 Apache 2.0；在非竞争 app 中嵌入包是被允许的。
25. 参考关键链接：GitHub 仓库 `https://github.com/lzhgus/Capso`；Releases `https://github.com/lzhgus/Capso/releases/latest`；网站 `https://www.awesomemacapp.com/app/capso`；Bug 报告 `https://github.com/lzhgus/Capso/issues/new?template=bug_report.yml`；功能请求 `https://github.com/lzhgus/Capso/issues/new?template=feature_request.yml`；GitHub Sponsors `https://github.com/sponsors/lzhgus`。

适用边界 · 注意事项

• 不适用于非 macOS 平台，因为 Capso 仅支持 macOS 15.0+ 并使用 SwiftUI/Swift 6。
• 不适用于想开发或销售与 Capso 竞争的屏幕捕获产品的场景，BSL 1.1 明确禁止。
• 如果开发环境无法满足 macOS 15.0+、Xcode 16+、Swift 6 或 XcodeGen 要求，则无法构建或集成。