内容
align="center">
<imgsrc/hunch/assets/hunch.png"Hunch" width="128">
</# Hunch
**使用任意LLM驱动您的Mac：在后台无干扰，通过MCPHunch是一个服务器，为您的LLM代理直接操作：您的已安装登录会话、文件，而无需接。在您在继续工作的同时可以在后台读取应用的UI、点击通过AppleScript操作Mail或Music、填写或移动文件。它适用于真正的原生应用，而不仅仅是浏览器。
> **与现代LLM配合最佳。** Hunch附带了一份，作为MCP服务器指令；有能力的工具（Claude Sonnet/Opus-class及更高版本）可以很好地遵循它。较小的模型可能会选择更笨拙的路径（截图和按键而不是树读取和点击）。
## 四层架构
Hunch始终优先使用最直接的层。速度更快、更可靠，除了外，从及您的屏幕：
| 层级 | 工具 | |
|---|---| **OS-API `trash` `file_op` `open_file` `clipboard_*` `launch_app | 文件、剪贴板、应用生命周期API调用 |
AppleScript**applescript` | 可脚本化的应用：Mail、Messages、Notes、Calendar、Music、Finder、Safari … |
| **WebP** |` `web `web_act` `web_login` 任意浏览器页面或Electron应用，在 |
| **无障碍** | `snapshot` `act` | 任意原生应用的UI树、点击/选择/输入参考 |
条件的最后手段（`screenshot` + 坐标点击/按键）存在于那些无障碍树的应用。它会焦点，因此需要先。
## 工作原理（无服务器，无云“MCP服务器估了这种本地`hunch serve普通的Python您的MCPClaude Desktop、…）作为**子进程**启动，并JSON-RPC/stdout**（的标准输入输出通信。没有点，没有Hunch监听的端口，没有守护没有遥测您的主机退出时就会消失。
工具是直接的mac调用：在进程内通过pyobjc使用无、`osascript`用于AppleScript、文件/剪贴板的OS API，以及用于Web层的Socket到Chrome的端口（`0.0.1`）。唯一曾经接触Chrome本身，进行普通的浏览。模型看到您的主机；除此之外上没有任何其他内容离开。
## 安装
macOS 13+。通过Homebrew（在隔离环境中安装Python和所有依赖项）：
```bash
brew install prithviseran/hunch/hunch
```
（PyPI/pipx发布计划中；目前Homebrew是支持的路径。）
然后性：bash
setup # 完成macOS权限授予浏览器配置文件
hunch doctor # 验证级；修复的任何问题
connect claude # 或：cl，cursor
```
重启您的MCP主机它**“使用hunch来…”** 权限，诚实地说
macOS信任**运行服务器的应用**，这意味着您的MCP主机（、Cursor、您的而不是“hunch”`hunch setup`会引导您完成：
- **无障碍**（必需）：允许Hunch读取应用UI并在无焦点状态下点击。授予CP主机应用在系统 隐私和安全 → 无障碍。
- **自动化**（，自动）：首次脚本化应用时，会显示一次性“允许控制”提示。
屏幕录制**（可选）：仅用于截图备用。
`hunch报告已授予的内容。无障碍行反映运行它的**终端**继承**主机**的## 凭证：代理使用不看到它们
```bash
hunch creds --domain github.com
hunch creds list
```
值直接进入**macOS钥**。代理通过调用_fill_login("github")`进行登录，只有服务**名称**unch从钥匙串中读取秘密并通过CDP页面。值永远不会进入模型的上下文、其日志或者的服务器。
**域名绑定**：使用`--domain`添加的凭证将仅在`github.com`（及其）上输入。如果一个混淆或提示注入的到一个类似的页面将被拒绝。为每个凭证绑定；空白（任意站点）仅存在于兼容性。
没有存储的凭证？代理会回`web_login`，打开一个标记的浏览器在其中自己登录；在Hunch的专用浏览器配置文件中持续存在。
## 确认门
您的MCP主机的工具审批是主要的权限层。Hunch添加了一个内容感知的第二道门，一个单击的macOS对话框，用于灾难性情况：
| 门 | 触发条件 |
|---|---|
| `gates.focus_steal` | 占用您的键盘/光标的操作（`key`、`click_xy`，无参考输入） |
| `gates.app_to_front` | 应用程序被带到前台（焦点切换，甚至全屏） |
| `gates.shell` | 包含`do shell script`的AppleScript |
| `gates.destructive_applescript` | 删除/发送/清空回收站/关闭/… |
一次批准涵盖其后续操作：点击“继续”（在`request_focus`、 gated `act`或应用前台对话框上）授权它宣布的切换约15秒：无需第二个对话框，并且焦点切换通知被抑制。切换要么被**询问**，要么被**宣布**，从不两者兼而有之，从不静默（关闭`gates.app_to_front`，切换回通知）。
全部默认开启。`hunch config show` / `hunch config set gates.shell off` 进行调整；更改立即生效，甚至适用于正在运行的服务器。`auto_approve_all` 禁用所有功能，并要求您确认了解 [风险](SECURITY.md)。
Hunch 还拒绝让代理通过其文件工具编辑 `~/.hunch/`（其自己的策略和数据）；权限更改适用于终端中的人类。
## 环境变量
| 变量 | 效果 |
|---|---|
| `HUNCH_NO_INTERNAL_GATE=1` | 禁用所有内部对话框（适用于运行自己的审批UX的主机应用） |
| `HUNCH_FORCE_SANDBOX=1` | web层使用一次性、注销的浏览器配置文件 |
| `HUNCH_NOTIFY_FOCUS=0` | 静默“Hunch正在切换应用”的通知（仅在无需对话框询问的切换中触发） |
## 常见问题
**每次树读取返回“（无窗口...）”并且AppleScript失败，错误为“-25211不允许辅助访问”。** 一个原因：托管Hunch的应用缺少**无障碍**授予。没有它，AX API会默默地返回空值，因此应用即使打开也显得无窗口。将其授予**主机**（参见下一个问题），如果它已经列出，请切换关闭和打开：macOS在应用更新时默默地使授予失效。之后重启主机。
**我应该为哪个应用授予权限？** 启动`hunch serve`的应用：Claude Desktop、Cursor或您的终端应用（用于Claude Code）。授予附加到该应用的身份，从不附加到“hunch”本身。这也是为什么`hunch doctor`可能具有误导性：它报告了您运行它的**终端**的授予，这可能与您的MCP主机的授予不同。
**只有`screenshot`失败；其他一切都正常工作。** 这是**屏幕录制**权限，仅需要截图/视觉备用。将其授予主机在系统设置 → 隐私和安全 → 屏幕录制中，或让代理使用`snaphot`，它不需要该权限。
**昨天它工作，今天却报错了。** 您的主机应用（或macOS）更新可能重置权限授予。在无障碍（和屏幕录制，如果您使用它）下切换主机关闭和打开，然后重启主机。
**应用的树读取为空或仅显示侧边栏。** 两种不同的情况。Electron/CEF应用（Discord，Slack，Spotify，VS Code）需要无障碍标志；`snapshot`在后台重新启动它们一次以设置它。主从和Catalyst应用（WhatsApp，Mail）仅显示您所在的窗格：代理应通过引用点击项目并重新快照；然后详细窗格出现。还请检查应用是否确实有窗口打开。
**Web层无法连接。** Chrome 136+出于设计考虑阻止了默认配置文件上的CDP。Hunch使用其自己的配置文件`~/.hunch/chrome-cdp`；运行`hunch setup`以创建它并在那里登录您的网站。
**我的主机显示服务器指令被截断。** 美观：一些主机UI在服务器信息显示中缩短了攻略；模型接收到完整的攻略。
## 安全
阅读 [SECURITY.md](SECURITY.md)：威胁模型（主要是提示注入），门控的作用和不覆盖的内容，以及如何报告漏洞。
## 许可证
Apache-2.0；参见 [LICENSE](LICENSE)。
MCP 市场