渠道
渠道将提供商 webhook 转换为智能体对话。当用户在 Slack、GitHub、Telegram 或其他平台中与你的机器人交互时，webhook 到达，Flue 将其转换为对话消息并将其传递给你的智能体。本指南涵盖渠道架构、实现自己的渠道、以及内置的 Slack、GitHub 和 Telegram 集成。
渠道架构
渠道有三个部分：
- Webhook 接收器。 接收来自提供商的传入 webhook 的 HTTP 端点。
- 消息适配器。 将提供商特定的消息格式转换为 Flue 的通用消息格式。
- 响应传递。 将智能体的响应转换回提供商的 API 并发送它们。
Flue 处理 webhook 验证、消息转换和响应传递。你提供渠道配置和智能体逻辑。
使用内置渠道
Flue 包含 Slack、GitHub 和 Telegram 的内置渠道。使用 flue add 蓝图命令添加一个：
flue add channel slack蓝图会引导你的编码智能体创建渠道文件、安装依赖并配置 webhook。
渠道路由
每个渠道在 app.ts 中有自己的路由：
import { createAgentRouter } from '@flue/runtime';
import { slack } from './channels/slack.ts';
import { github } from './channels/github.ts';
import { telegram } from './channels/telegram.ts';
import { SupportAgent } from './agents/support.ts';
const app = new Hono();
// 渠道路由
app.route('/channels/slack', slack.route());
app.route('/channels/github', github.route());
app.route('/channels/telegram', telegram.route());
// 智能体路由
app.route('/agents/support', createAgentRouter(SupportAgent));
export default app;每个渠道路由处理传入的 webhook、验证它们、转换消息并将它们分派到你的智能体。
实现自定义渠道
要创建自定义渠道，实现 Channel 接口：
import { defineChannel } from '@flue/runtime';
export const customChannel = defineChannel({
name: 'custom',
// 处理传入的 webhook
async handleWebhook(request) {
// 验证 webhook
// 解析提供商特定的消息格式
// 返回标准化的消息
return {
message: {
kind: 'user',
body: parsedMessage.text,
},
conversationId: parsedMessage.conversationId,
};
},
// 传递响应
async deliverResponse(response, context) {
// 将响应转换为提供商的格式
// 使用提供商的 API 发送
await sendToProviderAPI(response.text);
},
});Slack 渠道
Slack 渠道处理 Slack 事件 API 和交互式消息。
设置：
- 创建 Slack 应用并配置事件订阅。
- 将事件 URL 设置为
https://your-domain.com/channels/slack/events。 - 订阅
message.im、message.channels和app_mention事件。
配置：
import { slack } from '@flue/runtime/channels/slack';
export const slackChannel = slack({
signingSecret: process.env.SLACK_SIGNING_SECRET,
botToken: process.env.SLACK_BOT_TOKEN,
});功能：
- 直接消息和频道提及
- 线程回复
- 附件和文件
- 交互式消息（按钮、菜单）
GitHub 渠道
GitHub 渠道处理 GitHub webhook 事件，如问题评论和拉取请求。
设置：
- 创建 GitHub 应用或使用个人访问令牌。
- 配置 webhook URL：
https://your-domain.com/channels/github/events。 - 订阅
issues、issue_comment和pull_request事件。
配置：
import { github } from '@flue/runtime/channels/github';
export const githubChannel = github({
webhookSecret: process.env.GITHUB_WEBHOOK_SECRET,
appId: process.env.GITHUB_APP_ID,
privateKey: process.env.GITHUB_PRIVATE_KEY,
});功能：
- 问题评论回复
- 拉取请求审查
- 代码审查评论
- 状态检查
Telegram 渠道
Telegram 渠道处理 Telegram 机器人 API。
设置：
- 通过 @BotFather 创建 Telegram 机器人。
- 使用
setWebhookAPI 设置 webhook URL：https://your-domain.com/channels/telegram/webhook。
配置：
import { telegram } from '@flue/runtime/channels/telegram';
export const telegramChannel = telegram({
botToken: process.env.TELEGRAM_BOT_TOKEN,
});功能：
- 文本消息
- 命令（
/start、/help等） - 内联键盘
- 文件和媒体
渠道消息格式
渠道将提供商特定的消息转换为 Flue 的通用格式：
{
kind: 'user',
body: 'User message text',
metadata: {
// 提供商特定的元数据
provider: 'slack',
userId: 'U123456',
channelId: 'C789012',
timestamp: '1234567890.123456',
},
}智能体通过 useDelivery() hook 访问元数据：
export function SupportAgent() {
const delivery = useDelivery();
const userId = delivery.metadata?.userId;
// 使用 userId 进行个性化
}渠道响应
智能体的响应被转换回提供商的格式：
// 智能体返回文本
return 'Here is the answer to your question.';
// 渠道将其转换为提供商格式
// Slack: { text: 'Here is the answer to your question.' }
// GitHub: issue comment
// Telegram: sendMessage API call多渠道智能体
一个智能体可以通过多个渠道接收消息：
app.route('/channels/slack', slack.route());
app.route('/channels/telegram', telegram.route());
app.route('/agents/support', createAgentRouter(SupportAgent));智能体根据交付上下文调整其响应：
export function SupportAgent() {
const delivery = useDelivery();
if (delivery.metadata?.provider === 'slack') {
// 使用 Slack 特定的格式
return '*Bold answer* with _italic_ text.';
} else if (delivery.metadata?.provider === 'telegram') {
// 使用 Telegram 特定的格式
return '**Bold answer** with __italic__ text.';
}
return 'Plain text answer.';
}渠道持久性
渠道消息被持久化为对话历史的一部分。当智能体恢复对话时，它可以访问所有先前的消息，无论它们来自哪个渠道。
conversationId 通常基于提供商特定的标识符（Slack 频道 ID、GitHub 问题编号等），但你可以自定义它。
渠道安全
Webhook 验证。 所有内置渠道都验证传入的 webhook 签名。对于自定义渠道，确保验证提供商的签名。
速率限制。 实施速率限制以防止滥用。
身份验证。 使用提供商的 API 密钥和令牌安全地访问 API。