docs: 新增 Telegram 抓消息专文并更新交叉引用

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)
 

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 常见包名：

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*

docs/手机操作手册.md

@@ -94,9 +94,13 @@ cd C:\Users\Administrator\Desktop\notiMessage
 
 ### 4.3 notiMessage 抓 Telegram
 
-1. 打开 **notiMessage** → **开始监听** → 授予通知使用权
+详见 **[`Telegram抓消息说明.md`](Telegram抓消息说明.md)**（安装、作用域、双通道、排错）。
-2. LSPosed 作用域勾选 Telegram + 主 App
+
-3. PC 调试台（可选）：`.\scripts\start-debug-server.ps1`（需 `adb reverse tcp:8765 tcp:8765`）
+简要步骤：
+
+1. 打开 **notiMessage** → **监听设置** 添加 Telegram → **开始监听** → 授予通知使用权
+2. LSPosed 作用域勾选 Telegram + 主 App → **软重启 Telegram**
+3. PC 调试台（可选）：`.\scripts\start-debug-server.ps1`
 
 ---
 

docs/更新说明.md

@@ -89,6 +89,7 @@ adb logcat | findstr /i "HookMessageReceiver DebugForwarder NotificationService
 
 ### 文档
 
+- Telegram 专文：`docs/Telegram抓消息说明.md`
 - 架构与扩展：`docs/Hook指南.md`
 - Agent 说明：`AGENTS.md`