Telegram Bot Agent 是一个让 Claude 智能体充当 Telegram 机器人、管理账号、发送消息并自动化 Telegram 交互的技能，采用自然的基于名称的联系人系统。
用途 该技能适用于以下场景：创建或配置 Telegram 机器人；向用户或群组发送消息；通过联系人名称进行自然语言交互，例如“给 John 发消息”或“和开发团队聊天”，而不是直接使用 chat_id。
前置条件 使用前需安装： pip install python-telegram-bot python-dotenv
主要能力
- 机器人创建与设置：引导用户通过 Telegram 上的 @BotFather 创建机器人（发送 /newbot，提供名称和用户名，保存 BotFather 提供的 API token），运行初始化脚本 python scripts/init_bot.py 生成 .env 配置文件，运行 python scripts/test_connection.py 验证机器人是否正常工作，并通过 python scripts/contacts.py import 导入联系人。
- 联系人管理：支持从最近聊天导入联系人、手动添加联系人、列出全部联系人、搜索联系人、按名称获取 chat_id、移除联系人。命令包括 contacts.py import、contacts.py add "John" 123456789、contacts.py add "Dev Team" -100123456789 --type supergroup、contacts.py list、contacts.py search john、contacts.py get "John"、contacts.py remove "John"。
- 发送消息：优先使用联系人名称，例如 python scripts/send_message.py --to "John" -m "Hey, how are you?"；也可使用 chat_id；支持默认联系人 --use-default；支持 markdown 和 html 格式化，例如 --format markdown 或 --format html。
- 其他操作：获取机器人信息（bot_info.py）、列出最近聊天（list_chats.py）、获取指定聊天信息（get_chat_info.py --chat-id 123456789）。
- 加入群组：机器人需由群管理员添加，可通过邀请链接或管理员直接添加，之后导入群组为联系人并按群组名称发送消息。
- 高级功能：发送格式化消息、带按钮的消息（send_with_buttons.py --buttons "Yes,No,Maybe"）、发送文件（send_file.py --file path/to/file.pdf）、发送图片（send_photo.py --photo path/to/photo.jpg --caption "Check this out!"）。
使用方式 配置存储在 .env 中，包含 TELEGRAM_BOT_TOKEN 和 DEFAULT_CHAT_ID；联系人存储在自动创建的 contacts.json 中。用户以自然语言提出请求时，技能将其转换为基于联系人的命令，例如“Message John”对应 send_message.py --to "John" -m "..."，“Send this to the dev team”对应 send_message.py --to "dev team" -m "..."。联系人名称不区分大小写。
适用场景 适合需要通过 Claude 智能体自动化 Telegram 消息发送、联系人管理和群组交互的用户，尤其是希望以自然语言按名称操作联系人的场景。
限制与注意事项
- 群组聊天 ID 为负数（如 -100123456789），联系人系统会自动处理。
- 默认隐私模式下，群组中的机器人仅接收以 / 开头的命令、对机器人消息的回复或 @提及机器人的消息；如需接收所有消息，需通过 @BotFather 关闭隐私模式。
- Telegram 有速率限制（30 条消息/秒），脚本包含基本限流。
- 安全建议：不要提交 .env 或 contacts.json，不要分享机器人 token，发送前验证用户输入，使用环境变量存储敏感配置，如 token 泄露应通过 @BotFather 轮换。
- 故障排查：联系人未找到可运行 contacts.py list 或 import 或手动添加；机器人未收到消息需检查隐私模式、是否在群组中、是否被屏蔽；“Unauthorized”错误需检查 token 是否正确或是否被撤销；无法发送到群组需确认机器人是群成员且有发送权限。
- 详细 API 信息见 references/telegram_api.md，常见用法见 references/examples.md。