Rivoreo Agent - Telegram Bot 详细指南

专为Rivoreo社区设计的智能Telegram Bot，基于Claude Code SDK实现，支持私聊和群组消息处理、流式消息发送、文件处理等完整功能。

📚 主要文档: 请先阅读 主项目README 了解整体功能和快速开始指南

📊 当前状态: v2.3.0 | 461个测试用例100%通过 | 89%代码覆盖率 | 2025-10-04

🎯 Telegram Bot 专属特性

💬 智能消息处理

• 流式回复: 消息内容实时更新，提供流畅的对话体验
• Markdown智能清理: 自动处理格式问题，确保Telegram兼容性
• 上下文感知: 每个用户/群组独立的对话历史和上下文
• 持久化记忆: Bot重启后自动恢复所有对话历史

🖼️ 多媒体文件处理

• 图片分析: 自动分析上传的图片并提供详细描述
• 文档处理: 支持PDF、Word、文本等多种格式文档分析
• 文件安全: 大小限制(20MB)、格式白名单、自动清理

🏢 群组智能参与

• @机器人检测: 自动识别群组中的@提及
• 智能回复时机: 基于上下文判断是否需要参与讨论
• 权限精细控制: 支持用户级和群组级权限管理

🔧 详细配置指南

创建Telegram Bot

1. 在Telegram中联系 @BotFather
2. 发送 /newbot 创建新机器人
3. 按提示设置Bot名称和用户名
4. 获取Bot Token (格式: 1234567890:ABCdefGhIjKlMnOpQrStUvWxYz)

获取用户和群组ID

# 启动Bot并查看日志
python scripts/start_telegram_bot.py

# 私聊Bot或在群组@Bot后查看日志输出:
# [INFO] 收到用户消息: 用户ID=123456789, 用户名=@username
# [INFO] 收到群组消息: 群组ID=-1001234567890, 群组名=Group Name

完整配置文件示例 (configs/local.toml)

[telegram]
bot_token = "1234567890:ABCdefGhIjKlMnOpQrStUvWxYz"
allowed_users = [123456789, 987654321]        # 允许的用户ID列表
allowed_groups = [-1001234567890]             # 允许的群组ID列表 (负数)

[telegram.message]
stream_update_interval = 1.0                  # 流式消息更新间隔(秒)
max_message_length = 4096                     # 最大消息长度
context_history_limit = 50                    # 上下文历史保留数量
reply_timeout = 30                            # 回复超时时间(秒)

[telegram.files]
max_file_size_mb = 20                         # 最大文件大小(MB)
temp_dir = "temp/telegram"                    # 临时文件目录
allowed_image_types = ["jpg", "jpeg", "png", "gif", "webp"]
allowed_document_types = ["pdf", "doc", "docx", "txt", "md"]

[telegram.storage]
data_dir = "data/storage"                     # 持久化数据目录
auto_save_interval = 60                       # 自动保存间隔(秒)
backup_enabled = true                         # 启用备份功能
max_history_per_chat = 1000                   # 每个聊天最大历史记录数

[telegram.behavior]
auto_typing = true                            # 发送"正在输入"状态
markdown_mode = "safe"                        # Markdown处理模式: safe/strict/off
error_retry_count = 3                         # 错误重试次数
rate_limit_per_user = 10                      # 每用户每分钟消息限制

🚀 启动和部署选项

开发环境启动

# 方式1: 专用启动脚本(推荐)
cd run/telegrambot
./start_telegrambot.sh

# 方式2: Python直接启动
python scripts/start_telegram_bot.py

# 方式3: 指定工作目录
python scripts/start_telegram_bot.py --working-dir ./run/telegrambot

# 方式4: 指定配置环境
CLAUDE_CONFIG=local python scripts/start_telegram_bot.py

生产环境部署

# 1. 配置生产环境
export CLAUDE_CONFIG=production
export ANTHROPIC_API_KEY="your_production_api_key"

# 2. 使用systemd服务(推荐)
sudo cp scripts/rivoreo-agent.service /etc/systemd/system/
sudo systemctl enable rivoreo-agent
sudo systemctl start rivoreo-agent

# 3. 查看服务状态
sudo systemctl status rivoreo-agent
sudo journalctl -u rivoreo-agent -f

Docker容器部署

# 构建镜像
docker build -t rivoreo-agent .

# 运行容器
docker run -d --name rivoreo-telegram-bot \
  -e ANTHROPIC_API_KEY=your_api_key \
  -e CLAUDE_CONFIG=production \
  -v ./configs:/app/configs:ro \
  -v ./data:/app/data \
  --restart unless-stopped \
  rivoreo-agent

# 查看日志
docker logs -f rivoreo-telegram-bot

💬 使用场景和最佳实践

私聊使用模式

用户: 你好
Bot: 🤖 你好！我是Rivoreo Agent，你的智能AI助手。我可以：
• 💬 进行自然对话和问答
• 🖼️ 分析你发送的图片
• 📄 处理文档和文件
• 🧠 使用YOLO模式进行深度思考

直接发送消息、图片或文档给我即可！

用户: [发送图片]
Bot: 🖼️ 我看到了一张...的图片。图片中显示了...
[实时更新消息内容，流式显示分析结果]

群组使用模式

用户A: 大家好！
用户B: @rivoreo_agent 请分析一下这个技术问题...
Bot: 🤖 我来分析这个技术问题...
[基于群组上下文提供相关回复]

管理员: @rivoreo_agent 总结一下刚才的讨论
Bot: 📝 根据刚才的讨论，我总结如下要点：
1. ...
2. ...

文件处理工作流

1. 上传文件: 直接发送图片或文档到Bot
2. 自动识别: Bot自动识别文件类型和内容
3. 智能分析: 根据文件类型进行相应的分析处理
4. 结果反馈: 流式更新分析结果和建议

🧪 测试和监控

功能验证脚本

# 运行完整的功能验证
python scripts/verify_telegram_bot.py

# 输出示例:
# ✅ Bot Token验证通过
# ✅ 权限配置验证通过
# ✅ 文件处理功能正常
# ✅ 持久化存储正常
# ✅ 流式消息功能正常

测试覆盖状态 (2025-10-04)

测试模块	测试数量	通过率	覆盖率	状态
Bot核心功能	45个	100%	81%	✅ 优秀
消息处理器	38个	100%	72%	✅ 良好
文件处理器	32个	100%	81%	✅ 优秀
上下文管理	25个	100%	93%	🏆 卓越
流式发送器	20个	100%	56%	⚠️ 待改进

性能监控指标

# 查看Bot运行状态
ps aux | grep start_telegram_bot

# 监控内存使用
watch -n 5 'ps -p $(pgrep -f start_telegram_bot) -o pid,ppid,cmd,%mem,%cpu'

# 查看存储使用情况
du -sh data/storage/
ls -la data/storage/telegram_*

# 实时日志监控
tail -f logs/telegram_bot.log | grep -E "(ERROR|WARNING|消息处理|用户)"

🔧 故障排除专题

常见错误及解决方案

1. Bot Token相关错误

❌ Error: 401 Unauthorized: bot token is invalid

解决方案:

• 检查Token格式是否正确 (数字:字母数字组合)
• 确认Token未过期或被撤销
• 重新从BotFather获取Token

2. 权限被拒绝

❌ 用户 123456789 无权限访问此Bot

解决方案:

# 在 configs/local.toml 中添加用户ID
[telegram]
allowed_users = [123456789]  # 添加用户ID到列表
allowed_groups = [-1001234567890]  # 群组ID(负数)

3. 文件处理失败

❌ 文件过大: 25.5MB > 20MB限制

解决方案:

# 调整文件大小限制
[telegram.files]
max_file_size_mb = 50  # 增加到50MB

4. Markdown解析错误

❌ Can't parse entities: can't find end of the entity starting at byte offset 123

解决方案: Bot已集成智能Markdown清理，自动修复格式问题。如仍有问题，可调整配置:

[telegram.behavior]
markdown_mode = "safe"  # safe/strict/off

5. 持久化数据问题

❌ 无法保存对话历史: Permission denied

解决方案:

# 检查目录权限
ls -la data/storage/
chmod 755 data/storage/
chown -R $USER:$USER data/

# 检查磁盘空间
df -h

调试工具和技巧

启用详细日志

# 在启动脚本中添加调试配置
import logging
logging.basicConfig(level=logging.DEBUG)

# 或通过环境变量
export PYTHONPATH=/path/to/project:$PYTHONPATH
export LOG_LEVEL=DEBUG
python scripts/start_telegram_bot.py

测试特定功能

# 测试消息处理
python -m pytest tests/unit/telegram/test_message_handler.py -v -k "test_process_text_message"

# 测试文件处理
python -m pytest tests/unit/telegram/test_file_handler.py -v

# 测试完整流程
python -m pytest tests/integration/telegram/ -v

🎯 高级功能配置

自定义AI行为

通过 run/telegrambot/CLAUDE.md 文件自定义Bot的个性和行为:

# Rivoreo Agent 个性化设置

你是Rivoreo社区的智能AI助手，具有以下特点:
- 🤖 专业而友好的交流风格
- 🎯 专注于技术问题的深度分析
- 🚀 积极主动提供解决方案
- 🌟 保持对新技术的好奇和学习态度

在群组中：
- 只在被@时响应，保持适度参与
- 基于上下文提供相关性建议
- 避免重复已讨论的内容

在私聊中：
- 主动了解用户需求
- 提供详细的技术说明
- 推荐最佳实践方案

webhook集成配置

[webhook]
enable = true
port = 8080
secret_token = "your_webhook_secret"
allowed_ips = ["127.0.0.1"]

[webhook.bot_communication]
enable_broadcast = true
target_bots = ["@another_bot"]

📈 性能优化建议

消息处理优化

• 批处理: 启用消息批处理减少API调用频率
• 缓存: 使用Redis缓存频繁访问的数据
• 异步队列: 使用Celery处理耗时任务

存储优化

• 定期清理: 设置自动清理过期数据的定时任务
• 分片存储: 大量用户时考虑按用户ID分片存储
• 压缩备份: 启用数据压缩减少存储空间

监控告警

# 添加性能监控
import psutil
import time

def monitor_performance():
    cpu_percent = psutil.cpu_percent()
    memory_percent = psutil.virtual_memory().percent

    if cpu_percent > 80 or memory_percent > 80:
        # 发送告警通知
        send_alert(f"高资源使用: CPU {cpu_percent}%, 内存 {memory_percent}%")

🤝 社区和支持

贡献指南

1. 问题反馈: 通过GitHub Issues报告问题
2. 功能建议: 提交Feature Request描述需求
3. 代码贡献: Fork项目并提交Pull Request
4. 文档改进: 帮助改善文档和示例

技术交流

• Rivoreo社区群: 加入Rivoreo技术交流群组
• 开发者论坛: 参与技术讨论和经验分享
• 定期更新: 关注项目更新和新功能发布

---

📱 Telegram Bot专属: 本指南专注于Telegram Bot的详细配置和使用，更多整体功能请参考主项目文档

🎉 Rivoreo Agent Telegram Bot: 为Rivoreo社区量身定制的智能AI聊天助手，让AI技术真正为社区服务！

最后更新: 2025年10月4日 | 版本: v2.3.0