therayyanawaz/TeleUserBot

# ✨ TeleUserBot TeleUserBot 将杂乱无章的 Telegram 频道转化为更纯净、更敏锐、更有用的情报流。 它通过 **Telethon** 运行在你的**个人 Telegram 账户**上，实时监听频道和文件夹动态，过滤掉微弱或重复的帖子，快速推送紧急动态，将其他所有内容汇总成精炼的摘要，并允许你针对近期的报道进行私密提问。 如果你想要一个更像是私人监控台而不是简单转发机器人的工具，这个项目正是为此而构建的。💎 ## 🌍 为什么会有 TeleUserBot 大多数 Telegram 监控设置都会在相同的地方出问题： - 🔁 同一动态到处被重复转发 - 🚨 微弱信号被包装成突发新闻 - 🧱 原始频道信息流在规模化阅读时非常困难 - 🔎 在 Telegram 内部搜索近期的报道极其痛苦 - 🧠 纯媒体帖子通常包含重要的文本，但从未被提取出来 TeleUserBot 通过结合以下功能来解决这些问题： - 实时 Telegram 信息接收 - 多层重复抑制 - 严重程度感知路由 - 突发事件连贯性追踪 - 每小时和每日摘要生成 - 针对纯媒体帖子的 OCR 翻译 - 支持优先搜索 Telegram 证据的私密查询模式 - 在 Telegram 证据不足时可选的可信网络回退 - Telegram HTML 输出及可选的高级 Emoji 渲染 ## 🧠 核心功能 ### ⚡ 实时接收 - 通过 `FOLDER_INVITE_LINK` 监听共享的 Telegram 文件夹邀请 - 通过 `EXTRA_SOURCES` 手动添加信息源 - 作为真正的 **userbot** 运行，而不仅仅是 bot-token 监听器 - 将输出发送到指定用户目标或通过 Telegram Bot API 投递 ### 🛡️ 强大的防重机制 - 文本指纹和混合重复度评分 - 针对转发图片和相册的媒体签名检查 - 针对同源或重新压缩媒体的视觉媒体哈希 - 基于 SQLite 的记忆存储，使防重机制在重启后依然有效 ### 🚨 突发新闻路由 - 高严重性帖子可以立即发出 - 中低优先级更新可以排队进入摘要 - 突发跟进报道可以绑定到同一不断发展的新闻事件中 - 通过 `BREAKING_STYLE_MODE` 实现可选的主观突发风格 ### 📰 摘要发布 - 30分钟滚动摘要模式 - 24小时每日摘要模式 - 基于 SQLite 的队列/归档存储，具备重启安全的窗口声明机制 - 当单条 Telegram 消息不满足长度时的多消息摘要投递 - 可选的最新摘要帖子置顶轮换 ### 🔎 私密查询助手 - 在 **Saved Messages (收藏夹)** 中提问 - 或者使用**与你自己 Bot 的私密对话** - 优先搜索近期的 Telegram 证据 - 仅在配置后且必要时回退到可信的网络报道 ### 🖼️ 针对纯媒体帖子的 OCR - 为没有配文的图片进行 OCR - 为纯视频提取首帧进行 OCR - 仅在检测到非英文文本时进行翻译 - 不凭空捏造视觉描述，不伪造配文 ### 🎨 简洁的 Telegram 输出 - Telegram HTML 格式化 - 可选的高级 Emoji 映射 - 当源帖子属于同一消息流时保持回复线索的连续性 - 为提升信息流可读性而非频道垃圾信息进行的投递调优 ## 🏗️ 项目结构 ``` TeleUserBot/ ├── main.py ├── config.py ├── auth.py ├── ai_filter.py ├── breaking_story.py ├── db.py ├── news_signals.py ├── news_taxonomy.py ├── severity_classifier.py ├── utils.py ├── web_server.py ├── tests/ ├── install-all.ps1 ├── install-all-ubuntu.sh ├── .env.example └── README.md ``` 运行时状态存储在仓库外的以下路径中： ``` ~/.tg_userbot/ ``` 该目录存储运行时元数据，例如： - SQLite 状态 - 认证负载和缓存 - 日志 - 投递和流水线元数据 ### 运行时日志 - `~/.tg_userbot/runtime.log` 以 `DEBUG` 级别记录完整的运行时活动，作为一份可读的运维记录，包括第三方库日志。 - `~/.tg_userbot/errors.log` 以相同的可读格式保留仅含错误的日志流，以便更快地进行分类排查。 - 每次全新执行 `python main.py` 启动时，这两个日志文件都会被清空。 - 在单次运行期间，每个文件在达到 `10 MB` 时会进行轮换，最多保留 `5` 个文件。 - 启动、关闭、worker 生命周期以及低内存状态转换会发出结构化的 `memory_snapshot` 日志事件，其中包含进程内存使用字段。 ## 🧭 工作原理 1. TeleUserBot 连接到你的 Telegram 账号。 2. 从你的共享文件夹和附加频道中解析信息源。 3. 收到的帖子会经过重复检测、OCR 和严重性逻辑处理。 4. 高价值更新可以被立即投递。 5. 其他所有内容会被组织到摘要工作流和可搜索的历史记录中。 ## ✅ 环境要求 - Python **3.11+** - 建议使用最新发布的 Python 3 版本 - 从 `https://my.telegram.org` 获取的 Telegram `api_id` 和 `api_hash` - 用于 Telethon 登录的 Telegram 账号 - 用于 Bot API 投递或 Bot 私信查询模式的可选 Bot Token - 如果你需要提取图像/视频文本，需要可选的 OCR 系统安装包 ## 🚀 快速开始 ### 1. 克隆仓库 ``` git clone https://github.com/therayyanawaz/TeleUserBot.git cd TeleUserBot ``` ### 2. 创建虚拟环境 ``` python3 -m venv .venv source .venv/bin/activate ``` Windows PowerShell: ``` py -3 -m venv .venv .\.venv\Scripts\Activate.ps1 ``` 上面的示例有意使用了默认的 Python 3 启动器行为，以便你的分支可以采用最新安装的 Python 3 版本，同时仍要求版本为 **3.11 或更高**。 ### 3. 安装依赖 ``` python -m pip install --upgrade pip setuptools wheel pip install -r requirements.txt ``` ### 4. 安装可选附加组件 ``` pip install -r requirements.optional.txt ``` 如果你明确选择使用 OCR 辅助工具和 `sentence-transformers` 支持等较重型的功能，可选附加组件可以启用它们。 ### 5. 复制环境变量模板 ``` cp .env.example .env ``` Windows PowerShell: ``` Copy-Item .env.example .env ``` ### 6. 启动 Bot ``` python main.py ``` ## ⚙️ 一键安装脚本 如果你想要更快捷的途径： ### Windows ``` .\install-all.ps1 ``` 此脚本将： - 选择最新安装的 Python 3.11+ 解释器，或者在需要时安装最新可用的 Python 3 包 - 创建 `.venv` - 安装 `requirements.txt` 和 `requirements.optional.txt` - 安装 FFmpeg - 安装 Tesseract OCR - 预热 `sentence-transformers` 缓存 ### Ubuntu ``` bash install-all-ubuntu.sh ``` 此脚本将： - 选择最新安装的 Python 3.11+ 解释器，或者在需要时安装最新可用的 `python3.x` 包 - 安装 FFmpeg 和 Tesseract - 安装多语言 OCR 语言包 - 创建 `.venv` - 安装所有 Python 依赖 - 预热 `sentence-transformers` 缓存 ## 🔐 最低配置 一个精简的初始 `.env` 文件如下所示： ``` TELEGRAM_API_ID=123456 TELEGRAM_API_HASH="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" FOLDER_INVITE_LINK="https://t.me/addlist/xxxxxxxxxx" # EXTRA_SOURCES=["@channel1","https://t.me/+privateInviteHash"] # 选择一种目标模式 DESTINATION="@your_private_channel_or_chat" # 或 # BOT_DESTINATION_TOKEN="123456:ABCDEF..." # BOT_DESTINATION_CHAT_ID="7777826640" ``` 重要行为： - 如果同时设置了 `DESTINATION` 和 bot-destination 的值，**Bot 目标模式将优先** - 如果你更喜欢使用 `EXTRA_SOURCES`，`FOLDER_INVITE_LINK` 是可选的 - `BOT_DESTINATION_CHAT_ID` 通常应该是你的投递聊天群组，而不是你的查询私信 ## 🤖 OpenAI / Codex 认证 本项目使用 **Codex 风格的 OAuth 流程**，而不是普通的 API 密钥设置。 针对 ChatGPT 账户 Codex 认证推荐的低使用量模型： ``` CODEX_MODEL="gpt-5.1-codex-mini" ``` ### 托管或无头模式 推荐用于 Replit、服务器和长时间运行的部署： ``` OPENAI_AUTH_ENV_ONLY=true TG_USERBOT_AUTH_JSON_B64="..." ``` 将认证引导至环境变量形式： ``` python auth.py bootstrap-env ``` 或者将认证值写入 `.env`： ``` python auth.py setup-env ``` ### 本地交互模式 ``` OPENAI_AUTH_ENV_ONLY=false ``` 然后通过浏览器 OAuth 登录： ``` python auth.py login ``` 本地交互式启动可以自动修复缺失或过期的认证，并在同一进程中继续启动。 ### 有用的认证命令 ``` python auth.py login python auth.py login --env-file .env python auth.py status python auth.py logout python auth.py logout --env-file .env ``` ## 🧩 操作模式 ### 1. 信息流 / 警报模式 每条收到的 Telegram 帖子都会被评估，并且可能会被： - 作为重复内容跳过 - 作为快速突发警报路由 - 加入到摘要中 - 附加到现有的新闻事件线索中 ### 2. 摘要模式 TeleUserBot 不是原样转发每一条帖子，而是可以发布： - 30分钟滚动摘要 - 每日摘要 摘要模式专为那些希望获得高信号密度而不受原始信息流混乱干扰的人而设计。当 `DIGEST_MODE=true` 时，受监控的更新将被排队存入持久化的 SQLite 存储中，并仅通过摘要进行投递。 ### 3. 查询模式 提出自然语言问题，例如： - `latest tehran news` - `what happened in last 24 hours` - `recent beirut updates` - `who died recently in iran` 助手会首先检查近期的 Telegram 证据，并且只有在已配置且 Telegram 结果过于薄弱时，才会使用可信的网络回退。 ## 📰 摘要配置 推荐的基准配置： ``` DIGEST_MODE=true DIGEST_INTERVAL_MINUTES=30 DIGEST_DAILY_TIMES=["00:00"] DIGEST_DAILY_WINDOW_HOURS=24 DIGEST_MAX_POSTS=80 DIGEST_QUEUE_CLEAR_INTERVAL_MINUTES=0 OUTPUT_LANGUAGE="English" ``` 备注： - 滚动摘要与时间时钟的 `:00` 和 `:30` 对齐 - 摘要窗口是从 SQLite 中声明的，而不仅仅保留在内存中 - 如果摘要超出了 Telegram 消息长度限制，它将作为连续的 `Part 1/N`、`Part 2/N` ... 消息进行投递 - 滚动和每日摘要强制输出为英文 可选的摘要置顶轮换： ``` DIGEST_PIN_HOURLY=false DIGEST_PIN_DAILY=false ``` 启用后： - 该类型的最新摘要将被置顶 - 该类型之前置顶的摘要将被取消置顶 - 置顶失败不会阻止摘要的投递 ## 🧪 重复抑制 防重机制分为多层运行。 ### 文本级别 - 规范化的文本指纹识别 - 混合相似度评分 - 近期重复记忆 ### 媒体级别 - 同源图像检测 - 重新压缩媒体检测 - 相册签名追踪 - SQLite 中的持久化去重记忆 ### 事件线索连续性 当后续帖子作为回复到达源频道时，Bot 可以在目标信息流中保留这种关联关系。 ## 🚨 严重性路由 高级流程： - `high` → 立即警报 - `medium` / `low` → 摘要队列 突发语气可以通过以下配置调整： ``` BREAKING_STYLE_MODE=unhinged ``` 模式： - `unhinged` 提供更具冲击力的突发格式，并且仅在新闻事件关联足够强时才添加上下文 - `classic` 恢复更为克制的排版 ## 🖼️ 针对纯媒体帖子的 OCR 翻译 OCR 的行为是有意保持保守的。 - 带有配文的媒体保留原始 Telegram 配文 - 只有当 OCR 发现有意义的非英文文本并且翻译成功时，纯图片帖子才会获得配文 - 纯视频帖子使用首帧 OCR - 英文 OCR 文本会被忽略 - OCR 失败不会添加任何内容 示例配置： ``` MEDIA_TEXT_OCR_ENABLED=true MEDIA_TEXT_OCR_VIDEO_ENABLED=true MEDIA_TEXT_OCR_MIN_CHARS=12 MEDIA_TEXT_OCR_MAX_CHARS=1600 MEDIA_TEXT_OCR_VIDEO_MAX_MB=25 MEDIA_TEXT_OCR_LANGS=eng+ara+fas+urd+rus ``` 如果你想在 Linux 上使用 OCR： ``` sudo apt-get update sudo apt-get install -y tesseract-ocr ffmpeg sudo apt-get install -y tesseract-ocr-ara tesseract-ocr-fas tesseract-ocr-urd tesseract-ocr-rus ``` ## 🔎 查询助手规则 允许的上下文： - **Saved Messages (收藏夹)** - **与你自己 Bot 账号的私密对话** 不允许： - 群组 - 频道 - 与其他用户的任意私密对话 这种限制是有意为之的，旨在保持查询工作流的私密性和可预测性。 ## 🌐 查询网络回退 当 Telegram 证据不够充分时，Bot 可以搜索可信的新闻网站： ``` QUERY_WEB_FALLBACK_ENABLED=true QUERY_WEB_MIN_TELEGRAM_RESULTS=3 QUERY_WEB_MAX_RESULTS=12 QUERY_WEB_MAX_HOURS_BACK=24 QUERY_WEB_REQUIRE_RECENT=true QUERY_WEB_REQUIRE_MIN_SOURCES=2 QUERY_WEB_ALLOWED_DOMAINS=["reuters.com","apnews.com","bbc.com","aljazeera.com","cnn.com","nytimes.com","washingtonpost.com","bloomberg.com","ft.com","theguardian.com","dw.com","france24.com","aa.com.tr","npr.org"] ``` 备注： - Telegram 证据始终是主要来源 - 网络回退仅在需要时使用 - 风险较高的问题会被更保守地处理 ## 🧵 输出和投递细节 TeleUserBot 可以通过以下方式投递： - Telegram HTML 格式化 - 可选的高级 Emoji 支持 - 感知来源的回复连续性 - 摘要优先的可读性 `.env.example` 中有用的渲染标志： ``` ENABLE_HTML_FORMATTING=true ENABLE_PREMIUM_EMOJI=true PREMIUM_EMOJI_MAP_FILE="nezami_emoji_map.json" ``` ## 🩺 健康检查与托管 对于 Replit 或有正常运行时间监控的部署： ``` ENABLE_WEB_SERVER=true WEB_SERVER_HOST="0.0.0.0" WEB_SERVER_PORT=8080 HOLD_ON_STARTUP_ERROR=true OPENAI_AUTH_ENV_ONLY=true TG_USERBOT_AUTH_JSON_B64="..." ``` 健康端点： - `/` 渲染完整的运维仪表盘 - `/status` 为浏览器中托管状态检查渲染相同的仪表盘视图 - `/health` 渲染简化的健康页面，健康时返回 `200`，降级时返回 `503` 建议的托管命令： - 安装：`pip install -r requirements.txt` - 可选附加项：`pip install -r requirements.optional.txt` - 运行：`python main.py` ## 🛠️ 运行 Bot 单一入口： ``` python main.py ``` 启动流程： 1. 验证配置 2. 确保只激活一个实例 3. 初始化运行时数据库和缓存 4. 当交互模式检测到过期或缺失的认证时，在线修复认证 5. 连接到你的 Telegram 会话 6. 解析信息源 7 启动信息流、摘要、查询以及可选的 Web 服务器流水线 ## 🧪 测试 代码仓库包含了主要流水线部分的测试覆盖。 运行： ``` pytest ``` 或者先安装开发依赖： ``` pip install -r requirements.dev.txt pytest ``` ## 💬 运维命令 默认的摘要状态命令： ``` /digest_status ``` 此命令会报告队列状态、调度器状态和运行时健康详情。 ## 🧯 故障排除 ### `sentence-transformers 不可用` 如果你有意在不支持 Hugging Face 的情况下运行，这不是问题。 仅在你需要该后端时安装可选附加项： ``` pip install -r requirements.optional.txt ``` ### `数据库已锁定` 可能有另一个进程正在使用相同的 Telethon 会话或 SQLite 数据库。 解决方法： - 停止重复的进程 - 只保留一个活动实例 ### 在服务器上重复出现 OAuth 提示 使用仅环境变量认证： ``` OPENAI_AUTH_ENV_ONLY=true TG_USERBOT_AUTH_JSON_B64="..." ``` ### `PhoneNumberInvalidError` 请使用带国家代码的完整 E.164 格式。 示例： ``` +15551234567 ``` ### 纯媒体帖子没有有用的配文 检查： - 是否启用了 OCR - 是否安装了 Tesseract - 是否安装了语言包 - 媒体中是否确实包含可读的非英文文本 ### 查询回复看起来有误或缺失 请将查询模式限制在： - Saved Messages (收藏夹) - 你自己的 Bot 私信 ### Bot API 上传超时或连接重置 Bot 会在瞬时投递错误时重试一次。如果持续失败，请检查： - 网络质量 - VPS 稳定性 - 代理或 VPN 路径 - 超大媒体文件的上传 ## 🔒 安全 切勿提交： - `.env` - `userbot.session*` - `~/.tg_userbot/*` 密钥 - 导出的认证负载 - 私人 Token 导出内容 如果任何敏感信息泄露，请立即轮换更换。 ## 📦 升级工作流 ``` git pull source .venv/bin/activate pip install -r requirements.txt --upgrade pip install -r requirements.optional.txt --upgrade python main.py ``` ## 🧩 实际部署建议 通常最佳结果来自于角色分离： - 一个聊天群组用于**信息流投递** - 一个私密的 Bot 私信或 Saved Messages 用于**查询** 将两者混合到一个高吞吐量的聊天中也可以，但体验会变得更加嘈杂且难以控制。 ## ⚠️ 负责任地使用 本项目运行在真实的 Telegram 账户上，可能会处理来自众多来源的内容。请负责任地使用，遵守 Telegram 规则，尊重当地法律，并谨慎处理受监控的内容。 ## 💫 总结 TeleUserBot 专为那些希望 Telegram 监控变得更敏锐、更从容、更智能的运维人员而设计： - 更少的重复 - 更好的紧急程度控制 - 更纯净的摘要 - 更强大的私密搜索 - 更实用的媒体处理 如果你目前的设置感觉就像穿着风衣的混乱，那么这就是你要的升级版。 ✨

标签：API集成, DNS解析, ESC4, OCR, OSINT, Python, SQLite, Telegram, Telethon, Userbot, 严重性路由, 信息去重, 信息过滤, 可观测性, 威胁情报, 媒体处理, 安全资讯, 实时监听, 开发者工具, 开源项目, 情报分析与处理, 情报工作流, 情报收集, 摘要生成, 新闻聚合, 无后门, 漏洞研究, 私人监控台, 网络安全, 自动化机器人, 自然语言查询, 逆向工具, 重复数据删除, 隐私保护, 频道监听