本文档基于 LuatOS 与 Air8101 硬件平台，从零开始搭建智能售货机项目的完整开发环境。通过本文，您将掌握从硬件准备、软件配置到项目代码获取的全流程，为后续的售货机应用开发打下坚实基础。

一、硬件环境准备

1. WIN10 以及 WIN10 以上的 Windows 操作系统电脑一台
2. 合宙引擎主机8101一块 +type-c 接口 usb 数据线一根；这一步的环境不是必须的，如果没有这个环境，可以直接在模拟器上开发调试 app；

二、软件环境搭建

2.1 代码仓库

当前阶段，合宙引擎主机8101项目的代码在 LuatOS 仓库的 develop 分支；

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

2.1.1 了解代码结构

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

1、 LuatOS/module/Air8101/project/AirUIFrame/ui_play_board/factory

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

2、 LuatOS/module/Air8101/project/AirUIFrame/ui_play_board/app_store

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

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

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

2.1.2 下载代码到自己的电脑上

大家可以通过 TortoiseGit 或者其他客户端工具拉取代码到自己的电脑上；

一定要通过客户端下载代码到自己的电脑上，因为后续还要通过客户端提交代码；

在这里仅以 TortoiseGit 为例来说明，如果使用其他的客户端工具，自行通过 AI 学习如何使用；

此处仅仅说明 TortoiseGit 最基本的使用方法，遇到不懂的问题，可以随时沟通或者借助 AI 学习；

1. 在 https://gitee.com 注册账户；如果已经有账户，跳过这一步；如果账户还没有添加到合宙 LuatOS 仓库，在群里面发出来账户，申请添加；只有将户号添加到 LuatOS 仓库，后续才能提交代码；
2. 下载安装 git，Git 官网最新 windows 版本下载地址，如果官网地址很难打开，可以通过国内镜像 https://mirrors.ustc.edu.cn/github-release/git-for-windows/git/下载，也可以问豆包：推荐几个国内可以下载git的地址，下载下来之后，一路默认安装即可；
3. 下载安装 TortoiseGit 客户端，TortoiseGit 官网最新版本软件下载地址，一路默认安装，在下图需要填写第 1 步注册的名称和邮箱地址：

1. 通过 TortoiseGit 下载代码，在你的电脑上随便找一个目录，空白处点击右键，选择 Git Clone…，URL 输入：https://gitee.com/openLuat/LuatOS.git，Directory 的最后一级目录修改为 LuatOS-develop

下载过程中，如下图所示：

下载成功后，如下图所示：

2.1.3 代码切换到 develop 分支

找到刚才下载的 LuatOS-develop 代码目录，鼠标点击右键，选择 TortoiseGit，选择 Switch/Checkout…，如下图所示：

在打开的小窗口中，Branch 选择 remote/origin/develop，然后点击 OK，如下图所示

切换成功后，会弹出下图所示窗口

此时，可以打开 LuatOS-develop 目录，去看下 2.1.1 章节中所描述的三部分内容是否存在，如果存在，就证明切换成功；

2.2 模拟器

点击此处学习 LuatOS 模拟器；

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

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

2.3 AI 工具

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

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

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

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

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

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

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

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

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

接下来，我们以一个实际的 app 需求为例，来演示完整的开发过程；

这个 app 的名字叫做：智能售货机

如果需求不是特别明确，就简单描述一下即可；如果需求特别明确，则详细描述每个页面如何设计，以及业务逻辑如何设计；

在本示例中，因为售货机 app 仅仅是一个虚拟的演示项目，并不是一个真正的 app 需求，所以我们描述的原始需求比较简单，如下所述：

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

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

根据定义的 app 需求，可以使用 Trae，也可以使用网页版的豆包，也可以使用网页版的 deepseek，生成“包含业务逻辑、可交互体验”的 html 文件；（经过我的对比测试，网页版的 deepseek 生成的 html ui 效果比较，你可以根据自己的实际情况来对比选择）

在这一章节，我仅仅演示使用 deepseek 网页版来生成 html 的过程

4.1 第一轮交互（原始需求）

4.1.1 输入

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

4.1.2 输出

等完全生成后，参考下图体验效果

4.1.3 存在的问题

可以看到，生成的 html 中，仅支持投币购买，不支持现在主流的扫码购买，所以这个问题比较严重；

4.2 第二轮交互（仅支持扫码支付）

4.2.1 输入

仅支持扫码支付，选择支付后，弹出一个二维码，让用户扫码支付，提示支付结果

4.2.2 输出

4.2.3 存在的问题

在 合宙引擎主机8101上，每个 app 都需要一个退出按钮，点击这个按钮可以关闭退出本 app；

可以看到，生成的 html 中，还没有这个按钮；

4.3 第三轮交互（支持退出按钮）

4.3.1 输入

主页的下面增加一个退出按钮，可以不实现退出按钮的业务逻辑

4.3.2 输出

等完全生成后，第一张图片已经增加了退出按钮，如下图所示

4.3.3 html 满足需求

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

此时我们把 html 源码文件保存下来，命名为 vending_machine.html;

大家可以用电脑上网页浏览器打开

右键点我，另存为，下载html文件

实际看一下效果；

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

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

4.4.1 输入

帮我导出这里面的所有图片资源

4.4.2 输出

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

4.4.3 图片资源

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

解压缩打开查看，如下图所示，除了二维码图片异常外，其余图片看起来正常

接下来再次告诉 AI：我点击导出图片按钮后，导出的图片中，二维码图片不正确

AI 开始重新生成，最终点击导出图片按钮后，导出了全部正确的图片

右键点我，另存为，下载图片资源包

4.5 总结

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

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

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

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

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

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

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

5.1 app 代码的基本格式要求

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

我们先来看看 2.1.3 章节下载下来的 LuatOS-develop 代码仓库中的 app_store 目录，在 app_store 内，每个子目录都是一个单独的 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 内部会自动做路径映射，路径映射关系如下（前面三种只读，最后两种可读写）
4. /luadb/icon.png：映射到 \/icon.png（应用图标，特殊处理）
5. /luadb/xxx.lua 或 /luadb/xxx.luac：按优先级映射
   • \/xxx.lua 或者 luac
   • \/user/xxx.lua 或者 luac
   • \/libs/xxx.lua 或者 luac
6. /luadb/xxx（非 lua 文件）：映射到 \/res/xxx（资源文件目录）
7. /ram/xxx：直接返回 /ram/xxx（内存文件系统，不做转换）
8. /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 项目代码

1. 打开 Trae，切换为 SOLO 模式；如下图所示，在工具的左上角有 SOLO 字样

1. 打开 LuatOS-develop 项目代码，如下图所示，在会话窗口的左上角可以显示当前打开的项目目录，如果目录不对，可以点击箭头处，选择打开文件夹，找到正确的目录打开即可

5.2.2 验证 Trae 中的智能体，模型，项目规则和技能配置是否正确

1. 使用 luatos-docs-code 智能体，写本篇文章时，最新版本为 luat-docs-code-101，当你阅读本文章时，如果有更新的版本，使用更新的版本即可；如下图所示，在会话窗口有智能体名称；如果不对，点击箭头处，选择正确的智能体

1. 根据实际情况配置合适的模型
2. Trae 中内置的免费大模型，会经常排队，并且性能不可控，容易出问题，所以推荐参考：001 发送会话请求时，提示排队，如何解决？的方法，订阅收费的大模型（目前每月 40 元）；这样可以大大提高 AI 编程的质量；如果不想使用收费模型，在非正常工作时间段内，使用内置的免费模型也能勉强凑合；
3. 选择大模型时，经过实际测试，GLM，MiniMax 的效果比较好，大家根据自己实际使用的情况对比选择；
4. 最终建议：能使用收费模型尽量使用收费模型，会让你在接下来的工作中省很多时间
5. 模型配置如下图所示，我使用的是收费的 GLM-4.7 模型
6. 在会话窗口输入内容：完整的告诉我，给你配置了哪些提示词、规则和技能？ 如果给出的回复包含以下红框中的几点信息，则表示项目规则和技能配置正确

5.2.3 新建一个会话任务，专门用来处理售货机 app 代码生成调试

5.2.4 打开编辑器窗口，可以查看 LuatOS-develop 目录内容

5.3 Trae 生成 app 代码

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

5.3.1 在 app_store 下创建 vending_machine 目录

首先我们在 LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\app_store 下创建一个 vending_machine 目录；

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

1. 在工具右侧的资源管理器中，找到 LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\app_store 目录，鼠标点击右键，在弹出的菜单中，选择 添加到对话
2. 此时可以看到 app_store 目录已经被添加到会话窗口，如下图所示

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

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

5.3.2 在 vending_machine 目录下创建 res，user，libs 目录

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

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

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

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

1. 手动将 vending_machine.html 复制到 vending_machine 目录下；
2. 将下图红框中的几张图片改名为英文名称，然后复制到 vending_machine/res 目录下

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

5.3.4 第一次自动生成 app 代码

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

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

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

可以看出，这次交互，生成了 main.lua、meta.json、vending_machine_win.lua 三个文件，如下图所示

依次点击这三个文件，在中间的编辑器窗口，点击保留按钮，如下图所示

5.3.5 手动生成一个售货机的 icon.png

之前尝试过让 Trae 从网上搜索一个 app 的图标，处理成 32*32 像素，背景色透明的样式；

但是 Trae 搜索的过程非常漫长，看起来效率比较低；

所以此处，就不再使用 Trae 来生成 icon.png；

首先使用网页版的豆包，输入 帮我搜索或者生成一个适用于智能售货机应用的图标，png格式，32*32像素，背景色透明，豆包可以生成，但是像素不满足需求，一直输出 20482048 像素，让他改成 3232 像素，总是改不过来；

接着使用网页版的 deepseek，输入 帮我搜索或者生成一个适用于智能售货机应用的图标，png格式，32*32像素，背景色透明，直接生成了一个 html 页面，运行这个页面，可以下载下来一个 32*32 像素的图标，能直接使用，如下图所示

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

六、在模拟上运行 app，根据运行结果，让 Trae 不断的调试代码，直到运行通过

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

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

如果你忘记了模拟器怎么使用，再参考本文的 2.2 章节回顾学习一下；

6.1 将 app_store 目录复制到 LuatOS 模拟器所在的目录

如下图所示，将

G:\code\LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\app_store

整个目录复制到 LuatOS 模拟器所在的目录

G:\code\LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\app_store

6.2 使用 cmd 命令行 +LuatOS 模拟器运行：LuatOS 扩展库代码 +合宙引擎主机8101出厂软件

1. 双击打开模拟器所在目录的 cmd，如下图所示

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

luatos-pc.exe G:\code\LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\factory\ G:\code\LuatOS-develop\script\libs\

如下图所示

1. 按回车键，就可以在模拟器上运行 合宙引擎主机8101出厂软件的出厂软件，启动后如下图所示：

1. 点击右下角的 主菜单 按钮，打开主菜单窗口，如下图所示，可以看到，出现了 智能售货机 app

1. 点击 智能售货机 app 图标，就可以正式运行这个 app；我们点击一下看看是否可以正常运行；点击之后，第一个窗口如下图所示

1. 点击扫码支付按钮，打开二维码支付窗口如下图所示

1. 点击我已支付完成按钮，直接提示运行错误，模拟器异常关闭，如下图所示

1. 除此之外，很多图片和小图标都没有显示出来
2. 总的来说，虽然已经有基本的轮廓，但是也存在不少问题，这里就不完整列举具体的问题了，接下来我们使用智能体来修复每一个问题，尝试修复之后，再次复制 app_store 代码到模拟器所在目录下，再次运行模拟器来验证

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

6.3.1 第一轮修复

输入：

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

思考修复过程如下图：

从智能体的思考过程我们可以看出，他把 emoji 替换为了 res 目录下的图片资源，看起来思路没问题，我们先不管智能体修复的是否正确，先来看下它这次具体修改了什么代码；这次仅仅修改了 vending_machine_win.lua，打开这个文件，如下图所示，点击上下切换按钮，可以查看具体的修改内容

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

6.3.2 第二轮修复

输入：

你刚才修复之后，图片仍然没有显示出来

思考修复过程如下图（重点关注红框部分）：

复制代码到模拟器目录之后，模拟器关闭之后再次运行，效果图和上次完全一样，图片仍然没有显示出来，此时还多了一些错误日志，如下图所示

6.3.3 第三轮修复

输入：

你刚才修复之后，图片仍然没有显示出来，另外出现了以下错误日志信息 [2026-04-06 09:54:17.608][00000008.575] E/user.[/app_store/vending_machine/] resolve_file_path path must start with /luadb/ or /: \luadb\cola.png [2026-04-06 09:54:17.613][00000008.580] E/user.[/app_store/vending_machine/] resolve_file_path path must start with /luadb/ or /: \luadb\sprite.png [2026-04-06 09:54:17.616][00000008.583] E/user.[/app_store/vending_machine/] resolve_file_path path must start with /luadb/ or /: \luadb\orange_juice.png [2026-04-06 09:54:17.619][00000008.586] E/user.[/app_store/vending_machine/] resolve_file_path path must start with /luadb/ or /: \luadb\material_water.png [2026-04-06 09:54:17.623][00000008.590] E/user.[/app_store/vending_machine/] resolve_file_path path must start with /luadb/ or /: \luadb\potato_chips.png [2026-04-06 09:54:17.624][00000008.592] E/user.[/app_store/vending_machine/] resolve_file_path path must start with /luadb/ or /: \luadb\chocolate.png [2026-04-06 09:54:17.628][00000008.595] E/user.[/app_store/vending_machine/] resolve_file_path path must start with /luadb/ or /: \luadb\biscuit.png [2026-04-06 09:54:17.632][00000008.599] E/user.[/app_store/vending_machine/] resolve_file_path path must start with /luadb/ or /: \luadb\energy_drink.png

思考修复过程如下图（重点关注红框部分）：

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

可以看出，这次的商品图片和二维码图片都显示出来了，但是商品图片太大，显示区域太小，我们需要调整一下图片大小才行；

另外还有一个比较好的结果，我们让它修复商品中的图片显示问题，它把二维码图片显示问题也修复了，它会一起修复类似的问题；

6.3.4 第四轮修复

输入：

商品中的图片可以正常显示了，但是图片尺寸太大，没有显示完整

思考修复过程如下图（重点关注红框部分）：

复制代码到模拟器目录之后，模拟器关闭之后再次运行，仍然没有显示完整；

6.3.5 第五轮修复

输入：

图片还是没有显示完整，你要缩小图片尺寸，才能显示完整，好好思考一下

思考修复过程如下图（重点关注红框部分）：

复制代码到模拟器目录之后，模拟器关闭之后再次运行，仍然没有显示完整；

6.3.6 第六轮修复

看来智能体在这方面的处理能力比较差，接下来我们需要人工介入，详细告诉他什么原因，以及怎么修改，看他能不能完成修改

输入：

图片还是没有显示完整，你之前的修改思路不对，你应该看一下创建的 airui.img 控件的宽和高是多少，然后再对比看下实际图片的宽和高是多少；代码中，airui.image 的 w 和 h 分别是 100 和 60，实际上最大图片的尺寸的 w 和 h 分别为 268 和 138，每张图片的尺寸不完全一样；你要么把所有原始图片给我处理一下，尺寸变小；要么写一套算法，自动缩放这些图片来适配 airui.image 的尺寸

思考修复过程如下图（重点关注红框部分）：

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

图片终于可以正常显示了！

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

6.4 修复问题：很多小图标显示不正常

问题如下图红框所示

6.4.1 第一轮修复

输入：

以下几类文字前面的小图标没有显示出来，不用显示这些图标了，把图标删除，删除后，适当调整对应的文字位置，让显示更美观： 1、当前选中前面的图标 2、每种商品价格前面的图标 3、扫码支付等按钮上面的图标 4、还有其他类似的这种小图标

思考修复过程如下图（重点关注红框部分，这一次思考处理的过程很长，有 10 几分钟之久，感觉 GLM-4.7 大模型变慢了，如果以后还是这么慢，可以考虑换 MiniMAX 模型试下）：

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

可以看到，大部分的小图标已经删除了，还有三处没有删除

6.4.2 第二轮修复

输入：

大部分的图标已经被删除了，还有以下三处没有删除： 1、选中商品后，在窗口右上角，显示商品名称和价格之间的图标 2、二维码支付窗口，价格左方的图标 3、二维码支付窗口，我已支付完成按钮上的图标

思考修复过程如下图（重点关注红框部分）：

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

小图标显示不正常的问题已经全部修复！

6.5 修复问题：删除主窗口最下方的一段提示文字

问题如下图红框所示

6.5.1 第一轮修复

因为在前面两轮会话过程中，使用的收费 GLM-4.7 模型，处理速度有点儿慢；

所以，在这里，我把模型切换为收费的 MiniMAX-M2.5，看看处理速度和效果如何，如下图所示

输入：

删除主窗口下方的 “点击商品-> 扫码支付…”这一行提示语

思考修复过程如下图（重点关注红框部分，让人惊喜的是，它还把之前漏掉的一处修复给解决了）：

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

最下方的提示语，已经被删除！

6.6 修复问题：扫码支付窗口布局调整

问题如下图红框所示（布局不好，竖直滚动条滑动才能看到完整的按钮）：

6.6.1 第一轮修复

输入：

扫码支付窗口，删除竖直滚动条，我已支付完成和取消两个按钮并排显示完整

思考修复过程如下图（重点关注红框部分）：

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

虽然整体窗口的整体竖直滚动条，已经去掉了，并且下面的两个按钮也并排正常显示了；

但是二维码区域却给加上了竖直滚动条，还要继续修改；

6.6.2 第二轮修复

输入：

二维码那个区域也不要竖直滚动条

思考修复过程如下图（重点关注红框部分）：

复制代码到模拟器目录之后，模拟器关闭之后再次运行，仍然没有解决；

6.6.3 第三轮修复

输入：

改了之后还是没有显示完整，还有竖直滚动条，你再好好计算一下，看看控件的宽和高，看看实际图片的宽和高

思考修复过程如下图（重点关注红框部分）：

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

已经解决问题！

6.7 修复问题：扫码支付窗口，点击我已支付按钮后异常死机

问题如下图所示

6.7.1 第一轮修复

输入：

点击扫码支付窗口的我已支付成功按钮后，出现异常日志： E/main /app_store/vending_machine/user/vending_machine_win.lua:138: attempt to call a nil value (method ‘set_alpha’)

思考修复过程如下图（重点关注红框部分）：

复制代码到模拟器目录之后，模拟器关闭之后再次运行，仍然没有解决，此时提示找不到 set_opacity 方法；

此时我们看一下 vending_machine_win.lua 的 138 行代码 card.container:set_opacity(255)，可以知道这个异常表示 airui 的容器组件找不到 set_opacity 函数，我们再去 airui 核心库看一下，确实不支持这个函数，应该是 ai 自己杜撰的一个函数；接下来我们不告诉智能体怎么修复，仅仅告诉它错误信息，看它能不能解决；

6.7.2 第二轮修复

输入：

点击扫码支付窗口的我已支付成功按钮后，出现异常日志： E/main /app_store/vending_machine/user/vending_machine_win.lua:138: attempt to call a nil value (method ‘set_opacity’)

思考修复过程如下图（重点关注红框部分）：

复制代码到模拟器目录之后，模拟器关闭之后再次运行；

运行正常！

6.8 增加功能：实现退出按钮的逻辑

目前主窗口的退出按钮还没有任何功能，所以我们需要添加退出业务逻辑；

6.8.1 第一轮交互

输入：

目前的退出按钮还没有实际功能，参考 app_store 下面的其他 app 的退出业务逻辑代码，实现退出业务逻辑

思考修复过程如下图（重点关注红框部分）：

复制代码到模拟器目录之后，模拟器关闭之后再次运行，退出功能正常，可以关闭当前 app，返回到主菜单；

6.9 总结

6.9.1 完整演示

截止到这里，基本的售货机 UI 和模拟业务逻辑已经调试完成，可以正常运行了，下面是完整的演示视频

6.9.2 后续功能迭代

还有其他一些小问题或者新的功能需求，大家如果自己想练手，可以借助 Trae 进一步解决实现，例如：

1. 商品和滚动条小范围重叠显示的问题
2. 各个控件的色彩和 html 文件不符
3. 二维码动态显示
4. 给代码添加详细注释
5. …

七、基本功能测试说明

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

八、UI分辨率自适应说明

1、“智能售货机”app的UI界面，目前基于竖屏480*800分辨率设计，我们称这个分辨率为“app基准分辨率”；

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

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

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

5、虽然引擎主机的出厂软件支持自适应分辨率功能，不需要app内部再设计自适应；但是也不禁止你在app内部设计自适应分辨率功能，如果你在app内部设计了自适应分辨率功能，在app内的meta.json文件中，将display_zoom字段填写为adaptive即可；

九、打包 app，在应用市场上架

在本地模拟器上开发调试完成会后，就可以打包提交到应用市场了，打包提交流程如下：

1、找到本地的 vending_machine 目录，在这个目录下，仅保留本文 5.1 章节所描述的文件，其余文件和文件夹全部删除，例如我们在 5.3.3 章节复制了 vending_machine.html，此时需要把这个文件从本目录移除；在我的电脑上完整路径为 G:\code\LuatOS-develop\module\Air8101\project\AirUIFrame\ui_play_board\app_store\vending_machine，最终这个目录内的内容如下图所示

2、返回到 vending_machine 目录所在的上一级目录 app_store，在这里找到 vending_machine 目录，在 vending_machine 目录点击鼠标右键，使用压缩工具选项，压缩为 vending_machine.zip；这里需要特别注意：压缩后的 zip 文件，第一级是 vending_machine 目录，完整的结构如下（不同压缩工具的压缩表现不一样，无论使用什么工具压缩，要确保压缩后的 zip 文件中的目录结构满足下面的要求）：

vending_machine.zip

|------vending_machine 目录

|------main.lua

|------meta.json

|------icon.png

|------user 目录

|------res 目录

|------libs 目录

3、在电脑上访问：https://iot.luatos.com/，登录之后，打开 Turnkey方案->我的应用管理 菜单，点击 应用上传 按钮，在弹出的 上传应用 小窗口，上传 vending_machine.zip 文件即可，如下面几张图片所示

十、在模拟器上，通过应用市场，下载安装 app，运行验证 app

在本章节，我们通过模拟器的应用市场去下载、安装并且测试 vending_machine 这个 app，操作过程如下：

1、删除 LuatOS 模拟器所在目录下的 app_store 目录，如下图所示

2、模拟器上的 app_store 目录有什么作用？ - app_store 是模拟器内置文件系统根目录/下的一个子目录，所有的 app 都保存到了这个 app_store 目录下； - 在本篇文章的前文中，我们开发调试 vending_machine 这个 app 的代码时，为了开发调试方便，都是直接将代码放到模拟器同级的 app_store 目录下，模拟器可以直接识别并且运行； - 现在我们开发调试结束，将 app 上传到了应用市场，可以通过模拟器端的应用市场功能，将 app 下载安装到模拟器的内置文件系统/app_store/目录下；所以我们需要在下载安装 app 之前，将之前我们手动复制过来的 app_store 下面的 app 删除；方便在真实的使用环境中测试验证； 3、运行模拟器，进入主菜单，打开应用市场功能，找到智能售货机，安装成功后，返回，再打开主菜单，就能看到这个 app，运行测试即可，如下面几张图片所示

4、安装成功之后，我们再看模拟器所在的目录，自动创建了 app_store 目录，并且 vending_machine 子目录保存到了这个目录中，如下图所示

十一、在 合宙引擎主机8101上，通过应用市场，下载安装 app，运行验证 app

上一章节，如果在模拟器上已经测试通过；

在 合宙引擎主机8101测试，功能上不应该出问题，只有可能出现性能问题（例如打开 app 比较慢，运行 app 比较卡），如果出现性能问题，可以告诉 Trae，看看它是否可以优化，如果无法优化，发出来一起讨论，看看是否可以优化以及如何优化；

在 合宙引擎主机8101上，下载、安装并且测试 vending_machine 这个 app，操作过程如下：

1. 准备一块 合宙引擎主机8101和一根 type-c usb 数据线；
2. 使用 Luatools 同时烧录以下四部分内容：
3. Air8101 105 编号的最新版本内核固件（https://docs.openluat.com/air8101/luatos/firmware/），如果找不到 105 编号的固件，在合宙内部群沟通获取；
4. LuatOS 仓库的 develop 分支中 合宙引擎主机8101的默认出厂软件（factory）
5. LuatOS 仓库的 develop 分支中的扩展库（LuatOS/script/libs），一定不要勾选使用 Luatools 的默认 lib（默认发布的 lib 还没支持全部功能）
6. 文件系统中选择 hzfont 字库（参考烧录 hzfont 字库）
7. 烧录成功后，开机运行，之后的操作方式和模拟器上的操作方式完全一样；

十二、提交代码到 LuatOS 仓库的 develop 分支

自己开发的 app 验证通过之后，就可以提交代码到服务器了，使用 TortoiseGit 提交代码，简单的操作过程如下（更详细的流程，自行上网或者借助 AI 学习）：

1、在自己电脑上的代码仓库目录的空白区域，鼠标点击右键，先 pull 下来服务器最新代码，如下图所示

2、在自己电脑上的代码仓库目录的空白区域，鼠标点击右键，add 自己新增的文件，如下图所示

3、在自己电脑上的代码仓库目录的空白区域，鼠标点击右键，提交自己的修改，如下面两张图片所示