1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | leanback-to-compose-tv-migration-android-skills |
| 项目自述名称 | leanback-to-compose-tv-migration（SKILL.md frontmatter name 字段） |
| 作者/维护者 | Google LLC（Android 官方团队） |
| 来源链接 | https://github.com/android/skills/tree/main/tv/leanback-to-compose-tv-migration |
| 许可证 | Apache License 2.0（GitHub API 确认，仓库级；SKILL.md frontmatter 指向仓库根 LICENSE.txt） |
| GitHub Stars / Forks | 7,312 / 476（GitHub API；为 android/skills 整个合集仓库的数据，不代表本子技能单独热度） |
| 最新版本 | SKILL.md frontmatter last-updated：2026-09-03；该子目录最近一次提交：2026-09-07 |
| 安装方式 | Android CLI 一条命令，或手动复制到对应 Agent 的 skills 目录（详见第 10 章） |
2. 功能介绍与亮点
这是 Google Android 官方团队发布的结构化技能，指导 Agent 把 Android TV 应用从旧版 Leanback UI Toolkit、传统 Android View 或 Support Fragment（BrowseSupportFragment、VideoSupportFragment、GuidedStepSupportFragment、SearchSupportFragment 等）迁移到 Jetpack Compose for TV（androidx.tv）。
亮点：
- 覆盖 TV 应用五类核心画面的迁移：浏览页（Browse）、设置页、登录/认证页、播放页、搜索页，每类都给出对应的 Compose 组件替代方案与完整代码示例。
- 专门拆解“10 英尺 UI”这套 TV 专属设计范式：从观看距离、高对比度配色到 D-pad 四方向导航，逐条说明为什么 TV 界面不能照搬手机端 Compose 写法。
- 深入 D-pad 焦点管理的具体故障模式：明确指出哪些写法会导致焦点陷阱、
IllegalStateException崩溃（如给列表内单项设置方向覆盖、在快速滚动时对已脱离屏幕的元素调用requestFocus），并给出Modifier.focusRestorer、显式FocusRequester等对应修复写法——这类“为什么会崩、具体怎么修”的细节在同类迁移文档中较少见。 - 3 份 references 文档 + 主文档合计约 45KB，覆盖 TV 导航搭建、Compose for TV 环境配置、浏览页播放集成的官方参考资料。
3. 适用场景
固定分类：前端与设计。
适用于维护 Android TV 应用、需要把基于 Leanback/View/Support Fragment 构建的旧版界面迁移到 Jetpack Compose for TV 的 Android 工程师，尤其适合正在响应 Google 逐步弃用 Leanback 库、转向 Compose 统一 UI 技术栈这一趋势的团队。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持。
android/skills遵循开放的 Agent Skills 标准，技能目录即标准 SKILL.md + YAML frontmatter + references 结构，可直接复制到.claude/skills/使用。 - Codex：✅ 官方确认支持。Android Developers 官方文档与第三方综述（androiddevkit.com）均将 Codex 列入该开放标准兼容的 Agent 名单。
- OpenClaw：⚠️ 未经本技能专门验证。
- Hermes Agent：⚠️ 未经本技能专门验证。
需注意：官方 Android CLI 默认仅为 Gemini 与 Antigravity 自动安装技能，面向 Claude Code / Codex 需手动指定 --agent 参数或手动复制（详见第 10 章）。
5. 推荐理由
Leanback UI Toolkit 已进入维护模式，Google 官方方向是把 TV 应用迁移到 Jetpack Compose for TV，但这类迁移涉及的 D-pad 焦点管理与手机端 Compose 开发经验差异很大——照搬手机端写法极易踩中焦点陷阱、滚动时崩溃等 TV 特有问题。这份官方技能把迁移拆成五类具体画面，每类都给出可直接落地的 Compose 组件替代方案与代码示例，并且专门解释了焦点管理相关崩溃的成因和修复方式，能帮工程师少走一遍“迁移完发现遥控器操作不了”的弯路。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Google LLC（Android 官方团队）出品；仓库 7,312 stars 属整个 android/skills 合集，不代表本子技能独立热度；本子技能自身可核实的独立第三方证据为第 8 章列出的 1 条 GitHub issue 真实互动，尚未见更广泛的独立讨论 |
| 可用性 | 9 | 一条 CLI 命令或手动复制即用；SKILL.md 正文 740 行，按五类画面给出结构化迁移方案，配 3 份 references 覆盖导航、环境配置与播放页集成；该子目录 2026-09-07 有提交，维护活跃；用户实测反馈的两处代码笔误已在最新版本中修正（详见第 8 章），显示维护方对真实使用反馈响应及时；无付费依赖 |
| 安全性 | 9 | 详见下方安全检查清单 |
| 综合 | 8.3 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令及权限范围 | 全文未涉及任何 Shell 命令，纯 Kotlin/Compose 代码改写指导 |
| ② 运行时联网外发 | 无，全程为本地代码分析与改写，不涉及任何数据外发 |
| ③ API Key / 凭据 | 不需要 |
| ④ SKILL.md 与脚本可疑指令 | 已通读 SKILL.md 全文（740 行）及全部 3 份 references 内容，均为 Compose for TV 迁移官方技术规范转译，未发现越权指令或夹带与任务无关的推广内容 |
| ⑤ 作者/组织信誉 | Google LLC，Android 官方团队，androidx.tv 本身即由该团队维护 |
| ⑥ License | Apache License 2.0，明确（仓库级，GitHub API 确认） |
| ⑦ 最近维护时间 | 该子目录 2026-09-07 有提交，非弃置项目 |
7. 跟同类 Skills 相比的优势
| 名称 | 来源 | 定位 | 与本技能的差异 |
|---|---|---|---|
| leanback-to-compose-tv-migration（本推荐） | android/skills | 专注 Leanback/View/Fragment 到 Compose for TV 的整体迁移，覆盖五类核心画面与 D-pad 焦点故障排查 | — |
| migrate-xml-views-to-jetpack-compose | 同合集内 android/skills |
把传统 XML View 迁移到 Jetpack Compose（手机端） | 解决的是手机端“是否已用 Compose”的前提问题，不涉及 TV 专属的 D-pad 焦点管理、10 英尺 UI 设计范式 |
| navigation-3 | 同合集内 android/skills |
搭建 Jetpack Navigation 3 导航框架本身 | 是通用导航框架搭建，不涉及 TV 遥控器场景下的具体导航与焦点问题 |
| adaptive | 同合集内 android/skills |
让已有 Compose 应用适配手机、平板、可折叠设备乃至 TV/XR 等多种窗口尺寸 | 关注的是同一套代码如何跨设备自适应布局，本技能关注的是 TV 平台本身从旧技术栈整体迁移到 Compose，两者服务的迁移阶段不同 |
8. 用户评价
- GitHub 用户 theothernt 在 issue #152 中实际使用该技能迁移浏览页时，指出 references 文档中存在一处代码笔误（函数声明关键字写错）与一处过时 API 名称（应为
LazyColumn而非旧版TvLazyColumn），并援引 Android Developers 官方 Medium 文章佐证。Google 维护者 pflammertsma 次日确认收到反馈，两处笔误均已在 2026-09-07 更新的版本文档中修正（来源：github.com/android/skills/issues/152）。 - 尚未查到该技能的其他独立第三方评价。
9. 其他补充
无。
10. 安装使用方式
方式一：Android CLI（官方推荐，一条命令）
android skills add --skill=leanback-to-compose-tv-migration --project=.需先安装 Android CLI；未指定 --agent 时默认为 Gemini 与 Antigravity 自动安装，面向 Claude Code / Codex 需显式使用 --agent 参数指定，具体取值以官方文档为准。
方式二：手动安装（适用于 Claude Code / Codex）
git clone https://github.com/android/skills.git
cp -r skills/tv/leanback-to-compose-tv-migration <你的项目>/.claude/skills/leanback-to-compose-tv-migration复制时需保留 SKILL.md 与 references/ 目录的相对结构。安装后无需重启，Agent 会在识别到“迁移 TV 应用到 Compose”“替换 Leanback Fragment”“处理 TV 遥控器焦点问题”类任务时自动触发，也可按各 Agent 自身语法手动调用。
11. 注意事项
- 本技能面向已有 Android TV 应用、且明确要迁移到
androidx.tv技术栈的场景，非 TV 应用或尚未涉及 D-pad 焦点管理的项目不适用。 - OpenClaw、Hermes Agent 的兼容性未经本技能专门验证，使用前建议先小范围试点。
- 官方 Android CLI 默认只为 Gemini / Antigravity 自动安装，Claude Code / Codex 用户需手动复制或显式指定
--agent参数。