Warning
本 Android TV 客户端是一个 Vibe Coding 项目，代码主要由 AI 辅助生成。 代码质量、稳定性与设备兼容性均没有保证，请在使用前自行评估并承担风险。
Note
本项目接受完全由 AI 生成的 Pull Request（纯 AI PR）。 提交者无需手写代码，但仍需说明改动目的、完成必要验证，并对提交内容负责。
这是 Kaloscope 项目的原生电视客户端，面向仅使用遥控器的 Android TV 设备。 客户端连接到用户自行部署的服务端，提供媒体库浏览、网络资源搜索，以及电视端视频播放、图片与文本阅读能力。
本项目不包含服务端，也不会在本地提供媒体管理服务。使用前需要准备一台客户端可以访问的服务器。
- 管理多个服务器，并分别保存登录状态
- 浏览最近观看、媒体库、媒体详情及分季分集内容
- 通过服务端索引器搜索和筛选网络资源
- 播放本地与网络视频，支持 HLS、DASH、转码回退和续播
- 阅读图片与文本资源，支持翻页、缩放和排版设置
- 播放器支持章节、选集、字幕、倍速、自动连播和弹幕
- Android TV 设备，Android 6.0（API 23）或更高版本
- 电视设备可访问的 Kaloscope 服务端
- 具备所需媒体库或索引器权限的服务端账号
服务端安装方式参见部署指南。
- 前往 GitHub Releases 下载最新版本的 APK。
- 将 APK 传输并安装到 Android TV 设备，按系统提示允许安装即可。
- 打开应用，添加服务器地址并登录账号。
安装新版本时直接覆盖安装即可。不要先卸载旧版本，以免丢失本机保存的服务器和登录状态。
本项目采用单 app 模块、单 Activity 和 Jetpack Compose UI。主要代码位于 app/src/main/java/org/kaloscope/tv：
android-tv/
├── app/
│ └── src/
│ ├── main/java/org/kaloscope/tv/
│ │ ├── app/ # 应用外壳、启动流程、依赖注入与导航
│ │ ├── core/ # 通用模型、网络、存储、设计系统、播放与阅读策略
│ │ ├── data/ # Repository、远程 DTO、映射与持久化适配器
│ │ └── feature/ # 页面、ViewModel 与功能协调器
│ ├── test/ # JVM 单元测试和网络契约测试
│ └── androidTest/ # Compose UI、焦点、截图与设备测试
├── gradle/
│ └── libs.versions.toml # 依赖和插件版本目录
└── .github/workflows/ # GitHub Actions 工作流
主要功能包包括服务器配置与登录、首页、网络搜索、媒体库、媒体详情、播放器、阅读器和设置。
页面级 ViewModel 通过 StateFlow 暴露不可变 UI 状态，复杂状态转换由可测试的协调器或策略类承载。
实际依赖版本以 Gradle Version Catalog 为准。
| 类别 | 主要组件 | 用途 |
|---|---|---|
| 语言与构建 | Kotlin、Gradle、Java 17 | Android 应用开发与构建 |
| TV UI | Jetpack Compose、Compose for TV、TV Material | 单 Activity 的遥控器友好界面 |
| 导航 | Navigation 3 | 使用可序列化路由管理页面栈 |
| 依赖注入 | Hilt | 组装网络、存储、Repository 和 ViewModel |
| 网络与序列化 | Retrofit、OkHttp、Kotlinx Serialization | 调用服务端 API 并解析 JSON |
| 异步状态 | Kotlin Coroutines、StateFlow | 生命周期内的异步任务与 UI 状态流 |
| 本地存储 | Preferences DataStore、Android Keystore | 保存客户端设置并保护登录令牌 |
| 图片 | Coil | 加载海报、背景图和头像等服务端图片 |
| 播放 | AndroidX Media3 | ExoPlayer、MediaSession、HLS、DASH 和 Compose 播放界面 |
| 弹幕 | AkDanmaku | 播放器弹幕渲染与同步 |
| 测试 | JUnit、Coroutines Test、MockWebServer、Compose UI Test | 策略、数据、API 契约和 TV 交互验证 |
- JDK 17
- Android SDK，包含项目所需的 API 37 平台和 Build Tools
- Android Studio 或可执行 Gradle Wrapper 的命令行环境
- 可选：Android TV 模拟器或实体设备，用于焦点、播放和阅读验证
仓库已经包含 Gradle Wrapper，无需单独安装 Gradle：
git clone https://github.com/kaloscope/android-tv.git
cd android-tv
./gradlew :app:assembleDebugDebug APK 生成在：
app/build/outputs/apk/debug/app-debug.apk
常用验证命令：
# JVM 单元测试与网络契约测试
./gradlew :app:testDebugUnitTest
# Release 变体静态检查
./gradlew :app:lintRelease
# 本地 Release 构建；未配置签名变量时生成未签名 APK，配置签名时必须同时提供全部四项变量
./gradlew :app:assembleRelease涉及遥控器焦点、按键、播放器、阅读器或设备性能的改动，还应在 Android TV 模拟器或实体设备上验证。 更新模拟器或实体设备上的现有安装时应保留应用数据，避免通过卸载或清空数据破坏登录状态。
欢迎提交 Issue 和 Pull Request，包括完全由 AI 生成的 PR。提交前请阅读 AGENTS.md 中的项目边界，并至少说明：
- 要解决的问题以及修改范围
- 是否会影响界面、网络、存储、播放、阅读、遥控器或焦点行为
- 实际执行的构建、测试或设备验证
- 仍未验证的路径和已知风险
请勿提交服务器地址、账号、令牌、媒体路径、签名文件、密码或其他私有配置。 无论代码由人类还是 AI 生成，提交者都应先审阅最终 diff，并对提交内容负责。
本项目基于 MIT 开源协议发布。