[Feature] Add Lark/Feishu as a chat channel (willing to contribute)

[facto-dev-ops]

Hi @coleam00,

Thanks for the great work on Archon — the Channels architecture (Discord/Telegram) is exactly the kind of remote workflow I've been wanting for my AI coding setup.

I'd like to propose adding Lark (Feishu / 飞书) as a supported channel, and I'm willing to contribute the implementation if you're open to merging it.

Why Lark matters for Archon:

• It's the dominant team collaboration platform in China and across APAC (similar role to Slack in the West), used heavily by tech, AI, and Web3 teams.
• Many developers in this region would use Archon's remote dispatch / mobile workflow features daily if the chat surface were Lark instead of Discord/Telegram.
• It's a clean fit with the existing channel abstraction — same conceptual model (bot receives messages, dispatches to Archon, streams back results).

Implementation plan I have in mind:

• Use the official @larksuiteoapi/node-sdk (well-maintained, covers messaging, interactive cards, file upload).
• Support both WebSocket long-connection mode (no public endpoint required — works for self-hosted users behind NAT) and webhook mode (for production deployments).
• Mirror the existing Discord/Telegram channel API surface so the integration is symmetric and easy to maintain.
• Support interactive cards for streaming responses and confirmation buttons (which Lark handles natively and looks great for AI agent UX).

Questions before I start:

1. Are you open in principle to a Lark channel PR?
2. Any architectural conventions I should follow when adding a new channel (file layout, config schema, testing approach)?
3. Any preference on SDK choice or whether to keep it dependency-light?

Happy to open a draft PR or write a more detailed design doc first — whichever workflow you prefer.

Thanks!

[realDuang]

Not a maintainer, but having shipped a Feishu/Lark channel for an AI coding agent recently, here's a checklist of the things that bit us. Everything below has a Lark Open Platform doc link so it can be sanity-checked before the PR opens.

1. Token lifecycle

tenant_access_token TTL is 2 hours. Important detail that catches first-time integrators: calling the issue endpoint when remaining TTL > 30 minutes returns the same token; calling when remaining < 30 minutes returns a new token while the old one stays valid until it expires. Two simultaneous valid tokens is normal, not a bug. Source: Tenant access token — custom app.

2. Long-connection vs webhook

Long-connection mode (the right default for self-hosted Archon installs behind NAT) authenticates only at connect time — every event after that is plaintext, no signature check, no AES decrypt. Don't run the webhook decryption pipeline on long-connection payloads, you'll corrupt them. Webhook mode is the one that needs signature/encryption handling. Source: Subscribe to events — long-connection mode.

3. Webhook signature — the body trap

Header is X-Lark-Signature. Algorithm is sha256(timestamp + nonce + encrypt_key + body), hex-encoded. The single line that bites: body must be the raw request body, not the deserialized-and-reserialized JSON — re-serialization changes whitespace and the signature breaks. Header timestamp is X-Lark-Request-Timestamp, nonce is X-Lark-Request-Nonce. Source (with Python/Java/Go/Node.js sample code): Webhook signature — sample code.

4. AES decryption (only when Encrypt Key is configured)

AES-256-CBC. Key = SHA-256(encrypt_key) (32 bytes). IV = first 16 bytes of the base64-decoded ciphertext, payload = the rest. Important: the official Java sample uses AES/CBC/NOPADDING and manually strips trailing bytes ≤ 16. Python sample does similar manual unpad. So if you wire up a strict PKCS7 unpad expecting it to work, sometimes it does and sometimes it throws on the last block — match the official samples. Source (full code in 6 languages): Event payload decryption.

5. Card update — actual rate limits and hard caps

For PATCH /open-apis/im/v1/messages/:message_id (the card update endpoint):

• Per-card-message rate limit: 5 QPS (i.e. ≥ 200ms between updates of the same card)
• Endpoint-wide: 50 req/sec, 1000 req/min
• Card body cap: 30 KB (note: style tags inflate the actual size beyond what you typed)
• Update window: only messages sent within the last 14 days can be updated
• Both the original card and the updated card must declare config.update_multi: true (shared card semantics) — otherwise the update silently no-ops on every recipient except the sender. This is the Model stucked at response stream text #1 footgun.

Source: Patch sent message card — limits & rate caps.

6. For streaming AI responses, use the native streaming mode, not manual throttling

Card JSON 2.0 has first-class streaming: set config.streaming_mode: true and use streaming_config to control behavior. The card UI handles the typewriter effect, append semantics, and the "generating…" summary placeholder for you. This is materially better than calling patch in a loop and fighting the 5 QPS limit. Source: Card JSON 2.0 — config.streaming_mode.

Two related caps for JSON 2.0 cards: max 200 elements/components per card, and JSON 2.0 cards must be shared (update_multi: true is the only allowed value).

7. Interactive callbacks (buttons, inputs)

Subscribe to the new event card.action.trigger (the old one is card.action.trigger_v1 — use the new schema unless you need bw-compat). Handler must reply HTTP 200 within 3 seconds, or the user gets a "request error" toast. Response body can carry both an updated card and a toast (info/success/error/warning) for inline feedback — the toast story is nicer than what you get on Telegram/Discord. The interactive callback validity window for a sent card is 30 days (separate from the 14-day update window). Source: Handle card callbacks.

8. Image upload for multimodal coding flows

POST /open-apis/im/v1/images, multipart/form-data, required field image_type = "message" (sending in a message) or "avatar" (setting profile picture). Returns image_key, then reference that in card elements. Limits: ≤ 10 MB; non-GIF ≤ 12000×12000; GIF ≤ 2000×2000; supported formats JPG/JPEG/PNG/WEBP/GIF/BMP/ICO/TIFF/HEIC (TIFF/HEIC are converted to JPG server-side). Forgetting image_type is the most common 400. Source: Upload image.

9. User ID resolution

POST /open-apis/contact/v3/users/batch_get_id — but it only resolves from mobile or email to user IDs (open_id / union_id / user_id). It does NOT resolve from display name or @-mention text. For 1:1 bot DMs the bot only gets open_id from the receive event; for @-mentions in groups, the mention payload already contains open_id so you usually don't need to call this endpoint at all. Up to 50 emails + 50 mobiles per call; corporate emails (@yourcompany-style internal) are not supported. Source: Look up user ID by mobile or email.

---

If a working reference for the above is useful while scoping the PR, codemux (repo) ships a Feishu channel end-to-end. The adapter is at electron/main/channels/feishu and the cross-channel streaming logic (which uses Feishu's native streaming_mode for cards) is at electron/main/channels/streaming. Patterns there are MIT-licensed and don't require taking a dependency.

Good luck with the contribution — Archon's existing channel abstraction should land this cleanly.