feat: implement channel runtime connectors
This commit is contained in:
@ -13,19 +13,19 @@ ChannelConnector
|
||||
-> install / auth / QR / OAuth / credential validation / login state
|
||||
-> ChannelConnectionStore
|
||||
-> ChannelRuntime
|
||||
-> ChannelAdapter
|
||||
-> ChannelAdapter or ExternalConnectorChannel
|
||||
-> MessageBus
|
||||
-> AgentService
|
||||
```
|
||||
|
||||
The existing `ChannelRuntime`, `MessageBus`, `ChannelManager`, and `ChannelAdapter` contracts remain the message routing core. The new connector layer owns user-visible setup and connection lifecycle.
|
||||
The existing `ChannelRuntime`, `MessageBus`, `ChannelManager`, and `ChannelAdapter` contracts remain the message routing core. The new connector layer owns user-visible setup and connection lifecycle. For platforms backed by predeclared sidecar services, Beaver should expose the sidecar to the runtime as an `ExternalConnectorChannel` rather than a Beaver-owned platform protocol adapter.
|
||||
|
||||
## Why This Is Required
|
||||
|
||||
The current channel design assumes a channel is already configured before the backend starts. That is enough for local development and simple webhook/token channels, but it does not match real platform onboarding:
|
||||
|
||||
- Feishu/Lark now has a Channel SDK pattern that packages bot channel setup, WebSocket or webhook transport, event handling, and replies around an installed app identity.
|
||||
- Weixin/OpenClaw-style setup uses a local plugin installer plus QR login and persistent login state.
|
||||
- Weixin personal-account setup uses a docker-compose predeclared sidecar connector plus QR login and persistent login state.
|
||||
- Terminal devices need pairing or device registration; a raw `peer_id` connect frame is not enough for a real deployment.
|
||||
- Even simple token platforms such as Telegram need a UI flow for token entry, validation, status, revoke, and restart.
|
||||
|
||||
@ -44,11 +44,13 @@ So Beaver needs a connection lifecycle layer. Adapters should not be responsible
|
||||
|
||||
`ChannelConnection` is the user-visible connection instance. Examples: "Weixin personal account", "Lark workspace bot", "Telegram main bot", "Desk terminal".
|
||||
|
||||
`ChannelConnector` is the setup and lifecycle controller for one platform family. It starts pairing sessions, validates credentials, launches connector processes, handles reconnects, and emits runtime channel config.
|
||||
`ChannelConnector` is the setup and lifecycle controller for one platform family. It starts pairing sessions, validates credentials, checks preconfigured connector endpoints when needed, handles reconnects, and emits runtime channel config.
|
||||
|
||||
`ChannelAdapter` is the message transport adapter used by `ChannelRuntime`. It receives normalized inbound messages and sends outbound replies. It does not own onboarding.
|
||||
|
||||
`ExternalConnectorProcess` is an optional local process for platforms whose SDK or login behavior is better isolated outside the Python backend. It talks to Beaver through a narrow control and message protocol.
|
||||
`ExternalConnectorChannel` is the runtime channel object used when a platform protocol lives outside the Python backend. It implements the same `start()`, `stop()`, and `send()` contract as an adapter, but its `send()` method calls an external connector HTTP API and inbound messages enter Beaver through a connector bridge endpoint.
|
||||
|
||||
`ExternalConnectorProcess` is an optional preconfigured service for platforms whose SDK or login behavior is better isolated outside the Python backend. For Weixin, this process is a docker-compose predeclared sidecar service. Beaver must not dynamically create containers or require Docker socket access.
|
||||
|
||||
## Data Model
|
||||
|
||||
@ -171,7 +173,7 @@ Some channels should run through an external process:
|
||||
ExternalConnectorProcess
|
||||
-> Beaver connector control API
|
||||
-> local Unix/TCP/WebSocket bridge
|
||||
-> ChannelRuntime external adapter
|
||||
-> ChannelRuntime ExternalConnectorChannel
|
||||
```
|
||||
|
||||
The external process must not receive permanent backend admin credentials through QR codes or copied commands. It should receive a short-lived pairing token with a narrow scope:
|
||||
@ -183,7 +185,7 @@ expires_in: 10 minutes
|
||||
one_time: true
|
||||
```
|
||||
|
||||
After pairing, Beaver stores the resulting connection credentials and gives the connector a renewable connection token scoped to that connection only.
|
||||
After pairing, Beaver stores the resulting connection credentials and gives the connector a renewable connection token scoped to that connection only. For docker-compose sidecars, that token is passed through the connector HTTP API or service configuration agreed for that sidecar; Beaver does not create or restart the sidecar container.
|
||||
|
||||
## Per-Channel Assessment
|
||||
|
||||
@ -211,23 +213,41 @@ The connector should expose both "manual app credential setup" and future "insta
|
||||
|
||||
### Weixin
|
||||
|
||||
Weixin should use an external connector process.
|
||||
Weixin should use a docker-compose predeclared sidecar connector.
|
||||
|
||||
Recommended first implementation:
|
||||
|
||||
- connector kind: `weixin`
|
||||
- setup mode: local plugin command plus QR login.
|
||||
- external process: required.
|
||||
- runtime adapter: external bridge adapter that receives normalized events from the connector.
|
||||
- setup mode: Beaver calls the sidecar HTTP API to start QR login and poll pairing state.
|
||||
- external process: required, predeclared in docker-compose, and never dynamically created by Beaver.
|
||||
- runtime channel: `ExternalConnectorChannel`.
|
||||
|
||||
Required setup checks:
|
||||
|
||||
- local connector installed.
|
||||
- sidecar base URL is configured.
|
||||
- sidecar health endpoint responds.
|
||||
- connector version is compatible with Beaver.
|
||||
- QR session is pending, scanned, confirmed, expired, or failed.
|
||||
- login state is stored behind `credentials_ref`.
|
||||
- connector heartbeat is visible.
|
||||
|
||||
The sidecar owns Weixin protocol handling, QR login, inbound receive, outbound send, and login-state persistence. Beaver owns connector setup state, bridge API validation, message normalization boundaries, runtime dedupe, and outbound HTTP calls to the sidecar `/send` API.
|
||||
|
||||
The agreed runtime flow is:
|
||||
|
||||
```text
|
||||
Weixin sidecar connector
|
||||
-> Beaver connector bridge endpoint
|
||||
-> ChannelRuntime.accept_inbound()
|
||||
-> MessageBus
|
||||
-> AgentService
|
||||
|
||||
AgentService
|
||||
-> MessageBus outbound
|
||||
-> ExternalConnectorChannel.send()
|
||||
-> Weixin sidecar connector /send
|
||||
```
|
||||
|
||||
Group delivery remains best-effort. The connector must surface group capability separately from direct message capability.
|
||||
|
||||
### Telegram
|
||||
|
||||
@ -0,0 +1,307 @@
|
||||
# Chat Platform Channel Adapters Design
|
||||
|
||||
Date: 2026-06-02
|
||||
|
||||
## Goal
|
||||
|
||||
Add first-class Beaver channel adapters for four messaging platforms:
|
||||
|
||||
- `FeishuAdapter`
|
||||
- `QQBotAdapter`
|
||||
- `TelegramAdapter`
|
||||
- `ExternalConnectorChannel` for Weixin personal-account sidecars
|
||||
|
||||
Each runtime channel must plug into the existing `ChannelRuntime`, normalize inbound platform messages into `InboundMessage` with `ChannelIdentity`, and deliver `OutboundMessage` replies back to the original platform conversation. Feishu, QQBot, and Telegram use Beaver-owned protocol adapters. Weixin personal-account support uses a docker-compose predeclared sidecar connector, so Beaver exposes it as an `ExternalConnectorChannel` rather than a Beaver-owned `WeixinAdapter`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Use internal adapters by default, but allow external connector processes where platform SDK or login state requires them.
|
||||
- Do not implement WhatsApp in this phase.
|
||||
- Do not replace `ChannelRuntime`, `MessageBus`, or `ChannelManager`.
|
||||
- Do not move platform access policy into `AgentService`.
|
||||
- Do not implement streaming token deltas for these channels in this phase.
|
||||
- Do not promise stable Weixin group support; Weixin group delivery is best-effort only.
|
||||
|
||||
## Architecture
|
||||
|
||||
Keep Beaver's channel runtime as the owner of lifecycle, dedupe, event logging, and agent dispatch.
|
||||
|
||||
```text
|
||||
platform SDK/API or sidecar connector
|
||||
-> {Channel}Adapter or ExternalConnectorChannel bridge endpoint
|
||||
-> ChannelRuntime.accept_inbound()
|
||||
-> MessageBus.inbound
|
||||
-> ChannelRuntime bridge
|
||||
-> AgentService.handle_inbound_message()
|
||||
-> MessageBus.outbound
|
||||
-> ChannelManager.dispatch_outbound()
|
||||
-> {Channel}Adapter.send() or ExternalConnectorChannel.send()
|
||||
-> platform SDK/API or sidecar connector API
|
||||
```
|
||||
|
||||
Adapters own platform-specific transport and delivery details when Beaver directly integrates a platform API. For Weixin, the sidecar owns the platform protocol, QR login, receive loop, send behavior, and login-state persistence. The runtime owns Beaver session identity, dedupe, event logging, and run dispatch in both cases.
|
||||
|
||||
## Shared Adapter Contract
|
||||
|
||||
Each runtime channel implements the existing `ChannelAdapter` protocol:
|
||||
|
||||
```python
|
||||
channel_id: str
|
||||
kind: str
|
||||
mode: str
|
||||
|
||||
async def start() -> None
|
||||
async def stop() -> None
|
||||
async def send(message: OutboundMessage) -> None
|
||||
```
|
||||
|
||||
Each Beaver-owned adapter receives a `ChannelInboundSink` and calls `accept_inbound()` for every normalized user message. `ExternalConnectorChannel` receives inbound Weixin messages through Beaver's connector bridge endpoint, then submits normalized messages to `ChannelRuntime.accept_inbound()`.
|
||||
|
||||
For all four adapters:
|
||||
|
||||
- `kind` is one of `feishu`, `qqbot`, `telegram`, `weixin`.
|
||||
- `account_id` comes from channel config.
|
||||
- inbound messages must include `ChannelIdentity`.
|
||||
- outbound replies route by `message.channel_identity` when present, falling back to `message.session_id`.
|
||||
- unsupported media is represented as text metadata in phase one rather than dropped silently.
|
||||
|
||||
## Channel Configuration
|
||||
|
||||
All channels use the existing `BeaverConfig.channels` map.
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram-main": {
|
||||
"enabled": true,
|
||||
"kind": "telegram",
|
||||
"mode": "polling",
|
||||
"accountId": "bot-main",
|
||||
"displayName": "Telegram Main",
|
||||
"secrets": {
|
||||
"botToken": "..."
|
||||
},
|
||||
"config": {
|
||||
"requireMentionInGroups": true,
|
||||
"maxMessageChars": 4096
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Config keys stay channel-specific inside `config` and `secrets`. The factory chooses the adapter by `kind` and `mode`.
|
||||
|
||||
For sidecar-backed channels, config also includes the connector base URL and bridge settings. Beaver must call the already-running connector HTTP API and must not dynamically create containers or require Docker socket access.
|
||||
|
||||
## Identity Mapping
|
||||
|
||||
All adapters map platform identity into `ChannelIdentity`:
|
||||
|
||||
- `channel_id`: configured Beaver channel id, such as `telegram-main`
|
||||
- `kind`: platform kind
|
||||
- `account_id`: configured account id
|
||||
- `peer_id`: platform chat, group, openid, or user conversation id
|
||||
- `thread_id`: platform topic/thread id when applicable
|
||||
- `peer_type`: `dm`, `group`, `channel`, or platform-specific value
|
||||
- `user_id`: platform sender id when available
|
||||
- `message_id`: platform message id or event id
|
||||
|
||||
The runtime continues to derive sessions as:
|
||||
|
||||
```text
|
||||
<channel_id>:<account_id>:<peer_id>[:<thread_id>]
|
||||
```
|
||||
|
||||
Group sessions can later become per-user or per-thread by adding adapter-level `thread_id` rules without changing `ChannelRuntime`.
|
||||
|
||||
## Adapter Scope
|
||||
|
||||
### FeishuAdapter
|
||||
|
||||
Supports:
|
||||
|
||||
- WebSocket long connection as the preferred mode.
|
||||
- Optional webhook mode if configured.
|
||||
- Direct messages.
|
||||
- Group messages gated by mention or config.
|
||||
- Text outbound replies.
|
||||
- Basic inbound media metadata and cached local file paths when available.
|
||||
|
||||
Configuration:
|
||||
|
||||
- `secrets.appId`
|
||||
- `secrets.appSecret`
|
||||
- `config.domain`: `feishu` or `lark`
|
||||
- `config.connectionMode`: `websocket` or `webhook`
|
||||
- `config.requireMentionInGroups`
|
||||
- `config.allowFrom`
|
||||
- `config.groupAllowFrom`
|
||||
|
||||
### QQBotAdapter
|
||||
|
||||
Supports:
|
||||
|
||||
- Official QQ Bot WebSocket gateway for inbound events.
|
||||
- Official REST API for outbound text replies.
|
||||
- Private C2C messages.
|
||||
- Group messages.
|
||||
- Guild/channel messages when the platform event provides them.
|
||||
- Basic rich media intake as cached local files or text metadata.
|
||||
|
||||
Configuration:
|
||||
|
||||
- `secrets.appId`
|
||||
- `secrets.clientSecret`
|
||||
- `config.markdownSupport`
|
||||
- `config.dmPolicy`
|
||||
- `config.allowFrom`
|
||||
- `config.groupPolicy`
|
||||
- `config.groupAllowFrom`
|
||||
|
||||
### TelegramAdapter
|
||||
|
||||
Supports:
|
||||
|
||||
- Bot API long polling as the default mode.
|
||||
- Optional webhook mode if configured.
|
||||
- Direct messages.
|
||||
- Group messages gated by mention or config.
|
||||
- Text replies with platform-safe formatting and chunking.
|
||||
- Photo/document/audio/video intake as cached local files or metadata.
|
||||
|
||||
Configuration:
|
||||
|
||||
- `secrets.botToken`
|
||||
- `config.mode`: `polling` or `webhook`
|
||||
- `config.webhookUrl`
|
||||
- `config.webhookSecret`
|
||||
- `config.requireMentionInGroups`
|
||||
- `config.allowFrom`
|
||||
- `config.groupAllowFrom`
|
||||
- `config.maxMessageChars`
|
||||
|
||||
### ExternalConnectorChannel For Weixin
|
||||
|
||||
Supports:
|
||||
|
||||
- Docker-compose predeclared sidecar connector.
|
||||
- QR-login sessions started and observed through the sidecar HTTP API.
|
||||
- Direct messages.
|
||||
- Text replies sent through the sidecar `/send` API.
|
||||
- Media send/receive when the sidecar provides normalized metadata.
|
||||
- Group delivery as best-effort only.
|
||||
|
||||
Configuration:
|
||||
|
||||
- `secrets.connectionToken`
|
||||
- `config.accountId`
|
||||
- `config.baseUrl`
|
||||
- `config.bridgeSecret`
|
||||
- `config.dmPolicy`
|
||||
- `config.allowFrom`
|
||||
- `config.groupPolicy`
|
||||
- `config.groupAllowFrom`
|
||||
- `config.maxMessageChars`
|
||||
|
||||
Inbound flow:
|
||||
|
||||
```text
|
||||
Weixin sidecar connector
|
||||
-> Beaver connector bridge endpoint
|
||||
-> ChannelRuntime.accept_inbound()
|
||||
-> MessageBus
|
||||
-> AgentService
|
||||
```
|
||||
|
||||
Outbound flow:
|
||||
|
||||
```text
|
||||
AgentService
|
||||
-> MessageBus outbound
|
||||
-> ExternalConnectorChannel.send()
|
||||
-> Weixin sidecar connector /send
|
||||
```
|
||||
|
||||
The sidecar is the Weixin protocol adapter. Beaver's `ExternalConnectorChannel` only validates bridge calls, normalizes the sidecar event boundary, preserves runtime dedupe/session semantics, and forwards outbound sends to the sidecar HTTP API.
|
||||
|
||||
## Access Control
|
||||
|
||||
Adapters may block inbound messages before calling `accept_inbound()` when the platform has channel-native allowlist settings. Runtime dedupe still applies after adapter admission.
|
||||
|
||||
Initial policy values:
|
||||
|
||||
- `open`: allow matching platform scope.
|
||||
- `allowlist`: require `allowFrom` or `groupAllowFrom`.
|
||||
- `disabled`: ignore inbound messages for that scope.
|
||||
|
||||
Pairing is owned by the connector layer. Platform adapters assume a materialized `ChannelConnection` and adapter-ready runtime config. For Weixin personal-account support, the runtime channel is an `ExternalConnectorChannel`, not a Beaver-owned `WeixinAdapter`.
|
||||
|
||||
## Delivery Semantics
|
||||
|
||||
Inbound:
|
||||
|
||||
- validate required routing fields before submitting to runtime.
|
||||
- preserve raw platform payload in metadata only when useful for debugging.
|
||||
- keep metadata small enough for event logs.
|
||||
- include media paths in metadata and text summaries in `content` when the agent needs to know an attachment exists.
|
||||
|
||||
Outbound:
|
||||
|
||||
- send only final assistant replies in phase one.
|
||||
- chunk messages to platform limits.
|
||||
- mark `delivery_status = "unclaimed"` when a target cannot be resolved.
|
||||
- raise or return delivery failures so `ChannelManager` records `outbound_delivery_failed`.
|
||||
|
||||
## Runtime Status
|
||||
|
||||
`ChannelRuntime.statuses()` should report platform channels with:
|
||||
|
||||
- `channel_id`
|
||||
- `kind`
|
||||
- `mode`
|
||||
- `display_name`
|
||||
- `enabled`
|
||||
- `state`
|
||||
- `account_id`
|
||||
- `last_error`
|
||||
- `last_event_at`
|
||||
- `capabilities`
|
||||
|
||||
Capabilities are conservative:
|
||||
|
||||
- Feishu: `receive_text`, `send_text`, `receive_media`, `groups`
|
||||
- QQBot: `receive_text`, `send_text`, `receive_media`, `groups`
|
||||
- Telegram: `receive_text`, `send_text`, `receive_media`, `groups`
|
||||
- Weixin: `receive_text`, `send_text`, `receive_media`, `direct_messages`
|
||||
|
||||
## Error Handling
|
||||
|
||||
- Adapter startup failure sets channel state to `error` and does not stop other channels.
|
||||
- Runtime shutdown calls every adapter `stop()`.
|
||||
- Platform transient errors should retry inside the adapter only when retrying cannot duplicate user-visible sends.
|
||||
- Fatal credential/config errors should surface in channel status.
|
||||
- Inbound duplicates are handled by existing `ChannelDedupeStore`.
|
||||
|
||||
## Testing
|
||||
|
||||
Add tests in small layers:
|
||||
|
||||
- factory tests for `kind` and `mode` adapter selection.
|
||||
- identity normalization tests for each platform.
|
||||
- inbound adapter tests using fake platform payloads.
|
||||
- outbound adapter tests with fake platform clients.
|
||||
- runtime status tests for configured enabled/disabled/error channels.
|
||||
|
||||
Network live tests are out of scope for unit tests. Adapter constructors should accept injectable clients or lightweight transport functions so tests do not call real platform APIs.
|
||||
|
||||
## Rollout
|
||||
|
||||
Implement one adapter at a time:
|
||||
|
||||
1. Telegram
|
||||
2. Feishu
|
||||
3. QQBot
|
||||
4. Weixin
|
||||
|
||||
Telegram is first because its bot-token flow and text path are the simplest proof of the shared adapter pattern. Weixin is last because QR/login state, context tokens, and media handling are more specialized.
|
||||
Reference in New Issue
Block a user