huashu-mac-use

这是什么？适合谁？

huashu-mac-use（「话术 Mac use」）是一个基于开放 Agent Skills 协议的 macOS computer-use 技能：让任何能读 SKILL.md 的 agent 操控 Mac 上没有 API 的原生 app，并把每一步拍成可复现的取证。Claude Code、Codex、Kimi Code、Cursor、OpenClaw、WorkBuddy、豆包工作、千问办公、ZCode 等 runtime 都能安装。

它解决的是 computer-use 的三大老问题：读操作抢焦点（截个图把你的桌面切走）、写操作乱点鼠标、过程黑盒无证据。huashu 的原则是「读随便读，写不打扰，每一步都留证据」——真实案例：一个 coding agent 照 4 张 AI 生成照片在 Blender 里 33 分钟建出十万吨级邮轮，全程无人碰鼠标；给豆包工作连做 8 张过程截图，一次焦点都没借。

核心价值：四层通道分级（L0 结构接口 → L1 AX 语义树 → L2 窗口坐标 → L3 像素）先探测再动手，读操作全后台、写操作默认零焦点（postToPid 直投进程 + 截图差分验证），每步留取证截图。

适合人群：

• 想让 Claude Code / Codex / Cursor 等 agent 自动化 Mac 原生 App（Blender、剪映、WPS、系统设置等）的开发者
• 做自动化但被「抢焦点打断手头工作」困扰的用户
• 需要 GUI 自动化过程留痕（审计/复现）的团队

使用前提：macOS（实测 macOS 26，14 以上大概率可用，Apple Silicon / Intel 均可）+ Xcode Command Line Tools + Node.js；给正在用的终端 app 授「屏幕录制」与「辅助功能」权限。

准备工作

1. 系统：macOS 14+（实测 macOS 26），Apple Silicon 或 Intel
2. 环境：Xcode Command Line Tools（xcode-select --install，内核是一个 Swift 文件，首次编译约 20 秒）；Node.js（内嵌 Chromium 的 app 走 CDP 时用）
3. 权限：给你正在用的终端 app（Terminal / iTerm / Cursor…）授「屏幕录制」和「辅助功能」——是授给终端 app 不是授给脚本，换终端要重新授
4. 成本：MIT 开源免费，纯本地运行
5. 时间：安装 + 编译内核约 2 分钟

快速上手（3 步）

第一步：安装

三种方式任选：

# 方式一：一行命令（推荐）
npx skills add alchaincyf/huashu-mac-use

# 方式二：把链接丢给你的 agent
「帮我安装这个 skill：https://github.com/alchaincyf/huashu-mac-use」

# 方式三：手动
git clone https://github.com/alchaincyf/huashu-mac-use.git ~/.claude/skills/huashu-mac-use
# Codex 是 ~/.codex/skills，其余 runtime 同理
bash ~/.claude/skills/huashu-mac-use/scripts/build.sh   # 编译内核，一次就好

第二步：探一个 App 试试

bash ~/.claude/skills/huashu-mac-use/scripts/probe.sh 系统设置

probe.sh 是每次动手前的第 0 步：告诉你这个 app 的 bundle、架构、有没有 URL scheme、有没有 AppleScript 字典、有没有本地端口、AX 树里有几个可编辑控件、版本号。进程表判架构（有 Helper / crashpad_handler 子进程就是 Chromium 系）。

第三步：让 Agent 干一件真事

在你的 agent（如 Claude Code）里直接说自然语言：

「操控 Blender 做一个巧克力甜甜圈，要真实丰富的细节，渲出来」
「把 豆包工作 里正在跑的那个任务截三张过程图，别抢我焦点」
「把系统设置里的蓝牙关掉」

预期结果：agent 自选通道执行，写操作不抢焦点，每步产出后台取证截图。

初级用法

四层通道怎么选

后台取证

mac shot / mac shotfg：先试后台截图（不 activate、不切桌面），判空了才借焦点。截图是每一步的验证手段。

Chromium 系 App 一条命令开 CDP

mac open <app> --cdp 9333   # 带调试端口重启并等到端口通

内嵌 Chromium 的 app（某些 AI 办公客户端把整个 Chromium 埋在 Contents/Helpers/…/Frameworks/ 里）有完整 CDP 通道，比坐标点击可靠一个数量级。

高级玩法

写操作零焦点阶梯

mac op 先用 postToPid 把键鼠事件直投目标进程（不抢焦点、不切桌面、不受遮挡），截图差分看有没有生效；判不出才升级借焦点。升级前自动过四道闸（前台闸等），--dry 可以零执行预演每道闸的判定。

多 Agent 并行互不干扰

L0 通道跨桌面、零焦点，多个 agent 可以同时操控不同 app 互不打架——这是坐标自动化做不到的。

自主进化：收工回流

每次任务收工后把经验回流进 skill（仓库的「自主进化（每次收工回流一次）」机制），probe 判定规则随真实踩坑持续改进。

小技巧

1. 先 probe.sh 再动手——「是不是 Chromium 系」要看穿一层目录，顶层 Frameworks/ 为空不代表没有 CDP
2. 「后台能不能截到图」是窗口级差异不是架构级：同一个 Electron，千问办公能截、WorkBuddy 不能——别按架构预测，让 mac shotfg 每次先试
3. 换终端 app 后记得重新授权屏幕录制/辅助功能，否则读操作静默失败
4. AX 通道必须「实写之后应用状态真的变了」才算通——只探到控件不算
5. --dry 预演四道闸，写操作前先看判定结果再真跑

常见踩坑

踩坑 1：probe 判错架构，整轮走了坐标点击

• 现象：明明有 CDP 通道的 app 被当原生 app，全程 L2 坐标点击
• 原因：某 AI 办公客户端把整个 Chromium 埋在 Contents/Helpers/…/Frameworks/ 里，顶层 Frameworks/ 是空的，第一天被判成原生 app，第三天才发现 CDP 通道
• 解决：现版 probe.sh 用进程表判架构（有 Helper / crashpad_handler 子进程就是 Chromium 系）
  • 来源：官方 README

踩坑 2：换终端后读操作全部失败

• 现象：截图、AX 全部静默失败
• 原因：屏幕录制/辅助功能授权是授给终端 app的，换了终端（如从 Terminal 换 Cursor）旧授权不覆盖
• 解决：给新终端 app 重新授权两个权限

踩坑 3：AX 树探到控件但写入无效

• 现象：mac axset 执行了但应用状态没变
• 原因：AX 控件可枚举 ≠ 可写入；skill 的标准是「实写之后应用状态真的变了才算通」
• 解决：降级到 L2 坐标通道，或换 L0（查 AppleScript 字典/URL scheme）

踩坑 4：截图把我的桌面切走了

• 现象：agent 一截图就 activate 了目标 app
• 原因：走了借焦点的截图路径——skill 的 mac shotfg 先试后台，判空才借焦点；若你用的是旧版或其他工具则无此保护
• 解决：升级到最新版；确认读操作没有手动加了 activate 类命令

踩坑 5：macOS 版本过低或未装 Xcode CLT

• 现象：build.sh 编译失败
• 原因：内核是 Swift 文件，需要 Xcode Command Line Tools；实测 macOS 26，更低版本未验证
• 解决：xcode-select --install 后重跑 build.sh；macOS 14 以下无保证

常见问题 FAQ

Q1: 它和 Anthropic 官方 computer use 的区别？

A: 官方 computer use 以截图-点击为主（对应本 skill 的 L2/L3 层）；huashu-mac-use 把 L0 结构接口（CLI / AppleScript / URL scheme / CDP）作为默认起点——零焦点、跨桌面、可靠一个数量级，且失败降级有据可查。仓库有专节「和官方 computer use 的关系」。

Q2: 支持哪些 agent runtime？

A: 基于开放 Agent Skills 协议（agentskills.io），任何能读 SKILL.md 的 runtime 都能装：Claude Code、Codex、Kimi Code、Cursor、OpenClaw、WorkBuddy、豆包工作、千问办公、ZCode 等。

Q3: 免费吗？开源吗？

A: MIT 开源免费，纯本地运行，无云依赖。

Q4: 安全吗？会不会误操作我的系统？

A: 写操作有四道闸（前台闸等）+ --dry 预演；读操作只读不碰。权限授给终端 app 而非脚本，随时可在系统设置里撤销。

Q5: 必须是 Apple Silicon 吗？

A: 不是，Apple Silicon 或 Intel 都行；需要 Xcode Command Line Tools（内核首次编译约 20 秒）。

进阶学习建议

1. 读 SKILL.md 里四层通道的探测与降级顺序，理解为什么 L0 结构接口（CDP / AppleScript / URL scheme）永远优先于坐标点击——跨桌面、零焦点、多 agent 并行都建立在它之上
2. 复现官方三个案例建立手感：Blender 巧克力甜甜圈（bpy 命令行 + mac shot 后台取证）、邮轮照片复刻（参数化建模 8 轮迭代）、豆包工作过程截图（CDP 通道 8 张图零焦点）
3. 研究 mac op 的 postToPid 直投 + 截图差分 + 四道闸设计——这套「写默认零焦点」的阶梯值得任何 GUI 自动化项目借鉴
4. 用 probe.sh 对你最常用的 5 个 Mac app 做一次通道盘点，建立自己的「哪个 app 走哪层」速查表

参考链接

• 官方仓库
• README（看效果 / 安装 / 它怎么工作 / 与官方 computer use 的关系）
• Agent Skills 协议

最后更新：2026-09-07 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成