CityEngine CGA 学习总结与技术方案

执行摘要

本报告基于 CityEngine 2025 官方发布的 ESRI.lib、CityEngine2025Tutorial、CityEngine2025Example 三套工程文件（合计约 4.7 GB 压缩包，解压后约 11 GB，含 780 个 .cga 规则文件），结合官方 CGA Reference 与 Python API 文档，对 CGA（Computer Generated Architecture）形状语法进行了系统性学习。

一、CityEngine 与 CGA 概览

1.1 什么是 CityEngine

ArcGIS CityEngine 是 Esri 推出的三维城市建模软件，核心能力是基于二维矢量数据（地块、道路、建筑 footprint）或三维初始形状，通过程序化规则批量生成大规模、参数化的三维城市场景。它被广泛用于城市规划、建筑设计、游戏、影视特效和数字孪生等领域。

CityEngine 的关键特性包括：

• 程序化建模（Procedural Modeling）：用规则描述建筑、道路、植被等，而非手动建模。
• GIS 集成：支持 Shapefile、FileGDB、OSM、KML 等 GIS 数据作为输入。
• Python API：支持 Jython 2.7 与 Python 3.x，可自动化场景操作、规则分配、模型导出。
• 多格式导出：OBJ、FBX、glTF/GLB、DAE、USD、IFC、SLPK 等。

1.2 什么是 CGA

CGA（Computer Generated Architecture）是 CityEngine 的领域特定语言（DSL），属于 Shape Grammar 的变体。CGA 程序由一组规则组成，每个规则定义如何将一个形状（Shape）替换为新的形状或几何操作。

@StartRule
Lot --> extrude(height) Mass

Mass --> comp(f) { front: Facade | side: Wall | top: Roof }

Facade --> split(y) { ~1: Floor }*

Floor --> split(x) { 1: Wall | ~2: Window | 1: Wall }*

Window --> color("#00BFFF") primitiveCube()

上述代码展示了典型的建筑生成流程：地块（Lot）拉伸为体块（Mass），体块按面拆分，正立面按楼层和窗户网格细分，最终生成带颜色的窗户立方体。

1.3 本次分析的数据来源

这些数据覆盖了建筑、道路、植物、城市家具、地形、材质、屋顶、立面等绝大多数城市场景，为设计通用解析器提供了充足的语法和结构样本。

二、CGA 语法深度解析

2.1 文件结构与组成

一个典型的 .cga 文件由以下部分组成：

2.2 Shape、Scope 与 Pivot

CGA 的执行基于一个核心数据模型：Shape = 几何（Geometry）+ 作用域（Scope）+ 枢轴（Pivot）+ 符号（Symbol）。

2.2.1 Shape（形状）

Shape 是 CGA 执行过程中的基本单元。每个 Shape 包含：

• Symbol：形状名称，用于匹配规则，如 Lot、Facade、Window。
• Geometry：实际网格（顶点、边、面）与材质。
• Scope：形状的局部坐标系和包围盒，决定位置、方向、尺寸。
• Pivot：局部坐标系原点，通常与 Scope 原点对齐。

2.2.2 Scope（作用域）

Scope 定义了形状的局部坐标系，所有变换操作（s()、t()、r()）都基于当前 Scope。常用属性：

2.2.3 Pivot（枢轴）

Pivot 是 Shape 的坐标参考点。setPivot()、center()、alignScopeToGeometry() 等操作会改变 Pivot，从而影响后续 split 和 extrude 的方向。

2.3 核心操作符

CGA 的操作符分为几何创建、几何切分、几何变换、材质纹理、流程控制等类别。

2.3.1 几何创建

2.3.2 几何切分

2.3.3 几何变换

2.3.4 split 尺寸前缀

split 是 CGA 中最强大的操作之一，其尺寸前缀决定分配逻辑：

2.3.5 comp 组件选择器

comp 按拓扑组件拆分形状。常见组件类型与选择器：

2.4 内置函数库

CGA 内置函数按功能分为十余类。下表列出与解析器实现最相关的类别与代表函数。

2.4.1 数学与概率函数

2.4.2 几何查询函数

2.4.3 资源与文件函数

2.4.4 上下文与遮挡函数

2.4.5 材质与颜色函数

材质属性可通过 set(material.name, ...) 设置，颜色可通过 color("#rrggbb") 设置。PBR 属性包括 material.roughness、material.metallic、material.opacity 等。

三、真实案例研究

本节从三套工程文件中选取具有代表性的 CGA 规则，分析其实际结构与设计思路。

3.1 建筑：Building.cga

文件：CityEngine2025Example/Example_Complete_Streets__2025_0/rules/Buildings_Standard/Building.cga（460 行）

该规则是一个典型的参数化建筑生成器，展示了如何用 @Group、@Order、@Enum 等注解组织大量属性。

@StartRule
Building -->
    alignScopeToAxes(y)
    s('1,0,'1)
    cleanupGeometry(edges, 0.1)
    report("Building_FID", buildingFID)
    report("Parcel_FID", parcelFID)
    BuildingReference.Usage_Typology.ReportUsages(Total_GFA, 1)
    FootprintModelDispatch

FootprintModelDispatch -->
    case modelFileExists: ModelLoader
    else: BuildingShell

BuildingShell -->
    extrude(totalHeight) Mass

关键设计：

• 通过 typology 枚举支持 17 种建筑类型（农业、教育、工业、办公、住宅、交通等）。
• 优先加载外部 geospecific 模型（modelFile），否则程序化生成 BuildingShell。
• 使用 report() 输出建筑 FID、地块 FID、GFA 等指标，用于 Dashboard。
• 纹理通过 fileRandom 和 Three_Part_Texturing 库动态选择。

3.2 街道：Standard_Street.cga

文件：CityEngine2025Example/Example_Planning_04_Landscape_Design__2025_0/rules/Streets_Standard/Standard_Street.cga

街道规则是 CityEngine 中复杂度最高的规则类型之一，涉及车道、人行道、绿化带、路灯、交通标志等多元素协同。

Street -->
    split(z) { ~1: Sidewalk
             | streetWidth: Roadway
             | ~1: Sidewalk }

Roadway -->
    comp(f) { top: RoadSurface
            | side: Curb }

Sidewalk -->
    split(x) { ~1: Pavement
             | furnitureWidth: FurnitureStrip
             | ~1: Pavement }

FurnitureStrip -->
    split(x) { ~2: NIL
             | lampWidth: Lamp
             | ~2: NIL }*

关键设计：

• 街道沿 Z 轴切分为人行道、车行道、人行道三段。
• 车行道按 comp(f) 提取顶面和侧面，分别生成路面和路缘。
• 人行道家具带通过重复 split 规则放置路灯、长椅、垃圾桶等城市家具。
• 大量参数（车道宽度、人行道宽度、树种、路灯间距）通过 attr 暴露给用户。

3.3 植物：Trees.cga / Plant_Mixer

文件：CityEngine2025Tutorial/Tutorial_15_Publish_WebScenes__2025_0/rules/Trees.cga（41 行）

该规则展示了 CityEngine 中植物生成的典型模式：通过 import 调用 ESRI.lib 的通用 Plant_Loader.cga，实现植物模型的统一加载。

import Plant_Loader:"/ESRI.lib/rules/Plants/Plant_Loader.cga" 
    (Name=Plant_Name, Height=HEIGHT, Representation=Representation)

@Group("Plant Model", 0)

@Order(1)
attr Plant_Name =
    case GENUS == "Eucalyptus": "Blue Gum Eucalyptus"
    case GENUS == "Ulmus":      "Field Elm"
    case GENUS == "Washingtonia": "California Palm"
    case GENUS == "Acer":       "Sugar Maple"
    case GENUS == "Quercus":    "White Oak"
    case GENUS == "Juglans":    "California Walnut"
    else:                       NAME

@Order(2) @Enum("Realistic", "Schematic", "Fan")
attr Representation = "Fan"

Tree --> Plant_Loader.Generate

关键设计：

• 通过 GENUS 属名映射到具体植物模型名称（如 Acer → Sugar Maple）。
• 支持三种表达方式：Realistic（真实模型）、Schematic（示意）、Fan（扇形简化）。
• Plant_Loader 封装了模型查找、缩放、LOD 切换等复杂逻辑，上层规则只需传入参数。
• 这种“参数 + 通用加载器”模式非常适合向植物、城市家具、交通车辆等领域扩展。

3.4 城市家具：Bench.cga

文件：CityEngine2025Example/Example_Planning_04_Landscape_Design__2025_0/rules/Landscape_Design_Hardscape/Bench.cga（37 行）

这是一个极简的城市家具规则，展示了如何用少量 CGA 操作表达一个可参数化的长椅。

@Order(1) @Distance
attr Thickness = 0.06

@Order(2) @Color
attr Bench_Color = "#999999"

@StartRule
Bench -->
    color(Bench_Color)
    innerRectangle(scope) { shape: BenchFootprint }

BenchFootprint -->
    extrude(0.3)
    split(y) { ~1: BenchLegs | Thickness: X. }

BenchLegs -->
    split(x) { Thickness: X.
             | ~1: NIL
             | Thickness: X. }

关键设计：

• 通过 innerRectangle(scope) 获取放置长椅的内部矩形。
• 用 split(y) 分离椅面与椅腿区域。
• 用 split(x) 在两端生成椅腿，中间留空。
• 仅暴露 Thickness 和 Bench_Color 两个属性，简洁易用。

四、自研 CGA 解析器技术方案

4.1 总体目标

为 peyep 项目设计并实现一个纯自研的 CGA 解析器体系，具备以下能力：

• 自然语言转 CGA：用户用中文/英文描述建筑或城市元素，系统自动生成合法、可执行的 CGA 规则。
• CGA 解析生成几何体：不依赖 CityEngine 桌面软件，自主解析 CGA 并输出三维几何（mesh）。
• 通用性与可扩展性：以建筑为起点，逐步支持植物、城市家具、交通运输、道路网络等任意三维模型。
• Web 化与服务化：通过 FastAPI 提供 REST/ WebSocket 接口，支持在线编辑、实时预览与版本管理。

4.2 四层架构

直接让 LLM 输出 CGA 代码的成功率很低（CGA 是低资源 DSL）。因此采用分层架构，每层各司其职：

4.3 自然语言理解层

NL 理解层负责把用户的自然语言描述转换为结构化的 Semantic IR。需要处理的典型输入：

"建一个 5 层高的现代办公楼，底层是商业，入口朝南，屋顶是平的，立面有大面积玻璃窗。"

输出示例：

{
  "category": "building",
  "type": "office",
  "style": "modern",
  "floors": 5,
  "floor_height": 3.5,
  "ground_floor": { "usage": "retail", "height": 4.5 },
  "entrance": { "direction": "south" },
  "roof": { "type": "flat" },
  "facade": { "window_ratio": 0.7, "pattern": "grid" }
}

核心模块：

• 意图分类器：判断是建筑、植物、道路、家具还是城市场景。
• 实体抽取：抽取楼层数、高度、风格、材质、朝向、位置等。
• 单位归一化：将“5 层”、“20 米”、“约占 1/3”统一为数值。
• 缺失参数补全：用户提供不完整时，用默认值或反问确认。
• 风格本体库：将“现代”、“欧式”、“Art Deco”映射为规则模板与参数范围。

4.4 语义 / 规则中间表示

Semantic IR 是领域无关的，Rule IR 是领域相关的。中间表示的设计直接影响系统的可扩展性。

4.4.1 Semantic IR 示例

entity:
  id: building_01
  category: building
  type: office
  location: { x: 0, y: 0, z: 0 }
  footprint: [[0,0], [20,0], [20,15], [0,15]]
  parameters:
    floors: 5
    floor_height: 3.5
    ground_floor_height: 4.5
    roof_type: flat
    facade_window_ratio: 0.7
  style: modern
  context:
    entrance_direction: south
    adjacent_to: [road_01]

4.4.2 Rule IR 示例

{
  "rule": "Building",
  "operations": [
    { "op": "alignScopeToAxes", "axis": "y" },
    { "op": "extrude", "height": "totalHeight" },
    { "op": "comp", "selector": "f", "branches": [
      { "case": "front", "rule": "Facade" },
      { "case": "top", "rule": "Roof" }
    ]},
    { "op": "split", "axis": "y", "repeat": true, "parts": [
      { "size": "ground_floor_height", "rule": "GroundFloor" },
      { "size": "floor_height", "rule": "UpperFloor" }
    ]}
  ]
}

4.4.3 约束求解

几何约束需要在 Rule IR 层求解，例如：

• 楼层高度总和 ≤ 总高度
• 窗户不超出立面范围
• 入口朝南时，立面需对应 front 面
• 退界距离、容积率等城市设计规范

可选用 OR-Tools、Z3 或自定义约束求解器处理硬约束。

4.5 CGA 代码生成层

CGA 代码层将 Rule IR 编译为合法 CGA。采用模板引擎（如 Jinja2）+ 语法校验的组合。

4.5.1 模板策略

先不追求 LLM 直接写完整 CGA，而是为每个领域预置模板：

• BuildingTemplate：住宅 / 办公 / 商业 / 混合
• StreetTemplate：标准街道 / 林荫道 / 商业步行街
• PlantTemplate：乔木 / 灌木 / 地被
• FurnitureTemplate：长椅 / 路灯 / 垃圾桶 / 公交站台

4.5.2 CGA 子集

为降低实现难度，先支持 CGA 核心子集：

4.5.3 语法校验

生成 CGA 后立即进行静态检查：

• 语法树是否完整
• 规则是否存在循环依赖
• 引用的规则是否已定义
• split 尺寸是否合理（总尺寸不超过 scope）
• shape 名称是否唯一

4.6 CGA 解析与几何执行层

这是自研解析器的核心，需要独立完成 CityEngine 的解释器功能。

4.6.1 核心数据结构

class Shape:
    symbol: str
    geometry: Mesh
    scope: Scope  # 局部坐标系 + 尺寸
    pivot: Transform
    material: Material
    attributes: dict

class Scope:
    origin: Vector3
    axes: Matrix3  # X/Y/Z 局部轴
    size: Vector3

class Operation:
    name: str
    params: list
    branches: list  # 用于 split / comp / case

4.6.2 解释器执行流程

1. 解析：用 ANTLR/TextX 生成 CGA AST。
2. 实例化初始 Shape：从 footprint 或基本体开始。
3. 规则匹配：根据 Symbol 查找规则。
4. 操作执行：对 Shape 应用操作，生成新 Shape 列表。
5. 递归展开：直到没有匹配规则或到达终端。
6. 几何合并：收集所有叶节点几何，合并为最终 Mesh。

4.6.3 关键算法

4.6.4 输出格式

• Web 预览：glTF/GLB 供 Three.js / Cesium 加载。
• 标准模型：OBJ、FBX、DAE。
• 城市数据：CityJSON（需额外转换）。

4.7 多领域扩展设计

CGA 本身以建筑为核心，但通过统一 Semantic IR + 多后端编译器，可扩展到其他领域。

4.7.1 领域编译器接口

class DomainCompiler(ABC):
    @abstractmethod
    def compile(self, semantic_ir: SemanticIR) -> RuleIR:
        pass

class BuildingCompiler(DomainCompiler): ...
class PlantCompiler(DomainCompiler): ...
class StreetCompiler(DomainCompiler): ...
class FurnitureCompiler(DomainCompiler): ...

4.7.2 场景级组合

最终城市场景生成借鉴 CityEngine / CityX 的多阶段流水线：

道路网络生成
  → 地块划分（parcelization）
  → 建筑生成（per-lot CGA）
  → 绿化/家具 scatter（基于道路与建筑上下文）
  → 交通/行人层（可选）
  → 地形/水系融合

4.8 实施路线图

Phase 1 详细任务

1. 完成 CGA 词法/语法解析器（ANTLR4 文法）。
2. 实现 Shape、Scope、Pivot 核心数据结构。
3. 实现 extrude、split、comp、s/t/r、color、texture 等核心操作。
4. 设计 Semantic IR 与 Rule IR Schema。
5. 基于 LLM 实现 NL → Semantic IR（Prompt + Few-shot）。
6. 为建筑领域预置 3–5 个模板（现代办公楼、住宅、商业综合体）。
7. FastAPI 后端：上传 footprint、生成 CGA、执行几何、返回 GLB。
8. 前端 Three.js 预览 + 参数面板。

五、系统架构与工程实施详案

本节把第四章的技术方案进一步落地，给出可直接指导开发的系统架构图、子系统职责、数据流、子域名规划、立即执行的任务清单以及里程碑排期。

5.1 总体架构图

flowchart TB
    subgraph User["用户层"]
        U1[Web 浏览器 / 移动设备]
        U2[第三方 API 调用方]
    end

    subgraph CDN["边缘层"]
        C1[Caddy 反向代理
80/443 + on-demand TLS]
    end

    subgraph App["应用层 (FastAPI + Web)"]
        A1[Web 前端
Three.js / React]
        A2[FastAPI 主服务
REST + WebSocket]
        A3[认证 / 租户 / 项目管理]
    end

    subgraph Core["核心引擎层"]
        N1[NL 理解模块
LLM + NER + 风格本体]
        S1[Semantic IR
领域无关语义描述]
        R1[Rule IR
结构化规则推导树]
        CGA1[CGA 生成器
模板引擎 + 语法校验]
        INT1[CGA 解释器
Shape / Scope / Operation]
        GEO1[几何引擎
Extrude / Split / Comp]
        OUT1[输出器
GLB / OBJ / CityJSON]
    end

    subgraph Domain["领域编译器"]
        D1[BuildingCompiler]
        D2[PlantCompiler]
        D3[StreetCompiler]
        D4[FurnitureCompiler]
        D5[TransportCompiler]
    end

    subgraph Asset["资产与数据层"]
        DB1[(PostgreSQL
项目 / 用户 / 版本)]
        DB2[(Redis
缓存 / 队列)]
        FS1[文件存储
CGA / GLB / Texture]
        LIB1[规则模板库]
        LIB2[模型资产库]
    end

    U1 --> C1
    U2 --> C1
    C1 --> A1
    C1 --> A2
    A1 --> A2
    A2 --> N1
    A2 --> S1
    A2 --> R1
    A2 --> CGA1
    A2 --> INT1
    A2 --> GEO1
    A2 --> OUT1
    A2 --> A3
    N1 --> S1
    S1 --> R1
    R1 --> CGA1
    CGA1 --> INT1
    INT1 --> GEO1
    GEO1 --> OUT1
    R1 --> D1
    R1 --> D2
    R1 --> D3
    R1 --> D4
    R1 --> D5
    D1 --> CGA1
    D2 --> CGA1
    D3 --> CGA1
    D4 --> CGA1
    D5 --> CGA1
    A2 --> DB1
    A2 --> DB2
    A2 --> FS1
    A2 --> LIB1
    A2 --> LIB2
            

5.2 子系统职责与数据流

标准请求数据流

1. 用户在前端输入自然语言描述并上传 footprint（可选）。
2. FastAPI 接收请求，调用 NL 理解模块生成 Semantic IR。
3. 根据 category 选择对应 DomainCompiler（如 BuildingCompiler）。
4. DomainCompiler 生成 Rule IR，并通过约束求解器校验尺寸、比例、退界。
5. CGA 生成器将 Rule IR 编译为 .cga 文件，同时进行语法校验。
6. CGA 解释器加载 CGA，从初始 Shape 开始递归执行规则。
7. 几何引擎执行每个操作，生成 Shape Tree 的叶节点几何。
8. 输出器合并几何并导出 GLB，返回前端渲染。

5.3 子域名规划与分配

Caddy 已配置 on-demand TLS，任意子域名首次访问都会自动申请 Let's Encrypt 证书。以下是推荐用途：

注意：目前所有子域名都通过同一套 Caddy 配置反向代理到 FastAPI。后续可按需在 Caddyfile 中拆分：例如 docs.peyep.com 指向静态文档目录，static.peyep.com 开启缓存。

5.4 马上可以开展的任务

以下任务无需等待额外资源，可立即启动：

5.5 工程实施里程碑

六、商业化产品架构与核心技术路线

本节从商业化生产角度出发，将平台拆分为 NL2CGA、cgajs、CGARuntime、viewer、全球数据底座 五大核心子产品，分别给出技术路线对比、持续进化策略以及与其他模块的接口契约。

6.1 产品定位与商业模式

peyep 的最终产品形态是 “AI 驱动的程序化三维城市建模平台”，面向城市规划、建筑设计、游戏地编、数字孪生、影视特效等行业。核心价值在于：用自然语言或简单参数快速生成可生产、可编辑、可导出的大规模三维模型。

6.2 NL2CGA：自然语言转 CGA

核心问题：CGA 是 Esri 专有 DSL，LLM 预训练语料极少；直接端到端生成失败率高，无法用于生产。

6.2.1 技术路线对比

6.2.2 推荐架构：分层混合式 NL2CGA

flowchart LR
    A[用户输入
文本/图片/草图/Footprint] --> B[多模态编码 + NLU]
    B --> C[Semantic IR
建筑程序图]
    C --> D[规划器 + RAG 检索]
    D --> E[约束化 CGA 生成器]
    E --> F[CGA 编译与执行]
    F --> G[Critic / 评估器]
    G -->|失败| E
    G --> H[输出 .cga / .rpk + 3D 模型 + 说明]
            

6.2.3 持续进化与数据飞轮

flowchart LR
    A[用户输入] --> B[生成 CGA]
    B --> C[编译/渲染]
    C --> D[用户验收/反馈]
    D --> E[Bad Case 回收]
    E --> F[微调/RLHF/SFT]
    F --> A
            

• 显式/隐式反馈：点赞、星级、重生成次数、参数调整轨迹、最终是否导出。
• 评估指标：Compile Pass Rate、Runtime Success Rate、Geometry Validity、语义约束满足率、用户满意度。
• Bad Case 回收：按失败类型分桶，人工审核高价值案例，修正后入库。
• 模型迭代：收集高质量 (NL, IR, CGA) 三元组做 SFT；用编译/渲染结果作为奖励做 RLHF/DPO。

6.2.4 是否需要更多 CGA 文件？

结论：需要大量、合法、结构化的 CGA 语料。

6.3 cgajs：CGA 解析器

核心目标：纯自研、不依赖 CityEngine 桌面软件，完整解析并执行 CGA 规则。

6.3.1 解析器架构

flowchart TB
    A[CGA Source .cga] --> B[Lexer]
    B --> C[Parser]
    C --> D[AST Builder + Semantic Analyzer]
    D --> E[IR / Bytecode Generator]
    E --> F[Executor / Interpreter]
    F --> G[Shape Tree / Mesh / GLB]
            

6.3.2 解析器工具对比

6.3.3 函数库分层覆盖策略

6.3.4 如何持续完成解析 CityEngine 所有函数

• 以 780 个官方 .cga 文件为“活规范”，建立解析回归测试。
• 每个函数实现为 OperationHandler，注册到 Executor。
• 建立函数覆盖矩阵，每实现一个函数就补充单元测试和 golden 测试。
• 对缺失函数实现“软失败”：打印警告、返回 NIL 或保持原 shape，保证解析器能跑通更多文件。
• 用 PyPRT 作为 golden 参考：对同一 CGA + 同一 footprint，对比顶点/面片/面积/体积/Hausdorff 距离。

6.4 CGARuntime：几何运行时

核心目标：将 CGA 规则执行结果转换为可渲染 Mesh，达到或接近 CityEngine 的生成效果。

6.4.1 几何内核路线对比

6.4.2 推荐方案：混合内核

flowchart TB
    A[CGARuntime Geometry Kernel] --> B[Shape Tree + Scope + Half-edge Mesh]
    B --> C[CGAL 2D Offset
Straight Skeleton
Arrangement]
    B --> D[Manifold Boolean
Watertight]
    B --> E[OpenCASCADE
BRep 高精度]
            

6.4.3 关键操作实现要点

• extrude：多边形面沿法向拉伸，生成侧面和顶底面，维护 hole 拓扑。
• split：处理绝对、相对（'）、浮动（~）、重复（*）四种尺寸，用平面裁剪几何。
• comp(f)：按面法线在 scope/对象/世界坐标系下的象限分组。
• offset / setback / innerRectangle：嫁接 CGAL 2D 偏移与直骨架算法。
• boolean：闭合流形体用 Manifold；高精度场景用 OpenCASCADE。

6.4.4 如何达到 CityEngine 效果

6.4.5 输出格式

• GLB/glTF 2.0：Web 预览首选，支持 PBR、Draco、实例化。
• OBJ：快速 DCC 互操作。
• FBX：导入 Maya/3ds Max/UE。
• CityJSON：与 GIS/CIM 平台对接。
• 3D Tiles：大场景 Web 发布（Cesium）。

6.5 viewer：三维渲染引擎

核心问题：自研渲染器还是使用当下通用引擎？

6.5.1 渲染引擎对比

6.5.2 推荐方案

flowchart TB
    A[viewer 分层架构] --> B[单体建筑预览
Three.js WebGPU + GLB PBR]
    A --> C[城市级 GIS 预览
CesiumJS + 3D Tiles]
    A --> D[移动端降级
PlayCanvas / Three.js WebGL]
    B --> E[统一交换格式：glTF 2.0 / GLB]
    C --> E
    D --> E
            

结论：不要自研通用底层渲染器。 peyep 的核心价值在 CGA 解析与生成，viewer 应基于成熟引擎做应用层（相机控制、LOD、材质映射、城市流送）。

6.6 全球数据底座集成

核心目标：将 CGA 生成的建筑/城市模型放入真实的全球地理环境中，支持遥感影像、DEM、全球矢量数据。

6.6.1 数据源对比

6.6.2 集成方案：分阶段混合架构

flowchart TB
    A[CGA 输出局部坐标] --> B[Footprint 中心 → WGS84]
    B --> C[ENU 原点]
    C --> D[建筑顶点 ENU → ECEF]
    D --> E[CesiumJS 渲染]
    F[遥感影像] --> E
    G[DEM 地形] --> E
    H[OSM 矢量] --> E
            

6.6.3 坐标系统处理

• WGS84（EPSG:4326）：数据存储与交换标准。
• Web Mercator（EPSG:3857）：Web 瓦片显示。
• ECEF（EPSG:4978）：CesiumJS 内部 3D 渲染坐标。
• ENU：以 footprint 中心为原点的局部工程坐标，适合 CGA 建模。

6.6.4 商业化成本与合规

• Cesium ion：Community 仅限非商业；商业产品需 Commercial/Enterprise。
• Mapbox v2+：闭源商业许可，商业部署需购买授权。
• Google 3D Tiles：按 root tile 计费，注意刷新页面会重复计费。
• OSM：ODbL 协议，可商用但需署名；作为 Produced Work 展示通常只需署名。

6.7 子域名与微服务规划

基于商业化拆分，建议子域名按子产品/环境分配：

6.8 近期可实施任务清单

以下任务可立即启动，不依赖外部资源：

6.9 完整开发路线图

七、Golden 测试、CGA 语料消耗与产品界面方案

在前两章确定商业化架构与技术路线后，本章给出三个关键落地问题的具体方案：① 如何用 Esri PyPRT 作为 cgajs 的 golden 参考进行几何对比；② 如何系统地消耗 CityEngine 官方 780 个 CGA 文件，并建立基于 LLM 的自我迭代学习系统；③ 为 10 个子域名产品细化菜单、功能模块与界面布局。

7.1 PyPRT 作为 cgajs Golden 参考

7.1.1 PyPRT 与 PRT 关系及授权

PyPRT 是 Esri CityEngine 底层 PRT（Procedural Runtime） 的 Python 绑定，它调用 CityEngine 真正的 CGA 执行引擎生成三维模型。关键点：

• PyPRT 只能消费 .rpk 规则包，不能直接读取原始 .cga 文本；.rpk 内部包含编译后的 .cgb、纹理与资产。
• CityEngine 版本必须与 PyPRT 版本匹配，否则会出现 CGAC version 不兼容警告。
• 授权：个人/教育/非商业免费；商业用途需要组织至少持有一份最新 CityEngine 商业许可。禁止将 PyPRT 再分发或以 Web 服务形式对外提供，除非获得 Esri 书面许可。

7.1.2 从 .cga 到 .rpk

使用 CityEngine Python API 将官方 .cga 打包为 .rpk：

from scripting import *

ce = CE()
settings = RPKExportSettings()
settings.setRuleFile("/my_project/rules/building.cga")
settings.setFile(ce.toFSPath("/my_project/output/building.rpk"))
settings.setAddFilesAutomatically(True)      # 自动收集引用资产
settings.setIncludeSourceFiles(True)         # 保留 .cga 源文件
settings.setCompatibility(RPKExportSettings.DEFAULT)
ce.exportRPK(settings)

打包后，将 .rpk 放入 tests/fixtures/rules/，作为 golden 对比的权威输入。

7.1.3 InitialShape 与 generate_model API

PyPRT 的核心调用链为：InitialShape → ModelGenerator → generate_model。

import pyprt, os

# 1. footprint：y-up，逆时针
footprint = [0,0,0, 10,0,0, 10,0,10, 0,0,10]
shape = pyprt.InitialShape(footprint)

# 2. 查询 RPK 暴露的属性
info = pyprt.get_rpk_attributes_info(os.path.abspath("building.rpk"))
print(info.keys())

# 3. 配置属性与起始规则
attrs = {
    "shapeName": "golden_building",
    "seed": 42,
    "buildingHeight": 15.0,
    "ruleFile": "bin/rule.cgb",
    "startRule": "Default$Init"
}

# 4. 生成模型
m = pyprt.ModelGenerator([shape])
models = m.generate_model(
    [attrs],
    os.path.abspath("building.rpk"),
    "com.esri.pyprt.PyEncoder",
    {"emitGeometry": True, "emitReport": False, "triangulate": True}
)
model = models[0]
print(len(model.get_vertices()), len(model.get_faces()))

7.1.4 导出 OBJ/GLB 参考模型

通过内置 OBJEncoder / GLTFEncoder 导出完整材质、UV、法线：

out_dir = os.path.abspath("output/golden")
os.makedirs(out_dir, exist_ok=True)

# OBJ
m.generate_model(
    [attrs], os.path.abspath("building.rpk"),
    "com.esri.prt.codecs.OBJEncoder",
    {"outputPath": out_dir, "baseName": "golden", "triangulateMeshes": True}
)

# GLB
m.generate_model(
    [attrs], os.path.abspath("building.rpk"),
    "com.esri.prt.codecs.GLTFEncoder",
    {
        "outputPath": out_dir, "baseName": "golden",
        "outputFormat": "GLTF_GLB_WITH_SINGLE_BUFFER",
        "includeMaterials": True
    }
)

7.1.5 几何对比指标与代码示例

对同一 footprint + 同一 CGA，同时用 cgajs 与 PyPRT 生成模型，计算以下指标：

import trimesh, numpy as np
from scipy.spatial import cKDTree
from scipy.spatial.distance import directed_hausdorff

def sample_surface(mesh, n=20000):
    return mesh.sample(n)

def hausdorff_distance(a, b, n=20000):
    pa, pb = sample_surface(a, n), sample_surface(b, n)
    return max(directed_hausdorff(pa, pb)[0], directed_hausdorff(pb, pa)[0])

def chamfer_distance(a, b, n=20000):
    pa, pb = sample_surface(a, n), sample_surface(b, n)
    return (cKDTree(pb).query(pa)[0].mean() + cKDTree(pa).query(pb)[0].mean()) / 2

golden = trimesh.load("golden_0.obj", force="mesh")
ours   = trimesh.load("cgajs_building.obj", force="mesh")
print("hausdorff:", hausdorff_distance(golden, ours))
print("chamfer:", chamfer_distance(golden, ours))
print("area ratio:", ours.area / golden.area)

阈值建议：Hausdorff < 0.05 m、面积误差 < 1%、顶点数偏差 < 5%（triangulate 策略差异可导致面数不同，需结合 Hausdorff 判断）。

7.1.6 CI 集成与授权隔离

推荐把 PyPRT golden 测试限定在 tests/golden/ 与 self-hosted CI runner：

• runner 必须持有 CityEngine 商业许可。
• RPK 与 golden OBJ 版本锁定，文件名带 PyPRT / CityEngine 版本号。
• 生产 Docker 镜像不安装 PyPRT，避免授权违规。
• 当版本不匹配时，用 CityEngine CLI 批量导出静态 OBJ 作为临时 golden。

7.2 官方 780 CGA 文件的全流程消耗

7.2.1 语料画像与分类

对 780 个官方 CGA 建立 Capability Profile：

{
  "file": "Building.cga",
  "domain": "Building",
  "version": "2017.1",
  "lines": 460,
  "rules": 35,
  "ops": {"extrude": 5, "split": 40, "comp": 12, "setupProjection": 80},
  "builtin_funcs": {"rand": 20, "floor": 5},
  "imports": ["Referenced/Three_Part_Texturing.cga"],
  "assets": ["*.jpg", "facades/..."]
}

分类维度包括：

• 领域：建筑 ~271、街道 ~75、植物 ~27、家具 ~5、其他 ~396。
• 复杂度：L1 入门（<100 行）、L2 标准（100–500 行）、L3 复杂（500–2000 行）、L4 专家（>2000 行）。
• 操作签名：高频操作为 setupProjection（10,563 次）、projectUV（10,558 次）、split（6,054 次）、comp（1,359 次）、extrude（902 次）。
• 版本：2010.3 ~ 2025.1，约 290 个文件未声明 version。

7.2.2 四级测试流水线

flowchart LR
    A[Raw CGA] --> B[L0 解析测试
生成 AST]
    B --> C[L1 语义测试
符号表完整]
    C --> D[L2 执行测试
生成几何]
    D --> E[L3 对比测试
与 PyPRT 对比]
            

7.2.3 AI 自我迭代闭环

flowchart TD
    A[扫描 780 CGA 生成画像] --> B[批量跑 L0/L1/L2/L3]
    B --> C[失败分类器]
    C --> D[LLM 根因分析]
    D --> E[LLM 生成修复]
    E --> F[应用 patch 到沙盒分支]
    F --> G[重跑四级测试]
    G -->|通过| H[A/B 对比与人工审核]
    G -->|失败| D
    H --> I[合并到主分支]
            

LLM 接收的上下文包括：失败文件路径、错误行、错误类别、相关代码片段、能力画像、类似成功案例、解析/执行日志。LLM 输出修复提案（JSON patch），由脚本自动 apply 并在临时 worktree 中验证。

7.2.4 失败分类与根因分析

7.2.5 A/B 回归保护

任何 AI 生成的修复必须通过 A/B 对比：

• 新通过文件数 > 0。
• 原通过文件无新增失败。
• 总体解析成功率不下降。
• grammar 核心改动必须人工 approve；新增 OperationHandler 抽样 review；测试用例/文档可自动合并。

python scripts/ab_compare.py \
  --baseline main \
  --candidate fix-branch \
  --report reports/ab_2026_06_19.json

7.2.6 CGA 知识图谱

从语料中提取三层知识库：

• 函数依赖图：操作 → 文件、规则 → 规则、import → 被引用规则。
• 模板模式库：Box-Extrude-Facade-Split、Massing-LU-Shape、Texture-Projection-Paint、Street-Lane-Marking、Plant-Loader。
• 错误模式库：正则 + 修复提示，用于快速分类失败。

7.2.7 商用可行性评估

仅依靠官方 780 个文件，能够做到：

• 语法覆盖：90%+ 核心语法，但边缘语法（@Handle、inline、extension）不足。
• 操作覆盖：78 个 CGA 操作中约 40 个有真实用例；未出现的操作需按文档补全。
• 函数覆盖：约 42 个 builtin 函数有真实用例；CGA 总 builtin 函数 100+，需文档驱动实现。
• 领域覆盖：建筑/街道较强，植物/家具/交通较弱。

结论：780 个官方文件是极佳种子语料，可支撑 L0 60–70% 文件通过、L2 30–40% 文件通过 的 MVP；要达到商业化可用，必须扩展至数千真实项目文件、补充官方文档作为 ground truth、引入用户反馈闭环。

7.3 子域名菜单与界面设计方案

为 10 个子域名产品统一设计深色科技风界面，主色 #0A84FF、背景 #0F1419、表面 #1A1F26，桌面端左侧 240px 侧边栏 + 右侧主内容，移动端折叠为抽屉或底部 Tab。

7.3.1 全局设计系统

通用快捷键：Ctrl+K 全局搜索、Ctrl+Enter 运行/生成/解析、Ctrl+S 保存。状态栏统一显示服务健康、版本、坐标、操作提示。

7.3.2 peyep.com / www.peyep.com

• 定位：品牌门户、产品总览、技术报告与博客入口。
• 顶部导航：产品 · 解决方案 · 文档 · 报告 · 定价 · 博客 · 关于我们 · 登录/试用。
• 首页模块：Hero 大标题、6 大产品矩阵卡片、能力展示三段式、最新报告入口、应用场景、页脚。
• 报告页：左侧目录树 + 右侧 Markdown 渲染 + 顶部工具栏（字体/主题/分享/打印）。

7.3.3 app.peyep.com

• 定位：统一工作台，管理项目、资产、任务与团队协作。
• 顶部导航：工作台 · 项目 · 资产 · 团队 · 应用市场 · 设置。
• 侧边栏：我的项目 / 最近打开 / 收藏 / 回收站；全部项目 / 与我共享 / 模板库；模型 / 材质 / CGA 规则 / 数据源。
• 工作台：快捷入口（新建项目 / 导入 CGA / NL2CGA / 打开 viewer）、最近项目卡片、数据看板、活动流、推荐模板。
• 项目详情页：左侧资源树、中部编辑器/预览标签页、右侧属性检查器 + 参数面板、底部状态栏。

7.3.4 api.peyep.com

• 定位：REST / WebSocket API 文档、SDK 下载、开发者控制台。
• 顶部导航：文档 · 参考 · 控制台 · SDK · 定价 · 状态。
• 侧边栏：快速开始（认证 / 基础 URL / 错误码）；API 参考（NL2CGA / CGA 解析 / 几何生成 / Viewer / 数据底座）；WebSocket；SDK（Python / JS / CLI）；控制台（应用 / Key / 用量 / 账单）。
• API 参考页：左侧端点目录、中部请求说明 + 参数表、右侧代码示例 + “在控制台测试”按钮。

7.3.5 nl2cga.peyep.com

• 定位：自然语言生成 CGA，降低程序化建模门槛。
• 顶部导航：生成器 · 我的规则 · 模板 · 语法检查 · 定价。
• 布局：左侧模板/历史侧边栏；中部大输入区 + 生成按钮 + CGA 输出区；右侧参数面板（模型、风格、复杂度、输出语言）。
• 交互：输入框支持 / 唤起模板；生成后可一键“运行到 Runtime”；语法错误红色下划线 + 修复建议。

7.3.6 cgajs.peyep.com

• 定位：在线 CGA 解析、调试、AST 可视化与规则游乐场。
• 顶部导航：游乐场 · 解析器 · AST · 函数库 · 测试套件 · 文档。
• 布局：左侧文件树；中部 Monaco/CodeMirror 编辑器 + 控制台；右侧解析结果面板（AST JSON / 语法错误 / 符号表 / 性能）。
• 交互：Ctrl+Enter 触发解析；错误行点击跳转；AST 节点悬停显示源码位置；一键导出 Lark/JSON。

7.3.7 runtime.peyep.com

• 定位：CGA 规则执行与几何生成服务，输出 GLB/OBJ/USD 等格式。
• 顶部导航：执行 · 流水线 · 模型库 · 性能 · 文档。
• 布局：左侧任务队列；中部输入区（CGA 代码 / Shapefile）+ 输出日志 + 模型预览；右侧参数面板（种子、LOD、格式、纹理开关）。
• 交互：运行中实时刷新日志；输出模型一键下载或发送到 viewer；失败任务显示错误堆栈。

7.3.8 viewer.peyep.com

• 定位：Web 端三维模型预览、场景搭建、渲染组件展示。
• 顶部导航：示例 · 组件 · 场景 · 文档 · 打开模型。
• 布局：左侧场景树；中部 WebGL/WebGPU 3D 画布；右侧属性面板 + 渲染设置。
• 交互：悬停显示属性、双击聚焦、右键菜单（隐藏/孤立/重置）、截图导出 PNG、嵌入代码生成。

7.3.9 data.peyep.com

• 定位：全球地形、影像、矢量、OSM 等开放数据聚合与瓦片服务。
• 顶部导航：数据目录 · 瓦片服务 · 数据集 · API · 控制台。
• 布局：左侧数据目录；中部 CesiumJS / MapLibre 全球地图 + 瓦片预览；右侧图层/属性面板。
• 交互：框选区域下载数据、复制瓦片 URL、将建筑数据一键发送到 runtime 生成模型。

7.3.10 docs.peyep.com

• 定位：peyep 全产品线开发文档、教程与 FAQ。
• 顶部导航：快速开始 · 教程 · API · 示例 · 更新日志 · 搜索。
• 布局：标准文档三栏（左侧目录树、中部 Markdown 正文、右侧当前页面大纲）。
• 内容：环境搭建、第一个 CGA、NL2CGA / cgajs / CGARuntime / viewer / 数据底座教程、API 参考、CGA 语法、函数库、错误码、FAQ。

7.3.11 test.peyep.com

• 定位：内部测试、功能演示、A/B 测试、客户沙盒。
• 顶部导航：演示 · 沙盒 · 测试集 · 报告 · 状态。
• 布局：环境状态看板、各子产品演示入口、沙盒列表、最近测试任务、快速操作（清空缓存 / 重置数据 / 生成报告）。
• 沙盒页：顶部环境信息 banner、左侧功能菜单、中部嵌入对应子产品简化版、右侧操作说明与参数。

八、最终整体方案与分阶段实施路线图

本章从整体网站结构、产品逻辑、运维部署三个维度进行诊断，给出最终整体架构，并细化每个阶段的具体任务、交付物与验收标准，供决策后按优先级实施。

8.1 当前架构问题诊断

8.1.1 网站与部署层

• 子域名无感知路由：Caddy 把所有子域名都反代到同一个 FastAPI 进程，但应用层未根据 Host 头区分产品，所有子域名显示同一首页。
• 首页与落地页缺失：web/index.html 只是占位标题；没有与报告第六章、第七章设计对应的子产品落地页。
• 开发模式不适合生产：scripts/start.sh 使用 --reload 单 worker；缺少生产启动脚本、systemd 服务文件、日志轮转与进程守护。
• 缺少统一配置管理：没有环境变量/配置模块来区分 development / staging / production。
• 安全与性能基线缺失：未配置安全响应头、CORS、请求限流、静态资源缓存策略。

8.1.2 产品功能层

• API 空白：当前只有 /health、/ask、/updata.html，没有面向 NL2CGA / cgajs / Runtime / Viewer / Data 的实际 API。
• 路由与服务目录空转：app/routers/、app/services/ 目录存在但为空，产品边界未在代码中落地。
• 缺少统一 API 前缀规范：各子产品接口若随意命名，后续拆分微服务时集成成本极高。
• 缺少子产品间调用链：NL2CGA → cgajs → Runtime → Viewer 的数据流尚未抽象为内部 API 调用。
• 缺少数据模型：没有用户、项目、资产、场景、模型版本等核心数据实体设计。

8.1.3 数据与运维层

• 持久化未设计：没有数据库、对象存储、缓存、消息队列的选型与接入。
• 可观测性不足：无结构化日志、指标监控、告警、分布式追踪。
• CI/CD 缺失：没有自动化测试、构建、部署流水线。
• 服务运行方式临时：FastAPI 当前跑在 tmux，未使用 systemd 等持久化机制。
• 备份与容灾：未定义数据备份、灾难恢复、回滚策略。

8.2 最终整体架构

8.2.1 分层架构

flowchart TB
    subgraph EDGE["边缘层"]
        C[Caddy
TLS / gzip / 限流 / 缓存]
    end
    subgraph GATE["网关层"]
        F[FastAPI Main
子域名识别 / Auth / 健康聚合]
    end
    subgraph PROD["产品层（模块化单体，可拆分）"]
        W[www]
        A[app]
        AP[api]
        N[nl2cga]
        CJ[cgajs]
        R[runtime]
        V[viewer]
        D[data]
        DO[docs]
        T[test]
    end
    subgraph SHARED["共享服务层"]
        AUTH[Auth / SSO]
        DB[(PostgreSQL)]
        OBJ[(S3 / MinIO)]
        CACHE[(Redis)]
        Q[[Celery / RQ]]
    end
    subgraph FE["前端层"]
        CSS[统一设计系统 CSS]
        LP[子域名落地页]
        SPA[产品 SPA]
    end
    C --> F
    F --> W & A & AP & N & CJ & R & V & D & DO & T
    W & A & AP & N & CJ & R & V & D & DO & T --> SHARED
    W & A & AP & N & CJ & R & V & D & DO & T --> FE
            

8.2.2 子域名路由策略

采用「Caddy 统一接入 + FastAPI 应用层识别 Host」的渐进式方案：

• Caddy 为 *.peyep.com 提供自动 HTTPS 并反代到 127.0.0.1:8000；peyep.com 裸域 301 永久重定向到 www.peyep.com。
• FastAPI 中间件读取 Host 头，解析当前子域名并写入 request.state.subdomain。
• / 根据子域名返回对应落地页（web/{subdomain}/index.html，www 与根域共用 web/index.html）。
• 所有子产品 API 统一前缀 /api/v1/{product}/...，未来拆分微服务时只需把前缀代理到新后端。
• /api/v1/status 聚合所有子产品健康状态，供 test.peyep.com 与监控使用。

8.2.3 核心数据流

sequenceDiagram
    participant U as 用户
    participant A as app.peyep.com
    participant N as nl2cga
    participant C as cgajs
    participant R as runtime
    participant V as viewer
    participant D as data
    U->>A: 创建项目 / 选择地块
    A->>D: 获取 OSM / DEM / 建筑轮廓
    A->>N: 自然语言描述 → CGA
    N->>C: 校验 / 解析 CGA
    C-->>N: AST / 语义结果
    A->>R: 执行 CGA + footprint
    R-->>A: GLB / 报告
    A->>V: 预览模型 / 放置到地形
    V-->>U: 交互式三维场景
            

8.3 已修复的基础问题

在本次整体审视中，已先对最明显的基础设施问题进行修复，形成后续开发的可扩展骨架：

8.4 分阶段实施路线图

以下阶段按依赖关系排列，可根据资源与优先级调整。每个阶段给出目标、周期、具体任务、交付物与验收标准。

8.4.1 Phase 0：基础架构与门户（2 周）

目标：让 10 个子域名都有独立落地页和基础 API，建立可扩展、可观测、可部署的工程骨架。

验收标准：curl https://*.peyep.com 全部返回 200 且风格统一；/api/v1/status 返回所有服务状态；CI 流水线通过。

8.4.2 Phase 1：cgajs 解析与 Golden 测试（6–8 周）

目标：自研 CGA 解析器可解析 780 个官方文件的核心子集，并用 PyPRT 建立 golden 几何对比基准。

验收标准：70% Tutorial 文件 L0 通过；simpleBuilding 系列 L2 通过；与 PyPRT 的 Hausdorff 距离 < 0.05 m。

8.4.3 Phase 2：NL2CGA 自然语言生成（4–6 周）

目标：通过自然语言描述生成可执行的 CGA 规则，并以建筑为起点验证闭环。

验收标准：5 类建筑描述成功率 > 70%；生成 CGA 可通过 cgajs 解析并执行出有效 GLB。

8.4.4 Phase 3：Runtime 几何引擎与 Viewer（4–6 周）

目标：让几何生成结果稳定、高效，并在 Web 端可交互预览。

验收标准：任意 Tutorial 建筑 CGA → GLB → viewer 预览，视角切换流畅，材质正确。

8.4.5 Phase 4：数据底座与全局工作台（4–6 周）

目标：接入真实地理数据，实现项目/资产/场景管理，完成「地块 → 模型 → 地形」闭环。

验收标准：用户在地图上选择真实地块 → NL2CGA → Runtime → Viewer 看到建筑立于真实地形。

8.4.6 Phase 5：API / Docs / Test 与商业化（3–4 周）

目标：对外开放稳定 API，完善文档与测试环境，引入多租户与基础计费。

验收标准：外部开发者可通过 API Key 完成一次 NL2CGA → Runtime 调用；docs 站上线；test 环境可重置。

8.4.7 Phase 6：微服务拆分与规模化（持续）

目标：根据实际负载与团队规模，将模块化单体拆分为独立服务，支撑商用负载。

验收标准：平台 SLA 达到 99.5%，并发生成稳定，支持企业级 SSO 与审计。

8.5 子域名功能定位优化与冲突消解

在第八章前半部分确定技术路线后，需要回过头来审视 10 个子域名的功能定位，检查是否存在重叠、冲突或可合并的空间，并明确 peyep.com 与 www.peyep.com 的关系。

8.5.1 当前 10 个子域名定位回顾

8.5.2 潜在冲突与重叠分析

总体结论：当前 10 个子域名不存在必须合并的重大冲突。各子站定位清晰、目标用户不同，少量功能重叠通过「公共服务 + 集成嵌入」方式解决。

8.5.3 优化后的子域名架构

优化后保留 10 个子域名，但按「门户 / 工作台 / 能力服务 / 开发者 / 支撑环境」重新分组：

8.5.4 peyep.com 与 www.peyep.com 的关系

为避免 SEO 分散、品牌入口不统一，以及用户混淆：

• www.peyep.com 是唯一官方主站，承载品牌门户、技术报告、产品矩阵。
• peyep.com 裸域仅作为跳转入口，所有请求 301 永久重定向到 https://www.peyep.com{uri}。
• 搜索引擎只索引 www.peyep.com，避免重复内容。
• 所有对外宣传、链接、二维码统一使用 www.peyep.com。

实现方式：

# Caddyfile
peyep.com {
    redir https://www.peyep.com{uri} permanent
}

同时在 FastAPI 层做兜底：当检测到 Host 为 peyep.com 时，也返回 301 跳转。

8.5.5 子产品间集成关系

flowchart LR
    W[www.peyep.com
官网/报告]
    A[app.peyep.com
工作台]
    N[nl2cga.peyep.com
生成 CGA]
    C[cgajs.peyep.com
解析/调试]
    R[runtime.peyep.com
生成几何]
    V[viewer.peyep.com
预览]
    D[data.peyep.com
底图/数据]
    AP[api.peyep.com
控制台]
    DO[docs.peyep.com
文档]
    T[test.peyep.com
沙盒]

    W --> A
    A --> N & D & V
    N --> C --> R --> V
    AP --> DO
    T -.-> N & C & R & V & D
            

说明：

• www 向访客介绍产品并引流到 app。
• app 是核心集成入口，通过 iframe/组件调用 nl2cga、viewer、data。
• nl2cga 生成的 CGA 提交给 cgajs 解析，再交给 runtime 生成几何，最终在 viewer 预览。
• api 提供程序化访问，docs 提供详细文档，两者互相链接。
• test 部署各子站的 staging 版本，用于演示与回归测试。

8.6 决策清单

在进入大规模开发前，建议先明确以下决策：

九、服务器与基础设施配置清单

本章给出 peyep 项目从 MVP 到商业化不同阶段所需的服务器硬件、软件栈、网络、存储、安全与成本配置清单，用于采购、预算与部署决策。

9.1 总体原则

• 渐进投入：Phase 0–1 用单台高性能云服务器即可跑完全部 MVP；后续按实际负载水平扩展。
• 计算密集在 Runtime：CGA 解析与几何生成是 CPU/内存密集型，需优先为 runtime/cgajs 预留资源。
• GPU 非必需但推荐：MVP 阶段 LLM 走 API，无需 GPU；进入 Phase 3 后若要做本地化推理、实时渲染或路径追踪，再引入 GPU 节点。
• 数据与状态分离：应用无状态化，文件走对象存储，会话/缓存走 Redis，结构化数据走 PostgreSQL。
• 先云后裸金属：早期用云服务器灵活试错；规模化后可考虑裸金属或 GPU 专用服务器降低成本。

9.2 按开发阶段的服务器配置

9.2.1 Phase 0–1：MVP 单体阶段（约 2–10 周）

所有服务跑在单台 Linux 服务器上，Caddy + FastAPI + PostgreSQL + Redis 同机部署。

预估成本：云服务器约 ¥500–1,500/月（按国内主流云厂商 8 核 32G 计算型估算）。

9.2.2 Phase 2–3：NL2CGA + Runtime 强化（约 4–12 周）

开始拆分数据库、缓存、对象存储；runtime 可能跑独立 worker。

预估成本：约 ¥2,000–5,000/月（含计算、数据库、存储、带宽）。

9.2.3 Phase 4–5：多服务生产阶段（约 4–10 周）

子产品拆分为多个服务，需要多节点、负载均衡、独立数据服务。

预估成本：约 ¥8,000–30,000/月（含云服务器、数据库、对象存储、CDN、GPU）。

9.2.4 Phase 6：规模化与企业级（持续）

多区域、多可用区、Kubernetes、GPU 集群、企业合规。

预估成本：¥30,000+/月，视用户量与并发度而定。

9.3 节点类型与详细配置

9.4 软件栈清单

9.5 网络与域名要求

9.6 存储与备份

9.7 安全基线

9.8 开发环境与本地机器

9.9 成本估算

注：以上为国内主流云厂商（阿里云 / 腾讯云 / 华为云）按量/包月估算，不含 CityEngine 商业许可、Esri 资产授权、第三方 SaaS（如 Cesium ion、Google 3D Tiles）费用。

十、结论与下一步

通过对 CityEngine 官方工程文件和文档的系统性学习，以及对 NL2CGA、cgajs、CGARuntime、viewer、全球数据底座五大子产品的深入技术调研，可以确认：

• CGA 是一套成熟、表达力强的程序化建模 DSL，核心思想是 Shape + Scope + Rule Replacement。
• 商业化 NL2CGA 必须采用 Semantic IR + 模板 + Agent/Critic 的混合架构，而非端到端 LLM。
• cgajs 应走 Lark 快速解析 → Python 执行器 → ANTLR4 规范化 → C++ 几何内核加速 的路线。
• CGARuntime 应以 自研半边结构为主核，嫁接 CGAL / Manifold / OpenCASCADE 作为算法后端。
• viewer 不要自研底层渲染器，采用 Three.js 做单体建筑 + CesiumJS 做城市级 GIS。
• 全球数据底座采用 开放数据 + 商业补充 + CesiumJS 的混合方案，注意各平台商用授权。
• 基础设施已就绪：peyep.com 与任意子域名均已支持 HTTPS，FastAPI + Caddy 反向代理运行稳定。
• PyPRT 可作为内部 golden 参考，但需严格与产品运行时隔离，避免 Esri 授权风险。
• 780 个官方 CGA 足以支撑 cgajs 的 MVP 种子语料，配合 LLM 自我迭代可显著加速解析器与运行时完善。
• 10 个子域名功能定位经冲突审查后确认无需合并，已按门户 / 工作台 / 能力服务 / 数据 / 开发者 / 支撑环境重新分组；peyep.com 裸域统一 301 跳转至 www.peyep.com。