嵌入式设备：AirUI 节气动画与交互设计实践

本文将完整基于8101引擎主机开发的24节气APP的全开发流程，以合宙Air8101畅玩板作为硬件载体，搭载LuatOS系统提供稳定运行支撑，依托AirUI轻量化图形框架实现流畅交互与简约设计，核心围绕中华传统二十四节气文化展开，将传统民俗内涵与轻量化硬件应用深度融合，打造出一款兼具观赏性与实用性的特色应用。

1. 国风节气列表首页以卡片布局，呈现全部二十四节气，每张卡片清晰标注节气名称、时间区间与专属标识。
2. 节气全维度详解：点击节气卡片即可进入详情页面，全方位解锁节气内涵，包含节气概述、三候物候、古籍典故（原文 + 白话释义）、气候农时特点、养生饮食指南、经典节气诗词、民间传统习俗以及节气谚语歌谣。
3. 节气歌速览首页顶端展示完整版二十四节气歌，方便诵读记忆，传承传统节气文化。

24 节气 app ui 界面：

一、准备硬件环境

1. WIN10 以及 WIN10 以上的 Windows 操作系统电脑一台
2. 合宙引擎 8101 一块 +type-c 接口 usb 数据线一根
3. 如果没有上述 2 的硬件设备，可以直接在电脑端 pc 模拟器上开发调试 app

二、准备软件环境

2.1 代码仓库

1. 当前阶段，合宙引擎 8101 项目的代码在 LuatOS 仓库的 master 分支； <<<<<<< HEAD:docs/root/docs/ai/trae+luatos-docs-code/project/air8101_engine_project_app/005_24_Solar_Terms.md

2. 点击这里可以通过网络浏览器打开 LuatOS 代码仓库的 master 分支，可以直接点击克隆/下载，下载在本地

   c413a283b3197c2ac4d1f8b8022673c306c6bc13:docs/root/docs/ai/trae+luatos-docs-code/project/engine_host_vertical_app/005_24_Solar_Terms.md

1. （本步骤和步骤 2，二选一即可）通过 TortoiseGit 或者其他客户端工具拉取上述 master 分支代码到自己的电脑上，以便后续通过客户端提交代码到仓库，只本地运行的话可以不用客户端克隆/下载，直接步骤 2 下载即可；
2. 参考这里使用 TortoiseGit 克隆/拉取代码，点击查看 TortoiseGit 详细使用教程
3. master 分支代码放在你本地任何你觉得合适的位置，比如本文这里新建了存放的路径是 F:\LuatOS-master：

2.2 PC 模拟器

下载 Luatools 工具：luatos.com；

点击此处下载学习 Luatools 工具；

使用模拟器时，直接使用在本文 2.1.3 章节下载的 LuatOS-master 分支代码进行学习；

在本小节，使用 LuatOS 模拟器 +LuatOS-master 分支代码，可以正常运行起来一个 UI 项目就算达标；

2.3 AI 工具

AI 工具有很多种，有 Trae，Copilot 等等，每一种 AI 工具都可以配置不同的大模型，我们并不限制你使用哪一种 AI 工具；

各种 AI 工具使用的基本思路都是相同的，在本文，我们仅仅基于 Trae 这种 AI 工具来介绍，如果你使用其他 AI 工具，遇到不懂的问题，可以自行解决；

参考 Trae 的安装和智能体概念理解 和 安装 luatos-docs-code 智能体、规则和技能 安装好 Trae，配置 luatos-docs-code 智能体，配置项目规则和技能；其中：在 Trae 的安装和智能体概念理解第三章节中，不用再新建项目，直接打开自己电脑上的 LuatOS-master 目录即可；

Trae 的配置使用有以下三点特别重要：

1. 当你安装配置好智能体、规则和技能后，最终一定要参考验证智能体、规则和技能是否安装成功来验证安装配置是否正确；

2. Trae 中内置的免费大模型，会经常排队，并且性能不可控，容易出问题，所以推荐参考：001 发送会话请求时，提示排队，如何解决？的方法，订阅收费的大模型（目前每月 40 元）；这样可以大大提高 AI 性能；如果不想使用收费模型，在非正常工作时间段内，使用内置的免费模型也能勉强凑合；

3. 选择收费大模型时，经过我们的实际测试，根据工作任务的不同，可以按照如下建议选择（仅供参考，具体情况还需要根据你自己的实际使用情况来定）：

4. 代码开发任务，优先选择 GLM（可能是使用的人数太多，有时候处理较慢）；如果 GLM 处理太慢，再考虑切换到 MiniMax；

5. 其他任务，可以首先选择 ark-code-latest，其次选择 MiniMax，最后选择 GLM（可能是使用的人数太多，有时候处理较慢）；

三、定义自己的 app 原始需求

以一款实际的应用程序需求为案例，完整演示项目开发的全流程。

本次演示所用应用 APP 的名字是：「24 节气」。

对于应用开发需求，若界定不够清晰，仅需进行简要描述即可；

若需求明确具体，则需对各页面设计方案及业务逻辑架构展开详细说明。

在本次示例中，由于 24 节气属于民俗节气查询类 APP 品类，应用相对简单，因此对应的原始需求描述较为简洁，以此为基础，观察 AI 的实现效果。

如下所述：

设计一个可用于嵌入式设备的售货机项目页面和交互业务逻辑，分辨率为480*800，输出可以交互的html页面

四、根据 app 需求，借助 AI 工具，生成 html 文件和图片等资源文件

本步骤选择 Deepseek 这个 AI 工具，根据定义的 app 需求，生成 html 文件和图片等资源文件。

使用网页版的 deepseek，生成“包含业务逻辑、可交互体验”的 html 文件； 可以根据自己的实际情况来对比选择使用其他的 AI 工具。

在这一章节记录了使用 deepseek 网页版来生成 24 节气的 html 的过程：

4.1 生成 ui 界面.html 文件

4.1.1 输入

帮我生成一个html，用于嵌入式设备UI 演示 窗口竖屏，分辨率w=320,h=480 实现24节气的浏览功能

4.1.2 输出

全生成后的体验效果如下图：

4.1.3 存在的问题

点击运行，可以看到，生成的 html 中，点击节气卡片无法跳转到详情页；

4.2 第二轮交互（支持跳转详情页）

4.2.1 输入

点击节气卡片，进入详情页页面，每一个节气的详情页展示这个节气的介绍、历史渊源、农业、气候特征、 饮食与养生、节日祝福、谚语歌谣等信息

4.2.2 输出

生成后的体验效果如下图：

4.1.3 存在的问题

详情页下方没有添加「归卷」「上一个 / 下一个节气」的导航按钮

4.3 第三轮交互（添加详情页导航按钮）

4.3.1 输入

详情页下方添加「归卷」「上一个 / 下一个节气」的导航按钮

4.3.2 输出

等完全生成后，如下图所示

4.4 第三轮交互（完善首页节气歌内容）

4.4.1 输入

首页位置，二十四节气歌，完整显示：春雨惊春清谷天，夏满芒夏暑相连。秋处露秋寒霜降，冬雪雪冬小大寒

4.4.2 输出

生成后的体验效果如下图：

4.3.3 html 满足需求

经过本轮设计，生成的两个页面和业务逻辑可以满足需求，所以本阶段的 html 设计就算完成；

此时我们把 html 源码文件保存下来，命名为 24_Solar_Terms；

4.5 第四轮交互（导出所有图片资源）

虽然在前面已经生成了最终可以满足需求的 html 文件，但是还有一个问题没有解决，html 中使用到的图片资源，还没有导出来，所以我们此时让 AI 把图片资源导出来

4.5.1 输入

生成一个完整的HTML文件。该文件在之前看到的24节气浏览界面基础上，右下角增加了一个"导出图片”按钮(样式与原有按钮统一，不破坏整体UI)，点击后即可将节气图片、详情页小图片，打包成zip文件下载注意要求 AI 给出的图片都用英文命名，不然后期要一个一个修改

4.5.2 输出

它会在 html 效果图中增加了一个导出图片按钮，如下图所示，点击这个按钮，就导出了大部分图片资源

4.5.3 图片资源

我们把导出的图片资源包命名为 24_Solar_Terms_images.zip

解压缩打开，如下图所示，查看图片看起来正常。

4.6 总结

这个阶段，主要就是根据需求，不断的和 AI 交互，生成 html；

你自己的实际 app，根据自己的规划以及实际运行的效果，可能需要调整多次才行；

按照同样的交互思路，进行多轮交互即可，直到生成的 html 界面和交互逻辑可以满足你的需求；

最后再导出来用到的所有图片资源；

具体到本项目，最终输出了 24_Solar_Terms.html 和 24_Solar_Terms_images.zip 两个文件；

我们在接下来的编码环节会用到这两个文件；

5.1 app 代码的基本格式要求

app 代码有基本的格式要求；

我们先来看看 2.1.3 章节下载下来的 LuatOS-master 代码仓库中的 vertical_app 目录，在 vertical_app 内，每个子目录都是一个单独的 app，如下图所示：

我们以 airplane_battle 为例，来说明 app 内部的代码结构和格式要求：

5.1.1 main.lua

app 的入口文件，必须存在于单独 app 的根目录下；

文件内容按照以下格式编写即可：

PROJECT="AIRPLANE_BATTLE"VERSION="001.999.000"log.info("main", PROJECT, VERSION)require"airplane_win"sys.publish("OPEN_AIRPLANE_BATTLE_WIN")sys.run()

注意事项如下：

1. 前4行代码，对app的项目和版本信息进行配置，并且打印；实际上没有任何用处，但是为了和我们LuatOS开发的完整项目中的main.lua格式保持一致，所以也加上了；减少对外沟通解释的成本；

2. 第6行的require "airplane_win"和第8行的sys.publish("OPEN_AIRPLANE_BATTLE_WIN")，加载当前app的user目录下用户脚本模块，并且运行；具体的每个app，需要根据自己的app业务逻辑加载很行；

3. 第10行的sys.run()，实际上没有任何用处，但是为了和我们LuatOS开发的完整项目中的main.lua格式保持一致，所以也加上了sys.run()的调用；减少对外沟通解释的成本；

5.1.2 icon.png

app的图标文件，必须存在于单独app的根目录下；

要求：png格式，32*32像素，背景色透明；

5.1.3 meta.json

app的元数据文件，必须存在于单独app的根目录下；

文件内容按照以下格式编写即可：

{"app_name_cn":"飞机大战","app_name_en":"airplane-battle","version":"1.0.0","publish_time":"2026-04-04 12:00:00","category":"游戏","description":"拖拽飞机躲避敌机，自动发射子弹并挑战更高分数","resolution":"480x800","supported_models":{"Air8101":[{"firmware_id":104,"min_firmware_version":2010},{"firmware_id":105,"min_firmware_version":2010}]},"zip_size_kb":100,"origin_size_kb":300}

注意事项如下：

1. 文件内容必须是json格式；

2. version的格式必须是x.y.z格式，从1.0.0开始；

3. 其余字段，参考示例都很好理解；

5.1.4 user目录

1. 存放app具体功能模块的用户Lua脚本文件；

2. user目录下不能再包含子目录；

5.1.5 res目录

1. 存放app使用到的图片，音频，视频，字体等资源文件；

2. 只要不是Lua脚本文件，都存放到这里；

3. 代码中使用时，直接以/luadb/*.*方式使用

4. res目录下不能再包含子目录；

5.1.6 libs目录

1. 存放app使用到的扩展库脚本文件；

2. 如果用到的扩展库脚本文件，在默认出厂软件中已经包含，则此处的libs目录是否包含重复的扩展库脚本文件都没有任何影响，即使包含了也没有任何用处，app使用的仍然是默认出厂软件环境中的扩展库脚本文件；

3. 如果用到的扩展库脚本文件，在默认出厂软件中没有被包含，则此处的libs目录必须包含进来；

4. 为了节省空间，如果不确定默认出厂软件中是否已经包含app需要的扩展库文件，则可以默认已经包含，在调试app过程中，如果发现没有需要的扩展库，会提示出错，此时再加上扩展库脚本文件调试；

5. 已经包含在默认出厂软件中的扩展库文件有：dhcpsrv、dnsproxy、exapp、excloud、exmtn、exnetif、exwin、httpdns、httpplus、udpsrv（2026年4月7日的默认出厂软件包含这么多，仅供参考，后续可能会动态增加或者删除）；

6. libs目录下不能再包含子目录；

5.1.7 其他注意事项

1. 每个独立的app内部不再需要初始化lcd和tp，因为在默认出厂软件中已经完成这两项动作；

2. 每个app都可以使用fskv来存储键值对参数，仅可以读、写、清除app自己创建的参数，没有权限操作每个app之外的其他fskv参数

3. 每个app都可以使用io核心库执行文件和目录操作，仅可以控制自己app内的目录和文件，自己app的所有目录和文件都可读，自己app内的部分目录和文件可写，操作目录和文件时以/luadb/或者/开头，app内部会自动做路径映射，路径映射关系如下（前面三种只读，最后两种可读写）

   • /luadb/icon.png：映射到 /icon.png（应用图标，特殊处理）
   • /luadb/xxx.lua 或 /luadb/xxx.luac：按优先级映射
     • /xxx.lua或者luac
     • /user/xxx.lua或者luac
     • /libs/xxx.lua或者luac
   • /luadb/xxx（非lua文件）：映射到 /res/xxx（资源文件目录）
   • /ram/xxx：直接返回 /ram/xxx（内存文件系统，不做转换）
   • /xxx（其他以/开头的路径）：映射到 /data/xxx（数据存储目录）

5.2 Trae 生成 app 代码前的准备工作

在了解了每个 app 的代码基本格式和要求之后，接下来我们使用 Trae 来生成24节气app 代码；

注意：5.2.1 和 5.2.2 的顺序不能颠倒，必须是先打开项目代码，然后再验证项目规则和技能

如果此处验证不通过，返回到本文的 2.3 章节重新学习操作一遍

5.2.1 检查配置

参考2.3章节的内容，查验Trae的1. SOLO模式、2. LuatOS-master、3. luatos-docs-code、4. Trae中智能体模型的项目规则和技能配置是否正确配置；

5.2.1 新建一个会话任务，专门用来24节气app代码生成调试

5.3 Trae生成app代码

为了演示整个过程的字节，此处拆分为多步来逐步生成

5.3.1 在vertical_app下创建24_Solar_Terms目录

首先我们在F:\LuatOS_master\module\AirUI\app_store\vertical_app下创建一个24_Solar_Terms目录；

创建目录的方式有很多种，此处仅仅演示使用Trae创建的过程；

1. 在工具右侧的资源管理器中，找到F:\LuatOS_master\module\AirUI\app_store\vertical_app\24_Solar_Terms\目录，鼠标点击右键，在弹出的菜单中，选择添加到对话

1. 此时可以看到vertical_app目录已经被添加到会话窗口，如下图所示

1. 在会话窗口继续输入在这个目录下创建一个24_Solar_Terms目录，如下图所示，然后点击发送箭头按钮

1. 如下图所示，最终创建成功

5.3.2 在24_Solar_Terms目录下创建res，user，libs目录

会话窗口输入：在24_Solar_Terms目录下创建res，user，libs目录

最终创建成功，如下图所示

5.3.3 把第四章节生成的html和图片文件复制过来

这一步就不借助Trae完成了，直接人工手动操作：

1. 手动将24_Solar_Terms.html复制到24_Solar_Terms目录下；

2. 将所有图片改名为英文命名，然后复制到24_Solar_Terms/res目录下

完成这两步操作之后，如下图所示

5.3.4 第一次自动生成app代码

在会话窗口输入以下内容（LuatOS-master路径需要根据你自己电脑上的实际路径来修改），并且发送：

1、参考：F:\LuatOS_master\module\AirUI\app_store\vertical_app\24_Solar_Terms\24_Solar_Terms.html 中的UI界面和交互逻辑，在24_Solar_Terms中生成LuatOS代码2、代码文件格式以及内容参考F:\LuatOS_master\module\AirUI\app_store\vertical_app\下的其他目录，包含main.lua，meta.json，24_Solar_Terms\user目录下存储具体UI和业务功能的lua代码文件3、代码中需要的图片资源在24_Solar_Terms\user目录下，代码中用到的图片资源，使用\luadb\xxx.png的路径方式

然后luatos-docs-code-103智能体就开始工作了，几分钟之后，生成了第一份代码

完成后 24_Solar_Terms 目录下生成了 main.lua、meta.json、24_Solar_Terms_win.lua、三个文件，如下图所示：

在中间的编辑器窗口，依次点击main.lua、meta.json、24_Solar_Terms_win.lua三个文件,点击保留按钮，如下图所示

5.3.5 手动生成一个 24 节气的 icon.png

使用网页版的 deepseek，输入帮我搜索或者生成一个适用于24节气应用的图标，png格式，32*32像素，背景色透明，直接生成了一个 html 页面，运行这个页面，可以下载下来一个 32*32 像素的图标，能直接使用，如下图所示（我是直接让生成 3 个，从中选取了一个）

把下载下来的图片，改名为 icon.png，然后复制到 24_Solar_Terms 目录下，如下图所示

在本章节，我们在 LuatOS 模拟器上不断地运行刚才生成的 24_Solar_Terms 代码；

如果发现问题，让 Trae 不断的调试，直到在模拟器上可以正常运行；

6.1 准备运行 app

1. 右键 vertical_app，选择 在文件资源管理器中显示

1. 找到本地的 vertical_app 文件夹

1. 把 vertical_app 文件夹复制到 LuatOS PC 模拟器所在的目录。

可以查看 2.2 PC 模拟器章节中的操作，本教程 LuatOS PC 模拟器所在的目录是 E:\PC 模拟器\LuatOS-SoC_V2026_PC

6.2 在 PC 模拟器上运行

1. 找到 PC 模拟器目录下的 cmd 快捷方式，双击打开，如下图所示

1. 在命令行窗口粘贴输入以下指令：

luatos-pc-64bit.exe F:\LuatOS_project\LuatOS-master\app_engine\factory F:\LuatOS_project\LuatOS-master\script\libs

1. 输入完成后单击回车键，就可以在模拟器上运行 合宙引擎 Air8101 出厂软件的出厂软件，启动后如下图所示：

1. 鼠标模拟左右滑屏，就可以看到自己添加的 24 节气 app，点击运行测试 app 功能，看看是否可以正常运行；。

1. 点击一下点击之后，第一个窗口如下图所示

1. 点击节气卡片进入详情页，如下图所示

1. 从图片种可以看出，主页节气图片和详情页小图标都没有显示出来

总的来说，虽然已经有基本的轮廓，但是也存在不少问题，接下来我们使用智能体来修复每一个问题，尝试修复之后，再次复制 vertical_app 代码到模拟器所在目录下，再次运行模拟器来验证

6.3 修复问题：商品中的图片没有正常显示

6.3.1 第一轮修复

输入：

首页中的图片没有正常显示，注意使用F:\LuatOS_master\module\AirUI\app_store\vertical_app/24_Solar_Terms/res中的图片资源

查看智能体的思考过程，看下它这次具体修改了什么代码；这次仅修改了 24_Solar_Terms_win.lua，修改完成之后，点击查看具体的修改内容，

如果你会 LuatOS 编程，就知道，智能体这次的修复还是存在问题；我们先不管有什么问题，把修改的内容点击保留_（不需要让 AI 修改的部分点击__撤销__）_，把 vertical_app 复制到模拟器目录，运行一下看看效果，

图片仍然没有显示出来的话，可以进行多次交互，

直到在模拟器的运行后，首页和详情页图片正常显示出来，如下图所示

通过 6.3.1 小节调试修复这个问题，我们可以总结出重要的一点：智能体修复过程中，你要学会看代码，根据代码思路和实际效果，给智能体更详细的输入信息和指令，它可以理解得更透彻！

6.3.2 第二轮修复

输入：

所有详情页面“历史渊源·古文引证"处的文字在容器内不能完整显示，马上修正

查看思考和修改内容，保存修改内容，如下图所示

多次交互后，“历史渊源·古文引证"处的文字可以在容器内完整显示

6.4 总结

6.4.1 AI 代码没法直接完美运行

程序运行过程中，若出现图片无法加载、应用启动失败、图片显示异常、字体渲染错误、色彩参数不符等问题，可依照前述全部流程进行多次迭代修改。其余代码调试相关问题，可查阅智能售货机项目开发文档智能售货机项目开发文档 ，或在技术交流群内实时沟通解决。

6.4.2 任何一个 app，最基本的测试列表

1. app 内部有退出按钮，可以点击返回到主菜单窗口；app 退出后，在主菜单窗口，再次点击，可以再次正常进入 app；如果有问题，参考 6.8 章节检查代码
2. app 内部的基本业务逻辑和 UI 界面都正常
3. 退出 app 后，app 内部的业务逻辑也要停止，不要在后台运行；如果自己的 app 内部有运行日志，可以通过日志判断是否在后台运行；

就分享到这里了