Telegram MCP Server

# 轮询机制说明 ## 🔄 渐进式轮询策略 本 MCP 服务器使用**智能渐进式轮询**，根据等待时间自动调整检查频率，既保证响应速度，又节省资源。 ## 📊 轮询时间表 | 等待时长 | 轮询间隔 | 说明 | |---------|---------|------| | 0 - 30 分钟 | **30 秒** | 快速响应期 | | 30 分钟 - 1 小时 | **60 秒** | 中等响应期 | | 1 小时以上 | **120 秒** | 节能模式 | ### 示例时间线 ``` 开始等待 ↓ 0:00 - 检查 Telegram 0:30 - 检查 Telegram ← 30 秒间隔 1:00 - 检查 Telegram 1:30 - 检查 Telegram ... 29:30 - 检查 Telegram 30:00 - 检查 Telegram ↓ 30:00 - 切换到 60 秒间隔 31:00 - 检查 Telegram ← 60 秒间隔 32:00 - 检查 Telegram ... 59:00 - 检查 Telegram 60:00 - 检查 Telegram ↓ 60:00 - 切换到 120 秒间隔 62:00 - 检查 Telegram ← 120 秒间隔 64:00 - 检查 Telegram ... 继续直到收到回复或超时（最长 7 天） ``` ## ⏱️ 最长等待时间 **默认**: 604800 秒（7 天） 这意味着： - 你可以启动一个任务 - 离开电脑一周 - 随时通过 Telegram 回复 - Codex/Claude Code 会继续执行 ## 🎯 设计理念 ### 为什么使用渐进式轮询？ 1. **快速响应**（前 30 分钟） - 用户通常在任务启动后不久就会回复 - 30 秒间隔确保快速响应 2. **平衡资源**（30 分钟 - 1 小时） - 用户可能在处理其他事情 - 60 秒间隔足够快，又不浪费资源 3. **节省资源**（1 小时以上） - 用户可能离开了电脑 - 120 秒间隔节省 API 调用和电量 - 仍然能在 2 分钟内响应 ### 为什么最长等待 7 天？ - **真正的无人值守**: 可以周末启动任务，周一回来继续 - **灵活性**: 不用担心任务超时 - **实用性**: 覆盖几乎所有实际使用场景 ## 🔧 配置选项 ### 自定义最长等待时间 在调用工具时可以指定： ```python telegram_wait_reply(max_wait=3600) # 1 小时 telegram_unattended_mode(max_wait=86400) # 24 小时 ``` 或通过环境变量： ```bash TELEGRAM_MAX_WAIT=86400 codex # 24 小时 ``` ### 自定义轮询间隔 通过环境变量： ```bash # 格式: "间隔1,间隔2,间隔3"（秒） TELEGRAM_POLL_INTERVAL="10,30,60" codex # 示例：更激进的轮询 # 前 10 分钟: 10 秒 # 10-30 分钟: 30 秒 # 30 分钟以上: 60 秒 ``` ## 📈 资源消耗分析 ### 7 天等待的 API 调用次数 假设用户在第 7 天才回复： ``` 前 30 分钟: 1800 秒 / 30 秒 = 60 次 30-60 分钟: 1800 秒 / 60 秒 = 30 次 1 小时 - 7 天: (604800 - 3600) 秒 / 120 秒 = 5010 次 总计: 约 5100 次 API 调用 ``` **Telegram API 限制**: - 每秒 30 次请求 - 我们的最高频率: 每 30 秒 1 次 - **完全在限制范围内** ✅ ### 电量消耗 - 每次轮询: ~10ms CPU 时间 - 7 天总计: ~51 秒 CPU 时间 - **几乎可以忽略不计** ✅ ## 🎮 实际使用场景 ### 场景 1: 快速交互（5 分钟内） ``` 15:00:00 - 启动任务 15:00:30 - 检查（无消息） 15:01:00 - 检查（无消息） 15:01:30 - 检查（无消息） 15:02:00 - 检查（无消息） 15:02:30 - 检查（无消息） 15:03:00 - 检查（收到回复！）✅ ``` **响应时间**: 最多 30 秒延迟 ### 场景 2: 午餐时间（1 小时） ``` 12:00 - 启动任务，去吃午饭 12:30 - 切换到 60 秒间隔 13:00 - 回来，发送回复 13:01 - 收到回复！✅ ``` **响应时间**: 最多 60 秒延迟 ### 场景 3: 过夜任务（12 小时） ``` 22:00 - 启动任务，去睡觉 22:30 - 切换到 60 秒间隔 23:00 - 切换到 120 秒间隔 ...整夜持续轮询... 08:00 - 起床，发送回复 08:02 - 收到回复！✅ ``` **响应时间**: 最多 120 秒延迟 ### 场景 4: 周末任务（3 天） ``` 周五 18:00 - 启动任务，开始周末 周五 19:00 - 切换到 120 秒间隔 ...整个周末持续轮询... 周一 09:00 - 回到办公室，发送回复 周一 09:02 - 收到回复！✅ ``` **响应时间**: 最多 120 秒延迟 ## 🔍 监控轮询状态 ### 查看日志 ```bash tail -f /tmp/telegram-mcp-server.log | grep getUpdates ``` 输出示例： ``` 15:00:00 - HTTP Request: POST .../getUpdates "HTTP/1.1 200 OK" 15:00:30 - HTTP Request: POST .../getUpdates "HTTP/1.1 200 OK" 15:01:00 - HTTP Request: POST .../getUpdates "HTTP/1.1 200 OK" ... ``` ### 计算当前间隔 根据日志时间戳的间隔： - 30 秒 → 快速响应期 - 60 秒 → 中等响应期 - 120 秒 → 节能模式 ## ⚙️ Codex 配置要求 由于 Codex 有工具超时限制，需要配置： ```toml [mcp_servers.telegram] tool_timeout_sec = 604800 # 7 天 [mcp_servers.telegram.env] TELEGRAM_MAX_WAIT = "604800" # 匹配超时时间 ``` **重要**: `tool_timeout_sec` 必须 >= `TELEGRAM_MAX_WAIT` ## 📝 最佳实践 ### 1. 根据使用场景选择超时 | 场景 | 推荐配置 | |------|---------| | 快速开发 | `tool_timeout_sec = 3600`（1 小时） | | 日常使用 | `tool_timeout_sec = 86400`（24 小时） | | 完全无人值守 | `tool_timeout_sec = 604800`（7 天） | ### 2. 自定义轮询间隔 如果你希望更快的响应： ```bash # 更激进的轮询（消耗更多资源） TELEGRAM_POLL_INTERVAL="10,20,30" codex ``` 如果你希望节省资源： ```bash # 更保守的轮询（响应更慢） TELEGRAM_POLL_INTERVAL="60,120,300" codex ``` ### 3. 监控长时间运行 对于超过 1 天的任务： ```bash # 在另一个终端监控 watch -n 60 'tail -1 /tmp/telegram-mcp-server.log' ``` ## 🆚 与其他方案对比 ### 固定间隔轮询 ``` 每 30 秒检查一次，持续 7 天 API 调用: 604800 / 30 = 20160 次 ❌ 太多 ``` ### 指数退避 ``` 30s → 60s → 120s → 240s → 480s → ... 问题: 后期响应太慢（可能 8 分钟才检查一次）❌ ``` ### 渐进式轮询（我们的方案） ``` 30s → 60s → 120s（保持） API 调用: ~5100 次 ✅ 合理 响应时间: 最多 120 秒 ✅ 可接受 ``` ## 💡 技术实现 ### 代码位置 `telegram_mcp_server/server.py`: ```python def get_poll_interval(elapsed_seconds: float) -> int: """ Get polling interval based on elapsed time Progressive slowdown: 30s → 60s → 120s """ if elapsed_seconds < 1800: # < 30 minutes return 30 # 30 seconds elif elapsed_seconds < 3600: # < 1 hour return 60 # 60 seconds else: return 120 # 120 seconds ``` ### 配置位置 `telegram_mcp_server/config.py`: ```python TELEGRAM_MAX_WAIT = int(os.getenv("TELEGRAM_MAX_WAIT", "604800")) # 7 days POLL_INTERVALS = [30, 60, 120] # seconds POLL_THRESHOLDS = [1800, 3600] # 30 minutes, 1 hour ``` ## 🎯 总结 - ✅ **智能**: 根据等待时间自动调整 - ✅ **高效**: 快速响应 + 节省资源 - ✅ **灵活**: 可自定义所有参数 - ✅ **可靠**: 最长可等待 7 天 - ✅ **实用**: 覆盖所有实际场景 **这就是为什么本 MCP 服务器非常适合真正的无人值守模式！** 🚀