kolezka/NL5H00X
GitHub: kolezka/NL5H00X
一款针对锁定版 Android 投影仪的固件修改工具，提供完整备份与自定义启动器替换功能。
Stars: 7 | Forks: 1
# Android 投影仪工具包
用于绕过被锁定的 Android 投影仪上的安全限制并安装自定义启动器的工具。
## 目录
- [概述](#overview)
- [快速开始](#quick-start)
- [功能](#features)
- [脚本](#scripts)
- [文档](#documentation)
- [已测试设备](#tested-devices)
- [安全](#safety)
- [紧急恢复](#emergency-recovery)
- [贡献](#contributing)
- [许可证](#license)
## 概述
修复不允许安装应用或更换启动器的 Android 投影仪。创建完整的设备备份，并安全地将锁定的原厂启动器替换为 [Projectivy](https://github.com/spocky/miproja1) 或您选择的其他启动器。
## 快速开始
```
./scripts/PROJECTOR.sh
```
这就是全部操作。它会找到投影仪，显示其当前状态，并
引导您完成 备份 → 验证 → 解锁，并为耗时 15 分钟的
备份提供进度条。任何操作都会先征求您的同意。
```
NL5H00X Projector Toolkit
-----------------------------------------------------------
device NL5H00X_TP root: yes
backup verified 7.65 GB projector-backup-20260728_054611
launcher locked stock launcher
-----------------------------------------------------------
[1] Back up the device again ~13 min
[2] Unlock the launcher
[3] Restore the stock launcher
[4] Detailed unlock state
[5] Refresh
[q] Quit
> 1
```
备份过程会在实时视图后台运行，而不是让您对着无响应的屏幕等上十五分钟：
```
Backing up NL5H00X_TP
-----------------------------------------------------------
[########################................] 62%
pulled 4.74 GB / 7.65 GB
block 18 of 29
rate 10.4 MB/s 4 min left
stalls 3 killed and retried expected on this device
-----------------------------------------------------------
[INFO] 56% 4.28 GB / 7.65 GB
[WARN] Transfer stalled 30s at 4.41 GB - killing it
[WARN] Block at 4.41 GB: got 113156093 bytes, wanted 268435456 (try 1/3)
[INFO] 62% 4.74 GB / 7.65 GB
the backup keeps running even if you close this
```
`stalls killed` 在这种硬件上很正常，并不是警告信号 —— 远程
`dd` 会定期被清理，每个数据块都会简单重试。即使显示了
三次该提示的运行，依然能生成字节精确的镜像。
如果您愿意，或者想针对它们编写脚本，各个脚本依然可以独立运行：
```
./scripts/TOOLS.sh # opens hidden settings screens; no root needed
./scripts/MAKE_BACKUP.sh # full device image, resumable
./scripts/UNLOCK.sh --status # what is applied; changes nothing
./scripts/UNLOCK.sh --apply-all
```
## 解锁启动器
投影仪出厂时锁定在 `com.newlink.hisilauncher`，且不允许您
从“设置”中更改主屏幕。`UNLOCK.sh` 可以解决这个问题。
```
./scripts/UNLOCK.sh # interactive menu
./scripts/UNLOCK.sh --status # what is and is not applied; changes nothing
./scripts/UNLOCK.sh --apply-all # do everything, then stop
./scripts/UNLOCK.sh --revert # put the stock launcher back
```
**仅仅将启动器 APK 复制到 `/system/app` 是不够的。** 这是每个人
都会首先尝试的方法，但它不起作用：当原厂启动器仍然
启用时，它会在下次开机时重新夺回主屏幕。解锁操作会先禁用它，
然后再设置主屏幕 Activity。这个执行顺序才是关键所在。
它每次执行的一项操作及其目的 —— 每一步都会通过从设备回读值来进行检查，
而不是盲目信任命令的退出代码：
| 步骤 | 改动 |
|------|--------|
| `dev_options` | 打开开发者选项，允许从未知来源安装 |
| `launcher_present` | 安装 Projectivy（如果已安装则跳过） |
| `launcher_default` | 禁用原厂启动器，将 Projectivy 设置为主屏幕 |
| `cleanup_leftovers` | 移除先前尝试留下的空文件夹或重复文件夹 |
值得了解的安全行为：
- 拒绝在非 NL5H00X 设备上运行。
- 没有经过验证的备份拒绝进行任何更改（`--status` 除外）。
- 重新运行它是无操作（no-op）；它会报告已经完成了什么。
- **原厂启动器只有在确认替代启动器已经运行后才会被禁用。** 已安装并不
等于能正常工作 —— 启动时崩溃的启动器依然会出现在 `pm list packages` 中，如果
在此基础上禁用原厂启动器，最终会导致您完全失去主屏幕。因此，新的启动器
会先被启动并确认其仍在运行，然后才会禁用原厂启动器。
- 如果原厂启动器无法被禁用，程序会重新启用它，而不是
让您彻底失去主屏幕。
- `--revert` 可恢复原厂启动器，并且该过程同样会经过验证。
之后请重启投影仪，以使新的主屏幕生效。
### 为什么选 Projectivy
投影仪是通过遥控器操作的，而不是触摸屏。Projectivy 是一款
leanback 启动器：它声明了 `LEANBACK_LAUNCHER`，为方向键（D-pad）进行了布局优化，并且
专为这类设备而构建。Nova —— 之前的一次尝试将其留在了
`/system/app` 中 —— 是一款手机启动器，用鼠标操作尚可，但用包装盒里附带的
遥控器操作则非常别扭。
它的 APK 取自开发者自己的 GitHub releases，而不是镜像源，并且其包名、SDK 范围、ABIs 和
签名证书都记录在 [`apks/PROVENANCE.md`](apks/PROVENANCE.md) 中。如果您已经从 Google Play
安装了 Projectivy，请保留它 —— `launcher_present` 会检测到它并且什么也不做。
没有硬编码强制要求使用 Projectivy。要使用其他启动器：
```
LAUNCHER_PKG=com.teslacoilsw.launcher \
LAUNCHER_NAME=Nova \
LAUNCHER_APK_GLOB='nova-launcher*.apk' \
./scripts/UNLOCK.sh --apply-all
```
主屏幕 Activity 也从不被硬编码 —— 它是通过询问设备上实际由哪个组件处理 `CATEGORY_HOME` 来解析的，因此即使某个启动器在不同版本之间重命名了它的 Activity，也不会导致任何问题。
## 功能
- **隐藏设置访问** - 无需修改即可解锁厂商限制的功能
- **完整备份** - 支持 7GB 以上取证设备镜像及分块存储
- **自定义启动器** - 用 Projectivy、Nova 或其他启动器替换锁定的原厂启动器（需要 root）
## 脚本
| 脚本 | 用途 | 需要 Root |
|--------|---------|---------------|
| [`PROJECTOR.sh`](scripts/PROJECTOR.sh) | **从这里开始** —— 涵盖以下所有功能的引导式界面 | 视情况而定 |
| [`TOOLS.sh`](scripts/TOOLS.sh) | 打开隐藏的设置界面；也可以重置主屏幕 | 否 |
| [`MAKE_BACKUP.sh`](scripts/MAKE_BACKUP.sh) | 创建完整的设备备份 | 是 |
| [`UNLOCK.sh`](scripts/UNLOCK.sh) | 替换锁定的原厂启动器 | 是 |
## 文档
| 文档 | 描述 |
|----------|-------------|
| [技术说明](docs/TECHNICAL_NOTES.md) | 设备分析、ADB 命令、分区布局 |
| [安全分析](docs/SECURITY_ANALYSIS.md) | 详细的安全限制分析 |
| [文档 README](docs/README.md) | 文档概述 |
## 已测试设备
| 设备 | Android | 状态 |
|--------|---------|--------|
| Newlink NL5H00X | 9 | 已测试 |
## 仓库结构
```
scripts/
PROJECTOR.sh # Guided interface -- start here
TOOLS.sh # Access hidden features
MAKE_BACKUP.sh # Complete device backup
UNLOCK.sh # Launcher unlock, interactive CLI
lib/
common.sh # Shared functions
unlock.sh # Unlock steps (state/apply/revert per step)
tests/
run-tests.sh # Backup regression suite
unlock-tests.sh # Unlock end-to-end suite
ui-tests.sh # TOOLS.sh and PROJECTOR.sh front ends
fake-adb/adb # Emulated projector -- no hardware needed
device-emu/seed.sh # Seeds the emulator from measured firmware values
docs/
TECHNICAL_NOTES.md # Technical documentation
SECURITY_ANALYSIS.md # Security analysis
README.md # Docs overview
apks/
projectivy-launcher-4.71.apk # installed by default
nova-launcher-7.0.57.apk # fallback, via LAUNCHER_* overrides
PROVENANCE.md # where each came from and what was verified
assets/
img1.png # Console demo
```
## 安全
- **必须备份** - 修改脚本要求先进行完整备份
- **需要 Root** - 系统修改需要现有的 root 访问权限
- **失去保修** - 使用风险自负
## 紧急恢复
```
# 放回原装 launcher（受支持的方式——它会验证结果）
./scripts/UNLOCK.sh --revert
# 手动操作，如果你无法运行该 script。请注意，在原装 launcher 被禁用的情况下，仅这样做无法
# 在重启后依然生效。
# # 该 component 是 .WizardAciticity，在固件中就是完全这样拼写的。
# .MainActivity 是你实际看到的屏幕，但它不带有 HOME 过滤器，
# 因此 set-home-activity 会拒绝它。询问设备，而不是盲目相信任何一方：
adb shell 'echo "pm enable com.newlink.hisilauncher" | su'
adb shell cmd package query-activities --brief \
-a android.intent.action.MAIN -c android.intent.category.HOME
adb shell cmd package set-home-activity com.newlink.hisilauncher/.WizardAciticity
```
从镜像完全恢复则是另一回事。`RESTORE.sh` **是由 `MAKE_BACKUP.sh` 生成到备份目录中的** —— 它不在 `scripts/` 目录下 —— 所以请从该目录运行它：
```
cd projector-backup-/
./RESTORE.sh
```
如果设备完整镜像与 `backup-manifest.txt` 不匹配，它会拒绝写入；如果缺少清单文件，它会直接拒绝执行。将一个残缺的镜像覆盖恢复到整个设备，正是导致投影仪无法开机的元凶。
## 无需投影仪进行开发
整个工具包可以在模拟设备上运行，因此可以测试更改而无需触碰硬件 —— 当被测试的对象是“您将用来恢复的备份”或“您开机所需的启动器”时，这一点尤为重要。
```
bash tests/run-tests.sh # backup suite
bash tests/unlock-tests.sh # unlock suite
bash tests/ui-tests.sh # TOOLS.sh and PROJECTOR.sh
```
UI 测试套件通过 `/bin/bash` 运行前端，而不是通过 `$PATH` 解析出的
`bash`，因为 shebang 指定的就是这个路径。macOS 依然自带 bash 3.2，而在 Homebrew 提供的
较新版 bash 中进行测试，曾掩盖了一个会导致每个 Mac 用户的 `TOOLS.sh` 直接崩溃的
`local -n` 问题。
模拟器的数据源自真实 NL5H00X 上的测量值：包括它的
`build.prop`、它的 `/system/app` 清单、仅限管道方式的 `su`（拒绝 `su -c`，与真实设备一致）、只读挂载的 `/system`，以及在原厂启动器启用时会重新强制设为默认的启动流程。它会**拒绝设备所拒绝的操作**，因此，如果某个解锁操作忘记重新挂载 `/system` 或忘记禁用原厂启动器，在模拟器上同样会失败。
如果想要针对您自己提取的固件而不是内置替代品来运行脚本：
```
export FAKE_ADB_STATE=/tmp/fakedev
mkdir -p "$FAKE_ADB_STATE/sdcard"
cp projector-backup-*/full-system-backup.img "$FAKE_ADB_STATE/blockdev"
PATH="$PWD/tests/fake-adb:$PATH" ./scripts/TOOLS.sh
```
## 贡献
请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。
## 许可证
[MIT 许可证](LICENSE) - 仅限教育用途。
标签：ADB工具, 启动器替换, 固件修改, 安卓, 投影仪, 系统定制, 设备Root