| name | wechat-rpa-bot |
| description | Onboard and drive the yoko WeChat RPA MCP server. Use this skill to install yoko_rpa_mcp.exe, start it, activate the license, wire its local MCP endpoint into the host (mcp.json), and then use WeChat automation through the MCP tools it exposes. |
WeChat RPA Bot Skill (MCP edition)
This skill turns any MCP-capable host (OpenClaw / QClaw / WorkBuddy …) into a WeChat assistant by
onboarding the local yoko WeChat RPA MCP server and then driving WeChat through its MCP tools.
心智模型（务必先理解）
- 微信自动化能力由
yoko_rpa_mcp.exe 在用户桌面(Session 1)常驻提供，端口 9922，同一进程三门面：
/mcp — Streamable-HTTP MCP 端点（本技能的主通道，Bearer token 鉴权）/api/* — REST（本技能只在安装/激活/取 token等 setup 步骤用它）/ — 可视化控制台（手动兜底）
- 本技能不直接发微信：它负责把 MCP server 装好、拉起、激活、把
/mcp + token 写进宿主的 mcp.json。
一旦宿主重载配置，~27 个微信工具就原生出现在宿主里，之后由宿主 Agent 直接调用。
- Agent 绝不能自己 spawn 这个 exe：被 spawn 的进程会继承沙箱/会话隔离，看不见微信桌面。exe 必须由
用户在自己的交互会话里启动（首启一次；之后 exe 自注册开机自启，自动复活）。
0. 端到端流程总览
安装 exe ──▶ 用户首启(Session 1) ──▶ 健康检查(REST) ──▶ 激活 license(REST)
└──▶ 取 MCP token(REST) ──▶ 生成 mcp.json ──▶ 用户粘贴+重载宿主 ──▶ 验活(MCP tools/list)
──▶ 之后所有微信能力走 MCP 工具(自带 read_manual 手册)
1. 安装（用户运行安装器，Agent 只做引导）
⚠️ 这一步由用户本人完成，不是自动的。 微信能力由一个桌面程序提供，通过官方安装器 yoko_rpa_mcp_setup.exe 安装。
Agent 只负责把步骤讲清楚、给出下载链接；不要替用户静默安装，也不要自己去运行安装器或 exe——原因见 §2（沙箱/会话隔离会让自动拉起的进程操作不了微信）。
请一次性、清楚地告诉用户：「微信自动化需要在您电脑上装一个本地程序，下面我把下载和安装步骤发给您，需要您亲自运行一次安装器（会弹管理员确认）。」
- 确认环境：Windows + 微信桌面版 ≥ 4.1.7（语音发送需 ≥ 4.1.9）。
- 版本查看：微信 → 帮助 → 关于；版本不对从官方渠道升级。
- 下载并运行安装器
yoko_rpa_mcp_setup.exe（Inno Setup 安装包）：
- VB-Cable 虚拟音频驱动（仅"语音消息发送"需要）：从 https://vb-audio.com/Cable/ 下载安装，装后重启电脑。文本/图片/文件等功能不需要。
- 无需
.env：采用激活码体系，激活码从 www.yokoagi.com 获取。
2. 确认服务在运行（安装器已自动启动，通常无需手动）
为什么不能你来 spawn：微信自动化靠在用户可见桌面上模拟真实鼠标键盘。若 Agent（尤其在沙箱内）自己拉起 exe，它落在隔离会话里看不见微信。由设计如此——服务由安装器/自启在用户会话里跑，你只做网络客户端。
Step 1 — 健康检查。
GET http://127.0.0.1:9922/api/health（localhost 关代理）。有响应说明服务就绪 → 跳到 §3 检查激活。
装完安装器后一般会在数秒内起来；可每 ~3s 轮询，最多 ~2 分钟，不要等用户打字。
Step 2 — 若没起来（少数情况）。
安装器装完会自动启动、且已注册开机自启，正常无需手动。若 /api/health 始终无响应，引导用户：
"请双击桌面上的 「微信 RPA MCP 服务」 图标启动它（或从开始菜单打开）。启动后无需回复我，我会自动检测到就绪并继续。"
然后继续轮询 /api/health。仍不行则问用户是否有报错弹窗，或参考 §6 恢复手段。
开机自启：安装器已注册三通道自启 + 崩溃自愈守护，下次开机自动就绪，用户日常无需手动启停。
3. 激活 License（走 REST，setup 操作）
先探一次初始化状态以判断是否已激活：
GET http://127.0.0.1:9922/api/license/machine-code → 拿本机 machine_code
- 若服务返回已激活（后续 MCP 连接不返回 403）→ 跳到 §4。
- 若未激活：
- 告诉用户：「软件尚未激活。请前往 www.yokoagi.com 获取激活码，拿到后发我，我来自动激活。」
- 用户给码后：
POST http://127.0.0.1:9922/api/license/activate
Body: { "activation_code": "<用户提供>", "machine_code": "<step 1>" }
- 成功即可继续。MCP 端点每次连接会校验 license（未激活/过期 → 403 并回传 machine_code）。
注：REST 的 setup 调用需带 X-API-Key: yoko_test（localhost 关代理）。MCP 通道用的是另一套 Bearer token，见 §4，别混。
4. 接入 MCP（本技能核心）
4.1 取 MCP token
token 是本地随机密钥（不等于激活码，激活码不外泄），首次运行落盘 ~/.yokowebot/mcp_token.dat。
沙箱里 agent 通常读不到该文件，因此从后端专用端点取（已实现）：
GET http://127.0.0.1:9922/api/mcp/token
Headers: X-API-Key: yoko_test (localhost 关代理)
成功返回：
{
"success": true,
"endpoint": "http://127.0.0.1:9922/mcp",
"token": "<随机 pairing token>",
"server_name": "wechat-bot-mcp",
"transport": "streamable-http",
"auth_header": "Authorization: Bearer <token>"
}
- 需带
X-API-Key（此端点不在 api_key 豁免名单内）；未激活也能取（已加入 license 豁免），方便先配好再激活。
- 若返回
404 { code: "MCP_DISABLED" }：说明当前 exe 非 MCP 版（正常应下载 yoko_rpa_mcp.exe）。
4.2 生成 mcp.json 片段
把下面片段给用户（token 换成实际值）。Streamable-HTTP 传输，Bearer 鉴权：
{
"mcpServers": {
"yoko-wechat-rpa": {
"type": "streamableHttp",
"url": "http://127.0.0.1:9922/mcp",
"headers": { "Authorization": "Bearer yoko_mcp_xxxxxxxx" }
}
}
}
不同宿主字段略有差异（有的用 "transport": "http" / "url" 顶层 / 或 X-Yoko-Token 头代替 Bearer）。
若宿主支持「配置话术」，可让宿主 Agent 依据上面 URL + token 自行写入。
4.3 指导用户装配并重载
"请把这段配置加入您宿主的 mcp.json（或用宿主的 MCP 添加入口填入 URL 和 token），保存后重启/重载宿主。重载后微信相关工具会自动出现，之后我们就能直接用了。"
重要：本 skill 会话当场无法调用刚配好的 MCP 工具——宿主需重载配置后，工具才在新会话里原生可用。这是 MCP 的固有机制，不是故障。
4.4 验活
用户重载后，在新会话让宿主 Agent：
- 列工具：应能看到
wechat_* 系列 ~27 个工具（tools/list）。
- 调
wechat_license_info → 返回 licensed / machine_code / agent_id，确认授权与归属正常。
- 调
wechat_rpa_read_manual with { "topic": "index" } → 拿到手册目录，确认手册可读。
5. 用 MCP 工具驱动微信（重载后）
纪律：复杂能力先读手册再调用。 工具描述里对 SOP 类工具设了 gate「你必须先 wechat_rpa_read_manual({topic})」。手册已打进 exe（mcp_manuals/），通过 wechat_rpa_read_manual 读取，不要臆造参数。
能力地图（意图 → 工具 → 先读手册）
| 意图 | MCP 工具 | 先读手册 topic |
|---|
| 发文本消息 | wechat_send_message | — |
| 发文件 | wechat_send_file | — |
| 发真实语音气泡 | wechat_send_voice / wechat_list_voices | voice_send_sop |
| 发朋友圈 / 定时朋友圈 | wechat_post_moment / wechat_create_moment_plan / wechat_create_moment_post_task / wechat_cancel_moment_post_task | moment_post_sop |
| AI 自动朋友圈开关 | wechat_toggle_ai_moment（无独立手册，参数见工具描述；配 agent 参考 config_schema） | — |
| 群发 | wechat_mass_sending | — |
| 加好友 / 通过好友 SOP | （相关工具，见 tools/list） | auto_add_friend_sop |
| 读联系人 / 同步联系人 | wechat_get_contacts / wechat_sync_contacts | — |
| 拉最新消息 | wechat_fetch_latest_messages | — |
| 群聊总结 / 会话历史 | wechat_list_sessions / wechat_get_session_messages | group_summary_sop |
| 配置读写 | wechat_get_config / wechat_update_config | config_schema |
| 任务与日志 | wechat_get_tasks / wechat_get_task_logs | task_schema / task_log_schema |
| 多实例本地账号 | wechat_list_local_users | multi_instance_sop |
| 初始化微信 | wechat_initialize | basic_setup_checklist |
| 打开手动控制台 | wechat_open_console → 返回 http://127.0.0.1:9922/ | — |
| 授权/归属排查 | wechat_license_info | — |
| 服务自愈 | wechat_service_status / wechat_restart_service / wechat_launch_wechat | — |
exe 内实际手册（wechat_rpa_read_manual 的合法 topic）：index、basic_setup_checklist、multi_instance_sop、voice_send_sop、moment_post_sop、group_summary_sop、auto_add_friend_sop、config_schema、task_schema、task_log_schema。工具名/参数以宿主实际 tools/list 为准。
发消息最佳实践（提醒宿主 Agent）：直接用用户给的联系人备注名/昵称即可，RPA 会模糊匹配，不要先查 wxid，不要用相似名替代。
无后台事件推送：本版不提供主动通知/心跳（不存在实时事件推送通道）。任务失败、掉线、AI 配置错误等状态请按需查询——需要时调 wechat_service_status / wechat_get_task_logs，或引导用户打开控制台（wechat_open_console）查看。不要向用户承诺"出问题会自动提醒"。
6. 生命周期 / 恢复 / 手动兜底
yoko_rpa_mcp.exe 内置 supervisor + 三通道自启，多数情况无需人工：
| 场景 | 恢复 |
|---|
| worker（RPA）崩溃/被杀 | supervisor 秒级自动重启（退出码/心跳/health 三重监控） |
| supervisor 被杀 | 计划任务 restart-on-failure + 周期复活 / 下次登录三通道自启 |
| 服务能连但卡住 | 宿主调 wechat_restart_service（经 9921 控制通道重启 worker） |
| 全停 | 用户双击桌面「启动微信RPA」，或托盘「重启服务」 |
| exe 被杀软隔离 | 引导加白名单/重装（代码签名降误报） |
手动控制台：服务在跑时 http://127.0.0.1:9922/ 即完整可视化界面（与 MCP 共享同一后端状态，改动实时互通）。复杂操作可引导用户在此手动完成。
停止服务：沙箱内 taskkill 跨会话必失败（Session 隔离），别自己尝试。服务由安装器/自启常驻，正常不需要停。若确需停止/卸载，引导用户走「设置 → 应用 → 卸载『微信 RPA MCP 服务』」（卸载会清理自启并杀进程），或让用户在任务管理器结束 yoko_rpa_mcp.exe（注意开机自启会再次拉起，彻底停用需卸载或用 §6 的 wechat_restart_service 之外的手段）。
7. 维护备注
- 无宿主推送：本版不做实时事件/心跳（无向宿主主动推送通道）。状态按需查询（§5 末尾）。
- 手册以 exe 内为准：SOP/schema 手册打进
yoko_rpa_mcp.exe，经 wechat_rpa_read_manual 读取；本 skill 仓不再维护 REST 版 docs/。合法 topic 见 §5 表下的清单。
- 工具清单以运行时
tools/list 为准：当前版本 27 个工具（已实测）。exe 升级由重新运行最新 yoko_rpa_mcp_setup.exe 完成（安装器识别升级、关旧实例、重装并复位自启）。
- 鉴权两套别混：REST setup 调用用
X-API-Key: yoko_test；MCP 用 /api/mcp/token 拿的 Bearer pairing token。
