personal-wechat

Wisdom 経由の個人 WeChat

ユーザーがセルフホストしている Wisdom サービスを使って、個人の WeChat アカウントを操作します。現在のデプロイでは、コンテナー内でネイティブ版 Linux WeChat を実行し、HTTP API と、ログインおよび診断用の VNC デスクトップを提供しています。

認証情報は personalwechat BYOC コネクターによって注入されます。

• PERSONALWECHAT_BASE_URL — Wisdom サーバーのベース URL（例：http://203.0.113.10:8000）。
• PERSONALWECHAT_API_TOKEN — Wisdom の API_TOKEN。シークレットです。絶対にエコー、出力、ログへの記録をしないでください。

ヘルパーはトークンを Authorization: Bearer ... として送信し、URL にトークンを含めることはありません。Wisdom は UI を介した各操作（検索、送信、モーメンツ、グループ）に対して 202 とタスク ID を返します。ヘルパーが /api/tasks/{id} をポーリングし、最終結果のみを出力します。

これはユーザーの実際の個人 WeChat アカウントです。読み取り操作はそのまま実行されます。すべての書き込み操作（送信、共有、モーメンツ、グループの変更）は、まずドライランを行い、その内容についてユーザーが明示的に承認した後にのみ実行されます。

CLI

このスキルには、標準ライブラリのみを使うヘルパーが付属しています。以下の各 Bash ブロックの先頭で、必ずこのリゾルバーを実行してください。Bash の呼び出しごとに新しいシェルが起動し、$SKILL_DIR はこのターンに最後に読み込まれたスキルを指すため、独自のスクリプトを基準にしてください。

WX="$SKILL_DIR/scripts/personal_wechat.py"; [ -f "$WX" ] || WX=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/personal_wechat.py' 2>/dev/null | head -1)
[ -f "$WX" ] || { echo "personal-wechat script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }

まず接続を確認する

ユーザーから WeChat の使用を依頼されたら、必ず最初にステータスを確認してください。

python3 $WX status

正常な場合の想定形式：

{"status":"ready","since":"…","wechat_running":true,"logged_in":true,"error":null}

接続状態を判断する唯一の情報源は /api/status です。status、wechat_running、logged_in の値だけを見て判断してください。それ以外は考慮しません。

症状	意味
status: "ready"、logged_in: true	正常です。続行してください。
status: "qr_scan"／logged_in: false	Wisdom のウェブ UI／VNC を開き、スマートフォンで WeChat の QR コードをスキャンするようユーザーに依頼してください。
status: "preparing"	復号済みの DB スナップショットをまだ作成中です。完了するまで待ってから再試行してください。完了するまでは読み取りに失敗することがあります。
status: "error"	error.code／error.message をユーザーに伝えてください。
HTTP 401	現在の Wisdom API トークンを使って Personal WeChat コネクターを再接続するよう、ユーザーに依頼してください。
接続拒否／タイムアウト	接続中の Wisdom インスタンスの URL とデプロイの状態を確認してください。

ネイティブ版 Linux では、書き込みモードが使えると判断する前に、ステータスから weixin_client.capabilities を確認してください。ready はログインとデータ準備の完了を示しますが、すべての旧式 Windows API が使えることを示すものではありません。特に、現在のネイティブ版デプロイでは moments.read が利用できますが、WeChat の新しいデバイスに関するセキュリティ制限が解消されていない間は、モーメンツの投稿／削除は HTTP 409 で拒否されます。

ほかのパスで 404 が返っても、「WeChat がオフライン」と判断しないでください。404 はその Wisdom バージョンに該当するルートが存在しないことを意味するだけで、アカウントがログアウトしていることを示すものではありません。

読み取りワークフロー

現在のアカウント

python3 $WX account

連絡先

python3 $WX contacts --limit 50
python3 $WX contacts --type group --limit 100
python3 $WX contacts --limit 100 --offset 100

--limit の上限は 1 ページあたり 200 件です（Wisdom の上限）。それより大きな件数を指定するのではなく、--offset を使ってページを分けてください。

会話

python3 $WX conversations --limit 20

各エントリーの id は、messages に conversation_id として渡す値です。これは復号済み WeChat データベースを直接読み取るため、全履歴を取得できます。「履歴」専用のエンドポイントはありません。

会話内のメッセージ

python3 $WX messages "CONVERSATION_ID" --limit 50 --order asc
python3 $WX messages "CONVERSATION_ID" --limit 50 --offset 50

出力には mentions、quoted_text、conversation_type が含まれるため、誰が @ メンションされたか、また引用返信が何に対する返信かを確認できます。

指定したタイムスタンプ以降の新着メッセージ

python3 $WX poll --since 1785000000 --limit 100

--since は秒単位の Unix タイムスタンプです。会話全体を読み直すのではなく、間が空いた後に追いつくために使ってください。

モーメンツ（朋友圈）

python3 $WX moments --limit 30
python3 $WX moments --limit 30 --self-only

これは同期されたビューキャッシュのため、削除したばかりの投稿が WeChat の再同期まで残ることがあります。

タスク

書き込みが停止しているように見える場合は、キューに登録済みまたは完了済みの UI タスクを確認してください。

python3 $WX tasks --limit 20
python3 $WX task TASK_ID

検索

python3 $WX search "Alice"

検索では WeChat の UI を操作するため、上記のローカル DB 読み取りより時間がかかります。送信前に対象が存在することを確認するために使ってください。

書き込み — すべて要承認

以下の書き込みコマンドは、デフォルトではドライランを実行し、送信予定の正確なペイロードを表示します。実際に実行されるのは、--confirm を指定した場合、または AceDataCloud のスケジュール済みタスクでこの Skill が事前承認されている場合に --unattended-confirm を指定した場合のみです。

ドライランをユーザーに表示し、対象と内容を正確に指定したうえで明示的な承認を得てから、--confirm を付けて再実行してください。最初の試行で --confirm を指定してはいけません。曖昧な文面から同意を推測してはいけません。

メッセージを送信する

python3 $WX send "Alice" "今晚 8 点开会吗？"
# -> {"dry_run": true, "action": "send", ...}
python3 $WX send "Alice" "今晚 8 点开会吗？" --confirm

グループ内で実際に @メンションする。 --mention を指定します（複数回指定可能）。Wisdom が WeChat 独自のメンションポップオーバーを操作し、本物の @通知を生成します。メッセージ本文に @Name と入力して通知されることを期待してはいけません。これは通知が誰にも届かない単なるテキストです。

python3 $WX send "项目群" "记得今天交周报" --mention "Doms Jay" --confirm
python3 $WX send "项目群" "记得今天交周报" --mention "Alice" --mention "Bob" --confirm
python3 $WX send "项目群" "全员通知" --mention-all --confirm     # owner/admin only

送信結果には mentions が含まれます。--mention を指定したにもかかわらず null が返された場合、メンションは登録されていません。@に成功したと主張せず、その旨をユーザーに伝えてください。

引用返信。 テキストが一致する、そのチャット内の最新メッセージに返信します。

python3 $WX send "Alice" "这个我来跟" --quote-text "这个 bug 谁跟一下" --confirm

--quote-text はメンションより優先され、一致するメッセージが見つからない場合は通常の送信にフォールバックします。

メディア。 Wisdom はコンテナ内で URL からファイルをダウンロードして送信します。

python3 $WX send "Alice" --type image --image-url https://example.com/a.png --confirm
python3 $WX send "Alice" --type video --video-url https://example.com/a.mp4 --confirm
python3 $WX send "Alice" --type file  --file-url  https://example.com/a.pdf --confirm

再試行。 結果を確認できなかった送信も、すでに配信されている可能性があります。再試行する場合は、同じ --idempotency-key を指定して、二重送信の代わりに元のタスクを Wisdom から返すようにしてください。

python3 $WX send "Alice" "hi" --idempotency-key daily-2026-08-04 --confirm

Web ページを共有する

share は WeChat のブラウザーで公開 HTTP(S) ページを開き、ネイティブのリンクカードを 1 人以上の連絡先またはグループに送信します。--text を指定すると、カードにメッセージが追加されます。まず status で ready と logged_in: true を確認し、次に URL、テキスト、対象を正確に指定してドライランを実行してから承認を求めてください。

python3 $WX share "https://example.com/article" "Alice" "项目群" --text "供参考"
python3 $WX share "https://example.com/article" "Alice" "项目群" --text "供参考" --key article-20261004 --confirm

このコマンドは POST /api/share のみを呼び出し、タスクの結果を待ちます。各対象の succeeded、failed、not_attempted の結果と shared_url を確認してください。タスクの成功だけでは、受信者がカードを受け取った、または読んだことの証明にはなりません。WeChat のブラウザーでページがリダイレクトされた後、実際の URL が変わる場合があります。共有すると、まずアカウント自身の「ファイル転送アシスタント」に URL メッセージが送信されます。同じ Wisdom プロセスでタスクが保持されている間の重複排除に限り --key を使用してください。結果が不明な場合や再起動後は、重複送信を避けるため、再送信前にタスクとチャットの履歴を確認してください。

モーメンツ（朋友圈）

まず、ステータスで利用可能な機能を確認してください。moments.write または moments.delete がない場合は、制限があることを伝え、公開または削除できたと主張してはいけません。現在のネイティブ Linux デプロイでは、これらの書き込みに対して HTTP 409 が返されます。

python3 $WX moment-post "今天上线了新功能"
python3 $WX moment-post "看看这张图" --image-url https://example.com/a.png --visibility public --confirm

--visibility は public / private / partial / exclude（公開 / 非公開 / 一部に公開 / 特定の人に非公開）で、デフォルトは public です。

削除は取り消せません。match には、ユーザー自身のモーメンツ投稿のうち、特定しやすいものの一部を指定する必要があります。Wisdom は推測せず、曖昧な一致を拒否します。

python3 $WX moment-delete "Veo Videos Generation API"
python3 $WX moment-delete "Veo Videos Generation API" --confirm

グループチャット

他の人にも表示されるため、メンバーの正確な一覧を必ず先に確認してください。

python3 $WX group-create "Alice" "Bob" --name "项目群" --confirm   # needs >= 2 members
python3 $WX group-invite "项目群" "Carol" --confirm
python3 $WX group-remove "项目群" "Carol" --confirm                # kicks; visible to the group
python3 $WX group-rename "项目群" "项目群 2026" --confirm           # renames for everyone

スケジュール済みタスクでの無人承認

AceDataCloud のスケジュール済みタスク内で実行する場合、プラットフォームが特定の Skill を無人実行用に事前承認していることがあります。以下の条件をすべて満たす場合：

• AICHAT_UNATTENDED_MODE=true
• AICHAT_ACTIVE_SKILL が personal-wechat または acedatacloud/personal-wechat
• AICHAT_ACTIVE_SKILL が AICHAT_UNATTENDED_ALLOWED_SKILLS に含まれている

このスケジュール済みタスクでは、ユーザーがこの Skill を事前承認しています。その場合は、--confirm の代わりに --unattended-confirm を使用してください。

python3 $WX send "Alice" "今晚 8 点开会吗？" --unattended-confirm

ヘルパーが unattended_confirmation_denied を返した場合、--confirm を付けて再試行してはいけません。ドライランの結果を報告し、無人承認設定でこのタスクにこの Skill を選択する必要があることを説明してください。

安全ルール

• PERSONALWECHAT_API_TOKEN を絶対に表示しないでください。
• PERSONALWECHAT_BASE_URL + API_TOKEN は、ユーザーの WeChat を完全にリモート制御できるものとして扱ってください。
• 書き込み操作はすべて、まずドライランを実行して明示的な承認を求め、その後 --confirm を付けて再実行してください。
• この Skill が事前承認済みであることをプラットフォームの環境変数が示している場合に限り、--unattended-confirm を使用してください。
• グループとモーメントへの書き込みは他の人にも表示されます。moment-delete は取り消せません。
• 実際に起きたことを報告してください。mentions が null で返された場合、@ は登録されていません。
• ユーザーがサービスの修復を明示的に依頼しない限り、再起動／ログアウトのエンドポイントを呼び出さないでください。
• 接続状態の判断には python3 $WX status のみを使用してください。別のパスでの 404 は、そのルートが存在しないことを意味し、WeChat がオフラインであることを意味するものではありません。

エンドポイントの対応関係

このヘルパーは次の Wisdom エンドポイントをラップします。

コマンド	エンドポイント
status	GET /api/status
account	GET /api/account
contacts	GET /api/contacts
conversations	GET /api/conversations
messages	GET /api/messages
poll	GET /api/messages/poll
moments	GET /api/moments
tasks / task	GET /api/tasks、GET /api/tasks/{id}
search	POST /api/search
send	POST /api/messages/send
share	POST /api/share
moment-post / moment-delete	POST /api/moments、DELETE /api/moments
group-create / -invite / -remove / -rename	POST /api/groups、/invite、/remove、/rename

search 以降はすべて、キューに登録される UI タスクです（202 + タスク ID）。書き込み操作にはさらに、--confirm または検証済みの --unattended-confirm が必要です。