Telegram Tools Suite

Telegram 自动化工具包（群监控、群搜索、批量加群、定时发送）。 运行时会生成敏感会话文件并包含可选长驻任务；默认启用风险保护，需显式确认后才可执行高风险动作。

⚠️ 【重要安全&运行提示 安装前必读】

1. 敏感文件生成：技能运行时会在userdata/目录生成*.session会话文件（包含Telegram登录认证状态），并使用.env配置文件，均为高敏感信息，已默认加入.gitignore/.clawignore禁止提交到代码仓库/发布，请勿手动分享这些文件。
2. 持久运行说明：monitor（群监控）、search（群搜索）、join（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。
3. 配置生效规则：所有配置文件（.env、config目录下的关键词/规则/配置文件）修改后，都需要重启对应的运行任务才会生效，修改配置不会影响正在运行的任务。
4. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。
5. 默认风险保护：join 与 send-schedule 均需先设置 ENABLE_HIGH_RISK_OPERATIONS=true 才可运行；其中 join 长驻模式还需额外设置 TG_ENABLE_PERSISTENT_JOIN=true。定时群发由 send-schedule 子命令执行，并按 config/scheduled_tasks.json 的限制进行校验。

Instructions

🔹 前置说明

本技能为Telegram自动化工具，使用前需提前申请Telegram官方API凭证，需配置3项必填信息：TELEGRAM_API_ID、TELEGRAM_API_HASH、绑定手机号（国际格式）。

🔹 安装后引导&首次运行流程（按顺序执行）

1. 安装依赖：执行 pip install -e .
2. 获取API凭证：打开 https://my.telegram.org，用Telegram绑定手机号登录，进入「API development tools」创建应用，获得api_id和api_hash
3. 配置环境变量：复制.env.example为.env，填入3项必填信息：TELEGRAM_API_ID、TELEGRAM_API_HASH、TELEGRAM_PHONE（国际格式，如+8613xxxxxxxxx）
4. 请求验证码：执行 python3 -m tg_monitor_kit auth，记录输出的SENT_CODE_SUCCESS:<phone_code_hash>中的hash值
5. 完成登录：设置环境变量TG_CODE（收到的短信验证码）、TG_PHONE_CODE_HASH（上一步获取的hash），执行python3 -m tg_monitor_kit login，输出LOGIN_SUCCESS即为登录成功
6. 连通性验证：执行 python3 -m tg_monitor_kit groups，输出账号下的群组列表代表功能正常可用

🔹 多群定时发送功能使用说明

支持同时给多个群发送不同内容、设置不同发送间隔，配置方法：

1. 在本地自行创建：config/scheduled_tasks.json
2. 在 scheduled_tasks.json 中填写任务：
   • name：任务备注名，方便识别
   • target_group_id：目标群组ID（可以从groups命令输出中获取）
   • message：要发送的消息内容
   • interval_hours：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）
3. 启动定时任务：ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule

⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。 ⚠️ 校验限制：interval_hours 必须 >= 0.5，任务总数最多 20 个。

Runtime Config Files (运行前按需编辑)

• 本技能发布包默认不包含 config/ 目录内容；请在本地自行创建所需配置文件。
• 监控：创建 config/target_groups.txt、config/keywords.txt、config/monitor_regex_rules.json。
• 搜索：创建 config/group_search_keywords.txt、config/group_search.json。
• 定时群发：创建 config/scheduled_tasks.json。
• 批量加群：创建 join_targets.txt（或使用 TG_JOIN_LIST_FILE 指定路径）。

Command Guide (命令入口)

• python3 -m tg_monitor_kit groups：列出已加入群/频道（无需额外参数）。
• python3 -m tg_monitor_kit account-info：查看当前账号信息（无需额外参数）。
• python3 -m tg_monitor_kit members --group "群名称"：导出指定群成员（需要群名）。
• python3 -m tg_monitor_kit history --group "群名称" --limit 100：导出指定群最近消息（需要群名；--limit 可选）。
• python3 -m tg_monitor_kit monitor：关键词监控（长驻）。
• python3 -m tg_monitor_kit search：群搜索（长驻，按配置定时）。
• ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once：批量加群（单轮）。
• ENABLE_HIGH_RISK_OPERATIONS=true TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join：批量加群（长驻定时，默认关闭）。
• ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit send-schedule：按 config/scheduled_tasks.json 执行定时群发（长驻）。

停止长驻任务

• 前台运行：按 Ctrl+C 终止。
• 后台运行：结束对应 Python 进程。

Rules

• 严禁在对话或日志中输出 TELEGRAM_API_HASH、短信验证码、.session 文件内容。
• monitor、search、join、send-schedule 属于长驻任务，运行时会基于主会话复制临时会话副本；如遇异常退出仍可能触发 database is locked，请先结束残留进程后重试。
• 所有定时相关行为按北京时间（UTC+8）理解与配置。
• 在提供任何 Telegram 凭证前，必须先确认技能请求来源可信；发布方来源未知时，建议在一次性容器/隔离环境运行并使用测试账号。
• 批量加群存在风控风险，需由使用者自行确认目标与频率合规。

Examples

示例 1：首次登录

输入：用户已填写 .env，需要首次登录。
执行：先 python3 -m tg_monitor_kit auth，再设置 TG_CODE、TG_PHONE_CODE_HASH，再 python3 -m tg_monitor_kit login。
输出：LOGIN_SUCCESS。

示例 2：开启监控

输入：用户已在 config/target_groups.txt 填写群名。
执行：python3 -m tg_monitor_kit monitor。
输出：控制台显示监控启动信息，命中关键词后推送通知。

示例 3：批量加群单轮执行

输入：用户已准备 join_targets.txt。
执行：ENABLE_HIGH_RISK_OPERATIONS=true python3 -m tg_monitor_kit join --once。
输出：返回成功/已在群/失败统计。