# 更新说明

## v2.2.1（2026-07-02）

### 修复：Hook 通道在 notiMessage 后台时丢失消息

**问题**  
TG 在前台、notiMessage 切到后台时，Hook 虽能收到 Xposed 广播，但原先需经 `startService` 才转发到 PC。Android 8+ 会限制后台启动服务，导致 PC 调试台和日志经常收不到 `[Hook/...]` 消息，表现为「必须两个 App 都在当前页面才行」。

**改动**

| 模块 | 说明 |
|------|------|
| `HookMessageReceiver` | 收到广播后**直接在 Receiver 内**调用 `DebugForwarder`；使用 `goAsync()` 等待 HTTP 完成，避免进程被提前回收 |
| `DebugForwarder` | 增加完成回调与详细日志（成功 / HTTP 错误 / 网络失败） |
| `NotificationService` | `submitFromHook` / `requestStartMonitoring` 改用 `startForegroundService`（正式上传模式）；通知通道增加诊断日志 |
| `NotificationHealthCheckWorker` | 健康检查**不再要求联网**；每 15 分钟自动尝试恢复通知监听 |

**诊断 logcat 标签**

```text
HookMessageReceiver   — Hook 广播到达 / 被跳过
DebugForwarder        — PC 转发结果
NotificationService   — 系统通知到达 / 空通知跳过
NotiHealthCheck       — 定时健康检查
```

```powershell
adb logcat | findstr /i "HookMessageReceiver DebugForwarder NotificationService NotiHealthCheck"
```

**验证步骤**

1. 安装新版主 App：`scripts\install-debug.ps1`
2. 启动 PC 调试台：`scripts\start-debug-server.ps1`
3. notiMessage 点「开始监听」后**切到桌面**
4. 打开 TG 发消息 → PC 应出现 `[Hook/xposed_telegram]`

> **说明**：TG 在后台时仍走**通知通道**，需 TG 弹出系统通知。若 TG 被系统冻结或未弹通知，请给 TG / notiMessage 设「电池不受限制」，并确认群未静音。

---

## v2.2 + Xposed v1.1.0

### 新功能

- **Telegram 专用 Hook**（`TelegramMessageHook`）：前台抓取已解密消息，支持文字 / 图片说明 / 群名
- **双 APK 架构**：主 App + `xposed-module`，LSPosed 作用域需勾选 Telegram 与 notiMessage
- **PC 本地调试台**（`debug-server/server.py`，端口 8765）：按群/会话分组展示
- **`MessageLogStore`**：监听页日志持久化，App 后台再打开可恢复历史
- **`DebugForwarder`**：消息 POST 到 PC（`AppConfig.ENABLE_DEBUG_FORWARD`）
- **安装脚本**：`build-debug.ps1`、`install-debug.ps1`、`install-full.ps1`、`configure-lsposed.py`

### 配置（`AppConfig.java`）

| 开关 | 当前默认值 | 含义 |
|------|------------|------|
| `ENABLE_SERVER_UPLOAD` | `false` | 正式后端上传 |
| `ENABLE_DEBUG_FORWARD` | `true` | 转发到 PC 调试台 |
| `DEBUG_SERVER_URL` | `http://127.0.0.1:8765` | 调试服务地址（USB 用 adb reverse） |

### 双通道机制

| 场景 | 通道 | 日志标识 |
|------|------|----------|
| TG 后台 / 锁屏有系统通知 | 通知监听 | 无前缀 |
| TG 前台（通常无通知） | Xposed Hook | `[Hook/xposed_telegram]` |

### 已知限制

- 通用 SQLite Hook 对 Telegram **无效**（消息在加密 `data` 字段）
- 监听包名须与实际安装一致，如 `org.telegram.messenger.web`
- 空内容通知（纯图片无文字）会被跳过
- Android Studio 直接 Run 只装主 App；完整能力需 `install-full.ps1`

### 文档

- 架构与扩展：`docs/HOOK_GUIDE.md`
- Agent 说明：`AGENTS.md`

---

## 安装与升级

```powershell
# 构建
powershell -ExecutionPolicy Bypass -File scripts\build-debug.ps1

# 安装双 APK
powershell -ExecutionPolicy Bypass -File scripts\install-debug.ps1

# 完整安装（含 LSPosed 作用域 + adb reverse + 电池白名单）
powershell -ExecutionPolicy Bypass -File scripts\install-full.ps1

# PC 调试台
powershell -ExecutionPolicy Bypass -File scripts\start-debug-server.ps1
```

升级 v2.2.1 后**至少需重装主 App**；若只改了主 App 代码，Xposed 模块无需重装。