# 使用应用快照

> 在 macOS 上按住左右同一功能键，把前台窗口的截图与文字挂到输入框，让 Agent 理解你此刻的屏幕。

Canonical page: /product/app-snapshot



<Takeaways>
  <li>
    应用快照只在 macOS 提供，默认关闭
  </li>

  <li>
    抓取由独立的 Vetta Computer Use 辅助程序完成，需要单独授权
  </li>

  <li>
    捕获结果是附件，不会自动发送，你仍可以先补充说明再提问
  </li>
</Takeaways>

应用快照解决的是「我说不清屏幕上这一块是什么」。同时按住键盘左右两侧的同一个功能键约 0.25 秒，Vetta 会抓取**当前前台窗口**的截图和可读文字，作为附件挂到输入框，并把主窗口带到前台定位到新会话。它不是全屏录制，也不是持续监视：只在你做出手势的那一刻抓一次。

入口：**设置 → 应用快照**（仅 macOS 显示）。

<MediaFrame>
  <img src="/images/product/app-snapshot.webp" alt="Vetta 设置中的应用快照页，上方是触发方式选择与键盘示意图，下方是辅助功能与屏幕录制权限状态" width="1920" height="1275" />

  <figcaption>
    触发方式决定按哪一对功能键；权限区域显示辅助程序当前是否已获授权。
  </figcaption>
</MediaFrame>

## 开启并授权 [#开启并授权]

<Steps>
  <Step>
    ### 选择触发方式 [#选择触发方式]

    在 **触发快捷键 → 触发方式** 中选择一组功能键：同时按住左右 ⇧、左右 ⌘ 或左右 ⌥。选择「不启用」即关闭该功能。修改后立即生效，不需要重启。
  </Step>

  <Step>
    ### 授权辅助程序 [#授权辅助程序]

    应用快照通过独立的 **Vetta Computer Use** 辅助程序读取前台窗口，它是独立的授权主体，授权给 Vetta 主程序不能替代。首次开启时若权限不全，Vetta 会自动打开授权引导窗；也可以随时点击 **打开授权引导**，把窗口中的图标拖进系统权限列表完成授权。
  </Step>

  <Step>
    ### 确认权限状态 [#确认权限状态]

    回到设置页的 **权限** 区域，确认「辅助功能」和「屏幕录制」都显示为已授予。该区域在窗口重新获得焦点时会刷新。
  </Step>

  <Step>
    ### 试抓一次 [#试抓一次]

    切到任意其它应用窗口，按住选定的左右功能键。听到系统截图音效、主窗口弹出并在输入框看到快照卡片，即表示链路已通。
  </Step>
</Steps>

<Callout title="手势监听还需要输入监控权限" type="info">
  全局手势与快捷面板共用同一套键盘监听。若按住功能键完全没有反应，请在「系统设置 › 隐私与安全性 › 输入监控」中确认已授权 Vetta。
</Callout>

## 需要哪些权限 [#需要哪些权限]

| 权限   | 授权主体               | 缺失时的后果             |
| ---- | ------------------ | ------------------ |
| 辅助功能 | Vetta Computer Use | 读不到窗口标题、文档路径和窗口内文字 |
| 屏幕录制 | Vetta Computer Use | 抓不到截图，只保留文字与元信息    |
| 输入监控 | Vetta              | 手势不触发，功能完全不响应      |

两项辅助程序权限都缺失时，Vetta 会把主窗口带到前台并提示去权限管理授权，不会产生附件。只缺其中一项时仍会尽力抓取另一半。

## 一次捕获包含什么 [#一次捕获包含什么]

| 内容       | 来源   | 说明                                           |
| -------- | ---- | -------------------------------------------- |
| 窗口截图     | 屏幕录制 | 仅前台窗口，PNG                                    |
| 窗口文字     | 辅助功能 | 以 Markdown 落盘，带 app、window、captured\_at 等元信息 |
| 源文件路径    | 辅助功能 | 前台窗口正在编辑的文档路径（若可读取）                          |
| 应用名与窗口标题 | 辅助功能 | 作为附件卡片的标题显示                                  |

文字层只取辅助功能能读到的内容。抓不到文字时不会在捕获阶段做 OCR，而是只带截图交给模型用视觉能力理解。截图、图标和文字文件写入 `~/.vetta/image-cache/appshot/`，与图片缓存共用清理策略，长期未使用的缓存目录会被自动清除。

## 捕获之后 [#捕获之后]

* 附件以快照卡片的形式停留在输入框，可点击预览大图，也可以移除。
* 快照不会自动发送。补充一句你真正想问的问题再发送，效果明显好于只丢一张图。
* 发送后截图与文字一起作为附件进入会话，消息气泡里保留快照卡片。
* 未发送的快照会随输入框草稿一起保留，切走再回来不会丢。

## 触发没有生效时 [#触发没有生效时]

1. 确认前台窗口不是 Vetta 自己：抓取自身窗口会被主动忽略并提示。
2. 确认左右两侧的功能键**同时按住**并保持约 0.25 秒，先后按下或一触即放不会触发。
3. 确认设置里的触发方式不是「不启用」，且没有被其它全局快捷键抢占同一组键。
4. 出现「捕获失败」提示时，先看 **权限** 区域状态，再重新走一次授权引导；辅助程序被系统隔离或缺失时，重新安装应用可恢复。
5. 连续做手势只会跑一次捕获：上一次还在进行时新的手势会被忽略，稍等再试。

## 隐私边界 [#隐私边界]

* 捕获是手势触发的一次性动作，没有后台常驻录屏。
* 抓取范围限定为前台窗口，不包含其它应用窗口和桌面其余部分。
* 快照落在本机 `~/.vetta` 目录；只有当你发送这条消息时，内容才会随会话进入所选模型。
* 屏幕上有密码、密钥或客户数据时，先切走窗口再做手势，或在发送前移除附件。

<Continue>
  <ContinueLink href="/product/settings/" title="设置参考" description="按入口查找模型、权限、快捷键和环境配置。" />

  <ContinueLink href="/reference/security-and-data/" title="安全与数据边界" description="理解截图、附件与模型之间的数据边界。" />
</Continue>