从首次连接到拔线通话验收

01. 前提条件与安全边界

1. 目标设备与系统：黑莓 Passport（SQW100-1 / SQW100-3 / SQW100-4，代号 wolverine），运行 LineageOS 18.1-UNOFFICIAL-wseries（Android 11 / API 30，SELinux 保持 Enforcing）。工具会自动校验机型，非 wolverine 拒绝写入。
2. SIM 卡要求：已插入开通了 VoLTE 高清语音业务的 4G/5G USIM 卡，且手机状态栏当前能够正常驻留 LTE 数据网络。
3. 保持空闲状态：执行写入与重启前，请确认当前没有正在进行的通话，电量建议高于 30%，并使用可靠的数据线连接电脑。

02. 开启 LineageOS 18.1 的 USB 调试与 Root 调试

如果你使用推荐的电脑端激活方式（方式一或方式三），完全不需要刷入 Magisk，只需打开系统自带的开发者开关：

1. 在手机上进入 设置 → 关于手机，连续点击 7 次最下方的 版本号（Build number） 启用开发者选项。
2. 返回上一级，进入 设置 → 系统 → 高级 → 开发者选项。
3. 开启 Android 调试（USB 调试）。
4. 在同页面找到 Root 调试（Rooted debugging） 并开启允许。
5. 用数据线连接电脑，在手机弹出的「允许 USB 调试吗？」对话框中勾选一律允许并点击确定。

03. 方式一：Windows 桌面一键激活工具（最推荐）

1. 下载 passport-android11-volte-1.0.0-r1-windows-x64.exe 并双击运行（无需安装 Python 或 ADB）。
2. 确认顶部「ADB 设备」下拉框已识别到你的手机序列号，点击 「1. 只读检查状态」 确认连接正常。
3. 点击绿色主按钮 「2. 备份并一键激活 VoLTE」 并确认提示框。
4. 程序将自动：切换 adb root → 将原始基带快照保存至电脑 %LOCALAPPDATA%\passport-android11-volte\backups\ → 写入 Stage 6A 基带配置并执行 EFS_SYNC → 安装 PassportVolteIms.apk v2.3 并写入持久化 CarrierConfig → 正常重启手机并轮询确认 volte_stack_healthy: true。
5. 看到绿色「VoLTE 栈运行正常」横幅后，即可拔掉 USB 数据线进行通话测试。

04. 方式二：手机端独立管理 App（适合已刷 Magisk 用户）

如果你的 Passport 已经刷入了 Magisk（手机本地存在 su 超级用户守护进程），可以安装 PassportVolteManager-1.0.0-r1.apk，在手机屏幕上直接管理：

1. 下载 PassportVolteManager-1.0.0-r1.apk 到手机并点击安装（也可以在电脑桌面工具里点击「安装手机端管理 App」一键推送）。
2. 打开桌面上的 Passport VoLTE 图标，点击「刷新状态」可随时查看 IMS 服务与基带 QMI_IMSA 注册状态（无需 Root 也可只读查看）。
3. 点击「激活 / 修复原生 VoLTE（需 Magisk）」，在弹出的 Magisk 超级用户授权框中点击允许，应用会先校验内嵌载荷的 SHA-256、保存基带快照到应用私有目录，再完成 Stage 6A 配置、系统通话桥接安装与自动重启。

05. 方式三：macOS / Linux / 跨平台便携包（CLI & GUI）

下载并解压 passport-android11-volte-1.0.0-r1-portable.zip（已包含预编译签名的 ARM32 工具与 APK，仅需系统装有 Python 3.9+ 与 adb）：

# 1. 离线单元测试自检
python3 cli/volte_ctl.py self-test

# 2. 只读检查当前手机 VoLTE / QMI_IMSA / ImsResolver 状态
python3 cli/volte_ctl.py status

# 3. 备份基带原值 + 一键写入 Stage 6A + 安装 APK + 重启自动验收
python3 cli/volte_ctl.py deploy

# 4. 或启动跨平台桌面图形界面（需 Python tkinter）
python3 cli/gui.py

06. 方式四：LineageOS 18.1 ROM 源码集成与骁龙 801 移植

面向自定义 ROM 编译维护者，仓库内的 rom-integration/ 目录提供了完整的 Soong Android.bp 与 device-passport-volte.mk：

# 在 LineageOS 18.1 源码树中引入通话桥接服务：
mkdir -p packages/apps/PassportVolteIms
cp -r src/android-ims-service/* src/qmi-imsa-probe rom-integration/Android.bp packages/apps/PassportVolteIms/

# 在 device/blackberry/wolverine/device.mk 末尾加入：
$(call inherit-product, packages/apps/PassportVolteIms/device-passport-volte.mk)

注意：ROM 刷机包只会更新 /system 分区，不会改写高通独立基带分区（Modem EFS），每台实体机首次仍需执行一次 Stage 6A 基带激活。针对一加 1、小米 4、索尼 Z2/Z3、三星 S5 等同代 MSM8974 机型的移植分析，请查阅仓库文档 MSM8974_PORTING_GUIDE.md。

07. 换 SIM 卡与多运营商说明

Stage 6A 基带配置使用 3GPP 标准 ims APN 与 mode=0 动态 PCO 地址下发（不硬编码特定省市 P-CSCF IP），且持久保存在手机基带 EFS 中。当你更换另一张已开通 VoLTE 的 SIM 卡时：

1. 无需重新刷写基带 EFS；
2. 由于 Android 的 CarrierConfig 按 SIM 卡 subId 存储，换新卡后只需在电脑工具点击 「仅升级通话桥接 APK（零 EFS 写入）」（或运行 python3 cli/volte_ctl.py upgrade-apk，或在手机管理 App 点击「仅升级 / 重刷 CarrierConfig」），即可为新 SIM 卡绑定 VoLTE 开关。

08. 真实通话验收清单（必做）

工具显示 mImsRegistered=true 仅代表信令注册成功，请务必用系统自带拨号器逐项实测：

1. 拔掉 USB 数据线，确认完全脱离电脑运行；
2. 用自带拨号器拨打外部电话，接通后确认双方声音清晰，且手机顶部信号栏全程保持 LTE / 4G（不回落 2G/3G，也不假死）；
3. 用另一部手机拨打你的 Passport，确认响铃正常、来电号码正常显示（非“未知”）、接听与挂断干脆；
4. 正常重启一次手机，解锁后等待约 20–40 秒，再次拨打一通电话确认开机自愈生效。

09. 完整恢复出厂基带配置并卸载

如需彻底还原手机到修改前的出厂基带基线，连接电脑点击桌面工具的 「恢复出厂基带配置并卸载」，或执行：

python3 cli/volte_ctl.py rollback

该流程会清除持久化 CarrierConfig 覆盖、卸载 org.passport.volteims，调用 pp_regconfig_provision_v6 --rollback-all 将全部 54 项基带条目恢复出厂值并执行 EFS_SYNC，最后正常重启验证。

10. 校验下载文件 SHA-256

在运行安装包前，可在终端核对下载文件的哈希值是否与发布页的 .sha256 或 SHA256SUMS.txt 完全一致：

# Windows PowerShell:
Get-FileHash "$HOME\Downloads\passport-android11-volte-1.0.0-r1-windows-x64.exe" -Algorithm SHA256

# macOS / Linux:
shasum -a 256 ~/Downloads/passport-android11-volte-1.0.0-r1-portable.zip