一句话:在 Android Studio 的空 Compose 工程上,用十条提示词、两个晚上,和 AI 一起把「山洞水滴」动态壁纸从需求聊到能在 Pixel 真机上跑起来——M1 骨架和 M2 水滴涟漪场景编译通过、单测全绿。这篇把协作过程、提示词原文和四个容易卡死人的技术坑一次讲清楚。
先交代背景。上一篇我记录了用 Tauri + Vue + WebGL 做 Windows 桌面「星际穿越」动态壁纸的过程。这次换个完全不同的战场:Android 手机原生动态壁纸,技术栈是 Kotlin + Jetpack Compose,工程是 Android Studio 新建的空项目,包名 com.example.livewallpaper。
和上次最大的不同是这次的协作节奏:第一句提示词就明确说了「我们先讨论一下需求」——不写一行码,先把方向聊明白。回头看,这个开头省掉了后面大量返工。
第一步:不写码,先聊透需求
我的第一句话是:
「我想做一个动态壁纸,这是 Android Studio 创建的空项目,我们先讨论一下需求。」
AI 没有急着开写,而是先做了三件事:
- 探查工程现状:读
AndroidManifest.xml、app/build.gradle.kts和源码目录,确认技术底座——Kotlin 2.2.10、AGP 9.2.1、minSdk 29、targetSdk 36,标准 Compose 空模板。 - 讲清动态壁纸的技术骨架:它本质是一个常驻的
WallpaperService.Engine;渲染有三条路线(Canvas 2D / OpenGL ES / 视频循环);省电的生死线是「不可见就停帧」;设置页要挂在settingsActivity。 - 给出推荐方案再抛问题:第一版定为「自然氛围系·山洞水滴」——贴合我平时喜欢的山洞水滴、布谷鸟这类安静环境音,视觉和声音双差异化;渲染走 Canvas 2D;单 Service + 多 Engine 可插拔架构。
最后抛了三个待拍板问题:主题方向、环境音默认开关、发布目标。这就是一份四层需求决策地图:主题内容 → 渲染引擎 → 核心能力 → 工程形态。
第二步:把讨论结论固化成需求文档
我对方向很满意,于是说:
「哎,这个设计需求我很满意。你把这个需求保存到项目目录,当我们的需求文档。」
需求文档 v0.1 落盘后,三个开放问题按建议拍板,升级为 v0.2:
| 决策点 | 拍板结果 |
|---|---|
| 主题 | 山洞水滴(预留「星际穿越」作为后续可插拔场景) |
| 环境音 | 默认关闭,设置页里可手动打开 |
| 发布目标 | 自用 + 产出技术内容,不上架应用市场 |
接着一句话:「三个开放问题就按你的建议来。再为当前项目创建 Git 并提交。」——建立 42dd735 基线(48 个文件、1193 行),顺手校验了 .gitignore 确认 local.properties 和构建产物不会入库。
第三步:写码之前,先写系统设计
这里是我最刻意的一步:
「动手写代码前,我们先做一下这个系统设计,并把系统设计保存到当前项目中,以便以后我和别的 Agent 讨论系统设计方案,优化系统设计。」
这句话的目的不是走形式,而是让设计文档成为以后我和任何一个新 Agent 对话的公共上下文。系统设计文档里包含:三层架构(设置层 / 壁纸层 / 渲染层 + 音频旁支)、Mermaid 架构图、包结构、引擎生命周期表、渲染器接口、山洞六层场景拆解、音频设计、配置传递、省电策略,外加一张8 项关键权衡表和 M1–M6 里程碑。提交为 0ef9681。
第四步:M1 骨架——第一个硬坑就来了
「开始实现吧」之后,AI 搭出了壁纸服务骨架:LiveWallpaperService、WallpaperRenderer 接口、M1 空场景的 CaveRenderer(深色渐变 + 呼吸微光)、res/xml/wallpaper.xml、Manifest 注册(BIND_WALLPAPER 权限 + intent-filter + meta-data)。
编译时踩了三个坑,第一个是架构级的:
坑一:Kotlin 不能直接继承 WallpaperService.Engine
直觉写法是单独定义一个类继承 Engine:
// 编译不过
class CaveEngine(service: LiveWallpaperService) : service.Engine() { ... }
编译直接失败。原因是:WallpaperService.Engine 在 Java 里是一个 inner class(非静态嵌套类),它持有外部 Service 实例的引用;而 Kotlin 语言规范禁止把 inner class 当作 supertype——你没法在继承时给它一个外部类实例。
Google 官方示例的解法是:把 Engine 子类定义在 Service 类内部,让它天然持有 outer Service 实例。渲染器则不受这个限制,用接口解耦,仍然可以是独立文件、随时插拔新场景。
这个坑的价值在于它是「语言规范级」的,不是查个文档改个参数就能绕过去的。它直接决定了整个包结构:引擎必须贴着 Service 写,渲染器才能自由独立。
坑二:Engine 的 API 签名别想当然
onCreate(SurfaceHolder)是带参数的;onTouchEvent返回Unit(void),不是事件消费布尔值;onOffsetsChanged有 6 个参数。
凭记忆写 override,签名对不上就会默默写进一个没人调的新函数里。
坑三:依赖版本反向要求 compileSdk
androidx.core:core:1.19.0 要求 compileSdk ≥ 37,于是升到 compileSdk 37.2(本机已装该 platform,targetSdk 保持 36 不动)。
这些实现期发现,全部回写进系统设计文档的变更记录,而不是只躺在代码里。最后 gradlew assembleDebug 一次通过,APK 约 29.8 MB。
第五步:M2 场景——水滴、涟漪与「帧内零分配」
「你继续吧」之后进入真正的画面:
WaterDropSystem:重力水滴粒子,用对象池复用,触水时回调产生涟漪事件;RippleSystem:涟漪半径线性扩散、透明度线性衰减,用扁平椭圆模拟水面透视,同样对象池;CaveRenderer升级为分层场景:背景渐变 + 呼吸光 → 钟乳石剪影(确定性随机生成)→ 水面 → 涟漪 → 水滴。
这里有个关键性能纪律:所有 Shader / Path 在 onSurfaceCreated 里预建,onFrame 帧内零对象分配。逐帧 new Paint、new Path、new 粒子对象,GC 就会在屏幕上掉帧。每帧只改 paint 的 alpha 和池内对象的状态。
配套写了单元测试 WallpaperSceneTest,3/3 通过:水滴下落恰好触水一次、涟漪到半径上限回收、涟漪透明度衰减到零回收。粒子的状态机逻辑是纯计算,不碰 Android API,所以能直接在 JVM 测试里跑——这也是把渲染状态拆成可测纯逻辑的回报。
第六步:「为什么只显示 Hello Android?」
装到手机上打开 App,我看到的是一个写着 Hello Android 的空界面。这其实是每个第一次做动态壁纸的人都会撞的墙:
「为什么我通过 Android Studio 运行的时候,界面就显示了一个 Hello Android?」
答案是:那个 MainActivity 只是 Compose 模板自带的占位页,动态壁纸根本不在 App 里展示。它要到系统壁纸选择器里才能预览和绑定。我用的是 Pixel,完整路径是:
长按桌面 → 壁纸与样式 → 更换壁纸 → 动态壁纸 → 山洞水滴 → 预览 → 应用(可选主屏幕与锁屏)。
另外一个只有做过才知道的细节:预览模式(isPreview())下系统不允许发声,所以环境音要在预览时强制静音——这条记进了设计文档,留给 M4 实现。
关键技术决策速查表
| 主题 | 结论 |
|---|---|
| 引擎继承 | Engine 是 Java inner class,Kotlin 禁止其作 supertype → 引擎必须写在 Service 内部;渲染器用接口解耦保持可插拔 |
| Engine API | onCreate(SurfaceHolder) 带参;onTouchEvent 返回 Unit;onOffsetsChanged 六参 |
| compileSdk | androidx.core 1.19.0 要求 ≥ 37,targetSdk 仍保持 36 |
| 帧内零分配 | Shader/Path 在 onSurfaceCreated 预建;粒子走对象池;onFrame 只改 alpha 与池内状态 |
| 省电 | onVisibilityChanged(false) 是唯一权威停帧停声信号,logcat 可验证渲染循环 start/stop |
| 预览声音 | isPreview() 时系统不允许声音,M4 实现时强制无声 |
这套协作方式收获的几条经验
- 第一句就说「先讨论需求」:空工程上最值钱的动作不是写码,是把主题、渲染路线、发布目标先拍板,后面才不会推倒重来。
- 需求和设计都要落盘成文档:v0.2 需求文档 + v0.1 系统设计,是我下次和任何新 Agent 继续聊的公共上下文,不用重新解释一遍。
- 实现期的发现回写设计文档:Kotlin 继承限制这种架构级结论,只留在代码里三个月后就没人记得。
- 语言规范级的坑要单独标注:inner class 继承问题不是「报错→百度→改」,它决定了包结构,值得写进决策表。
- 状态机逻辑写成可单测的纯函数:水滴触水、涟漪回收这类规则,脱离 Android 框架在 JVM 里测,反馈最快。
- 给读者写清验证路径:「Hello Android」不是 bug,是不知道去壁纸选择器里看——App 类项目最容易缺的就是这段引导。
下一步
当前进度到 M2,按系统设计的里程碑后面还有:
- M3:触摸交互(点水面起涟漪、点顶部惊落水滴)+ 翻页视差;
- M4:环境音(SoundPool 水滴 + 布谷鸟声,默认关,声音素材来源待定);
- M5:Compose 设置页 + 配置联动 +
settingsActivity; - M6:省电验证、性能打磨、预览降级。
另外还有个待拍板项:把那个「Hello Android」的 MainActivity 改成**「一键设置壁纸」引导页**,省得每个装包的人都问一遍去哪设置。
说明:M3 之后的触摸、环境音、设置页均为设计目标,尚未实现;本文涉及的 APK 为 debug 构建(约 29.8 MB),未做上架优化。