wechat-use
GitHubBlog

开始 / Getting Started

核心循环

日常就两件事:发消息 和 查东西。wechat send 把话发出去,sessions / history / sent 把该看的看回来。全程纯后台,不激活窗口、不抢焦点——你手上的微信照常用,它在底下替你干活。

后台的 wechatd daemon 会按需自动拉起,你不用手动 start。第一次发消息、第一次查历史时它就悄悄起来了,之后常驻。真正要管它的时候才有 wechat daemon status / ping。

发消息

一条命令:wechat send <文本> <收件人>。收件人可以是名字(模糊匹配备注/昵称,带 30 天最近联系加权)、wxid、或 filehelper(文件传输助手,调试首选)。

bash
$ wechat send "晚点十分钟到,先开始" 张伟        # 名字模糊匹配
$ wechat send "收到" wxid_abc123def            # 直接给 wxid
$ wechat send "test 一下通道" filehelper       # 文件传输助手,最安全

名字撞车(多个候选)时命令不会瞎发:退出码 2,`--json` 下返回 {"status":"ambiguous","candidates":[...]},你挑准了再发。想先确认路由到谁、不真发,加 --dry-run:

bash
$ wechat send "确认一下收件人" 张伟 --dry-run    # 只解析,不发

群里 @ 某人

发到群、并且要 @ 出真红点提醒,加 --mention <wxid>。@ 是在微信自己加密这条消息之前注入到 <atuserlist> 的,所以对方收到的是货真价实的群 @,不是文本里打个「@」糊弄。

bash
$ wechat send "看下这个方案" 项目讨论群 --mention wxid_abc123def
⚠️ 首次发送要暖机
每次 WeChat 重启后,第一条 send 会失败(delivery_verify_timeout)——需要你在微信里手动打字发一条(比如发给 filehelper)把发送链路接通,再重试就顺了。这是一次性动作,之后整轮会话都不用管。真卡住了用 wechat unfreeze 安全解卡(只 SIGCONT + 干净 detach,绝不 kill 微信)。

查会话与记录

另一半是「查」。列最近会话、翻某个聊天的历史、自检自己发出去的——都走本地解密后的库,毫秒级,不挂进程。

最近在聊什么

bash
$ wechat sessions                       # 最近会话一览
$ wechat sessions -n 20 --filter group  # 只看群,前 20 条
$ wechat unread                         # 只看有未读的

翻某个聊天的历史

wechat history <聊天>,收件人写法和 send 一样(名字/wxid/群名都行)。--since / --until 支持 ISO 日期、时间戳,甚至自然语言(「昨天」「上周」)。里面的语音消息会自动转写。

bash
$ wechat history 张伟 -n 50              # 最近 50 条
$ wechat history 项目讨论群 --since 昨天  # 昨天到现在
$ wechat history 张伟 --order asc        # 按时间正序读

我到底发了啥(自检)

wechat sent 跨所有会话把「我发出去的消息」捞出来——发完一轮群发、或者不确定某条到底发出去没,用它对一眼。

bash
$ wechat sent --since 今天               # 今天自己发的所有消息

历史里的图片

历史里的图片消息带 local_id,用 wechat image get 就地解密落盘(默认 --from auto:本地 .dat → daemon 堆扫描 → CDN 三级兜底),文件写到 ~/.wechat/media-cache/(0600)。

bash
$ wechat history 张伟 -n 20              # 先找到图片消息的 local_id
$ wechat image get 12345 --chat 张伟     # 解密并落地那张图
✅ 提示
读类命令(sessions / history / sent / contacts …)默认输出 YAML,给人看很清爽;要喂给脚本或 agent 就加 --json,拿到稳定结构再解析。发消息才需要激活码,查历史不需要。

把这个循环连起来

一个典型的日常回合:wechat unread 看谁找我 → wechat history 某人 补上下文 → wechat send "回复" 某人 发出去 → wechat sent --since 今天 确认发到了。发和查共用同一套本地解密 + 同一个 daemon,来回切零成本。要长时间盯新消息,看 实时监听;想在终端里像聊天软件一样直接聊,试 wechat chat。