30分钟快速跑通HarmonyOS AdventureWheel元服务:云手机+AI编译打包安装完整教程
30分钟快速跑通HarmonyOS AdventureWheel元服务:云手机+AI编译打包安装完整教程
这篇教程带你用云手机 + AI 编译打包的方式,在 30 分钟内跑通 HarmonyOS「冒险大转盘」(AdventureWheel)元服务:克隆工程 → AI 生成 HAP → 创建鸿蒙云手机 → 安装并启动 → 体验转盘抽取与本地任务库。项目为朋友聚会提供纯本地的真心话大冒险玩法,内置 190 条任务,支持 JSON/TXT 导入导出,无需服务器。
一、项目是什么:一个聚会可用的真心话大冒险元服务 🎡
AdventureWheel 是一个鸿蒙元服务(手机侧、Stage 模型、ArkTS/ArkUI 开发),核心体验闭环是:
- 开局设置:选「真心话 / 大冒险 / 混合局」,设置 2–20 个任务和最高挑战程度;
- 清单确认:点击「立即开始」先看本局任务清单,不满意可重新生成,确认后才开局;
- 轮流转盘:每人点击一次,Canvas 转盘减速停下、突出命中扇区,动画弹出完整任务卡片;
- 交接与去重:「交给下一位」后该扇区变灰标记「完成」,同局不再重复抽取;
- 任务库:浏览 190 条内置任务,添加/编辑/启停/删除自己的任务,并可导出 JSON 或分享 TXT 带到另一台设备。
技术栈一览:Canvas + 透视变换做 2.5D 转盘动画、Preferences 做本地持久化、DocumentViewPicker + 文件 URI 做导入导出与分享。
二、开始前的环境与资源准备 🧰
| 项目 | 要求 | 说明 |
|---|---|---|
| 云端开发入口 | 鸿蒙开发实践中心作业中心的可用工作区 | 创建项目时能带入案例仓库 |
| 测试设备 | 鸿蒙云手机(或本地模拟器) | 云端「设备管理 → 鸿蒙云手机」创建 |
| 版本兼容 | 目标 API 23,最低兼容 API 20 | 云手机镜像需满足工程要求 |
| 签名 | 本地模拟器可无签名调试 | 真机/云手机按平台实际要求准备 |
| 网络 | 联网 | 获取源码、SDK 与依赖;游戏运行本身不依赖网络 |
💡 本案例无需创建云函数、数据库或服务器,云手机只是运行验证设备,不是应用后端。
完成本文后,你也可以顺着 README.md 第 4 章,从空项目开始用 AI 独立构建自己的版本。
三、第一步:克隆工程并核对目录结构
在开发环境或本机执行克隆:
git clone https://gitcode.com/harmony-practice-center/HarmonyOS-AtomSer-AdventureWheel
完成标志:目录中出现以下关键路径,说明工程导入完整。
AdventureWheel/
├── AppScope/ # 元服务标识、名称和图标
├── entry/src/main/
│ ├── module.json5 # 元服务入口与设备范围
│ └── ets/
│ ├── pages/ # 首页、任务库、转盘页
│ ├── components/WheelCanvas.ets # Canvas 转盘
│ ├── engine/TaskEngine.ets # 随机抽取与同局去重
│ └── store/LocalTaskStore.ets # Preferences 本地存储
├── data/内置任务-v1.0.json # 190 条内置教学任务
├── build-profile.json5
└── oh-package.json5
关键文件对照:
| 文件 | 作用 |
|---|---|
| entry/src/main/ets/pages/SetupPage.ets | 首页开局设置,恢复上次玩法与任务数 |
| entry/src/main/ets/engine/TaskEngine.ets | 开局筛选 + Fisher–Yates 洗牌抽样 |
| entry/src/main/ets/components/WheelCanvas.ets | 2.5D 转盘绘制与旋转动画 |
| entry/src/main/ets/store/LocalTaskStore.ets | 自定义任务本地持久化 |
| data/内置任务-v1.0.json | 95 条真心话 + 95 条大冒险 |
四、第二步:让 AI 编译打包生成 HAP 🤖
在 AI 对话中直接粘贴下面这段提示词(来自 README.md 云端快速体验路线):
请解析当前“冒险大转盘”工程,找到 HarmonyOS 入口,
检查现有 SDK、依赖和构建工具,编译生成 HAP。
可自行处理的问题根据日志修复并重新构建,保持现有功能、包名、
目标 API 23 和最低兼容 API 20。
需要安装工具、修改环境或变更需求时,先说明,由我决定。
完成后告诉我 HAP 的实际位置,以及设备安装的系统和签名条件。
完成标志:构建成功,AI 给出 HAP 的实际路径。
⚠️ 高频构建报错速查:
| 现象/错误码 | 常见原因 | 处理方式 |
|---|---|---|
00303313 |
固定编译 SDK 与工具不匹配 | 使用配套 SDK,保留目标 API 23 / 兼容 API 20 再重新构建 |
| 找不到工具、Java 或 HAP | 路径、目录或环境不匹配 | 让 AI 读取日志定位,确认本次构建产物存在 |
| 案例未导入 | 「案例仓地址」与「Git 仓库地址」字段填混 | 核对案例仓地址,工程出现后再构建 |
记住一条原则:构建成功 ≠ 运行成功,安装与启动要分别核对。
五、第三步:创建并连接鸿蒙云手机 ☁️
- 进入开发环境的「设备管理 → 鸿蒙云手机」;
- 选择满足工程要求(目标 API 23、最低兼容 API 20)的手机镜像,点击创建;
- 连接设备,回到开发环境确认能识别。
完成标志:云手机处于运行状态,且 AI/命令行能识别该设备。多设备同时连接时,后续步骤先列出设备让你选择。
六、第四步:AI 安装 HAP 并启动元服务 📲
继续粘贴提示词:
请识别已连接的鸿蒙云手机,将刚才生成的 HAP 推送、安装,
并启动“冒险大转盘”元服务。多个设备时先列出让我选择。
失败时依据实际错误排查;需要我准备签名或操作时告诉我。
完成后告诉我使用的设备,以及是否已打开首页。
完成标志:云手机桌面/元服务列表中出现「冒险大转盘」并打开首页。
关于签名:公开工程默认不配置签名,可生成无签名 HAP;本地模拟器按官方无签名方式调试即可,真机或云手机若平台明确要求签名,再用自己的调试签名,不要复用他人私钥。
七、第五步:5 分钟体验核心功能 ✅
安装成功后,按这条路线走一遍:
- 首页选「混合局」,任务数拉到 6、挑战程度「适中」,点击「立即开始」;
- 查看本局清单,点击「确认开局」进入转盘页;
- 点击转盘中心「开始」,观察减速、命中扇区高亮与结果卡片入场动画;
- 点击「交给下一位」,该扇区变灰标记「完成」,再转一次——结果不会重复;
- 返回首页进入「任务库」,浏览 190 条内置任务与「我添加的」入口。
进阶玩法:在任务库新增一条「大冒险 / 轻松」的任务,重启应用确认本地保留;再用「分享我的任务」生成 TXT(正文仍是 JSON),在另一台设备导入恢复——这就是本案例的文件迁移能力,契约细节见 docs/任务文件格式.md。
八、跑不通时怎么排查 🔍
按「工程和素材 → 工具与构建 → 设备与签名 → 业务状态」的顺序缩小范围:
| 现象 | 环节 | 恢复方式 |
|---|---|---|
| 无设备或安装失败 | 设备 | 检查连接、API 版本与签名条件,依据原始报错处理,实际安装并打开后再继续 |
| TXT 不能导入 | 迁移 | 对照 docs/任务文件格式.md 检查正文是否为 JSON、是否超过 1 MiB / 1000 条 |
| 分享只打开一个应用 | 迁移 | 接收目标由已安装应用决定;核对文件是否实际接收,必要时改用导出 |
| 自定义任务没被抽到 | 开局 | 检查是否停用、条件不符或超过「本局数量 50%」上限 |
| AI 忘记之前约束 | 实践 | 让 AI 重读需求文档与素材,最小修复后复查 |
排障提示词(直接粘贴给 AI):
请依据实际失败的日志或页面现象复现并定位问题。
区分环境、素材、构建、设备和业务问题,最小修复后重跑失败步骤;
需要改环境或需求先告诉我,由我决定。
说明原因、修改内容和重试结果。
九、接下来可以做什么 🚀
- 想理解实现原理:读 docs/设计说明.md,掌握「两层随机规则」「完成状态不持久化」「动画与结果分离」的设计取舍;
- 想从空项目独立构建:按 README.md 第 4 章「完整实践」,用统一教学素材和八步提示词,2–4 小时做出自己的版本;
- 备份数据超限时:参考 docs/批量迁移说明.md 用工程自带工具安全拆分再逐份导入;
- 素材与字段细节:docs/实践素材说明.md 与 NOTICE.md。
30 分钟跑通「克隆 → AI 编译 → 云手机安装 → 转盘体验」,你就同时完成了 HarmonyOS 元服务打包、设备安装和 ArkTS/ArkUI 动画、本地存储、文件迁移三个知识点的实战验证。祝开局顺利,玩得开心 🎉


