# Desktop

> 桌面操控。让 CC 看屏幕、动鼠标、点按钮、输文字。基于 macOS 原生 OCR 触觉反馈，不截全屏传 AI，极致省 token。触发词："/desktop"、"帮我操作桌面"、"点一下那个按钮"、"看看屏幕上有什么"

- Skill: `aster110/desktop` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add aster110/desktop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aster110/desktop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aster110 (https://skillmd.com/u/aster110)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aster110/desktop

---


# Desktop — CC 桌面操控

## 核心理念：触觉反馈

不截全屏传 AI（慢、贵），而是用 macOS 原生 OCR 当"触觉"。
鼠标移到哪 → OCR 哪 → Agent 知道手在哪、摸到什么。

## CLI 工具栈

所有操作通过 Bash 调 CLI 工具完成：

```bash
# ===== 眼（感知） =====

# OCR 工具路径（ocr.py 在本 skill 目录下，venv 在 ~/tools/ocr-env/）
SKILL_DIR=".claude/skills/desktop"
OCR="$HOME/tools/ocr-env/bin/python3 $SKILL_DIR/ocr.py"

# 全屏 OCR（快速模式，~240ms，注意：中文必须用精确模式）
$OCR --screen --fast

# 全屏 OCR + JSON 包围盒（精确模式，~870ms）
$OCR --screen --bbox

# 鼠标附近 OCR（触觉，~250ms，默认 300x200）
$OCR --cursor

# 鼠标附近 OCR + JSON（带可点击坐标）
$OCR --cursor --bbox

# 鼠标附近 OCR（自定义区域大小）
$OCR --cursor --size 200x100

# 指定图片 OCR
$OCR /path/to/image.png

# ===== 手（操控） =====

# 获取鼠标位置
cliclick p:.

# 移动鼠标
cliclick m:500,300

# 点击
cliclick c:500,300

# 双击
cliclick dc:500,300

# 右键
cliclick rc:500,300

# 输入文字
cliclick t:"Hello World"

# 按键（回车、Tab 等）
# 注意：cliclick kp:return 在微信等部分应用中无效，优先用 osascript
osascript -e 'tell application "System Events" to key code 36'   # Return（推荐）
cliclick kp:return                                                # Return（备选）
cliclick kp:tab
cliclick kp:escape

# 键盘快捷键
osascript -e 'tell application "System Events" to keystroke "c" using command down'
osascript -e 'tell application "System Events" to keystroke "v" using command down'
osascript -e 'tell application "System Events" to keystroke "s" using command down'
osascript -e 'tell application "System Events" to keystroke "a" using command down'

# ===== 感知（窗口/应用状态） =====

# 当前可见应用列表
osascript -e 'tell application "System Events" to get name of every process whose visible is true'

# 当前前台窗口信息
osascript -e 'tell application "System Events" to get {name, position, size} of every window of (first process whose frontmost is true)'

# 切换到指定应用
osascript -e 'tell application "APP_NAME" to activate'

# 点击菜单
osascript -e 'tell application "System Events" to click menu item "ITEM" of menu "MENU" of menu bar 1 of process "APP"'

# 全屏截图（传 Claude 视觉兜底时用）
screencapture -x /tmp/desktop-screenshot.png

# 局部截图
screencapture -x -R "x,y,w,h" /tmp/desktop-region.png
```

## 操作流程

### 标准流程：点击按钮

```
1. 全屏 OCR 找目标
   $OCR --screen --fast
   → 找到 "保存" @ (550, 300)

2. 移动鼠标 + 触觉确认
   cliclick m:550,300
   $OCR --cursor --size 200x100
   → 确认 "保存" 在鼠标下方 ✓

3. 点击
   cliclick c:550,300

4. 触觉验证结果
   $OCR --cursor
   → 确认操作成功
```

### 快捷流程：已知坐标直接点

```
cliclick c:550,300
```

### 文字输入

```
1. 点击输入框
   cliclick c:400,200

2. 清空（全选+删除）
   osascript -e 'tell application "System Events" to keystroke "a" using command down'
   cliclick kp:delete

3. 输入文字
   cliclick t:"要输入的内容"
```

### OCR 找不到时的兜底

```
1. 全屏截图
   screencapture -x /tmp/desktop-screenshot.png

2. 用 Read 工具读取截图（Claude 视觉）
   → Claude 自动分析截图内容

3. 根据 Claude 的分析结果决定操作
```

## 安全规则

| 级别 | 操作 | 策略 |
|------|------|------|
| 绿色 | 截图、OCR、读剪贴板、列窗口、移动鼠标 | 自动执行 |
| 黄色 | 点击、输入文字、切换窗口 | 执行并告知用户 |
| 红色 | 涉及密码、支付、删除、发消息 | 先问用户 |

**禁区**：
- 不操控 Terminal/iTerm（防 GUI 绕过权限控制）
- 不输入密码
- 不操作支付页面
- 不修改系统安全设置

## OCR 输出格式

### 简洁模式（默认）
```
cursor: (516,703)  ocr: 277ms
  [0.50] 上线的时候记得把密码改强一点  @ (665,678)
  [0.50] 己置那个上游的api 呢？  @ (508,744)
```

### JSON 模式（--bbox）
```json
{
  "cursor": [516, 703],
  "elapsed_ms": 243,
  "items": [
    {
      "text": "保存",
      "confidence": 0.98,
      "bbox": [540, 290, 60, 30],
      "center": [570, 305]
    }
  ]
}
```

`center` 是文字中心坐标，可直接传给 `cliclick c:` 点击。

## 性能参考

| 操作 | 耗时 |
|------|------|
| 鼠标移动/点击 | < 10ms |
| 局部 OCR（300x200） | ~250ms |
| 全屏 OCR（快速） | ~240ms |
| 全屏 OCR（精确） | ~870ms |
| 获取窗口列表 | < 50ms |

## 微信操控脚本

本 skill 目录下有三个微信操控脚本，封装了完整的读/发/验证流程：

```bash
SKILL_DIR=".claude/skills/desktop"

# 读取当前聊天内容（OCR 聊天区域，排除标题栏和输入框）
$SKILL_DIR/wechat-read.sh              # 简洁文字
$SKILL_DIR/wechat-read.sh --bbox       # JSON 包围盒

# 发送文字消息（自动验证：OCR 输入框 count==0 = 成功）
$SKILL_DIR/wechat-send.sh "消息内容"

# 发送文件/图片（剪贴板 POSIX file → 粘贴 → 回车 → OCR 验证）
$SKILL_DIR/wechat-send-file.sh /path/to/file
```

### 使用前提
- 微信已打开并停留在目标聊天窗口
- 需要 cliclick（`brew install cliclick`）
- 需要 OCR 环境（`~/tools/ocr-env/`，pyobjc + Vision Framework）

### 关键参数（脚本内固定）
- `SIDEBAR=310`：微信侧边栏固定宽度（图标60 + 列表250）
- `TITLE_H=50`：顶部标题栏高度
- `INPUT_H=110`：底部输入框+工具栏高度

### 注意事项
- **中文 OCR 不用 --fast**：fast 模式中文乱码，脚本默认用精确模式
- **坐标动态获取**：每次操作前 `osascript get {position, size}`，不硬编码
- **焦点防抢**：activate + delay 写在同一个 osascript block 里