WeCom

WeCom

WeCom is one of the clearer China-facing donor candidates because PicoClaw already implements the official AI Bot WebSocket protocol directly. The porter question is not whether the transport edge exists; it is how much of that edge is reusable once PicoClaw’s QR bootstrap and gateway glue are stripped away.

Status

docs/content/building-gormes/architecture_plan/subsystem-inventory.md now groups WeCom into the Phase 2.B.10 regional/device adapter tranche. Gormes has a contract-tested shared-bot seam in internal/channels/wecom for policy-gated ingress and reply-path behavior, but the real WeCom WebSocket transport/bootstrap binding remains planned.

Evidence level:

• Donor code for this dossier was verified against the external sibling repo at <picoclaw donor repo>.
• The donor commit inspected for this research was 6421f146a99df1bebcd4b1ca8de2a289dfca3622.
• The upstream donor repo is https://github.com/sipeed/picoclaw.
• Any pkg/... or docs/... path listed below is relative to that donor root, not relative to the Gormes repo.
• Current Gormes status and target behavior were verified in-tree against internal/channels/wecom/bot.go, internal/channels/wecom/bot_test.go, docs/content/building-gormes/architecture_plan/subsystem-inventory.md, and docs/content/upstream-hermes/user-guide/messaging/wecom.md.

Keep the boundary explicit: PicoClaw is donor input for WeCom channel-edge mechanics only. Gormes architecture, session ownership, and gateway/kernel boundaries remain authoritative.

Why This Adapter Is Reusable

The reusable part is mostly the transport protocol handling, not the onboarding surface.

• pkg/channels/wecom/wecom.go owns the actual AI Bot WebSocket lifecycle: subscribe, heartbeat, read loop, request/response correlation, turn tracking, and fallback from reply-mode streams to active push.
• pkg/channels/wecom/protocol.go is valuable because it captures the protocol frame shapes and message-body variants in one place.
• pkg/channels/wecom/media.go contains platform-specific media constraints, upload chunking, AES-CBC inbound decryption, and message-type mapping that a porter would otherwise need to rediscover from scattered docs.
• pkg/channels/wecom/reqid_store.go shows how PicoClaw preserves reply routing across time, but its persistence path and state ownership are PicoClaw-specific.

The bootstrap pieces are donor ideas, not donor code:

• cmd/picoclaw/internal/auth/wecom.go is CLI QR onboarding glue.
• web/backend/api/wecom.go is web-admin QR onboarding glue.

That split matters. WeCom is mostly donor code at the transport layer, but mostly donor ideas at the auth/bootstrap layer.

Picoclaw Donor Files

• Provenance note: the following pkg/... and docs/... paths are relative to the external donor root <picoclaw donor repo> at commit 6421f146a99df1bebcd4b1ca8de2a289dfca3622, not relative to the Gormes repo.
• picoclaw/pkg/channels/wecom/wecom.go
• picoclaw/pkg/channels/wecom/protocol.go
• picoclaw/pkg/channels/wecom/media.go
• picoclaw/pkg/channels/wecom/reqid_store.go
• picoclaw/pkg/channels/wecom/wecom_test.go
• picoclaw/cmd/picoclaw/internal/auth/wecom.go
• picoclaw/web/backend/api/wecom.go
• picoclaw/docs/channels/wecom/README.md
• docs/content/upstream-hermes/user-guide/messaging/wecom.md
• docs/content/building-gormes/architecture_plan/subsystem-inventory.md

What To Copy vs What To Rebuild

Copy candidates:

• The WebSocket connection lifecycle from Start, connectLoop, runConnection, heartbeatLoop, and readLoop.
• Envelope and command structs from protocol.go; they document the real wire contract.
• Reply-mode turn handling from dispatchIncoming, queueTurn, BeginStream, sendStreamChunk, and sendActivePush.
• Media upload/download behavior from media.go, especially size caps, 512 KB chunk upload flow, and the distinction between native image/file/voice/video sends.
• Behavioral tests in wecom_test.go, especially req-id route storage, stream update/finalize flow, and fallback from stream reply to active push.

Rebuild in Gormes-native form:

• Request-route persistence. reqid_store.go writes under ~/.picoclaw; Gormes needs its own state location and likely an adapter-owned cache abstraction rather than a donor file-path convention.
• QR login and credential save flow. Both auth/wecom.go and web/backend/api/wecom.go are PicoClaw control-plane glue, not transport logic.
• Inbound publication into the runtime. Replace PicoClaw’s bus calls and metadata layout with Gormes kernel submission and Gormes session identity rules.
• Operator-facing config semantics. Follow the upstream Hermes WeCom behavior doc for policy and configuration shape, not PicoClaw’s exact settings object.

Gormes Mapping

• wecom.go should inform the future internal/channels/wecom runtime split between transport session management and Gormes-facing event submission.
• dispatchIncoming is the donor for parsing inbound WeCom message types, extracting media, and deciding when a turn is stream-capable.
• BeginStream plus wecomStreamer maps well to Gormes’ adapter-local streaming reply contract. The important idea is that WeCom streaming is tied to an active inbound turn, not to arbitrary outbound messages.
• sendActivePush and sendActiveMedia are the donor path for expired-turn fallback and proactive outbound delivery.
• The Hermes doc should remain authoritative for DM/group policy and allowlist semantics; PicoClaw only proves the transport implementation details.

Implementation Notes

• Preserve the hard split between reply-mode streaming and proactive push. That is the center of the WeCom transport.
• Port protocol.go structurally first. It is easier to reason about the rest of the adapter once the command and payload types are fixed.
• Carry over duplicate suppression and turn expiry behavior; the donor already treats replayed messages and stale streams as real operational cases.
• Keep media upload logic close to the adapter. WeCom’s media limits and upload protocol are too channel-specific to push into a generic shared helper.
• Treat QR flows as separate setup work. They should not leak into the transport package.

Risks / Mismatches

• PicoClaw persists req-id routes in a local JSON file under a donor-specific home directory. Copying that literally would violate Gormes ownership boundaries.
• The donor assumes PicoClaw’s message bus and media-store interfaces. The protocol logic is portable, the surrounding call graph is not.
• Upstream Hermes docs describe richer access-policy behavior than the PicoClaw donor package exposes directly. Product behavior should still come from Gormes docs.
• QR bootstrap code is fragile to vendor changes and should be revalidated when implementation begins; it is not the stable part of the donor.

Port Order Recommendation

1. Port the protocol structs and WebSocket lifecycle first.
2. Port inbound dispatch, req-id/turn tracking, and stream reply handling next.
3. Port media upload/download and native media sends after text reply flow is stable.
4. Rebuild QR onboarding separately as setup/control-plane work.
5. Only then widen policy/config surfaces to match the final Gormes operator UX.

Code References

• picoclaw/pkg/channels/wecom/wecom.go: Start, BeginStream, Send, SendMedia, connectLoop, runConnection, dispatchIncoming, sendStreamChunk, sendActivePush, sendActiveMedia.
• picoclaw/pkg/channels/wecom/protocol.go
• picoclaw/pkg/channels/wecom/media.go: storeRemoteMedia, resolveOutboundPart, uploadOutboundMedia, resolveMediaRoute.
• picoclaw/pkg/channels/wecom/reqid_store.go
• picoclaw/pkg/channels/wecom/wecom_test.go
• picoclaw/cmd/picoclaw/internal/auth/wecom.go
• picoclaw/web/backend/api/wecom.go
• picoclaw/docs/channels/wecom/README.md
• docs/content/upstream-hermes/user-guide/messaging/wecom.md

Recommendation: copy candidate.