Summary

Add a new wechat gateway platform for Hermes Agent, backed by the local wechat-bridge --shape hermes interface from leeguooooo/wechat-skill.

This is not the same as the existing weixin adapter in Hermes. The current weixin adapter targets Tencent iLink / bot-style integration, while this request is for a local personal WeChat account bridge running on the same machine.

Motivation

A working local bridge now exists and already exposes a Hermes-compatible shape. This makes it possible to add WeChat as another first-class Hermes messaging channel, alongside WhatsApp / Feishu / Signal, without Hermes having to understand WeChat internals.

The key point is: Hermes would not integrate against WeChat protocol details directly. It would integrate against a stable local bridge contract, exactly like Hermes already does with its WhatsApp bridge.

Why this should be a separate wechat platform

Hermes already has Platform.WEIXIN and a gateway/platforms/weixin.py, but that path is for Tencent iLink bot / official-style integration. It is not the same thing as a local desktop WeChat bridge for a personal account.

So this request is specifically:

• add Platform.WECHAT
• add gateway/platforms/wechat.py
• wire it into the gateway the same way other platforms are wired

Current upstream state

The upstream bridge author has already added a Hermes-compatible shape in wechat-skill:

• release: v1.10.2
• startup: wechat-bridge --shape hermes
• stability promise: v1.10.x bridge paths / methods / field names / enum values will not break

The bridge author explicitly recommends that Hermes integrate against the bridge directly, instead of using CLI-subprocess mode.

Public bridge contract (already implemented upstream)

Start

wechat-bridge --shape hermes
# default: 127.0.0.1:18400

Transport

• local HTTP/1.1
• SSE for inbound stream
• optional Bearer auth if exposed beyond loopback

Endpoints

• GET /health
• GET /messages/stream?since=TS
• POST /send body { "wxid": "...", "text": "..." }
• GET /chat/:wxid
• GET /chat/:wxid/history?limit=N&since=TS&until=TS
• GET /chats?limit=N&types=private,group
• GET /unread
• GET /contacts?query=X&limit=N
• GET /resolve?hint=X&limit=N

/send response shape

{
  "status": "delivered" | "submitted_unconfirmed" | "status_unknown" | "failed",
  "wxid": "...",
  "recipient_display_name": "...",
  "delivered_verified": true | false | null,
  "verify_tables_scanned": 10,
  "verify_rows_scanned": 3,
  "reused_session": false,
  "diagnostic": { ... }
}

Error shape

{ "error": "short_code", "message": "human string" }

With status codes such as 400, 401, 402, 404, 413, 503.

Hermes-shaped inbound event fields

The upstream --shape hermes stream already exposes fields aligned to Hermes WhatsApp-style expectations, including:

• messageId
• chatId
• senderId
• senderName
• chatName
• isGroup
• body
• hasMedia
• mediaType
• mediaUrls
• mentionedIds
• quotedParticipant
• botIds
• timestamp

Local validation (already tested)

This is not speculative. The bridge has already been validated locally on the target machine:

• wechat-bridge --shape hermes --port 18400 starts successfully
• GET /health returns Hermes-shaped bridge status
• GET /chat/filehelper works
• GET /chat/filehelper/history?limit=2 works and returns Hermes-shaped history rows
• POST /send to filehelper succeeds and history later contains the sent message
• POST /typing returns 501 not_supported as designed

So the missing piece is now on the Hermes side: adding an adapter and platform wiring.

Proposed Hermes implementation (minimum viable scope)

Add a new wechat gateway adapter that integrates against wechat-bridge --shape hermes:

1. gateway/config.py

   • add Platform.WECHAT
   • add env/config parsing for bridge host/port/bearer/home channel

2. gateway/platforms/wechat.py

   • connect to wechat-bridge over local HTTP
   • use /messages/stream (SSE) for inbound delivery
   • use /send for text replies
   • use /chat/:wxid for chat info
   • optional /chat/:wxid/history for future context helpers
   • treat 501 not_supported on typing / reply features as graceful no-op or downgrade

3. gateway/run.py

   • add adapter factory branch for Platform.WECHAT
   • add authorization env mappings (WECHAT_ALLOWED_USERS, WECHAT_ALLOW_ALL_USERS, etc.)

4. toolsets.py, send_message_tool.py, channel_directory.py, setup/status surfaces

   • register a hermes-wechat toolset
   • allow message delivery to WeChat home channel
   • include session/channel discovery if appropriate

Feature boundaries / known limitations

The upstream bridge explicitly does not fake unsupported behaviors:

• POST /typing -> 501 not_supported
• replyTo on send -> 501 reply_not_supported

So a Hermes adapter should degrade cleanly:

• typing indicator can be a no-op
• replies can fall back to plain send or quoted text formatting

Why now

This is a good moment to do it because the upstream bridge author has:

• already added a Hermes alignment layer (--shape hermes)
• promised no breaking changes within v1.10.x
• explicitly invited feedback if field names / error codes need further alignment

That makes the integration risk much lower than designing a fresh protocol.

Ask

Please consider opening support for Platform.WECHAT in Hermes gateway.

If maintainers are open to it, the upstream wechat-skill author may also be willing to help align field names further (or possibly contribute the adapter wiring), since the bridge side is already implemented and tested.

I can provide additional local validation details if needed, but the main point is: the local bridge is already real, stable, and Hermes-shaped; Hermes now needs the adapter.