feat: migrate to GramJS with TS

README.md

@@ -1,80 +1,79 @@
-# 群监控自动加群
+# 群监控（GramJS 版）
 
-使用 Telethon 登陆用户账号（User-Bot），自动加入目标群、抓取群主信息、监控消息并通过单独的 Bot 汇报关键词命中结果。
+使用 [GramJS](https://github.com/gram-js/gramjs) 驱动的 Node.js User-Bot 自动加入目标群、识别群主并实时监听消息。一旦命中关键词，结果会通过单独的 Telegram Bot 安全汇报到指定群/频道。
 
-## 功能概述
-- 通过 `GROUP_LINKS` 列表批量加入群（支持公开链接与 `https://t.me/+xxxx` 邀请链接）。
-- 获取群主/创建者信息并在汇报群内确认当前监控状态。
-- 长连接监听群消息，命中关键词时推送到指定群/频道。
-- 关键词配置独立于代码（`keywords.yaml`），可随时增删并自动热加载。
-- 汇报通道使用 Bot Token，避免 user-bot 重复发言。
+## 功能亮点
+- **GramJS 长连接**：以 Node.js 形式运行，便于使用 Chrome DevTools Protocol 调试 Node 后端。
+- **自动入群**：支持公开群链接与 `https://t.me/+xxxx` 邀请链接，必要时自动执行 `ImportChatInvite`。
+- **群主洞察**：拉取 `ChannelParticipantsAdmins`，找到创建者后写入汇报，方便对齐「自动添加群主」的状态。
+- **关键词热加载**：`keywords.yaml` 被修改后自动重新解析，支持子串匹配与 `(?i)`、`(?im)` 等内联正则修饰符。
+- **Bot 汇报隔离**：监听使用 user-bot，会话由用户账号维持；真正的告警与附件提醒交由 Bot Token 发出，避免刷屏。
 
 ## 环境要求
-- Python 3.10+
-- Telegram API 凭据（`api_id`/`api_hash`）
-- 目标账号可登录的手机号（首登需要验证码）
-- Bot Token（用于把监控结果发到 @kt500_bot 已在的群）
+- Node.js 18+（建议 LTS）
+- Telegram API 凭据：`api_id` / `api_hash`
+- 可登录的手机号（首次运行需验证码）
+- Telegram Bot Token（Bot 必须已经在汇报群内）
 
 ## 快速开始
 1. 安装依赖：
    ```bash
-   python3 -m venv .venv && source .venv/bin/activate
-   pip install -r requirements.txt
+   npm install
    ```
-2. 准备配置：
+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. 运行：
+   填写下方参数；`SESSION_DIR` 会自动创建并持久化 `*.session` 文件。
+3. 配置 `keywords.yaml`（示例见下节）。
+4. 启动：
    ```bash
-   python3 -m src.main
+   npm run dev       # tsx 直接运行 TypeScript
+   # 或
+   npm run build && npm run start
    ```
-   - 首次运行会提示输入验证码 / 二步验证密码。
-   - 成功后会看到“群监控已启用”提示，同时在 `REPORT_CHAT_LINK` 对应的群内收到确认消息。
+   首次登陆会提示输入手机号验证码及二步验证密码（若有）。
 
-## 工作流程
-1. **自动入群**：对每个链接先尝试 `get_entity`，若失败且为邀请链接，则执行 `ImportChatInviteRequest` 加入。加入或已在群内后会开始监听。
-2. **群主识别**：调用 `GetParticipantsRequest(... ChannelParticipantsAdmins ...)` 找到 `ChannelParticipantCreator`，将结果写入汇报中，便于核对“自动添加群主”状态。
-3. **关键词监控**：`events.NewMessage` 监听指定群，命中关键词时将群名、消息 ID、发送人、关键词、时间与截断内容推送到 Bot 所在的群。
-4. **多次触发 & 附件提醒**：文本命中会附带一则消息，若原消息含媒体，还会追加“附件提醒”。
+## 环境变量说明
+- `API_ID` / `API_HASH`：来自 [my.telegram.org](https://my.telegram.org)。
+- `SESSION_NAME` / `SESSION_DIR`：本地 session 文件名及所在目录。
+- `USER_PHONE`：可选，预填手机号。
+- `TWO_FA_PASSWORD`：可选，账号开启二步验证时使用。
+- `GROUP_LINKS`：逗号分隔的群链接列表，可混合公开链接与 `https://t.me/+xxxx`。
+- `REPORT_CHAT_LINK`：汇报消息要发送到的群/频道；留空时默认取 `GROUP_LINKS` 第一项。
+- `TELEGRAM_BOT_TOKEN`：Bot HTTP API Token。
+- `KEYWORDS_FILE`：关键词配置路径，默认 `keywords.yaml`。
+- `LOG_LEVEL`：`trace|debug|info|warn|error`，默认 `info`。
 
-## 常见扩展
-- **新增关键词**：直接编辑 `keywords.yaml`，保存后生效（无需重启）。
-- **新增群**：在 `.env` 的 `GROUP_LINKS` 中添加链接，重启程序即可。
-- **自定义汇报格式**：在 `src/group_monitor.py` 的 `_handle_new_message` 中调整 `lines` 内容。
-- **落地数据库**：可在 `_handle_new_message` 中追加写库逻辑，然后调用 `reporter.send_safe` 做通知。
+## 关键词配置
+`keywords.yaml` 结构与旧版 Python 一致：
+
+```yaml
+keywords:
+  - name: promo
+    patterns:
+      - "推广"
+      - "广告"
+    regex: false
+  - name: join_request
+    patterns:
+      - "(?i)拉群"
+      - "(?im)^加好友"
+    regex: true
+```
+
+- `regex: false`：子串匹配，自动转为小写比较。
+- `regex: true`：使用 JavaScript 正则。保留了 Python 示例中的 `(?i)`、`(?im)` 等内联修饰符，会自动拆解为对应的 `i/m/s` flags。
+- 文件保存后会触发热加载，无需重启进程。
+
+## 常用脚本
+- `npm run dev`：tsx 直接运行 `src/main.ts`。
+- `npm run build`：编译到 `dist/`，配合 `npm run start` 运行。
+- `npm run lint`：`tsc --noEmit` 类型检查。
+- `npm run test`：Vitest 单测，当前覆盖 `KeywordStore` 热加载逻辑。
 
 ## 注意事项
-- 请确保 user-bot 与 @kt500_bot 均已在 `REPORT_CHAT_LINK` 对应的群里，并授予发送消息权限。
-- Telegram 对频繁入群/拉人有限制，若日志出现 `FloodWaitError`，需等待对应秒数。
-- Session 文件包含账户授权信息，只应保存在可信设备中。
-- 若长期运行，建议用 `supervisor`/`systemd` 守护，并开启日志轮转。
-
-## 后续工作
-- 若需要把“自动添加群主”升级为主动发送好友请求，可结合 `contacts.AddContactRequest`，条件是群主公开手机号。
-- 可根据需要加入异常上报（例如钉钉/企业微信）或统计报表。
+- user-bot 与汇报 Bot 都必须在 `REPORT_CHAT_LINK` 对应的群/频道里，且 Bot 拥有发言权限。
+- Telegram 对频繁入群会触发 `FLOOD_WAIT_xx`，日志会提示需要等待的秒数。
+- `sessions/*.session` 含账号授权信息，请妥善保管。
+- 长期部署建议使用 `pm2 / systemd` 等守护方式并接入日志轮转。