grammY 集成（Telegram Bot API）

为何用 grammY

• 以 TypeScript 为先的 Bot API 客户端，内置 long-poll、webhook 辅助、中间件、错误处理与限流。
• 比手写 fetch + FormData 更清晰的媒体处理，支持全部 Bot API 方法。
• 可扩展：支持通过自定义 fetch 做代理、可选 session 中间件、类型安全的 context。

我们提供的实现

• 单一客户端路径：已移除基于 fetch 的实现；grammY 现为唯一的 Telegram 客户端（发送 + 网关），默认启用 grammY throttler。
• 网关：monitorTelegramProvider 构建 grammY Bot，接入提及/白名单门控、通过 getFile/download 下载媒体，并用 sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument 发送回复。通过 webhookCallback 支持 long-poll 或 webhook。
• 代理：可选配置 channels.telegram.proxy，通过 grammY 的 client.baseFetch 使用 undici.ProxyAgent。
• Webhook 支持：webhook-set.ts 封装 setWebhook/deleteWebhook；webhook.ts 托管回调并处理健康检查与优雅关闭。当设置 channels.telegram.webhookUrl 时网关启用 webhook 模式，否则使用 long-poll。
• 会话：私聊并入主会话（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.streamMode 在私密主题聊天中使用 sendMessageDraft（Bot API 9.3+）。与频道块流式是分开的。
• 测试：grammY 模拟覆盖私聊 + 群组提及门控与出站发送；更多媒体/webhook 用例仍欢迎补充。

待定事项

• 若遇到 Bot API 429，可考虑可选的 grammY 插件（throttler）。
• 增加更多结构化媒体测试（贴纸、语音消息）。
• 将 webhook 监听端口做成可配置（当前固定为 8787，除非经网关接入）。