1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | play-billing-library-version-upgrade-android-skills |
| 项目自述名称 | play-billing-library-version-upgrade（SKILL.md frontmatter name 字段） |
| 作者/维护者 | Google LLC（Android 官方团队） |
| 来源链接 | https://github.com/android/skills/tree/main/play/play-billing-library-version-upgrade |
| 许可证 | Apache License 2.0（GitHub API 确认，仓库级；SKILL.md frontmatter 指向仓库根 LICENSE.txt） |
| GitHub Stars / Forks | 6,782 / 410（GitHub API；为 android/skills 整个合集仓库的数据，不代表本子技能单独热度） |
| 最新版本 | SKILL.md frontmatter last-updated：2026-08-06；该子目录最近一次提交：2026-08-07 |
| 安装方式 | Android CLI 一条命令，或手动复制到对应 Agent 的 skills 目录（详见第 10 章） |
2. 功能介绍与亮点
这是 Google Android 官方团队发布的结构化技能，指导 Agent 把 Android 项目里的 Google Play Billing Library（PBL）从任意旧版本升级到最新稳定版。
亮点：
- 区分“声明版本”与“有效版本”：先尝试直接编译，若失败则扫描代码中残留的已弃用 API（如
SkuDetails），据此判断项目实际使用的 API 面属于哪个版本——build.gradle里写的版本号有时并不代表代码真实调用的接口，这个判断步骤能避免用错误的起点规划升级路径。 - 按版本落差自动规划迁移策略：落后目标 2 个大版本以内走直接迁移，落后更多则按“两个大版本一跳”分步迁移，每跳后运行
./gradlew assembleDebug验证再继续，避免一次性跨版本迁移时中间的破坏性变更被遗漏。 references/migration-logic.md系统梳理 7 类高影响变更：连接管理（v8+ 从开发者手动重连改为库自动重连）、SkuDetails→ProductDetails数据模型迁移、订阅升降级参数变化、queryPurchases同步 API 弃用、enablePendingPurchases()等必需配置项、各版本compileSdk要求，均附具体代码对照。references/version-checklist.md+ 79KB 官方发布说明汇编：升级完成后逐版本核对清单，避免漏项。- 持续活跃维护：该子目录 2026-08-07 有提交，与整个仓库的更新节奏一致。
3. 适用场景
固定分类：工程效率与代码质量。
适用于维护中的 Android 应用需要把 Google Play Billing Library 从 v3–v8 等旧版本升级到最新版的工程师，尤其是应用积累了多个版本技术债、需要跨多个大版本分步迁移，或代码中仍在使用 SkuDetails 等已弃用 API 的场景。
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. 推荐理由
Google Play Billing Library 的版本升级是 Android 开发中容易踩坑的迁移场景——API 模型在 v5–v8 间从 SkuDetails 结构性地变为 ProductDetails，订阅升降级、分期付款、预付费计划等特性只在特定版本之后才可用，而 build.gradle 里声明的版本号有时并不代表代码实际调用的 API 面。这份官方技能把这些容易被忽略的细节系统化为可执行流程：先判断真实起点，再按版本落差规划直接或分步迁移路径，逐版本核对破坏性变更，省去工程师把官方迁移指南和发布说明逐页比对的成本。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Google LLC（Android 官方团队）出品；仓库 6,782 stars 属整个 android/skills 合集，不代表本子技能独立热度（已在第 1 章注明），未发现本子技能自身独立于官方身份之外的第三方证据支撑更高档位 |
| 可用性 | 9 | 一条 CLI 命令或手动复制即用；SKILL.md 按 4 阶段给出结构化流程，配 3 份 references（migration-logic.md、version-checklist.md、79KB 官方发布说明汇编）；该子目录 2026-08-07 有提交，维护活跃；无付费依赖 |
| 安全性 | 9 | 详见下方安全检查清单 |
| 综合 | 8.3 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令及权限范围 | 指导执行标准 Gradle 构建/测试命令（./gradlew assembleDebug/test/clean/build），均为用户项目自身的标准构建工具调用，无越权操作 |
| ② 运行时联网外发 | 无，全程为本地代码分析与编写，不涉及任何数据外发 |
| ③ API Key / 凭据 | 不需要 |
| ④ SKILL.md 与脚本可疑指令 | 已通读 SKILL.md 全文及全部 3 份 references，内容均为 Play Billing 官方技术规范转译，未发现越权指令或夹带与任务无关的推广内容 |
| ⑤ 作者/组织信誉 | Google LLC，Android 官方团队，Google Play Billing Library 本身即由 Google Play 团队维护 |
| ⑥ License | Apache License 2.0，明确（仓库级，GitHub API 确认） |
| ⑦ 最近维护时间 | 该子目录 2026-08-07 有提交，非弃置项目 |
7. 跟同类 Skills 相比的优势
| 名称 | 来源 | 定位 | 与本技能的差异 |
|---|---|---|---|
| play-billing-library-version-upgrade（本推荐） | android/skills | 专注 Play Billing Library 版本升级路径规划与破坏性变更迁移 | — |
| play-billing-skills | RevenueCat/play-billing-skills（第三方，45 stars，最近提交 2026-06-02） | 把 RevenueCat 自家的 Google Play Billing 手册与 RevenueCat Android SDK 手册转化为可执行指令，覆盖 RTDN 配置、续订失败处理等更广的账单集成流程 | 版本迁移只是其覆盖场景之一，且捆绑 RevenueCat SDK 概念；本技能不依赖第三方支付中间层，且把“声明版本 vs 有效版本”判定与分步迁移策略作为唯一焦点，覆盖深度更专 |
| agp-9-upgrade | 同合集内 android/skills |
Android Gradle Plugin 版本升级 | 迁移对象是构建工具链而非支付 SDK，破坏性变更清单完全不重叠 |
| camerax | 同合集内 android/skills |
CameraX 相机功能实现与迁移 | 面向相机硬件层，与本技能的支付/订阅 API 层无关联 |
8. 用户评价
- GitHub 用户 kingargyle 在 issue 中指出，该技能与仓库内另外 4 个技能的 references 目录嵌套层级超过 agentskills.io 规范建议的“保持文件单层深度”最佳实践，可能增加 token 占用（来源：github.com/android/skills/issues/23）。
- 第三方技术博客 AndroidDevKit 将该技能列入其推荐的 Android Skills 起步安装清单，评价 Android Skills 类工具“最适合用在给出似是而非错误答案代价很高的场景”，应被当作“更好的检查清单，而非自动驾驶按钮”使用（来源：androiddevkit.com/blog/android-skills-cursor-claude-codex）。
9. 其他补充
无。
10. 安装使用方式
方式一：Android CLI（官方推荐，一条命令）
android skills add --skill=play-billing-library-version-upgrade --project=.需先安装 Android CLI；未指定 --agent 时默认为 Gemini 与 Antigravity 自动安装，面向 Claude Code / Codex 需显式使用 --agent 参数指定，具体取值以官方文档为准。
方式二：手动安装（适用于 Claude Code / Codex）
git clone https://github.com/android/skills.git
cp -r skills/play/play-billing-library-version-upgrade <你的项目>/.claude/skills/play-billing-library-version-upgrade复制时需保留 SKILL.md 与 references/ 目录的相对结构（含 references/android/google/play/billing/release-notes.md 的嵌套路径）。安装后无需重启，Agent 会在识别到“升级 Play Billing Library”“迁移到 PBL X”类任务时自动触发，也可按各 Agent 自身语法手动调用。
11. 注意事项
- 分步迁移（Stepped Migration）适用于版本落后目标 2 个大版本以上的场景，会经过中间版本反复编译验证，耗时较长，建议在独立分支上进行。
- references 目录存在多层嵌套（如
references/android/google/play/billing/release-notes.md），第三方开发者已指出这与 agentskills.io 规范的“单层深度”建议不完全一致（见第 8 章），实际使用未见功能性影响。 - OpenClaw、Hermes Agent 的兼容性未经本技能专门验证，使用前建议先小范围试点。
- 官方 Android CLI 默认只为 Gemini / Antigravity 自动安装，Claude Code / Codex 用户需手动复制或显式指定
--agent参数。