# NL2CGA 架构澄清与实现路线

> 说明：本文档用于澄清 `cga-library`（cgajs.com 本地）与 `marketplace.rulepackage.com`（rulepackage.com 权威）在 NL2CGA 体系中的不同定位，并给出“如果没有本地 NL2CGA CGA 库框架，如何更快更好地实现自然语言转 CGA”的详细方案。

---

## 1. 当前双站分工（已落地）

| 站点 | 职责 | 对应目录/端点 |
|---|---|---|
| **cgajs.com** | CGA 引擎、IDE、NL2CGA 训练语料库（高质量、人工 curated） | `/api/v1/cga-library` → `nl2cga/prebuilt/`、`nl2cga/template_engine/templates/`、`nl2cga-service/library/` |
| **rulepackage.com** | Marketplace / CGA 文件写入权威、Omega 黄金标准、Corpus 分发 | `/api/v1/cga-corpus`、`/api/v1/marketplace/*`、`/api/v1/omega/*` |

### 1.1 `cga-library` 与 `marketplace` 的本质区别

- **`cga-library`（cgajs.com 本地）**
  - 目标：为 NL2CGA 提供**语义训练样本**。
  - 特点：
    - 代码质量高、结构规范、带 `@StartRule` 与 `attr` 注释；
    - 按建筑风格/功能分层（`prebuilt`、`parameterized`、`library`）；
    - 与 `nl2cga_service` 直接耦合，用于意图匹配、少样本提示（few-shot）、参数模板；
    - 写入权限保留在 cgajs.com，方便 NL2CGA 团队快速迭代语料。
  - 因此它**不应该**被迁移到 rulepackage.com，它是 cgajs.com 的 NL2CGA 核心资产。

- **`marketplace.rulepackage.com`**
  - 目标：用户上传/购买的 CGA 示例仓库。
  - 特点：
    - 来源开放、质量参差不齐；
    - 通过 `cga-corpus` API 对外提供只读消费；
    - 适合作为 IDE 的“示例浏览器”和 NL2CGA 的**外部检索增强语料**。

**结论**：两者不是竞争关系，而是互补关系。`cga-library` 是 NL2CGA 的“教科书”，`marketplace` 是“案例集”。

---

## 2. 已修正的代码

此前 P2 实现中，误将 `cgajs.com /api/v1/cga-library/files/{slug}` 的 `save/rollback` 代理到了 rulepackage.com。现已回滚：

- `cgajs-api/cga_editor_routes.py` 中 `save_file` / `rollback_file` 恢复为本地操作；
- 去掉了对 `rulepackage_client` 的依赖；
- Marketplace 的读取仍然代理到 rulepackage.com（见 `/api/v1/marketplace/feed` 与 `/{id}/download`），确保 IDE 能加载 marketplace 示例。

---

## 3. 方案 A：保留本地 cga-library（推荐，当前已采用）

如果保留 `cga-library` 作为 NL2CGA 训练语料库，整体 NL2CGA 流程如下：

```text
用户自然语言描述
        ↓
[意图解析] 提取：建筑风格、功能、尺寸、材质、规则偏好
        ↓
┌─────────────────────────────────────────┐
│ 1. 本地 cga-library 语义匹配              │
│    - 向量检索（embedding）               │
│    - 关键词/标签匹配                     │
│    - 参数化模板匹配                      │
└─────────────────────────────────────────┘
        ↓
┌─────────────────────────────────────────┐
│ 2. Marketplace 案例增强（RAG）            │
│    - 调用 rulepackage.com /cga-corpus    │
│    - 检索相似标题/标签的公开示例         │
└─────────────────────────────────────────┘
        ↓
[Prompt 组装] 系统提示 + 本地模板 + 市场案例 + 用户描述
        ↓
[LLM 生成 CGA]
        ↓
[引擎编译验证] → 成功：返回 CGA；失败：进入自动修复循环
```

### 3.1 为什么推荐保留本地库

1. **质量可控**：NL2CGA 输出高度依赖示例质量，本地 curated 库能避免 Marketplace 中劣质/错误代码污染模型。
2. **语义对齐**：本地库可以按 `建筑风格 × 功能 × 复杂度` 打标签，与 NL2CGA 的意图解析层一一对应。
3. **离线可用**：本地库不依赖 rulepackage.com，核心生成链路更稳定。
4. **快速迭代**：调整语料、修复 bad case 不需要跨站发布。

---

## 4. 方案 B：如果没有本地 cga-library，如何更快更好地实现 NL2CGA

如果由于某种原因不能维护本地 `cga-library`，则应把 **rulepackage.com 的 `/api/v1/cga-corpus` 作为唯一语料源**，并通过工程手段弥补“质量不可控”的缺陷：

### 4.1 语料预处理层（必须在 rulepackage.com 或 cgajs.com 实现）

```text
rulepackage.com /cga-corpus 原始文件
        ↓
[质量过滤]
  - 必须包含 @StartRule
  - 引擎编译成功
  - AST 节点数 > N
  - 包含 attr / 注释 / 结构化 split/comp
        ↓
[元数据提取]
  - 标题、描述、标签、分类
  - 提取 attrs 列表与默认值
  - 识别建筑类型关键词（roof、facade、window、extrude…）
        ↓
[向量化]
  - 用 embedding 模型（text-embedding-3 / bge / e5）把
    "标题 + 描述 + 标签 + 代码摘要" 编码为向量
        ↓
[向量数据库]
  - pgvector / chroma / qdrant 存储 (embedding, metadata, cga_code)
```

### 4.2 NL2CGA 生成链路（无本地库版）

```text
用户输入
        ↓
[意图解析] 同样提取风格/功能/尺寸/材质
        ↓
[向量检索 Top-K] 从 pgvector 中召回最相似的 Marketplace 案例
        ↓
[重排序 Rerank]
  - 按编译成功率、质量分、描述相似度排序
  - 过滤掉重复/低质案例
        ↓
[少样本提示 Few-shot]
  - System: 你是 CityEngine CGA 专家
  - Examples: Top-3 高质量 Marketplace 案例
  - User: 按以下意图生成 CGA：{意图}
        ↓
[LLM 生成]
        ↓
[编译验证 + 自动修复]
```

### 4.3 如何“更快更好”

| 要点 | 做法 | 效果 |
|---|---|---|
| **质量门** | Marketplace 上传时强制编译校验 + `quality_score` | 把劣质语料挡在门外 |
| **自动标注** | 用 LLM 给每个 .cga 生成标题/标签/描述 | 解决 Marketplace 元数据缺失问题 |
| **向量索引** | 每晚用 `corpus_validator.py` 重跑，更新 embedding | 保证检索与引擎版本同步 |
| **混合检索** | 向量相似度 + 关键词过滤 + 质量分排序 | 召回更精准 |
| **自动修复闭环** | 生成失败 → 解析错误 → LLM 修复 → 再编译 | 提升首次成功率 |
| **A/B 测试** | 对同一意图用不同 Few-shot 案例生成，选编译通过且几何合理的 | 持续提升输出质量 |

### 4.4 关键风险

- **语料噪声大**：Marketplace 案例来自用户，错误、风格不统一、过度复杂都会降低 NL2CGA 稳定性。
- **延迟高**：每次生成都要跨站检索、向量化、LLM 调用，链路变长。
- **版权/付费内容**：不能直接把付费 Marketplace 文件作为 Few-shot 示例返回给未购买用户，需要按价格/权限过滤。

**结论**：没有本地库也能做，但需要在 rulepackage.com 侧建立“质量过滤 + 自动标注 + 向量索引”三层基础设施，否则效果会明显差于方案 A。

---

## 5. 让 IDE 读取 marketplace.rulepackage.com 示例

此功能已落地：

- `cgajs.com /api/v1/marketplace/feed` 代理到 `rulepackage.com /api/v1/marketplace/feed`；
- `cgajs.com /api/v1/marketplace/{id}/download` 本地未命中时代理到 rulepackage.com；
- IDE 中点击“🏪 CGA市场”即可加载 rulepackage.com 的公开/免费示例。

如果需要进一步在 IDE 中直接浏览 `/api/v1/cga-corpus`（按分类/标签），可以再增加一个“Corpus 浏览器” Tab，调用：

```js
const corpus = await fetch('/api/v1/cga-corpus?source=marketplace&limit=20');
```

---

## 6. 推荐下一步（按优先级）

1. **P0** 确认 `cga-library` 写入保留在 cgajs.com（已完成）。
2. **P1** 在 cgajs.com 为 NL2CGA 建立 `cga-library` 向量索引（pgvector），把本地高质量语料 embed 化。
3. **P1** 实现“意图解析 → 本地向量检索 → Marketplace 向量检索”的混合召回。
4. **P2** 在 rulepackage.com 侧为 Marketplace 文件自动打标、评分、建立向量索引（如果未来想减少对本地库的依赖）。
5. **P2** 在 IDE 增加 Corpus 浏览器 Tab，直接消费 `/api/v1/cga-corpus`。
6. **P3** 上线 NL2CGA A/B 评估面板，持续对比“本地库 few-shot” vs “Marketplace RAG” 效果。

---

## 7. 一句话总结

`cga-library` 是 cgajs.com 的 NL2CGA 训练资产，应保留在本地；`marketplace.rulepackage.com` 是用户示例仓库，应作为 RAG 增强源通过代理供 IDE 读取。没有本地库时，NL2CGA 仍然可行，但必须在 rulepackage.com 侧建立强有力的质量过滤与向量化层。