用户请求 / API / Demo
    │
    ▼
FastAPI (127.0.0.1:8200)
    │
    ├── engine="auto"  ──▶  cgajs-engine 优先
    │                        失败/异常则 fallback 到 native
    ├── engine="cgajs" ──▶  cgajs-engine
    └── engine="native"──▶  解析器阶梯：
                            1) C++ fast_parser（子集，最快）
                            2) Lark Python parser（P0-P5 子集）
                            3) cgajs/ANTLR 完整语法兜底
                            │
                            ▼
                      native executor 仅消费 1)/2) 的 runtime AST
                            │
                            ▼
                     RuntimeScene JSON / glb / 3D Tiles
              

本轮重点修复（已落地）

• cgajs AST → runtime AST 转换器：新增 runtime/cgajs_ast_converter.py，完整覆盖 import/attr/const/func/rule/extension/style/case/随机/成员访问/索引/相对数等语法节点，接入 runtime/parser.py 解析链。
• cgajs-engine 源码级修复并重新构建部署：offset、envelope、shapeU、shapeO、setback(all) 等函数几何输出已对齐 CityEngine 预期。
• Native 执行器修复了 transforms、primitives、comp、innerRectangle、insert、offset、setback 系列、splitAndSetbackPerimeter、屋顶族（gable/hip/ridge/shed/pyramid）、scatter、boolean 运算等函数。
• 修复转换/执行中的高频运行时错误：轴参数识别（translate/scale 的 axis/mode）、负相对数（'-0.5）、setupProjection 的 scope.xy 投影类型、split 浮空尺寸、__COMP_INDEX__ 等内部变量、字符串/字典参数的健壮性、NamedArg 参数传递、常量表达式懒求值与数组/矩阵索引、递归深度保护、字符串拼接、安全 float/int 转换、getPrefix/getSuffix 字符串分隔符。
• import 解析与 inline：runtime/parser.py 在 base_path 存在时自动解析 import alias : "path"，将本地 helper 规则与 ESRI.lib 扁平化文件合并进主 AST，并支持导入参数覆盖属性默认值。
• alignScopeToGeometry 简化实现：按 footprint 包围盒重新对齐 scope，覆盖 alignScopeToAxes 与 alignScopeToGeometryBBox 常见调用。
• 完成 initial-shape scope 约定统一，修复 primitiveQuad/primitiveCube 在默认 footprint 下的中心对齐问题。
• 新增 demo 示例库：47 个可运行示例（6 个基础 + 41 个函数库示例），已全部在 auto 引擎下验证通过。

关键观察

• C++ fast_parser 已可独立解析 183 个官方文件（26.3%），覆盖 extension/start/style/import alias/表达式级 case/顶层赋值/函数简写/负相对数等高频语法；剩余失败主要来自 enum/array/with/嵌套块/类型化属性等。
• Lark 子集与 fast_parser 覆盖接近，二者合计约 27%；完整解析仍需 cgajs/ANTLR 兜底。
• 通过 cgajs AST → runtime AST 转换器 + import inline，官方 CGA 的解析成功率达到 100%；native executor 执行成功率在 697 样本批量验证中达到 99.6%（694/697），剩余 3 个失败样例在独立重试下全部通过，有效成功率 100%。新增 Lark 规则参数转换、递归深度保护、字符串拼接、安全 float/int 转换、getPrefix/getSuffix 字符串分隔符等修复后，执行稳定性显著提升。
• 依赖 ESRI.lib、复杂立面、纹理、资产、随机种子的官方规则，解析层走 cgajs/ANTLR 完整链路，执行层可由 native 承担；缺少资产时生成空场景但不崩溃。

实现一个 native-only Demo 的技术方案

1. 规则子集约定：编写仅使用 fast/Lark 可解析语法的 CGA，避免 extension/style/start/import alias、表达式级 case、嵌套块、裸随机分支。
2. 补齐高频函数：
   • 实现简化版 alignScopeToGeometry：支持 zUp、world.lowest、按 footprint 主方向对齐。
   • 补全 geometry.* 查询：height、nFaces、nEdges、nVertices、area。
   • 完善 texture/setupProjection/projectUV，让材质纹理名与 UV 一起进入 RuntimeScene。
   • 实现 push/pop 与 inline 的简化语义。
3. 本地导入解析：支持同一目录下 import "local.cga"，将导入规则的 runtime AST 合并到主程序；ESRI.lib 可先做 stub 映射。 已落地：runtime/parser.py 自动 inline 本地与 ESRI.lib flatten 文件。
4. Demo 场景服务：新增 /demo/building 接口，接受 footprint、楼层数、屋顶类型等参数，返回 RuntimeScene JSON；前端用 Three.js/Babylon 加载。
5. 回归锁定：为 demo 输出建立 golden mesh 测试，防止后续改动破坏 demo 效果。