From 5a232213f378c4136969d30c12b0545c13e312bc Mon Sep 17 00:00:00 2001 From: mars <3361409208@qq.com> Date: Mon, 6 Jul 2026 14:17:01 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20Telegram=20?= =?UTF-8?q?=E6=8A=93=E6=B6=88=E6=81=AF=E4=B8=93=E6=96=87=E5=B9=B6=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E4=BA=A4=E5=8F=89=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 +- docs/Hook指南.md | 4 +- docs/Telegram抓消息说明.md | 295 +++++++++++++++++++++++++++++++++++++ docs/手机操作手册.md | 10 +- docs/更新说明.md | 1 + 5 files changed, 308 insertions(+), 5 deletions(-) create mode 100644 docs/Telegram抓消息说明.md diff --git a/AGENTS.md b/AGENTS.md index fa71244..b4d5b1a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,8 @@ Android 应用，监听通知栏消息并通过 **双通道**（通知监听 + Xposed Hook）抓取内容，支持 PC 本地调试台转发。 -> **Hook 架构与扩展指南**：详见 [docs/Hook指南.md](docs/Hook指南.md)（含 **Xposed / LSPosed**、Telegram、接入新 App） +> **Hook 架构与扩展指南**：详见 [docs/Hook指南.md](docs/Hook指南.md)（含 **Xposed / LSPosed**、接入新 App） +> **Telegram 抓消息专文**：[docs/Telegram抓消息说明.md](docs/Telegram抓消息说明.md) > **手机部署与银行 bypass 操作**：详见 [docs/手机操作手册.md](docs/手机操作手册.md) > **MariBank 风控与 register 载荷**：[docs/MariBank风控与载荷说明.md](docs/MariBank风控与载荷说明.md) diff --git a/docs/Hook指南.md b/docs/Hook指南.md index e9f1320..a0e8d73 100644 --- a/docs/Hook指南.md +++ b/docs/Hook指南.md @@ -2,7 +2,7 @@ 本文说明 notiMessage 的双通道抓取机制、Telegram 的实现方式、**Xposed 与 LSPosed**，以及日后接入其他 App 的步骤。 -> 手机部署步骤见 [`手机操作手册.md`](手机操作手册.md) · MariBank 载荷与风控见 [`MariBank风控与载荷说明.md`](MariBank风控与载荷说明.md) +> 手机部署步骤见 [`手机操作手册.md`](手机操作手册.md) · **Telegram 专文**见 [`Telegram抓消息说明.md`](Telegram抓消息说明.md) · MariBank 见 [`MariBank风控与载荷说明.md`](MariBank风控与载荷说明.md) --- @@ -85,6 +85,8 @@ notiMessage 使用 **两条独立通道** 抓取消息，互为补充： ## 2. Telegram 实现方式 +> **完整安装、双通道、排错、logcat**：见专文 [`Telegram抓消息说明.md`](Telegram抓消息说明.md)。本节保留架构摘要。 + ### 2.1 包名与作用域 Pixel 6 等设备上 Telegram 常见包名： diff --git a/docs/Telegram抓消息说明.md b/docs/Telegram抓消息说明.md new file mode 100644 index 0000000..bd1cb7f --- /dev/null +++ b/docs/Telegram抓消息说明.md @@ -0,0 +1,295 @@ +# Telegram 抓消息说明 + +> **用途**：在 notiMessage 中抓取 Telegram 消息（前台 + 后台），转发到 App 本地日志与 PC 调试台。 +> **关联**：[`Hook指南.md`](Hook指南.md)（通用架构、Xposed/LSPosed）· [`手机操作手册.md`](手机操作手册.md) · [`更新说明.md`](更新说明.md) + +--- + +## 1. 能力概览 + +| 场景 | 通道 | 是否需要 Root / LSPosed | 日志标识 | +|------|------|-------------------------|----------| +| TG **后台** / 锁屏，系统弹出通知 | 通知监听 `NotificationService` | ❌ 不需要（仅需通知使用权） | 无前缀 | +| TG **前台** 打开聊天（通常无系统通知） | Xposed `TelegramMessageHook` | ✅ 需要 Magisk + LSPosed + 模块 | `[Hook/xposed_telegram]` | + +**重要**：只开通知监听、不装 Xposed 时，**TG 在前台收消息抓不到**。要完整覆盖，必须启用 Hook 模块。 + +--- + +## 2. 必须安装什么 + +### 2.1 完整能力（前台 + 后台） + +| 序号 | 组件 | 说明 | +|------|------|------| +| 1 | **Telegram** | 包名见 §3 | +| 2 | **notiMessage 主 App** | `com.miraclegarden.smsmessage` | +| 3 | **Xposed 模块 APK** | `com.miraclegarden.smsmessage.xposed`（与主 App 同仓库 `:xposed-module`） | +| 4 | **Magisk + Zygisk** | Root 环境 | +| 5 | **LSPosed** | 加载 Xposed 模块 | + +抓 TG **不需要** Shamiko（那是 MariBank 等银行 App 用的）。 + +### 2.2 仅后台通知（不抓前台） + +| 必须 | 不需要 | +|------|--------| +| notiMessage 主 App | Xposed 模块 | +| Telegram | LSPosed / Root | +| 通知监听权限 | | + +### 2.3 PC 端（调试台，可选） + +| 组件 | 用途 | +|------|------| +| 本仓库源码 + JDK + Android SDK | 编译安装 | +| **adb** | USB 安装、`adb reverse` | +| **Python 3** | `configure-lsposed.py`（`install-full.ps1` 用） | +| `debug-server/server.py` | PC 浏览器查看消息（端口 **8765**） | + +--- + +## 3. 包名与 LSPosed 作用域 + +Pixel 6 等设备常见包名： + +| 安装来源 | 包名 | +|----------|------| +| Play / 官网 APK | `org.telegram.messenger` | +| 部分渠道 / Web 版 | `org.telegram.messenger.web` | + +**必须勾选与实际安装一致的包名**（两个都装则两个都勾）。 + +LSPosed 作用域需勾选： + +1. **目标 Telegram 包名**（上表） +2. **notiMessage 主 App** `com.miraclegarden.smsmessage`（接收 Hook 广播、写日志） +3. 模块本身已在 LSPosed 里 **启用** + +默认作用域见 `xposed-module/src/main/res/values/arrays.xml`。 +一键安装时 `scripts/configure-lsposed.py` 会写入上述包名。 + +**每次更新 Xposed 模块 APK 后**：LSPosed 里对 Telegram **软重启**（或整机重启），否则 Hook 不注入。 + +--- + +## 4. 安装与配置（推荐流程） + +### 4.1 PC 一键安装 + +```powershell +cd C:\Users\Administrator\Desktop\notiMessage +.\scripts\install-full.ps1 +``` + +自动完成：编译 → 安装双 APK → 写入 LSPosed 作用域 → `adb reverse` → 电池白名单 → 通知监听授权。 + +仅编译安装、不写作用域： + +```powershell +.\scripts\build-debug.ps1 +.\scripts\install-debug.ps1 +``` + +> **注意**：Android Studio 直接 Run 只装主 App，**不会**装 Xposed 模块。完整 TG 抓取必须用 `install-full.ps1` 或手动装两个 APK。 + +### 4.2 手机上 + +1. **LSPosed** → 启用模块 **notiMessage Xposed** → 作用域勾选 Telegram + 主 App → **软重启 Telegram** +2. 打开 **notiMessage** → **监听设置** → 添加 **Telegram**（包名须与 LSPosed 一致） +3. 回到 **监听控制台** → **开始监听** → 授予通知使用权 +4. （可选）设置 → 给 Telegram / notiMessage **电池不受限制** + +### 4.3 PC 调试台 + +```powershell +.\scripts\start-debug-server.ps1 +``` + +浏览器打开 **http://127.0.0.1:8765**，按群/会话分组展示。 +脚本会自动执行 `adb reverse tcp:8765 tcp:8765`。 + +### 4.4 验证 + +1. 启动调试台（可选） +2. notiMessage 开始监听后 **切到桌面** +3. 打开 Telegram，在任意群/私聊 **收一条别人发的消息**（前台场景） +4. 期望： + - App 监听页出现 `[Hook/xposed_telegram] 群名 发送者: 内容` + - PC 调试台同内容 +5. 再把 TG 切后台，收一条 **会弹系统通知** 的消息 → 走通知通道（无前缀） + +--- + +## 5. 双通道架构 + +``` + Telegram + │ + ┌──────────────┴──────────────┐ + │ │ + 后台弹系统通知 前台收到新消息 + │ │ + ▼ ▼ + NotificationService TelegramMessageHook + (NotificationListener) (xposed-module 进程内) + │ │ + │ │ 广播 HOOK_MESSAGE + │ ▼ + │ HookMessageReceiver + │ ├─ MessageLogStore + │ ├─ DebugForwarder → PC :8765 + │ └─ （可选）正式后端上传 + └──────────────┬──────────────┘ + ▼ + 监听页 / PC 调试台 +``` + +| 配置项 | 文件 | 默认值 | +|--------|------|--------| +| PC 转发开关 | `AppConfig.ENABLE_DEBUG_FORWARD` | `true` | +| 调试台地址 | `AppConfig.DEBUG_SERVER_URL` | `http://127.0.0.1:8765` | +| 正式后端上传 | `AppConfig.ENABLE_SERVER_UPLOAD` | `false` | + +Hook 广播格式： + +```text +Action: com.miraclegarden.smsmessage.action.HOOK_MESSAGE +Package: com.miraclegarden.smsmessage +Extras: packageName, title, content, timestamp, source=xposed_telegram +``` + +`HookMessageReceiver` 会检查 Telegram 是否在 **监听列表**；未添加则日志 `[Hook] 未配置监听: org.telegram...` 并丢弃。 + +--- + +## 6. 实现原理（TelegramMessageHook） + +源码：`xposed-module/src/main/java/.../hook/TelegramMessageHook.java` + +### 6.1 为何不 Hook SQLite？ + +Telegram 消息存在 SQLite 的 **`data` 字段（TL 二进制序列化）**，不是明文 `content`/`text`。 +通用 `SqliteMessageHook` **对 Telegram 无效**，因此单独实现本 Hook。 + +### 6.2 Hook 路径（三条，互为补充） + +| 优先级 | Hook 点 | 触发时机 | +|--------|---------|----------| +| **主路径** | `NotificationCenter.postNotificationName(int, Object[])`，当 `id == didReceiveNewMessages` | 前台收到新消息、消息已解密为 `MessageObject` | +| **通知路径** | `NotificationsController.appendMessage(MessageObject)` | 后台准备弹系统通知时 | +| **兜底** | `MessageObject` 全部构造函数 | 主路径安装失败时 | + +### 6.3 过滤与去重 + +- 只处理 **非 outgoing**（`messageOwner.out == false`），忽略自己发出的消息 +- 去重键：`dialogId:messageId`，内存保留最近 512 条 + +### 6.4 字段提取 + +| 字段 | 提取方式 | 展示 | +|------|----------|------| +| **群名/会话名** | `MessagesController.getPeerTitle(dialogId)` → `getName()` → `getChat().title` | 广播 `title` | +| **发送者** | `MessageObject.getFromName()` | 群内：`发送者: 正文` | +| **正文** | `messageText` → `messageOwner.message` → `caption` | 广播 `content` | +| **媒体** | `isPhoto` / `isVideo` 等 → `[图片]`、`[视频]`… | 与 caption 合并 | + +支持的媒体标签：`[图片]`、`[视频]`、`[GIF]`、`[贴纸]`、`[语音]`、`[音频]`、`[文件]`、`[位置]`、`[联系人]`、`[媒体消息]`。 + +**注意**：不要把 `TLRPC$...` 对象直接 `toString()` 当标题；代码里 `safeText()` 会过滤这类字符串。 + +--- + +## 7. 常见问题 + +| 现象 | 原因 | 处理 | +|------|------|------| +| 前台有消息，无 `[Hook/...]` | Hook 未注入 | LSPosed 启用模块；作用域勾 **实际 TG 包名**；**软重启 TG** | +| 日志 `[Hook] 未配置监听` | 监听列表未加 Telegram | 监听设置里添加对应包名 | +| 只有后台有、前台没有 | 未装 Xposed / 作用域错误 | 安装 xposed 模块 + `install-full.ps1` | +| PC 无数据 | `adb reverse` 未设或调试台未开 | 跑 `start-debug-server.ps1` | +| notiMessage 切后台后 PC 断 | 旧版依赖 startService | 更新到 v2.2.1+，`HookMessageReceiver` 内直接转发 | +| 标题显示 `TLRPC$...` | 旧版或异常路径 | 更新模块；见 `TelegramMessageHook.extractTitle` | +| 图片只有「图片」无说明 | 说明在 caption | 已合并 caption；仍空则 TG 未带说明 | +| 群静音 / 无通知 | 后台通道无触发 | 前台靠 Hook；后台需 TG 允许通知且未静音 | +| TG 被系统冻结 | 省电策略 | TG、notiMessage 设「不受限制」 | +| logcat 无 `notiMessageHook/Telegram` | Hook 未加载 | 查 LSPosed 日志；确认包名是否为 `.web` 版 | + +--- + +## 8. 诊断 logcat + +```powershell +$adb = "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" + +# Hook 是否安装 +& $adb logcat -d | Select-String "notiMessageHook/Telegram" + +# 主 App 是否收到广播 +& $adb logcat -d | Select-String "HookMessageReceiver|DebugForwarder" + +# 通知通道 +& $adb logcat -d | Select-String "NotificationService" +``` + +期望看到： + +```text +notiMessageHook/Telegram: installed for org.telegram.messenger.web, didReceiveNewMessages=... +notiMessageHook/Telegram: appendMessage hook installed for ... +HookMessageReceiver: hook received: pkg=org.telegram.messenger.web source=xposed_telegram title=... +``` + +--- + +## 9. 与 MariBank 模块的关系 + +本仓库 **同一个 Xposed APK** 里还包含 MariBank bypass、澳银 Hook 等；**Telegram 抓消息与银行 bypass 互不依赖**： + +| 能力 | 是否需要 Telegram Hook | 是否需要 MariBank Hook | +|------|------------------------|------------------------| +| 抓 TG 消息 | ✅ | ❌ | +| MariBank 注册 bypass | ❌ | ✅ | + +LSPosed 作用域可以 **只勾 Telegram + 主 App**，不勾银行包名。 + +详见 [`Hook指南.md`](Hook指南.md) 中「模块与通知管理的关系」说明。 + +--- + +## 10. 相关文件 + +```text +xposed-module/ +├── src/main/assets/xposed_init +├── src/main/java/.../MainHook.java # 路由到 TelegramMessageHook +├── src/main/java/.../HookForwarder.java +├── src/main/java/.../hook/TelegramMessageHook.java +└── src/main/res/values/arrays.xml # 默认 xposed_scope + +app/ +├── src/main/java/.../service/HookMessageReceiver.java +├── src/main/java/.../service/NotificationService.java +├── src/main/java/.../MessageLogStore.java +├── src/main/java/.../network/DebugForwarder.java +└── src/main/java/.../AppConfig.java + +debug-server/server.py +scripts/install-full.ps1 +scripts/start-debug-server.ps1 +``` + +--- + +## 11. 最短路径速查 + +```text +PC: install-full.ps1 → start-debug-server.ps1 +手机: LSPosed 启用模块 → 勾 Telegram + 主 App → 软重启 TG +App: 监听设置添加 Telegram → 开始监听 +验证: TG 前台收消息 → 出现 [Hook/xposed_telegram] +``` + +--- + +*最后更新：2026-07-06* diff --git a/docs/手机操作手册.md b/docs/手机操作手册.md index c802858..e677ef6 100644 --- a/docs/手机操作手册.md +++ b/docs/手机操作手册.md @@ -94,9 +94,13 @@ cd C:\Users\Administrator\Desktop\notiMessage ### 4.3 notiMessage 抓 Telegram -1. 打开 **notiMessage** → **开始监听** → 授予通知使用权 -2. LSPosed 作用域勾选 Telegram + 主 App -3. PC 调试台（可选）：`.\scripts\start-debug-server.ps1`（需 `adb reverse tcp:8765 tcp:8765`） +详见 **[`Telegram抓消息说明.md`](Telegram抓消息说明.md)**（安装、作用域、双通道、排错）。 + +简要步骤： + +1. 打开 **notiMessage** → **监听设置** 添加 Telegram → **开始监听** → 授予通知使用权 +2. LSPosed 作用域勾选 Telegram + 主 App → **软重启 Telegram** +3. PC 调试台（可选）：`.\scripts\start-debug-server.ps1` --- diff --git a/docs/更新说明.md b/docs/更新说明.md index 20aa9d7..018a9b5 100644 --- a/docs/更新说明.md +++ b/docs/更新说明.md @@ -89,6 +89,7 @@ adb logcat | findstr /i "HookMessageReceiver DebugForwarder NotificationService ### 文档 +- Telegram 专文：`docs/Telegram抓消息说明.md` - 架构与扩展：`docs/Hook指南.md` - Agent 说明：`AGENTS.md`