Skip to content

LAVARONG/wechat-automation-api

wechat-automation

Verified

微信发信能力:通过 Windows 桌面微信发送文本、图片URL或本地文件。适合各类 Agent 在本机直接发送一次性消息。触发词:给[某人]发微信、通知[某人]、把这个用微信发给[某人]、用微信发个图片、把本地文件发给[某人]

FileKindSize
SKILL.mdskill md9.9 KB
examples/README.mdmarkdown819 B
examples/monitor_wechat_messages.pyscript11.9 KB
examples/wx.pyscript2.1 KB
scripts/app.pyscript8.4 KB
scripts/message_queue.pyscript10.6 KB
scripts/monitor.pyscript4.4 KB
scripts/skill_cli.pyscript6.2 KB
scripts/test_wpush.pyscript2.5 KB
scripts/wechat_controller.pyscript57.6 KB
---
name: "wechat-automation"
description: "微信发信能力:通过 Windows 桌面微信发送文本、图片URL或本地文件。适合各类 Agent 在本机直接发送一次性消息。触发词:给[某人]发微信、通知[某人]、把这个用微信发给[某人]、用微信发个图片、把本地文件发给[某人]"
---

# 微信自动发信 Skill

赋予智能体掌控 Windows 桌面微信直接向真实用户或群组发送文本、图片URL或本地文件的能力。本 Skill 默认以同步命令行方式运行,执行一次命令发送一次消息,命令结束后立即退出。

只发送微信消息时,不需要专门启动后台 HTTP API,不需要运行 `run.bat`,也不需要调用 `scripts/app.py`。但**如果后台 HTTP API 恰好已在运行**,本 Skill 会**自动改走 API 队列模式**发送,以避免多个请求同时直接操作微信窗体造成冲突,详见下文「执行模式与结果判定」。

## 应用场景

- **信息推送**:当你作为智能体完成了某项长耗时的搜索、总结或生图任务后,可以将最终结果或报告链接直接通过微信发送给用户指定的联系人。
- **定时催办/打卡通知**:结合智能体的定时任务机制,向目标群组发送通知。
- **跨平台转发**:将抓取到的内容(特别如新闻图片、数据图表链接)作为微信信息直接转发。
- **任务链收尾**:先完成搜索、分析、运行命令、生成报告等任务,再把最终摘要或结果通过微信发送给指定联系人或群。
- **本地文件转发**:把 Agent 生成的报告、截图、表格、压缩包、本地图片等文件直接发给指定联系人或群。

## 典型触发语句

- “帮我给 **LAVA** 发个微信,就说**我今天晚点到**。”
- “把刚才总结的**会议纪要**发到**工作群**里。”
- “下载这个图片,用微信发给 **文件传输助手**。”
- “帮我通知一下 **张三**,让他**明天带电脑**。”
- “查询今天关于 **AI** 的最新新闻,整理成简洁总结,然后通过微信发送到联系人 **文件传输助手**。”
- “把这次运行结果总结整理,通过微信发送到 **项目通知群**。”
- “把本机上的 **C:\tmp\report.xlsx** 通过微信发送给 **文件传输助手**。”
- “把刚生成的截图发到 **项目群**。”

## 作为 Skill 调用的规范指令

本 Skill 调用后会直接返回结果并退出,不会常驻内存。请在项目根目录中使用以下语法调用:

### 发送文本消息

```powershell
python scripts/skill_cli.py --to "联系人或群组名称" --content "你要发送的具体文本"
```

### 发送图片消息

```powershell
python scripts/skill_cli.py --to "联系人或群组名称" --content "https://example.com/image.png" --action "sendpic"
```

如果 `sendpic` 的 `--content` 是本地路径,则不会下载图片,会直接按本地文件复制并粘贴到微信。

### 发送本地文件或本地图片

```powershell
python scripts/skill_cli.py --to "联系人或群组名称" --content "C:\path\to\file.zip" --action "sendfile"
```

本地图片、PDF、Office 文档、压缩包等都使用 `sendfile`。Agent 发送自己刚生成的文件时,应优先使用绝对路径。

### 发送测试

首次安装或接入 Agent 后,优先向“文件传输助手”发送测试消息:

```powershell
python scripts/skill_cli.py --to "文件传输助手" --content "这是一条来自 Agent Skill 的测试消息"
```

stdout 输出 `发送成功` 表示任务完成。stdout 输出 `发送失败` 或 `执行异常` 时,应将错误信息原样反馈给用户。

如需更稳定地解析结果,可追加 `--json`:

```powershell
python scripts/skill_cli.py --to "文件传输助手" --content "测试消息" --json
```

JSON 输出字段包含 `success`、`code`、`message`、`to`、`action`。`success=true` 表示发送请求已被成功受理;`success=false` 表示未成功(同步模式下即为发送失败,详见下文模式说明)。

## 执行模式与结果判定

本 Skill 有两种执行模式,默认会**自动选择**:

- **同步 CLI 模式**(默认,且后台 API 未运行时):直接操作微信窗体发送,命令返回的 `success` 即为**真实发送结果**。失败会给出 `CONTACT_NOT_FOUND`、`WECHAT_WINDOW_NOT_FOUND` 等具体 `code`。需要确切知道"是否真的发出去了"时用这个模式。
- **API 队列模式**(后台 `app.py` / `run.bat` 已在运行,且 `config.json` 配好 `token` 时自动启用):把消息提交到后台 HTTP 队列,由后台串行异步发送,多个请求不会互相抢占微信窗体。**注意:此模式下 `success=true` 仅表示"消息已入队受理",并不代表已成功送达**;真实发送结果需查询后台 `GET /status` 或服务端日志 `wechat_automation.log`。

可用以下参数显式指定模式(不加则自动判定):

| 参数 | 作用 |
| --- | --- |
| `--no-api` | 强制同步 CLI 模式,跳过 API 自动检测,确保拿到真实发送结果 |
| `--api` | 强制 API 队列模式(需先启动后台服务并配置 `token`,否则报错) |
| `--lock-mouse` | 发送期间临时锁定鼠标,防止用户误触干扰(同步 CLI 模式生效) |
| `--no-lock-mouse` | 发送时不锁定鼠标(默认使用 config.json 的 lock_mouse_during_send 配置) |

```powershell
# 强制同步发送并拿真实结果(不论后台 API 是否在运行)
python scripts/skill_cli.py --to "文件传输助手" --content "测试消息" --no-api --json
```

**给 Agent 的判定建议**:常规发信依据退出码与 `success` 判断任务是否被受理即可;若任务**必须确认真实送达**(如重要通知),请追加 `--no-api` 走同步模式,再据 `code` 反馈用户。

## 安装与运行环境

1. Windows 10/11,微信 PC 客户端已启动并登录。
2. 在项目根目录安装依赖:`pip install -r requirements.txt`。
3. Agent 执行本 Skill 时,工作目录应为本项目根目录,确保 `python scripts/skill_cli.py ...` 可以找到 `scripts/wechat_controller.py`。
4. 不要为普通发消息任务启动后台 HTTP API;HTTP API 只用于长期服务、队列和外部系统集成。

## 系统辅助功能启用

若运行环境为精简版或 Ghost 系统,需确保 Windows 辅助功能正常运行。通过键盘 Win 键唤出开始菜单,输入“讲述人”并开启该功能(开启后可立即关闭),此操作可确保系统底层 UI 自动化接口处于激活状态,避免程序无法识别元素。

## 注意事项与约束

1. **必须精确匹配名称**:`--to` 参数指定的联系人或群组名称必须与微信内的备注或网名**完全一致**(区分大小写和空格),否则可能导致发送失败或发错人。
2. **直接执行命令**:不要试图使用视觉模型去理解或分析微信页面。直接执行上述命令行命令即可,底层脚本已封装窗体查找、联系人搜索和发送操作。
3. **识别执行结果**:执行后请读取 stdout 和退出码。退出码 `0` 表示请求已被受理;退出码非 `0` 表示失败。如果输出 `发送失败` 或 JSON 中 `success=false`,请**原封不动**把 `message` 和 `code` 反馈给用户,不要擅自循环重试。注意:当输出为 `消息已提交发送队列受理…` 时表示走了 API 队列模式(异步),仅代表受理成功;需确认真实送达请改用 `--no-api`。
4. **长文本分段发送**:如果要发送的文字内容超过 2000 字,Agent 应主动拆成多段,分多次调用本 Skill 发送。每段建议不超过 2000 字,并在内容开头标明序号,例如 `【1/3】...`、`【2/3】...`、`【3/3】...`。
5. **特殊字符支持**:内容中可以直接包含换行符(`\n`)或表情符号文本,脚本层会自动处理转义与输入,请放心传入。
6. **本地文件用绝对路径**:发送本机文件或本机图片时,优先传绝对路径,例如 `C:\tmp\report.pdf`。相对路径会按当前工作目录解析。
7. **避免重复发送**:失败后不要自动多次重试,除非用户明确要求。

## 异常处理与反馈

CLI 会尽量给出明确失败原因,常见 `code` 包括:

- `WECHAT_WINDOW_NOT_FOUND`:未找到微信窗口。请确认微信 PC 已启动并登录;精简版或 Ghost 系统可按“系统辅助功能启用”处理。
- `CONTACT_NOT_FOUND`:未找到联系人或群组。请确认 `--to` 与微信备注、联系人名或群名完全一致。
- `SEARCH_BOX_NOT_FOUND`:未找到微信搜索框。可能是微信 UI 结构变化、窗口未加载完成或系统 UI 自动化不可用。
- `CHAT_INPUT_NOT_FOUND`:未找到聊天输入框。可能未成功进入目标会话,或微信 UI 结构变化。
- `CLIPBOARD_TEXT_FAILED`:文本写入剪贴板失败。请检查系统剪贴板、`pyperclip` 或远程桌面会话状态。
- `IMAGE_DOWNLOAD_FAILED` / `IMAGE_URL_NOT_IMAGE`:图片 URL 下载失败或返回内容不是图片。
- `IMAGE_CLIPBOARD_FAILED`:图片复制到剪贴板失败。
- `LOCAL_FILE_NOT_FOUND`:本地文件不存在。请检查路径是否正确,建议使用绝对路径。
- `LOCAL_FILE_INVALID`:路径不是文件,当前不支持发送目录。
- `FILE_CLIPBOARD_FAILED`:本地文件复制到剪贴板失败。请检查系统剪贴板或远程桌面会话状态。
- `SEND_FILE_ERROR`:发送本地文件异常。
- `DEPENDENCY_MISSING`:缺少 Python 依赖。请在项目根目录执行 `pip install -r requirements.txt`。
- `CLI_EXCEPTION`:CLI 自身执行异常。

Agent 遇到失败时应停止当前发送任务,把错误原因反馈给用户,并建议用户检查对应环境或联系人名称。

## 开发者辅助工具

如需维护或扩展元素查找逻辑,建议使用 Visual Studio SDK 自带的 `Inspect.exe` 工具(或 Windows SDK 工具包),用于实时查看微信窗口的 UI 元素树结构、`Name`、`AutomationID` 及 `ClassName` 等关键属性,辅助编写元素查找逻辑。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall