# 消息抓取架构与 Hook 扩展指南

本文说明 notiMessage 的双通道抓取机制、Telegram 的实现方式，以及日后接入其他 App 的步骤。

---

## 1. 总体架构

notiMessage 使用 **两条独立通道** 抓取消息，互为补充：

```
┌─────────────────────────────────────────────────────────────────┐
│                        目标 App（如 Telegram）                    │
└───────────────┬─────────────────────────────┬───────────────────┘
                │                             │
     后台/锁屏弹系统通知              前台打开 App、消息入库/解码
                │                             │
                ▼                             ▼
   NotificationListenerService          Xposed Hook 模块
   (NotificationService)              (xposed-module)
                │                             │
                │                             │ Broadcast
                │                             ▼
                │                    HookMessageReceiver
                │                      │ goAsync()
                │                      ├─ MessageLogStore（立即写入）
                │                      ├─ DebugForwarder（直接转发 PC）
                │                      └─ submitFromHook（仅正式上传模式）
                │                             │
                └──────────────┬──────────────┘
                               ▼
              NotificationService.submitNotification()（通知通道）
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
      MessageLogStore    DebugForwarder    （可选）正式后端上传
      （App 本地日志）    （PC 调试台）      AppConfig.ENABLE_SERVER_UPLOAD
```

| 通道 | 触发条件 | 代码入口 | 日志前缀 |
|------|----------|----------|----------|
| **通知监听** | 目标 App 在后台且弹出系统通知 | `NotificationService.onNotificationPosted()` | 无前缀 |
| **Hook** | 目标 App 进程收到新消息（通常在前台） | `HookMessageReceiver` → 直接 `DebugForwarder` | `[Hook/xposed_telegram]` 等 |

**重要**：仅开通知监听时，目标 App 在前台通常 **不会** 产生系统通知，因此抓不到消息。要覆盖前台场景，必须启用 Xposed Hook。

---

## 2. Telegram 实现方式

### 2.1 包名与作用域

Pixel 6 等设备上 Telegram 常见包名：

| 安装来源 | 包名 |
|----------|------|
| Play / 官网 APK | `org.telegram.messenger` |
| 部分渠道 / Web 版 | `org.telegram.messenger.web` |

LSPosed 作用域需勾选 **目标 Telegram 包名** + **notiMessage 主 App**。

默认作用域见 `xposed-module/src/main/res/values/arrays.xml`。

### 2.2 为何不 Hook SQLite？

Telegram 消息存在 SQLite 的 **`data` 字段（加密二进制 TL 序列化）**，不是明文 `content`/`text`。

通用 `SqliteMessageHook` 只能读明文列，对 Telegram **无效**。因此单独实现 `TelegramMessageHook`。

### 2.3 Hook 点

**主路径**：Hook `NotificationCenter.postNotificationName(int, Object[])`

- 读取静态字段 `NotificationCenter.didReceiveNewMessages` 作为事件 ID
- 当 `id == didReceiveNewMessages` 时，从参数里的 `List<MessageObject>` 取新消息
- 只处理 **非 outgoing**（`messageOwner.out == false`）的消息

**兜底路径**：Hook `MessageObject` 全部构造函数（主路径失败时启用）

源码位置：`xposed-module/.../hook/TelegramMessageHook.java`

### 2.4 字段提取逻辑

| 字段 | 提取方式 | 用途 |
|------|----------|------|
| **群名/会话名** | `MessagesController.getPeerTitle(dialogId)` → `MessageObject.getName()` → `getChat().title` | 分组标题、转发 `group` |
| **发送者** | `MessageObject.getFromName()` | 群内消息前缀 `发送者: 内容` |
| **正文** | `messageText` → `messageOwner.message` → `caption` | 文本内容 |
| **图片+说明** | 识别 `[图片]` 等媒体标签 + 合并 `caption` | 避免只显示「图片」丢失说明 |
| **dialogId** | `MessageObject.getDialogId()` | 去重键 `dialogId:messageId` |

**注意**：不要把 `messageOwner.from_id`（`TLRPC$TL_peerUser` 对象）直接 `toString()` 当标题，会出现 `TLRPC$TL_peerUser@xxxx`。

### 2.5 转发到主 App

Hook 模块通过 `HookForwarder` 发送广播：

```
Action: com.miraclegarden.smsmessage.action.HOOK_MESSAGE
Package: com.miraclegarden.smsmessage
Extras: packageName, title, content, timestamp, source=xposed_telegram
```

主 App 的 `HookMessageReceiver` 接收后：

1. 检查该 `packageName` 是否在监听列表（`App.getMessageByNotiList`）
2. 写本地日志（`MessageLogStore`，立即持久化）
3. **直接**转发 PC（`DebugForwarder`，不依赖 `startService`，后台可用）
4. 若开启正式上传（`ENABLE_SERVER_UPLOAD`），再经 `submitFromHook` 交给 `NotificationService`

---

## 3. 主 App 相关模块

| 文件 | 职责 |
|------|------|
| `NotificationService.java` | 通知监听 + 统一提交入口 |
| `HookMessageReceiver.java` | 接收 Xposed 广播 |
| `MessageLogStore.java` | 日志持久化（后台也能保留历史） |
| `DebugForwarder.java` | POST 到 PC 调试服务 |
| `AppConfig.java` | `ENABLE_DEBUG_FORWARD`、`ENABLE_SERVER_UPLOAD` 开关 |

### PC 调试台

```powershell
# 启动本地服务（含 adb reverse）
powershell -ExecutionPolicy Bypass -File scripts\start-debug-server.ps1
# 浏览器打开 http://127.0.0.1:8765 ，按群/会话分组展示
```

---

## 4. 日后接入其他 App 的步骤

### 4.1 先判断用哪种 Hook 策略

```
目标 App 前台消息是否需要抓取？
├─ 否 → 仅通知监听即可，在 App「监听设置」里添加包名
└─ 是 → 需要 Xposed Hook
         │
         ├─ 消息以明文写入 SQLite（content/text/body 等）？
         │   └─ 是 → 可复用 SqliteMessageHook（默认兜底）
         │
         ├─ 微信？
         │   └─ 是 → 已有 WeChatMessageHook（Hook WCDB message 表）
         │
         └─ 其他（Telegram、WhatsApp、银行 App 等）
             └─ 需编写 **专用 Hook 类**
```

### 4.2 新增专用 Hook 的标准流程

以新 App `com.example.chat` 为例：

#### 步骤 1：分析目标 App

1. 用 `adb shell pm path <包名>` 拉出 APK
2. jadx / dexdump 找消息解码后的类（类似 Telegram 的 `MessageObject`）
3. 确认：消息明文出现在哪个字段、哪个时机（构造函数 / 事件总线 / 通知回调）

#### 步骤 2：编写 Hook 类

在 `xposed-module/src/main/java/.../hook/` 新建 `ExampleChatMessageHook.java`：

```java
public final class ExampleChatMessageHook {
    public static void install(XC_LoadPackage.LoadPackageParam lpparam) {
        // 1. findClass + findAndHookMethod / hookAllConstructors
        // 2. 提取 title（群名）、content（正文）、过滤 outgoing/系统消息
        // 3. 去重（messageId + dialogId）
        // 4. HookForwarder.forward(context, lpparam.packageName, title, content, "xposed_example");
    }
}
```

在 `HookBridge.java` 增加 source 常量，例如 `SOURCE_XPOSED_EXAMPLE = "xposed_example"`。

#### 步骤 3：注册到 MainHook

编辑 `MainHook.java`：

```java
if ("com.example.chat".equals(lpparam.packageName)) {
    ExampleChatMessageHook.install(lpparam);
    return;
}
```

#### 步骤 4：更新 LSPosed 作用域

编辑 `xposed-module/src/main/res/values/arrays.xml`：

```xml
<item>com.example.chat</item>
```

#### 步骤 5：主 App 添加监听

在 notiMessage「监听设置」中添加该 App（或通过 `shared_prefs/server.xml` 的 `saveNotiList`）。

`bankInfoId` 本地调试可用 `local:<包名>`。

#### 步骤 6：构建、安装、验证

```powershell
# 完整安装（主 App + Xposed + LSPosed 作用域）
powershell -ExecutionPolicy Bypass -File scripts\install-full.ps1
```

验证清单：

- [ ] LSPosed 中模块已启用，作用域勾选 **目标 App + notiMessage**
- [ ] 强制停止并重启目标 App（让 Hook 重新加载）
- [ ] notiMessage 监听控制台「开始监听」
- [ ] **后台场景**：收消息 → 通知通道有日志
- [ ] **前台场景**：收消息 → `[Hook/xxx]` 日志 + PC 调试台有数据
- [ ] `adb logcat | grep notiMessageHook` 可见 `installed for <包名>`

### 4.3 复用通用 SqliteMessageHook 的条件

`SqliteMessageHook` 会在 `MainHook` 中作为 **默认兜底** 安装（非微信、非 Telegram 时）。

适用 App 特征：

- 使用标准 `SQLiteDatabase` / `FrameworkSQLiteDatabase`
- 表名含 `message` / `messages`
- `ContentValues` 中有明文列：`content`、`text`、`body`、`msg` 等

**不适用**：Telegram、WhatsApp、Signal 等端到端加密或二进制 `data` 列的 App。

### 4.4 已有专用 Hook 参考

| App | 类 | Hook 目标 |
|-----|-----|-----------|
| 微信 | `WeChatMessageHook` | `com.tencent.wcdb.database.SQLiteDatabase` insert，`message` 表 |
| Telegram | `TelegramMessageHook` | `NotificationCenter.didReceiveNewMessages` + `MessageObject` |
| 其他 | `SqliteMessageHook` | 通用 SQLite insert 兜底 |

---

## 5. 构建与安装

| 脚本 | 用途 |
|------|------|
| `scripts/build-debug.ps1` | 构建主 App + Xposed 双 APK |
| `scripts/install-debug.ps1` | 仅安装双 APK |
| `scripts/install-full.ps1` | **推荐**：构建 + 双 APK + LSPosed 作用域 + adb reverse + 电池白名单 |
| `scripts/start-debug-server.ps1` | 启动 PC 调试台 |

**注意**：Android Studio 点 Run 只安装 `:app` 主模块，**不会**安装 Xposed 模块。完整功能必须用 `install-full.ps1` 或手动安装两个 APK。

---

## 6. 常见问题

| 现象 | 原因 | 处理 |
|------|------|------|
| 前台有消息，App 无日志 | 仅通知通道，Hook 未生效 | 检查 LSPosed 作用域、重启目标 App |
| 标题显示 `TLRPC$...` | 误把对象当字符串 | 用 `getPeerTitle` 等 API，见 TelegramMessageHook |
| 图片消息只有「图片」 | 说明在 caption 字段 | 合并 `caption` + 媒体标签 |
| PC 有数据，App 无历史 | 旧版日志未持久化 | 已用 `MessageLogStore` 修复，更新主 App |
| Hook 日志前缀 `[Hook/...]` 无 | Xposed 未注入 | 确认 Magisk + LSPosed + 模块启用 |

---

## 7. 相关文件索引

```
xposed-module/
├── src/main/assets/xposed_init          # 入口 MainHook
├── src/main/java/.../MainHook.java      # 包名路由
├── src/main/java/.../HookForwarder.java # 广播转发
├── src/main/java/.../hook/
│   ├── TelegramMessageHook.java
│   ├── WeChatMessageHook.java
│   └── SqliteMessageHook.java
└── src/main/res/values/arrays.xml       # xposed_scope 默认作用域

app/
├── src/main/java/.../service/
│   ├── NotificationService.java
│   └── HookMessageReceiver.java
├── src/main/java/.../MessageLogStore.java
├── src/main/java/.../network/DebugForwarder.java
└── src/main/java/.../AppConfig.java

debug-server/server.py                   # PC 调试台
scripts/install-full.ps1                 # 一键完整部署
```