Andee在macOS的第二个身体:同一个大脑如何驱动鼠标、键盘与沙箱终端
Andee在macOS的第二个身体:同一个大脑如何驱动鼠标、键盘与沙箱终端
Andee 是一个开源的 AI 智能体项目:它"住"在你的 Mac 里,像你一样操作任意 App——点鼠标、敲键盘、在沙箱终端里执行命令,而记忆和密码(localOnly 数据)始终不离开设备。它的特别之处在于"一个大脑、两个身体":手机和 Mac 跑的是同一份智能体循环代码,Mac 身体只是换上了一套全新的"手"。这篇文章带你看看 Andee macOS 桌面版是如何实现的,以及如何构建安装它。
一个大脑,两个身体:core/ 模块里共享了什么
Andee 的仓库分成三个 Gradle 模块,"大脑共用"就是靠这个结构实现的:
core/——平台中立的"大脑":智能体循环LocalBrain、系统提示词LocalPrompt、工具清单ToolSchemas、回合守卫TurnGuards、笔记本(记忆)逻辑、语音引擎,以及朋友互连core/peer/app/——Android 身体:无障碍服务 +WindowManager悬浮层desktop/——Mac 身体:Compose Desktop 窗口 + 悬浮小球 + Swift 桥接层
每个身体只需实现同一个接口 BrainHost.kt,大脑从此看不到任何 Android 或桌面平台的类型。Mac 这边的实现是 DesktopBrainHost.kt:它把屏幕、终端、设备、语音等能力拆成一个 ToolProvider 列表,"只向模型注册真正能跑的工具"——一个列出来却做不到的工具,等于模型对用户许下的、无法兑现的承诺。
新的手:鼠标、键盘与屏幕是怎么驱动的
手机上 Andee 靠无障碍手势"点"屏幕;Mac 上它拿到了真家伙——真实的鼠标点击和键盘事件。这部分通过一个 Swift 原生桥接(desktop/native/AndeeMac.swift,由 Bridge.kt 经 JNA 加载)实现,而 MacScreen.kt 把 macOS 的无障碍树翻译成和手机完全相同的协议:
- 界面被压成一份"元素大纲",每个元素一个
e编号,附 0–1000 的相对坐标 - 坐标点击就是真鼠标点击;带
Press动作的元素优先走自身动作,保证"不会点歪" - 截图上依然叠着 8×12 的标号网格,放大时还有品红色十字准星——和手机上一模一样
- 同样的防误触守卫:坐标超出 0–1000 直接拒绝;同一位置五分钟内第四次点击也会拒绝
设备类能力(启动 App、音量、日历、提醒、联系人、通知、保险箱等)在 MacDevice.kt 里注册,走 macOS 自家的 AppleScript 和系统能力。它还会像个"权限管家":任务需要某个授权时,替你打开系统设置并解释为什么要给。Mac 身体需要三样授权:辅助功能(操作其它 App)、屏幕录制(看屏幕)、完全磁盘访问(读通知)。
沙箱终端:按风险分级、删除进废纸篓的"手"
这是 Mac 身体独有、也是最能体现设计克制的一只手:一个沙箱终端。模型能发起的命令只有三个工具:run_command、command_output、stop_command(实现见 ShellTools.kt,完整设计思路见 desktop-shell-tool.zh-CN.md)。
五级风险分级,先读命令再放行
每条命令在运行前由 RiskClassifier.kt 按 ;、&&、| 拆段打分,取最高档:
| 风险档 | 典型例子 | 处理方式 |
|---|---|---|
| 安全 | ls、cat、git status、rg |
只读命令,直接跑 |
| 低 | 名单外的程序 | 问一次,可"总是允许" |
| 中 | rm 单文件、kill -9、git push、npm publish |
问一次;带危险参数时"总是允许"失效 |
| 高 | rm -r、sudo、git push --force、chmod 777 |
每次都问,不能"总是允许" |
| 致命 | rm -rf /、git reset --hard、DROP DATABASE、terraform destroy |
每次都问,并二次确认 |
有两个刻意的"更严":"安全"只收只读命令(会写入的命令至少是"低");凡影响远程系统的命令至少"中"——沙箱管得住本机文件,管不住推到远端的代码,这种事必须过人眼。
四种模式,沙箱兜底
ShellPolicy.kt 给出用户可选的四种模式:
- 问我(默认):只有"安全"直接跑,其余都问
- 自动:沙箱里"低""中"也放行,"高""致命"仍每次问
- 只读:只许查,不许写
- 完全开放:不问、不进沙箱——但必须在设置里输入"开启"才生效,且"致命"命令默认仍要二次确认
除完全开放外,每条命令都在 sandbox-exec 生成的沙箱档案里运行(SandboxProfile.kt):
- 全盘可读、默认禁写,只放开工作文件夹、临时目录和 npm / pip / gradle 等工具缓存
- 密钥目录读写全禁:
~/.ssh、~/.aws、钥匙串、浏览器 Cookie 和密码、甚至 Andee 自己的数据目录(保险箱和笔记本) - 删除单独禁:
rm被替换成 Andee 自带的"软删"版本,一律移到废纸篓,一次超过 50 个文件或 200 MB 还会先停下来问 - 网络默认只通 localhost:访问新域名时弹卡片按域名放行
- 命令输出在返回给模型前会做密钥脱敏(Redactor.kt),保险箱里的值一旦出现在输出里就替换掉
还有一层更硬的闸门:按回合来源拦截。来自陌生通知触发的回合、静默复盘回合,执行命令会被分发器直接拒绝——即使你开了"完全开放"也一样。因为"完全开放"是信任 Andee,不是信任给这台电脑发消息的陌生人。
🔑 连 git push 都有说法:Andee 自己充当 ssh-agent,私钥存进系统钥匙串只签名、不给文件,按主机授权、每次签名都在聊天记录里留一行。
同一张脸:桌面版的情绪小球
Mac 版保留了手机上的灵魂——那颗会做表情的球。FloatingBall.kt 让小球悬浮在所有窗口之上,聊天窗口里还有第二颗,两颗共享同一套 MacBall 状态。手势词汇和手机完全一致:单击停下并聆听,双击停下并打字,横滑换角色,长按展开窗口。它执行屏幕、终端、设备类操作时,小球还会轻轻"点头"——一只"手"动了,你看得见。
手机和 Mac 成为朋友:扫码互相帮忙
两个跑着 Andee 的设备可以成为"朋友"(core/peer/):一方出示二维码,另一方扫一下。二维码两分钟过期、三次错误作废,并携带出示方设备的密钥指纹,扫描方只认这把钥匙;之后每条链路都是带前向保密的签名加密通道,无服务器中转。
| 类型 | 行为 |
|---|---|
| 我的设备 | 另一台你自己的设备,请求按你本人的请求执行 |
| 朋友 | 陌生人的设备:对方主人先收到"允许 / 总是 / 拒绝"卡片,任务跑在一个一次性大脑里——没有你的记忆、历史、保险箱和终端,只有屏幕、提问、开 App 这几样白名单工具 |
于是就有了这样的分工:手机上的一句话,可以让 Mac 上的 Andee 打开终端查文件;你的 Mac 也能让手机去干别的。
快速开始:构建并安装 Andee macOS 桌面版
环境要求:macOS 14+(Apple silicon 或 Intel)、JDK 17–20、Command Line Tools(提供 swiftc)。
git clone https://gitcode.com/gh_mirrors/an/andee
cd andee
./gradlew :desktop:createDistributable
# 产物:desktop/build/compose/binaries/main/app/Andee.app
cp -R desktop/build/compose/binaries/main/app/Andee.app /Applications/
安装后的三件事:
- 授予权限:在系统设置 → 隐私与安全性里给 Andee 打开"辅助功能"和"屏幕录制"
- 配置大脑:⚙ 设置 → Backend,填入你自己的模型 key(支持任意 OpenAI 兼容端点)
- 第一次启动:由于本地自签名,macOS 15 上"右键打开"已失效——按 README-signing.md 的说明,去 系统设置 → 隐私与安全性 → 安全 里点"仍要打开"(按钮只在启动失败后约一小时内出现)
注意:macOS 把辅助功能和屏幕录制授权绑定在代码签名上,所以未签名的每次重新构建都会让授权失效,开关却仍显示为"开"——自己反复构建的话,按 desktop/README-signing.md 配一个固定的本地签名身份即可。
小结
Andee 的 macOS 版证明了"大脑与身体分离"这套架构的价值:core/ 里的智能体循环、提示词、记忆格式和守卫一个字节都没改,Mac 身体只是注册了新的 ToolProvider——真鼠标键盘、沙箱终端、通知管家。而它最可贵的不是能力清单,而是能力旁边的边界:风险分级、废纸篓、脱敏、按回合来源的硬拦截,全都写在代码里,不靠提示词"劝说"。想深入了解终端那套完整的设计推演,值得一读 docs/design/desktop-shell-tool.zh-CN.md。



