grammY

- TypeScript 优先的 Bot API 客户端，内建 long-poll / webhook 辅助、middleware、错误处理与限流器。

- 媒体处理比自己手写 fetch + FormData 更干净；覆盖 Bot API 全量方法。

- 可扩展：支持自定义 fetch（用于代理）、session middleware（可选）、类型安全的上下文。

- 单一客户端路径： 已移除 fetch 版实现；目前 Telegram 客户端（发送 + gateway）统一使用 grammY，并默认启用 grammY throttler。

- Gateway： monitorTelegramProvider 构建 grammY Bot，接入 mention/allowlist 门禁；媒体通过 getFile/download 下载；出站使用 sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument。支持 long-poll 或通过 webhookCallback 的 webhook。

- 代理： 可选 channels.telegram.proxy，通过 grammY 的 client.baseFetch 使用 client.baseFetch。

- Webhook 支持： webhook-set.ts 封装 setWebhook/deleteWebhook；webhook.ts 托管 callback 并提供健康检查与优雅退出。Gateway 在配置了 channels.telegram.webhookUrl + channels.telegram.webhookSecret 时启用 webhook 模式（否则默认 long-poll）。

- Sessions: DMs fold into agent main session (agent:<agentId>:<mainKey>); groups use agent:<agentId>:telegram:group:<chatId>; replies deterministically return to same channel.

- 配置项： channels.telegram.botToken、channels.telegram.dmPolicy、channels.telegram.groups（群 allowlist + mention 默认）、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，在私聊 topic chat 里使用 sendMessageDraft（Bot API 9.3+）。该能力与通道 block streaming 独立。

- 测试： grammY mocks 覆盖私聊 + 群 mention 门禁与出站发送；仍欢迎补充更多媒体/webhook fixtures。

开放问题

- 若遇到 Bot API 429，评估引入更多 grammY plugins（或调整 throttler 策略）。

- 增加更结构化的媒体测试（贴纸、语音条等）。

- 让 webhook 监听端口可配置（当前若不通过 gateway 统一配置，默认固定为 8787）。