深色模式
MCP 工具参考
AgileShot 的 MCP Server 当前共暴露 60 个工具。下面先给 10 个基础工具的完整签名， 再列出其余 50 个的分组清单。
参数以本页为准
下面 10 个工具的参数名与源码逐一核对过。注意几个易错处：截图历史类用 id 而不是 shot_id，搜索用 keyword 而不是 query，区域截图用 w / h 而不是 width / height。
安全门控（先读这段）
工具分两个安全等级，行为差别很大：
| 等级 | 含义 | 举例 |
|---|---|---|
| Readonly | 只观察，任何档位都放行 | 截图、枚举窗口、读元素、查历史 |
| Mutating | 会动状态，受门控约束 | 点击、输入、删历史、标注 |
键鼠自动化那批（Phase C 起）走三层门控：opt-in 开关 + armed 总闸 + 敏感焦点检测。另外还有「用户在场让路」——你一动手，AI 的自动化操作就暂停， 只读工具不受影响（AI 可以继续观察，不打扰你）。
截图
screenshot_fullscreen
截取全屏（光标所在的那个屏）。返回 PNG 图像内容。
参数: 无
screenshot_region
按虚拟桌面逻辑坐标截取矩形区域。
参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
x | integer | ✅ | 左上角 x（虚拟桌面逻辑坐标） |
y | integer | ✅ | 左上角 y |
w | integer | ✅ | 宽 |
h | integer | ✅ | 高 |
screenshot_active_window
截取当前前台窗口（自动取窗口边界）。
参数: 无
历史管理
list_recent_shots
列出最近的历史截图（只含文件名与元信息，不含图像内容）。
参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
count | integer | 否 | 取几条，默认 10，范围 1–100 |
get_shot
按历史 id 取出截图（返回图像内容）。
参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | ✅ | 历史 id，来自 list_recent_shots / search_shots |
search_shots
按关键词搜索历史，匹配文件名与 OCR 文本。
参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
keyword | string | ✅ | 关键词 |
limit | integer | 否 | 返回条数，默认 20，范围 1–200 |
delete_shot
按 id 从 AgileShot 历史里移除一条。
参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | ✅ | 历史 id |
它删的是哪一份
只删 AgileShot 自己的内部全分辨率副本（确实会释放相应磁盘空间）， 不动你保存目录里的原图 —— 那个文件还在。如果这张图是当次截的， 结果里已经给过原图完整路径；更早的历史条目 MCP 只暴露文件名、不给路径。
count_shots
返回历史截图总数。
参数: 无
屏幕信息
get_screen_info
取屏幕拓扑（屏数、各屏几何、各屏 DPR）与当前光标位置。
参数: 无
标注
annotate_image ⭐
在一张历史截图上叠加标注，返回标注后的 PNG。这是「让 AI 直接在图上画给你看」的工具。
参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | ✅ | 历史 id |
annotations | array | ✅ | 标注项数组，字段见下 |
每个标注项:
| 名 | 类型 | 说明 |
|---|---|---|
type | string | rect / ellipse / arrow / line / highlight / text |
x y | integer | 起点坐标 |
w | integer | rect 为宽；arrow 为终点相对 x；text 忽略 |
h | integer | rect 为高；arrow 为终点相对 y；text 忽略 |
text | string | type=text 时必填 |
color | string | hex，如 #FF3B30，默认红 |
thickness | integer | 线宽，默认 3 |
fontPx | integer | 字号，默认 18 |
json
{
"id": 128,
"annotations": [
{ "type": "rect", "x": 100, "y": 100, "w": 200, "h": 50, "color": "#FF3B30", "thickness": 3 },
{ "type": "text", "x": 100, "y": 170, "text": "这里报错", "fontPx": 18 }
]
}其余 50 个工具
这些是 v0.12.0 起陆续加入的桌面操作能力（AgileShot 独占的那部分 —— 让 AI 不只是 「看屏幕」，还能在屏幕上动手）。逐个参数尚未整理进本页，工具名与分组如下， 调用时可让 MCP 客户端读 tools/list 拿实时 schema。
窗口与截图补充（5）screenshot_window（按 hwnd / title 直接截窗口自身，绕遮挡，能截被挡住或最小化的窗口）· screenshot_element（截单个 UI 元素）· screenshot_with_marks（带编号框的截图， 让模型选编号而不是猜坐标）· list_visible_windows（按 Z 序列可见顶层窗口）· activate_window（按 hwnd / title 激活 / 还原 / 置顶，会切前台焦点）
历史与钉图补充（3）get_shot_ocr_text（读已存的 OCR 文本）· copy_shot_to_clipboard · pin_shot（把历史截图钉成桌面贴图）
键鼠自动化（7）cursor_position · mouse_move · click · drag · scroll · type_text · press_key
UI Automation 元素级（8） — 精准操作，不靠猜坐标 list_ui_elements · click_element_by_id · element_from_point · type_into_element · get_element_state · wait_for_element · scroll_element_into_view · wait_for_ui_idle
OCR / 文本定位（4） — 打通没有 UIA 元素的 Electron、Canvas、老程序 find_ocr_text · click_ocr_text · click_text · click_mark
文本选择与剪贴板（4）get_selected_text · select_text · clipboard_get · clipboard_set
窗口控制与诊断（4）window_control（最大化 / 最小化 / 关闭 / 移动）· read_window_text · compare_screenshots · diagnose_coordinates
弹窗处理（2） — agent 最常卡在这里 dismiss_dialog（只放行无副作用的「确认 / 知晓」类按钮）· handle_file_dialog（原生文件框）
后台模式（11） — 操作独立窗口，不抢你的前台焦点 background_start · background_stop · background_launch · background_windows · background_elements · background_click · background_type · background_press_key · background_scroll · background_screenshot · background_ocr
其他（2）launch_app · get_presence_state（让 AI 主动查「现在能不能动手」）