Telegram Tools Suite

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

Security Scan

This package is a coherent Telegram automation toolkit: it legitimately requires Telegram API credentials, creates local session files, and provides long-running monitor/search/join features with explicit risk guards — use caution because the credentials and session files are highly sensitive.

Purpose & Capability

Name/description, SKILL.md, and the included Python modules are consistent: the code implements monitoring, group search, batch join and scheduled send using Telethon and requires TELEGRAM_API_ID/TELEGRAM_API_HASH/TELEGRAM_PHONE as declared. No unrelated credentials or unusual binaries are requested.

Instruction Scope

Runtime instructions stay within the stated purpose (auth, login, monitor/search/join, scheduled send). The skill explicitly generates .session files and uses a .env file (both sensitive) and warns about that. One operational note: many optional environment variables control file paths (TG_PROJECT_ROOT, TG_JOIN_LIST_FILE, TG_MONITOR_REGEX_RULES_FILE, etc.), allowing the runtime to read/write files outside the project if misconfigured; that increases the scope of file access but is consistent with configurable tooling.

Install Mechanism

No remote downloads or installers; recommended install is 'pip install -e .' and dependencies are standard PyPI packages (telethon, openpyxl, python-dotenv) declared in pyproject/requirements. No extract-from-arbitrary-URL, no nonstandard install locations.

Credentials

Required environment variables (TELEGRAM_API_ID, TELEGRAM_API_HASH, TELEGRAM_PHONE) are expected for Telethon-based tooling. These are highly sensitive (API_HASH and session files provide access to the Telegram account). The many optional env vars are reasonable for configuration, but their ability to point to absolute paths (TG_PROJECT_ROOT, TG_JOIN_LIST_FILE, etc.) means a mis-set environment could cause the skill to read/write unexpected files — review these before running.

Persistence & Privilege

The skill does create persistent artifacts (userdata/*.session, caches, lockfiles) and supports long-running daemons, but 'always' is false and persistent/long‑run modes require explicit env switches (TG_ENABLE_PERSISTENT_JOIN, TG_RISK_ACK). It does not modify other skills or system-wide agent settings.

Assessment

This package appears to do what it says, but you must protect the sensitive credentials and session files. Before installing/running: 1) Use a disposable/test Telegram account (not your main account). 2) Keep .env and userdata/*.session private and do not share them; ensure .gitignore/.clawignore include them. 3) Double-check any environment variables that accept paths (TG_PROJECT_ROOT, TG_JOIN_LIST_FILE, TG_MONITOR_REGEX_RULES_FILE, TG_MONITOR_WEB_OUTPUT_DIR) so they don't point to system or other users' directories. 4) Understand and acknowledge the risk flags: TG_ENABLE_PERSISTENT_JOIN must be explicitly set to enable persistent joining; scheduled send requires TG_RISK_ACK=I_UNDERSTAND. 5) Inspect scheduled_tasks.json and join_targets.txt for content you are legally/ethically comfortable sending/joining — the examples include promotional content that could violate Telegram policies or local laws. 6) Run first in an isolated environment, verify behavior with small tests (groups, sending to yourself), and only then enable persistent/background modes. If you want higher assurance, review the specific modules (monitoring, join, search) in detail or run in a sandboxed VM.

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

1. 敏感文件生成：技能运行时会在userdata/目录生成*.session会话文件（包含Telegram登录认证状态），并使用.env配置文件，均为高敏感信息，已默认加入.gitignore/.clawignore禁止提交到代码仓库/发布，请勿手动分享这些文件。
2. 持久运行说明：monitor（群监控）、search（群搜索）、join（批量加群定时模式）均为长时间运行的长驻任务，启动后会持续在后台运行直至手动终止。
3. 合规使用提示：本工具仅用于合法的Telegram群组自动化管理用途，禁止用于发送垃圾信息、骚扰用户、批量爬取用户信息等违反Telegram服务条款和当地法律法规的行为。建议使用独立测试账号运行，避免主账号被平台封禁。所有配置需用户自行填写，工具无内置默认发送目标、消息内容或爬取规则。
4. 默认风险保护：join 默认仅允许 --once；若需长驻必须设置 TG_ENABLE_PERSISTENT_JOIN=true。scheduled_send.py 默认拒绝发送，需设置 TG_RISK_ACK=I_UNDERSTAND 后才执行。

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. 复制配置模板：cp config/scheduled_tasks.example.json config/scheduled_tasks.json
2. 编辑scheduled_tasks.json，按示例格式添加多个任务：
   • name：任务备注名，方便识别
   • target_group_id：目标群组ID（可以从groups命令输出中获取）
   • message：要发送的消息内容
   • interval_hours：发送间隔（小时，建议不小于1小时，避免被平台判定为垃圾消息）
3. 启动定时任务：python3 scheduled_send.py

💡 兼容性说明：旧版本的单任务环境变量配置依然有效，若存在多任务配置文件则优先使用多任务配置。 ⚠️ 防封号提示：建议不同群的消息内容不要完全一致，发送间隔不要低于30分钟，避免被Telegram判定为垃圾消息导致账号封禁。 ⚠️ 风险确认：执行前必须设置 TG_RISK_ACK=I_UNDERSTAND。

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

• config/target_groups.txt：监控白名单群名（monitor 必需，空文件会拒绝启动）。
• config/monitor_regex_rules.json：监控正则规则配置（可用 TG_MONITOR_REGEX_RULES_FILE 指定）。
• config/keywords.txt：监控普通关键词（逐行匹配，可与正则规则叠加）。
• config/group_search_keywords.txt：群搜索关键词（search 使用）。
• config/group_search.json：群搜索时间、采样量、导出目录等参数。
• join_targets.txt：批量加群目标列表（join 使用；可用 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：群搜索（长驻，按配置定时）。
• python3 -m tg_monitor_kit join --once：批量加群（单轮）。
• TG_ENABLE_PERSISTENT_JOIN=true python3 -m tg_monitor_kit join：批量加群（长驻定时，默认关闭）。

停止长驻任务

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

Rules

• 严禁在对话或日志中输出 TELEGRAM_API_HASH、短信验证码、.session 文件内容。
• monitor、search、join 属于长驻任务，同一会话名同一时刻仅运行一个，避免 database is locked。
• 所有定时相关行为按北京时间（UTC+8）理解与配置。
• 批量加群存在风控风险，需由使用者自行确认目标与频率合规。

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。
执行：python3 -m tg_monitor_kit join --once。
输出：返回成功/已在群/失败统计。