GUI 自动化MCP 服务AI 应用【免费下载链接】PeekabooPeekaboo is a macOS CLI optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.项目地址https://gitcode.com/gh_mirrors/peekaboo6/Peekaboo点击查看免费下载本篇指南以 Peekaboo 仓库的 docs/modern-swift.md 为骨架结合仓库内真实的 Swift 源码、SwiftLint/SwiftFormat 配置与测试代码展开。读者将掌握 Peekaboo 在 Swift 6.2 严格并发模式下的编码约定视图状态如何放置、可观察模型如何组织、阻塞调用如何与异步边界隔离、以及在重构时如何守住已发布 API 与线格式的兼容底线。适合任何要为 Peekaboo 提交 Swift/SwiftUI 改动无论是 macOS 应用、CLI 还是 Core 各模块的开发者阅读。一、总则Swift 6.2 约定、显式self与工具链基线Peekaboo 的 Swift 代码遵循Swift 6.2 约定并强制在成员引用处使用显式self。文档明确要求提交改动前必须运行仓库自带的 SwiftFormat 与 SwiftLint同时不得为了某个重构能编译而擅自抬高部署目标——这条规则在 docs/platform-support.md 中有完整的基线矩阵。1.1 工具链与部署目标基线从仓库的包清单可以确认所有 SwiftPM 包一律声明swift-tools-version: 6.2例如Apps/CLI/Package.swiftApps/Mac/Package.swiftCore/PeekabooAutomationKit/Package.swiftCore/PeekabooCore/Package.swiftCore/PeekabooFoundation/Package.swiftplatform-support.md 给出的基线为表面最低要求说明已发布的 CLI 与 MCP 包macOS 15.0Apps/CLI/Package.swift声明.macOS(.v15)npm 包包装同一 CLI 二进制macOS 应用macOS 15.0Xcode 工程设置MACOSX_DEPLOYMENT_TARGET 15.0公共 SwiftPM 库macOS 14.0包元数据根Package.swift导出PeekabooFoundation、PeekabooProtocols、PeekabooAutomationKit、PeekabooBridgeCLI 源码构建macOS 15.0、Swift 6.2 工具链维护者与 CI 使用 Xcode 26.x 或更新版本因此任何重构都应就着现有地板完成而不是把 deployment target 抬高一档来换取编译器放行。1.2 格式化与静态检查配置仓库根目录的 .swiftformat 与 .swiftlint.yml 定义了唯一权威配置SwiftFormat 使用--swiftversion 6.2、--self insert插入self适配 Swift 6 并发要求的成员引用、--maxwidth 120、4 空格缩进、before-first的参数换行风格、MARK: - %t %p的类型/扩展标记SwiftLint 的included覆盖Apps与Core排除.build、DerivedData、**/Generated、**/Resources、Package.swift等根配置通过parent_config: .swiftlint-rules.yml继承规则集Apps/CLI下另有独立的 .swiftlint.yml 用于 CLI 目标少数必须保持原样的文件被显式排除在格式化之外例如Core/PeekabooCore/Sources/PeekabooCore/Extensions/NSArrayExtensions.swift。这条链路的用意很明确格式与 lint 不是可选项而是提交前必须通过的入口检查。二、状态与视图State、Binding、Observable与Bindable的摆放规则文档给出的状态管理纪律可以概括为一句话让状态靠近它的所有者。视图局部值放State可写值经Binding下传共享依赖走已有 environment 或初始化器注入。2.1 视图局部状态StateApps/Mac/Peekaboo/Features/Settings/SettingsWindow.swift 是教科书式的例子State private var selectedTab: PeekabooSettingsTab .general State private var monitoringPermissions false同一文件中还出现了典型的一次性检测状态State private var hasAttemptedOllamaDetection false说明State只承载视图生命周期内、无共享需求的值。2.2 可写值下传BindingGeneralSettingsView把开关行拆成独立组件时通过Binding传递写权限Binding var showInDock: Bool Binding var isOn: Bool这正对应文档pass writable values throughBinding的约定——子视图只拿到读写通道不拥有数据本体。2.3 可观察模型ObservableMainActor文档允许新代码使用 Observation 框架同时要求UI 持有的模型隔离到MainActor由拥有它的视图通过State持有。仓库的落地非常一致Apps/Mac/Peekaboo/Core/Settings.swift 注释明确写着 This class uses the modern Observable pattern for SwiftUI integrationApps/Mac/Peekaboo/Core/ConversationSession.swift 是标准模板Observable MainActor final class SessionStore { var sessions: [ConversationSession] [] var currentSession: ConversationSession? ... }同一目录下的PeekabooAgent.swift、Permissions.swift、ProviderCredentialCoordinator.swift以及 Features 中的AutomationTargetTracker.swift都采用相同的Observable模式。2.4 子视图取绑定Bindable当子视图需要把可观察模型的属性变成绑定例如切换开关时使用Bindable。SettingsWindow.swift中典型的局部写法Environment(PeekabooSettings.self) private var settings var body: some View { Bindable var settings self.settings Form { SettingsToggleRow(..., isOn: $settings.launchAtLogin) ... } }这里$settings.launchAtLogin正是由Bindable提供的属性绑定。整套组合——State持有、Bindable取绑定、Binding下传——就是文档所述Keep state near its owner在 Peekaboo 中的具体形态。2.5 何时抽模型、何时抽视图文档还有两条微妙的边界抽模型当某段状态或行为需要被多处共享时从视图里提炼出来抽视图当某个子树有了清晰职责时再抽视图小视图不必配套模型不要为了对称给每个小组件硬造一个 model 类型。此外已发布的ObservableObject契约要原样保留除非这次改动明确迁移了它的调用方。这与下文兼容性红线一脉相承。三、渲染与异步工作.task、.task(id:)与TimelineView3.1 渲染代码不得夹带 I/O文档要求rendering code free of I/O and repeated expensive work。这是 SwiftUI 性能的基本盘body只负责声明视图结构真正的异步加载放.task。3.2.task与.task(id:)的选用.task绑定视图生命周期的异步工作视图消失即取消.task(id:)当某个具体输入变化时应重启任务。仓库中的真实用法在 SettingsWindow.swift.task(id: self.settings.ollamaBaseURL) { await self.refreshOllamaModels() }当用户修改 Ollama 服务地址时模型列表的探测任务会随id变化自动重启——这正是用id表达重启语义的典型场景。对应的refreshOllamaModels()被标注为MainActor与Observable模型的隔离保持一致。3.3 时间驱动的呈现TimelineView与事件流文档给出了取舍原则新代码的时间驱动呈现优先用TimelineView如果其调度语义契合功能当事件流本身就是真相源时保留事件流。也就是说不要为了看起来新而用TimelineView去重实现一个本就基于流订阅的界面。3.4 取消与失败要分开处理Handle cancellation separately from a user-visible failure——取消是调用方主动结束等待不应被包装成一次面向用户的错误提示。这与下一节并发边界的原则互为表里。四、并发与服务边界尊重 actor 隔离不为编译而作弊4.1 禁止用nonisolated(unsafe)/unchecked Sendable堵编译器文档的态度非常明确尊重 actor 隔离而不是用nonisolated(unsafe)或unchecked Sendable来静音编译器。当类型确实需要用锁或队列保护共享状态时所有对该状态的访问必须留在同步边界内必须在注释里说明为什么这个 unchecked 一致性是健全的sound。仓库中那些合法的unchecked Sendable都有明确理由。例如 ElementDetectionTimeoutRunner.swift 中的AXObservationWorkerPool它用NSLock保护lanes字典所有读写都经过self.lock.withLock { ... }见其enqueue、complete、evictIdleLanesIfNeeded方法因此unchecked Sendable是有同步机制兜底的。同理ScreenCaptureKitOwnerLease.swift 用NSLock保护nonisolated(unsafe) static var的进程描述符注册表每个可变静态状态旁边都配一把专用锁。4.2 actor 与跨边界值优先Sendable结构体跨 actor 与传输边界传递的数据应尽量是类型化的、Sendable的值。仓库中大量 actor 与异步服务之间交换的是显式Sendable结构体例如ActionVerifier.swift 的ActionDescriptor/VerificationResultAgentCompatibilityTypes.swift 的AgentExecutionResultAgentToolMCPBridge.swift 的actor AgentToolMCPImageStore。actor EventHandlerPeekabooAgentServiceExecution.swift则展示了让状态归 actor、跨 actor 只传值的经典布局。4.3 关键洞察async不会让阻塞调用变非阻塞文档点出了 Peekaboo 并发模型中最反直觉的一条把阻塞性 Accessibility 或 socket 调用包进async函数并不会让它变成非阻塞。Accessibility RPC 与 socket 读写在原生层面是不协作取消的取消只能结束调用方等待不能中断后台原生工作。因此 Peekaboo 在这些边界使用有界的原生 worker 与传输队列并完整保留入场admission、截止时间deadline、清理cleanup规则。最完整的实例是 ElementDetectionTimeoutRunner.swiftrun(seconds:operation:)用withCheckedThrowingContinuation装配一个截止时间状态机主操作放Task { MainActor ... }而超时计时器刻意放在Task.detached——注释明确写着 The timer must not inherit MainActor防止同步的 MainActor 操作靠饿死 deadline 任务来假成功runDetached(...)把非变异 AX 工作投递到per-process 串行 laneAXObservationWorkerPool按pid processStartIdentity建 lane每个 lane 一个DispatchQueue并支持maximumPendingOperationCount限流与空闲 lane 驱逐上限 64;每个 AX 调用有软/硬两级超时DetachedAXWindowEnumerationTiming硬超时减去 0.01~0.25s 的完成宽限得到软超时超时后立即恢复调用方绝不 join 仍在飞行中的 AX RPC。这就是async函数不会让阻塞调用非阻塞的正解在原生边界保留有界 worker 和专用队列把等待与原生工作彻底分离。4.4 结构化并发与 detached task 的所有权文档规定子工作的生命周期属于调用方时优先用结构化并发Task.detached必须有明确的生命周期与取消所有者。上述超时任务是有意脱离调用方生命周期它必须独立于 MainActor 运行的少数例外且每个 detached task 都在onCancel中通过state.cancel()收尾。4.5 模块职责边界生产自动化逻辑放在AutomationKitAgent / MCP 适配放在AgentRuntime共享可视组件放在UICore 或 Visualizer。从目录结构看Core/PeekabooAutomationKit自动化原语、Core/PeekabooCore/Sources/PeekabooAgentRuntimeAgent 运行时、Core/PeekabooUICore/Core/PeekabooVisualizerUI 与可视化正是这条分层的物理体现。五、验证纪律在所有权边界测试不靠 sleep5.1 测试应落在行为的所属边界文档的验证原则是Exercise behavior at its owning boundary能注入时钟、服务、临时存储的接缝处就注入用可观察的完成等待结果而不是sleep一段估算时长。仓库测试大量使用时钟注入来避免睡眠Core/PeekabooAutomationKit中的ScreenCaptureKitCaptureGate、ScreenCaptureKitWindowPlanCache等实现都以ContinuousClock.Instant作为截止时间输入见 ScreenCaptureKitCaptureGate.swift 与 ScreenCaptureKitWindowPlanCache.swift测试据此可以精确控制现在时刻来验证过期与超时路径。5.2 已发布 API 与线格式的测试必须保留重构时已发布的 API 与已确定线格式wire format的测试不得删除。这条规则在 docs/dev/lint-compatibility.md 中有严格登记DesktopTargetEvidenceAdapter.evidence(processIdentifier:...)DesktopTargetEvidenceAdapter.swift因六个独立输入是 v4.2.2 发布契约持有唯一一个function_parameter_count豁免且由版本选择的 SwiftPM 消费者 fixturescripts/test-swiftpm-consumer.sh做编译验证三个用available(*, deprecated)上下文故意调用 v4.2.2 已废弃公共 API 的测试声明PeekabooBridgeAppleScriptCompatibilityTests、InMemorySnapshotManagerTests的两个 legacy initializer 用例被点名保留豁免范围只限这三处声明本身不授权整文件注释、编译警告抑制或兼容垫片。5.3 提交前的验证流程文档给出的最终检查清单是构建受影响的包并运行相关测试UI 行为改动还要运行构建出的应用、对照受控 fixture 验证可见结果——SwiftUI previews只辅助布局不能证明生命周期、权限或自动化正确性遵循 docs/building.md 与docs/testing/下的相应契约完成检查。六、总结一份可执行的改动前 Checklist把整份规范浓缩成提交前的自查清单工具链为 Swift 6.2改动不抬高任何包的 deployment target对照 docs/platform-support.md成员引用显式写self代码通过仓库 .swiftformat 与 .swiftlint.yml 检查视图局部值用State可写值用Binding下传共享依赖走 environment/初始化器注入新可观察模型用ObservableMainActor由State持有子视图绑定用Bindable既有ObservableObject公共契约未动渲染代码无 I/O异步工作挂.task/.task(id:)取消与用户可见失败分开处理没有用nonisolated(unsafe)/unchecked Sendable堵编译器锁保护的共享状态全部访问都在同步边界内unchecked 一致性有注释论证阻塞的 AX/socket 调用走有界原生 worker 与传输队列worker 的入场/截止时间/清理规则原样保留子工作优先结构化并发detached task 有明确生命周期与取消所有者测试落在所有权边界用注入的时钟/服务/临时存储用可观察完成代替 sleep已发布 API 与线格式测试完整保留lint 豁免符合 docs/dev/lint-compatibility.md 的登记范围构建受影响包、跑相关测试UI 改动再用受控 fixture 跑真实应用验证。这份指南既是新人快速进入 Peekaboo 的编码入口也是老改动合入前唯一的合规裁判。遵循它你的改动才能同时通过编译器、SwiftLint、测试与发布契约四道关卡。赞分享GUI 自动化MCP 服务AI 应用【免费下载链接】PeekabooPeekaboo is a macOS CLI optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.项目地址https://gitcode.com/gh_mirrors/peekaboo6/Peekaboo点击查看免费下载相关推荐Amaze File Manager 的 AI 代码贡献指南从提交纪律到测试验证的完整开发规范Amaze File Manager 的 AI 代码贡献指南从提交纪律到测试验证的完整开发规范 本文基于仓库根目录的 CLAUDE.md https://li移动开发妙言 MiaoYan Swift 开发规范实战指南UI 框架边界、线程纪律与 CJK 文本处理妙言 MiaoYan Swift 开发规范实战指南UI 框架边界、线程纪律与 CJK 文本处理 本篇技术指南围绕妙言MiaoYan开源仓库中的 .clau桌面应用CLIJSHint 与 Redux状态管理库的代码规范JSHint 与 Redux状态管理库的代码规范 你是否曾在 Redux 项目中遇到过这些问题Action 命名混乱导致调试困难Reducer 函数中出现Lint静态分析上一篇GetQzonehistory免费完整导出 QQ 空间历史说说到本地 Excel 的备份工具下一篇如何安全使用Facebook-scraper避免封禁的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考