grammY 集成（Telegram Bot API）

为什么选择 grammY

  • TS 优先的 Bot API 客户端，内置长轮询 + webhook 帮助器、中间件、错误处理、速率限制器。
  • 比手写 fetch + FormData 更简洁的媒体帮助器；支持所有 Bot API 方法。
  • 可扩展：通过自定义 fetch 支持代理、会话中间件（可选）、类型安全的上下文。

我们发布的内容

  • 单一客户端路径： 移除基于 fetch 的实现；grammY 现在是唯一的 Telegram 客户端（发送 + gateway），默认启用 grammY 限速器。
  • Gateway： monitorTelegramProvider 构建 grammY Bot，连接提及/允许列表门控，通过 getFile/download 下载媒体，并通过 sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument 发送回复。支持长轮询或通过 webhookCallback 的 webhook。
  • 代理： 可选的 channels.telegram.proxy 通过 grammY 的 client.baseFetch 使用 undici.ProxyAgent。
  • Webhook 支持： webhook-set.ts 包装 setWebhook/deleteWebhook；webhook.ts 托管带健康检查和优雅关闭的回调。当设置 channels.telegram.webhookUrl + channels.telegram.webhookSecret 时，Gateway 启用 webhook 模式（否则它长轮询）。
  • 会话： 直接聊天折叠到代理主会话（agent:<agentId>:<mainKey>）；群组使用 agent:<agentId>:telegram:group:<chatId>；回复路由回同一通道。
  • 配置旋钮： channels.telegram.botToken、channels.telegram.dmPolicy、channels.telegram.groups（允许列表 + 提及默认值）、channels.telegram.allowFrom、channels.telegram.groupAllowFrom、channels.telegram.groupPolicy、channels.telegram.mediaMaxMb、channels.telegram.linkPreview、channels.telegram.proxy、channels.telegram.webhookSecret、channels.telegram.webhookUrl、channels.telegram.webhookHost。
  • 实时流预览： channels.telegram.streaming（off | partial | block | progress）发送临时消息并使用 editMessageText 更新它。这与通道块流式传输是分开的。
  • 测试： grammy 模拟覆盖 DM + 群组提及门控和出站发送；更多媒体/webhook fixture 仍然欢迎。

开放问题

  • 可选的 grammY 插件（限速器）如果遇到 Bot API 429。
  • 添加更多结构化媒体测试（贴纸、语音备忘录）。
  • 使 webhook 监听端口可配置（目前固定为 8787，除非通过 gateway 接入）。