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、Accessibility、シェルインストーラー、または管理対象の 4.1.9 に関する手順は適用しないでください。
• macOS： Windows セクションはスキップし、macOS セクションに従ってください。
• Linux および Intel Mac は、サポート対象のネイティブランタイムがありません。

Windows x64（実験的）

スタンドアロンパッケージは、https://github.com/leeguooooo/wechat-use/releases/tag/windows-v0.1.0 で公開されています。パッケージにはランタイムが含まれています。このパッケージを使用するために、システム Python をインストールしたり呼び出したりしないでください。テスト済みの WeChat ビルドは 4.0.6.17 で、ログイン互換性には制限があります。すべての Windows 版 WeChat ビルドがサポートされているわけではありません。メディア、バックグラウンド送信、自動チャット選択、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 です（listen は JSONL）。--from-start が指定されていない場合、最初のリスナーはベースラインを確立します。event_id で重複を排除し、1 つの状態ディレクトリに対して複数のリスナーを同時に実行しないでください。キーは現在のユーザーの DPAPI で暗号化されています。キーを表示したりアップロードしたりしないでください。

フォアグラウンド送信では、すでに開かれている曖昧さのないチャットと、空の入力欄が必要です。選択された WeChat ウィンドウが前面に表示されます。既存の送信許可に従ってください。ただし、依頼されていないテストメッセージを送信しないでください。送信が行われたか不確かな場合は、それ以上の操作を行う前に履歴を確認してください。サーバーに記録された行は、既読通知を意味するものではありません。

MCP で使用する場合は、runtime.json の executable と mcp_args（["mcp"]）を使用してください。ソースからのインストールでは、記録された python を -X utf8 <script> mcp とともに使用します。これは wechat_sessions、wechat_contacts、wechat_history、および実験的な wechat_send をサポートします。commit のデフォルトは false です。

古い WeChat ビルドではログインが拒否される場合があります。compat-version --pid ... はデフォルトでは検査のみを行います。この制限の修正をユーザーが依頼した場合に限り、明示的な実験用オプション --apply を適用してください。この機能はフィンガープリントによる制限があり、一時的なフィールドを 1 つ変更してロールバック用ジャーナルを保存します。今後ログインが受け入れられることを保証するものではありません。QR コードのスキャン／ログイン確認はユーザーが行います。

Claude のフックエラー

このプラグインにはUserPromptSubmit フックは定義されていません。Python が見つからないというフックエラーは、別途設定されたフックに関するものであり、スタンドアロンの WeChat ランタイムに関するものではありません。変更する前に Claude の設定で該当するフックを確認し、関係のないフックはそのまま維持してください。すべてのフックを無効にしたり、WeChat を再インストールしたりしないでください。ブロッキングを伴わないフックエラーから、CLI が利用できないとは判断できません。読み込まれたスキルにこのプラットフォームのセクションがない場合は、マーケットプレイス／プラグインを更新して Claude を再読み込みしてください。

Windows の手順は以上です。Windows では、以下の macOS セクションを実行しないでください。

macOS のみ：安定版 CLI

セットアップの失敗とユーザーからの報告（v1.18.7 以降）

リリース状況：v1.18.13 が公開されています。それ以降のバージョンについては GitHub Releases を確認してください。以下の機能はリリース済みビルドに適用されます。古いバージョンをお使いの場合は、README のインストールコマンドでアップグレードできます。

サポートを始める前に、macOS のバージョンや新規インストールかどうかをユーザーに尋ねる必要はありません。セットアップウィンドウが、環境とサービスに関する情報を自動的に収集し、機密情報を伏せて表示します。エラーのスクリーンショットから WXS-… 問題コードを確認してください。さらに詳しい情報が必要な場合は、待機中のページを含むセットアップページのいずれでも、ユーザーが「复制诊断信息」をクリックできます。コアを起動できない場合も、このウィンドウには最小限のレポートが表示されます。keys.json、アクティベーショントークン、生のメモリ出力、個人チャットデータは絶対に要求しないでください。

システムの開発者ツールの認証が不足している場合は、初期化前に検出され、macOS 標準の管理者確認を伴う「授权并继续」が表示されます。既存のログイン状態と許可設定は維持してください。原因が不明な初期化エラーに対して、再インストールや権限の一括リセットを提案しないでください。v1.18.6 のエラーウィンドウにある「修复安装」ボタンを使うと、現在のリリースに一度アップグレードできます。その後は、特定された問題に応じて対処し、何度も再インストールしないでください。

macOS 版 WeChat の統合 CLI です。メッセージの送信や、セッション、連絡先、チャット履歴、グループメンバー、モーメンツ、お気に入りに関する暗号化されたローカルデータベースの検索ができます。会話の選択は管理対象のクローン内で行われ、クローンのウィンドウをアクティブにしたり、前面に表示したりすることはありません。

管理対象の WeChat 4.1.9（v1.18.0 以降）

インストーラーは、対応するローカルの 4.1.9 を自動的にコピーするか、固定された Tencent DMG を（確認を求めずに）ダウンロードします。独自のバンドル ID とサンドボックスコンテナを持つ ~/Applications/WeChat-4.1.9-wechat-use.app をインストールし、そのクローンのアップデートを無効にして、~/.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 のみです。インストールを修復する場合はインストーラーを再実行してください。最新の WeChat をダウンロードしないでください。

セットアップと復旧の統合（v1.18.6+）

UI を開かずに現在のセットアップ段階を確認するには、wechat-use setup --json を使用します。一般ユーザー向けの curl インストーラーと対話型の wechat-use init は、同じネイティブのセットアップウィンドウを使用します。このウィンドウは既存のアクティベーション、ログイン、キーを保持し、ツール用に互換性のあるインストール済み開発ツールのみを選択して、公式バックグラウンドサービスを起動し、サービスの実際の所有者と権限を検証します。

ユーザーによる操作が必要な場合は、wechat-use setup を実行するか、~/Applications/WechatUseSetup.app を開いてください。アクティベーション、ログイン、システム認証、ドラッグ＆ドロップ、再確認はウィンドウに任せてください。doctor、init、launchctl、xcode-select の修復コマンドを順番にユーザーへ案内しないでください。権限回避のために、Terminal 所有のデーモンを起動してはいけません。サービスは公式ブリッジが所有している必要があります。

ブリッジの /setup/status は、キーやアクセシビリティの許可を利用できるようになる前から利用できます。これは診断専用で、送信は引き続き制限されます。セットアップの制御には、認証されていない HTTP 書き込みエンドポイントではなく、検証済みの launchd プロセスに対するローカルシグナルを使用します。

未確認のセットアップテストは保存され、ウィンドウを閉じたり再度開いたりしても自動的に再実行されません。--skip-verify は明示的に送信をスキップします。権限が利用可能であることだけでは、配信の証拠にはなりません。本人確認と実際の macOS の許可は、引き続きユーザー自身が管理します。

ユーザー向けセットアップガイド

バックグラウンド実行

「システム設定」でツールが有効になっていると表示されていても、実際の launchd ブリッジがアクセシビリティを拒否する場合は、表示されたスイッチを証拠と見なさないでください。インストール先のパスと署名を確認し、そのツールのスイッチだけを更新して、再読み込みしたばかりの公式サービスを再確認してください。それでも確認に失敗する場合、特定の古い権限エントリが古くなっている可能性があります。認可されたローカルのコンピューター制御エージェントは、現在インストールされているバイナリを使って、問題のあるツールのエントリだけを削除して追加し直せます。各操作の前に対象の行を特定してください。座標を使った無差別な操作や、ほかのアプリの権限のリセットは行わないでください。専用の WeChat プロセスとキーは保持してください。その後、HTTP のヘルス状態、デーモンによる実際のアクセシビリティ判定、親プロセスが公式ブリッジであることを確認してください。ユーザー本人の確認が必要なチャレンジには、引き続きユーザー自身の操作が必要です。

通常の操作では、ユーザーの前面ウィンドウを維持する必要があります。通常の準備として open -a を呼び出したり、クローンをアクティブ化・前面表示・最小化解除したり、アプリケーションを切り替えたり、前面表示を伴うホットキーやグローバルホットキーを使ったりしないでください。プロセスを指定した入力とバックグラウンドでの会話ナビゲーションを使用し、宛先が正確であることを確認してください。これはインストール、初期化、権限エラー、サービス復旧にも適用されます。実行可能な診断情報を返し、「システム設定」、Finder、権限ダイアログを自動的に開いたり、送信を再試行したりしないでください。doctor --fix-tcc は明示的な対話型復旧コマンドであり、「システム設定」を開きます。 利用可能なバックグラウンド手段がないことを確認した場合に限り、最終手段として前面での復旧を行ってください。未確認のメッセージを、アクティブ化して無条件に再送信してはいけません。まず配信状況を調べてください。AX スナップショットが空であることだけでは、前面での復旧や WeChat の再起動を正当化できません。

最短手順（最初にお読みください）

1 回の呼び出しで 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）を検索します：
   • 一致が 1 件 → 送信
   • 複数一致するが、最近のアクティビティ（30 日）があるのが 1 件のみ → その相手に送信
   • それ以外 → 終了コード 2 + JSON {"status":"ambiguous","candidates":[...]} を返します。エージェントが候補を選び、明示的な 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>"
}

エージェントは candidates[0].wxid を読み取り、wechat-use send "<text>" <wxid> を再試行してください。最上位の候補に最近のアクティビティがない場合、または複数の候補に最近のアクティビティがある場合を除き、ユーザーに確認してはいけません。

エージェント連携用 HTTP ブリッジ（v1.10+）

wechat-bridge は、デーモンの RPC を安定したローカルホスト HTTP インターフェイスとして提供する独立したバイナリです。WeChat をエージェントプラットフォーム（Hermes、n8n、Dify、LangChain、カスタムボット）に接続する場合に使用してください。HTTP の方が、呼び出しごとに CLI を起動するよりも低コストで連携できます。

# 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"

エンドポイント：

Method	Path	Maps to
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 パスでは、File Transfer Assistant のウォームアップサンプルは不要になりました。/health では、デーモンの稼働状態とは別に wechat.state と wechat.account_state が報告されます。not_ready は、アカウントが送信可能な状態ではないことを意味します。doctor の needs_wechat_login は WeChat へのログインが必要な状態を示しており、再初期化やキャッシュの削除が必要という意味ではありません。WeChat で電話による確認または QR コードログインが必要になる場合があります。このツールがその確認を回避することはありません。

通常のファイル、動画、カードは、ネイティブ送信ではまだサポートされていません。

HTTP 経由での画像送信

画像パスには、ブリッジホスト上のファイルを指定する必要があります。ネイティブリクエストでは image_path（または imagePath）、Hermes リクエストでは imagePath を使用します。画像のみのリクエストでは、テキストフィールドを省略してください。テキストと画像は別々に送信してください。両方を 1 つのリクエストにまとめると、内容が黙って破棄されるのではなく、リクエストが拒否されます。

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 は、次の JSON 配列を含む event: messages を出力します。

{
  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 は使用しないでください。DM では双方向のメッセージで同じ senderId が共有されます。
• グループでは、isGroup && isMentioned の場合にのみ応答してください。デーモンが正式なメンション比較をすでに解決しているため、mentionedIds.includes(myWxid) を自分で再実装しないでください（myWxid が備考や検索結果であっても、デーモンが正しく解決する場合があります）。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 を解析し、そのパスに対してホストエージェントのファイル／画像読み取り機能を使用してください。デフォルトの --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 より前のすべてのフィールドは、名前と型が維持されています。新しいフィールドは追加のみです。

エージェント向けセキュリティ上の注意：

• ブリッジは 127.0.0.1 にバインドされており、トンネリングなしでは LAN に公開されません。
• 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 ブリッジ（v1.10+）	wechat-bridge（別バイナリ）	localhost HTTP 経由でのエージェント／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	ローカル REST ブリッジを Cloudflare Tunnel 経由でリモートサービスに公開します。詳細は 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／ドメインは不要です）。cherry-class などの SaaS 連携で使用します。プロトコルについては 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 のバックグラウンド自動ホットアップデート経路をロックします（MacUpdate パスに対して chflags uchg を実行）。Tencent が新しい dylib を配布しても置き換わりません。現在のビルドへの適応を安定させるため、init の完了後に一度 disable を実行することをおすすめします。CLI の起動時に自己診断して警告しますが、処理はブロックしません。
probe-build（v1.16.32+）	probe-build	WeChat をツールが認識しない新しいビルドにアップグレードした場合に実行します。ローカルの literal_scan と pattern-match routing アンカーから shift 値を出力し、/v2/probe に POST して適応キューに送ります。バイナリは送信しません。送信するのは導出された数値のみです。read-side コマンド（history / sessions など）は literal_scan fallback により、すぐに使用できます。

すべてのクエリコマンドは、デフォルトでYAML 出力（エージェント向け、トークン消費量が少ない）を使用します。JSON を取得するには --json を追加してください。

🛑 安全ルール（重大 — send を呼び出す前にお読みください）

すべての send 呼び出しは、既知の wxid を解決できなければなりません。 「現在のチャット」に暗黙にフォールバックすることはありません。そのフラグ（--current-chat）は 1.13 より前に削除されています。リゾルバーが宛先を見つけられない場合は、処理を中止してユーザーに確認してください。

「给 XXX 发 YYY」（XXX に YYY を送る）の正しい手順：

1. まず試す：wechat-use send "YYY" XXX。高速パスのリゾルバー（このドキュメントの冒頭を参照）は、wxid 形式の宛先を即座に処理し、ローカルの連絡先 DB でセッションの新しさを考慮しながら名前をあいまい検索します。
2. 終了コード 2 かつ status: "ambiguous" の場合：candidates[0] の last_seen が約 30 日以内で、他の候補が古い、または空の場合、CLI はすでに自動選択して成功を返しています。実際に曖昧な場合（最近のアクティビティがある候補が複数ある場合）は、推測せず、ユーザーに確認して候補を選んでください。
3. no contact matches "XXX" の場合：ユーザーに wxid を尋ねるか、wechat-use contacts --query XXX --brief の候補を確認してもらってください。

厳守事項（エージェントは必ず守ること）：

• wxid を推測したり、捏造したりしないでください。 解決に失敗した場合は、ユーザーに確認してください。
• wxid を探すために、ファイルシステムをスキャンしたり、ログを grep したり、AppleScript を使用したりしないでください。 CLI は高速パスでローカルの連絡先 DB をすでに検索します。宛先が見つからない場合は、それを信頼して処理を中止し、ユーザーに確認してください。
• 高速パスの send で曖昧だと通知された場合を除き、wechat-use contacts と wechat-use send を別々の呼び出しとして続けて実行しないでください。1 行で実行すれば、約 400ms とエージェントの往復を 1 回分節約できます。

---

機能一覧

機能	状態	コマンド
DB キーとキャッシュレイアウトの抽出（クエリコマンドを実行する前に必ず行う最初の手順）	✅	wechat-use init
特定の wxid／グループ名／ニックネームへのテキスト送信	✅	wechat-use send "..." <recipient>
あらゆる Unicode／絵文字／CJK／長さに対応	✅	組み込み
UI のちらつきなし（フォーカスを奪わない）	✅	send のデフォルト
最近のチャットセッションの一覧表示	✅	wechat-use sessions
未読メッセージがあるセッション	✅	wechat-use unread
前回の確認以降の新着メッセージ	✅	wechat-use new-messages
連絡先の検索／あいまい検索	✅	wechat-use contacts [--query KW]
チャット履歴（個人／グループ）	✅	wechat-use history <chat> [-n 500]
LLM 対応グループダイジェスト	✅ 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 を 1 回実行後、wechat-use audio transcribe <svr_id>（1.13.25 以降）
初回送信時のチャットコンテキスト	自動	デーモンが送信前に正確な宛先を選択して確認するため、ユーザーがチャットをクリックしたり、ウォームアップメッセージを送信したりする必要はありません。
リアルタイム受信ストリーム（v1.3）	✅	wechat-use listen — 新着メッセージを監視し、標準出力に送信
受信コールバック → シェルコマンド（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 — または、任意のクエリコマンドで自動起動
WeChat バイナリのフィンガープリント検証（v1.7.2 以降）	✅	wechat-use doctor で、WeChat のホットフィックス更新後の差異を確認できます
画像／ファイルの送信	⏳ ロードマップ	—
グループ一斉送信	❌ 禁止	不正利用防止のため、LICENSE で禁止されています
Linux／Intel Mac	❌	この macOS バックエンドには arm64 が必要です。Windows では、上記の別の実験的バックエンドを使用します。
未検証の WeChat ビルド	⚠️ 未検証	適応データにずれが生じる可能性があります。wechat-use doctor が警告します

---

エージェント：初回セットアップ

ステップ 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 自体がログイン画面を表示している場合は、ユーザーが実際のログイン認証を完了する必要があります。ログイン済みのクローンを再起動したり、バンドル ID を変更したり、ローカルのアカウントデータを削除したりして、新たな認証を発生させてはいけません。

ステップ 3 — サービスの権限を確認します：

wechat-use doctor --json

実行中のデーモンの daemon_accessibility の結果と、ブリッジのヘルス状態を確認してください。アクセシビリティ権限はインストール済みのヘルパー ID に付与されます。署名済みのアップグレードでは、これらの権限が保持されるはずです。権限がない場合は、wechat-use init --fix-tcc を実行してください。適切な設定パネルを開き、Finder でドラッグ＆ドロップするバイナリを選択してから、実行中のデーモンを自動で再確認します。ユーザーに隠しパスを探したり、復旧コマンドを自分で入力したりするよう求めてはいけません。

ステップ 4 — チャットを手動で選択せずに送信を確認します：

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

デーモンは選択中のチャット ID を読み取り、バックグラウンドで会話を切り替えて、入力前に指定された宛先を正確に選択します。Enter を押す前に、ID を再確認します。ビルドのキャリブレーションがない場合、コンテキストが曖昧な場合、宛先が変更された場合、または対象が利用できない場合は、送信前に停止します。通常のセットアップ手順として、ユーザーに filehelper をクリックしたり、ウォームアップメッセージを送信したりするよう求めてはいけません。現在のローカル候補では、宛先コンテキストに一致するキャリブレーションが必要です。このキャリブレーションの配布はまだ保留中のため、リリース前にテストする必要があります。

配信として扱えるのは、指定されたチャット内で確認できた記録のみです。delivery_verify_timeout は配信の遅延を示している場合があります。再試行する前に履歴を確認してください。自動準備に失敗した場合は、診断出力を保持して wechat-use doctor --json を実行してください。回避策として、ログイン済みの WeChat を再起動したり、そのアカウントを再アクティベートしたりしてはいけません。

AX ツリーが空、または自動化のスクリーンショットが空白であっても、WeChat の画面が空である、ログアウトしている、またはフリーズしている証拠にはなりません。診断には、プロセス、CLI、データベースの証拠と、ユーザーに見えている状態を使用してください。自動化のスナップショットを復旧するだけの目的で、ログイン済みのクローンを終了して再起動してはいけません。

---

送信失敗のパターン（エージェントによる自己復旧テーブル）

wechat-use send が {ok: false, …} を返す場合、または stderr がサポート用ペイロードの reason: 欄と一致する場合は、ユーザーにデバッグを依頼する前に、以下の手順に従ってください。バックグラウンドで診断を行い、その場で完了できないことが確認された手順に限り、人による操作を依頼してください。送信失敗を根拠に、フォーカスを取得する許可があると推測してはいけません。

reason: スロット	根本原因	エージェントの対応
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（詳細：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.* LaunchAgents があり、orchestrate（KeepAlive）が古い launchd の責任チェーンを使って wechatd を再起動しました	curl -fsSL https://raw.githubusercontent.com/leeguooooo/wechat-use/main/install.sh | bash を再実行します。v1.16.12 以降の install.sh は、すべての ai.wechat.*.plist を bootout し、正しい順序で 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 が含まれます。人間が読める中国語のエラーメッセージではなく、これらの正確なフィールド名で照合してください（メッセージはリリースごとに変わる可能性があります）。 エージェント向け 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> プレフィックスです（テキストのみで、実際のメンション通知はありません — issue #4 を参照）。
--dry-run	いいえ	受信者を解決して検証しますが、送信はしません。エージェントによるドライチェックには --json との併用が適しています。
--json	いいえ	JSON 出力です。

send --json の3状態契約（v1.13.20+）

すべての --json 出力にはトップレベルの ok: bool が含まれます。エージェントは3種類のスキーマを解析することなく、直接 if (r.ok) {...} else {...} を実行できます。

状態	発生条件	形状（トップレベルフィールド）
success	wechat-use send TEXT RECIPIENT --json で実際に送信し、成功	{ok: true, sent: true, reason: null, diagnostic: {…SendResult 全フィールド…}}
dry-run	--dry-run --json（リゾルバーの処理は成功し、実際の送信はしない）	{ok: true, dry_run: true, text, resolved_wxid}
error (early)	--json と併用した際に引数が不正／リゾルバーで見つからない／候補が曖昧／ネットワーク切断	{ok: false, exit_code: <int>, error: "<msg>"}
error (send fail)	送信失敗、または配信が未確認（自動準備の失敗／権限不足／バージョン未対応など）。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 には引き続き人間が読めるエラーの説明が出力されます（ターミナルユーザー向け）。エージェントは 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 ペイロードの形式（エージェント向けの安定した契約）

トップレベルのラッパー（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 より 24 時間以上先行しており、シャードがずれている可能性が高い）／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" を解析した後、エージェントはタイムゾーンを再計算せず、この 3 つの値を使って「実際に検索した範囲は X から Y で、現在時刻は Z です」とユーザーに伝えられます。

各 message row のフィールド（snake_case）：

フィールド	型	説明
local_id	int	DB 行の主キー（chat ごとに単調増加）。image get <local_id> --chat <wxid> で画像を取得します。
server_id	int	WeChat サーバー側の msg id（取り消し時は replacedMsgId を参照）。
local_type	int	元の type code。下位 16 ビットをマスクした値は、1 がテキスト、3 が画像、34 が音声、43 が動画、49 が appmsg などです。
message_kind	string	enum：text／image／audio／video／url／mini_program／recalled／appmsg など。Wechaty と整合しています。
display_text	string	サニタイズ済みの、人が読める本文（text は body と同じ。image／url はタイトルを抽出。recalled は代替テキストを表示）。
message_content	string	元の body（raw XML の場合や、グループメッセージで <sender>:\n のプレフィックスが付く場合があります）。デバッグ用です。本番ロジックでは display_text を使用してください。
sender_wxid	string | null	グループメッセージでは実際の送信者の wxid。DM では両側とも null（WeChat DB は 1:1 chat で sender wxid を記録しません）。この値だけで自分が送信したかを判定できません（DM では双方を誤判定し、システムメッセージも null になります）。
sender_display_name	string | null	daemon が解決した表示名（グループのグループ内ニックネーム／連絡先のメモ／ニックネーム）。v1.16.19+ の変更点： 連絡先 DB にアクセスできない、または該当する wxid が見つからない場合、null ではなく生の wxid にフォールバックします（エージェントは shape の有無を両方処理する必要がありません）。DM の自分の送信メッセージ／システムメッセージは引き続き null です。
real_sender_id	string	chat ごとに増加する ID（文字列で、常に空ではありません）。WeChat は現在のアカウントに固定 ID を割り当てます（この環境での値は "2" ですが、アカウントによって異なる場合があります）。その他の整数値は相手またはグループメンバーです。これを使って自分が送信したか判定します：filehelper の履歴をスキャンし、自分の ID を取得します（filehelper は 100% 自分からの送信で、出現数が最も多い ID が自分の ID です）。他の chat では同じ ID でフィルタリングします。
chat_id / username	string	会話の wxid（DM）または xxxx@chatroom（グループ）。
chat_display_name	string	グループ名／連絡先のメモ／ニックネーム（v1.13.9+ で自動解決）。xxxx@chatroom はそのままでも判別できます。
create_time	int	epoch 秒。
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 固有の構造化フィールド（SSE schema を参照）。

フィールドの安定性：フィールドが追加される場合、デフォルト値は null または省略です。名前が変更されたり、型が変わったりすることはありません（この契約は v1.10.27 以降、SSE schema の単体テストで保証されています）。

複数の chat をまたいで「自分が何を言ったか」を取得するには： wechat-use sent --since "7 days ago" --json（v1.16.12+）を使用してください。sessions を手動で列挙してフィルタリングするより、ずっと簡潔です。

グループ名の曖昧さ： wechat-use history "AI 星球" は複数の候補（同名のグループと連絡先）に一致する可能性があります。曖昧な候補がある場合、CLI は候補を一覧表示してエラーを報告するため、--chat <wxid> または --chat <chatroom_id@chatroom> を使って明示的に指定してください。

v1.16.19+ のユーザーエイリアス： 長いグループ名や emoji で始まるグループ名は fuzzy 検索で見つからないことがよくあります（詹密群／季景铭郡业主三群）。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

音声 — エージェントがグループの履歴を読み取れるようになります（v1.13.25+）

一度 wechat-use audio setup を実行すると（ダウンロードとビルドに約2〜3分かかります。中サイズのモデルを約1.5GBダウンロードし、silk-decoderをビルドします）、wechat-use history が音声メッセージを自動で文字起こしするため、エージェントは発話内容を 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 フィールドで、テキストの取得元をエージェントに知らせます：cached / transcribed / no_deps（wechat-use audio setup を実行してください）/ failed / skipped_svr_id_zero / invalid_input。

wechat-use doctor は音声機能の準備状況を2つの行で報告するため、マシンから文字列を解析せずにデフォルトモデルの状態を確認できます：

• audio_transcribe_setup — ffmpeg / whisper-cli / silk-decoder の全体的な有無です。音声機能はオプションのため、常に ok: true です。ツールが見つからなくても、全体のdoctorステータスが needs_init に変わることはありません。
• audio_transcribe_default_model — ggml-medium.bin が存在するかどうかです。ok は実際の状態を反映しますが、全体のステータス計算からは除外されるため、中サイズモデルがなくても status: "ok" と表示されます。wechat-use history のデフォルトの文字起こしが動作するかどうかを確認するには、この行の ok フィールドを直接確認してください。

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出力にはメタデータのみが含まれます）。出力するには --include-transcript を指定してください。

音声 — audio setup を省略する場合の手動デコード

wechat-use audio get <svr_id> は、未加工の .silk バイト列をローカルに書き出します（純粋なローカルDB読み取りであり、デバッグ用インターフェース／メモリ内検索／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／モーメンツ関連のコマンド（sns-feed、sns-search、sns-notifications）と、レガシーの bootstrap サブコマンドはv1.13系列で削除されました。データは引き続き sns.db に保存されており、sqlcipherで直接クエリできますが、まだ正式なCLI機能はありません。ロードマップで進捗を確認してください。

---

使用方法 — リアルタイムで受信（v1.3）

wechat-use listen は、新着のWeChatメッセージを受信と同時に標準出力へストリーミングします（遅延は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	DBの real_sender_id（数値。通常は不要です。代わりに SENDER_WXID を使用してください）
WECHAT_MSG_DB	メッセージの取得元となったメッセージDBの絶対パス

安全性に関する注意：

• コンテンツは環境変数を通じて渡され、コマンドにシェル展開される形で埋め込まれません。$(rm -rf) のようなインジェクションに対して安全です。
• ハンドラーは非同期で実行されます（メッセージごとにサブプロセスを1つ起動します）。メッセージの到着より処理に時間がかかると、ハンドラーが滞留します。ハンドラーを高速にするか、独自のキューイングを追加してください。

デーモンのライフサイクル

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

デーモンは暗号化されたローカルDB接続をそれぞれキャッシュするため、wechat-use sessions / contacts / history / unread を30ms未満で実行できます（デーモンがない場合は400〜500msです）。また、message_*.db-wal ファイルの変更を監視して、wechat-use listen にも機能を提供します。

あいまいなチャットの解決

history / search --in / stats / export / members は <chat> 引数を受け取り、次の順序で照合します：wxid の完全一致 → remark → 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

---

このスキルを呼び出すタイミング（エージェントのトリガー）

送信：

• 「给 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 then 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> + handler that greps

ユーザーの発話例と、最初に実行すべきコマンド：

• 「给 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 は、未加工の DB キーを ~/.wechat/keys.json（モード 0600）にキャッシュします。このキーはパスワードと同様に扱ってください。keys.json と ~/Library/Containers/com.tencent.xinWeChat/... のコピーを持つ人は、WeChat のすべてのデータを復号できます。
• ~/.wechat/ を Git にコミットしないでください。キーをチャットウィンドウに貼り付けないでください。キーが漏えいした場合は、WeChat からログアウトして再ログインし、キーをローテーションしてください。

---

仕組み（概要）

init — キャッシュ済みのデータベースキーが有効な場合は再利用し、そうでない場合は macOS の公開デバッグインターフェイスを通じて、実行中の管理対象クローンをスキャンします。既存のログイン状態を維持してください。通常の初期化として WeChat を再起動しないでください。デバッグインターフェイスは取得後に切断されます。

クエリコマンド — ローカル設定から取得済みのデータと検出済みの DB パスを読み込み、暗号化されたローカルデータベースを直接読み取ります。バックグラウンドデーモンの実行中は、クエリはローカルの Unix ソケット経由で永続接続プールにルーティングされ、レイテンシが 5～10 倍低減します。

listen — ディスク上のメッセージデータベースの変更を監視し、新しい行をデーモンソケット経由で登録済みの CLI プロセスにプッシュします。ネットワーク通信は発生せず、すべてローカルで実行されます。

send — macOS Accessibility API を使用してチャット入力欄を目立たないように指定し、ローカルデバッグインターフェイス経由で WeChat の通常の送信処理を実行します。ウィンドウのアクティブ化やフォーカスの奪取は発生しません。

---

注意事項

• macOS arm64 専用です。継続的にサポートされるのは独立版の WeChat 4.1.9 クローンのみです。wechat-use doctor を実行して、お使いのビルドが対応対象に含まれているか確認してください。他のバージョンでは適合作業が必要になる場合があります。
• バイナリはスタンドアロンのネイティブ実行ファイルです（GitHub Releases）。install.sh は macOS Gatekeeper の隔離属性を自動的に解除します。
• WeChat API ではありません。ユーザーランドでの調査成果物です。WeChat の更新によって動作しなくなる可能性があります。
• LICENSE により商用利用は禁止されています。LICENSE と DISCLAIMER.md を参照してください。

CLI の更新

セッションを開始する前に、エージェントは wechat が十分に新しいバージョンであることを確認してください。バイナリは単体で動作するため、新しいリリースを取得するだけでアップグレードできます。

現在のバージョンを確認する：

wechat --version

最新バージョンにアップグレードする（安全で、繰り返し実行できます） — wechat-use upgrade（下記の「## 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）よりマイナーバージョンで 1 つ以上古い場合
• ユーザーが依頼したコマンドがまだ存在しない場合（このページの機能一覧は最新リリースを反映しています。古いバイナリにはコマンドがない可能性があります）
• WeChat 自体が更新された場合 — 新しいバージョンへの対応データを追跡するため、新しい wechat リリースが必要になることがあります（https://github.com/leeguooooo/wechat-use/releases に記載がないか確認してください）

WeChat の自動更新を停止する（強く推奨、v1.16.33+）：

wechat-use init が成功し、現在のビルドで wechat-use send が動作した後に、次を実行します。

wechat-use update-guard disable

WeChat のコンテナ内にある MacUpdate ディレクトリを chflags uchg でロックし、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 スライスに対して 3 つのルーティングアンカーをパターンマッチングしたうえで、導出した数値シフトを適応キューに POST します。バイナリのバイト列はアップロードしません。 send の適応を待つ間も、リテラルスキャンのフォールバックによって読み取りコマンド（history／sessions／unread／sent）は引き続き使用できます。

スキルのメタデータを更新する（エージェントを skills.sh 経由でインストールした場合の、この SKILL.md 自体）：

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

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 を追加します。対象はプラグイン、Git チェックアウト、またはインストーラー管理の wechat-use コピーのみです）。変更を加えずに確認するには、wechat-use upgrade --check（または --json）を実行します。--tag vX.Y.Z でリリースを指定できます。WeChat メッセージを送信したり、ログインを求めたりすることはありません。ユーザーは「升级 wechat-use」または「upgrade wechat-use」と伝えるだけでもかまいません。これは、WeChat 自体の自動更新をブロックする wechat-use update-guard とは無関係です。

スキルが 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