{"repo": "apnn633/tgbot", "files": {"README.md": {"d456717b2490d0b22fff9656dc05a3427d40d504": {"t": 1785595450.7153215, "n": 6032, "h": "59c27ff124ff51f9", "c": "# 丛雨 (Murasame) Telegram Bot\n\n一个以丛雨（千恋＊万花）角色为人格的 Telegram 聊天机器人，支持文字、语音、图片、视频交互。\n\n## 功能特性\n\n- 🎭 **角色扮演** - 以丛雨的人格与用户对话，带有傲娇、古风口吻和颜文字\n- 🗣️ **语音交互** - 支持语音消息识别（Whisper/讯飞）与日语语音合成（OpenAI TTS/InworldTTS）\n- 🖼️ **图片理解** - 多模态 AI 分析图片内容，支持多种视觉模型\n- 🎬 **视频理解** - 多模态 AI 分析视频内容\n- 💬 **对话管理** - 支持多对话切换、自动命名、重命名、删除\n- 🔐 **用户认证** - 配对码授权机制，支持白名单和动态授权\n- 🌐 **双模式运行** - 支持 Polling（开发）和 Webhook（生产）模式\n\n## 环境要求\n\n- Python 3.11+\n- [uv](https://docs.astral.sh/uv/) 包管理器\n- FFmpeg（讯飞 STT 或音频转码时需要）\n\n## 安装\n\n```bash\n# 克隆仓库\ngit clone https://github.com/apnn633/tgbot.git\ncd tgbot\n\n# 安装依赖\nuv sync\n\n# 复制配置文件\ncp .env.example .env\n# 编辑 .env 填入你的 API 密钥\n```\n\n### FFmpeg 安装\n\n讯飞语音识别需要 FFmpeg 进行音频转码：\n\n```bash\n# Ubuntu/Debian\nsudo apt install ffmpeg\n\n# macOS\nbrew install ffmpeg\n\n# Windows (使用 Chocolatey)\nchoco install ffmpeg\n```\n\n## 配置\n\n编辑 `.env` 文件，配置以下必要项：\n\n### 最小配置\n\n```env\n# Telegram Bot Token (必需)\nTELEGRAM_BOT_TOKEN=your_bot_token\n\n# 对话 API (必需 - DeepSeek / OpenAI / GLM 兼容)\nCHAT_API_KEY=your_api_key\nCHAT_BASE_URL=https://api.openai.com/v1\nCHAT_MODEL=gpt-4o-mini\n```\n\n### 完整配置示例\n\n```env\n# === Telegram Bot ===\nTELEGRAM_BOT_TOKEN=your_bot_token_here\n\n# === 认证 ===\nALLOWED_USER_IDS=12345678,87654321\nPAIRING_CODE_TTL=300\n\n# === 对话 API ===\nCHAT_API_KEY=your_chat_api_key_here\nCHAT_BASE_URL=https://open.bigmodel.cn/api/paas/v4\nCHAT_MODEL=glm-4.6\n\n# === 多模态 API ===\nMULTIMODAL_MODE=auto\nMULTIMODAL_API_KEY=your_api_key\nMULTIMODAL_BASE_URL=https://cloud.infini-ai.com/maas/v1\nMULTIMODAL_MODEL=qwen3-vl-plus\n\n# === STT (语音识别) ===\nSTT_PROVIDER=openai\nSTT_API_KEY=your_api_key\nSTT_BASE_URL=https://api.openai.com/v1\nSTT_MODEL=whisper-1\n\n# === TTS (语音合成) ===\nTTS_PROVIDER=openai\nTTS_API_KEY=your_api_key\nTTS_BASE_URL=https://api.openai.com/v1\nTTS_MODEL=tts-1\nTTS_VOICE=shimmer\nTTS_OUTPUT_MODE=llm_output\n```\n\n### 配置说明\n\n#### 多模态模式\n\n`MULTIMODAL_MODE` 支持四种模式：\n\n| 模式 | 说明 | 要求 |\n|------|------|------|\n| `auto` | 自动选择（推荐） | 两个 API 都配置时用 two_step |\n| `two_step` | 多模态分析 → 对话生成 | 需同时配置两个 API |\n| `direct` | 多模态 AI 直接回复 | 只需多模态 API |\n| `disabled` | 禁用图片/视频 | 只需对话 API |\n\n#### 视觉模型选择\n\n| 模型系列 | 支持传输 | 图片限制 | 视频限制 |\n|----------|----------|----------|----------|\n| Qwen-VL (qwen3-vl-plus 等) | 仅 Base64 | 5MB | 5MB |\n| GLM (glm-4.5v, glm-4.6v) | URL + Base64 | 5MB | 200MB |\n\n> 如果使用 GLM 模型时 URL 访问失败，Bot 会自动回退到 Base64 模式，并可通过 `/fix` 命令永久启用 Base64 模式。\n\n#### 语音配置\n\n**STT (语音识别):**\n\n| 服务 | 说明 | 依赖 |\n|------|------|------|\n| OpenAI Whisper（默认） | 多语言识别 | 无额外依赖 |\n| 讯飞语音 | 中文/英文/方言 | FFmpeg |\n\n**TTS (语音合成):**\n\n| 服务 | 说明 | 配置 |\n|------|------|------|\n| OpenAI TTS（默认） | 多语言语音合成 | `TTS_API_KEY`, `TTS_VOICE` |\n| InworldTTS | 日语语音克隆 | `INWORLD_API_KEY`, `INWORLD_VOICE_ID` |\n\n**TTS 输出模式:**\n\n| 模式 | 说明 |\n|------|------|\n| `llm_output`（推荐） | AI 直接输出 JSON `{\"zh\": \"中文\", \"ja\": \"日语\"}`，效率高 |\n| `translate` | 先生成中文，再翻译成日语，兼容性好 |\n\n#### 认证配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `ALLOWED_USER_IDS` | 白名单用户 ID（逗号分隔），留空则所有人需要配对码认证 |\n| `PAIRING_CODE_TTL` | 配对码有效期（秒），默认 300 |\n\n## 运行\n\n### 使用 uv 直接运行\n\n```bash\n# 默认模式（自动选择 polling/webhook）\nuv run python main.py\n\n# Polling 模式（开发推荐）\nuv run python main.py --polling\n\n# Webhook 模式（生产推荐）\nuv run python main.py --webhook\n```\n\n### 使用启动脚本\n\n```bash\n# Polling 模式\n./run.sh --polling\n\n# Webhook 模式（默认）\n./run.sh\n```\n\n### 命令行参数\n\n| 参数 | 说明 |\n|------|------|\n| `--polling` | 使用 Polling 模式运行 |\n| `--webhook` | 使用 Webhook 模式运行 |\n| `--debug` | 调试模式（显示所有日志） |\n| `--no-pretty` | 禁用彩色日志输出 |\n| `-o, --output FILE` | 日志输出到文件 |\n| `-q, --quiet` | 静默模式（无控制台输出） |\n\n### 后台运行\n\n```bash\n# 后台运行，日志输出到文件\nuv run python main.py -o bot.log -q &\n\n# 使用 nohup\nnohup uv run python main.py -o bot.log -q &\n\n# 使用 systemd（推荐生产环境）\n# 创建 /etc/systemd/system/tgbot.service\n```\n\n## 用户管理\n\n使用 `tgbot-admin` 命令行工具管理用户：\n\n```bash\n# 使用配对码授权用户\nuv run tgbot-admin pair <配对码>\n\n# 列出已授权用户\nuv run tgbot-admin list\n\n# 列出待处理配对请求\nuv run tgbot-admin pending\n\n# 撤销用户授权\nuv run tgbot-admin revoke <用户ID>\n\n# 清理过期配对码\nuv run tgbot-admin cleanup\n\n# 显示白名单\nuv run tgbot-admin whitelist\n```\n\n## 命令列表\n\n| 命令 | 说明 |\n|------|------|\n| `/start` | 开始使用/获取配对码 |\n| `/help` | 查看帮助 |\n| `/new [名称]` | 新建对话 |\n| `/list` | 查看对话列表 |\n| `/det <编号>` | 删除指定对话（支持多个，空格分隔） |\n| `/delall` | 删除所有对话 |\n| `/clear` | 清空当前对话 |\n| `/rename <编号> <名称>` | 重命名对话（省略编号则重命名当前对话） |\n| `/voice` | 切换语音模式 |\n| `/reset` | 恢复出厂设置 |\n| `/fix` | 修复图片 URL 访问问题（自动启用 Base64 模式） |\n\n## 项目结构\n\n```\ntgbot/\n├── main.py               # 入口文件\n├── pyproject.toml         # 项目配置\n├── run.sh                 # 启动脚本\n├── .env.example           # 配置模板\n└── src/tgbot/\n    ├── __init__.py        # 包初始化\n    ├── bot.py             # Bot 应用创建与运行\n    ├── cli.py             # 管理命令行工具\n    ├── config.py          # 配置管理\n    ├── constants.py       # 共享常量\n    ├── database.py        # SQLite 数据库操作\n    ├── handlers.py        # Telegram 消息处理\n    ├── llm.py             # LLM API 集成\n    ├── prompts.py         # AI 提示词\n    ├── auth.py            # 用户认证管理\n    ├── utils.py           # 工具函数\n    └── voice.py           # 语音处理（STT/TTS）\n```\n\n## 常见问题\n\n### Bot 启动失败\n\n| 问题 | 解决方案 |\n|------|----------|\n| `配置缺失: TELEGRAM_BOT_TOKEN` | 在 `.env` 中设置 Bot Token |\n| `配置缺失: CHAT_API_KEY` | 在 `.env` 中设置对话 API 密钥 |\n| `Connection error` | 检查网络连接和 API 地址是否正确 |\n\n### 图片/视频无法识别\n\n1. 确认已配置 `MULTIMODAL_API_KEY`\n2. 检查 `MULTIMODAL_MODE` 是否为 `disabled`\n3. 如果使用 GLM 模型遇到 URL 访问失败，发送 `/fix` 命令或设置 `FORCE_BASE64_IMAGE=true`\n\n### 语音功能不工作\n\n1. **语音识别失败**：检查 `STT_API_KEY` 是否正确配置\n2. **讯飞 STT 失败**：确认已安装 FFmpeg（`ffmpeg -version`）\n3. **语音合成失败**：检查 `TTS_API_KEY` 是否正确配置\n4. **InworldTTS 失败**：确认 `INWORLD_API_KEY` 和 `INWORLD_VOICE_ID` 都已设置\n\n### Webhook 模式无法接收消息\n\n1. 确认 `WEBHOOK_URL` 可从外网访问\n2. 确认 `WEBHOOK_PORT` 未被防火墙阻止\n3. 使用 Cloudflare Tunnel 等工具暴露本地端口：\n   ```bash\n   cloudflared tunnel --url http://localhost:8443\n   ```\n\n### 数据库相关\n\n- 数据库文件位于 `.tgbot_data/tgbot.db`\n- 删除数据库文件会丢失所有对话和授权数据\n- 数据库使用 SQLite，无需额外安装\n\n## 贡献指南\n\n1. Fork 本仓库\n2. 创建功能分支：`git checkout -b feature/your-feature`\n3. 提交更改：`git commit -m \"Add your feature\"`\n4. 推送分支：`git push origin feature/your-feature`\n5. 创建 Pull Request\n\n### 代码规范\n\n- 使用 [Ruff](https://docs.astral.sh/ruff/) 进行代码检查和格式化\n- 行宽限制：100 字符\n- Python 版本：3.11+\n- 运行检查：`uv run ruff check src/`\n\n## 许可证\n\nMIT License\n"}}}}