NL2CGA 自主学习系统开发计划

CGA 引擎现状

• 解析器：ANTLR4 驱动，语法覆盖完整，错误恢复能力基础可用
• 运行时：1727 行核心求值器，支持 60+ Shape 操作、162 个内置函数
• 几何模块：Extrude / Split / Comp / Roof / UV / Boolean / Setback 等已实现，但部分为简化方案
• 测试：14 组 e2e 测试覆盖 happy path，边缘 case 不足

NL2CGA 现状

• 严重缺失引擎层 nl2cga_bridge.ts 仅为接口空壳，prompt_templates.ts 全部为空
• 部分可用API 层 ai_service.py 有 LLM 客户端，但仅用于编译错误分析（修代码），不能生成代码
• 闭环存在learning_routes.py 已建立"失败案例 → LLM 分析 → 修复建议 → 人工审核"的学习闭环
• 资产可用createurban-cga-lite 中有预建模板 + LLM 生成实现，可直接移植

问题：当前 Prompt 中硬编码"已支持语法"，每次新增函数都要手动改 Prompt，极易遗漏和过时。

方案：编写一个构建时脚本，自动扫描源码生成结构化语法知识库：

# 自动提取脚本（建议放在 cgajs-engine/scripts/extract-grammar-docs.mjs）
# 输入：CGAGrammar.g4 + builtins.ts + evaluator.ts
# 输出：grammar-knowledge.json（被 RAG 和 Prompt 动态加载）

提取内容：
  1. 从 CGAGrammar.g4 提取：规则定义语法、操作序列结构、条件/随机分支写法
  2. 从 builtins.ts 提取：162 个函数的签名、参数类型、返回值、使用示例
  3. 从 evaluator.ts 提取：60+ Shape 操作的用法和约束
  4. 从 tests/ 提取：每个函数/操作的真实运行示例

输出格式（JSON）：
{
  "version": "1.3.2",
  "generatedAt": "2026-06-09",
  "operations": [
    { "name": "extrude", "params": ["height"], "returns": "Shape[]",
      "example": "Lot --> extrude(10) comp(f) { top: Roof }",
      "constraints": ["height > 0"] }
  ],
  "functions": [
    { "name": "rand.int", "category": "probability",
      "signature": "rand.int(min, max) -> int",
      "description": "返回 [min, max) 范围内的随机整数" }
  ],
  "annotations": ["@StartRule", "@Group", "@Range", "@Hidden"]
}

触发方式：将脚本绑定到 npm run build 或 Git 预提交钩子，每次构建自动更新。Prompt 加载时动态读取此 JSON，而非写死。

当用户请求 NL2CGA 生成时，后端自动将当前引擎的完整语法快照注入 LLM 上下文：

# 动态 Prompt 组装（cgajs-api 层实现）
system_prompt = f"""
你是 CGA.js v{engine_version} 专家。当前引擎支持的语法如下：

## 可用 Shape 操作（{len(operations)} 个）
{format_operations(grammar_knowledge['operations'])}

## 可用内置函数（{len(functions)} 个）
{format_functions(grammar_knowledge['functions'], top_used=30)}

## 关键约束
- 必须使用 @StartRule 标记入口规则
- split 轴只能是 x|y|z|u|v（当前 u/v 未实现，避免使用）
- comp(h) 孔洞检测暂不支持，避免依赖

只输出有效 CGA 代码，不要解释。
"""

价值：新增 roofGambrel 函数后，重新部署即自动出现在 AI 的知识范围内，零人工维护 Prompt。

这是让 NL2CGA "越用越聪明" 的核心飞轮：

语法变更时的自动适应：当你修改了语法（如新增 @Import 注解），过去积累的"错误-修复"对中涉及旧语法的数据会被自动标记为 legacy，新语法的成功案例会被赋予更高权重进入训练集。

不仅要知道"有哪些函数"，还要知道"什么时候该用什么函数"。

• 将 Marketplace 中每个 .cga 文件 + 标题 + 描述向量化（使用代码嵌入模型）
• 将 162 个函数的文档和 3~5 个典型用例向量化
• 用户输入自然语言时，检索 Top-5 最相关的 CGA 源码片段和函数文档
• 检索结果直接拼接到 LLM 上下文（Few-shot 示例），让 AI "看到"别人是怎么写的

# RAG 检索示例
用户输入："做一个带飞檐的中式屋顶"
检索结果：
  1. "03_japanese_pagoda.cga" — 相似度 0.91（roofHip 多层叠加）
  2. "temple style guide" — 相似度 0.87（飞檐参数说明）
  3. "roofHip 函数文档" — 相似度 0.85

LLM 上下文追加：
  "参考以下实现飞檐屋顶的方式：" + 检索到的代码片段

这是自主学习的触发器，确保语法变更被 NL2CGA 系统第一时间感知：

# 绑定到 CI/CD 或 Git 钩子的流水线
触发条件：grammar/CGAGrammar.g4 或 src/functions/builtins.ts 发生变更

自动执行：
  1. 运行 extract-grammar-docs.mjs → 更新 grammar-knowledge.json
  2. 运行全量 e2e 测试 → 确认新语法行为正确
  3. 运行回归测试 → 确认旧语法未被破坏
  4. 用新语法重新索引 Marketplace 文件 → 更新向量数据库
  5. 重新编译预建模板 → 验证模板仍有效
  6. 若存在 Fine-tuned 模型 → 触发增量微调任务（用新语法案例扩充数据集）

结果：你提交一个 PR 新增 geometry.isRectangular 函数，10 分钟后 NL2CGA 系统已经知道它的存在、签名、用法，并能在生成代码时正确推荐。