企业官网建设流程全解析

• 人工智能
• AI 应用
• AI Agent
• 代码智能体
• 桌面应用
• 开发工具
• GUI 自动化

cc-haha 是一款本地优先的跨平台 AI 编程桌面工作台，它的 Computer Use（电脑操控）功能让 Claude 能截图、点击、输入，替你操作那些没有 API 的桌面应用。在 macOS 上，cc-haha 用一个原生 Swift 运行时（cu-helper）实现了"非占用式光标控制"：Agent 干活时，你的真实鼠标纹丝不动，屏幕上滑动的只是一枚虚拟光标——你可以一边让 AI 操作备忘录，一边用自己的鼠标继续写代码。这篇文章拆解它背后的架构与关键实现。

为什么传统方案会"抢走"你的鼠标

早期的 AI 电脑操控（包括 cc-haha 最初的兼容执行器）大多基于 Python 的 pyautogui。它在 macOS 底层把鼠标/键盘事件注入到HID 硬件事件层（CGEventPost(kCGHIDEventTap)），后果是：

• 系统只有一个物理光标，注入等于把真光标拖走，用户无法同时操作；
• 事件只能落在"当前前台窗口"，目标应用必须亮在最前；
• 全局生效，无法定向投递到某个后台 App。

这正是用户核心诉求的反面：我想一边自己工作，一边让 Agent 在另一个应用上跑自动化。cc-haha 为此把最底层的 Python helper 换成了原生 Swift 二进制 cu-helper，上层安全体系与工具协议完全不动。

整体架构：只换最底一层

Computer Use 是一条 6 层链路：MCP 工具定义 → 九层安全关卡 → 会话绑定 → 宿主集成 → 进程调用边界（Bridge）→ 平台执行运行时。Swift 化的精妙之处在于只替换了最底层的执行运行时：

• 旧的 mac_helper.py 与新的 cu-helper 遵守完全相同的 JSON 命令行协议（<command> --payload <json>，stdout 返回{ok, result}）；
• 上层的 Python Bridge 调用边界 几乎零改动，即可在 Python 与 Swift 之间热切换。

非占用式控制的三件套

1. 按 PID 定向注入：事件不经过系统光标

新执行器有一条"绝对规则"：所有鼠标/键盘事件一律用CGEvent.postToPid(targetPid)（即CGEventPostToPid）投递给目标应用进程，永远不调用 HID 层注入，也永远不调用CGWarpMouseCursorPosition之类的位移 API。

事件上虽然还带有坐标，但那只是让目标应用做命中测试（点中正确的按钮），投递带坐标的事件并不会移动硬件光标。这条规则写在 Injection.swift 的文件头注释里，是整个注入引擎的宪法。

2. 虚拟光标：你自己画一个"假光标"给用户看

真光标不动了，用户就看不到 AI 在点哪里。cu-helper 的答案是自绘覆盖层：每块屏幕上一个无边框、透明、点击穿透的浮层窗口，光标是一枚随逻辑坐标平滑滑动（ease-out 缓动）的动画元素，点击时播放涟漪动效；被操控的窗口还会有一圈柔和光晕跟随。

关键实现约束：覆盖层不抢焦点、不出现在 Dock、不吃鼠标事件，也不会出现在截图里（否则模型会看到自己的光标，形成反馈回路）。逻辑位置就是唯一的"光标状态源"，见 VirtualCursor.swift。

3. Accessibility（AX）兜底：点按钮不必真的"点"

postToPid对部分应用不够可靠，所以 cu-helper 对按钮、菜单、文本框提供 AX 控件级路径：通过坐标找到命中控件，直接执行"按下"动作，或给文本框赋值。策略与业界一致：CGEvent 优先（更像真实交互），AX 兜底。

后台窗口截图：目标应用不必在最前

配合不抢光标，截图也换了引擎：Capture.swift 基于 macOS 14+ 的 ScreenCaptureKit，直接抓取指定显示器或窗口的图层内容。窗口被遮挡、不在最前、甚至在另一块屏幕上，都能抓到——这就是"你在 App B 工作，Agent 却在驱动 App A"的底气。

人机共存：如何确认"没有人和 Agent 抢输入"

一个容易被忽略的安全问题：Agent 操作到一半，真人碰了鼠标，怎么办？

早期实现用"只读事件监听（listen-only event tap）"，结果踩了个大坑：监听键盘事件需要第三个系统权限"输入监控"，而授权卡片从未请求过它——新装机上所有操作直接失败。现在的方案优雅得多：改读HID 系统事件计数器（CGEventSource.counterForEventType(.hidSystemState)），零权限、不可失效，且实测postToPid注入的合成为事件不会污染计数器。每次动作前后比对计数器"纪元"，一旦真人动过输入，立即让位中止。实现见 PhysicalInputEpochMonitor.swift 与 ForegroundLease.swift。

九道安全关卡：每一次动作都要过检

非占用不等于无边界。每次动作执行前，都要串过 9 层检查：全局开关 → TCC 系统权限（辅助功能 + 屏幕录制）→ 会话互斥锁 → 应用隐藏 → 前台应用白名单 → 三级权限徽章（read / click / full）→ 受保护剪贴板 → 像素新鲜度校验 → 才轮到执行。任何一环失败，动作被拒。cc-haha 自己、终端和浏览器也在默认拒绝名单内，防止 Agent 反向"操控"宿主。

如何开启与使用

对普通用户，你只需要知道两件事：

1. 只需两项系统权限：「辅助功能」（发点击和输入）+「屏幕录制」（截屏）。"输入监控"永远不该出现在任何提示里。授权后需完全退出并重新打开应用；
2. 入口：打开「设置 → Computer Use」开启，然后给任务写清边界（"只在备忘录里操作"），比笼统目标靠谱得多。

日常用法、已知边界与排查方法，见功能指南 docs/desktop/computer-use.md。

关键文件路径速查

小结

cc-haha 的 Computer Use 用三个替换解决了一个大问题：事件按 PID 定向投递（不动真光标）、自绘虚拟光标（让用户看得见 AI 在干嘛）、AX 控件兜底（后台应用也能操作），再配上 ScreenCaptureKit 后台截图和 HID 计数器人机共存检测——整套原生 Swift 运行时的协议边界与旧 Python helper 完全一致，上层安全体系一行未改。这也是"只换最底一层"架构的胜利：能力升级了，复杂度却没有扩散。

• 人工智能
• AI 应用
• AI Agent
• 代码智能体
• 桌面应用
• 开发工具
• GUI 自动化