乐聚 Aelos 工程构建器

为乐聚（Leju）Aelos 系列教育机器人生成能在 Aelos Edu 软件里直接打开并运行的积木工程，同时提供工程格式、积木体系与代码生成规则的权威参考。

本技能的所有结论均来自对 Aelos Edu v2.2.3（aelos_blockly_edu，Electron + 定制 Blockly）安装包的 app.asar 逆向解析、官方工程实例比对，以及软件内置积木定义文件 action_blocks_aelos_smart.js 的逐条核对，非推测。

何时使用本技能

满足以下任一情形即加载：

• 用户要为乐聚 Aelos 机器人新建 / 生成 / 克隆一个积木工程
• 用户手里有 .abe 或 test.xml 文件，需要读懂、修改或重新生成
• 用户询问积木类型、参数取值、动作积木对应中文名、遥控按键编码
• 用户询问 main.py / main.lua 由积木如何生成，或 Lua 与 Python 两条路线的差异
• 用户在做机器人编程课程设计、竞赛案例、试讲课件（如超声波避障、颜色识别、标签跟随）

核心概念

1. 工程文件构成

一个 Aelos 工程就是一个普通文件夹，文件名硬编码，不可随意改动：

.abe 只有四个字段：

{
  "path": "D:\\lejurobot\\工程输出\\我的工程",
  "author": "Leju Company",
  "robotType": "Aelos_smart",
  "version": "2.2.3"
}

robotType 决定加载哪套积木库，写错会导致积木显示为「未知积木」。取值：Aelos_smart / Aelos / Aelos_pro / Aelos_lite / Aelos_claw 等。

2. 三级目录模型（极易踩坑）

软件不使用安装目录里的积木文件，而是在 %APPDATA%\aelos_edu\ 维护一份工作副本：

安装目录\resources\app.asar\build\blockly\lejublocks\   ← 模板源（只读）
       ↓ 选机型 / 换语言 / 开工程时按需覆盖
%APPDATA%\aelos_edu\Blocks\                             ← 运行时工作区（真正生效）
       ↓
       用户工程目录\<工程名>\

因此：直接改安装目录里的积木文件不会生效；且 Aelos.config 里若不写 robotType，软件会退回默认机型（旧款 Aelos）。

3. 两条代码生成路线

只要工程里出现视觉积木（read_distance、read_label_id、color_discrimination、face_* 等），就必须走 Python 路线。

工作流

方式 A：用脚本生成（推荐，适合批量与精确控制）

1. 写出工程描述 JSON（不确定格式就先导出模板）：

bash python scripts/gen_aelos_project.py --dump-spec > my_project.json

2. 按需修改 body 里的积木序列，不确定积木名或参数就查：

bash python scripts/gen_aelos_project.py --blocks # 列出全部可用积木及槽位

3. 生成并自动校验：

bash python scripts/gen_aelos_project.py --spec my_project.json

脚本会校验 XML 合法性、main.py 语法，并在含视觉积木时提示必须用 Python 模式。

4. 可选：--check 只校验不写盘。

现成描述文件见 references/templates/。

方式 B：手写工程文件

1. 新建 <工程名>\ 文件夹，按上面的文件表落盘。
2. test.xml 必须是 <xml xmlns="http://www.w3.org/1999/xhtml"> 根节点，start 积木需 deletable="false"。
3. 多语句按 <next> 嵌套串联；分支/循环用 <statement name="do"> / <statement name="if_do"> 等，条件用 <value name="condition">。
4. 变量必须在根 <variables> 里声明，且在 variables_get / variables_set 的 <field name="VAR"> 上用相同 id 引用。

关键约束（务必遵守，否则工程打开后报错或逻辑反转）

1. 比较符编码与显示符号不一致（最容易出错）：

手写 XML 时写的是编码，不是显示的符号。

2. 动作积木必须使用官方积木类型名，不要臆造。main.py 里对应的是 base_action.action('<中文动作名>')，中文名见 references/action_names.json。

3. Smart 机型没有超声波积木。工具箱里的「读距离」是 ARTag 视觉标签测距（read_distance）。真正的超声波只能通过「控制器 → 传感器模块」（sensor 积木）读 GPIO，拿到 0–255 原始 ADC 值，厘米换算在机器人端 lib.lua 内完成。

4. 端口只有 1 和 2；摄像头只有 head（头部）与 chest（胸前）；颜色枚举为 red/black/white/green/yellow/blue/gray。

5. test.xml 的名字不可改，改了软件找不到积木程序。

6. 不要声称 import aelossdk 风格属于软件原生输出——软件原生是 from leju import * + base_action.action(...) + nodes.node_initial() 结构。

资源索引