Rivoreo Source Code Repositories
src.rivoreo.one / aichatbot / main
commit5095705f33f86b9c26b3a1620d0bf9bc5e08667f[log] [download]
authorRivoreo AutoPilot <autopilot@rivoreo.one>Thu Dec 11 03:45:54 2025 +0800
committerRivoreo AutoPilot <autopilot@rivoreo.one>Thu Dec 11 03:45:54 2025 +0800
tree15da45be1b64407c4f4f3be87d3006d7d3968375
parent0ec736d6397f5ff6ea9079216163659d73feef52 [diff]
fix(telegram): enable MCP image analysis tool in system prompts

Remove MCP tool restriction from bot CLAUDE.md files to allow
AI to use the analyze_telegram_image tool for processing user images.

Changes:
- Update restriction rule from "不得使用任何MCP" to allow image tool
- Add analyze_telegram_image tool documentation to system prompts
- Specify tool usage: image_path (required), caption (optional)
- Clarify when to call the tool: upon "请使用 analyze_telegram_image 工具" prompt

Affected Bots:
- Tomato (西红柿)
- Cyrene
- Gold Ship (黄金船)

This fix resolves the issue where AI would not call the MCP tool
due to explicit prohibition in system prompts.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
3 files changed
tree: 15da45be1b64407c4f4f3be87d3006d7d3968375
  1. .coveragerc
  2. .env.all.example
  3. .gitignore
  4. CLAUDE.md
  5. DOCKER_DEPLOYMENT_MODES.md
  6. Dockerfile
  7. README.md
  8. ServerSideAutoCompact_TechnicalDesign_20251201_V1.0.md
  9. configs/
  10. coverage.json
  11. docker-bot.sh
  12. docker-compose.yml
  13. docs/
  14. fix_tests.py
  15. pyproject.toml
  16. references/sshout/
  17. requirements.txt
  18. run/
  19. scripts/
  20. src/claude_agent/
  21. tests/
README.md

Rivoreo Agent - 智能AI聊天助手

Version Tests Coverage Status

基于Claude Code SDK的智能AI聊天助手系统，专为Rivoreo社区设计，支持CLI交互、Telegram Bot、SSHOUT聊天室集成和多种AI交互模式。

🎯 核心特性

🤖 智能AI助手

  • Claude Code SDK集成: 基于最新Claude模型的智能对话处理
  • 双思考模式: 交互模式和YOLO自主思考模式
  • 流式响应: 实时消息更新和编辑功能
  • MCP工具集成: 支持外部工具和服务扩展

💬 多平台支持

  • Telegram Bot: 完整的Telegram机器人实现，支持私聊和群组
  • SSHOUT集成: SSH聊天室自动响应和智能参与
  • CLI界面: 现代化命令行交互体验
  • Webhook API: Bot间通信和消息广播系统

🚀 企业级特性

  • 持久化存储: 完整的离线记忆和对话历史恢复
  • 权限控制: 支持用户和群组白名单管理
  • 异步架构: 高性能并发处理和非阻塞I/O
  • 配置驱动: TOML配置文件，支持多环境部署

🏗️ 系统架构

rivoreo-agent/
├── src/claude_agent/          # 核心源代码
│   ├── core/                  # AI Agent核心逻辑
│   ├── telegram/              # Telegram Bot模块 (完整功能)
│   ├── cli/                   # 命令行界面
│   ├── sshout/               # SSHOUT聊天室集成
│   ├── mcp/                  # MCP工具框架
│   ├── webhook/              # Webhook API系统
│   ├── storage/              # 持久化存储
│   └── utils/                # 通用工具模块
├── tests/                    # 461个测试用例 (100%通过)
├── scripts/                  # 启动脚本和工具
├── configs/                  # 配置文件模板
├── docs/                     # 完整项目文档
├── data/                     # 运行时数据存储
└── run/                      # 专用运行环境

⚡ 快速开始

1. 环境配置

# 激活虚拟环境
source venv/bin/activate

# 验证依赖安装
pip install -r requirements.txt

2. Telegram Bot (推荐)

# 配置Bot Token (configs/local.toml)
[telegram]
bot_token = "YOUR_BOT_TOKEN"
allowed_users = [YOUR_USER_ID]

# 启动Telegram Bot
cd run/telegrambot
./start_telegrambot.sh

3. CLI模式

# 基础CLI
python scripts/main.py

# 增强CLI (支持历史翻查和补全)
python scripts/main_enhanced.py

4. SSHOUT聊天室

# 配置SSH连接 (configs/default.toml)
[sshout]
mention_patterns = ["@Claude", "@claude"]

# 启动SSHOUT集成
python scripts/main_enhanced.py --sshout

5. Webhook服务器 (Bot间通信)

# 配置Webhook服务器 (configs/webhook_server.toml)
[webhook]
enabled = true
auth_token = "your-secure-token"

[webhook.server]
host = "0.0.0.0"
port = 8080

# 启动独立Webhook服务器
./scripts/start_webhook_server.sh

Webhook服务器用途:

  • 突破Telegram限制: Telegram Bot API不允许Bot在群组中接收其他Bot的消息，Webhook打通Bot间通信
  • Bot间消息同步: 多个Bot实例之间实现消息广播和状态同步
  • 统一消息分发: 将消息同时发送到多个群组，实现跨群组通信
  • 中央通信枢纽: 作为Bot集群的消息路由中心，协调多Bot协作
  • 负载均衡: 支持多Bot实例的任务分发和消息协调处理

🌟 主要功能

Telegram Bot功能

  • ✅ 智能对话: 私聊和群组@机器人触发
  • ✅ 多媒体支持: 图片分析、文档处理
  • ✅ 流式消息: 实时消息更新编辑
  • ✅ 持久化记忆: 重启后自动恢复对话历史
  • ✅ 权限管理: 用户和群组白名单控制
  • ✅ 错误恢复: 完善的异常处理机制

AI交互模式

  • 🎯 交互模式: 传统问答式对话
  • 🧠 YOLO模式: 自主多步思考和问题解决
  • 📊 上下文管理: 智能对话历史管理
  • 🔄 流式响应: 实时消息流处理

支持的文件类型

  • 📷 图片: JPG, PNG, GIF, WebP
  • 📄 文档: PDF, DOC, DOCX, TXT, MD
  • 💾 其他: JSON, CSV等结构化数据

🧪 测试状态 (2025-10-04)

当前测试成就 🏆

  • 461个测试用例: 100%通过率
  • 89%代码覆盖率: 高质量测试覆盖
  • 8个跳过测试: 需要外部依赖的测试
  • 0个失败测试: 稳定可靠的代码质量

测试分布

模块测试数量通过率覆盖率
Telegram150+100%74%
Core Agent90+100%83%
Storage80+100%84%
Utils/CLI70+100%76%
SSHOUT/MCP60+100%70%

质量指标

  • ✅ 单元测试: 广泛的功能测试覆盖
  • ✅ 集成测试: 模块间交互验证
  • ✅ 黑盒测试: 端到端功能验证
  • ✅ 异常处理: 全面的错误场景测试
  • ✅ 性能测试: 响应时间和资源使用验证

📊 配置说明

Telegram Bot配置

[telegram]
bot_token = "BOT_TOKEN"                    # Telegram Bot Token
allowed_users = [123456]                   # 允许的用户ID列表
allowed_groups = [-1001234567]             # 允许的群组ID列表

[telegram.message]
stream_update_interval = 1.0               # 流式消息更新间隔
max_message_length = 4096                  # 最大消息长度
context_history_limit = 50                 # 上下文历史保留数量

[telegram.files]
max_file_size_mb = 20                      # 最大文件大小
temp_dir = "temp/telegram"                 # 临时文件目录

SSHOUT配置

[sshout]
mention_patterns = ["@Claude", "@claude"]  # 提及检测模式

[sshout.server]
hostname = "tianjin1.rivoreo.one"         # SSHOUT服务器
port = 22333                               # SSH端口
username = "sshout"                        # 登录用户名

[sshout.ssh_key]
private_key_path = "assets/ssh-keys/id_ecdsa_sshout_test"
timeout = 10                               # 连接超时

Webhook服务器配置

[webhook]
enabled = true                             # 启用Webhook功能
auth_token = "secure-webhook-token-2024"   # API认证Token
server_url = "http://localhost:8080"       # 服务器URL (可选)

[webhook.server]
host = "0.0.0.0"                          # 服务器绑定地址
port = 8080                               # 服务器端口
connection_timeout = 10.0                 # 连接超时 (秒)
request_timeout = 5.0                     # 请求超时 (秒)
max_retries = 3                           # 最大重试次数
retry_delay = 1.0                         # 重试延迟 (秒)

[logging]
level = "INFO"                            # 日志级别
format = "[%(asctime)s] %(levelname)s %(name)s: %(message)s"

技术背景: Telegram Bot API限制Bot在群组中无法接收其他Bot发送的消息，这导致多Bot系统无法直接通信。Webhook服务器通过HTTP API实现Bot间消息路由，突破了这一限制。

Webhook API端点:

  • POST /webhook/register - 注册Bot到服务器
  • POST /webhook/broadcast - 广播消息到指定群组
  • GET /webhook/health - 健康检查
  • GET /webhook/stats - 服务器统计信息

🔐 安全特性

权限控制

  • 🛡️ 白名单机制: 用户和群组访问控制
  • 🔐 SSH密钥认证: ECDSA私钥安全连接
  • 📝 输入验证: 防恶意输入和注入攻击
  • 🚫 未授权拒绝: 自动拒绝未授权访问

数据安全

  • 💾 本地存储: 敏感数据本地加密存储
  • 🧹 自动清理: 临时文件自动清理机制
  • 📋 配置分离: 敏感配置文件排除版本控制
  • 🔄 备份恢复: 自动数据备份和恢复

🚀 部署指南

生产环境部署

# 1. 环境配置
export CLAUDE_CONFIG=production
export ANTHROPIC_API_KEY="your_api_key"

# 2. 配置生产配置文件
cp configs/default.toml configs/production.toml
# 编辑 configs/production.toml

# 3. 启动服务
python scripts/start_telegram_bot.py

Docker部署 (可选)

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

# 运行容器
docker run -d --name claude-bot \
  -e ANTHROPIC_API_KEY=your_key \
  -v ./configs:/app/configs \
  -v ./data:/app/data \
  claude-agent

📈 性能指标

响应性能

  • ⚡ 消息响应: 平均 < 2秒
  • 🔄 流式更新: 1秒间隔实时更新
  • 📊 并发处理: 支持多用户同时对话
  • 💾 内存优化: 智能消息历史管理

系统资源

  • 🖥️ CPU使用: 空闲时 < 5%
  • 💾 内存占用: 平均 200-500MB
  • 💿 存储需求: 基础 < 100MB，数据按需增长
  • 🌐 网络带宽: 平均 < 1MB/小时

📚 文档体系

用户文档

开发文档

项目文档

🛠️ 故障排除

常见问题

  1. Bot Token无效

    ❌ 请配置有效的Telegram Bot Token

    解决: 检查 configs/local.toml 中的 bot_token 配置

  2. 权限被拒绝

    ❌ 用户无权限访问

    解决: 将用户/群组ID添加到白名单

  3. SSH连接失败

    ❌ SSHOUT连接失败

    解决: 检查SSH密钥权限和网络连通性

  4. 消息格式错误

    ❌ Markdown解析错误

    解决: 已修复Markdown清理机制，自动处理格式问题

日志分析

# 查看Telegram Bot日志
tail -f logs/telegram_bot.log

# 查看系统资源使用
htop | grep python

# 检查存储使用情况
du -sh data/storage/

🤝 开发贡献

代码质量标准

  • ✅ 类型注解: 完整的Python类型注解
  • ✅ 文档字符串: 规范的docstring文档
  • ✅ 错误处理: 全面的异常处理机制
  • ✅ 测试覆盖: 充分的测试用例覆盖

贡献流程

# 1. Fork项目并创建功能分支
git checkout -b feature/new-feature

# 2. 开发和测试
python -m pytest tests/ -v

# 3. 代码检查
python -m pytest tests/ --cov=src/claude_agent --cov-report=term

# 4. 提交Pull Request
git commit -m "feat: add new feature"
git push origin feature/new-feature

📄 许可证

MIT License - 详见 LICENSE 文件

🎯 项目状态

  • 当前版本: v2.3.0 Telegram Bot持久化存储版
  • 发布日期: 2025年10月4日
  • 测试状态: ✅ 461/461 测试用例通过 (100%通过率)
  • 代码覆盖: 📊 89%整体覆盖率，核心模块74-83%
  • 部署状态: 🚀 生产就绪，推荐立即部署使用
  • 维护状态: 🔄 持续维护和功能迭代

⚠️ 重要提醒: 请勿将包含真实Bot Token和API密钥的配置文件提交到版本控制系统。

🎉 项目成就: Rivoreo Agent已成功演进为功能完整、测试完备、生产就绪的企业级智能AI聊天助手系统！