# 🤖 AI 代理机器人 (TG Bot)

一个基于 NVIDIA API 的多模态 Telegram 聊天机器人，具备自主搜索、深度阅读、图片识别及长期记忆管理能力。

## ✨ 核心特性

### 1. 灵活的核心架构
- **API 适配层**：默认对接 `https://integrate.api.nvidia.com/v1/chat/completions`，完全兼容所有 NVIDIA NeMo 微服务及第三方 OpenAI 协议接口。
- **动态模型切换**：内置 `/model` 指令，实时并发检测所有注册模型的可用性（显示 ✅/❌ 状态），一键无缝切换推理引擎。
- **主脚本配置**：所有核心参数（API 地址、密钥、模型列表）均在 `tg_bot.py` 顶部配置，无需额外配置文件即可快速迁移或私有化部署。

### 2. 智能 Agent 能力
- **自主决策流程**：
  - 🔍 **Web Search**：优先使用搜索引擎获取最新信息。
  - 📄 **Web Fetch**：自动判断是否需要深度阅读全文（包含防 PDF 陷阱机制）。
  - 🖼️ **Image Search**：支持按关键词实时检索图片并返回 Markdown 格式展示。
  - 🧠 **Memory Mgmt**：内置单用户级长期记忆存储 (`user_memory.json`)，支持添加、查询、删除关键个人偏好。
- **上下文优化**：
  - 自动压缩长对话历史，保留 System Prompt 和最近 20 轮有效信息。
  - 防止重复抓取同一 URL，节省 Token 消耗。

### 3. 输出优化
- **移动端友好**：强制禁用 Markdown 表格，转换为清晰的无序列表格式，完美适配 Telegram 客户端渲染。
- **流式状态反馈**：发送消息后立即编辑占位符文字（如“正在搜索..."、“正在深度阅读...”），提升交互体验。

---

## 🚀 快速开始

### 1. 环境依赖
确保已安装 Python 3.8+ 及以下库：
```bash
pip install pyTelegramBotAPI python-dotenv duckduckgo-search beautifulsoup4 requests urllib3
```

### 2. 环境变量配置 (.env)
在项目根目录创建 `.env` 文件填入凭证：
```ini
# Telegram Bot Token
TELEGRAM_BOT_TOKEN=your_telegram_token_here

# NVIDIA API Key (或其他兼容接口的 Key)
NVIDIA_API_KEY=nvapi-your-key-here

# 允许使用的用户 ID (逗号分隔，为空则不限)
ALLOWED_USERS=123456789,987654321
```

### 3. 运行程序
```bash
cd E:\AI_Workspace
python tg_bot.py
```

---

## ⚙️ 高级定制指南

### 修改 API 地址与模型
如需适配非 NVIDIA 官方接口（例如本地 Ollama 或其他云厂商）：

1. 打开 `tg_bot.py`。
2. 定位至 **核心配置区**（约第 25 行）：
   ```python
   NVIDIA_API_URL = "https://integrate.api.nvidia.com/v1/chat/completions" # 修改此处
   DEFAULT_MODEL = "openai/gpt-oss-120b"                                  # 修改默认模型
   ```
3. 更新 `MODEL_MAP` 字典以匹配新提供商支持的模型 ID：
   ```python
   MODEL_MAP = {
       "my-custom-model": "namespace/model-id", # 格式：display_name: api_model_id
       ...
   }
   ```

### 扩展自定义工具
在 `TOOLS` 列表中定义新的 Function Schema，并在 `execute_*` 系列函数中实现具体逻辑。

---

## 📂 项目结构

| 文件名 | 说明 |
| :--- | :--- |
| `tg_bot.py` | **主程序**。包含核心逻辑、Tool 定义、API 调用及 Telegram 事件处理。 |
| `.env` | **敏感配置**。Token 与 API Key 存放处，严禁提交到公共仓库。 |
| `user_memory.json` | **运行时自动生成**。存储每个 ChatID 对应的长期记忆数据。 |
| `README.md` | **本项目文档**。 |

---

## 💡 常见问题 (FAQ)

- **Q: 为什么某些模型显示 ❌？**
  A: 可能是网络超时或 API Key 权限不足。检查 `.env` 中的 Key 是否正确，并确保网络能访问目标端点。
- **Q: 内存占用过高怎么办？**
  A: 每次重启程序会重置 `chat_memory` 缓存（但保留 `user_memory.json` 中的持久记忆）。长时间运行建议定期 `/reset` 清理过长的上下文窗口。
- **Q: 图片如何处理？**
  A: 上传的图片会被编码为 Base64 并通过 `image_url` 字段发送给支持视觉的模型；若需搜图，请使用自然语言描述意图（如“帮我找一张...的照片”），触发 `image_search` 工具。

---
*最后更新时间：2026 年 03 月 14 日*