Telegram 入群验证 Bot（OpenAI 出题）

这个机器人会在用户入群后自动禁言，并发送一题四选一验证题：

1. 新用户入群即禁言；
2. 使用 OpenAI 按主题生成 4 选 1 题目；
3. 用户答对后自动解除禁言；答错或超时则踢出，但允许再次加入；
4. 支持通过环境变量控制题目主题、模型、群组白名单。

功能契约（简版）

• 输入：Telegram 新入群事件 + 环境变量配置。
• 输出：群内一条带 4 个按钮的验证题消息。
• 成功：目标用户在超时前答对 -> 解除禁言。
• 失败：答错/超时 -> 踢出并立即解封（允许重新加入）。

环境变量

请参考 .env.example：

• TELEGRAM_BOT_TOKEN：必填，Bot Token。
• OPENAI_API_KEY：必填，OpenAI API Key。
• OPENAI_BASE_URL：可选，OpenAI 兼容接口地址（例如 https://api.openai.com/v1）。
• QUESTION_TOPIC：题目主题，默认 基础常识与群规。
• OPENAI_MODEL：OpenAI 模型，默认 gpt-4.1-mini。
• CHALLENGE_TIMEOUT_SECONDS：超时秒数，默认 90。
• GROUP_WHITELIST：群组 ID 白名单，逗号分隔；空表示全部群启用。
• LOG_LEVEL：日志级别，默认 INFO。

快速开始（Windows PowerShell）

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

填好 .env 后运行：

python run.py

使用 Docker Compose 启动

先准备环境变量文件：

Copy-Item .env.example .env

然后启动：

docker compose up -d --build

查看日志：

docker compose logs -f

停止并删除容器：

docker compose down

权限要求

将机器人设为群管理员，并至少给予：

• 限制成员（禁言/解除禁言）
• 封禁成员（踢出）

主要文件

• bot/main.py：事件处理与验证流程。
• bot/question_service.py：OpenAI 出题与解析。
• bot/config.py：环境变量配置。
• bot/challenge_store.py：内存态挑战管理。
• tests/：配置与题目解析的基础测试。

已覆盖的边界情况

• 非目标用户点击按钮会被拒绝；
• 题目生成失败时自动降级到本地兜底题；
• 同一用户重复入群会覆盖旧挑战并取消旧超时任务。

说明

• 当前挑战状态保存在内存中，重启 bot 会丢失未完成挑战。
• 如果你后续要多实例部署，建议接入 Redis 做共享状态。