# CGA.js 引擎函数库与 NL2CGA 生成能力提升方案

> 版本：v1.0  
> 日期：2026-06-11  
> 基于 CityEngine 2025.1 对比分析 + 当前代码库深度审查

---

## 目录

1. [引擎函数库完善方案](#一引擎函数库完善方案)
2. [NL2CGA 生成能力提升方案](#二nl2cga-生成能力提升方案)
3. [实施时间表](#三实施时间表)
4. [资源需求与风险评估](#四资源需求与风险评估)

---

## 一、引擎函数库完善方案

### 1.1 当前状态

| 指标 | 数值 |
|------|------|
| 内置函数 | **177+**（math 30 / string 21 / array 18 / color 15 / list 16 / file 13 / context 6 / edge 3 / asset 20 / prob 4 / convert 9 / geometry 22） |
| 几何操作 | **80+**（extrude、split、comp、roof 系列、s/t/r、color、texture、setback、boolean 等） |
| 测试覆盖 | **~28 个**（主要是 roof、primitive、split、comp、transform） |
| 无测试函数 | **~140+ 个**（math/string/array/color/list/file/context/asset/geometry query 全部无测试） |
| 与 CityEngine 覆盖率 | **~25%**（CityEngine 有 ~85 个 shape 操作 + ~80 个内置函数 + ~50 个属性） |

### 1.2 缺失函数优先级矩阵

#### 🔴 P0 — 必须实现（核心功能缺失，直接影响使用）

| # | 缺失项 | CityEngine 用途 | 当前状态 | 实现难度 | 预期收益 |
|---|--------|-----------------|----------|----------|----------|
| 1 | `inset` | 向内偏移多边形并保持孔洞拓扑，与 `offset`/`setback` 互补 | ❌ 完全缺失 | 高 | 高（建筑开窗、阳台切割） |
| 2 | `setPivotMatrix` | 通过矩阵直接设置 pivot（支持任意轴序和旋转） | ⚠️ `setPivot` 仅支持 cornerIndex，axisMap 被忽略 | 中 | 高（复杂建筑 pivot 控制） |
| 3 | `writeTextFile` / `writeFloatTable` / `writeStringTable` | 文件写出操作（与 read 对称） | ❌ 完全缺失 | 低 | 中（数据导出、调试） |
| 4 | `fileDate` / `fileSize` | 获取文件元数据 | ❌ 完全缺失 | 低 | 低（资产管理） |
| 5 | `strmatch` / `regexp` | 字符串正则匹配 | ⚠️ `$` 前缀正则内嵌在 `count`/`splitString` 中，无独立函数 | 低 | 中（字符串处理） |
| 6 | `geometry.angle` | 返回当前面的转角 | ⚠️ 硬编码返回 90 | 中 | 中（屋顶计算） |
| 7 | `geometry.du` / `dv` / `uMin` / `uMax` / `vMin` / `vMax` | UV 域查询 | ⚠️ 硬编码返回常量 | 低 | 中（UV 操作） |
| 8 | `geometry.groups` / `geometry.materials` | 返回组/材质数量 | ⚠️ 硬编码返回 1 | 低 | 低（几何查询） |

#### 🟠 P1 — 重要缺失（影响高级建模能力）

| # | 缺失项 | 说明 | 当前状态 | 实现难度 |
|---|--------|------|----------|----------|
| 1 | `trim` 操作 | 接入 trim plane 系统，与 `insert` 配合 | ⚠️ no-op | 中 |
| 2 | `convexify` | 从 2D XZ 升级到 3D convex hull（支持孔洞） | ⚠️ 2D only | 中 |
| 3 | `alignScopeToGeometry` / `alignScopeToGeometryBBox` | 分析实际 face normal 和 bounding box | ⚠️ 直接 rx=ry=rz=0 | 中 |
| 4 | `insert` / `i` | 集成 Three.js GLTF/OBJ loader，实现真实资产加载 | ⚠️ stub | 高 |
| 5 | `asset*Sort*` / `image*Sort*` | 实现真正的按尺寸/比例排序逻辑 | ⚠️ 直接返回第一个元素 | 低 |
| 6 | `convert` | 实现 scope/world/object 坐标系转换矩阵 | ⚠️ no-op | 中 |
| 7 | `setPivot` | 完整支持 axisMap（xyz/yzx/zxy 等轴序重排） | ⚠️ 仅支持 cornerIndex | 中 |
| 8 | `softenNormals` | 按 dihedral angle 判断而非直接调用 computeVertexNormals | ⚠️ 简化实现 | 低 |
| 9 | `rectify` | 按 angle 阈值 snap 到轴，而非仅四舍五入到整数坐标 | ⚠️ 简化实现 | 低 |
| 10 | `roofRound` / `roofGambrel` / `roofHalfHip` | 已有实现但**零测试覆盖** | ⚠️ 未验证 | 低 |

#### 🟡 P2 — 中期增强（提升完整性和兼容性）

| # | 缺失项 | 说明 | 当前状态 |
|---|--------|------|----------|
| 1 | `style` 运行时切换 | 在 EvalContext 中增加 `currentStyle` | ⚠️ 解析正确但无运行时逻辑 |
| 2 | `import` 实现 | 递归加载外部 `.cga` 文件，合并符号表 | ⚠️ 解析正确但未加载 |
| 3 | 注解系统 | 扩展 `@Hidden`, `@Range(min,max)`, `@Group` | ⚠️ 仅 `@StartRule` 被处理 |
| 4 | 字符串转义 | Lexer 增加 `\n`, `\t`, `\uXXXX` 支持 | ⚠️ 仅支持 `\"` 和 `\\` |
| 5 | `version` 兼容性检查 | 解析到 version 字符串但未做版本 gate | ⚠️ 未校验 |
| 6 | `extension` 规则扩展 | 回退为普通规则，未实现真正语义 | ⚠️ 回退处理 |

### 1.3 解析器改进方案

#### 1.3.1 AST → Evaluator 链路补齐

```
当前：StyleDecl → 回退为 RuleDef
目标：StyleDecl → EvalContext.currentStyle → 按 style 名过滤规则集

当前：ExtensionDef → 回退为 RuleDef
目标：ExtensionDef → 继承基础规则 + 扩展新规则

当前：ImportDecl → 仅解析，未加载
目标：ImportDecl → 递归加载 .cga → 合并符号表 → 处理命名冲突
```

#### 1.3.2 错误恢复机制

- 增加 `strictMode` 选项：对未注册操作抛出错误（而非静默返回 `[shape]`）
- 增加 `validateParam` 调用：在 `evalSimpleOperation` 前校验参数签名
- 修复 `ExprIndex` 多维索引：支持 ragged array 的递归索引（当前 `i*n+j` 对非矩形数组会出错）

#### 1.3.3 语法兼容性增强

- 支持 `
`, `	`, ` ` 等完整转义序列
- 支持 `1e3` 等科学计数法
- 更新保留字列表以匹配 CityEngine 2025.1

### 1.4 测试覆盖补强计划

**阶段一：基础函数单元测试（2周）**
- Math 30 个函数：纯函数测试，输入→输出断言
- String 21 个函数：边界测试（空串、特殊字符、Unicode）
- Array 18 个函数：多维、ragged、空数组测试
- Color 15 个函数：RGB/HSV/Hex 互转断言

**阶段二：几何查询测试（2周）**
- 创建 mock shape（带真实 BufferGeometry）
- 验证 geometry.area / volume / nFaces / nEdges / nVertices / nHoles
- 验证 geometry.isPlanar / isRectangular / isConcave / isClosedSurface

**阶段三：文件 I/O 测试（1周）**
- 利用 `virtual-files.ts` 测试 readTextFile / readFloatTable / readStringTable
- 测试 writeTextFile / writeFloatTable / writeStringTable（新增）

**阶段四：Context 测试（1周）**
- 创建多 shape scene，验证 inside / overlaps / touches 的 AABB 逻辑

**阶段五：Roof 家族补测（1周）**
- 补充 roofRound / roofGambrel / roofHalfHip 测试用例
- 从 `roofTestCases` 复制模板扩展

---

## 二、NL2CGA 生成能力提升方案

### 2.1 当前状态

| 指标 | 数值 |
|------|------|
| Tier 1 预建模板 | **11 个**（住宅、别墅、办公楼、公寓、商场、学校、工厂、教堂、摩天楼、城堡、日式塔） |
| Tier 2 参数化模板 | **9 个**（全部为中国古建：太和殿、天安门、六角亭、牌坊、城墙、台基、栏杆、台阶、铺地） |
| 知识库实体 | **8 个**（太和殿、保和殿、中和殿、角楼、千秋亭、城墙、宫殿城市布局、瓦片系统） |
| CGA 资产库 | **60+ 文件**，8 大分类，但平均仅 30 行/文件 |
| RAG 索引 | **333 个**社区 CGA 文件，基于关键词重叠评分 |
| Tier 1 成功率 | ~95%（硬编码，无编译风险） |
| Tier 2 成功率 | ~70-85%（依赖模板匹配精度） |
| Tier 3 首次编译成功率 | ~40-60%（LLM 语法错误率高） |
| Tier 3 修复后成功率 | ~60-75%（2 轮修复） |

### 2.2 核心问题诊断

```
用户输入 → 意图识别
    │
    ▼ 关键词匹配（无语义）
    │    "故宫大殿" ≠ "太和殿"（不匹配）
    │    "生成现代博物馆" → GENERIC（无模板）
    ▼
[Tier 1] 11个预建模板，无参数化 → 命中率低
    │
[Tier 2] 仅9个中国古建模板 → 无法覆盖现代/西方/伊斯兰/印度建筑
    │
[Tier 3] LLM生成 → 语法错误率高（括号、case分支、comp选择器）
    │    修复规则仅10条，无法处理语义错误
    │    知识库仅8个中国实体，无法支撑全球建筑
```

### 2.3 能力提升方案

#### 🔴 Phase 1 — 扩展参数化模板库（2周）

**目标**：将 Tier 2 模板从 9 个扩展到 **50+**，覆盖全球主要建筑风格。

| 类别 | 新增模板 | 示例 |
|------|----------|------|
| 中国古建 | +5 | 天坛祈年殿、颐和园长廊、苏州园林、悬空寺、布达拉宫 |
| 伊斯兰建筑 | +5 | 清真寺（圆顶+宣礼塔）、阿拉伯庭院、波斯花园、摩洛哥riad、奥斯曼建筑 |
| 哥特式建筑 | +5 | 巴黎圣母院式、英国垂直式、德国砖哥特、飞扶壁结构、玫瑰窗 |
| 巴洛克/洛可可 | +3 | 凡尔赛宫、圣彼得广场、洛可可别墅 |
| 现代主义 | +8 | 包豪斯、粗野主义、高技派、解构主义、极简主义、参数化表皮、摩天楼、空中大堂 |
| 装饰艺术 | +3 | Art Deco 塔楼、几何装饰立面、纽约风格 |
| 日式传统 | +4 | 神社、鸟居、枯山水、町屋 |
| 印度/东南亚 | +4 | 印度教寺庙、吴哥窟、婆罗浮屠、泰式寺庙 |
| 非洲/大洋洲 | +3 | 泥砖建筑、圆形聚落、毛利会堂 |
| 基础设施 | +5 | 桥梁（悬索/拱/梁）、机场航站楼、高铁站房、水坝、通信塔 |
| 景观园林 | +5 | 假山、曲桥、花窗、月洞门、喷泉广场 |

**每个模板包含**：
- `@StartRule` 主规则
- `@Range` 参数化属性（lot_width, floor_count, roof_angle 等）
- `@Group` 参数分组（地块/屋顶/柱网/颜色）
- 编译验证通过的完整 CGA 代码
- LOD 分级（L0/L1/L2）

#### 🟠 Phase 2 — 增强预建模板 Tier 1（1周）

**目标**：为 11 个预建模板添加基础参数支持。

```cga
@StartRule
attr lot_width = 20
attr lot_depth = 20
attr floor_count = 3
attr color_scheme = "modern"

Lot -->
    extrude(floor_count * 3)
    comp(f) { front : FrontFacade | side : SideFacade | top : Roof }
```

**新增 P0 类型预建模板**：
- 清真寺、哥特式教堂、现代主义文化馆

#### 🟡 Phase 3 — 构建全球建筑知识库（2周）

**目标**：将 `building-entities.json` 从 8 个扩展到 **50+**。

| 文明 | 实体数量 | 代表性建筑 |
|------|----------|-----------|
| 中国 | 15 | 太和殿、祈年殿、悬空寺、布达拉宫、苏州园林、福建土楼、四合院 |
| 伊斯兰 | 8 | 蓝色清真寺、泰姬陵、阿尔罕布拉宫、伊斯法罕广场 |
| 欧洲 | 12 | 巴黎圣母院、圣彼得大教堂、凡尔赛宫、科隆大教堂、圣家堂 |
| 印度/东南亚 | 6 | 吴哥窟、婆罗浮屠、泰姬陵、泰国大皇宫 |
| 现代地标 | 10 | 埃菲尔铁塔、帝国大厦、悉尼歌剧院、哈利法塔、鸟巢 |

**每个实体包含**：
- 名称、风格、朝代/年代
- 屋顶类型、柱网尺寸、最小地块
- 关键 CGA 函数映射
- 推荐参数范围
- 语义关键词（支持反向检索）

#### 🟢 Phase 4 — 升级意图识别（2周）

**当前**：纯关键词包含匹配，无语义理解。
**目标**：引入轻量级 Embedding 语义匹配。

```
用户输入 → text-embedding-3-small / BGE → 向量
    │
    ▼ 与知识库实体向量比对（余弦相似度）
    │
    → 相似度 > 0.8：直接命中 ENTITY
    → 相似度 0.6~0.8：候选列表供 LLM 参考
    → 相似度 < 0.6：走 GENERIC
```

**Embedding 模型选择**：
- 在线：`text-embedding-3-small`（OpenAI，1536维，便宜）
- 本地：`BAAI/bge-small-zh-v1.5`（384维，可本地部署）

#### 🔵 Phase 5 — 完善编译验证与修复（2周）

**当前**：10 条修复规则，覆盖基础语法错误。
**目标**：扩展到 **30+ 条规则**，覆盖语义错误。

| 新增规则 | 错误模式 | 修复动作 |
|----------|----------|----------|
| RULE-011 | `roofHip` 参数数量错误 | 补全缺失参数为默认值 |
| RULE-012 | `comp` 选择器非法组合 | 替换为合法选择器 |
| RULE-013 | `case` 分支穷尽性错误 | 补充 `else: NIL` |
| RULE-014 | `split` 尺寸总和超出 scope | 按比例缩放或截断 |
| RULE-015 | `extrude` 参数类型错误 | 强制转换为 float |
| RULE-016 | 未定义的 attr 引用 | 添加 attr 定义并设默认值 |
| RULE-017 | `color` 参数越界（>1 或 <0） | clamp 到 [0,1] |
| RULE-018 | `texture` URL 404 | 替换为可用材质库 URL |
| RULE-019 | 递归深度超限 | 插入 `@Enum` 限制或提前终止 |
| RULE-020 | `import` 文件不存在 | 内联可用代码或删除 import |

**自动规则挖掘**：
- 从 `learning_log.json` + `CgaFailureCase` 数据挖掘高频错误模式
- 自动生成修复规则（基于模式匹配 + 替换模板）

#### 🟣 Phase 6 — AST 直接生成（长期，4周）

**目标**：绕过文本生成 → parse 阶段，直接组装 AST → evaluate。

```
当前：用户输入 → LLM → CGA 文本 → ANTLR4 parse → AST → evaluate
    │                                          ↑
    └────────── 语法错误常发于此 ──────────────┘

目标：用户输入 → 意图识别 → 模板选择 → AST 直接组装 → evaluate
    │
    └────────── 零语法错误 ───────────────────┘
```

**技术路径**：
1. 建立 `ast_builder.py` 生产级实现（当前为概念验证）
2. 每个模板对应一个 ASTBuilder 子类
3. 参数填充 → AST 节点组装 → 序列化为可 evaluate 的结构
4. 完全跳过文本 parse 阶段，消除 100% 语法错误

### 2.4 CGA 资产库深化

**当前问题**：60+ 文件平均仅 30 行，LOD 分级未充分利用。

**改进方案**：

1. **base/ 层补全**：
   - `roof.cga`：完整实现 Hip/Gable/Flat/Pyramid/Mansard 5 种屋顶 + LOD L2（雕花、瓦片细部）
   - `facade.cga`：窗框、门廊、装饰线脚分级
   - `material.cga`：PBR 材质映射表

2. **分类 Demo 场景**：
   - 每个分类至少 1 个可编译运行的完整 Demo
   - 包含 `import` 链、LOD 切换、材质贴图

3. **LOD 分级统一**：
   ```cga
   @Enum("Lod0","Lod1","Lod2","Lod3") attr lodstep = "Lod2"

   Building -->
      case lodstep == "Lod0" : Box
      case lodstep == "Lod1" : SimpleFacade
      case lodstep == "Lod2" : DetailedFacade
      else : UltraDetailedFacade
   ```

---

## 三、实施时间表

### Phase 1：引擎基础补强（2026 Q3，7~9月）

| 周 | 引擎任务 | NL2CGA 任务 |
|----|----------|-------------|
| W1 | P0 函数：writeTextFile/writeFloatTable/writeStringTable、fileDate/fileSize、strmatch | Phase 1：扩展参数化模板至 20 个（中国+伊斯兰+哥特） |
| W2 | P0 函数：geometry.angle/du/dv/uMin/uMax/vMin/vMax/groups/materials（修复硬编码） | Phase 1：继续扩展至 35 个（+现代主义+巴洛克+日式） |
| W3 | P0 函数：inset（polygon inset with hole support） | Phase 1：完成 50 个模板（+装饰艺术+印度+基础设施+景观） |
| W4 | P1 函数：trim、convexify 3D、alignScopeToGeometry、setPivot 完整 axisMap | Phase 2：增强 Tier 1 预建模板（+参数化+清真寺/教堂/文化馆） |
| W5 | 解析器：StyleDecl 运行时切换、ExtensionDef 真正语义 | Phase 3：构建全球建筑知识库（50+ 实体） |
| W6 | 解析器：import 递归加载、version 版本 gate | Phase 4：升级意图识别（Embedding 语义匹配） |
| W7 | 测试：Math/String/Array/Color 单元测试全覆盖 | Phase 5：扩展修复规则至 30 条 |
| W8 | 测试：Geometry Query + File I/O + Context 测试 | Phase 5：自动规则挖掘（从失败日志） |
| W9 | 测试：Roof 家族补测 + 整体回归测试 | Phase 6：AST 直接生成概念验证 |

### Phase 2：引擎高级功能（2026 Q4，10~12月）

| 周 | 引擎任务 | NL2CGA 任务 |
|----|----------|-------------|
| W1-W2 | P1 函数：insert/i（Three.js GLTF/OBJ loader）、asset*Sort* 真正排序 | AST 直接生成生产级实现 |
| W3-W4 | P1 函数：convert 坐标系转换、softenNormals dihedral angle、rectify angle snap | 模板引擎性能优化（跳过文本 parse） |
| W5-W6 | P2：注解系统（@Hidden/@Range/@Group）、字符串转义完整支持 | RAG 向量检索升级（语义搜索替代关键词） |
| W7-W8 | 性能优化：Boolean CSG 替换（three-bvh-csg）、Instance 实现 | 生成质量 A/B 测试与监控仪表盘 |

### Phase 3：生态系统（2027 Q1，1~3月）

- 引擎：AST 直接组装全面替代文本生成路径
- NL2CGA：多模态输入支持（草图→风格识别→CGA 生成）
- 两者：GIS 属性批量导入（buildingType/buildingStyle/floorCount 自动映射）

---

## 四、资源需求与风险评估

### 4.1 资源需求

| 资源 | 需求 | 说明 |
|------|------|------|
| 开发人力 | 1 名全职前端/引擎工程师 + 1 名后端/AI 工程师 | 或 1 名全栈 + AI 辅助 |
| 服务器 | 当前配置即可 | 开发阶段不需要额外资源 |
| Embedding 模型 | 可选（本地 BGE 免费 / OpenAI 付费） | 本地部署无额外费用 |
| 测试数据 | 需要更多 CGA 样例代码 | 可从 marketplace 社区文件提取 |

### 4.2 风险评估

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| `inset` 实现复杂度高 | 中 | 高 | 使用 `polygon-clipping` 库替代自研 |
| `insert/i` GLTF/OBJ 加载复杂 | 中 | 中 | 先用 Three.js 内置 loader，简化版实现 |
| AST 直接生成工作量超预期 | 中 | 高 | 分阶段实现，先覆盖高频模板 |
| 模板扩展数量大，维护成本高 | 低 | 中 | 建立模板测试自动化，每次提交前编译验证 |
| Embedding 模型部署资源 | 低 | 低 | BGE-small 仅需 512MB 内存，可轻松部署 |

### 4.3 关键成功指标（KPI）

| 指标 | 当前 | Phase 1 目标 | Phase 2 目标 |
|------|------|-------------|-------------|
| 引擎内置函数覆盖率 | ~70% | ~80% | ~90% |
| 引擎测试覆盖率 | ~15%（28/177） | ~60% | ~85% |
| NL2CGA Tier 2 模板数 | 9 | 50+ | 100+ |
| NL2CGA 知识库实体数 | 8 | 50+ | 100+ |
| NL2CGA Tier 3 首次编译成功率 | 40-60% | 55-70% | 70-85% |
| NL2CGA Tier 3 修复后成功率 | 60-75% | 75-85% | 85-95% |
| 引擎与 CityEngine 兼容度 | ~25% | ~40% | ~55% |

---

## 附录：关键文件清单

| 文件 | 作用 |
|------|------|
| `/www/wwwroot/cgajs-engine/src/builtins/` | 内置函数插件目录 |
| `/www/wwwroot/cgajs-engine/src/runtime/evaluator.ts` | 求值器核心 |
| `/www/wwwroot/cgajs-engine/src/parser/ast/types.ts` | AST 节点类型 |
| `/www/wwwroot/cgajs-engine/grammar/CGAGrammar.g4` | ANTLR4 语法文件 |
| `/www/wwwroot/cgajs-api/nl2cga/template_engine/` | 参数化模板引擎 |
| `/www/wwwroot/cgajs-api/nl2cga_service.py` | NL2CGA 三层生成管道 |
| `/www/wwwroot/cgajs-api/nl2cga/intent_router.py` | 意图识别器 |
| `/www/wwwroot/nl2cga-service/building-entities.json` | 建筑实体知识库 |
| `/www/wwwroot/nl2cga-service/library/` | CGA 资产库（60+ 文件） |
| `/www/wwwroot/cgajs-api/rag_index.json` | RAG 社区索引（333 文件） |