通道适配器

LibreFang 支持 40 个消息平台适配器，连接您的 agent 到用户所在的每个平台。

提示: 每个通道都可以单独配置访问控制、速率限制和过滤规则。

支持的平台

核心平台

平台	说明	状态
Telegram	Bot API	✅
Discord	Bot API	✅
Slack	Bot API	✅
WhatsApp	Business API	✅
Signal	Bot API	✅
Matrix	Client API	✅
Email	IMAP/SMTP	✅

企业平台

平台	说明
Microsoft Teams	Bot Framework
Mattermost	Webhook/API
Google Chat	Bot API
Webex	Bot API
Feishu/Lark	Open Platform
Zulip	API

社交平台

平台	说明
LINE	Messaging API
Viber	Bot API
Facebook Messenger	Graph API
Mastodon	Client API
Bluesky	AT Protocol
Reddit	OAuth API
LinkedIn	Marketing API
Twitch	PubSub

社区平台

平台	说明
IRC	Client/Server
XMPP	Client API
Guilded	HTTP API
Revolt	HTTP API
Keybase	Client API
Discourse	API
Gitter	Client API

隐私平台

平台	说明
Threema	Gateway API
Nostr	NIP-04/26
Mumble	Murmur API
Nextcloud Talk	HTTP API
Rocket.Chat	Client API
Ntfy	HTTP API
Gotify	HTTP API

工作平台

平台	说明
Pumble	HTTP API
Flock	Webhook/API
Twist	API
DingTalk	Open API
Zalo	API

配置

[telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = ["user_id_1", "user_id_2"]

Discord

[discord]
bot_token_env = "DISCORD_BOT_TOKEN"
guild_ids = ["server_id_1", "server_id_2"]

Slack

[slack]
bot_token_env = "SLACK_BOT_TOKEN"
app_token_env = "SLACK_APP_TOKEN"

通道覆盖

每个通道支持覆盖设置：

[channels.telegram]
model = "claude-sonnet-4-20250514"
system_prompt = "你是一个客服 agent"
dm_policy = "allow"  # allow/deny
group_policy = "allow"  # allow/deny
rate_limit = 10  # 每分钟消息数
output_format = "markdown"  # markdown/html/plaintext

覆盖选项

选项	说明
`model`	覆盖默认模型
`system_prompt`	覆盖系统提示
`dm_policy`	DM 策略 (allow/deny)
`group_policy`	群组策略 (allow/deny)
`rate_limit`	每分钟限制
`output_format`	输出格式

速率限制

每个通道有内置速率限制：

每用户限制 - 防止滥用
每通道限制 - 平台限制
成本感知 - 跟踪 token 使用

[channels.telegram]
rate_limit = 10  # 每分钟 10 条消息

格式化

LibreFang 自动格式化消息：

Telegram → HTML
Slack → Mrkdwn
Discord → 嵌入
其他 → 纯文本

CLI 命令

# 列出通道状态
librefang channel list

# 设置新通道
librefang channel setup telegram

# 测试通道
librefang channel test telegram

# 启用通道
librefang channel enable telegram

# 禁用通道
librefang channel disable telegram

消息路由

AgentRouter 根据规则路由消息：

用户匹配 - 特定用户
通道匹配 - 特定通道
内容匹配 - 关键词/正则

最佳实践

限制访问 - 使用 allowed_users 限制谁可以访问
设置速率限制 - 防止滥用
使用覆盖 - 为不同通道定制行为
监控使用 - 定期检查通道统计

添加 Feature Flag

所有通道适配器都通过 Cargo feature flag 进行条件编译。默认构建包含 12 个常用通道，您可以按需启用其他通道以减小二进制体积。

Feature Flag 层级

Feature flag 需要在三层 Cargo.toml 中逐级转发：

1. crates/librefang-channels/Cargo.toml — 定义 feature 并绑定可选依赖：

[features]
default = [
    "channel-telegram",
    "channel-discord",
    "channel-slack",
    # ... 共 12 个默认通道
]

all-channels = [
    "channel-telegram",
    "channel-discord",
    # ... 全部 42 个通道
]

# 各通道的 feature 定义
channel-telegram = []
channel-email = ["dep:lettre", "dep:imap", "dep:native-tls", "dep:mailparse"]
channel-qq = ["dep:rustls"]
channel-wecom = ["dep:roxmltree", "dep:aes", "dep:cbc"]

2. crates/librefang-api/Cargo.toml — 转发到 channels crate：

[features]
channel-telegram = ["librefang-channels/channel-telegram"]
channel-qq = ["librefang-channels/channel-qq"]
all-channels = ["librefang-channels/all-channels"]

3. crates/librefang-cli/Cargo.toml — 转发到 api crate：

[features]
all-channels = ["librefang-api/all-channels"]

可选依赖绑定

部分通道需要额外依赖，通过 dep: 语法绑定到 feature flag：

通道	可选依赖	用途
Email	`lettre`, `imap`, `native-tls`, `mailparse`	IMAP/SMTP 邮件收发
QQ	`rustls`	TLS 加密连接
WeCom (企业微信)	`roxmltree`, `aes`, `cbc`	XML 解析与消息加解密

在源代码中使用 #[cfg(feature = "channel-xxx")] 条件编译：

#[cfg(feature = "channel-telegram")]
pub mod telegram;

#[cfg(feature = "channel-qq")]
pub mod qq;

构建选项

# 默认构建（12 个通道）
cargo build --workspace

# 启用全部通道
cargo build --workspace --features all-channels

# 仅启用特定通道
cargo build --workspace --no-default-features --features channel-telegram,channel-slack

# 最小构建（无通道适配器）
cargo build --workspace --no-default-features

贡献新 Channel Adapter

添加新通道适配器的完整步骤：

创建适配器模块 — 在 crates/librefang-channels/src/ 下新建 myplatform.rs，实现 ChannelAdapter trait（包含 name()、channel_type()、start()、send()、stop() 方法）
添加 Feature Flag — 在 crates/librefang-channels/Cargo.toml 中添加 channel-myplatform = []（如有特殊依赖则绑定 dep:），并将其加入 all-channels 列表
转发 Feature Flag — 在 crates/librefang-api/Cargo.toml 中添加 channel-myplatform = ["librefang-channels/channel-myplatform"]，并加入其 all-channels 列表
注册模块 — 在 crates/librefang-channels/src/lib.rs 中添加条件编译模块声明：
#[cfg(feature = "channel-myplatform")] pub mod myplatform;
接入 Bridge — 在 crates/librefang-api/src/channel_bridge.rs 中添加适配器初始化逻辑
添加配置支持 — 在 librefang-types 中添加配置结构体（包含 token_env、default_agent、overrides 字段），并加入 ChannelsConfig
添加 CLI 向导 — 在 crates/librefang-cli/src/main.rs 的 cmd_channel_setup 中添加交互式设置流程
编写测试 — 使用 ChannelMessage 类型编写集成测试，无需连接真实平台即可验证适配器逻辑