@@ -0,0 +1,295 @@
# Telegram 抓消息说明
> **用途**：在 notiMessage 中抓取 Telegram 消息（前台 + 后台），转发到 App 本地日志与 PC 调试台。
> **关联**： （ ）
---
## 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（
### 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 后 ** ： **软重启 ** （或整机重启），否则 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
```
> **注意**： ，
### 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. 双通道架构
```
│
┌──────────────┴──────────────┐
│ │
后台弹系统通知 前台收到新消息
│ │
▼ ▼
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
Package: com.miraclegarden.smsmessage
Extras: packageName, title, content, timestamp, source=xposed_telegram
```
`HookMessageReceiver` 会检查 Telegram 是否在 **监听列表 ** ；未添加则日志 `[Hook] 未配置监听: org.telegram...` 并丢弃。
---
## 6. 实现原理（ ）
源码：`xposed-module/src/main/java/.../hook/TelegramMessageHook.java`
### 6.1 为何不 Hook SQLite？
Telegram 消息存在 SQLite 的 * * `data` 字段（ `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 包名 ** ；
| 日志 `[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；
| 群静音 / 无通知 | 后台通道无触发 | 前台靠 Hook；
| 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: 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
├── 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
手机: LSPosed 启用模块 → 勾 Telegram + 主 App → 软重启 TG
App: 监听设置添加 Telegram → 开始监听
验证: TG 前台收消息 → 出现 [Hook/xposed_telegram]
```
---
* 最后更新： *
mars