wx-auto

概览

wx-auto 是一个面向 macOS WeChat 客户端的自动化工具集，封装了从命令行向指定群聊发送文本和图片的完整流程。项目通过 Node.js 结合 JavaScript for Automation (JXA) 与 @nut-tree/nut-js 控制 WeChat 应用，支持输出详细的步骤日志与错误信息，便于排查和扩展。

快速开始

• 安装依赖后使用 wechat-send --group <群名称> [--text "消息"] [--image /path/to/img] 即可触发一次发送。
• 命令会返回每个动作的执行记录（激活窗口、搜索、定位输入框、发送文本、粘贴图片等）。任何步骤失败时 CLI 会打印错误原因和建议。

核心原理

• 权限与环境：依赖 macOS 辅助功能权限，以 nut-js 完成鼠标键盘操作；通过 osascript -l JavaScript 运行 JXA 脚本访问 WeChat 的可访问性树；图片发送通过 JXA 调用 AppKit 写入系统剪贴板。
• 编排层：lib/wechatAutomation.js 是核心状态机，围绕 sendToGroup 将校验、JXA 操作和物理输入串联成有顺序的步骤，形成可追踪的执行轨迹。
• 脚本执行层：lib/jxaRunner.js 动态拼装并执行 JXA 代码，使用环境变量在 Node 与 JXA 之间传递 payload 与步骤标识，并对 stdout/stderr 做健壮的 JSON 解析与报错包装。
• 输入控制层：lib/inputController.js 基于 nut-js 实现移动点击、Command+V 粘贴、回车发送等动作，并统一转换为带错误码的 UIActionError。
• 数据与校验：lib/validation.js 负责参数规范化（例如图片路径绝对化、存在性检查、窗口标题提示），lib/types.js 定义步骤名、错误码、日志结构，提供自动化结果的统一描述。

模块结构

• bin/wechat-send.js：命令行入口，解析参数、打印帮助并调用 sendToGroup。
• lib/wechatAutomation.js：流程引擎，依次执行激活 WeChat → 搜索群聊 → 选中聊天 → 聚焦输入框 → 填充文本 → 粘贴图片 → 按回车发送。
• lib/wechatJxa.js：包含所有 JXA 片段，负责查找窗口、搜索框、聊天区域、候选项、聊天标题等，并暴露 activateWechat/prepareSearch/ensureChatInput/fillChatText 等调用。
• lib/jxaRunner.js：封装 osascript 调用、payload 注入、输出解析与错误归类。
• lib/inputController.js：鼠标键盘原语和辅助 delay/ensureScreen 等工具。
• lib/clipboard.js：使用 JXA 的 AppKit API 将图片加载为 NSImage 写入通用剪贴板。
• lib/validation.js：输入检查、图片路径规范化、默认选项处理。
• search.js：早期的实验脚本，演示如何在 JXA 中直接调用 WeChat 可访问性结构与 cliclick。
• JXA-Cookbook.wiki/：随仓库存放的参考文档，提供 JXA 技巧与系统事件示例。

工作流程详解

1. 校验输入：确认群名、文本或图片至少提供其一，图片路径存在并转为绝对路径，同时合并默认选项（窗口标题提示、步骤超时）。
2. 检测屏幕访问：通过 nut-js 的 screen.width() 试探辅助功能权限，提前捕获缺失权限的情况。
3. 激活 WeChat：JXA 搜索目标进程与窗口，尝试 Application().activate() 与 frontmost=true，记录窗口标题。
4. 检查当前聊天：若已经聚焦目标群，后续搜索与选择步骤会标记为跳过，减少无谓操作。
5. 准备搜索：若未聚焦，定位搜索框、尝试写入群名，并结合鼠标点击、候选框分析等物理操作为选中做准备。
6. 选中群聊：通过候选项坐标点击或 UIAction，再次确认聊天标题匹配；若失败会返回 E_GROUP_NOT_FOUND 并附详细日志。
7. 聚焦输入框：确保聊天输入区存在且属于目标群，记录其矩形信息并模拟点击，以保证后续粘贴或输入的可用性。
8. 填充文本：调用 JXA 设置聊天框 value，失败时给出 E_TEXT_INPUT_FAILED 与栈日志。
9. 发送图片：逐张执行“加载图片→写入剪贴板→Command+V 粘贴→等待”流程，失败会标记源图片路径。
10. 发送消息：通过 pressEnter 模拟按键，默认一次，完成后返回成功。

每一步都产生日志与耗时信息，最终结果包含 steps 数组，方便 CLI 或调用方进行回放与调试。

错误处理与日志

• 错误码集中定义于 lib/types.js 的 ERROR_CODES，涵盖窗口、搜索、聊天框、剪贴板、发送等常见失败原因。
• sendToGroup 捕获 Node 异常、JXA 返回以及 UI 控制错误，统一包装成 AutomationErrorDetail，并附带针对性的解决建议。
• 步骤日志通过 createStepLog/finalizeStepLog 标记开始结束时间、执行结果和附加元数据，CLI 会以易读文本输出。

权限与环境要求

• macOS（配套 WeChat 桌面版），需在“系统设置 → 隐私与安全性 → 辅助功能”中授权终端、WeChat 以及任何使用 nut-js 的进程。
• osascript 需允许运行 JXA，若被安全策略阻止会返回 E_JXA_FAILED。
• 发送图片要求文件可访问，且 WeChat 支持从剪贴板粘贴图片。

开发与调试建议

• 可用 STEP_NAMES 和 ERROR_CODES 自定义上层监控或 UI 提示。
• 调整 options.windowTitleHints 以适配多语言或多实例窗口标题。
• 利用 JXA-Cookbook.wiki 获取更多 System Events 与 ObjC Bridge 示例，便于扩展新的自动化节点。
• search.js 可作为直接操作 JXA 的实验脚本参考，但生产逻辑以 sendToGroup 为准。