# 归藏电视：项目介绍、改造说明与使用指南

> 这是已发布 v0.2.0 的历史指南。最新版为 [v0.3.0](https://github.com/op7418/guizang-tv/releases/tag/v0.3.0)，统一设置、列表 / Dock、图标、字体和首页编辑详见 [设置指南](SETTINGS.md)。本文旧设置路径与固定六项的描述仅适用于 v0.2.0。

本文对应 **v0.2.0**，整理于 **2026 年 10 月 21 日**。面向想了解项目、在电视上试用，或按自己需求修改源码的读者。

## 1. 这个项目解决什么问题？

归藏电视是一个面向国内小米电视使用场景的简洁 Android 桌面。打开后，背景是一张照片，左边是常用设备和应用，右上角显示时间，右下角集中放置设置入口。

它起初来自一个很具体的需求：进电视首页，经常只是想打开 PS5、切到 Apple TV、看哔哩哔哩，或者投屏。与其每次先找应用、再打开信号源菜单，不如把这些常用入口直接放在首页。

因此，这个版本将 **PlayStation 5 和 Apple TV 的 HDMI 入口与应用并列**，配上中文大字列表和默认开启的照片轮播。安装后作为普通应用使用，保留小米原桌面及系统组件。

项目地址：[op7418/guizang-tv](https://github.com/op7418/guizang-tv)

下载地址：[v0.2.0 安装包](https://github.com/op7418/guizang-tv/releases/tag/v0.2.0)

## 2. 和前两个项目是什么关系？

归藏电视有两条明确的来源：

- **代码起点：**[Gathin23/cleanyourtv](https://github.com/Gathin23/cleanyourtv)。先在这个 Android TV 项目的基础上做本地定制，再整理出当前公开版。
- **设计参考：**[nthnclrk/CleanFrame](https://github.com/nthnclrk/CleanFrame)。参考它的照片背景、大字纵向列表和克制的焦点表现；当前 Android 界面由原生 Java 实现，没有移植它的 Tizen 运行代码，也没有附带它的照片。

下面比较的是本次开发时实际参考的版本：[cleanYourTV `69c93b6`](https://github.com/Gathin23/cleanyourtv/tree/69c93b66a75c70a9e386adff327b6a51c12addc5)、[CleanFrame `fa537d1`](https://github.com/nthnclrk/CleanFrame/tree/fa537d1892b71d2de2bf94c24cbff3812e9f70d5)，以及归藏电视 v0.2.0。它不是对上游后续版本的实时评测。

| 维度 | cleanYourTV | CleanFrame | 归藏电视 |
| --- | --- | --- | --- |
| 主要平台 | Android TV / Google TV，覆盖多品牌的工具与桌面 | Samsung The Frame，Tizen | Android；当前重点适配指定小米机型 |
| 主要目标 | 通过 ADB 清理及桌面定制改善电视体验 | 为 The Frame 提供安静、简洁的电视首页 | 让常用应用与 PS5 / Apple TV 更容易进入 |
| 首页形态 | 常用应用 Dock、应用网格、焦点效果等 | List / Dock 两种布局，可配照片背景 | 照片背景、六项大字纵向列表 |
| 系统操作 | 提供备份、禁用系统包和恢复等流程 | 有针对特定固件的 Home / 启动研究与可选辅助流程 | 公开版不包含系统包禁用流程，也不接管 Home 键 |
| 信号源 | 已有 Inputs 入口，支持 HDMI / AV / Live TV 等场景 | 功能围绕 Tizen 与 The Frame 实现 | 适配机型上将两个常用 HDMI 入口直接放进主列表 |
| 应用配置 | 支持常用应用、主题及其他配置 | 可选择、排序首页应用，并发现已安装应用 | 默认六项固定；“全部应用”可打开其他应用，编辑主列表需改源码 |
| 壁纸与外观 | 已支持壁纸与主题 | 支持壁纸、明暗背景、字体及焦点等设置 | 内置五张照片，可固定使用或按间隔轮播 |
| 对国内使用的取舍 | 可配置，也包含中文支持 | 原项目主要面向其 Samsung 使用环境 | 默认入口直接采用哔哩哔哩、小米投屏、相册、小米原桌面 |
| 安装形态 | Android 应用及配套工具 | Tizen 应用，需要相应构建与签名流程 | Android APK，可先作为普通应用试用 |

原项目并不是“不能在国内用”：cleanYourTV 本身就支持中文和自定义配置，也已有壁纸与信号源功能。归藏电视的变化主要是**重新组织这些使用场景，并针对一台国内小米电视做适配和简化**。

## 3. 具体改了什么？

### 3.1 将首页改成照片背景与大字列表

公开版没有保留原来的 Dock 桌面，而是采用全屏照片、左侧文字列表、右上角时钟的布局。选中项通过亮度和轻微缩放提示焦点，背景叠加暗色渐变，让文字更容易辨认。

相较于 CleanFrame，保留了其设计方向，但使用 Android 系统字体和原生控件重新实现；没有加入其完整的字体、玻璃效果和布局编辑能力。

### 3.2 把两台外接设备放到首页

默认前两项为：

- **PlayStation 5 → HDMI 2**
- **Apple TV → HDMI 1**

在已适配电视上，选中后按确认即可调用对应 HDMI，无需先打开“其他信号源”再挑选。其他输入仍可通过右下角的原生信号源菜单进入。

这里的 Apple TV 指通过 HDMI 连接的实体设备；两个名称都是源码中的预设，**不会自动识别电视接了什么设备，也不会自动判断线插在哪个口**。

### 3.3 将默认应用换成实际常用的国内入口

首页预设哔哩哔哩、小米投屏、相册和小米原桌面。项目只负责打开电视已有的应用，没有预装这些 App，也不提供视频内容、会员账号或代安装服务。

### 3.4 将常用设置统一放到右下角

右下角依次为“壁纸设置”“全部应用”“其他信号源”“设置”。右上角只保留时钟。

遥控器从主列表按右，就能进入操作区；按左回到原来选中的主列表项目。壁纸设置与其他操作放在同一处，减少跨区域寻找入口。

### 3.5 增加适合长期展示的壁纸轮播

公开版默认每 **5 分钟**按顺序切换照片，可以改为 **1 / 5 / 15 / 30 分钟**，也可以固定一张。

切换使用约 700 毫秒的淡入淡出。离开桌面、进入其他应用或打开壁纸设置时暂停轮播计时，回到桌面后重新计时。模式、当前照片和间隔会保存。

五张内置照片都保留作者和来源，另有压缩副本与缩略图。它们的处理后素材总量约为 **1.92 MB**，比所选原图总量减少约 **89.8%**。这仅是图片文件体积对比，不代表运行内存或性能测试结果。

### 3.6 针对小米固件处理系统入口

将 HDMI 切换、原生信号源面板、系统设置和小米原桌面调用集中在适配代码中。专用调用会检查机型、组件导出情况及权限，失败时给出提示。

这解决的是特定固件上的实际调用问题，并不意味着所有小米电视都使用相同接口。当前没有通过禁用系统应用来实现这些入口。

### 3.7 整理成可以独立安装和修改的公开项目

公开版使用独立包名 `io.github.op7418.guizangtv`，名称为“归藏电视”，提供源码、构建检查、签名发布包、许可说明与壁纸署名。

公开仓库没有包含上游的一键清理脚本、旧 Dock 桌面或无障碍按键服务。私人调试数据、签名密钥及版权未确认的照片不在公开版中。

## 4. 有哪些优势？哪些情况不适合？

**常用设备进入路径更短。** 对经常切换 PS5 和 Apple TV 的家庭，设备入口与应用在同一层。它节省的是打开信号源菜单的操作，不承诺降低 HDMI 握手时间或游戏延迟。

**默认内容更贴近这套国内使用习惯。** 中文入口和小米系统功能已放到首页，无需先把海外服务示例逐个换掉。不同家庭仍可能需要修改默认列表。

**界面信息少，适合远距离看。** 大字、照片和少量入口构成主画面，没有内置推荐流或广告位。视频 App 自己的广告、小米系统广告或开机广告不会因此消失。

**可以先试用，保留原系统路径。** 不需要 Root 或刷机；安装后从应用列表进入。原桌面、语音、投屏、直播及 HDMI 系统组件保留，随时可以回原桌面。

**桌面本身可离线运行。** 不需要账号，没有网络权限、后台服务端或遥测实现。被打开的视频与投屏应用是否需要网络，由它们自身决定。

**实现较小，便于按需修改。** UI、壁纸和机型适配集中在少量 Java 文件中，没有第三方运行时库；v0.2.0 的签名 APK 约 1.95 MB。安装包小不等于已经证明它比其他桌面更快或更省内存。

当前最适合的是：愿意保留原桌面、主要使用少数应用和 HDMI 设备、接受初期兼容性范围的用户。

v0.2.0 新增实验性开机自动进入，需要适配机型、一次 ADB 配置和应用内开关，详见[专门教程](BOOT-START.md)。如果你需要跨品牌通用适配、在电视上自由增删排序入口、联网图库或直接导入照片，当前版本还不能满足这些需求。cleanYourTV 和 CleanFrame 在各自平台上也有归藏电视没有保留的配置能力。

## 5. 安装前先确认兼容性

已验证配置如下：

| 项目 | 配置 |
| --- | --- |
| 型号 | MiTV-MTSU0 |
| 商品名称 | 小米电视 S55 Mini LED 2026 至尊版 |
| 系统 | Android 14 / API 34 |
| 固件 | OS3.0.119.0.UTSMATV |
| 桌面渲染尺寸 | 1920 × 1080，density 320 |

最低编译要求为 Android 8 / API 26，**不是所有 Android 8 及以上电视均已兼容的承诺**。其他机型可能能显示桌面、打开已安装应用，但专用 HDMI、信号源及小米原桌面入口不一定可用。

实机已检查过常用入口、遥控器焦点、固定壁纸保存和轮播。私人前身及公开版验证范围分别记录在[兼容性说明](COMPATIBILITY.md)与[首次公开发布记录](changes/2026-10-20-public-release.md)中。v0.1.1 增加内置照片；v0.2.0 移植私人同源实现中已验证的开机自动进入。公开签名 v0.2.0 APK 未重新进行完整重启测试，具体范围见[开机说明](BOOT-START.md)。

小爱语音、实际手机投屏播放、直播播放、HDMI 音频、游戏延迟和长期待机尚未完成全流程验证。“保留系统组件”不等于这些功能全部经过测试。

## 6. 怎样安装？

### 方法一：使用电视支持的本地安装方式

1. 打开 [v0.2.0 发布页](https://github.com/op7418/guizang-tv/releases/tag/v0.2.0)。
2. 在 Assets 中下载 **`guizang-tv-v0.2.0.apk`**。`Source code` 是源码压缩包，不能直接当作电视应用安装。
3. 按电视固件支持的方式，通过 U 盘或本地文件传输把 APK 送到电视。
4. 打开 APK，按系统提示允许对应安装来源并完成安装。不同固件对文件管理器及第三方安装的限制不同。
5. 回到小米原桌面的应用列表，打开 **“归藏电视”**。

如果电视不允许这类本地安装，可以使用下面的 ADB 方式。

### 方法二：通过电脑 ADB 安装

先在电脑安装 Android SDK Platform-Tools，确认终端运行 `adb version` 能显示版本；电脑与电视连接同一家庭局域网，在电视设置中开启固件提供的调试功能。

以下是操作模板，**请将 `TV_IP:PORT` 替换为电视实际的地址和调试端口**。部分固件使用 5555，但不能假设所有电视都相同。若系统提供配对码式“无线调试”，需先按该系统流程配对，再连接显示的调试端口。

```sh
adb connect TV_IP:PORT
adb devices
adb -s TV_IP:PORT install -r "/path/to/guizang-tv-v0.2.0.apk"
```

首次连接时在电视上确认电脑的调试授权。设备列表状态应为 `device`；若是 `unauthorized`，先处理电视上的授权提示。安装命令输出 `Success` 后，再到电视的应用列表打开应用。

ADB 只用于安装或调试。完成后可以断开连接、关闭电视调试，正常使用桌面不依赖电脑连接。

### 更新或结束试用

同一官方签名的后续版本可使用覆盖安装，通常保留偏好设置。自行构建的 Debug 包使用不同签名，不能直接覆盖正式发布包。

遇到签名冲突时，先确认安装包来源；不要把卸载重装当成保留设置的升级方式。开发者可以为自用版本设置独立 `applicationId`，或持续使用自己的同一套签名。

未配置开机自动进入时，不再需要可在系统应用管理中卸载“归藏电视”。已经配置的用户先按[关闭与恢复说明](BOOT-START.md)处理系统目标与缓存，避免直接降级到没有启动判断入口的旧版。此前的私人“简洁桌面”及上游应用使用不同包名，不会被公开版覆盖，其设置也不会自动迁移。

## 7. 日常怎么操作？

### 首页入口

| 位置 | 名称 | 确认后的动作 |
| --- | --- | --- |
| 左侧第 1 项 | PlayStation 5 | 适配机型上切到 HDMI 2 |
| 左侧第 2 项 | Apple TV | 适配机型上切到 HDMI 1 |
| 左侧第 3 项 | 哔哩哔哩 | 打开已安装的对应电视 App |
| 左侧第 4 项 | 小米投屏 | 打开小米投屏入口 |
| 左侧第 5 项 | 相册 | 打开小米相册 |
| 左侧第 6 项 | 小米原桌面 | 返回小米原桌面 |
| 右下角 | 壁纸设置 | 选择图片、模式与轮播间隔 |
| 右下角 | 全部应用 | 查看并打开可启动的已安装应用 |
| 右下角 | 其他信号源 | 打开适配机型的原生信号源面板 |
| 右下角 | 设置 | 选择电视系统设置或开机自动进入选项 |

未安装对应 App 时会显示提示，不会自动下载安装。手机投屏需要继续按照小米投屏自身的说明完成连接；直播可沿用原桌面、相应应用或原生信号源入口。

### 遥控器

| 按键 | 操作 |
| --- | --- |
| 上 / 下 | 在当前区域中移动焦点 |
| 右 | 从左侧列表进入右下角操作区 |
| 左 | 从操作区回到上次选中的主列表项目 |
| 确认 | 执行当前项目；仅移动焦点不会切换 HDMI |
| 返回 | 关闭面板；从操作区回列表；适配机型上从主列表回原桌面 |
| Home | 由系统原有设置处理，本应用不拦截 |

已测试的 HyperOS 固件会忽略第三方默认桌面选择。普通使用方式仍是从应用列表打开“归藏电视”。希望开机自动进入的用户，可按[实验功能说明](BOOT-START.md)完成配置；Home 键仍按原系统设置工作。

### 固定一张壁纸

1. 按右进入操作区，选择“壁纸设置”。
2. 移动到喜欢的缩略图，按确认。
3. 选择图片会自动切到固定模式；按返回关闭面板。

也可以直接选择“固定壁纸”，保留当前背景。

### 开启或调整轮播

1. 打开“壁纸设置”，选择“自动轮播”。
2. 选择“间隔”，从 1、5、15、30 分钟中选一个。
3. 按返回回到首页，等待完整间隔后切换下一张。

默认每 5 分钟顺序轮播，最后一张之后回到第一张。离开首页后不继续后台换图；在设置面板中等待也不会触发轮播。

### 开机自动进入

在已适配机型上，先按[完整教程](BOOT-START.md)通过 ADB 配置系统启动目标，再到“设置 → 开机自动进入”开启开关。默认关闭；每次完整开机只尝试一次，不需要悬浮窗权限或无障碍服务。

## 8. 如何按自己的需求修改？

这部分面向愿意构建 Android 项目的用户。日常使用官方安装包不需要完成这些步骤。

### 8.1 构建环境与命令

需要 Git、JDK 17、Gradle 8.9、Android SDK Platform 34 和 Build Tools 34.0.0。仓库未提供 Gradle Wrapper，使用已安装的 `gradle`，不要直接照抄其他项目的 `./gradlew` 命令。

以下为 macOS / Linux shell 示例，环境路径替换为本机实际位置：

```sh
git clone https://github.com/op7418/guizang-tv.git
cd guizang-tv
export ANDROID_HOME=/path/to/Android/sdk
export JAVA_HOME=/path/to/jdk-17
gradle :app:assembleDebug :app:testDebugUnitTest :app:lintDebug
```

输出为 `app/build/outputs/apk/debug/app-debug.apk`。首次构建需要联网获取构建与测试依赖。

### 8.2 换应用或调整 HDMI 接线

在 [FrameHomeActivity.java](../app/src/main/java/io/github/op7418/guizangtv/FrameHomeActivity.java) 中找到这些配置：

```java
addRow(list, "PlayStation 5", "HDMI 2", () -> hdmi(2));
addRow(list, "Apple TV", "HDMI 1", () -> hdmi(1));
addRow(list, "哔哩哔哩", null, () -> openPackage("com.xiaodianshi.tv.yst"));
```

如果 PS5 实际插在 HDMI 1，需要同时修改显示标签和调用参数，例如：

```java
addRow(list, "PlayStation 5", "HDMI 1", () -> hdmi(1));
```

替换应用时，修改显示名称与 `openPackage(...)` 中的实际包名，并确认电视已经安装了可以启动的对应应用。可以通过 `adb -s TV_IP:PORT shell pm list packages` 查询包名。

初次修改建议替换现有六项中的一项。直接增加第七项还需要调整布局高度、焦点关系及保存选中项的边界；当前不是动态首页编辑器。

HDMI 适配当前只接受端口 1 和 2。要支持其他端口或机型，需检查 [XiaomiControls.java](../app/src/main/java/io/github/op7418/guizangtv/XiaomiControls.java) 中的系统接口、端口映射、组件与权限，并做实机验证；只放宽机型判断不算完成适配。

### 8.3 打包自己的照片

电视上的“选择壁纸”仅指选择 APK 中已有的图片，当前没有电视端导入文件按钮。

准备一个包含 **1–15 张 JPEG / PNG / WebP** 的文件夹，在项目根目录执行：

```sh
python3 -m venv .venv
.venv/bin/pip install Pillow
.venv/bin/python scripts/prepare_wallpapers.py "/path/to/your/wallpapers"
gradle :app:assembleDebug
```

Windows 环境需将虚拟环境的可执行文件路径改为 `.venv\Scripts\` 下的对应程序。

脚本保留原图，按文件名顺序生成最长边不超过 1920 像素的照片副本及 320 × 180 缩略图，并去除 EXIF。文件名会作为电视端显示的照片名称；横向图片通常更适合电视背景，显示时可能发生居中裁切。

生成文件在 `app/src/main/assets/wallpapers/local/`，被 Git 忽略。重新构建并安装后，应用优先使用这组图片；默认五张照片仍保留在安装包内。

再次运行脚本时，旧的生成结果会移到 `.wallpaper-backups/`，不会删除源照片。要恢复默认五张图，把 `local/` 文件夹移到项目目录外备份，再重新构建。没有可用照片时，程序可回退到生成的渐变背景。

自行分发 APK 前，应检查自己加入图片的授权。Git 忽略本地照片并不意味着它们不会进入你本地生成的 APK。

### 8.4 主要代码位置

| 文件 | 职责 |
| --- | --- |
| [FrameHomeActivity.java](../app/src/main/java/io/github/op7418/guizangtv/FrameHomeActivity.java) | 首页布局、入口、遥控器导航和应用启动 |
| [XiaomiControls.java](../app/src/main/java/io/github/op7418/guizangtv/XiaomiControls.java) | 小米机型与系统入口适配 |
| [FrameWallpapers.java](../app/src/main/java/io/github/op7418/guizangtv/FrameWallpapers.java) | 壁纸加载、设置面板、切换与偏好保存 |
| [WallpaperCycle.java](../app/src/main/java/io/github/op7418/guizangtv/WallpaperCycle.java) | 轮播间隔与选中项边界 |
| [BootStart.java](../app/src/main/java/io/github/op7418/guizangtv/BootStart.java) / [BootGateActivity.java](../app/src/main/java/io/github/op7418/guizangtv/BootGateActivity.java) | 开机选项、状态与一次性启动入口 |
| [prepare_wallpapers.py](../scripts/prepare_wallpapers.py) | 本地壁纸打包工具 |

## 9. 常见问题

**按 Home 为什么仍是小米原桌面？**

这是当前试用方式的正常行为。应用不拦截 Home，已测固件也没有按第三方默认桌面选择切换。

**PS5 或 Apple TV 入口没有画面？**

先从电视原生信号源菜单确认设备已开机、线缆和端口正确。若原生入口正常而归藏电视提示不可用，可能是机型未适配或固件接口不同；固定名称不会自动匹配接线。

**ADB 连接失败？**

确认实际 IP、调试端口、同一局域网及电视授权状态。开启 USB 调试不必然意味着网络端口已经开放；来宾网络隔离也可能阻止电脑连接电视。

**想增加爱奇艺、腾讯视频或其他应用？**

先正常安装对应电视应用，可以从“全部应用”打开。要放进左侧固定列表，当前需按上节修改源码并重新构建。

**壁纸为什么没换？**

确认处于“自动轮播”，关闭壁纸设置并在首页等待完整间隔。切到其他 App 后不累计后台时间；如果选过某张缩略图，需要重新开启自动轮播。

**这是三星 The Frame 的 Art Mode 吗？**

不是。这里实现的是桌面照片背景与轮播，不包含三星 Art Mode、专门的待机画框模式或相关省电能力。

**能彻底去广告、提升游戏帧率吗？**

项目没有这些功能或性能结论。它改变首页与进入设备、应用的路径，不改变外部设备的视频输出，也不清理第三方应用内容。

## 10. 开源许可与分享时可用的介绍

代码使用 MIT 许可并保留上游署名，详见 [LICENSE](../LICENSE) 和 [NOTICE](../NOTICE.md)。五张内置照片适用 **Unsplash License**，不是 MIT 代码素材，也不是无版权图片；作者、原始链接和处理方式见[壁纸预览与署名](WALLPAPERS.md)。

可以用下面这段介绍项目：

> 我给自己的小米电视做了一个简洁桌面，叫「归藏电视」。它从 cleanYourTV 的本地定制起步，参考了 CleanFrame 的照片背景和大字列表设计，把常用的 PS5、Apple TV 信号源直接放到首页，并加入哔哩哔哩、小米投屏、相册和壁纸轮播。安装后从应用列表打开，保留小米原桌面。项目已经开源，目前重点适配 MiTV-MTSU0，其他机型还需要验证。