TV Launcher 设计方案

相对 v2（GPT 版）的改动

"焦点卡片放大与标题显示方式、背景是否随焦点变化"在 Google TV 主页本身没有找到一手说明；本方案依据的是 developer.android.com 的 TV 焦点系统与沉浸式列表规范。

动效：两套弹簧 token

数值与 material3 1.5.0-alpha25 源码中的 ExpressiveMotionTokens / StandardMotionTokens 逐项一致，代码直接使用 MotionScheme.expressive()。原型右侧的"动效方案"可切换 Expressive、Standard 和减弱三种，曲线由这些参数实时采样生成。

形状、字重与组件

material3 1.5.0-alpha25 里的 Expressive API

上面的样例使用与原型相同的实时配色，在原型里移动焦点时会一起变色。

相对 v3.2 的更正

• 版本基线：由 74b135d 更新到 6182cf2。
• guard：v3.2 把无障碍服务和通知监听写成 guard 变体独有。实际上 guard flavor 只去掉 HOME 过滤器，这些组件都在主清单里。
• Lite：是独立模块，不是 productFlavor。
• 手机整理：aerial-tv 用固定端口 8790 和持久令牌，应用运行期间一直监听。v3.2 §14 的"随机端口、一次性令牌、10 分钟会话"是本方案自己的选择，不是参考做法，现已分开写。
• 4K 界面画布：UhdCanvas 默认关闭，v3.2 把它列为实现要点；本方案不采用。
• 内置壁纸：14 张是程序绘制的，不是图片素材。
• 首页排序：aerial-tv 没有启动次数统计，首页按用户排列。

行的顺序：Hero → 继续观看（无内容时隐藏）→ 片单（只存本机，空时隐藏；Hero 的「片单」按钮加入或移出）→ 你的应用（始终存在；没有内容行时它成为第一行）→ 已批准的频道（含系列应用的频道，§11）→ 小组件速览 → 行末的"管理频道"入口。没有任何合法内容来源时，不显示占位推荐，首页直接从应用行开始。

文件夹

• 磁贴：文件夹在"你的应用"行和应用页中各占一个位置。磁贴内按 3×3 排列前 9 个应用的缩略图标，下方显示文件夹名；焦点规则与应用图标相同（§09）。
• 新建与命名：整理模式下对应用选"移到文件夹" → "新建文件夹"。电视上从预设名称中选："影音""游戏""工具""学习""其他"；任意名称在手机整理页修改（§14）。
• 打开：OK 打开文件夹浮层，主页在后面模糊变暗，应用按主页磁贴尺寸排列；BACK 关闭，焦点回到文件夹磁贴。
• 清空即删除：最后一个应用移出后，文件夹自动消失。

来源与规则

• 低彩度来源（灰、白、黑的图标，如原型中的"文件管理"）：MCU 默认会回退到 #4285F4。桌面改为保持当前全局主题，只把局部光环换成中性色，避免焦点经过一个灰色图标时整屏跳成蓝色。
• 节流：焦点停留 180ms 才切换全局主题；按住方向键连续滚动期间不切换，松开 180ms 后再算；新旧种子色差 ΔE < 6 时跳过过渡。
• 变体：全局界面默认 TonalSpot，色相与内容一致、彩度克制；Hero 遮罩可以用 Content 变体，更贴近海报。Expressive 变体会把主色相旋转 240°，界面颜色不再跟内容同色相，只作为个性化选项。色彩规范版本跟随 MCU 的 SPEC_2025（MaterialKolor 6.0 的默认值）。
• 对比度：前景与容器靠色调差保证对比度（如 onPrimary T20 对 primary T80）。设置中提供对比度级别 0 / 0.5 / 1.0，对应 DynamicScheme 的 contrastLevel。
• 不取色的情况：儿童模式与长辈模式（§14）锁定固定种子色；用户关闭"动态配色"时使用固定种子色；DRM 视频帧抓取失败时保持原主题。

三个作用范围

当前种子色的色调板

种子 —

Primary

Secondary

Tertiary

Neutral

色块下的数字是色调（0 黑，100 白）。原型用 CIELAB-LCh 近似 HCT 来演示：色调维度与 HCT 完全一致，色相和彩度是近似值。生产代码使用 MCU 的 HCT。

代码骨架

// core:dynamiccolor —— 依赖 com.materialkolor:material-color-utilities（MCU 的 Kotlin 移植，包名以 6.0.0 为准）
class SeedExtractor(private val dao: SeedCacheDao, private val io: CoroutineDispatcher) {
  suspend fun seedFor(key: SourceKey, load: suspend () -> Bitmap?): SeedResult = withContext(io) {
    dao.get(key.value, ALGO_VERSION)?.let { return@withContext it.toResult() }
    val bmp = load() ?: return@withContext SeedResult.Unavailable
    val small = Bitmap.createScaledBitmap(bmp, key.sampleW, key.sampleH, true)
    val px = IntArray(small.width * small.height).also { small.getPixels(it, 0, small.width, 0, 0, small.width, small.height) }
    val opaque = px.filter { Color.alpha(it) >= 250 }.toIntArray()
    val quantized = QuantizerCelebi.quantize(opaque, 128)
    val ranked = Score.score(quantized, desired = 1, fallbackColorArgb = NO_SEED, filter = true)
    val result = if (ranked.first() == NO_SEED) SeedResult.LowChroma else SeedResult.Seed(ranked.first())
    dao.put(key.value, ALGO_VERSION, result); result
  }
}

// 全局主题：一个 Animatable 驱动插值，颜色在绘制阶段读取，过渡期间不触发重组
class ThemeController(private val scope: CoroutineScope) {
  private val progress = Animatable(1f)
  var from: LauncherColors = Defaults; private set
  var to: LauncherColors = Defaults; private set
  fun colors(): LauncherColors = lerp(from, to, progress.value)   // 在 drawBehind / graphicsLayer 中调用
  private var job: Job? = null
  fun onFocusSettled(seed: SeedResult, style: Variant) {
    if (seed !is SeedResult.Seed) return                         // 低彩度：保持当前主题
    val next = LauncherColors.from(SchemeFactory.dark(seed.argb, style, contrast = settings.contrast))
    if (deltaE(next.primary, to.primary) < 6f) return
    job?.cancel(); from = colors(); to = next
    job = scope.launch { progress.snapTo(0f); progress.animateTo(1f, LauncherMotion.ambientColor()) }
  }
}

材质 token

tint 颜色全部来自当前动态配色，所以玻璃会随焦点变色。可以在原型右侧切换 T1 / T2 / T3 对比效果。

三档渲染

val hazeState = rememberHazeState()
CompositionLocalProvider(LocalHazePerformanceMode provides tier.hazeMode) {   // T1 设备默认 HazePerformanceMode.Performance
  Box(Modifier.fillMaxSize()) {
    AmbientBackdrop(Modifier.fillMaxSize().hazeSource(hazeState, zIndex = 0f, key = "backdrop"))
    HomeContent(Modifier.fillMaxSize().hazeSource(hazeState, zIndex = 1f, key = "content"))

    // L4：只取背景层，焦点动画不会让顶栏每帧重新模糊
    val backdropOnly = HazeInput.Sources(hazeState, selection = HazeSourceSelection.Behind.where { it.key == "backdrop" })
    TopBarPill(Modifier.glass(tier, backdropOnly, LauncherGlass.chrome(colors)))

    // L6：模态面板，背后静止，取全部来源
    if (quickSettingsOpen) QuickSettings(Modifier.glass(tier, HazeInput.Sources(hazeState), LauncherGlass.panel(colors)))
  }
}

object LauncherGlass {
  fun chrome(c: LauncherColors) = HazeBlurStyle {
    blurRadius(24.dp)
    noiseFactor(0.12f)
    colorEffects(listOf(HazeColorEffect.tint(c.surfaceContainer.copy(alpha = 0.50f)), HazeColorEffect.tint(c.primary.copy(alpha = 0.06f))))
    fallbackColorEffect(HazeColorEffect.tint(c.surfaceContainerHigh.copy(alpha = 0.94f)))
  }
}

// T1 / T2 / T3 统一入口
fun Modifier.glass(tier: GlassTier, input: HazeInput, style: HazeBlurStyle): Modifier = when (tier) {
  GlassTier.Live   -> hazeBlur(input = input, style = style)
  GlassTier.Frozen -> frozenGlass(LocalFrozenBackdrop.current, style.tintColors())   // 预模糊位图按 positionInRoot 偏移绘制
  GlassTier.Solid  -> hazeBlur(input = input, style = style.then { blurEnabled(false) })
}

tintColors() 与 frozenGlass 为项目内扩展，不属于 Haze。HazeInput.Backdrop(state) 是官方示例写法，会优先走平台原生 backdrop 路径（仅新版本平台且默认关闭），否则回落到 Sources；本方案直接用 Sources 以便按 key 选择来源。

字号（以 960dp 宽画布计）

必须设计的非理想状态

• 列表：使用标准 LazyRow / LazyColumn / LazyVerticalGrid。TvLazy 系列在 2025-01 已被移除，官方建议用标准 Lazy 布局，并用 BringIntoViewSpec 实现焦点定位。
• 定位：行内焦点停在左侧 48dp 处，纵向焦点行停在 y 236。行尾不留空白，最后几项在可见区内移动焦点。
• 记忆：每行用稳定 key 记住最后的焦点项（应用用 ComponentName，节目用 来源包名 + 外部 ID，小组件用 appWidgetId）。纵向移动时回到目标行记住的那一项，与 Google TV 一致。
• 连按：长按方向键时最快每 80ms 移动一次；连按期间暂停背景切换和全局取色，松开后再更新。
• 恢复：项目消失时依次落到同行下一项、上一项、行标题、主页默认项；进程被杀后只恢复页面、行和 key，不恢复对话框、授权流程或拖拽中间状态。

// 行内焦点停在左侧 keyline（BringIntoViewSpec 为 ExperimentalFoundationApi，以锁定版本为准）
val KeylineSpec = object : BringIntoViewSpec {
  override fun calculateScrollDistance(offset: Float, size: Float, containerSize: Float): Float {
    val keyline = 0f                       // 内容区已有 48dp 内边距
    return offset - keyline
  }
}
CompositionLocalProvider(LocalBringIntoViewSpec provides KeylineSpec) {
  LazyRow(contentPadding = PaddingValues(horizontal = 48.dp), horizontalArrangement = Arrangement.spacedBy(18.dp)) { /* … */ }
}

按键音效

• 声音：AudioManager.playSoundEffect(int)。焦点移动用 FX_FOCUS_NAVIGATION_UP / DOWN / LEFT / RIGHT，OK 用 FX_KEY_CLICK，BACK 在 API 33+ 用 FX_BACK，到边缘无法移动时用 FX_KEYPRESS_INVALID。
• 跟随系统：这个重载按系统"按键音"设置（Settings.System.SOUND_EFFECTS_ENABLED）决定是否发声，桌面不另设总开关。
• 只响应用户操作：最近 250ms 内收到过方向键、OK 或 BACK 的按下事件才发声。程序移动焦点（恢复记忆、项目消失后的落点、Hero 自动轮播）以及触屏、鼠标操作都不发声。

触屏与鼠标

• 点按：先把焦点移到被点的项，再按 OK 的规则激活（同样 500ms 去重）。鼠标左键相同。
• 长按：达到系统长按时长（ViewConfiguration.getLongPressTimeout()）打开该项的上下文菜单，等同长按 OK；鼠标右键相同。
• 拖动：行内横向、页面纵向都可拖动滚动，松手后按速度惯性滑动。拖动不移动焦点，背景与全局主题继续跟随当前焦点项。
• 浮层：点在浮层面板之外关闭浮层，等同 BACK；面板内的触摸不会穿透到下面的主页。
• 与遥控器混用：遥控器按键按下尚未抬起时，触摸不结束这次按压。

数据来源

规则

• 整表读取，本地过滤：三张表各查一次，不带 selection，在内存中按频道分组。数据量通常是几百行，代价可以接受。
• 审批状态自己存：新建频道的 browsable 默认是 0，第三方桌面又不能写这一列，所以"哪些频道显示在主页"记录在桌面自己的 ChannelApproval 表里。新频道出现时，在行末"管理频道"入口加角标，不弹窗打断。
• 用户移除节目：PREVIEW_PROGRAM_BROWSABLE_DISABLED、WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED 是受保护广播，第三方桌面发不出，移除只在本地生效；系列应用通过直连回传（见下文）。
• App 请求显示频道：有两条路。requestChannelBrowsable()（publishDefaultChannel() 内部也会调用）由系统发出受保护广播 CHANNEL_BROWSABLE_REQUESTED，逐个发给声明了接收器的应用，带频道 id 和请求方包名；桌面注册接收器即可收到（TvInputManagerService 源码）。ACTION_REQUEST_CHANNEL_BROWSABLE 是 Activity Intent，桌面声明处理它的确认页，确认后写审批表并返回 RESULT_OK；系统桌面仍安装时由谁接收，需在 M0 验证。
• 刷新：在 TvContract 的三个 URI 上注册 ContentObserver（只在前台注册），防抖 500ms，结果写入 Room；冷启动先显示缓存。
• 启动安全：INTENT_URI 来自其他 App 写入的数据。解析后把 package 固定为该行的 package_name，清掉 URI 授权标志，捕获 ActivityNotFoundException。

字段到界面

class ChannelRepository(private val cr: ContentResolver, private val approvals: ChannelApprovalDao) {
  // 无 ACCESS_ALL_EPG_DATA 时，带 selection 的查询会抛 SecurityException：整表读取后在本地过滤
  suspend fun previewRows(): List<ChannelRow> = withContext(Dispatchers.IO) {
    val channels = cr.readAll(TvContractCompat.Channels.CONTENT_URI, Channel.PROJECTION, Channel::fromCursor)
      .filter { it.type == TvContractCompat.Channels.TYPE_PREVIEW }
    val programs = cr.readAll(TvContractCompat.PreviewPrograms.CONTENT_URI, PreviewProgram.PROJECTION, PreviewProgram::fromCursor)
      .groupBy { it.channelId }
    val approved = approvals.approvedKeys()                    // 桌面自己的审批表：包名 + internalProviderId
    channels.filter { ChannelKey(it) in approved }
      .map { ch -> ChannelRow(ch, programs[ch.id].orEmpty().sortedByDescending { it.weight }) }
  }
}

private fun <T> ContentResolver.readAll(uri: Uri, projection: Array<String>, map: (Cursor) -> T): List<T> =
  query(uri, projection, null, null, null)?.use { c -> buildList { while (c.moveToNext()) add(map(c)) } }.orEmpty()

// API 23–25：旧版推荐通知
class RecommendationListener : NotificationListenerService() {
  override fun onNotificationPosted(sbn: StatusBarNotification) {
    val n = sbn.notification
    if (n.category != Notification.CATEGORY_RECOMMENDATION) return
    legacyRepo.upsert(sbn.packageName, sbn.key, n.extras, RecommendationExtender(n), n.contentIntent)
  }
  override fun onNotificationRemoved(sbn: StatusBarNotification) = legacyRepo.remove(sbn.key)
}

系列应用：myBV、mydv、mytv-android

三个应用已经通过 TvProvider 发布频道，下表按 2026-11-02 的源码整理。接入原则：数据仍走上面的 A，这样它们在 Google TV 和原生 Android TV 桌面上照常工作；第三方桌面做不到的几件事，用一条系列内部的直连通道补上，不另起一套数据格式。

在本桌面上要处理的问题

• 台标卡：mytv-android 的收藏按 1:1 台标卡显示，底色取台标颜色。焦点预览只在 T1 设备上静音播放直播流，离开焦点立即释放。
• 混排比例：mydv 同一行里有 2:3 和 16:9，按下方字段表"行高统一、宽度按比例"处理，不裁成同一比例。
• 继续观看：myBV 和 mydv 目前没有 Watch Next。建议 myBV 把历史记录里没看完的视频写成 WATCH_NEXT_TYPE_CONTINUE，带进度和真实的最后观看时间，这样在本桌面和原生 Android TV 桌面的继续观看里都会出现；Google TV 上新的继续观看接入要走 Engage（见上文）。
• 小组件：mytv-android 的"继续观看"小组件和 mydv 的 Glance 小组件按 §12 的第三方流程添加，不需要单独处理。

系列直连协议 v1

// 桌面侧
object SeriesBridge {
  const val ACTION = "com.github.mytv.action.LAUNCHER_BRIDGE"
  private val TRUSTED = mapOf(                                   // 包名 → 签名证书 SHA-256，构建时注入
    "com.github.mytv.bv" to Certs.MYBV, "dev.aaa1115910.bv" to Certs.MYBV,
    "com.github.mytv.dv" to Certs.MYDV, "com.github.mytv.android" to Certs.MYTV,
  )
  fun isSeries(ctx: Context, pkg: String) = TRUSTED[pkg]?.let { it == ctx.packageManager.certSha256(pkg) } == true

  fun sources(ctx: Context): List<ProviderInfo> =
    ctx.packageManager.queryIntentContentProviders(Intent(ACTION), 0)
      .map { it.providerInfo }.filter { isSeries(ctx, it.packageName) }

  fun call(ctx: Context, p: ProviderInfo, method: String, arg: String? = null): Bundle? =
    runCatching { ctx.contentResolver.call(Uri.parse("content://${p.authority}"), method, arg, null) }.getOrNull()
}

// App 调用 requestChannelBrowsable() 时由系统发出；受保护广播，只有系统能发，所以导出也安全
// <receiver android:name=".ChannelRequestReceiver" android:exported="true">
//   <intent-filter><action android:name="android.media.tv.action.CHANNEL_BROWSABLE_REQUESTED"/></intent-filter>
// </receiver>
class ChannelRequestReceiver : BroadcastReceiver() {
  override fun onReceive(ctx: Context, intent: Intent) {
    val channelId = intent.getLongExtra(TvContract.EXTRA_CHANNEL_ID, -1L)
    val pkg = intent.getStringExtra(TvContract.EXTRA_PACKAGE_NAME) ?: return
    // 读频道行拿 internalProviderId；系列应用直接批准并调用 approve，其他应用记为待审
    ApprovalWorker.enqueue(ctx, pkg, channelId, autoApprove = SeriesBridge.isSeries(ctx, pkg))
  }
}

// App 侧：series-bridge 模块
abstract class LauncherBridgeProvider : ContentProvider() {
  abstract fun onInit()
  abstract fun onApprove(channelKey: String, approved: Boolean)
  abstract fun onHide(programKey: String)
  abstract fun rows(table: String): List<ContentValues>          // 有 TvProvider 时返回空列表

  override fun call(method: String, arg: String?, extras: Bundle?): Bundle? {
    LauncherTrust.check(context!!, callingPackage)                  // 证书不符抛 SecurityException
    when (method) {
      "hello" -> return bundleOf("version" to 1)
      "init" -> onInit()
      "approve" -> onApprove(arg!!, extras?.getBoolean("approved", true) ?: true)
      "hide" -> onHide(arg!!)
    }
    return null
  }
  override fun query(uri: Uri, projection: Array<String>?, selection: String?, args: Array<String>?, sort: String?): Cursor {
    LauncherTrust.check(context!!, callingPackage)
    return rows(uri.lastPathSegment!!).toCursor(projection)
  }
  // insert / update / delete 一律抛 UnsupportedOperationException
}

各应用的改动

• myBV：接入 series-bridge。init 调 syncRecommend(force) 和 syncToView(force)；approve 记入 TvChannelsStore，syncToView 的可见判断加上它；hide 按 aid 记墓碑；available() 为 false 时由 rows 返回同一批 PreviewProgram。
• mydv：接入 series-bridge；新增墓碑；isSupported() 为 false 时由 rows 返回数据。
• mytv-android：接收器和周期 Job 保持现状；接入 series-bridge，init 调 startJob()；频道设 internalProviderId；继续观看写真实的最后观看时间；删除记录改为按 internalProviderId。
• 三个应用现有的 TvProvider 发布逻辑都不用改，在其他桌面上的行为不变。

设备现状（AOSP 源码核实）

绑定授权：五条路径

每次绑定都先调用 bindAppWidgetIdIfAllowed()，失败时依次尝试后面的路径。授权一次之后，以后添加任何小组件都不再询问。原型里可以完整走一遍：「小组件」页 → 添加小组件 → 选一个第三方小组件。

添加流程

class WidgetBinder(private val ctx: Context, private val host: AppWidgetHost, private val awm: AppWidgetManager) {
  sealed interface Bind { data class Ok(val id: Int) : Bind; data class NeedsGrant(val id: Int) : Bind }

  fun bind(info: AppWidgetProviderInfo, options: Bundle): Bind {
    val id = host.allocateAppWidgetId()
    return if (awm.bindAppWidgetIdIfAllowed(id, info.profile, info.provider, options)) Bind.Ok(id) else Bind.NeedsGrant(id)
  }

  // 路径 2：只有设备真的有处理者时才用
  fun systemBindIntent(id: Int, info: AppWidgetProviderInfo): Intent? =
    Intent(AppWidgetManager.ACTION_APPWIDGET_BIND)
      .putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, id)
      .putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.provider)
      .putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER_PROFILE, info.profile)
      .takeIf { it.resolveActivity(ctx.packageManager) != null }
}

// 路径 3：Shizuku 以 shell 身份授权一次（IAppWidgetService 为隐藏接口，需要隐藏 API 存根，做法与 Shizuku 官方示例相同）
fun grantBindViaShizuku(ctx: Context) {
  val binder = ShizukuBinderWrapper(SystemServiceHelper.getSystemService(Context.APPWIDGET_SERVICE))
  IAppWidgetService.Stub.asInterface(binder)
    .setBindAppWidgetPermission(ctx.packageName, Process.myUid() / 100_000 /* userId */, true)
}

// API 26+：App 发起"添加到主屏幕"。Manifest：<action android:name="android.content.pm.action.CONFIRM_PIN_APPWIDGET"/>
class PinWidgetActivity : ComponentActivity() {
  override fun onCreate(state: Bundle?) {
    super.onCreate(state)
    val req = getSystemService(LauncherApps::class.java).getPinItemRequest(intent)
    if (req == null || !req.isValid || req.requestType != LauncherApps.PinItemRequest.REQUEST_TYPE_APPWIDGET) return finish()
    // 显示确认页 → 走同一个 WidgetBinder；绑定成功后：
    // req.accept(bundleOf(AppWidgetManager.EXTRA_APPWIDGET_ID to id))  —— accept 不负责绑定
  }
}

网格与尺寸

遥控器操作

宿主规则

• 生命周期：startListening() 放在 onStart，stopListening() 放在 onStop。启动时用 getAppWidgetIds()（API 26+）与 Room 对账，删除孤立的 ID。
• provider 变化：App 更新、卸载或停用时，刷新选择器，失效的实例显示占位卡，提供"移除"。
• 崩溃隔离：布局加载失败或 RemoteViews 异常时，只替换这一个小组件为占位卡，提供"重新加载"和"移除"。
• 玻璃位置：Frame 玻璃只画在 AppWidgetHostView 的后面和四周，不盖在上面。
• 内置小组件：时钟与天气（见下文"内置时钟与天气"）、正在播放（MediaSession，需要通知使用权）、日程、存储与网络。它们是 Compose 实现，作为第三方之外的补充，完整套用全局与局部主题。

内置时钟与天气

顶栏时钟、环境模式大时钟和"时钟与天气"小组件共用下列数据与规则。

让第三方小组件跟随桌面配色（API 31+）

AppWidgetHostView.setColorResources(SparseIntArray) 可以覆盖小组件引用的 system_accent1/2/3_* 和 system_neutral1/2_* 颜色资源。官方文档说明，调用它会让小组件完整重新加载，所以只在两种情况下调用：全局主题稳定 3 秒以上，或用户修改了壁纸 / 主题设置。焦点移动不触发。原型里的第三方小组件按同样的规则换色：主题稳定 3 秒后才变，并带一次"重新加载"的闪动。

// 色调板 → 系统颜色资源；每组 13 个，0 对应色调 100，1000 对应色调 0
private val TONES = intArrayOf(100, 99, 95, 90, 80, 70, 60, 50, 40, 30, 20, 10, 0)

@RequiresApi(31)
fun LauncherScheme.toWidgetColors() = SparseIntArray().apply {
  listOf(
    WidgetIds.accent1 to primaryPalette, WidgetIds.accent2 to secondaryPalette, WidgetIds.accent3 to tertiaryPalette,
    WidgetIds.neutral1 to neutralPalette, WidgetIds.neutral2 to neutralVariantPalette,
  ).forEach { (ids, palette) -> ids.forEachIndexed { i, id -> put(id, palette.tone(TONES[i])) } }
}
// WidgetIds.accent1 = intArrayOf(android.R.color.system_accent1_0, system_accent1_10, system_accent1_50, system_accent1_100 … system_accent1_1000)

themeController.settled.debounce(3_000).collect { scheme ->
  if (Build.VERSION.SDK_INT >= 31) hostViews.forEach { it.setColorResources(scheme.toWidgetColors()) }
}

API 34 新增的 system_primary_dark 等语义颜色资源能否同样被覆盖，待 M0 验证。

片源

自己的视频

• 上传：手机页把文件作为原始请求体发送（不用 multipart），服务端边收边写临时文件，不整段读入内存。写完后用 MediaExtractor 确认至少有一条视频轨，且 MediaCodecList 有对应的解码器；不满足时删除文件，手机页显示"无法播放这个视频"。
• 限额：单个文件 ≤ 2 GB；全部视频合计 ≤（已存视频 + 当前可用空间）的一半，且上传后可用空间不少于 1 GB；最多 64 段。先按 Content-Length 预检，超限直接拒绝；传输中超限立即中止并删除临时文件。
• 播放：与航拍共用环境模式的播放器和规则。没有预置关键帧，返回界面时的静态帧按"真机抓帧"的回退路径取得；keyColor 在上传完成后取一帧算好，存入 UserClip。

必应每日一图

• 接口：https://cn.bing.com/HPImageArchive.aspx?format=js&idx=0&n=8&mkt=zh-CN，每天最多请求一次。只使用 wp 为 true 的图片（必应标注可用作壁纸）。
• 分辨率：界面分辨率高于 1080p 时下载 urlbase 加 _UHD.jpg 的版本，否则用 url 给出的 1920×1080 版本。
• 保留：本机只保留最近 8 张；"最新"选项始终跟随最新一张。
• 署名：壁纸设置页里，当前图片下方显示必应返回的 copyright 原文。
• 只用于显示：图片存在应用私有目录，不提供导出、分享或从手机页下载，也不用作其他界面的素材。
• 开关与兜底：桌面设置可关闭此来源，关闭时删除已下载的图片；请求失败、来源关闭或没有可用图片时回到内置壁纸。风险见 §20。

真机抓帧

aerial-tv（LiveWallpaper.kt）在真机上遇到两类问题：小米 MStar 机型上 PixelCopy 返回成功但画面全黑；TCL MT5879 上能抓到，但 4K 帧要 0.6–1.7 秒，期间主页卡住。本方案的处理：

• 不在主线程等待：PixelCopy 的回调放在专用 HandlerThread；返回界面的动画不等结果，先显示上一张静态帧或预置关键帧，抓到后交叉淡入。
• 150 ms 预算：任何一次成功的抓帧耗时超过 150 ms，本机此后不再使用 PixelCopy。
• 全黑检测：结果按 16×9 网格采样，最大亮度低于 4% 视为全黑。当前片段的 keyColor 不是近黑色时，连续两次全黑即判定本机不可用。
• 按固件记住：判定结果以 Build.FINGERPRINT 为键存入 DataStore，固件升级后重新探测；devices.json 可以预置结论（§16）。
• 回退：航拍片单为每段影片预先提供关键帧图（按时间索引）和 keyColor，按播放位置取最近的一张。没有预置帧的片源（自己的视频）用 MediaMetadataRetriever.getFrameAtTime(t, OPTION_PREVIOUS_SYNC) 从本地文件取；航拍只从 1080p H.264 文件取，不碰 4K HEVC 与杜比视界文件。
• 解析器卡死：部分固件的 MPEG4 解析器会在 MediaMetadataRetriever 里卡死（aerial-tv 在 TCL 上遇到）。取帧放在独立线程，10 秒超时；超时一次后，本次开机内不再从文件取帧，只用预置帧或壁纸。

解码器交接

电视通常只有一个 4K / HDR 解码实例。桌面的播放器占着它时，用户打开的应用可能起播失败。

• 主动离开（打开应用或信号源，或在播放器暂停时启动屏保）：先抓帧（可用时），再释放暂停中的播放器（解码器与 Surface 一起释放），最后发出启动 Intent。环境模式正在播放时进入本应用屏保不在此列，见"从环境模式到屏保"。
• 被动离开（其他应用或系统界面来到前台、待机）：播放器停在当前帧，最多再占用解码器 2.5 秒用于取得静态帧，到时无论成败都释放。
• 回来：从记住的片段与位置重新起播。
• 离开 HDMI 后延迟：devices.json 标记的机型（如 Mi TV 4，aerial-tv FilmAfterInput.kt 记录过整机重启）从信号源回到主页后，等 2.5 秒再打开解码器，期间显示静态帧或壁纸。

画质、缓存与失败处理

从环境模式到屏保

• 同一个播放器：环境模式正在播放时进入本应用的屏保（桌面内屏保或本应用的 DreamService，同一进程），把播放器的输出 Surface 切到屏保窗口，片段、位置和画质不变，不黑屏、不重新缓冲。只有用户为屏保单独选了更高画质（如 4K 杜比视界）时才重新起播，切换时可能黑屏一次。
• 跨重启续播：当前片段 ID 与播放位置（毫秒）每 10 秒及离开时写入 DataStore；进程重启或开机后从这里继续。
• 小集合轮换：航拍片单在本机只轮换 3 段，每天换入一段新的、移出最旧的一段，提高缓存命中；屏保中左右键切换上一段 / 下一段。

屏保兜底

• 桌面内屏保：本应用的 DreamService 不是当前系统屏保（Settings.Secure 的 screensaver_components 不含本组件，或读取不到），或机型在 devices.json 中标记为不列出第三方屏保时启用。主页空闲达到设定时长（默认 10 分钟）后，桌面在自己的窗口里全屏播放；只在桌面位于前台时生效。
• 不妨碍待机：桌面内屏保运行时设置 FLAG_KEEP_SCREEN_ON，累计达到系统关屏时长（Settings.System.SCREEN_OFF_TIMEOUT）后清除，交回系统按原设置待机。
• 立即启动：快速设置的"屏保"项提供"立即启动"，直接进入本应用屏保（§14）。
• 内容：航拍片单、自己的视频、照片（含必应每日一图）、时钟，与 DreamService 共用一套渲染；任意键退出，回到进入前的页面与焦点。

• HDMI 固定：信号源可以固定到"你的应用"行，显示为圆形图标，图标和种子色按设备类型预设（游戏机、机顶盒、回音壁、电脑）。
• 手机整理：只在用户打开时启动局域网服务。技术选型参考 aerial-tv（NanoHTTPD + ZXing 二维码；它用固定端口 8790 和持久令牌，应用运行期间一直监听）。本方案用随机端口，二维码里带一次性令牌，会话 10 分钟后失效；只监听局域网地址；上传类型与限额见下文"手机整理页"；所有写操作在电视上弹确认。手机页面同时显示小组件授权用的 appwidget grantbind 命令，便于复制到电脑执行（§12）。

信号源补充

• 信号源键：KEYCODE_TV_INPUT 打开快速设置的信号源页（§10）。devices.json 标记"固件自带信号源面板"的机型不消费这个键，交给固件，避免两个面板同时出现（aerial-tv 在 TCL MT5879 上遇到）。
• 固件信号源界面：getTvInputList() 为空，或切换用的 ACTION_VIEW 没有处理者时，信号源项改为打开固件自己的信号源界面（组件名记在 devices.json）；仍没有时隐藏此项。海信、康佳等不经过 TvInputManager 的私有接口只在 oem 变体实现。
• 开机 / 唤醒目标：桌面设置的"开机后打开"可选主页（默认）、一个信号源或一个应用。每次开机执行一次，每次从待机唤醒执行一次，同一次亮屏期间不再执行。开机判断用 Settings.Global.BOOT_COUNT（API 24+），API 23 比较开机时刻（System.currentTimeMillis() - SystemClock.elapsedRealtime()）。唤醒时只在桌面位于前台时执行；HDMI-CEC 已把电视切到某个输入（前台已不是桌面，或当前输入就是目标）时跳过。开机后按 devices.json 的延迟等输入服务就绪再切换。

HDMI 实时画面作壁纸

• 来源：壁纸可选一个已固定的信号源。只列出 TvInputManager 列出的输入（inputId 为 TvInputService 组件形式，含 "/"），不包括固件私有信号源。
• 播放：主页背景层放一个 TvView，附加到窗口 0.8 秒后调用 tune(inputId, TvContract.buildChannelUriForPassthroughInput(inputId))；setStreamVolume(0f) 静音。
• 弱信号：收到 VIDEO_UNAVAILABLE_REASON_WEAK_SIGNAL 时在 3 / 5 / 10 / 15 / 20 / 30 秒后重试，仍失败则显示内置深色底图，直到下次回到主页。
• 界面：主页静止后与环境模式一样淡出界面框架（§06"信号源画面"状态）。直通画面无法抓帧，返回界面时背景换成内置深色底图做 T2 玻璃，取色用该信号源按设备类型预设的种子色。
• 交接：打开应用、信号源或屏保前先 TvView.reset() 释放会话；离开 HDMI 后的解码器延迟同 §13"解码器交接"。

儿童模式、长辈模式与家长 PIN

两种受限模式在桌面设置里开启，共用一个家长 PIN。§07 中锁定固定种子色的就是这两种模式。

• PIN：4 位数字，或 4 次方向键（没有数字键的遥控器也能输入）。保存随机 16 字节盐与 SHA-256 哈希，不存明文。连续输错 5 次锁定 60 秒。
• 解锁：输入正确后 10 分钟内可修改设置、暂停模式、打开不在允许列表里的应用；按 HOME、进入屏保或关屏时立即重新上锁。
• 暂停与恢复：从"家长"菜单退出只是暂停，进入屏保、关屏或重启后自动恢复。关闭模式要在桌面设置里输入 PIN 后关掉开关。
• 忘记 PIN：界面上没有重置入口。只能用 ADB：adb shell am broadcast -n <pkg>/.config.ConfigReceiver --ez clear_pin true（接收器要求发送方持有 WRITE_SECURE_SETTINGS，只有 shell 和系统满足），或 adb shell pm clear <pkg>（同时清空布局）。系统设置默认不在允许列表里，从电视上无法清除桌面数据。

standard 变体不用无障碍服务，各项的执行手段与前提如下：

• 状态展示：桌面设置的儿童模式页列出"使用情况访问：已授予 / 未授予"和"悬浮窗：已授予 / 未授予"，以及对应的 ADB 命令。
• 做不到时：某台设备上锁屏无法从后台拉起时，额度用完后只能在回到主页时锁定；没有使用情况访问权限时，从允许的应用跳转到的其他应用拦不住。需要系统级强制时用 oem 变体：预装为特权应用，直接持有 PACKAGE_USAGE_STATS 与后台启动权限。

设为默认桌面与 HOME 兼容

• 清单：主 Activity 的 intent-filter 声明 android.intent.action.MAIN 与 android.intent.category.HOME、android.intent.category.DEFAULT、android.intent.category.LAUNCHER、android.intent.category.COMMON_HOME；另一个 filter 声明 android.intent.category.HOME.CC 与 DEFAULT；再加 <meta-data android:name="com.tcl.app.type" android:value="com.tcl.ui" />。后三项是部分国内固件识别桌面用的非标准值，字符串取自 aerial-tv app/src/standard/AndroidManifest.xml，效果在 M0 的测试固件上核实。
• Activity 属性：launchMode="singleTask"、stateNotNeeded="true"、clearTaskOnLaunch="true"、excludeFromRecents="true"、resumeWhilePausing="true"、screenOrientation="landscape"。
• "默认桌面"页：首次启动引导的第一步，桌面设置里也有同一页。页面显示"已是默认桌面"或"当前默认桌面：{应用名}"（用 resolveActivity(HOME, MATCH_DEFAULT_ONLY) 判断）。"设为默认桌面"按钮依次尝试：API 29+ RoleManager.createRequestRoleIntent(ROLE_HOME)；Settings.ACTION_HOME_SETTINGS；发 HOME Intent 让系统弹出选择器。都没有结果时，页面列出 ADB 命令 adb shell cmd package set-home-activity <pkg>/.MainActivity，API 29+ 另有 adb shell cmd role add-role-holder android.app.role.HOME <pkg>（两条命令在 M0 核对）。
• 失效检测：桌面每次回到前台检查一次是否仍是默认桌面；不是时只在桌面设置的"默认桌面"项显示状态，不弹窗。

手机整理页

• 二维码地址：选择局域网 IPv4 地址时跳过 VPN 网络（NetworkCapabilities.TRANSPORT_VPN）、tun 类接口和 198.18.0.0/15（代理软件常用的虚拟网段）；有多个候选时以太网优先，其次 Wi-Fi。没有可用地址时显示"未连接局域网"，不启动服务。

诊断导出

• 内容：DiagLog 环形缓冲（最近 200 行，同时写入应用私有文件）；帧时间统计（每个页面最近 600 帧的 P50 / P90 / P99；API 24+ 用 FrameMetrics，API 23 用 Choreographer 估算）；设备与固件信息（厂商、型号、SoC、API 级别、Build.FINGERPRINT、显示模式与刷新率、解码能力、设备档位、命中的 devices.json 条目与 ADB 覆盖项、PixelCopy 判定）；桌面版本、变体、是否为默认桌面、各项授权状态。
• 脱敏：IP 地址只留前两段，MAC 只留前 3 字节，令牌与 PIN 相关字段整体替换。不收集账户、Wi-Fi 名称、序列号、城市和已安装应用列表。
• 导出：只通过手机整理页下载纯文本报告；桌面不向任何服务器上传。

// app/build.gradle.kts（节选）
android { defaultConfig { minSdk = 23; targetSdk = 36 } }
dependencies {
  implementation(platform("androidx.compose:compose-bom:2026.09.00"))
  implementation("androidx.compose.material3:material3:1.5.0-alpha25")   // 最后一个 minSdk 23 的 1.5.0；不要升级
  implementation("dev.chrisbanes.haze:haze:2.0.1")
  implementation("dev.chrisbanes.haze:haze-blur:2.0.1")
  implementation("com.materialkolor:material-color-utilities:6.0.0")
  implementation(libs.media3.exoplayer); implementation(libs.media3.ui.compose)   // ≥ 1.9
  implementation(libs.tvprovider); implementation(libs.recommendation); implementation(libs.coil.compose)
  implementation(libs.shizuku.api); implementation(libs.shizuku.provider)          // 可选：小组件绑定授权
}
// 防止被依赖升级悄悄抬到 alpha26+（minSdk 24）：
configurations.all { resolutionStrategy.force("androidx.compose.material3:material3:1.5.0-alpha25") }
// M0 必做：./gradlew :app:dependencies 确认没有被传递依赖抬高 minSdk（manifest merger 也会报错）

主题与动效（基于 material3 1.5.0-alpha25）

@Composable
fun LauncherTheme(theme: ThemeController, reducedMotion: Boolean, content: @Composable () -> Unit) {
  MaterialExpressiveTheme(
    colorScheme = theme.colorSchemeSnapshot(),          // 必须显式传暗色方案：默认是 expressiveLightColorScheme()
    motionScheme = if (reducedMotion) ReducedMotionScheme else MotionScheme.expressive(),
    typography = LauncherTypography,                     // 含 *Emphasized；CJK 映射到 700 / 800
    shapes = LauncherShapes,                             // 卡片 16、焦点 24、面板 28–32、Hero 48
    content = content,
  )
}
// 颜色过渡期间每帧变化的部分（环境遮罩、玻璃 tint、光环）在绘制阶段读取 theme.colors()，
// 传给 MaterialExpressiveTheme 的方案只在过渡结束时更新一次，避免整树重组。

// 组件里统一从主题取动效
val motion = MaterialTheme.motionScheme
val scale by animateFloatAsState(if (focused) 1.1f else 1f, motion.fastSpatialSpec())      // 0.6 / 800
val rowScroll = MotionScheme.standard().defaultSpatialSpec<Float>()                            // 0.9 / 700：长距离不晃
val ambient = spring<Float>(dampingRatio = 1f, stiffness = 200f)                           // 环境色过渡，本方案自定

// 减弱动效：spatial 改为 snap，effects 保留
object ReducedMotionScheme : MotionScheme by MotionScheme.standard() {
  override fun <T> defaultSpatialSpec(): FiniteAnimationSpec<T> = snap()
  override fun <T> fastSpatialSpec(): FiniteAnimationSpec<T> = snap()
  override fun <T> slowSpatialSpec(): FiniteAnimationSpec<T> = snap()
}

// 图标焦点形变：圆 → Cookie9Sided（MaterialShapes 已归一化到 0..1）
@OptIn(ExperimentalMaterial3ExpressiveApi::class)
val IconMorph = Morph(MaterialShapes.Circle, MaterialShapes.Cookie9Sided)

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
class MorphShape(private val morph: Morph, private val progress: Float) : Shape {
  override fun createOutline(size: Size, layoutDirection: LayoutDirection, density: Density): Outline {
    val path = morph.toPath(progress)                  // material3 提供的 Morph.toPath
    path.transform(Matrix().apply { scale(size.width, size.height) })
    return Outline.Generic(path)
  }
}
// Modifier.graphicsLayer { shape = MorphShape(IconMorph, focusProgress.value); clip = true }

// Hero 按钮组：M3 ButtonGroup 只在按下时变宽，电视改为焦点驱动
@Composable
fun TvButtonGroup(buttons: List<TvButtonSpec>) = Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
  buttons.forEach { spec ->
    var focused by remember { mutableStateOf(false) }
    val extra by animateDpAsState(if (focused) 20.dp else 0.dp, MaterialTheme.motionScheme.defaultSpatialSpec())
    val corner by animateDpAsState(if (focused) 14.dp else 23.dp, MaterialTheme.motionScheme.fastSpatialSpec())
    TvButton(spec, Modifier.onFocusChanged { focused = it.isFocused }.padding(horizontal = extra / 2), RoundedCornerShape(corner))
  }
}

app                    standard / oem 两个 flavor
core:designsystem      MaterialExpressiveTheme 封装、形状、字体
core:dynamiccolor      取色、配色、ThemeController、SeedCache
core:glass             Haze 封装、T2 frozenGlass、材质 token
core:tvfocus           焦点组件、BringIntoViewSpec、焦点记忆
core:ambient           背景层、播放器、PixelCopy、帧取色、信号源画面
data:apps              PackageManager、图标与 banner、整理
data:channels          TvProvider、推荐通知、审批表
data:series            系列应用直连：发现、证书校验、approve / hide / init、行数据
data:widgets           AppWidgetHost、绑定授权、网格布局、内置小组件
data:media             航拍片单、自己的视频、每日一图、缓存、许可信息
data:weather           天气、城市表、农历
data:restricted        儿童 / 长辈模式、PIN、计时
core:update            版本检查、下载校验、安装会话（仅 standard）
core:diag              DiagLog、帧统计、诊断报告、devices.json
feature:home | apps | widgets | quicksettings
feature:settings | onboarding | phone-organizer
oem                    EPG 全量、BIND_APPWIDGET、亮度等
opt:shizuku            可选：小组件绑定授权

分发与更新

standard 变体以 APK 侧载发行（项目网站与 GitHub Releases），没有应用商店的更新通道，所以自带更新检查。oem 变体随系统 OTA 更新，不含 core:update。

机型修正数据

机型差异集中在随包发布的 assets/devices.json，按 Build.MANUFACTURER + Build.MODEL 匹配（必要时加 Build.DEVICE 或 Build.FINGERPRINT 前缀），代码中不写机型判断。

• 单机覆盖：adb shell am broadcast -n <pkg>/.config.ConfigReceiver --es device_profile '{…}'（与 PIN 重置同一个接收器，要求发送方持有 WRITE_SECURE_SETTINGS）；覆盖项存入 DataStore，优先于随包数据；传空字符串清除。
• 可见性：诊断报告列出命中的条目与覆盖项（§14）。

启动、刷新率与内存

• Baseline Profile 必须实际生效：冷启动目标以"已按 profile 编译"为前提。侧载发行靠安装会话附带的 .dm（§16"分发与更新"）；验收时在侧载安装后检查 ProfileVerifier 的结果，或 adb shell dumpsys package dexopt 中本应用为 speed-profile。Macrobenchmark 用 CompilationMode.Partial() 测量同样的状态。
• 刷新率：API 31+ 从当前显示模式的 getAlternativeRefreshRates()（可无缝切换的刷新率）中选不超过 120Hz 的最高值，通过窗口的 preferredDisplayModeId 设置；不选择需要重新同步、会黑屏的模式切换。API 23–30 不改显示模式。帧时间预算按实际刷新率换算。
• onTrimMemory：TRIM_MEMORY_UI_HIDDEN（每次打开应用都会收到）时不释放，保证回到主页时首屏不必重新生成；TRIM_MEMORY_RUNNING_LOW、RUNNING_CRITICAL 以及 BACKGROUND 和更高级别时，清空图片内存缓存、冻结模糊位图和取色缩略图，保留 Room 与磁盘缓存。API 34+ 不再发送 RUNNING_* 级别，以 BACKGROUND 为准。
• 冷启动：首帧只用 Room 里缓存的行和种子色（ChannelRowCache / ProgramCache / SeedCache）；TvProvider、系列直连和小组件在首帧之后加载；字体在 Application 启动时于后台预热（aerial-tv FontWarmup.kt）；首帧前不初始化 Media3、Haze 模糊和网络客户端；不经过单独的启动页跳转。

ADR