核心用法
telethon-plus 是一个将 Telethon（Telegram MTProto 用户协议客户端）包装为 HTTP API 和 MCP（Model Context Protocol）端点的容器化服务。与 Bot API 不同，它驱动的是完整的 Telegram 用户账户，具备读写、管理、管理员等全部权限。
主要能力包括：
- 消息操作：发送/编辑/删除/转发消息，支持 Markdown/HTML 解析，可回复、静默发送、定时调度
- 媒体处理：通过 URL 发送文件/图片，或下载消息中的附件（HTTP 流或 MCP base64）
- 对话管理：列出会话、解析用户名/手机号/t.me 链接、搜索历史消息
- 群组与频道：创建/删除/加入/离开，获取成员列表，解析关联讨论组
- 管理员功能：禁言/解禁/踢人/提升/降级管理员，支持细粒度权限控制
- 投票系统：创建投票、投票、查看结果
- 实时推送：通过 WebSocket 或 webhook (
TELETHON_POST_TO_URL) 接收所有 incoming 事件
服务提供双入口：标准 REST API (/api/...) 和 MCP 流式 HTTP 端点 (/mcp/)，共 34 个工具，JSON 进出，Bearer Token 可选认证。
显著优点
1. 完整用户账户权限：超越 Bot API 限制，可操作私密对话、获取完整成员列表、执行管理员命令
2. 双协议兼容：既支持传统 HTTP/REST 调用，也支持 MCP 协议，便于接入 Claude 等 AI Agent
3. 实时事件流：WebSocket 和 webhook 双重机制，适合构建消息机器人、通知中心、自动化工作流
4. 内置防刷保护：多级令牌桶限流、自适应退避、实体缓存，主动规避 Telegram 的 FLOOD_WAIT 封禁
5. 部署简单：单容器 Docker 部署，环境变量配置，健康检查与 Prometheus 指标开箱即用
6. 灵活的实体引用：支持 @用户名、手机号、t.me 链接、数字 ID、me（收藏夹）等多种形式
潜在缺点与局限性
1. 部署前提复杂：需要用户自行完成 Telegram 账户的首次登录（生成 session string），技能本身不处理登录流程
2. SSRF 攻击面：file_url 参数由服务端抓取，若接受不可信 URL 可能导致内网探测，需严格校验域名白名单
3. ID 解析限制：纯数字 ID 需先有访问记录（通过用户名解析或对话列表），冷 ID 无法直接解析
4. 无多租户架构：每个容器绑定单一账户，不支持 Bot API 式的多机器人管理
5. 数据外泄风险：启用 webhook 会将全部 incoming 消息转发至外部端点，需确保目标可信
6. 资源占用：长期运行的 MTProto 会话与消息缓存需要持续内存和网络连接
适合的目标群体
- 开发者与运维工程师：需要将 Telegram 整合到自建系统、CI/CD 通知、监控告警的个人或团队
- 自动化爱好者：希望用脚本、curl 或 AI Agent 控制个人 Telegram 账户进行消息归档、内容转发、定时发布
- 社群管理员：管理大型群组/频道，需要批量执行禁言、踢人、权限调整等管理员操作
- 隐私优先用户：Bot API 无法满足需求（如获取完整成员列表、操作私密对话），且愿意自建基础设施
- MCP 生态探索者：希望将 Telegram 作为工具链接入 Claude Code 等 MCP 兼容的 AI 环境
常规使用风险
| 风险类别 | 说明 |
|---------|------|
| **账户封禁** | 尽管有防刷机制，高频操作或违反 Telegram ToS（垃圾信息、批量拉人）仍可能导致账户受限或永久封禁 |
| **权限过大** | 完整账户访问意味着误操作可删除群组、清空消息、提升恶意用户为管理员，破坏性操作需二次确认 |
| **凭证泄露** | `TELETHON_AUTH_KEY` 和 session string 泄露等于账户完全失控，需严格保管 |
| **网络暴露** | 若将 `/api/` 或 `/mcp/` 暴露至公网且无认证，任何人均可操作账户，建议绑定 localhost 或配合反向代理 + TLS |
| **依赖可用性** | 服务依赖 Docker 容器持续运行，Telegram 服务器故障或网络中断会导致 API 不可用 |
| **数据隐私** | webhook 和 MCP 调用会将消息内容外发至配置的目标，需确认接收端的数据处理合规性 |