基于 Telethon 和 Flask 构建的 Telegram 账号自动化管理工具，提供 Web 管理界面，支持多账号、关键词自动回复、定时发送、Forum 话题、白名单、发送队列可视化等功能。

• 多账号同时在线（每个账号独立 Session）
• 通过 Web 界面完成手机号 + 验证码 + 2FA 登录授权
• 账号在线状态实时显示
• 托管时间段：可为每个账号设置仅在指定时间段内（如 18:00～次日 08:00）执行自动回复，支持跨午夜区间；非托管时段触发时向「已保存的消息」发送通知

• 三种触发方式（每条规则独立选择）：
  • 引用回复（默认）：监听"别人引用了我的消息"的回复
  • @提及：有人在消息中 @我 时触发（不含引用回复）
  • 所有消息：检测收到的所有消息（建议配合白名单使用）
• 触发后自动发送预设回复内容
• 可指定适用账号（或对全部账号生效）
• 三种等待模式：
  • 立即回复：匹配后立刻发送
  • 解析等待时间：从触发消息中提取中文时间（如"1小时48秒"），到期后再发送，支持固定缓冲秒数或随机缓冲区间
  • 随机等待时间：忽略消息中的时间，在自定义 [最小, 最大] 秒区间内随机取值后发送
• 可启用 / 停用单条规则，不删除保留配置
• 多关键词匹配：可在一条规则中配置多个关键词，被检测消息必须同时包含所有关键词才触发回复

• 维护可复用的目标实体列表（用户/机器人/群组/超级群/频道）
• 输入目标 ID 后实时识别实体类型并自动填充名称
• 若目标是 Forum 频道，自动拉取全部话题列表并提供下拉选择
• 支持为目标绑定默认 Forum 话题 ID

• 多种调度方式：
  • 按间隔：每 N 分钟执行一次
  • Cron 表达式：精确控制执行时间（如 0 9 * * * 每天 09:00 UTC）
• 支持随机延迟：在触发后额外等待 [最小, 最大] 秒再发送
• 断点续时：程序重启后，间隔任务会根据上次实际发送时间（last_run_at）自动计算剩余等待时间并从断点继续，而非从头计时

• 专属页面展示所有等待中的任务（关键词回复 + 定时任务）
• 每条任务显示：类型徽章、账号、目标、消息预览、计划发送时间、倒计时进度条
• 进度条颜色随剩余时间动态变化（绿→橙→红）
• 每秒本地倒计时 + 每 5 秒从服务器同步，确保数据准确

• 入队时防冲突：新任务入队时使用贪心时间槽算法，自动检测同一目标 10 秒内的已有任务并向后推移，支持多米诺效应级联处理
• 执行时顺序保障：同一目标的到期消息按计划时间升序发送；若连续发送间隔不足 10 秒则自动 sleep 补齐
• 失败自动重试：发送异常时将该消息推迟 10 秒重新入队，记录错误日志，下次轮询自动重试
• 智能去重（可在系统设置中开关）：当不同关键词规则产生相同消息内容发往同一目标，且计划发送时间差距在阈值范围内时，只保留剩余时间最短的一条，自动删除其余重复项

• 配置白名单实体（用户/机器人/频道），只对名单中的发送者触发关键词回复
• 留空则对所有人生效

• 通过 Web 界面管理全局运行参数
• 智能去重开关：启用 / 关闭跨规则的消息内容去重
• 去重时间阈值：自定义计划时间差距范围（默认 60 分钟），超出阈值的重复消息各自保留

• 记录关键词匹配、自动回复、定时发送、错误等全部事件
• 可在 Web 界面中实时查看
• 支持按类型/关键词筛选、勾选批量删除、一键清空

git clone https://github.com/yourname/tgbot.git cd tgbot python -m venv .venv # Windows .venv\Scripts\activate # Linux / macOS source .venv/bin/activate pip install -r requirements.txt

cp .env.example .env

编辑 .env：

SECRET_KEY=换成你的随机字符串 DATABASE_URL=sqlite:///tgbot.db WEB_HOST=127.0.0.1 WEB_PORT=5000 DEBUG=False

python migrate.py

python main.py

服务启动后访问 http://127.0.0.1:5000。

docker compose up -d

1. 进入账号管理页面，点击「添加账号」
2. 填写：
   • 显示名称（便于识别）
   • 手机号（含国际区号，如 +8613800138000）
   • API ID 和 API Hash（在 my.telegram.org 获取）
3. 点击「添加」后跳转验证页面，填入收到的验证码，若有两步验证再填密码
4. 授权成功后账号状态变为「已连接」

1. 打开 my.telegram.org，用手机号登录
2. 进入 API development tools
3. 创建应用，获取 api_id 和 api_hash

1. 进入关键词回复页面，点击「添加规则」
2. 填写：
   • 适用账号：留空则全部账号生效
   • 关键词：在消息中检测此文本
   • 触发方式：「引用我的消息时」/「@提及我时」/「所有消息」
   • 等待模式：选择立即回复、解析时间（含缓冲）、或随机等待
   • 回复内容：触发后发送的消息
   • 发送目标 ID（可选）：填入数字 ID 后自动识别类型；Forum 频道自动弹出话题下拉菜单
3. 可随时启用 / 停用规则而无需删除

1. 进入定时任务页面
2. 选择账号，填入目标 ID（自动识别类型）
3. 选择调度类型：「按间隔」填写分钟数，「Cron 表达式」填写标准 5 字段 Cron
4. 若目标是 Forum 频道，选择话题
5. 可配置随机延迟区间（在触发后额外随机等待）
6. 填写消息内容后添加；程序重启后自动从断点续时

进入发送队列页面，实时查看所有待发任务（关键词回复 + 定时任务）：

• 类型：青色 = 关键词回复，紫色 = 定时任务
• 倒计时：精确到秒，带颜色进度条（≥2分钟绿色 / ≤2分钟橙色 / ≤30秒红色）
• 每 5 秒自动从服务器同步一次数据

在账号管理页面，每个账号可配置：

• 开启托管时间：仅在指定时间段内执行自动回复
• 开始时间 / 结束时间：支持跨午夜区间（如 18:00 ~ 08:00）
• 非托管时段触发的关键词会发送通知到「已保存的消息（Saved Messages）」

进入系统设置页面，可管理全局运行参数：

• 智能去重：开启后，当多条待发回复具有相同的（账号、目标群组、消息内容），且计划发送时间差距在阈值范围内时，只保留剩余时间最短的一条
• 时间阈值：默认 60 分钟，可调整为 1～1440 分钟；超出阈值的重复消息各自保留

tgbot/ ├── main.py # 入口：启动 Flask + Telethon 事件监听 ├── telegram_manager.py # Telethon 客户端管理、定时任务、待回复轮询、防冲突执行 ├── message_handler.py # 关键词检测、时间解析、贪心时间槽入队算法 ├── time_parser.py # 中文时间解析（小时/分钟/秒） ├── models.py # SQLAlchemy 数据模型 ├── config.py # Flask 配置读取 ├── migrate.py # 数据库结构迁移（幂等，列已存在自动跳过） ├── fetch_messages.py # 工具脚本：导出群组消息到本地文件 ├── requirements.txt ├── .env.example └── web/ ├── app.py # Flask 应用工厂，注册所有 Blueprint └── routes/ │ ├── accounts.py # 账号管理、授权、群组/话题发现 API │ ├── keywords.py # 关键词规则 CRUD │ ├── tasks.py # 定时任务 CRUD │ ├── targets.py # 目标实体列表管理 │ ├── queue.py # 发送队列页面 & JSON API │ ├── whitelist.py # 白名单管理 │ ├── logs.py # 日志查看、删除 │ └── settings.py # 系统设置 └── templates/ ├── base.html ├── accounts.html ├── account_auth.html ├── keywords.html ├── keyword_edit.html ├── tasks.html ├── task_edit.html ├── targets.html ├── queue.html # 发送队列实时倒计时页面 ├── whitelist.html ├── settings.html ├── logs.html └── index.html 

同一目标（account + group）短时间内有多条待发消息时，入队时自动调整计划时间，确保相邻两条间隔 ≥ 10 秒：

1. 查询同目标已有的未发送消息，按计划时间升序排列
2. 从期望时间 slot 开始，逐一与已有消息比较：若 |e - slot| < 10s，则 slot = e + 10s
3. 自动级联处理多米诺效应（连续冲突时 slot 持续后移直到无冲突）

执行时额外保障：到期消息按时间升序批量发送，同目标连续发送间隔不足 10 秒则 sleep 补齐；发送失败自动推迟 10 秒重试。

间隔型定时任务每次成功发送后将当前时间写入 last_run_at。程序重启时：

expected_next = last_run_at + interval if expected_next > now: start_date = expected_next # 从剩余时间继续，而非重新计时 

与现有的同规则去重（按 keyword_id 去重，同一规则 + 同一目标只保留一条）互补。智能去重按消息内容去重：不同关键词规则产生的相同消息也会合并。

去重维度：(account_id, group_id, message, topic_id)，去重条件：scheduled_at 差距 ≤ 阈值（默认 60 分钟）。按计划时间升序排列后，保留最早的一条（剩余等待时间最短），删除同簇其余条目。可在系统设置页面开关此功能。

当模型结构有新增列时，运行迁移脚本（幂等，列已存在时自动跳过）：

python migrate.py

• 本工具仅用于个人账号自动化，请遵守 Telegram 使用条款
• 频繁自动发送消息可能触发 Telegram 的频率限制或账号封禁风险，建议合理配置等待时间
• API ID 和 API Hash 属于敏感信息，请勿提交到公开仓库，.env 已在 .gitignore 中排除
• SQLite 数据库文件 instance/tgbot.db 包含 Session 字符串，请妥善保管

群组 ID 获取方法：将账号拉入群组后，在群组头像上右键 → 复制链接， 从链接末尾获取数字部分；超级群组需在前面加 -100。