wechat-use

WechatUse — 先选择宿主平台

此技能支持 macOS Apple Silicon 和实验性的 Windows x64。切勿告诉 Windows 用户 WechatUse 没有 Windows 版本。插件/技能版本 1.18.15 是元数据；运行时版本独立管理（macOS v1.18.13、Windows windows-v0.1.0）。

• **Windows：**仅遵循下方的 Windows 部分。不要套用 macOS 的要求、激活/设置命令、LLDB、辅助功能、Shell 安装程序或托管的 4.1.9 说明。
• **macOS：**跳过 Windows 部分，遵循 macOS 部分。
• Linux 和 Intel Mac 不支持原生运行时。

Windows x64（实验性）

独立安装包发布于 https://github.com/leeguooooo/wechat-use/releases/tag/windows-v0.1.0 。它包含运行时；使用该安装包时，不要安装或调用系统 Python。已测试的微信版本为 4.0.6.17，登录兼容性有限；并非所有 Windows 版微信都受支持。不支持媒体、后台发送、自动选择聊天、HTTP Bridge 或 Wechaty。

重新安装前先查找已安装的运行时

在 PowerShell 中，先检查 Get-Command wechat-use -ErrorAction SilentlyContinue，然后检查默认启动器：

& "$env:LOCALAPPDATA\Programs\wechat-use\wechat-use.cmd" doctor

对于自定义安装，请读取已安装技能的 runtime.json：$CODEX_HOME\skills\wechat-use\runtime.json；如果未设置 CODEX_HOME，则读取 $env:USERPROFILE\.codex\skills\wechat-use\runtime.json。独立安装程序会写入 executable、args 和 mcp_args；请使用 PowerShell 的 & 运算符调用该确切可执行文件。较早的源码安装可能改为记录 python 和 script；请使用记录的绝对路径并添加 -X utf8，切勿猜测 python 命令。Claude 插件提供说明；仅安装/更新插件不会安装运行时。

如果不存在运行时，请下载并运行官方 Windows 安装程序：

Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/leeguooooo/wechat-use/windows-v0.1.0/install-windows.ps1 -OutFile install-windows.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-windows.ps1

安装程序会校验下载文件的哈希值，安装用户本地 CLI 和 Codex 技能，且不会发送任何消息。它不需要系统 Python。该安装包未经 Authenticode 签名。支持范围请参阅 https://github.com/leeguooooo/wechat-use/blob/main/docs/windows.md。

读取、监听和发送

doctor 会检查本地就绪情况，不会检查消息是否送达或当前登录是否被接受。请发现当前进程/账户；切勿重复使用记忆中的 PID，也不要将已初始化的状态目录切换到其他账户。

wechat-use accounts
wechat-use init --db-dir 'D:\WeChat\xwechat_files\ACCOUNT\db_storage' --pid 1234
wechat-use sessions -n 20
wechat-use contacts --query 'name'
wechat-use history 'exact_username' -n 20
wechat-use listen --once
# Preflight only: open the intended chat in WeChat first
wechat-use send filehelper 'specific text' --pid 1234
# Only after recipient/content authorization; never blindly retry
wechat-use send filehelper 'specific text' --pid 1234 --commit

历史记录/搜索需要精确的用户名。输出为 JSON（监听时为 JSONL）；除非指定 --from-start，第一个监听器会建立基线。请按 event_id 去重，不要针对同一个状态目录同时运行多个监听器。密钥使用当前用户的 DPAPI 加密；切勿打印或上传密钥。

前台发送要求聊天窗口已打开且目标明确，并且草稿为空；程序会调出选中的微信窗口。请遵守现有的发送授权，但不要发送未经请求的测试消息。若无法确定是否已提交，请先检查历史记录，再进行任何操作；服务端记录不代表已读回执。

使用 MCP 时，请使用 runtime.json 中的 executable 和 mcp_args（["mcp"]）。源码安装则使用其中记录的 python，并运行 -X utf8 <script> mcp。这支持 wechat_sessions、wechat_contacts、wechat_history 和实验性的 wechat_send；commit 默认为 false。

旧版微信可能会拒绝登录。compat-version --pid ... 默认仅检查；只有用户要求修复该限制时，才使用明确指定的实验性 --apply。该操作受指纹校验限制，只会修改一个临时字段并保存回滚日志；不保证今后能成功登录。二维码/登录确认需由用户完成。

Claude hook 错误

此插件未定义 UserPromptSubmit hook。找不到 Python 的 hook 错误属于单独配置的 hook，与独立运行的微信无关。更改前，请检查 Claude 设置中指定的 hook；保留无关的 hook，不要禁用所有 hook，也不要重新安装微信。非阻塞式 hook 错误不能证明 CLI 不可用。如果已加载的 skill 中缺少此平台部分，请更新 marketplace/plugin 并重新加载 Claude。

Windows 说明到此结束。在 Windows 上，请勿执行下方的 macOS 部分。

仅限 macOS：稳定版 CLI

设置失败和用户反馈（v1.18.7+）

发布状态：v1.18.13 已发布；后续版本请查看 GitHub Releases。以下功能适用于已发布的版本；旧版本用户可使用 README 中的安装命令升级。

请勿在提供帮助前要求用户确认 macOS 版本或是否为全新安装。设置窗口会自动收集已脱敏的环境和服务信息。从错误截图中读取 WXS-… 问题代码；如需更多详情，用户可以在任意设置页面（包括等待页面）点击“复制诊断信息”。核心程序无法启动时，窗口也会提供最简报告。绝不要索取 keys.json、激活令牌、原始内存输出或私人聊天数据。

初始化前会检测是否缺少系统开发者工具授权，并通过原生 macOS 管理员确认窗口提示“授权并继续”。保留现有登录状态和授权。对于原因不明的初始化失败，不要建议重新安装或全局重置权限。v1.18.6 的错误窗口可使用现有的“修复安装”按钮，一次性升级到当前版本；然后根据具体诊断处理，不要反复重新安装。

适用于 macOS 的微信统一 CLI。发送消息，并查询加密的本地数据库，涵盖会话、联系人、聊天记录、群成员、朋友圈和收藏。会话选择会在受管理的克隆版中运行，不会激活或显示其窗口。

受管理的 WeChat 4.1.9（v1.18.0+）

安装程序会自动复制受支持的本地 4.1.9 版本，或下载固定版本的腾讯 DMG（不会提示）。它会安装 ~/Applications/WeChat-4.1.9-wechat-use.app，该应用拥有独立的 bundle ID 和沙盒容器，并会禁用此克隆版的更新，同时保存 ~/.wx-rs/managed-wechat.json。

所有 CLI、守护进程、HTTP 桥接和 MCP 操作默认使用此克隆版。先检查其当前状态，并复用已有登录状态。如果它已关闭，请使用 open -g "$HOME/Applications/WeChat-4.1.9-wechat-use.app" 启动。仅在确实需要时才要求首次登录，然后运行 wechat-use init。不要用 open -a WeChat 替代，不要对主应用 /Applications/WeChat.app 进行签名，不要移除受管理的选择，也不要在克隆版关闭时回退到主应用。只有 4.1.9 会持续获得兼容性维护。修复安装时，请重新运行安装程序；不要下载最新版微信。

统一设置与恢复（v1.18.6+）

使用 wechat-use setup --json 查看当前设置阶段，无需打开 UI。对于普通用户，curl 安装程序和交互式 wechat-use init 使用相同的原生设置窗口。它会保留现有激活状态、登录状态和密钥，仅为该工具选择兼容的已安装开发工具，启动官方后台服务，并验证实际的服务所有权和权限。

如果需要用户执行操作，请运行 wechat-use setup 或打开 ~/Applications/WechatUseSetup.app。让窗口处理激活、登录、系统授权、拖放和重新检查。不要给用户提供一串 doctor、init、launchctl 或 xcode-select 修复命令。绝不要将由 Terminal 拥有的守护进程作为权限变通方案启动。服务必须由官方 bridge 拥有。

在密钥或辅助功能授权尚未就绪前，bridge 的 /setup/status 仍可用。它仅用于诊断；发送仍受限制。设置控制通过本地信号与经过验证的 launchd 进程通信，而不是使用未经身份验证的 HTTP 写入端点。

未经确认的设置测试会被持久化，关闭或重新打开窗口后不会自动重放。--skip-verify 会明确跳过发送；权限就绪本身并不代表消息已送达。人工身份确认和实际的 macOS 授权仍由用户控制。

用户设置指南

后台执行

当“系统设置”显示该工具已启用，但实际的 launchd bridge 仍拒绝辅助功能权限时，不要将显示的开关视为权限已生效的证明。检查已安装路径和签名，仅刷新该工具的开关，并重新检查刚加载的官方服务。如果这些检查仍未通过，特定的旧权限条目可能已失效。经授权的本地计算机控制 Agent 可以使用当前已安装的二进制文件，仅移除并重新添加未通过检查的工具条目。每次操作前都要确认具体条目；不要盲目使用坐标，也不要重置其他应用的权限。保留专用的 WeChat 进程和密钥。之后验证 HTTP 健康状态、守护进程实际的辅助功能权限结果，以及其父进程是否为官方 bridge。用户身份验证仍需由用户操作。

常规操作必须保留用户的前台窗口。不要将 open -a、激活／置顶／取消最小化克隆应用、切换应用或前台／全局快捷键 作为常规准备步骤。应使用面向进程的输入和后台会话导航，并确认收件人无误。 安装、初始化、权限错误和服务恢复时也同样适用。返回可执行的诊断信息， 不要自动打开“系统设置”、Finder、权限对话框，也不要重试发送。doctor --fix-tcc 是显式的 交互式恢复命令，会打开“系统设置”。 只有在确认现有后台方法不可用后，才能将前台恢复作为最后手段。切勿激活应用并盲目重发未经确认的消息；应先检查是否已送达。仅凭空白的 AX 快照不足以作为前台恢复或重启 WeChat 的理由。

快速入门（请先阅读）

一次调用即可发送 WeChat 消息：

wechat-use send "早上好" Lisa                 # fuzzy name match (remark / nick / alias)
wechat-use send "hi" filehelper              # wxid — zero DB lookup, fastest
wechat-use send "提醒一下" 20590343959@chatroom  # group wxid (ends in @chatroom)

解析规则（按顺序应用）：

1. RECIPIENT 匹配 wxid 格式（wxid_…、…@chatroom、gh_…、biz_… 或 filehelper 等保留标识）→ 跳过所有 DB 操作并直接发送。
2. 否则，使用会话活跃度作为优先条件，在本地联系人 DB 中搜索（备注／昵称／别名／wxid）：
   • 仅有一个匹配项 → 发送
   • 有多个匹配项，但近期（30d）只有一个有活动 → 发送给该匹配项
   • 否则 → 退出码为 2 + JSON {"status":"ambiguous","candidates":[...]}；由 Agent 选定对象，并使用明确的 wxid 重试

遇到歧义时的示例响应：

{
  "status": "ambiguous",
  "hint": "Lisa",
  "candidates": [
    {"wxid": "lishuang683451", "display_name": "lisa", "last_seen": "2026-04-20 05:34:55"},
    {"wxid": "wxid_xxx", "display_name": "Lisa (另一个)", "last_seen": ""}
  ],
  "note": "multiple matches; pass one of the wxids explicitly: wechat-use send <text> <wxid>"
}

Agent 应当：读取 candidates[0].wxid，然后重试 wechat-use send "<text>" <wxid>。除非排名第一的候选对象没有近期活动，或有多个候选对象，否则不要询问用户。

用于 Agent 集成的 HTTP Bridge（v1.10+）

wechat-bridge 是一个独立二进制文件，可将守护进程的 RPC 封装为稳定的本地主机 HTTP 接口。将 WeChat 接入 Agent 平台（Hermes、n8n、Dify、LangChain、自定义机器人）时可使用它——与每次调用都启动 CLI 相比，HTTP 集成成本更低。

# Start bridge (binds 127.0.0.1:18400 by default)
wechat-bridge &

# Health + send-readiness
curl http://127.0.0.1:18400/health

# Send
curl -X POST http://127.0.0.1:18400/send \
  -H 'Content-Type: application/json' \
  -d '{"wxid":"filehelper","text":"hi"}'

# SSE message stream — ⚠️ ALWAYS pass ?since=<epoch>
# Without ?since, default is 0 = backfills entire local message history
# (1MB+ in seconds for typical accounts). For agent / long-running flows
# always pass a since timestamp; pick "now" for live-only or last-checkpoint.
SINCE=$(date +%s)
curl -N "http://127.0.0.1:18400/messages/stream?since=$SINCE"

端点：

方法	路径	映射到
GET	/health	ping + send_status
GET	/chats	sessions
GET	/unread	unread
GET	/contacts	contacts (query + limit)
GET	/chat/:wxid	会话元数据（不包含消息行）
GET	/chat/:wxid/history	history (limit + since + until)
GET	/resolve	resolve_recipient
POST	/send	send_text — 返回 {status: delivered / submitted_unconfirmed / status_unknown / failed, diagnostic, ...}
POST	/typing	正在输入指示器（仅当 --shape hermes 时）
GET	/messages/stream?since=<epoch>	将 new_messages_since 轮询结果推送到 SSE；请传入 since，否则首次连接时会收到完整积压消息

账号就绪状态与图片发送

图片发送和读取自己发送的消息时，会在每个消息分片中解析当前账号；在托管的 4.1.9 路径中，不再需要文件传输助手预热样本。/health 会将 wechat.state 和 wechat.account_state 与守护进程存活状态分开报告。not_ready 表示账号尚未准备好发送；doctor 中的 needs_wechat_login 表示需要完成 WeChat 登录，而不是重新初始化或删除缓存。WeChat 仍可能要求通过手机确认或扫码登录。该工具不会绕过此确认。

原生发送目前不支持普通文件、视频和卡片。

通过 HTTP 发送图片

图片路径必须指向 Bridge 主机上的文件。原生请求接受 image_path（或 imagePath）；Hermes 请求使用 imagePath。仅发送图片时，请省略文本字段。请分别发送文本和图片；在同一请求中组合两者会被拒绝，而不会静默丢弃内容。

curl -X POST http://127.0.0.1:18400/send \
  -H 'Content-Type: application/json' \
  -d '{"wxid":"filehelper","image_path":"/absolute/path/photo.png"}'

SSE 负载结构（v1.10.28 — 与 Wechaty 对齐 + isMentioned）

/messages/stream 会发送 event: messages，其中包含一个 JSON 数组：

{
  messageId: string,
  chatId: string,                // wxid (DM) or groupid@chatroom
  senderId: string,              // in group: sender's wxid; in DM: the other party's wxid
  senderName: string,
  chatName: string,
  isGroup: boolean,
  body: string,                  // human-readable text. For URL / quote / mini_program, body is the title — raw XML is NOT exposed here.
  hasMedia: boolean,
  mediaType: "image"|"voice"|"video"|"file"|"",
  mediaUrls: string[],           // first entry is CDN URL when applicable
  mentionedIds: string[],        // v1.10.25+ — authoritative @-mention list resolved by daemon
  isMentioned: boolean,          // v1.10.28+ — bridge-authoritative "this row @-mentions ME". Self-sent rows are always false.
  quotedParticipant: string,     // v1.10.27+ — populated from refer.fromUser on quote replies
  botIds: string[],              // legacy heuristic self-marker; NEW consumers should rely on fromSelf instead
  fromSelf: boolean,             // v1.10.25+ — bridge-authoritative "this row was produced by our own POST /send"; DROP THESE to avoid self-echo loops
  messageKind: "text"|"image"|"audio"|"video"|"contact"|"emoticon"|"location"|
               "url"|"attachment"|"mini_program"|"chat_history"|"transfer"|
               "red_envelope"|"recalled"|"system"|"unknown",  // v1.10.27+, aligned to Wechaty's MessageType enum
  urlLink?:     { title, description, url, thumbUrl },                             // present iff messageKind=url
  miniProgram?: { title, description, appId, username, pagePath, thumbUrl },        // present iff messageKind=mini_program
  refer?:       { svrId, fromUser, chatUser, displayName, content },              // present on quote replies
  recall?:      { replacedMsgId, text },                                            // present iff messageKind=recalled
  media?:       { aesKey, md5, cdnUrl, cdnThumbUrl, length, durationSeconds, localPath },  // structured metadata for image/audio/video/attachment
  timestamp: number,
}

完整的 JSON Schema 已提交至 wx/schema/sse-payload-v1.10.28.schema.json，并由守护进程构建中的契约测试强制校验。

使用方检查清单：

• 使用 fromSelf === true 过滤自身回显。不要使用 senderId === myWxid——在私聊中，两个方向的消息共用同一个 senderId。
• 在群聊中，仅在 isGroup && isMentioned 时回复——守护进程已经解析了权威的提及对比结果，因此不要自行重新实现 mentionedIds.includes(myWxid)（你的 wxid 可能是备注或查找值，守护进程能正确解析）。当 WECHAT_BRIDGE_GROUP_MENTION_ONLY=1 时，桥接程序也会自动丢弃未使用 @ 提及的群消息。
• 只需要 URL？使用 mediaUrls[0]。需要 aesKey 和 md5 来解密或验证？使用 media.cdnUrl / media.aesKey / …。
• 对于 messageKind: "image"，不要在聊天回复中内嵌 base64 图片数据。调用 wechat-use image get <messageId> --chat <chatId> --json，解析 absolutePath，然后使用宿主 Agent 的文件/图片读取能力读取该路径。默认 --from auto（自 v1.13.11 起）会先尝试守护进程的内存查找（速度快，且用户在 WeChat 中至少打开过一次该图片时即可使用），未命中时才回退到 CDN 重放。如果结果是 image not yet viewed in WeChat (cache empty), and CDN fallback failed，请让用户在 WeChat 中打开一次图片后重试。cdn-expired 或 needs local-decrypt adaptation 表示两种方式都无法恢复该图片——应将此情况告知用户，而不是猜测。
• 对于 URL、引用和 mini_program，body 应为人类可读的标题。如果你之前从 body 中解析原始 <appmsg> XML，请迁移到专用的 urlLink / miniProgram / refer 对象。
• 向后兼容：所有 v1.10.25 之前的字段均保留其名称和类型。新增字段仅作扩展。

Agent 安全注意事项：

• 桥接程序绑定到 127.0.0.1——未通过隧道时不会暴露在局域网中。
• 设置 WECHAT_BRIDGE_BEARER=<secret> 环境变量，可要求非 /health 路由提供 Authorization: Bearer <secret>。通过 Tailscale / SSH 建立隧道时请使用此设置。
• 激活门控在 wechatd 内部强制执行，而非由桥接程序执行。缺少或已过期的 wechatuse_ 令牌会导致 /send 返回 HTTP 401 / 402。桥接程序无法绕过激活。

命令组

组	命令	首次使用要求
诊断	doctor	—（先运行；检查 AX 权限、守护进程状态、WeChat 二进制文件指纹）
设置	init	登录托管克隆一次；扫描正在运行的 4.1.9 进程，不重启它。查询正常时，重复使用缓存的密钥。
发送	send	自动准备所选克隆的聊天上下文；无需手动选择聊天或发送热身消息。
查询（消息）	sessions、unread、new-messages、contacts、history、search、members、stats、export、image、sent（v1.16.12+，跨聊天查询自己发送的消息）	先运行 init；按需自动启动守护进程（v1.7.5）
收藏项	favorites	先运行 init；按需自动启动守护进程
实时（v1.3+）	listen	按需自动启动守护进程（v1.7.5）
守护进程（v1.2+）	daemon start|stop|status|ping	可选 — 查询/监听命令会在需要时自动启动它
HTTP Bridge（v1.10+）	wechat-bridge（独立二进制文件）	通过 localhost HTTP 集成 agent / Hermes / n8n — 见下文章节
Wechaty Puppet 网关（v1.10.32+）	wechat-wechaty-gateway（独立二进制文件，gRPC :18401）	面向编写 wechaty 机器人的开发者 — 本技能不使用它。如果用户询问“我可以在这上面运行我的 wechaty 机器人吗？”，请指引他们访问 https://github.com/leeguooooo/wechat-use#接-ai-agent 并停止。不要使用本技能尝试编写 wechaty TS。
wechat-use tunnel（v1.11+）	wechat-use tunnel setup	通过 Cloudflare Tunnel 将本地 REST bridge 暴露给远程服务；详情见 docs/remote-gateway.md，不要在本技能中内嵌完整设置流程。
wechat-use orchestrate（v1.12+）	wechat-use orchestrate setup --outbox-url= --webhook-url= --bearer= --webhook-secret=	长期运行的工作进程，轮询 SaaS outbox API，并将 SSE 入站事件推送到 SaaS webhook。适合 NAT 环境（Mac 仅需出站连接，无需公网 IP / 域名）。用于 SaaS 集成（cherry-class）。协议：docs/v1.12-orchestrate-protocol.md。不要在此处内嵌 SaaS 端点设计。
认证（v1.9.1+）	auth activate | status | renew	send 前必须激活 — 通过 Telegram 上的 @WechatCliBot 获取代码
update-guard（v1.16.33+）	update-guard status | disable | enable	锁定 WeChat 后台自动热更新通道（chflags uchg MacUpdate 路径），Tencent 推送的新 dylib 不会替换它。建议完成 init 后运行一次 disable，以保持当前 build 的适配稳定；CLI 启动时会自检并发出警告，但不会阻塞
probe-build（v1.16.32+）	probe-build	WeChat 升级到工具无法识别的新 build 时运行。本机 literal_scan + pattern-match routing 锚点，输出 shift 数值，并 POST 到 /v2/probe，提交至适配队列。不传输 binary，只传输派生数值。读侧命令（history / sessions 等）通过 literal_scan fallback 立即可用

所有查询命令默认输出 YAML（适合 Agent，token 消耗低）。添加 --json 可获取 JSON。

---

🛑 安全规则（重要——调用 send 前请阅读）

每次调用 send 都必须解析到已知的 wxid。 不要默认静默发送到“当前聊天”——该标志（--current-chat）已在 1.13 之前移除；如果解析器找不到收件人，请停止并询问用户。

“给 XXX 发 YYY”的正确流程：

1. 直接尝试：wechat-use send "YYY" XXX。快速路径解析器（见本文顶部）会立即处理符合 wxid 格式的目标，并根据会话活跃度优先级，对本地联系人数据库中的名称进行模糊匹配。
2. 退出码为 2 且 status: "ambiguous" 时：如果 candidates[0] 的 last_seen 在约 30 天内，其他候选项则已过期或为空，CLI 已自动选中该候选项并返回成功。如果确实存在歧义（多个候选项近期都很活跃），请询问用户并由用户选择，不要猜测。
3. 出现 no contact matches "XXX" 时：询问用户提供 wxid（或让用户从 wechat-use contacts --query XXX --brief 的候选项中确认）。

硬性规则（Agent 必须遵守）：

• 不要猜测或伪造 wxid。如果解析失败，请升级处理并询问用户。
• 不要扫描文件系统、grep 日志或使用 AppleScript 查找 wxid。CLI 已通过快速路径搜索本地联系人数据库——请信任它。如果找不到收件人，请停止并询问用户。
• 除非快速路径的首次 send 已提示存在歧义，否则不要先后分别调用 wechat-use contacts 和 wechat-use send。使用一行命令可节省约 400 ms 和一次 Agent 往返。

---

能力矩阵

能力	状态	命令
提取 DB 密钥、缓存布局（查询命令的必需第一步）	✅	wechat-use init
向指定 wxid / 群名 / 昵称发送文本	✅	wechat-use send "..." <recipient>
支持任意 Unicode / emoji / CJK / 长度	✅	内置
零 UI 闪烁（不抢夺焦点）	✅	send 的默认行为
列出最近的聊天会话	✅	wechat-use sessions
列出有未读消息的会话	✅	wechat-use unread
获取自上次检查以来的新增消息	✅	wechat-use new-messages
联系人查找 / 模糊搜索	✅	wechat-use contacts [--query KW]
聊天记录（私聊 / 群聊）	✅	wechat-use history <chat> [-n 500]
适用于大模型的群聊摘要	✅ v1.13.33（--with-id v1.16.19+）	wechat-use digest <chat> [--json --with-id]
聊天用户别名映射	✅ v1.16.19+	wechat-use alias add/list/rm
全 DB 关键词搜索（FTS5 trigram，v1.16.21+）	✅	wechat-use search <kw> [--in CHAT] [--since TIME]
群成员	✅	wechat-use members <group>
聊天统计（发送者 / 类型 / 时段）	✅	wechat-use stats <chat>
将聊天导出为 Markdown / JSON	✅	wechat-use export <chat> --format markdown -o ...
收藏（文本/图片/文章/...）	✅	wechat-use favorites [--type ...] [--query KW]
图片媒体（本地内存查找 + CDN 回退）	✅	wechat-use image get <messageId> --chat <id>
语音媒体（原始 SILK_V3）	✅	wechat-use audio get <svr_id>（1.13.21+）
语音转录（whisper.cpp + SILK 流程）	✅	运行一次 wechat-use audio setup，然后运行 wechat-use audio transcribe <svr_id>（1.13.25+）
首次发送时的聊天上下文	自动	守护进程会在发送前选择并验证确切的接收对象；用户无需点击聊天或发送预热消息。
实时入站流（v1.3）	✅	wechat-use listen — 监视新消息并推送到 stdout
入站回调 → shell 命令（v1.3）	✅	wechat-use listen --on-message "handler.sh"（WECHAT_MSG_* 环境变量）
服务端 wxid 筛选（v1.3）	✅	wechat-use listen --wxid filehelper
后台守护进程（v1.2+，延迟启动 v1.7.5）	✅	wechat-use daemon start — 或由任意查询命令自动启动
微信二进制指纹验证（v1.7.2+）	✅	微信热修复更新后，wechat-use doctor 会提示版本差异
发送图片 / 文件	⏳ 计划中	—
群发消息	❌ 不允许	防止滥用；LICENSE 中禁止
Linux / Intel Mac	❌	此 macOS 后端需要 arm64；Windows 使用上文单独介绍的实验性后端。
未验证的微信版本	⚠️ 未验证	适配数据可能发生偏差；wechat-use doctor 会发出提示

---

Agent：首次使用设置

步骤 1 — 检查 wechat 是否位于 PATH 中：

command -v wechat

如果缺失：

curl -fsSL https://raw.githubusercontent.com/leeguooooo/wechat-use/main/install.sh | bash
# Ensure ~/.local/bin is on PATH
case "${SHELL##*/}" in
  fish) fish_add_path "$HOME/.local/bin" ;;
  zsh)  grep -q '.local/bin' ~/.zshrc  2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc ;;
  bash) grep -q '.local/bin' ~/.bashrc 2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc ;;
esac
export PATH="$HOME/.local/bin:$PATH"

步骤 2 — 初始化已登录的托管版 WeChat：

wechat-use init

在托管版 WeChat 4.1.9 上，这会扫描现有进程以获取每个数据库的密钥；不需要退出并重新启动 WeChat。保留现有账户、容器和登录状态。只要查询正常，就重复使用缓存的密钥，包括守护进程重启后；仅在密钥缺失或无法解密时重新扫描。

如果 WeChat 本身显示登录界面，用户必须完成真实的登录验证。不要通过重启已登录的克隆版、更换其 Bundle 标识或删除其本地账户数据来制造新的验证流程。

步骤 3 — 检查服务权限：

wechat-use doctor --json

检查运行中守护进程的 daemon_accessibility 结果以及桥接服务的运行状况。辅助程序已安装的身份具有辅助功能权限；签名升级应保留这些授权。如果缺失，请运行 wechat-use init --fix-tcc：它会打开正确的面板，在 Finder 中选中二进制文件以便拖放，然后自动重新检查运行中的守护进程。不要要求用户查找隐藏路径或自行输入恢复命令。

步骤 4 — 验证发送，无需手动选择聊天：

wechat-use send "安装验证" filehelper --json

守护进程会读取已选聊天的身份，并通过后台会话导航，在输入前选中准确的目标收件人。按下 Enter 前，它会再次检查身份。如果缺少构建校准、上下文不明确、收件人已更改或目标不可用，则会在发送前停止。不要要求用户点击 filehelper 或发送预热消息作为常规设置步骤。当前本地候选版本需要匹配的收件人上下文校准；此校准仍待分发，发布前必须进行测试。

只有在指定聊天中核实到记录，才算发送成功。delivery_verify_timeout 可能表示发送延迟：重试前先检查历史记录。如果自动准备失败，请保留诊断输出并运行 wechat-use doctor --json；不要重启已登录的 WeChat，也不要重新激活其账户来作为变通方法。

空的 AX 树或空白的自动化截图，并不能证明 WeChat 界面为空、已退出登录或已冻结。诊断前应结合进程、命令行、数据库证据以及用户看到的状态。切勿仅为恢复自动化快照而退出并重新启动已登录的克隆版。

---

发送失败模式（Agent 自助恢复表）

当 wechat-use send 返回 {ok: false, …}，或标准错误输出与支持信息中的 reason: 字段匹配时，请先按照以下操作手册处理，再请用户排查问题。在后台进行诊断，仅当确认某个步骤无法在后台完成时才请求人工操作。切勿根据发送失败推断自己已获准取得焦点。

reason: 槽位	根本原因	Agent 操作
desktop_locked	macOS 系统锁屏已启用；未发送任何消息	请用户解锁 Mac 系统屏幕。保留现有的 WeChat 登录状态和账户数据；不要要求用户登录 WeChat 或手动选择聊天。仅在桌面解锁后重试。
delivery_misrouted	消息发到了其他聊天	停止继续发送，确认实际发送目标并修正收件人选择。不要悄悄重试，也不要要求用户手动预热。
delivery_verify_timeout	已执行发送流程，但尚未确认送达	重试前检查指定聊天的历史记录；延迟的消息仍可能送达。
slot_send_bp_armed_no_fire	自动输入上下文准备未能激活发送信号	保留诊断信息并运行 wechat-use doctor --json。不要要求用户手动预热、重启 WeChat 或重新激活账户。
wechat_not_running	所选克隆版未运行	启动 open -g "$HOME/Applications/WeChat-4.1.9-wechat-use.app"，然后检查现有登录状态是否已恢复。仅在确有需要时才要求登录。绝不要将主应用作为备用方案启动。
slot_send_bp_failed_to_arm (detail: send adapter install did not complete within 30s)	WeChat 的 get-task-allow=false（官方默认签名）；wechatd 的本地调试接口无法连接	运行 wechat-use doctor 确认 wechat_get_task_allow ✗。然后请用户复制并运行 install.sh 输出的合并模式重新签名代码块（或 wechat-use doctor 建议的代码块）。需要 sudo，必须由用户运行。不要使用替换模式的 codesign --entitlements ... 命令——它会移除 WeChat 现有的系统权限，并导致 WeChat 本身的 TCC 无法正常工作。
最近安装/升级后出现 daemon_accessibility FAIL / ax_trusted=false	机器上存在多个 ai.wechat.* LaunchAgent——orchestrate（KeepAlive）通过过时的 launchd 责任链重新生成了 wechatd	重新运行 curl -fsSL https://raw.githubusercontent.com/leeguooooo/wechat-use/main/install.sh | bash。v1.16.12+ 的 install.sh 会先 bootout 所有 ai.wechat.*.plist，再按正确顺序 bootstrap。不要尝试用 launchctl kickstart 单独修复——它不会重置责任链。
tcc_accessibility_denied（wechat-bridge 或 wechatd 不受信任）	缺少必需的 macOS 辅助功能授权	使用 wechat-use doctor --json 确认缺少的授权，并报告结果，不要打开任何窗口。如果需要交互式恢复，请说明 wechat-use doctor --fix-tcc 会打开权限对话框和系统设置；用户必须启用相关授权。不要将其作为自动重试来运行。
activation_* / subscription_* / unauthorized	激活码已过期或尚未兑换	使用 wechat-use auth status 确认。然后运行 wechat-use auth activate <code>。引导用户前往 https://t.me/WechatCliBot 申请激活码（仅限研究／个人用途——不受理商业咨询）。
dylib_fingerprint_unverified	WeChat 自动更新到了不在已验证版本范围内的构建	wechat-use doctor 会显示新的指纹。告知用户关闭 WeChat 自动更新（WeChat → 设置 → 通用 → 「有更新时自动升级」），并使用安装程序修复受管理的 4.1.9 克隆版。不要升级到其他 WeChat 版本。

关键原则：每个 reason: 槽位都是稳定的枚举值；支持负载包含 ax_trusted、input_monitoring、binary_fingerprint、cli_version、daemon_version——请根据这些确切字段名称进行匹配，而不要依据人类可读的中文错误消息进行匹配（错误消息可能会随版本发布而变化）。 面向 Agent 的 LaunchAgent / TCC 手册：如果需要手动重置责任链（例如，用户的机器使用了自定义的 LaunchAgent 布局），请使用 launchctl bootout + launchctl bootstrap，切勿使用 launchctl kickstart -k。kickstart 不会重新读取 plist EnvironmentVariables，也不会重置 launchd 的责任链缓存。install.sh 升级流程是参考实现。

---

用法 — 发送

# Recipient resolves wxid / 群名 / 昵称 / 备注 (fuzzy match against local contact DB)
wechat-use send "你好 🎉" filehelper
wechat-use send "会议 5 分钟后开始" lishuang683451
wechat-use send "早上好" Lisa                # 找不到 → friendly error + 候选

# Group send (resolver also handles group display names)
wechat-use send "今天 19:00 团建" "AI 星球"

# JSON output for agents that parse responses
wechat-use send "ok" filehelper --json

# Dry-run: resolve recipient + validate args, do NOT actually send. Useful when
# the agent wants to verify a fuzzy name → expected wxid before committing.
wechat-use send "draft" "李工" --dry-run --json

send 参数

参数	必填	描述
<TEXT>（位置参数）	是	消息正文。长度不限，支持任何 Unicode 字符。
<RECIPIENT>（位置参数）或 --wxid	是	目标 wxid / 群聊 ID / 昵称 / 群名 / 备注。如果提示信息不够精确，解析器会选择最近最活跃的匹配项。
--mention <wxid>	否	可见的 @<name> 前缀（仅文本，不会真正发送 ping 确认 — 参见 issue #4）。
--dry-run	否	解析收件人并进行验证，但不发送。与 --json 配合使用，适用于 Agent 的干运行检查。
--json	否	JSON 输出

send --json 三态契约（v1.13.20+）

所有 --json 输出都带有顶层 ok: bool，Agent 可直接使用 if (r.ok) {...} else {...}，无需解析三套 schema：

状态	触发条件	结构（顶层字段）
成功	wechat-use send TEXT RECIPIENT --json 发送成功	{ok: true, sent: true, reason: null, diagnostic: {…SendResult 全字段…}}
干运行	--dry-run --json（解析器正常工作 + 不实际发送）	{ok: true, dry_run: true, text, resolved_wxid}
错误（早期）	使用 --json + 参数错误 / 解析器找不到 / 存在歧义 / 网络断开	{ok: false, exit_code: <int>, error: "<msg>"}
错误（发送失败）	发送失败或未确认送达（自动准备失败 / 缺少权限 / 版本未适配等）；请核对 diagnostic 和历史记录	{ok: false, sent: false, reason: "<reason>", diagnostic: {…}}

# 推荐:agent 用 jq 分支
wechat-use send "hi" filehelper --dry-run --json | jq -e '.ok' && echo "✓ resolved" || echo "✗ failed"

stderr 仍会提供便于人类阅读的错误描述（供终端用户查看）；Agent 只需解析 stdout JSON。

---

用法 — 查询

# Sessions (recent conversations)
wechat-use sessions -n 20                           # full yaml
wechat-use sessions --brief -n 20                   # 单行/会话, 带未读数
wechat-use sessions --filter group --json -n 20     # 只看群聊 (chat_type: group / private / official_account / folded / other)
# JSON 字段命名:未读数是 `unread_count`(下划线全名), 不是裸 `unread`。brief 视图渲染成 [N unread] 仅是显示, 实际字段是 unread_count。

# Contacts
wechat-use contacts --query 李                      # fuzzy match nickname/remark/wxid
wechat-use contacts --brief -n 50                   # 单行/联系人 (姓名 + wxid)

# Unread
wechat-use unread -n 5

# History (chat positional or --chat flag, both accepted)
wechat-use history "张三" -n 2000
wechat-use history --chat 21263894984@chatroom -n 200
wechat-use history "AI 星球" --since "2026-04-01" --until "2026-04-15" -n 200   # ISO date OK
wechat-use history "AI 星球" --since 1719793200 --until 1720484400 -n 200       # epoch OK too

# Search (FTS5 trigram, v1.16.21+)
wechat-use search "会议纪要"                              # 全局,毫秒级
wechat-use search "报销" --in "财务群"                    # 群限定
wechat-use search "claude" --since "3 days ago"          # 加时间窗
wechat-use search "report" --since "2026-05-01" --until "2026-05-10"

# Search agent UX (v1.16.22+):
wechat-use search "desktop" --in "Helm" --context 5m     # 每条命中带前后 5 分钟同群上下文,文本模式 `>` 标记命中
wechat-use search "report" --timeout-ms 5000             # 硬上限 5s,超时 exit 124 + `search_timeout`
# `--json` meta 多带: elapsed_ms / row_count / chat_resolved / chat_hint / context_secs

# HTML 证据页 (v1.16.23+, v1.16.24 重做 WeChat 主题 UI + 默认 inline 图片):
wechat-use search "desktop" --in "Helm" --report                    # 单文件 HTML,默认 --context 5m,图片 base64 inline
wechat-use search "房价" --in "立水桥" --report --no-media           # 跳过图片(escape hatch,渲染成占位卡片)
wechat-use search "通知" --in "群" --report --out report.html       # 自定义路径,无 sidecar 目录,转发邮件/微信直接带走
# stdout = 写入的文件路径(text 模式)或 {ok, report_path, hit_count, ...}(--json)
# 输出文件 self-contained:inline CSS,无 JS,无 CDN,可直接邮件/微信/Notion 转发

# Search caveats (FTS5 trigram limits):
# - 查询 < 3 字符: 全局会报 `query_too_short`,加 `--in <chat>` 则
#   fallback 到 LIKE 单 shard。例: `wechat-use search 卡 --in <chat>`
# - 首次升级后 daemon 在后台 backfill (266k 消息 ~86s 本机);期间
#   查询会报 `search_index_unavailable`,等一两分钟后再查
# - mirror DB at `~/.wx-rs/search-index.db` (SQLCipher 加密,key 从
#   现有 WeChat key HKDF 派生),mirror 跟 WeChat 数据库一起在 home 目录
# - `--context` 需要配合 `--in <chat>` 才生效(无 chat 时被 daemon 跳过)

# Group members
wechat-use members "AI 星球"

# Stats
wechat-use stats "AI 星球"

history --json payload shape (stable contract for agents)

顶层包装(history / sessions / unread / search / digest 全一致):

{
  "meta": {
    "chat_latest_timestamp": 1778981425,
    "shards_scanned": 2,
    "shards_hit": 2,
    "status": "ok",
    "order": "desc",
    "now_unix": 1779178200,
    "since_resolved": 1778573400,
    "until_resolved": 1779178200
  },
  "rows": [ {...row...}, {...row...} ]
}

不是裸数组。jq 要 .rows[] 不是 .[]。meta.order 是 v1.16.12+ 加的字段,告诉 你 rows 是 "desc"(新→老,history 默认)还是 "asc"(老→新,digest 默认 / wechat history --order asc)。别拿 rows[0] 当"最新"也别当"最老",先看 meta.order。

meta.status 取值:ok / windowed(传了 --since/--until)/ possibly_stale (SessionTable 比 history 领先 > 24h,大概率分片漂)/ possibly_stale_unknown_shards (磁盘有新分片 daemon 不认,要重跑 wechat-use init)。

v1.16.19+ 时间窗回灌(history): meta.now_unix 是查询时的本机 epoch; meta.since_resolved / meta.until_resolved 是 --since / --until 自然语言解析后的 实际 epoch(没传不出现)。自然语言 --since "2 days ago" 解析完后,agent 不用重算时区, 直接拿这三个值跟用户复述"实际查的是 X 到 Y, 当下 Z"。

每条 message row 字段(snake_case):

字段	类型	说明
local_id	int	DB 行主键(per chat 单调)。image get <local_id> --chat <wxid> 用这个取图。
server_id	int	WeChat 服务端 msg id(撤回时引用 replacedMsgId)。
local_type	int	原始 type code。低 16 位 mask 后 = 1 文本 / 3 图 / 34 语音 / 43 视频 / 49 appmsg / 等。
message_kind	string	enum: text / image / audio / video / url / mini_program / recalled / appmsg / 等。Wechaty 对齐。
display_text	string	已清洗后的 human-readable body(text 直接 = body;image/url 抽 title;recalled 给替代文案)。
message_content	string	原始 body(可能是 raw XML / 群消息带 <sender>:\n 前缀)。debug 用,生产逻辑请用 display_text。
sender_wxid	string | null	群消息 = 真发送者 wxid;DM 两侧都是 null(WeChat DB 在 1:1 chat 不记 sender wxid)。不能单凭这个判 self-sent(DM 会双方都误判 + 系统消息也是 null)。
sender_display_name	string | null	daemon-resolved 展示名(群里的群昵称 / 联系人备注 / 昵称)。v1.16.19+ 改: 联系人 DB 不可达 / 这条 wxid 找不到时,fallback 到裸 wxid 而不是 null(agent 不用同时处理 has/has-not 两种 shape)。DM self-sent / 系统消息仍为 null。
real_sender_id	string	per-chat 自增 ID(字符串,永远非空)。WeChat 给当前账号分配一个固定 id(本机经验值是 "2",不同账号可能不同),其它整数 = 对方/群成员。判 self-sent 用这个:扫 filehelper 历史得到自己的 id(filehelper 100% 自发,占比最大那个就是 self id),其它 chat 用同一 id 过滤。
chat_id / username	string	会话 wxid(DM)或 xxxx@chatroom(群)。
chat_display_name	string	群名 / 联系人备注 / 昵称(v1.13.9+ 自动解析)。xxxx@chatroom 直接看得懂。
create_time	int	epoch seconds。
created_at	string	ISO 本地时区(2026-05-18T01:30:45+09:00),v1.13.30+ 派生,人读直接拿这个。
is_mentioned	bool	当前账号在群里被 @ 了(daemon 端权威解析,客户端别再算一遍)。
media	object	image / voice / video / file 才有: {aesKey, md5, cdnUrl, cdnThumbUrl, length, durationSeconds, localPath, dat_path?, dat_md5?, dat_exists?}。
urlLink / miniProgram / refer / recall	object	type-specific 结构化字段(见 SSE schema)。

字段稳定性:增加 = 默认 null / 缺省;不会重命名 / 改类型(契约由 v1.10.27 起的 SSE schema 单测守)。

想跨 chat 拉"我说过什么": 用 wechat-use sent --since "7 days ago" --json(v1.16.12+), 比手动遍历 sessions + filter 干净得多。

群名歧义: wechat-use history "AI 星球" 可能匹配多个(同名群 + 同名联系人)。 撞歧义时 CLI 会列出候选 + 报错,改用 --chat <wxid> 或 --chat <chatroom_id@chatroom> 明确指定。

v1.16.19+ user alias: 长群名 / emoji 前缀群名 fuzzy 经常 miss(詹密群 / 季景铭郡业主三群),用 alias map 一劳永逸:

wechat-use alias add 詹密群 17765974862@chatroom
wechat-use alias add AI星球 20590343959@chatroom
wechat-use alias list                # 看现有
wechat-use alias rm 詹密群           # 删

Resolver 优先级:wxid-shape > alias > contact.db fuzzy。wechat-use send / history / digest / search / recalled / sent / listen --wxid 全部 共享同一查找(写到 ~/.wx-rs/aliases.json)。

# Export
wechat-use export "张三" --format markdown -o zhang.md
wechat-use export "AI 星球" --format json -o ai.json -n 5000

# Incremental (since last checkpoint saved in ~/.wx-rs/cursor.json)
wechat-use new-messages -n 50      # advances checkpoint
wechat-use new-messages --reset    # rewind checkpoint to "now" so next call starts fresh

# Favorites
wechat-use favorites                          # all locally-cached items

# Image media (local in-memory lookup first, CDN fallback)
wechat-use image get <local_id> --chat <chat_id>            # decrypts + writes to ~/.wechat/media-cache/<md5>.jpg
wechat-use image inspect <local_id> --chat <chat_id>        # dump CDN metadata (no key/url leak)

# Voice media — history auto-transcribes by default (v1.13.25+)
wechat-use audio setup [--model small|medium|large]         # one-time: install deps + download model
wechat-use audio transcribe <svr_id> [--language zh]        # single-file pipeline
wechat-use audio get <svr_id>                               # raw SILK_V3 bytes, no decode

语音 — Agent 读取群聊历史记录，开箱即用（v1.13.25+）

运行一次 wechat-use audio setup（约 2–3 分钟，下载约 1.5GB 的 medium 模型并构建 silk-decoder）后，wechat-use history 会自动转写语音消息，让 Agent 能在 display_text 中看到语音内容（并在 media.transcript 中查看结构化数据）——不再有 [语音消息] 占位符破坏对话上下文。转写结果按音频数据块的 SHA-256 值缓存，因此重新读取同一聊天记录几乎是瞬时完成的。

# One-time setup
wechat-use audio setup

# Read a chat — voice messages already transcribed inline
# (Output is {meta, rows} not a bare array — use `.rows[]` not `.[]`.)
wechat-use history <chat> --json | jq '.rows[] | {kind: .message_kind, text: .display_text}'

选择退出（跳过转写以保持历史记录读取速度／保护隐私）：

wechat-use history <chat> --no-transcribe                   # skip transcribe entirely
wechat-use history <chat> --transcribe-model small          # smaller / faster model
wechat-use history <chat> --quiet                           # silence stderr progress lines
                                                        # (auto-on in --json mode)

每条音频记录中的 media.transcript_status 字段会告知 Agent 文本的来源：cached / transcribed / no_deps（运行 wechat-use audio setup）/ failed / skipped_svr_id_zero / invalid_input。

wechat-use doctor 会通过两行报告音频就绪状态，供机器读取端检查默认模型状态，而无需解析字符串：

• audio_transcribe_setup — ffmpeg / whisper-cli / silk-decoder 是否齐备。始终为 ok: true（音频功能可选；缺少工具不得将整体 doctor 状态改为 needs_init）。
• audio_transcribe_default_model — ggml-medium.bin 是否存在。ok 反映实际情况，但不计入整体状态计算，因此没有 medium 的用户仍会看到 status: "ok"。直接读取此行的 ok 字段，即可判断 wechat-use history 的默认转写功能是否可用。

若要转写 history 之外的单个语音文件：

SVR=$(wechat-use history <chat> --json | jq -r '.rows[] | select(.message_kind=="audio") | .server_id' | head -1)
wechat-use audio transcribe "$SVR"           # prints transcript directly

wechat-use audio transcribe --json 默认会对转写文本进行脱敏（JSON 输出中仅包含元数据），避免 Agent 意外记录私人对话内容。传入 --include-transcript 即可选择包含转写文本。

语音 — 不运行 audio setup 时手动解码

wechat-use audio get <svr_id> 会将原始 .silk 字节写入本地（纯本地数据库读取；不使用调试接口、内存查找或 CDN）。若要播放／分享，但不通过 audio transcribe：

# One-time decoder build
git clone https://github.com/kn007/silk-v3-decoder /tmp/silk-v3-decoder
cd /tmp/silk-v3-decoder/silk && make

# Per-file
SVR=691336177198502815
wechat-use audio get "$SVR"
/tmp/silk-v3-decoder/silk/decoder ~/.wechat/audio-cache/$SVR.silk /tmp/$SVR.pcm
ffmpeg -y -f s16le -ar 24000 -ac 1 -i /tmp/$SVR.pcm /tmp/$SVR.wav

注意：SNS / Moments 命令（sns-feed、sns-search、sns-notifications）和旧版 bootstrap 子命令已在 v1.13 系列中移除。数据仍保存在 sns.db 中，可使用 sqlcipher 直接查询，但目前还没有一流的 CLI 接口——请通过路线图跟进。

---

用法 — 实时监听（v1.3）

wechat-use listen 会在新收到微信消息时将其实时流式输出到 stdout（延迟 <500ms）。需要后台守护进程。

# One-time: start the daemon (keep running in a separate terminal or `&`)
wechat-use daemon start

# Stream all new messages
wechat-use listen

# Stream only messages from one chat (server-side filter)
wechat-use listen --wxid filehelper

# JSONL output for agent consumption
# IMPORTANT: pipe stdout only — daemon spawn / errors go to stderr.
#   wechat-use listen --format json | your-adapter      ← OK
#   wechat-use listen --format json 2>&1 | your-adapter ← WRONG, stderr 混流会把 [daemon] 字样混进 stdin
wechat-use listen --format json

# Trigger a shell command per message — the handler sees WECHAT_MSG_* env vars
# Handler stdout is routed to /dev/null (so it doesn't pollute the JSONL stream
# that agents pipe to jq); use stderr or write to a file for logging.
wechat-use listen --on-message "./ai-reply.sh"
wechat-use listen --wxid lisa --on-message 'echo "[$(date +%H:%M)] $WECHAT_MSG_SENDER_WXID: $WECHAT_MSG_TEXT" >> log.txt'

--on-message 环境变量

变量	含义
WECHAT_MSG_TEXT	消息正文（已清理：已解压缩内容，已移除群聊 <sender>:\n 前缀）
WECHAT_MSG_SENDER_WXID	群聊消息发送者的 wxid（私聊时为空字符串——此时聊天 wxid 就是发送者）
WECHAT_MSG_TABLE	Msg_<md5(chat_wxid)> — 内部表名
WECHAT_MSG_CREATE_TIME	Unix 纪元秒数（字符串）
WECHAT_MSG_LOCAL_ID / WECHAT_MSG_LOCAL_TYPE	内部消息 ID 和类型代码
WECHAT_MSG_SENDER_ID	数据库中的 real_sender_id（数字；很少需要——请改用 SENDER_WXID）
WECHAT_MSG_DB	消息来源数据库的绝对路径

安全说明：

• 内容通过环境变量传递，不会通过 shell 字符串插值嵌入命令。可安全防范 $(rm -rf) 式注入。
• 处理程序异步运行（每条消息启动一个子进程）；如果处理时间长于消息到达间隔，处理程序就会堆积。请保持处理程序快速，或自行添加队列。

守护进程生命周期

wechat-use daemon start              # foreground; or `wechat-use daemon start &` for background
wechat-use daemon status             # socket + pid + uptime
wechat-use daemon ping               # round-trip latency sanity check
wechat-use daemon stop               # graceful shutdown

守护进程会缓存每个加密的本地数据库连接，因此 wechat-use sessions / contacts / history / unread 的运行时间低于 30ms（未启用守护进程时为 400–500ms）。它还通过监视 message_*.db-wal 文件变化为 wechat-use listen 提供支持。

模糊聊天对象解析

history / search --in / stats / export / members 接受一个 <chat> 参数，并按以下顺序进行匹配：精确 wxid → 备注 → nick_name → alias。如果有多个匹配项，则选择最近最活跃的匹配项。如果需要消除歧义，请先使用 wechat-use contacts --query ...。

输出格式

所有查询命令默认输出 YAML。添加 --json 可输出 JSON：

wechat-use sessions --json | jq '.rows[] | select(.chat_type=="private" and .unread_count>0)'
wechat-use new-messages --json                # ideal for agents consuming incremental updates

---

何时调用此技能（Agent 触发条件）

发送：

• “给 Lisa 发消息：...”
• “发微信通知我妈 '到家了'”
• “提醒 XXX 会议 5 分钟后开始”
• “send to filehelper ...”

查询：

• “微信里 Lisa 最近说了什么” → wechat-use history Lisa
• “搜一下群里谁提过报销” → wechat-use search 报销
• “AI 星球群有多少人 / 谁发言最多” → wechat-use members + wechat-use stats
• “有哪些未读消息” → wechat-use unread
• “导出我和张三的聊天记录” → wechat-use export 张三 -o ...
• “XX 群里那张图是什么” → wechat-use history "XX群" -n 50（查找 message_kind: image 的 local_id）→ wechat-use image get <local_id> --chat <chat_id>
• “最近收藏了什么” → wechat-use favorites

实时：

• “帮我盯着 Lisa 发来的消息，收到就自动回复 XXX” → wechat-use daemon start，然后运行 wechat-use listen --wxid <lisa-wxid> --on-message "..."
• “把微信消息接进我的 AI assistant” → wechat-use listen --format json --on-message "curl -X POST ..."
• “监控这个群谁提到 '会议'，马上通知我” → wechat-use listen --wxid <group> + 用于 grep 的处理程序

示例用户说法及对应的首次调用：

• “给 Lisa 发消息：会议 5 分钟后开始” → wechat-use contacts --query Lisa → wechat-use send --wxid ... --text ...
• “send to filehelper today's summary” → wechat-use send --text ... --wxid filehelper
• “查一下 XXX 群最近谁发言最多” → wechat-use stats "XXX"

---

🔐 安全 / 数据范围

• 所有操作都 100% 在本地运行 — 不会有数据离开设备。
• wechat-use init 会将原始数据库密钥缓存到 ~/.wechat/keys.json（权限模式 0600）。请将此密钥视同密码 — 任何拥有 keys.json 和 ~/Library/Containers/com.tencent.xinWeChat/... 副本的人，都可以解密你的所有微信数据。
• 切勿将 ~/.wechat/ 提交到 git。切勿将密钥粘贴到聊天窗口。如果密钥泄露：退出登录，然后重新登录微信以轮换密钥。

---

工作机制（简述）

init — 如果缓存的数据库密钥有效，则重复使用；否则通过 macOS 公共调试接口扫描正在运行的受管理克隆。保留现有登录状态；请勿在常规初始化时重启微信。捕获完成后，调试接口会断开。

查询命令 — 从本地配置加载捕获的数据和发现的数据库路径，并直接读取加密的本地数据库。如果后台守护进程正在运行，查询会通过本地 Unix 套接字路由到持久连接池 — 延迟可降低 5-10 倍。

listen — 监视磁盘上的消息数据库是否发生变化，并通过守护进程套接字将每条新记录推送给已订阅的命令行进程。零网络流量；完全在本地运行。

send — 使用 macOS 辅助功能 API 静默定位聊天输入框，然后通过本地调试接口驱动微信的常规发送流程。不会激活窗口，也不会抢占焦点。

---

注意事项

• 仅支持 macOS arm64。只有独立的 WeChat 4.1.9 克隆会持续获得支持 — 运行 wechat-use doctor，确认你的具体构建版本属于适配范围。其他版本可能需要进行适配。
• 二进制文件是独立的原生可执行文件（GitHub Releases）。install.sh 会自动清除 macOS Gatekeeper 隔离属性。
• 这不是微信 API。这是用户空间研究产物，任何微信更新都可能导致其无法使用。
• LICENSE 禁止商业用途 — 请参阅 LICENSE 和 DISCLAIMER.md。

更新 CLI

开始会话前，Agent 应检查 wechat 是否足够新。该二进制文件是独立的；升级只需获取更新版本。

检查当前版本：

wechat --version

升级到最新版本（安全、可重复执行） — wechat-use upgrade（参见下文“## 升级”）。如果当前版本没有此命令，请重新运行安装程序：

curl -fsSL https://raw.githubusercontent.com/leeguooooo/wechat-use/main/install.sh | bash

两种方式都会从 GitHub 获取最新的已标记版本二进制文件，重新安装到 ~/.local/bin/wechat，并再次清除任何 Gatekeeper 隔离属性。不会丢失数据——~/.wechat/keys.json 和 state.json 都不会被改动。

升级时机：

• 某条 wechat-use 命令显示 wechat-use X is available，或 wechat-use upgrade --check 显示 current -> latest
• wechat --version 比 https://github.com/leeguooooo/wechat-use/releases 上的最新版本标签落后一个以上的次版本
• 用户要求的命令尚不存在（此页面上的功能矩阵对应最新版本；较旧的二进制文件可能缺少某些命令）
• WeChat 本身已更新——新版本可能需要发布新的 wechat 版本来跟进适配数据（请留意 https://github.com/leeguooooo/wechat-use/releases 上的说明）

停止 WeChat 自动更新（强烈建议，v1.16.33+）：

wechat-use init 成功且 wechat-use send 在当前构建版本上正常工作后，运行：

wechat-use update-guard disable

此操作会使用 chflags uchg 锁定 WeChat 容器中的 MacUpdate 目录，防止 Tencent 的静默 dylib 热更新替换二进制文件。当前适配配置会保持有效，直到用户明确运行 wechat-use update-guard enable 将其恢复。禁用后，wechat-use doctor 会将 wechat_update_guard 显示为 ✓。此操作仅作用于用户级别，且可撤销——不会触及 WeChat 二进制文件、NSUserDefaults 或 TCC。

适配尚未列入已验证列表的全新 WeChat 构建版本（v1.16.32+）：

如果 wechat-use doctor 显示 wechat_dylib_fingerprint ✗ (not in verified list)，且 wechat-use send 因“build not supported”而失败：

wechat-use probe-build

此操作会对本地 dylib 进行哈希处理，运行 literal_scan 以验证 SQLCipher 密钥提取，通过模式匹配 ARM64 切片中的三个路由锚点，并将推导出的数值偏移量 POST 到适配队列。**不会上传二进制文件字节。**等待 send 适配期间，读取命令（history / sessions / unread / sent）会通过 literal_scan 回退方案继续工作。

更新技能元数据（Agent 通过 skills.sh 安装时，即此 SKILL.md 文件本身）：

# refresh skill files (including this SKILL.md) from the public repo
npx skills update leeguooooo/wechat-use -g

如果 Agent 在运行 npx skills update 后看到 wechat: command not found，仍需运行 install.sh——技能更新不包含二进制文件。

升级

下方的启动器命令将在后续版本中推出。在 v1.18.13 及更早版本中，仍需使用文档所述的 install.sh 命令进行升级。

当任何 wechat-use 命令显示 wechat-use X is available 时，告知用户并询问是否运行 wechat-use upgrade（仅更新 CLI；添加 --skills 还会刷新此技能——仅适用于 wechat-use 的插件、 git 检出或由安装程序管理的副本）。只检查而不做更改： wechat-use upgrade --check（或 --json）。使用 --tag vX.Y.Z 固定版本。此操作绝不会发送 WeChat 消息，也不会要求登录。用户也可以直接说“升级 wechat-use” / “upgrade wechat-use”。 这与 wechat-use update-guard 无关，后者会阻止 WeChat 自身的自动更新。

如果技能来自 upgrade 无法刷新的位置：

• Claude Code 插件：claude plugin update wechat-use@leeguooooo-plugins
• 整个系列：curl -fsSL https://raw.githubusercontent.com/leeguooooo/plugins/main/upgrade-use-family.sh | sh

支持

• 问题反馈 → https://github.com/leeguooooo/wechat-use/issues