Suntime 在 LuatOS 中的应用与开发实践-程序员充电站

从原理到实践，本文详解 OpenLuat 生态里的 Suntime 日出日落计算模块，覆盖基础配置、异常处理与离线计算要点，适配低资源硬件场景。

重要提醒：

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

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

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

代码开发任务，优先选择 GLM（可能是使用的人数太多，有时候处理较慢）；如果 GLM 处理太慢，再考虑切换到 MiniMax；
其他任务，可以首先选择 ark-code-latest，其次选择 MiniMax，最后选择 GLM（可能是使用的人数太多，有时候处理较慢）；

名词解释

工业引擎主机是什么

工业引擎主机是给用户做多媒体编程的硬件载体；

虽然用 PC 模拟器也能编程，也能下载安装应用市场的 APP，但是工业引擎主机的体验更好玩；

例如工业引擎主机 8101，就是以 Air8101 系列模组为主控的一种工业引擎主机；

应用市场是什么

应用市场和平时大家在手机上使用的应用市场的概念完全一样；

应用市场分为两部分：

1、web 端的应用市场：任何用户都可以在 web 端的应用市场，提交自己开发的 app、查看所有 app；整体效果如下图所示：

2、工业引擎主机或者模拟器上的应用市场：任何用户都可以搜索、查看、下载安装、卸载 app；整体效果如下图所示：

分辨率：

1、“日出日落”app 的 UI 界面，目前基于竖屏 480*800 分辨率设计，我们称这个分辨率为“你的 app 基准分辨率”；

2、有多款不同物理分辨率的竖屏引擎整机，例如 Air8000W 引擎整机的物理分辨率为 320480，Air8101 引擎整机的物理分辨率为 480854，Air1602 引擎整机的物理分辨率为 720*1280，后续可能还有其他型号的引擎整机；

3、工业引擎整机的默认出厂软件，可以根据“你的 app 基准分辨率”，自适应为引擎整机硬件的物理分辨率，这个自适应过程是自动完成的，不需要你的 app 做特殊处理；

4、也就说，虽然你的 app 只是基于了某一种分辨率来设计，但是从理论上说，你的 app 可以在不同分辨率的引擎整机上自适应运行；

概述：

本篇旨在讲述在 8101 畅玩板开发日出日落的时间 app（Suntime）项目的详细过程。

日落的时间 app，是一款使用AirUI 轻量化图形开发框架，基于工业引擎 Air8101B 硬件和 LuatOS 系统软件开发的一款 UI 应用程序。

日落的时间 app 核心功能：

配置城市（或自动定位）
一键展示当日日出、日落核心时刻
同步呈现白昼时长、黄昏 / 正午参考时间，信息全面
倒计时（距离日落还有 X 小时 X 分钟）

app ui 界面：

一、硬件环境准备

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

二、软件环境准备

2.1 代码仓库

当前阶段，工业引擎 8101 项目的代码在 LuatOS 仓库的 master 分支；

2.1.1 了解代码结构

在这个代码分支中，以下三项内容和本项目直接相关：

1、 LuatOS/module/Air8101/project/AirUIFrame/engine_host

工业引擎 8101 项目的默认出厂软件
支持开机欢迎界面、待机界面、主菜单界面
支持 WiFi 设置，系统设置，应用市场功能
如果把工业引擎 8101 比作一个手机，这里的 engine_host 就相当于是手机出厂自带的默认软件功能

2、 LuatOS/module/AirUI/app_store/vertical_app

所有可以在工业引擎 8101 项目上运行的 app，例如 airplane_battle（飞机大战）、game_2048（2048 游戏）、luatos_competition（LuatOS 知识竞赛），等等等等；
这里的每个 app，不是默认出厂软件支持的功能；而是通过默认出厂软件中的应用市场，下载安装后，才可以在模拟器或者工业引擎 8101 上运行；
如果把工业引擎 8101 比作一个手机，这里的每个 app 就相当于手机通过应用商店下载安装的每一个应用；
本文所描述的内容，最重要的一个目标就是：根据自己的 app 需求，生成 app 代码，把代码提交到这个 app_store 目录下

3、 LuatOS/script/libs：LuatOS 扩展库，和 engine_host 中的默认出厂软件目录一起在模拟器上运行或者烧录到工业引擎 8101 上运行；

具体到本项目，软件代码架构如下图所示，黄色背景的你将要开发的某个 app，就是参照本文所描述的内容，你要开发完成的某一个 app

2.1.2点击这里可以通过网络浏览器打开 LuatOS 代码仓库的 master 分支；

2.1.3 大家可以通过 TortoiseGit 或者其他客户端工具拉取代码到自己的电脑上；以便后续通过客户端提交代码到仓库参考这里使用 TortoiseGit 克隆/拉取代码，点击查看 TortoiseGit 详细使用教程

develop 分支代码放在你本地任何你觉得合适的位置，比如本文这里新建了存放的路径是 D:\gir:

注：2.1.2 和 2.1.3 步骤，二选一即可

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

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

本步骤是借助 AI 工具，根据定义的 app 需求，生成 html 文件和图片等资源文件。

AI 工具可以使用 Trae，也可以使用网页版的豆包，也可以使用网页版的 deepseek，生成“包含业务逻辑、可交互体验”的 html 文件；你可以根据自己的实际情况来对比选择使用其他的 AI 工具，经我们对比，网页版的 deepseek 生成的 html ui 效果比较符合需求。

在这一章节记录了使用 deepseek 网页版来生成日出日落的时间 app 的 html 的过程：

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

解压缩打开查看，如下图所示，图片看起来正常，注：这时候我们需要更改图片的名称，图片名称不能有中文，否则后面的代码中无法识别

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

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

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

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

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

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

五、根据 html 文件 + 图片等资源文件 + 代码仓库，让 AI 生成 app 项目代码

本步骤全程在 trae AI 下进行。

在进行本步骤之前，一定确保 2.3 章节 4.验证规则和技能都没有问题，如果验证异常，按照 2.3 章节 2-3-4 步骤重来一遍即可。

5.1 app 代码的基本格式要求

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

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

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

https://docs.openluat.com/ai/trae%2Bluatos-docs-code/project/image/UxKWbLmZnonEnlxmNtncWHcXntg.png

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()

注意事项如下：

前 4 行代码，对 app 的项目和版本信息进行配置，并且打印；实际上没有任何用处，但是为了和我们 LuatOS 开发的完整项目中的 main.lua 格式保持一致，所以也加上了；减少对外沟通解释的成本；
第 6 行的require "airplane_win"和第 8 行的sys.publish("OPEN_AIRPLANE_BATTLE_WIN")，加载当前 app 的 user 目录下用户脚本模块，并且运行；具体的每个 app，需要根据自己的 app 业务逻辑加载很行；
第 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}

注意事项如下：

文件内容必须是 json 格式；
version 的格式必须是 x.y.z 格式，从 1.0.0 开始；
其余字段，参考示例都很好理解；

5.1.5 res 目录

存放 app 使用到的图片，音频，视频，字体等资源文件；
只要不是 Lua 脚本文件，都存放到这里；
代码中使用时，直接以/luadb/_._方式使用
res 目录下不能再包含子目录；

5.1.6 libs 目录

存放 app 使用到的扩展库脚本文件；
如果用到的扩展库脚本文件，在默认出厂软件中已经包含，则此处的 libs 目录是否包含重复的扩展库脚本文件都没有任何影响，即使包含了也没有任何用处，app 使用的仍然是默认出厂软件环境中的扩展库脚本文件；
如果用到的扩展库脚本文件，在默认出厂软件中没有被包含，则此处的 libs 目录必须包含进来；
为了节省空间，如果不确定默认出厂软件中是否已经包含 app 需要的扩展库文件，则可以默认已经包含，在调试 app 过程中，如果发现没有需要的扩展库，会提示出错，此时再加上扩展库脚本文件调试；
已经包含在默认出厂软件中的扩展库文件有：dhcpsrv、dnsproxy、exapp、excloud、exmtn、exnetif、exwin、httpdns、httpplus、udpsrv（2026 年 4 月 7 日的默认出厂软件包含这么多，仅供参考，后续可能会动态增加或者删除）；
libs 目录下不能再包含子目录；

5.1.7 其他注意事项

每个独立的 app 内部不再需要初始化 lcd 和 tp，因为在默认出厂软件中已经完成这两项动作；
每个 app 都可以使用 fskv 来存储键值对参数，仅可以读、写、清除 app 自己创建的参数，没有权限操作每个 app 之外的其他 fskv 参数
每个 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 来生成日出日落的时间 app 代码；

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

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

5.2.1 打开 Trae，切换为 SOLO 模式，打开 LuatOS-develop 项目代码

打开 trae 客户端，新建一个会话任务，专门用来处理日出日落的时间 app 代码生成调试
打开编辑器窗口，可以查看 LuatOS-develop 目录内容
右键点击 app_store，添加到对话。

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

5.2 创建 app 项目目录

在会话窗口继续输入指令：在这个目录下创建一个 Suntime 目录。点击发送箭头按钮，等待创建完成

创建成功后可以在资源管理器 app_store 目录下看到新建的 Suntime 目录
创建 res，user，libs 目录

继续在会话窗口输入：在Suntime目录下创建res，user，libs目录

成功创建后可以在 Suntime_robot 目录下看到子目录 res、user，libs。

5.3 添加资源

手动把 4.4 中下载的 Suntime.html 复制到 Suntime 目录下；（快速找到 Suntime 本地目录的方法：上图页面 Suntime 右键选择在文件资源管理器中显示）
把 4.5 中下载的图片资源复制到 Suntime\res 目录下.

把图片名称改成自己好识别的英文名称。

参考 4.5 的交互生成一个日出日落时间图标图片，下载后修改图片名称为 icon.png，复制图片到 Suntime 目录下.

完成以上三步后最终如下所示:

5.4 生成项目代码

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

参考：D:\git\LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\app_store\Suntime\Suntime.html 中的UI界面和交互逻辑，在Suntime中生成LuatOS代码 代码文件格式以及内容参考D:\git\LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\app_store\下的其他目录，包含main.lua，meta.json，Suntime\user目录下存储具体UI和业务功能的lua代码文件 代码中需要的图片资源在Suntime\user目录下，代码中用到的图片资源，使用\luadb\xxx.png的路径方式

然后luatos-docs-code-102智能体就开始工作了，几分钟之后，会生成第一份代码，思考输出的过程如下图所示：

查看 Suntime 目录下生成了 main.lua、meta.json、Suntime_win.lua、config.lua、message.lua 五个文件，如下图所示：

点击查看生成的 5 个代码文件，单击保留

trae 可能没办法一次就生成可成功运行的代码，按照下述第六章的方式运行代码，查看运行日志和运行效果，继续使用 AI 工具调试修改代码即可，如果要学习完整的一个 app 代码调试过程，可以参考智能售货机项目开发文章。

六、运行 app 并调试代码

6.1 准备运行 app

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

找到本地的 app_store 文件夹

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

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

6.2 在 PC 模拟器上运行

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

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

luatos-pc-64bit.exe D:\git\LuatOS_project\LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\factory\ D:\git\LuatOS_project\LuatOS-develop\script\libs\

输入完成后单击回车键，就可以在模拟器上运行 Air8101 UI 畅玩板出厂软件的出厂软件，启动后如下图所示：

鼠标模拟左右滑屏，翻到第三页，就可以看到自己添加的日出日落的时间 app,点击运行测试 app 功能。

点击日出日落的时间 app 图标，就可以正式运行这个 app；我们点击一下看看是否可以正常运行；点击之后，第一个窗口如下图所示

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

6.3.1 第一轮修复

输入：

商品中的图片没有正常显示，注意使用 D:\git\LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\app_store\Suntime\res 中的图片资源

思考修复过程如下图：

从这次仅仅修改了 Suntime_win.lua，打开这个文件，如下图所示，点击上下切换按钮，可以查看具体的修改内容

如果你会 LuatOS 编程，就知道，智能体这次的修复还是存在问题；我们先不管有什么问题，把 app_store 复制到模拟器目录，再运行一下看看效果，仍然没有显示出来图片

6.3.2 第二轮修复

输入：

你刚才修复之后，图片仍然没有显示出来，另外出现了以下错误日志信息 [ [2026-04-23 16:03:06.500][00000000.841] I/user.sntp 高精度时间戳 1776931384.647 [2026-04-23 16:03:09.442][00000003.783] I/user.idle_win layout 480 800 landscape false cols 4 card 110 92 per_page 24 [2026-04-23 16:03:09.525][00000003.866] W/airui [Warn] (2.675, +2675) lv_image_set_src: failed to get image info: /app_store/air_quality/icon.png lv_image.c:195
[2026-04-23 16:03:15.331][00000009.671] I/user.idle_win open app /app_store/Suntime/ [2026-04-23 16:03:15.331][00000009.672] I/user.exapp.open app started: /app_store/Suntime/ [2026-04-23 16:03:15.333][00000009.674] I/user.[/app_store/Suntime/] main SUNTIME 001.999.000 [2026-04-23 16:03:15.333][00000009.674] I/user.[/app_store/Suntime/] require enter: suntime_win [2026-04-23 16:03:15.335][00000009.676] I/user.[/app_store/Suntime/] sys.run() disabled in sandbox [2026-04-23 16:03:15.335][00000009.676] I/user.[/app_store/Suntime/] app_task waitUntil close_req event /app_store/Suntime/ [2026-04-23 16:03:15.342][00000009.683] I/user.[/app_store/Suntime/] exwin.open window opened, ID: 3 window count: 1

修复之后复制代码到模拟器目录之后，模拟器关闭之后再次运行，效果图如下

可以看出，这次的日出日落的图片还是没有显示出来，；