francismiko WeChat macOS Automation
通过 macOS 辅助功能 API 控制微信桌面客户端，实现消息收发和聊天记录浏览。
前提条件
- 微信 macOS 版已安装并登录
- 辅助功能权限已授予终端应用和 claude CLI（系统设置 → 隐私与安全性 → 辅助功能）
- cliclick 已安装（
brew install cliclick）
如果用户遇到权限错误（"不允许辅助访问"），引导他们到系统设置添加对应程序。需要授权的程序：终端应用（如 Warp、iTerm2）和 /opt/homebrew/Caskroom/claude-code/*/claude。
工具库
所有操作封装在 scripts/wechat-utils.sh 中。使用前先 source：
source ~/.agents/skills/wechat-automation/scripts/wechat-utils.sh
踩坑指南（必读）
以下是实际操控中验证过的经验，违反这些规则会导致操作失败：
绝对不要做
| 操作 | 后果 | 正确做法 |
|---|---|---|
用 Cmd+F 搜索会话 |
打开全局搜索（含网络/公众号搜索），不是会话搜索 | 用 wechat_open_chat 点击侧边栏搜索框 |
用 Cmd+N 找已有会话 |
创建新群聊 | 用 wechat_open_chat |
用 keystroke 输入中文/emoji |
输入为空或乱码 | 用 wechat_paste 通过剪贴板粘贴 |
| 不移动鼠标直接滚动 | 滚到别的窗口 | 先 wechat_move 到聊天区域再 wechat_scroll |
| 用 Page Up/Down 翻页 | 焦点跳到别的应用 | 用 wechat_scroll_chat |
| 搜索后不清理输入框 | 残留文字被当消息发出 | wechat_open_chat 已内置清理；wechat_send_message 也会先清空 |
必须做
- 截屏验证：UI 自动化天生不稳定。关键操作后调用
wechat_screenshot+ Read 工具确认状态 - 激活后缓存窗口信息：
wechat_activate会自动缓存窗口坐标，后续操作复用，避免重复查询 - 滚动前定位鼠标：
wechat_scroll_chat已内置移动鼠标逻辑，直接用它而不是裸调wechat_scroll
可用操作
基础操作
| 函数 | 参数 | 说明 |
|---|---|---|
wechat_activate |
— | 激活微信窗口、置顶、缓存窗口坐标 |
wechat_screenshot [path] |
输出路径 | 截取当前屏幕 |
wechat_paste "文本" |
文本内容 | 通过剪贴板粘贴（唯一正确的输入方式） |
wechat_key keycode |
key code | 模拟按键（36=回车, 53=ESC, 51=删除） |
wechat_cmd "key" |
字符 | 模拟 Cmd+key |
wechat_click x y |
坐标 | 点击 |
wechat_move x y |
坐标 | 移动鼠标（滚动前必须调用） |
wechat_scroll dir count |
up/down, 次数 | 在鼠标当前位置滚动 |
组合操作
| 函数 | 参数 | 说明 |
|---|---|---|
wechat_open_chat "名称" |
联系人/群名 | 点击侧边栏搜索 → 粘贴 → 回车 → ESC 关闭搜索面板 |
wechat_scroll_chat dir count |
up/down, 次数 | 移动鼠标到聊天区域 → 滚动 |
wechat_send_message "消息" |
消息文本 | 点击输入框 → 清空 → 粘贴 → 回车，自动追加签名 |
高级操作（支持后台模式）
| 函数 | 参数 | 说明 |
|---|---|---|
wechat_send_to "名称" "消息" [bg] |
联系人、消息、后台(默认true) | 完整流程：激活 → 搜索 → 发送 → 切回 |
wechat_read_chat [scroll] [path] [bg] |
滚动次数、路径、后台 | 截屏当前会话 |
wechat_view_chat "名称" [scroll] [path] [bg] |
联系人、滚动、路径、后台 | 搜索会话 → 截屏 |
后台模式（默认开启）：操作前保存当前前台应用和剪贴板，操作后恢复。微信只需短暂前台 3-5 秒。
使用模式
发消息
source ~/.agents/skills/wechat-automation/scripts/wechat-utils.sh
wechat_send_to "张三" "你好" true
查看聊天记录
截屏 + Read 工具读取分析：
source ~/.agents/skills/wechat-automation/scripts/wechat-utils.sh
wechat_view_chat "群名" 80 /tmp/chat.png true
# 然后 Read /tmp/chat.png 查看内容
连续浏览历史
如果已在目标会话中，不要再调 wechat_open_chat（会重新搜索），直接滚动：
source ~/.agents/skills/wechat-automation/scripts/wechat-utils.sh
wechat_activate
# 假设已在目标会话中
for i in 1 2 3 4 5; do
wechat_scroll_chat up 100
wechat_screenshot "/tmp/chat-${i}.png"
done
# 批量 Read 截图分析
截屏驱动的操控模式
对于不确定的场景，采用「截屏 → 分析 → 操作 → 截屏验证」循环：
source ~/.agents/skills/wechat-automation/scripts/wechat-utils.sh
wechat_activate
wechat_screenshot /tmp/step1.png # 看当前状态，Read 分析
# 根据截图决定下一步...
wechat_open_chat "某人"
wechat_screenshot /tmp/step2.png # 确认进入正确会话
wechat_send_message "你好"
wechat_screenshot /tmp/step3.png # 确认发送成功
故障排查
| 症状 | 原因 | 解决 |
|---|---|---|
| "不允许辅助访问" | 缺少辅助功能权限 | 系统设置 → 辅助功能，添加终端和 claude CLI |
| 搜索打开了网络结果 | 误用了 Cmd+F | 用 wechat_open_chat（点击侧边栏搜索框） |
| 滚动滚到了别的窗口 | 鼠标不在微信上 | 用 wechat_scroll_chat 而非裸调 wechat_scroll |
| 发出了群名当消息 | 搜索残留未清理 | wechat_send_message 已内置清空逻辑 |
| 点到了公众号/其他页面 | 窗口坐标偏移 | 先 wechat_activate 刷新坐标缓存 |
详细的按键码和 UI 布局信息见 references/key-codes.md。