# 群监控自动加群

使用 Telethon 登陆用户账号（User-Bot），自动加入目标群、抓取群主信息、监控消息并通过单独的 Bot 汇报关键词命中结果。

## 功能概述
- 通过 `GROUP_LINKS` 列表批量加入群（支持公开链接与 `https://t.me/+xxxx` 邀请链接）。
- 获取群主/创建者信息并在汇报群内确认当前监控状态。
- 长连接监听群消息，命中关键词时推送到指定群/频道。
- 关键词配置独立于代码（`keywords.yaml`），可随时增删并自动热加载。
- 汇报通道使用 Bot Token，避免 user-bot 重复发言。

## 环境要求
- Python 3.10+
- Telegram API 凭据（`api_id`/`api_hash`）
- 目标账号可登录的手机号（首登需要验证码）
- Bot Token（用于把监控结果发到 @kt500_bot 已在的群）

## 快速开始
1. 安装依赖：
   ```bash
   python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   ```
2. 准备配置：
   ```bash
   cp .env.example .env
   ```
   按需填写：
   - `API_ID` / `API_HASH`：来自 [my.telegram.org](https://my.telegram.org)。
   - `SESSION_NAME`：本地 session 文件名，首次登录会生成 `SESSION_NAME.session`。
   - `USER_PHONE`：用于自动登录（可留空，运行时手输）。
   - `GROUP_LINKS`：逗号分隔的群链接，可直接填 `https://t.me/+tvVm--E19cxkNWJl`。
   - `REPORT_CHAT_LINK`：用于汇报的群/频道链接，如果就地汇报可与 `GROUP_LINKS` 中某一项相同。
   - `TELEGRAM_BOT_TOKEN`：你的 @kt500_bot Token。
   - `KEYWORDS_FILE`：关键词配置文件路径，默认 `keywords.yaml`。
3. 配置关键词：编辑 `keywords.yaml`，示例：
   ```yaml
   keywords:
     - name: promo
       patterns:
         - "推广"
         - "广告"
       regex: false
     - name: join_request
       patterns:
         - "(?i)拉群"
         - "(?i)加好友"
       regex: true
   ```
   - `regex: false` 表示普通子串匹配（自动转换小写）。
   - `regex: true` 将整条 `pattern` 按正则表达式处理，可使用 `(?i)` 等修饰。
   - 文件被修改后，程序会自动检测更新时间并重新加载。
4. 运行：
   ```bash
   python3 -m src.main
   ```
   - 首次运行会提示输入验证码 / 二步验证密码。
   - 成功后会看到“群监控已启用”提示，同时在 `REPORT_CHAT_LINK` 对应的群内收到确认消息。

## 工作流程
1. **自动入群**：对每个链接先尝试 `get_entity`，若失败且为邀请链接，则执行 `ImportChatInviteRequest` 加入。加入或已在群内后会开始监听。
2. **群主识别**：调用 `GetParticipantsRequest(... ChannelParticipantsAdmins ...)` 找到 `ChannelParticipantCreator`，将结果写入汇报中，便于核对“自动添加群主”状态。
3. **关键词监控**：`events.NewMessage` 监听指定群，命中关键词时将群名、消息 ID、发送人、关键词、时间与截断内容推送到 Bot 所在的群。
4. **多次触发 & 附件提醒**：文本命中会附带一则消息，若原消息含媒体，还会追加“附件提醒”。

## 常见扩展
- **新增关键词**：直接编辑 `keywords.yaml`，保存后生效（无需重启）。
- **新增群**：在 `.env` 的 `GROUP_LINKS` 中添加链接，重启程序即可。
- **自定义汇报格式**：在 `src/group_monitor.py` 的 `_handle_new_message` 中调整 `lines` 内容。
- **落地数据库**：可在 `_handle_new_message` 中追加写库逻辑，然后调用 `reporter.send_safe` 做通知。

## 注意事项
- 请确保 user-bot 与 @kt500_bot 均已在 `REPORT_CHAT_LINK` 对应的群里，并授予发送消息权限。
- Telegram 对频繁入群/拉人有限制，若日志出现 `FloodWaitError`，需等待对应秒数。
- Session 文件包含账户授权信息，只应保存在可信设备中。
- 若长期运行，建议用 `supervisor`/`systemd` 守护，并开启日志轮转。

## 后续工作
- 若需要把“自动添加群主”升级为主动发送好友请求，可结合 `contacts.AddContactRequest`，条件是群主公开手机号。
- 可根据需要加入异常上报（例如钉钉/企业微信）或统计报表。