NL2CGA 自主学习系统开发计划

• 在 runtime.cityvistion.cn 部署 Loki 2.9.8，本地监听 127.0.0.1:3100，数据持久化到 /var/lib/loki。
• runtime 与 gateway 两台服务器部署 Promtail 2.9.8，采集 systemd-journal 与 application 日志并推送到 Loki。
• Nginx 为 /loki/ 添加 Basic Auth，跨节点推送使用 HTTPS + 用户名/密码。
• Grafana 新增 Loki 数据源与 "Runtime Logs" 日志面板，CityVistion Runtime Overview 看板同时展示 Metrics 与 Logs。
• 新增 C++ 几何内核 cv_geometry_native（Clipper2 + earcut + pybind11），已集成到 cga_runtime.py，offset/inset/slice/extrude 走 native 路径，失败自动回退 shapely/trimesh。

• 修复 admin.html 编码与站点管理面板
• 新增站点脚本模板与 nginx 配置模板
• 安全同步 rulepackage cgajs-api 到 cgajs 并验证稳定

• 根据完整诊断日志，定位到真正失败点：DIAG import FAIL: /assets/cgajs-engine/index.js?v=31。
• 进一步排查发现 cgajs-engine/dist/engine-Q6UQinqA.js 顶部存在静态导入 import { readFile } from "node:fs/promises";，浏览器解析模块时会直接失败，导致整个引擎加载中断。
• 修复：移除该静态导入，改为在 loadAssetGeometryUncached 函数内部动态 await import('node:fs/promises')，仅在 Node 环境实际调用时才加载。
• 将引擎版本戳从 v=31 提升到 v=32，强制浏览器重新拉取修复后的文件。
• 本次备份：/root/backups/www.cgajs.com-20260615-204504.tgz。

• 用户反馈只能看到部分 fetch OK 诊断，缺少引擎文件与 import 诊断；怀疑 /cgajs-engine/dist/ 路径被浏览器/扩展/网络层拦截。
• 将 /cgajs-engine/dist 通过符号链接暴露到 /assets/cgajs-engine，所有 IDE 中的引擎引用改为 /assets/cgajs-engine/index.js?v=31，避免原路径被拦截。
• 动态 import 诊断也改为绝对 URL，不再依赖 importmap。
• 在页面顶部增加固定 <textarea id="ide-raw-logs"> 日志区，所有错误自动追加，便于一键复制完整输出。
• 本次备份：/root/backups/www.cgajs.com-20260615-204131.tgz。

• 用户反馈 v=25/26/27 均报 Resource failed to load | inline-module，说明问题不在 ide-core.js 本身，而在其 ES Module 静态依赖加载。
• 将内联模块从静态 import 改为异步 await import()，并用绝对 URL，彻底绕过 importmap 可能的解析问题。
• 引入 es-module-shims.min.js 作为 importmap / 模块加载 polyfill，覆盖浏览器原生实现有缺陷的场景。
• 在 ide.html 增加两层诊断脚本：
  • fetch 诊断：直接请求每个依赖 URL，区分网络层失败还是模块层失败。
  • 动态 import 诊断：对每个依赖调用 import()，失败时输出具体错误和堆栈。
• 为 cgajs-engine/dist/index.js 的相对导入 ./engine-Q6UQinqA.js 追加 ?v=31，避免其历史缓存影响。
• 本次备份：/root/backups/www.cgajs.com-20260615-201226.tgz。

• 用户反馈 v=25/26/27 均报 Resource failed to load: https://www.cgajs.com/assets/ide-core.js?v=27，说明单纯版本戳无法解决。
• 服务端确认 ide-core.js 及其所有静态依赖（three、cgajs-engine、addons）HTTP 均为 200 + CORS 头，且文件内容完整无语法错误。
• 彻底修复：将 ide-core.js 直接内联到 ide.html，消除该文件本身的网络请求/缓存/扩展拦截等失败可能。
• importmap 中 three 与 cgajs-engine 的版本戳分别刷新为 ?v=27 与 ?v=31，避免其缓存中可能存在的历史失败响应。
• 增强前端错误捕获：资源失败时现在会输出 tag/type/src/inline-module/message/filename/lineno/colno 等完整字段，便于定位真实失败点。
• 本次备份：/root/backups/www.cgajs.com-20260615-200404.tgz。

• 用户反馈通过 https://cgajs.com/ide.html 访问时，调试面板仍报 Resource failed to load: https://cgajs.com/assets/ide-core.js?v=26。
• 服务端验证该文件可正常返回 200，判断为浏览器端缓存/域名不一致导致。
• 将 ide-core.js 与 cga-codemirror-mode.js 的版本戳从 v=26 提升到 v=27，强制浏览器重新拉取。
• 在 Nginx 中为 js/css/引擎/字体/图片等静态资源统一添加 Access-Control-Allow-Origin: *，避免 crossorigin / ES Module 出现 CORS 偶发失败。
• 在 HTTPS 层面对 cgajs.com 添加 301 跳转至 www.cgajs.com，统一规范域名，消除双域名缓存/跨域歧义。
• 本次备份：/root/backups/www.cgajs.com-20260615-195951.tgz。

• 用户反馈调试面板显示 Resource failed to load: https://www.cgajs.com/assets/ide-core.js?v=25。
• 服务端验证该文件 HTTPS 返回 200 + application/javascript，资源本身正常。
• 将 ide-core.js 与 cga-codemirror-mode.js 的版本戳从 v=25 提升到 v=26，强制浏览器跳过可能存在的旧缓存/301 重定向缓存。
• 为 ide-core.js 模块脚本增加 crossorigin="anonymous"，改善错误报告与跨域一致性。
• 本次备份：/root/cgajs_full_backup_20260615_195557.tar.gz。

• API、Marketplace、引擎资源 HTTP 返回均正常；服务端无异常日志。
• 移除 .CodeMirror { height: 100% !important; } 中的 !important，避免 CodeMirror 内部 setSize 被覆盖。
• 在 ide.html 增加前端错误浮层，捕获 JS Error / 资源加载失败 / 未处理 Promise，方便用户直接反馈。
• 等待用户按 Ctrl+Shift+R 强制刷新后，把页面底部红色调试信息贴回。
• 本次备份：/root/cgajs_full_backup_20260615_195036.tar.gz。

• 修复 index.html 导航 HTML 因自动脚本导致的重复/错位标签。
• 桌面端主导航仅保留 5 个核心入口：IDE、Marketplace、CGA Library、NL2CGA、Omega。
• 其余页面统一收进「🧭 更多」下拉菜单；移动端菜单同步精简分组。
• 本次备份：/root/cgajs_full_backup_20260615_194524.tar.gz。

• 恢复 .layout flex 列布局与 html { font-size: 14px; } 基准，解决字体变大问题。
• 补全侧栏 .panel-tabs / .panel-tab / .panel-content 样式，修复 Inspector / AST / Diagnostics 等面板显示异常。
• 补全 #viewer canvas 100% 填充与 .error-item 样式，恢复 3D 视图与诊断列表。
• 将 IDE 初始化失败检测从单次 2.5s 改为 8s 轮询，并在初始化成功后自动移除提示，避免大模块加载时被误判。
• 本次备份：/root/cgajs_full_backup_20260615_194229.tar.gz。

• 创建 backup-full.sh：每次修改前自动全站备份，保留最近 10 份。
• 创建 update-project-dashboards.py：自动更新 updata.html 会话卡片、me.html 用户待办、首页导航菜单。
• 创建 kimi-wrap-up.sh：一键执行备份 + 更新仪表盘 + 同步共享记忆库。
• 本次已自动备份：/root/cgajs_full_backup_20260615_192208.tar.gz。

对 https://www.rulepackage.com/architecture-report.html 提出的“cgajs.com 专注引擎/AI，rulepackage.com 专注 CGA 资产与 Omega 测试”解耦方案进行了可行性评估。结论：架构方向合理、技术上可行，但落地风险集中在“服务器即开发机”的工作流和跨站 API 完整性。

一、方案优势（值得采纳）

• 职责清晰：cgajs.com 作为“引擎大脑”负责 parser、geometry runtime、NL2CGA、auth/billing、IDE；rulepackage.com 作为“资产与标尺中心”负责 CGA 仓库、Marketplace、Omega golden case。避免两站同时维护同一份权威数据。
• 单一权威：CGA 文件只在 rulepackage.com 编辑，引擎只在 cgajs.com 编辑，天然消除写入冲突。
• API 优先：跨站调用走 REST API，不直接读对方数据库，符合分布式系统最佳实践。
• 按需同步：引擎产物 rsync、语料 webhook + cron、Omega golden case API 拉取，三种同步策略与数据特性匹配。

二、当前落地差距（需要补齐）

三、最大风险：服务器即开发机

• 报告提出“直接在服务器上修改、提交、测试”。这在生产环境是高风险反模式：没有 PR review、没有 staging、没有回滚分支、一次误操作即可影响线上。
• 建议改为：服务器上保留 git 工作区用于快速验证，但关键变更仍需走“本地/容器开发 → PR → CI → 部署脚本”流程；紧急热修也必须先 git commit 再改文件，便于事后追溯。
• 当前已创建的 docker-compose.yml、.github/workflows/ci.yml、scripts/deploy.sh 已经为 CI/CD 闭环打下基础，应继续完善而非回到纯服务器开发模式。

四、推荐实施节奏

五、立即可以执行的 3 件事

1. 在 rulepackage.com 创建 /api/v1/cga-corpus 与 /api/v1/omega/sync-to-cgajs，先把磁盘文件暴露为 API。
2. 在 cgajs.com 扩展 /api/v1/webhooks/rulepackage，支持 asset.created、asset.updated、omega.batch_ready、marketplace.approved 四种事件类型。
3. 新增 scripts/promote-to-prod.sh：cgajs.com 引擎 CI 通过后，rsync dist-stable 到 rulepackage.com，并同步更新双方的 site-version.json。

最终结论：该解耦方案可行且建议采纳，但不要采用“服务器即开发机”的原始工作流，而是把当前已搭建的 Docker/CI/GitHub Actions 能力接进去，形成真正可维护的双站协作体系。

为同时支撑“解析器完整能力”和“NL2CGA 未来进化”，提出不再把两个站点合并成一个网站，而是让 cgajs.com 专注 CGA 引擎/解析器/NL2CGA 生成，rulepackage.com 专注 CGA 文件仓库与 Omega 黄金测试体系，二者通过 API 互联。

一、角色定位

二、跨站 API 契约

cgajs.com 提供：

• POST /api/v1/engine/run：输入 CGA 规则 + 初始 Shape，返回执行后的 geometry 与 metadata。
• POST /api/v1/geometry/compare：输入 expected / actual + 对比策略，返回 pass/fail 与差异。
• POST /api/v1/parse：已存在，保持不变。

rulepackage.com 新增 omega-api：

• POST /api/v1/omega/build-case：从 OBJ 生成标准 tests/golden/cases/<caseId>/ 目录结构。
• POST /api/v1/omega/run-test：调用 cgajs.com engine/run + geometry/compare，写入报告。
• GET /api/v1/omega/reports：获取 golden 测试报告。
• POST /api/v1/omega/sync-to-cgajs：批量推送 golden cases 给 cgajs.com CI。

三、数据流向

rulepackage.com (Omega 上传 OBJ)
        ↓
生成 golden case → tests/golden/cases/<caseId>/
        ↓
调用 cgajs.com /api/v1/engine/run 执行 rule
        ↓
调用 cgajs.com /api/v1/geometry/compare 对比 expected
        ↓
生成报告 ← 反哺修复 engine ← CGA 文件/语料同步给 cgajs.com NL2CGA

四、实施阶段

• Phase 1（1 周）：定义 API 契约；cgajs.com 新增 engine/run 与 geometry/compare；rulepackage.com 新建 omega-api。
• Phase 2（1 周）：统一 golden case 目录格式（rule.cga + initial-shape.json + expected.json），迁移已有 uploads。
• Phase 3（1 周）：Omega 前端打通“生成 case → 运行测试 → 查看报告”闭环。
• Phase 4（1 周）：rulepackage.com CGA 文件作为 NL2CGA 权威语料源，rsync/webhook 同步到 cgajs.com 重建向量 RAG 索引。
• Phase 5（1–2 周）：cgajs.com IDE 增加“提交到 Golden Test”按钮；admin 嵌入 rulepackage.com 报告看板。
• Phase 6（持续）：rulepackage.com 每日/触发式运行 npm run test:golden，作为 cgajs.com 引擎发布的硬门槛。

五、数据所有权

• CGA 文件 / marketplace / library：权威在 rulepackage.com，消费方是 cgajs.com NL2CGA 与 IDE。
• Golden cases / expected outputs：权威在 rulepackage.com，cgajs.com engine/CI 消费。
• Parser / Engine / NL2CGA model：权威在 cgajs.com，rulepackage.com 测试调用。
• 用户 / auth / billing / IDE：权威在 cgajs.com。
• Omega 上传工具 / 测试报告：权威在 rulepackage.com。

目标：以 cgajs.com 的解析器和 NL2CGA 为躯干，以 rulepackage.com 的 Omega 黄金测试体系为“眼睛和标尺”，两边合并后通过持续 golden case 驱动 NL2CGA 自我进化，形成真正可用、可维护、可扩展的 CGA 智能生成平台。

实际扫描远端 8.216.94.109 上 /www/wwwroot 全域，共发现 534 个 .cga 文件（扫描覆盖 531 个）。这些文件不应只躺在磁盘里，而应被索引为解析器回归套件、NL2CGA 训练/检索语料、Marketplace 商品目录三类资产。

一、资产盘点

元数据画像：总大小约 0.83 MB，平均每文件 1.6 KB；共提取到 2 262 个 attr 声明、236 个 @StartRule、229 个文件含规则描述；前三大复用模块为 roof、facade、material。

二、解析器完善：把 534 文件变成“不会退化的标尺”

• 回归套件：在 cgajs-engine/tests/cga-corpus/ 下按原目录结构软链接/复制全部 534 文件，CI 中批量跑 parseCGA()，当前 525/531 通过（98.9%）。
• 失败专项：6 个失败全部集中在 private-knowledge/rag-source 中式宫殿文件，典型错误为 split(z)、顶层 const 与 comp 选择器混用、splitArea(z, noAdjust)。为每个错误建独立 issue，逐个补齐语法或做源码规范化。
• AST 往返测试：对 marketplace 380 个 UUID 文件执行“解析 → AST → 代码生成 → 再解析”，保证 AST 稳定、无信息丢失。
• 注解覆盖：23 个模板文件大量使用 @Group/@Range/@Color/@Enum/@Hidden，用它们验证 parser 对注解语法的完整支持。

三、NL2CGA 进化：从文件堆到可检索的语义库

• RAG 语料 cga-corpus.jsonl：每条记录包含文件路径、风格标签、自然语言描述（提取 @RuleFileDescription、目录名、文件名）、参数 schema、StartRule、imports、关键规则片段。
• 参数 schema 库：聚合 2 262 个 attr 的 @Group/@Range/@Enum/@Color 信息，生成 cga-parameter-schema.json，让 NL2CGA 生成时不再瞎造参数名。
• Few-shot 样本库：从 20 个预建模板 + 23 个参数化模板 + 99 个 library 分类文件中，按风格挑选 canonical 示例，作为大模型 in-context learning 的 shot。
• 评测基准：建立 NL2CGA eval benchmark，输入为自然语言描述，期望输出为对应 CGA 文件；评测指标 = 语义相似度 + parse 成功率 + engine 渲染成功率。
• 风格专场：9 个中式宫殿文件用于训练“古建/宫殿”专属生成能力；marketplace 380 文件用于训练真实用户分布的风格分类器。

四、Marketplace 完善：从 UUID 文件到可售资产

• 元数据补全：自动把 UUID 文件名替换为语义名（如 modern_villa.cga），依据 @RuleFileDescription、规则名、高频 attr 关键词；无描述时走 LLM 自动 caption。
• 质量门：公开上架前必须通过 parse 成功、engine 渲染成功、无运行时错误；高价值 case 再跑 Omega golden diff。
• 自动分类：按目录/内容关键词打上 Residential / Commercial / Industrial / Transportation / Religious / Public / ChineseArchitecture / Infrastructure 等标签。
• 预览与参数面板：每个文件生成缩略图（engine 渲染 OBJ → 截图）、参数 UI JSON（从注解生成滑动条/颜色选择器/下拉枚举），前端支持搜索、预览、一键在 cgajs.com IDE 打开。
• manifest 规范：每个资产增加 manifest.json（title、description、tags、author、license、parameters、preview、source）。

五、4 周落地路线

六、立即可以开始的 3 个动作

1. 远端执行 node /www/wwwroot/cgajs-engine/scripts/scan_cga_corpus.js，生成每日解析率报告。
2. 在 rulepackage.com 新增 /api/v1/cga-corpus：返回分类、参数 schema、下载链接，供 cgajs.com NL2CGA 消费。
3. 为 marketplace UUID 文件跑一遍 engine 渲染，生成缩略图 + 失败清单，失败的文件先不入库。

目标：让这 534 个文件不再是“死文件”，而成为解析器不会退化的标尺、NL2CGA 不断进化的教材、Marketplace 持续增长的库存。

在上一轮 CGA 语料方案基础上，再次对比两个站点当前实际代码状态，发现双方已经“各走各的”：cgajs.com 实现了更多几何操作但本地提交较旧；rulepackage.com 有更新的 parser/IDE 修复但缺少这些几何操作。需要一次双向合并 + 权威归属 + 自动化同步。

一、现状快照

二、关键差距

1. 引擎“双向分叉”：cgajs.com 有 inset/convert/asset-loader 等实现但缺本地最新 parser/IDE 修复；rulepackage.com 有最新修复但缺这些几何操作。两边 dist-stable 版本不一致（v24 vs v27）。
2. 语料权威在 rulepackage.com 但未落地：按架构方案，CGA 文件权威应在 rulepackage.com，但本地反而没有 corpus 目录和 API；远端已先一步实现。
3. Omega golden case 未形成闭环：远端有 /omega/sync-to-cgajs，但 rulepackage.com（上传入口）没有，导致 golden case 无法从上传端主动推送给引擎端 CI。
4. Marketplace 仍是 raw files：380 个 UUID 文件没有语义名、manifest、缩略图、质量门。
5. 站点版本 / 缓存戳未统一：本地没有 site-version.json，IDE 引用的引擎版本落后，用户可能命中旧缓存。

三、继续完善方案

• 1. 引擎双向合并（P0）
  • 把 cgajs.com 的 src/geometry/operations/create/insert.ts、inset.ts、src/runtime/asset-loader.ts、asset-collector.ts、import-resolver.ts 以及 convert() 实现合并到 rulepackage.com。
  • 把 rulepackage.com 的最新提交（autocomplete 313 项、primitiveSphere、block-body 解析、vector normalization、const annotations、function signatures）合并到 cgajs.com。
  • 统一 dist-stable 版本到同一 hash，并在两个站点同步 site-version.json（engine 升到同一版本）。
• 2. 建立 CGA 语料权威（P1）
  • 在 rulepackage.com 新增 scripts/build_cga_corpus.py：扫描 /www/wwwroot 下 534 个 .cga，按原目录结构软链接进 cgajs-engine/tests/cga-corpus/。
  • 新增 tests/parser/cga-corpus.test.ts 与 /api/v1/cga-corpus endpoint，把解析结果写入 cga_assets 表。
  • cgajs.com 通过定时任务拉取 rulepackage.com 的 /api/v1/cga-corpus，重建本地 tests/cga-corpus/ 与 DB。
• 3. Omega golden case 闭环（P1）
  • 在 rulepackage.com 的 omega_routes.py 补齐 /omega/sync-to-cgajs（直接复制远端实现）。
  • cgajs.com 新增 cron：每 30 分钟拉取 rulepackage.com 的 golden cases，导入 tests/golden/omega-imports/ 并跑 diff。
• 4. Marketplace 资产化（P2）
  • 写 scripts/enrich_marketplace.py：UUID → 语义 slug、自动 caption、参数 schema、标签分类、engine 渲染缩略图。
  • 质量门：parse 成功 + render 成功 + 无缺失 import 才写入 marketplace.rulepackage.com/assets/<slug>/manifest.json 并上架。
• 5. 站点版本与缓存统一（P0-P1）
  • rulepackage.com 新增 site-version.json；ide.html、nl2cga.html、omega.html 都从此文件读取 engine/autocomplete/mode 版本戳。
  • 部署脚本 scripts/promote-to-prod.sh 在同步 dist-stable 后自动 bump site-version.json 并刷新 Nginx。
• 6. CI / 同步流水线（P2-P3）
  • cgajs.com 引擎 CI 通过 → rsync dist-stable 到 rulepackage.com。
  • rulepackage.com 语料 / Marketplace 更新 → webhook 通知 cgajs.com 拉取。
  • 清理 dist-beta、bak 文件、未跟踪临时文件，避免仓库膨胀。
• 7. 跨站状态面板（P3）
  • 新增 /status.html，实时展示两站 engine 版本、corpus 数量、parse 成功率、marketplace 已审核数、上次同步时间。

四、建议落地顺序

五、马上可执行的 3 件事

1. 从 cgajs.com 把 src/geometry/operations/create/inset.ts、src/runtime/asset-loader.ts、tests/e2e/insert.test.ts、tests/e2e/convert.test.ts 等文件 rsync 到 rulepackage.com。
2. 在 rulepackage.com 创建 scripts/build_cga_corpus.py，生成 cgajs-engine/tests/cga-corpus/ 并跑通 cga-corpus.test.ts。
3. 两端都新增 site-version.json，并把 IDE 中的 ?v=24 统一改为读取 site-version.json 的 engine 字段。

目标：结束“双站分叉”，让 cgajs.com 专注引擎能力、rulepackage.com 专注资产与测试，两边通过自动化同步保持完全一致，用户无论访问哪个站点都得到同一套最新引擎与同一批高质量 CGA 资产。

已输出一份独立的可视化报告，明确两个站点解耦后的权威职责、跨站 API 契约、数据流向、功能砍留清单，以及未来直接在服务器上开发的工作流。

• cgajs.com 保留：引擎 / 解析器 / runtime、NL2CGA AI 生成、IDE、用户/鉴权/计费/管理后台、函数库文档、插件生态。
• cgajs.com 砍掉/弱化：canonical CGA 文件仓库、Omega 上传与 golden case 存储、Marketplace 资产发布后台、多版本 dist 并存。
• rulepackage.com 保留：CGA 文件仓库 / Marketplace 资产、Omega 黄金测试体系、NL2CGA 语料源、跨站测试报告 / 状态面板。
• rulepackage.com 砍掉/弱化：引擎源码主开发、NL2CGA 生成服务、完整用户/计费/admin、独立 IDE 创作入口。
• 通信方式：rulepackage.com 暴露 /api/v1/cga-corpus、/api/v1/omega/sync-to-cgajs、/api/v1/marketplace/assets；cgajs.com 暴露 /api/v1/engine/run、/api/v1/geometry/compare、/api/v1/nl2cga/generate；引擎产物用 rsync，语料用 webhook + cron。

完整报告：/architecture-report.html

以后直接在服务器上开发，不再走“本地开发 → 部署”。为了让任意一台服务器的 Kimi 登录后都能读取和更新任务、记忆与更新日志， 建立了一套双机共享记忆仓库。

一、共享仓库位置

• 仓库：/www/wwwroot/shared-memory.git（bare repo，位于 cgajs.com），两站均 clone 到 /www/wwwroot/shared-memory/。
• 共享文件：
  • updata.html、architecture-report.html：两站 web 根通过符号链接指向同一文件。
  • tasks.json：跨机任务清单，Kimi 会话优先读取。
  • memory.md：项目上下文、关键决策、当前焦点。
  • AGENTS.md：Kimi 双机开发指南。
  • sync.sh：一键 pull/push。

二、双机 SSH 与命令互通

• rulepackage.com → cgajs.com：ssh root@8.216.94.109 ...（已配置 migrate_key 免密）。
• cgajs.com → rulepackage.com：ssh -p 2222 root@localhost ...（通过 systemd 维护的反向 SSH tunnel，把 cgajs.com 的 2222 端口转发到 rulepackage.com 的 22 端口）。

三、使用流程

1. 每次 Kimi 登录后先执行：

   /www/wwwroot/shared-memory/sync.sh pull

2. 读取 /www/wwwroot/shared-memory/tasks.json 和 memory.md，了解当前任务与上下文。
3. 开发完成后或修改共享文件后执行：

   /www/wwwroot/shared-memory/sync.sh push

4. 需要操作另一台服务器时，直接通过上述 SSH 命令执行，无需切换终端。

四、自动兜底

• systemd 服务 shared-tunnel.service 保证反向 tunnel 断线自动重连。
• 两站均已把 updata.html 与 architecture-report.html 替换为符号链接，任何一次 sync.sh push 都会同时更新两个站点。

五、纪律

• 在 rulepackage.com 不再直接修改引擎源码（会被 cgajs.com 同步覆盖）。
• 在 cgajs.com 不再直接修改 CGA 文件仓库（会被 rulepackage.com 同步覆盖）。
• 所有跨站数据交换必须通过 API 或共享 git 仓库，禁止直接读写对方数据库。

目标：无论登录哪台服务器，Kimi 看到的任务、记忆、更新日志都是同一份，开发过程不再“断片”。

针对“哪台是主开发机、cgajs 同时改解析器是否冲突、能否在本机开发远端任务、宕机如何检测恢复、重启后如何恢复、记忆数据如何备份”等问题，输出了一份详细运维计划，待确认后开发。

• 角色：cgajs.com 是引擎主节点；rulepackage.com 是控制与资产主节点。没有唯一“主开发机”。
• 冲突避免：引擎源码只在 cgajs.com 写；CGA 资产只在 rulepackage.com 写；shared-memory 先 pull 再改。
• 远端开发：在本机通过 ssh -t root@8.216.94.109 'kimi -C' 直接开发 cgajs.com 任务。
• 宕机检测：双机每分钟互相 ping HTTP/SSH，写入 shared-memory/health/；宕机时记录 incidents 并告警。
• 重启恢复：/root/kimi-recover.sh 重启 tunnel、拉取 shared-memory、备份并清理损坏的 Kimi wire。
• 备份：shared-memory git 三副本；数据库/ golden cases / Marketplace 文件 nightly rsync；Kimi 日志异地备份，但实时 wire 不同步。

完整计划：/disaster-recovery-plan.html

当前两个站点都保留了 /omega.html 与 /omega-docs.html，但上传入口、golden case 存储与引擎对比的权威归属不同。以下是选型分析。

一、现状

二、推荐结论

Omega 测试的主入口应放在 rulepackage.com，cgajs.com 的 Omega 页面建议退化为“只读报告看板”或直接 301 跳转。

三、理由

1. 单一权威：golden case 的生成、命名、版本化、报告都在 rulepackage.com，避免 cgajs.com 也产生重复或冲突的 golden 数据。
2. 架构定义：architecture-report 明确 rulepackage.com 负责 Omega 黄金测试体系，cgajs.com 负责引擎运行与几何对比。
3. 闭环最短：rulepackage.com 完成批次后可通过 webhook 通知 cgajs.com；cgajs.com 拉取 golden cases 进入 CI 回归，流程自然。
4. 用户心智清晰：创作者去 cgajs.com IDE 写规则，QA/测试人员去 rulepackage.com Omega 上传 OBJ 并验证。
5. 避免双写风险：若两边都支持上传，同一 batch_id 可能在两台服务器产生不同目录，状态面板无法对账。

四、建议的后续动作

• cgajs.com /omega.html 移除上传 UI，改为只读报告/同步状态看板；或直接 301 到 https://www.rulepackage.com/omega.html。
• cgajs.com 保留 /api/v1/omega/health、/reports 用于监控，但关闭 /convert 写入能力（或仅内部调试使用）。
• rulepackage.com Omega 后端在对比环节优先调用 cgajs.com engine/compare；对比报告回写到 rulepackage.com。

一句话：上传 golden case 去 rulepackage.com，跑引擎对比与回归在 cgajs.com。

按“上传 golden case 去 rulepackage.com，跑引擎对比与回归在 cgajs.com”的架构建议，完成了双站 Omega 职责拆分与代码修复。

一、cgajs.com 侧调整

• /omega.html 已改为跳转页，自动跳转到 https://www.rulepackage.com/omega.html，移除上传入口。
• /api/v1/omega/convert 写入端点已禁用：环境变量 OMEGA_UPLOAD_DISABLED=1 已写入 /etc/cgajs/cgajs-api.env，调用时返回 403 并提示前往 rulepackage.com。
• 保留只读能力：/api/v1/omega/health、/reports、/report/<batchId>、/sync-to-cgajs 以及 /run-test 引擎对比端点均正常可用。

二、rulepackage.com 侧增强

• 新增 /api/v1/omega/run-test 代理端点，将前端对比请求透明转发到 cgajs.com /api/v1/omega/run-test。
• 新增 /api/v1/omega/batch/run-test 端点：读取本地 golden case，批量调用 cgajs.com 引擎执行 engine/run + geometry/compare，返回每个 case 的对比结果。
• /omega.html 结果区新增“🔬 运行对比测试”按钮，点击即可对当前批次触发 cgajs.com 引擎对比。

三、验证结果

• ✅ cgajs.com /api/v1/omega/convert 返回 403，提示使用 rulepackage.com。
• ✅ rulepackage.com /api/v1/omega/convert 仍可正常上传 OBJ 并生成 golden JSON。
• ✅ rulepackage.com /api/v1/omega/batch/run-test 成功调用 cgajs.com 引擎并返回对比结果。

根据最新约定，建立并落地以下工作流：每次修改先备份网站；每次对话与任务写入 updata.html；需要站主亲自处理的任务写入 me.html；新增页面/子站点自动加入首页菜单或导航下拉。

一、已落地的机制

二、me.html 已写入的待办任务

• ME-20260615-01 NL2CGA 独立服务形态决策（方案 A/B）
• ME-20260615-02 是否启动 Marketplace 元数据化改造
• ME-20260615-03 cgajs.com Marketplace 写入权威是否迁移到 rulepackage.com
• ME-20260615-04 确认 rulepackage.com → cgajs.com 实时同步的共享密钥
• ME-20260615-05 确认 parser ambiguity 警告的治理优先级
• ME-20260615-06 为 380 个 Marketplace UUID 文件提供/确认语义名与分类

三、导航菜单覆盖范围

• rulepackage.com：Omega、Marketplace、状态、站主待办、架构报告、灾备计划、更新日志；子站点 apihand/marketplace/pic/osm；cgajs.com 引擎入口。
• cgajs.com：IDE、CGA Library、NL2CGA、Omega、函数库、知识库、插件、文档、状态、架构报告、灾备计划、更新日志、站主待办、路线图；子站点 apihand/marketplace/pic（cgajs 与 rulepackage）。

访问地址：/me.html

对 cgajs.com 与 rulepackage.com 进行了全站 HTTP/API 健康检查、静态链接扫描、核心功能冒烟测试，修复了导航缺失问题，并完成整站备份。

一、检查范围

• 双站首页、IDE、NL2CGA、函数库、插件、管理后台、Omega、状态页、共享报告等核心页面。
• 关键 API：/api/v1/health、/api/v1/status、/api/v1/parse、/api/v1/validate、/api/v1/compile、/api/v1/cga-corpus、/api/v1/marketplace、/api/v1/omega/*。
• 静态链接扫描：cgajs.com 394 个 URL，rulepackage.com 核心页面与归档跳转。

二、发现的问题

• cgajs.com 全局导航缺失：site-nav.js 与首页未链接共享的 /architecture-report.html 和 /updata.html，用户难以找到架构报告与更新日志。
• cgajs.com 23 个页面引用旧版 site-nav.js?v=1：修改导航后可能导致浏览器缓存旧导航。
• cgajs.com /api/v1/marketplace/recent 端点不存在：但站点页面未引用该端点，不影响线上功能。

三、已执行的修复

• cgajs.com assets/site-nav.js 增加“🏛️ 架构报告”和“📋 更新日志”入口。
• cgajs.com index.html 顶部导航与页脚同步增加架构报告、更新日志链接。
• 将 cgajs.com 全站 23 处 site-nav.js?v=1 统一升级为 v=2，避免缓存旧导航。
• rulepackage.com Omega 批次完成后调用 /api/v1/omega/batch/close 异步通知 cgajs.com（已在上一轮落地）。

四、验证结果

• ✅ cgajs.com 与 rulepackage.com 核心页面全部 200。
• ✅ /api/v1/parse、/api/v1/validate 对简单 CGA 返回 success: true。
• ✅ rulepackage.com /api/v1/omega/convert 与 /api/v1/omega/batch/close 正常工作。
• ✅ 双站 /api/v1/status 引擎版本一致（1.3.2）。
• ✅ cgajs.com 首页与 site-nav.js 已出现“架构报告”“更新日志”链接。

五、备份清单

• /root/rulepackage-www-postfix-20260615-191648.tgz（18 MB）
• /root/rulepackage-api-postfix-20260615-191648.tgz（100 MB）
• /root/shared-memory-postfix-20260615-191648.tgz（1.5 MB）
• cgajs.com：/root/cgajs-www-postfix-20260615-191707.tgz（17 MB）、/root/cgajs-api-postfix-20260615-191707.tgz（405 MB）
• 数据库：rulepackage.com 已执行 backup-db.sh，dump 文件已异地同步到 cgajs.com。

cgajs.com 已完成 P0-P4 架构修复（引擎仓库干净、promote-to-prod、site-version 统一）。现在需要把 rulepackage.com 也精简到 architecture-report 定义的角色： CGA 资产与测试标尺中心。清理失去功能的菜单和页面，保留核心能力，确保稳定。

一、两站最终功能架构对比

二、需要清理的页面（归档到 /archive/，根目录放 301 跳转）

三、保留的核心页面

• index.html：rulepackage.com 首页，说明自身角色（CGA 资产 / Omega 测试 / 跨站监控）。
• omega.html / omega-docs.html：Omega 上传与文档。
• status.html：跨站状态仪表盘。
• architecture-report.html / disaster-recovery-plan.html / updata.html：共享记忆与报告。
• 404.html：保留，用于归档后的旧链接友好提示。

四、菜单精简方案

统一后的顶部菜单（site-nav.js + index.html inline nav）：

🏠 首页  |  📤 Omega测试  |  🏪 Marketplace  |  📊 状态  |  🏛️ 架构报告  |  🛡️ 容灾计划  |  📋 更新日志

五、首页 index.html 改造

• 标题改为：rulepackage.com — CGA 资产与测试中心。
• 副标题说明：这里是 CGA 文件权威仓库、Omega 黄金测试入口、双机共享记忆与状态监控中心。
• CTA 按钮：📤 上传 OBJ 测试（→ /omega.html）、🏛️ 架构报告、📊 站点状态。
• 移除“打开 IDE”等指向 cgajs.com 功能的按钮，改为清晰的跳转说明。

六、Omega 与 cgajs.com 的进一步闭环

• 在 omega_routes.py 批次处理完成后，调用 cgajs.com /api/v1/webhooks/rulepackage 或 /api/v1/omega/sync-to-cgajs，通知 cgajs.com 拉取 golden cases。
• 在 omega.html 增加提示：“需要创作/编辑 CGA？前往 cgajs.com IDE”。

七、稳定性保障措施

1. 先备份：执行前把 /www/wwwroot/www.rulepackage.com 打包到 /root/rulepackage-www-backup-<date>.tgz。
2. 先归档、后替换：旧页面移动到 /archive/，根目录放置 <meta http-equiv="refresh"> 跳转页，不直接删除，便于回滚。
3. 保留 API：不删除 cgajs-api 中的任何路由，避免 cgajs.com 调用失败；仅移除前端 HTML/菜单。
4. 不改引擎源码：/www/wwwroot/cgajs-engine/src 保持只读。
5. 验证清单：修改后 curl 检查 index/omega/status/architecture-report/updata 均 200；检查被清理页面返回 301/302 跳转。

八、实施顺序（建议）

九、已执行记录

• 备份：已打包整站到 /root/rulepackage-www-backup-20260615-184616.tgz。
• 归档：ide/IDEA/IDEB/IDEC、nl2cga、ku/cga/cga-ku、plugin、auth/billing/profile/admin/admin-monitor、help/study/timeline/roadmap/wenti/cityengine-ops 已移至 /archive/。
• 跳转：上述页面在根目录保留 meta-refresh 跳转页；IDE/函数库/NL2CGA/插件/账户跳转 cgajs.com，其余跳转架构报告。
• 导航：site-nav.js 已精简为：首页 / Omega 测试 / Marketplace / 状态 / 架构报告 / 灾备计划 / 更新日志；index.html 与 status.html、omega.html、omega-docs.html 已同步引用 v=2。
• 首页：index.html 已重写为“CGA 资产与测试中心”，保留 Marketplace/Omega/状态/架构/灾备/更新日志入口。
• Omega 闭环：新增 /api/v1/omega/batch/close，批次转换完成后异步通知 cgajs.com；cgajs-api 已重启生效。
• 验证：核心页面全部 200；归档页面均含正确跳转目标；API 与 Omega 健康检查 200。

已按确认执行 P0-P2 全部任务，两站现在具备角色边界、冲突防护、故障检测与数据备份能力。

• P0 完成：双机 SSH 别名（cga-ssh/cga-kimi/cga-test、rpk-ssh/rpk-kimi/rpk-test）；rulepackage.com 上 cgajs-engine/src 只读标记 + pre-commit hook；/root/kimi-recover.sh 双机部署；shared-tunnel.service 健康运行。
• P1 完成：watchdog.sh 每分钟互 ping HTTP/SSH，写入 shared-memory/health/*.json，连续 3 次失败写 incidents.json 与 alerts.log，支持 webhook 告警配置。
• P2 完成：
  • backup-db.sh：每日 03:00 PostgreSQL dump，同步到对端。
  • backup-files.sh：每日 02:30 同步 Omega golden cases / Marketplace 文件 / NL2CGA library。
  • backup-kimi-logs.sh：每日 01:00 同步 Kimi CLI 日志到对端。

当前双机状态均为 overall_ok: true，备份目录已相互同步。下一步 P3：shared-memory 异地镜像 + 真实故障演练。

对 cgajs.com 进行了全面扫描：引擎测试全过（68 文件 / 1285 测试），但仓库有 448 条未提交变更；API 与 NL2CGA 端点已就绪，但版本号不一致、webhook 未打通、Omega 未主动拉取。

• P0：清理提交 cgajs-engine（删除备份目录、dist-beta，重建 dist-stable，分批 commit）。
• P1：新增 scripts/promote-to-prod.sh，统一两站引擎版本与 site-version.json。
• P2：决策 NL2CGA 独立服务去留（压测内嵌端点后决定归档或启动）。
• P3：配置 RULEPACKAGE_WEBHOOK_SECRET，让 rulepackage.com 实时推送资产/Omega 事件到 cgajs.com。
• P4：CGA 语料自动索引，CgaAsset 表状态持续更新。
• P5：parser ambiguity 统计与治理，禁止新增二义性。

完整方案在 architecture-report.html 第 8 节：/architecture-report.html#cgajs-assessment

完成 CGA.js 引擎黄金标准对比测试前提出的 8 项修复计划，并同步升级 /omega.html 为批量上传工具，服务端自动保存成功 case、生成失败报告，方便后续 AI 修复。

一、引擎修复 8 项计划（全部完成）

• mirror / mirrorScope 负 scope 修复：翻转轴向并对尺寸取 Math.abs，消除负体积/负面积。
• geometry.* 硬编码常量修复：area、volume、isPlanar、isRectangular、isConcave、isClosedSurface 改为基于真实几何计算；hasTags 改为布尔语义。
• primitive / extrude 轴向量同步修复：所有 primitive 与 extrude 操作后调用 updateAxisVectors()，避免缩放/旋转错位。
• copy 真复制修复：由共享引用改为返回 [shape, cloneShape(shape)] 独立副本。
• utility 函数 SPEC 与矩阵测试补齐：覆盖 color、set、print、convert、reportError 等。
• boolean 函数 SPEC 与矩阵测试补齐：覆盖 union、subtract、intersect、offset 组合。
• setback 函数 SPEC 与矩阵测试补齐：覆盖凹多边形、退台大于尺寸、多边形孔洞等边界。
• SPEC / coverage-gap 文档同步更新：偏差与 TODO 已清理，并跑通全量测试。

二、Omega 工具 v3.2 升级

• 批量上传：支持一次拖拽/选择多个 OBJ，前端顺序调用 /api/v1/omega/convert。
• 文件名自动解析：function_param1_param2_inputshape.obj 自动识别函数、参数、输入形状。
• 8 种 footprint 预设：正方形、长方形、L 形、U 形、凹多边形、带孔洞、极小、极大。
• 服务端自动保存：成功 case 写入 /www/wwwroot/cgajs-engine/tests/golden/omega-uploads/<batch_id>/<case_id>/golden.json。
• 失败报告：同目录 report.json 记录失败文件名与错误，支持 /api/v1/omega/report/<batch_id> 读取。
• 一键复制：结果区可直接复制“批次 ID”或“失败列表”给 AI，无需手动整理。
• 精度保证：OBJ 顶点原样保留；默认对比策略 bbox+vertex + ε=1e-4，忽略 UV 与 Scope 旋转差异。

测试结果：全量 672 passed / 1 skipped；typecheck、build、signature 一致性检查全部通过。
文档：omega-docs.html 已同步更新至 v3.2。

在 /cga.html 上线 CGA 模板在线编辑器，所有 NL2CGA 模板以真实 .cga 文件形式展示，支持在线修改、自动编译校验、备份与回滚。

• 全部模板文件化：20 个预建模板从 nl2cga_service.py 迁出到 nl2cga/prebuilt/*.cga，与 23 个参数化模板统一以文件为操作对象；PREBUILT_CGA_LIBRARY 改为从 manifest.json 加载。
• 管理员写、公开读：新增 /api/v1/cga-library/* 接口，列出/读取/保存/回滚模板；写操作需要管理员权限并记录审计日志。
• 保存即编译：保存前自动备份原文件，调用 cgajs-engine 编译；编译失败立即恢复原文件并返回错误，不会入库。
• 修改可追踪：每次保存生成 backups/cga/<slug>/<timestamp>.cga，提供 diff、回滚、改动列表与全量校验功能。
• 全量资产 43 个编译通过：运行 migrate_nl2cga_assets.py 后，20 预建 + 23 参数化模板全部 success。

/cga.html 现在支持浏览和编辑 NL2CGA CGA 架构图中的全部 CGA 文件，并增加页面级密码保护。

• 密码浏览：访问 cga.html 需要输入密码 316891（仅前端校验，会话期内免重复输入）。
• 接入架构图全量库：新增 nl2cga-service/library/**/*.cga 来源，共 92 个 library 文件，与原有 43 个 NL2CGA 模板合计 135 个可编辑 CGA 文件。
• Library 编译支持 import：保存 library 文件时自动把整个 library/ 目录作为 workspace 传入引擎，使 import "../../base/roof.cga" 等相对路径正确解析。
• 多次修改与备份策略：同一文件可无限次保存，每次自动备份；每个 slug 仅保留最近 20 份备份，防止磁盘无限增长。
• 全量校验通过：/api/v1/cga-library/verify-all 对 135 个文件重新编译，全部 success。

确定“模板优先 + 本地小模型兜底”的九个月商业化路线，并完成本周当务之急：修复 NL2CGA 管道 bug、建立模板自动编译流水线、扩展 20 个预建模板、建立基准报告、评估本地 Ollama 可行性。

• 修复 nl2cga_service.py：knowledge_context 在模板引擎匹配失败分支使用前未定义，已提前初始化并保留模板引擎错误上下文供 LLM 参考。
• 模板自动编译校验流水线：新增 scripts/verify_nl2cga_assets.py，对 cga_assets 中所有 NL2CGA 资产批量编译并更新 compile_status/nl2cga_ready；scripts/migrate_nl2cga_assets.py 现在失败时返回非零退出码。
• 扩展 20 个 Tier 1 预建模板：新增 Mosque、Gothic Church、Modern Museum、Library、Gymnasium、Hospital、Hotel、Gas Station、Bus Stop；cga_assets 现有 29 个 NL2CGA 资产全部编译通过。
• 建立基准报告：新增 training/baseline_report.py，对 50 条 benchmark 跑模板匹配基线；当前模板覆盖率 16%（8/50），模板编译成功率 100%，报告保存为 training/report-v1.json。
• 本地 AI 可行性评估：确认 E5-2670V2 + 32G 内存可运行 Qwen2.5-Coder-7B（Q4_K_M 约 4.7 GB）；新增 docs/local-ai-setup.md 与 scripts/setup_local_ollama.sh。

旧版 roofHip 直接使用 footprint 的轴对齐包围盒生成矩形屋顶，导致非矩形地块（如五边形、L 形）屋顶与墙体错位。现已改为基于真实 footprint 生成屋顶。

• 矩形地块：自动检测实际四角，按真实长宽方向生成四坡屋顶，支持旋转矩形。
• 非矩形凸多边形：使用轮廓外扩（overhang）+ 中心尖顶生成贴合地块的金字塔式屋顶。
• 凹多边形 / 退化情况：回退到基于真实轮廓的金字塔屋顶，避免再生成错误的外接矩形。
• 全量引擎测试通过（440 passed），cgajs-engine 重新构建并重启 cgajs-api 服务。

按决策实施 P0+P1：建立 cga_assets 统一数据层，迁移并编译校验 NL2CGA 模板，改造服务优先读库；同步支持 Marketplace 分类字段与付费资产授权设计。

• P0 建表：新增 cga_assets、cga_category_mappings 模型与迁移；cga_files 增加 marketplace_category，cga_purchases 增加 cga_asset_id。
• P1 迁移 NL2CGA 资产：20 个预构建 + 参数化模板全部写入 cga_assets，经引擎编译校验，全部 nl2cga_ready=TRUE。
• 服务读库改造：match_prebuilt_cga() 与参数化模板引擎优先查询 cga_assets，失败时回退内存库，不影响旧接口。
• Marketplace 分类同步：上传/发布接口新增 category 字段；列表/Feed 支持 ?category= 筛选；新上传文件自动镜像到 cga_assets。
• 付费资产 NL2CGA 授权：新增 nl2cga_access_policy（free/purchase/subscription）与 nl2cga_purchase_price；实现余额扣费 + cga_purchases 记录的检查函数。
• 历史失败示例标记：后台任务正在批量编译 1077 个 Marketplace 文件，失败示例仅标记 compile_status='failed'，不下架、不删除，便于人工审阅。

上线子站点 osm.rulepackage.com，用于验证 OpenStreetMap 属性通过 JSON 导入 CGA 后批量生成建筑模型。

• 提供 50 栋示例建筑数据（含 footprint、height、levels、building、wallColor）。
• CGA 编辑器升级为一体式 CodeMirror，支持行号、语法高亮、自动补全（与 IDE 同款能力）。
• 内置 Leaflet 地图：搜索城市、框选区域、范围 100m~1000m，通过 Overpass API 下载真实 OSM 建筑数据并自动执行 CGA 生成。
• 默认 CGA 使用 import "building.json" as b 读取外部 JSON，支持 attr height = b.height 等字段绑定。
• 批量生成并发限制为 2，避免 2H8G 服务器过载；支持“仅测 5 栋”快速验证。
• 引擎 CLI / Worker 增加 workspace 解析支持，使 JSON 导入在 API 调用中可用。
• API 域名白名单支持通配符 *.rulepackage.com，CORS 同时放行所有 rulepackage.com 子域。

在 updata.html 新增“NL2CGA 与 Marketplace CGA 资产统一方案”章节，提出建立 cga_assets 统一数据层 + 编译安全门的详细实施计划，待决策后执行。

• 统一 NL2CGA 预构建模板、参数化模板、Marketplace 示例三类资产。
• 通过 nl2cga_ready 与编译校验隔离失败示例，防止污染 NL2CGA 解析与自然语言生成。
• 建议 NL2CGA 标签与 Marketplace 分类解耦，通过映射表关联。
• 给出 P0~P5 分阶段实施计划、风险应对与待决策事项。

在 updata.html 中新增“版本控制与网站修复发布流程”章节，明确引擎发版、前端热修、回滚方案、版本号记录与后续改进方向。

• 补充“引擎发版流程”与“前端/网站修复流程”两条可视化流水线。
• 明确当前生产环境无 CI/CD、无 git remote、无 staging，所有修改直接生效的风险与备份策略。
• 列出 EngineVersion、前端 git commit、nginx 配置、环境变量四类版本/配置的回滚依据。

本次对 www.rulepackage.com、marketplace.cgajs.com、apihand.cgajs.com 及引擎/NL2CGA 服务进行了静态扫描 + 人工抽查，共覆盖 376 个 HTML 文件。以下是详细检查报告与修复建议。

一、扫描统计

• 扫描 HTML 文件：376 个（含 309 个函数详情页 ku/*.html）。
• 确认死链 / 可疑链接：17 条（详见下文清单）。
• 同页重复 ID：1 处（billing.html 的 qrcode-img）。
• JS 引用缺失 DOM ID：3 处（均为 billing.html 动态创建的 pay-jump-btn，静态分析误报，但逻辑上需警惕）。
• 未设置 viewport 的页面：350 个（主要是 ku/*.html 与 docs/*.html，移动端体验差）。
• 表单缺少 action：2 处（auth.html 登录/注册表单，实际由 JS 拦截，可接受但建议保留 action="javascript:void(0)" 兜底）。

二、菜单与导航不一致（P0）

全站没有统一的导航组件，导致每个页面入口不同，用户容易迷路。

• IDE 四件套菜单不统一：
  • ide.html / IDEA.html / IDEB.html：首页 / 🏪 CGA市场 / 🐛 报告问题。
  • IDEC.html：首页 / 标准 IDE / 帮助。
  • IDEA 有 AI 切换按钮，IDEB 没有；IDEC 缺少用户下拉与发布入口。
• 公开页菜单互相“漏页”：
  • index.html 链接到 /docs/、/plugin.html、/roadmap.html，但 ku.html、nl2cga.html、study.html 都没同时覆盖这些入口。
  • ku.html 使用 /timeline.html，而 index.html 使用 /roadmap.html；两页内容高度重复。
  • nl2cga.html 的市场链接写成 /marketplace.rulepackage.com/（相对路径 404），且缺少函数库、学习文档入口。
  • study.html 顶部导航只有 IDE / NL2CGA / Admin / GitHub；侧边栏才出现 Ku、Home。
  • roadmap.html 的市场链接同样是 /marketplace.rulepackage.com/，且缺少 Updata。
  • timeline.html 有 Updata，但缺少 Study / Marketplace / Plugin。
• 用户中心/后台菜单断裂：
  • admin.html 没有返回首页或监控页链接；监控看板卡片存在却不能跳转。
  • admin-monitor.html 只有 3 个入口（总览/监控/账单），账单还指向用户端 /billing.html。
  • profile.html / billing.html 只互相链接 + IDE，缺少函数库/文档。
  • auth.html 没有任何站点导航。
• 子站点无统一导航：
  • marketplace.cgajs.com/index.html 导航只有 IDE / Profile / Login，且依赖 nginx 重定向回 www.rulepackage.com。
  • apihand.cgajs.com/index.html 完全没有跨站导航。

三、死链与路径错误（P0）

• index.html：底部“文档”链接到 /docs/，但该目录无 index.html，会 404 或暴露目录列表。
• nl2cga.html、roadmap.html：/marketplace.rulepackage.com/ 是相对路径，应改为 https://marketplace.rulepackage.com/。
• plugin.html：/pricing 不存在，出现在 Pro 版购买与激活教程两处。
• marketplace.cgajs.com/index.html：/profile.html 在子域名文件系统不存在，生产靠 nginx 跳转，但代码应显式写完整 URL。
• study.html：函数库速查表多处链接到不存在的 /ku/scope.html、/ku/geometry.top.html、/ku/setTag.html（实际文件名为 scope.*.html、geometry.top.html 不存在、tag.html）。
• omega-docs.html：链接到 /docs 同样无 index.html；正文还误写本地绝对路径 /www/wwwroot/www.cgajs.com/omega-docs.html。
• index.html：GitHub 链接仍是占位 https://github.com/yourname/cgajs-engine。
• cityengine-ops.html：页脚引用旧域名 createurban.com。

四、JS 与交互逻辑问题（P1）

• IDE / 编辑器：
  • enhance.js 仍按 CodeMirror 6 的 .cm-content 取值，但页面使用 CodeMirror 5，导致自动同步 inspector/API 导出失效。
  • IDEA.html、IDEB.html 调用 cm.getSearchCursor()，但未加载 CodeMirror searchcursor addon，会抛异常。
  • IDEC.html 调用未暴露的 window.__setWireframeMode 与 window.__ideEditor，相关按钮无响应。
  • IDEA.html 存在两个 aiAutoFix 定义，后者覆盖前者，导致侧边栏“自动修复当前代码”只是把错误复制到聊天框。
  • 功能诊断弹窗 #fd-modal-overlay 及相关函数在所有 IDE 中均为死代码，无入口触发。
• 后台 / 权限（admin.html）：
  • loadReleaseKanban() 被定义两次，第二次覆盖第一次。
  • renderReleaseCard() 调用未定义的 promoteProd()、rollbackVersion()。
  • adminLogin() 把 admin token 同时写入 cgajs_token，污染用户 token 存储。
  • logout() 只清 cgajs_admin_token，不清共享 cookie 与用户 token。
  • 多处深属性访问无空值保护（u.balance.toFixed、sys.load.join、status.production.version）。
  • renderReleaseCard() 把版本号/备份路径直接拼入 onclick，若含单引号会破化事件处理器。
• 监控页（admin-monitor.html）：
  • 未登录时只更新状态栏，不跳 /auth.html。
  • renderEndpointStats() / renderAlerts() 未转义输出，存在 XSS 风险。
  • updateGauge() 未对百分比做 0–100 截断。
• 充值页（billing.html）：
  • 同页存在两个 id="qrcode-img"（初始 img 与后续 innerHTML 插入）。
  • data.pay_url 无效时直接 return，导致支付状态文案与轮询未初始化。
  • me.balance.toFixed(2) 在 balance 缺失时会抛异常。
• 其它：
  • omega.html：复制按钮在转换失败时也会显示“已复制”；大小写校验导致 .OBJ 被拒绝；失败分支假设后端返回 JSON。
  • help.html：侧边栏全部使用 href="#"，前进/后退与 hash 定位体验差。
  • apihand.cgajs.com/index.html：showPage(id) 依赖内联事件的全局 event，不标准。

五、样式与移动端问题（P1）

• ku/*.html（309 个函数页）与 docs/*.html 全部缺少 <meta name="viewport">，手机端无法阅读。
• docs/*.html 使用浅色独立模板，与全站深色 GitHub 风格不统一，且无返回导航。
• ku/*.html 页面间 CSS 变量与版式不一致（如 --accent、max-width），说明非统一模板生成。
• nl2cga.html 使用未定义 CSS 变量：--border-hover、--red、--yellow、--blue、--green、--text-secondary。
• study.html 内联样式引用 --fg-dim，但 :root 只定义了 --fg-muted。
• study.html、marketplace.cgajs.com/index.html、apihand.cgajs.com/index.html 缺少 <link rel="icon">。

六、内容重复与数据不一致（P1）

• roadmap.html 与 timeline.html 内容高度重复，都包含 NL2CGA 开发计划时间线。
• nl2cga.html 与 study.html 在架构、能力、路线图上大量重叠。
• study.html 的“高频函数速查表”与 ku.html 职能重复。
• nl2cga.html：架构统计“83 文件 / 3,811 行”与列出的“92 文件 / ~3,656 行”不一致；目录名 religious/、agricultural/ 与实际 religious_monumental/、agricultural_rural/ 不一致。
• study.html：仍写“Beta 测试站已下线”，却又描述 Beta 构建流程；部署表写前端目录为 /www/wwwroot/www.cgajs.com/，实际为 /www/wwwroot/www.rulepackage.com/；Grammar 工作流步骤 8/9 重复 npm run build。
• apihand.cgajs.com/index.html 使用 Three.js r128 CDN，与引擎文档声明的 three@0.164.1 不一致。

七、子站点与域名问题（P1）

• marketplace.cgajs.com/index.html 实际通过 nginx 部署在 marketplace.rulepackage.com，文件路径与域名不一致。
• apihand.cgajs.com/index.html 同理部署在 apihand.rulepackage.com。
• Marketplace SPA 没有自己的 auth/profile 路由，完全依赖 nginx 重定向，SEO 与直接访问体验差。

八、修复建议（按优先级）

1. 统一导航组件：抽取一个 site-nav.js / 共用 header 片段，注入到所有页面；确保核心入口（IDE、函数库、NL2CGA、Marketplace、插件、文档、更新日志、管理后台）在每个页面都可到达。
2. 修死链：
   • /docs/ 下补 index.html（聚合 docs/*.html 与 Markdown），或把首页“文档”改为 /study.html。
   • 所有 Marketplace 链接改为 https://marketplace.rulepackage.com/。
   • 修正 study.html 函数库速查表中的错误文件名。
   • plugin.html 的 /pricing 改为 /billing.html 或创建 pricing 页。
   • 修正 GitHub 占位链接。
3. 修复 IDE JS 兼容性问题：让 enhance.js 同时支持 CodeMirror 5；补齐 CodeMirror searchcursor addon；清理 IDEC 中无效的全局调用；合并/移除 aiAutoFix 重复定义。
4. 修复 admin 逻辑缺陷：移除重复函数定义、补充缺失的 promoteProd/rollbackVersion、隔离 admin/user token、logout 清理共享 cookie、对后端字段做空值保护。
5. 修复充值/监控页：去重 qrcode-img ID、处理 pay_url 无效分支、修复 admin-monitor 的 XSS 与未登录跳转。
6. 统一模板与 viewport：为 ku/*.html 与 docs/*.html 统一生成模板并补 viewport；统一 docs 主题色；清理未定义 CSS 变量。
7. 内容去重：合并 roadmap.html / timeline.html；让 study.html 专注于架构与开发指南，函数详情引流到 ku.html；修正 nl2cga.html 的统计数字与目录名。
8. 清理废弃页面：cga-ku.html 可被 301 到 /ku.html；omega.html / omega-docs.html 如已废弃建议加 deprecation banner 或下线。

九、附录：按页面问题速查

• 问题：官方 CGA 示例中大量 setback、splitArea、splitAndSetbackPerimeter、offset、shapeL/U/O、modify、union/subtract/intersect 的块语法（如 { front : A }、{ '0.2 : ColorMe }）被解析为 StochasticBody，导致分支被忽略、失败用例增多。
• 根因：grammar 中 blockBody 把 '{' ruleBody '}' 放在 '{' paramBlockBranch ... '}' 之前，ANTLR 在歧义时优先选择 stochastic 解释，AST 生成器因此产生 StochasticBody 而非 ParamBlockBody。
• 修复：在 evaluator.ts 中新增 normalizeBlockBody()，把 StochasticBody 转换为通用的 parameter-block 分支格式（2 段 selector:body 或 3 段 length:depth:body），并在所有相关 block 操作中统一使用；splitArea / splitAndSetbackPerimeter 的 repeat 模式因此正确执行。
• IDE 补全增强：把 cgaHint 的列表项改为直接显示完整函数签名（如 extrude(distance, [world.y])），并支持对签名内容模糊过滤；重新生成 cga-autocomplete.js，升级 cga-codemirror-mode.js?v=21 / cga-autocomplete.js?v=15 缓存戳，覆盖 ide.html / IDEA.html / IDEB.html / IDEC.html。
• 验证：npm test 440/441 通过（1 skipped），其中 split-area 与 split-and-setback-perimeter 两个重点失败用例已修复；npm run build 零错误；dist-stable 已重新同步。

• 1. git commit / deploy / 修改 dist-stable 的影响
  • git commit：仅把当前修改记录到本地仓库，不会直接影响线上；可随时 git revert 或切分支回滚，是最安全的操作。
  • npm run build：生成 dist/，这是最新构建产物，但生产环境默认加载的是 dist-stable/，所以只改 dist/ 不会立即影响用户。
  • ./scripts/deploy.sh prod / 管理后台“发布到生产”：会把 dist/ 同步到 dist-stable/，同时同步前端文件（ide.html / enhance.js / ku.html 等），并可能触发 API worker 重启。这是真正影响线上用户的一步。
  • 修改 dist-stable/ 的风险：如果构建产物有隐藏 bug，所有通过 importmap 加载引擎的页面（IDE、Marketplace 预览、API）都会受影响，可能导致编译大面积失败。建议发布前确保 npm test 通过（当前仅剩 2 个已知旧基线失败），并做好全站备份。
• 2. 失败用例是否需要用新基线？
  • 当前失败的 split-area 和 split-and-setback-perimeter 是旧有实现缺陷，不是本次改动引入的回归。
  • 不建议直接改成新基线：如果把它们标记为“通过”或从 CI 中移除，会掩盖真实几何算法缺口，后续 splitArea 的 repeat 分发、perimeter split 的 segment 索引等 bug 就不会再被监控。
  • 影响：保持失败会阻止“零失败才能部署”的严格 CI 策略；建议的正确做法是继续修复底层算法，而不是降低测试标准。若短期内必须发布，可在部署脚本中明确列出这 2 个已知豁免项，而不是修改测试断言。
• 3. 为什么代码编辑器没有了自动补全功能？
  • 根因：assets/cga-codemirror-mode.js 里的静态补全数组被清空，并计划从 /cga-autocomplete.js 提供的 window.CGA_COMPLETIONS 读取；但 mode 文件实际仍使用自己的空数组，没有引用 window.CGA_COMPLETIONS。
  • 叠加问题：mode 文件在 HTML 的 <head> 中较早加载，而 cga-autocomplete.js 在页面底部加载，即使引用全局变量，mode 初始化时也拿不到数据。
  • 修复：在 cgaHint 里改为动态读取 window.CGA_COMPLETIONS || []，不再依赖加载顺序；并把 cga-codemirror-mode.js 缓存戳从 v=19 升到 v=20（ide.html / IDEA.html / IDEB.html / IDEC.html 全部更新）。
  • 效果：542 条 CGA 函数/操作/关键字/注解补全恢复，支持带说明和参数占位符的 snippet 插入。
• 4. JSON 数据绑定 import 的具体用法与影响
  • 语法：

    import "https://api.example.com/building/123.json" as data
    // 或
    import data: "./params.json"

  • 解析与绑定：引擎通过 importResolver 或全局 fetch 拉取 JSON，解析成功后把整个对象写入初始 shape 的 attributes，键名为 alias（上例即 data）。
  • 在 CGA 中使用：

    attr height = data.height
    attr wallColor = data.materials.wall
    case data.zone == "commercial" : CommercialFacade
    else : ResidentialFacade

  • 典型场景：
    • 从 GIS/ CityJSON / GeoJSON 批量读取地块属性驱动生成；
    • 前端表单把用户参数 POST 到临时 JSON URL，再交给引擎编译；
    • 风格库、材质配置、LOD 阈值等外部化，规则文件只保留逻辑。
  • 影响：彻底把“数据”和“规则”解耦；规则可以通用化，同一份 CGA 加载不同 JSON 就能生成不同城市/地块/风格；也为 NL2CGA 从知识库注入参数打通了最后一段。
• 5. 远程/版本化 import（pkg:）的具体作用与表现
  • 语法：

    import "pkg:facade@v2.1" as facade
    import "pkg:roof-kit@latest/lib/roof.cga" as roofs

  • 解析规则：pkg:id@version/path 会被映射到 {baseUrl}/api/pkg/{id}/{version}/{path}；若省略 path 则默认 index.cga；未指定 version 则默认 latest。
  • 递归加载：被 import 的 CGA 内部还可以继续 import 其他模块，引擎会递归解析并合并到同一张 AST；同时支持 alias 命名空间（facade.Main）和原始名称兼容调用。
  • 市场表现：
    • Marketplace 不再只是“示例仓库”，而变成可版本化的模块 registry；
    • 用户可以发布 屋顶库 v1.0、立面库 v2.1，其他规则按版本引用，避免“改一个库所有规则崩掉”；
    • 企业/团队可搭建私有 registry，baseUrl 指向内网地址，实现代码复用与权限隔离。
  • 与 JSON import 结合：

    import "pkg:building-config@v1" as cfg
    import "https://data.city/osm/parcel-42.json" as parcel
    
    Init -->
      extrude(parcel.height)
      color(cfg.wallColor)
      comp(f) { top: cfg.roofRule }

  • 影响：CGA.js 从“单文件脚本”升级到“模块化、版本化、数据驱动的规则生态”，与 CityEngine 桌面版相比形成 web 原生优势。

• 根因：assets/cga-codemirror-mode.js 里把静态补全数组清空后，cgaHint 实际仍在使用自己的空数组，没有读取 /cga-autocomplete.js 注入的 window.CGA_COMPLETIONS；同时 mode 文件在 <head> 中早于 autocomplete 文件加载，即便引用全局变量也拿不到数据。
• 修复：把 cgaHint 改为运行时动态读取 window.CGA_COMPLETIONS || []，不再依赖脚本加载顺序；542 条唯一补全项（函数/操作/关键字/注解）恢复，带说明与参数占位符。
• 缓存戳：cga-codemirror-mode.js?v=19 → v=20（ide.html / IDEA.html / IDEB.html / IDEC.html 全部同步），cga-autocomplete.js?v=14 保持不变。

• 为 LlmClient.chat() 增加超时/网络、HTTP 5xx、限流以及“System is too busy”类错误的指数退避重试机制（最多 3 次），提升“连接测试”在高延迟或被限流场景下的成功率
• 增强响应体错误解析：对返回 200 但 body 含 error/code/message 的异常响应进行识别，并将访问被拒绝类错误归类为 LlmAuthError
• Kimi Code API 要求请求方必须是受认可的 Coding Agent（Kimi CLI、Claude Code、Roo Code 等），因此保留 User-Agent: KimiCLI/1.5 身份标识
• Kimi Code 当前模型只接受 temperature=1.0，代码已自动对 kimi_code provider 强制使用该温度值
• 统一使用 requests.Session，改善连接复用
• 说明：Kimi Code 官方模型 ID 固定为 kimi-for-coding，后端会自动映射到最新版本（当前为 2.7），客户端无需修改 model 名称即可使用最新模型

• 清理冗余文件：删除网站根目录下的 *.bak.* 与 *.bak.latest 备份文件；保留 IDEA/IDEB/IDEC.html（help.html 仍引用这些 AI 方案入口）
• 补齐函数文档：为缺失的 52 个函数/操作自动生成 /ku/*.html 详情页（如 geometry.*、primitivePyramid、copy、instance、scatter、setback、tag 等）
• 补全签名库：在 src/functions/signatures.ts 中新增 57 条签名，覆盖 evaluator 已实现但此前缺失的操作与函数（如 NIL、convexify、setback、geometry.*、len、print 等）
• 补充冒烟测试：新增 tests/e2e/operation-smoke.test.ts，覆盖 35 个此前缺少测试的操作（Transform 别名、几何清理、offset、setback、shapeL/U/O、copy、repeat、scatter 等）
• 重新生成知识库：grammar-knowledge.json 已同步最新签名；引擎已重新构建并更新缓存戳至 v=21
• 测试全绿：407 passed | 1 skipped

• CityEngine Shape Recomposition 文档学习：完整学习官方 “Shape Recomposition: Essential Knowledge” 页面，提取 13 个 CGA 示例并全部通过回归测试
• 新增回归测试：tests/e2e/shape-recomposition.test.ts 覆盖 inline(recompose)、modify、cleanupGeometry、roofHip、布尔运算等全部文档示例
• 函数库分类重构：
  • 新增 recomposition 分类：将 modify、cleanupGeometry 归入形状重组类别
  • 将 inline、union、subtract、intersect 统一归入 boolean 分类（Rule Inlining and Boolean 3D）
  • 为 cleanupGeometry 补全签名描述与示例
• 文档自动生成：重新运行 scripts/extract-grammar-docs.mjs，grammar-knowledge.json 已同步最新分类与签名
• Marketplace 示例发布：13 个 CityEngine 形状重组示例已发布到 Marketplace（ID #1098 ~ #1110），标签 recomposition,inline,modify,cityengine-doc
• print / report 输出可视化：CGA 中的 print(...) 与 report(...) 输出现在会被收集并返回给 IDE，在 HUD 右下角新增 Console 面板实时显示
• Marketplace → IDE 联动修复：
  • ide.html 现在自动读取 ?cga_id= 参数并加载对应 CGA
  • Marketplace “在 IDE 中打开”链接修正为 https://www.rulepackage.com/ide.html?cga_id=...
• 缓存戳升级：引擎 importmap v=18、ide-core.js?v=22、enhance.js?v=prod-1.3.4

• 函数实现度全景统计：ku.html 新增顶部统计面板，实时显示 294 已完成 / 15 部分完成 / 0 未实现，支持按状态筛选
• 新增数学函数：log(x) 自然对数、round(x) 四舍五入
• 新增字符串函数：search(string, substring) 查找子串位置、strcasecmp(a, b) 不区分大小写比较
• 新增数组/转换函数：array(...) 数组构造函数
• 新增颜色函数：hsb(h, s, b) HSB 转 RGB、rgb(r, g, b) RGB 构造函数、colorConvert(color, from, to) 颜色空间转换（支持 rgb↔hsb）
• 新增 Asset 函数：assetType(path) 返回资源类型（image/model/unknown）、assetWidth/Height/Depth(path) 返回资源尺寸
• 新增文件函数：filePath(path) 返回文件路径
• 新增拓扑查询函数：topology.averageNormal(shape) 返回平均法向量、topology.connectedFaces(shape) 返回连通面组数
• 新增常量：PI (3.14159...)、E (2.71828...)，可在表达式中直接使用
• 新增 Operations：repeat(n) 重复形状 n 次、copy() 复制当前形状、instance(name) 创建命名实例
• Scope 属性全面支持：scope.sx/sy/sz/tx/ty/tz/rx/ry/rz 已可在表达式中访问
• 语法关键字状态修正：attr/const/start/extension/style/import/version/case/else/conditional/stochastic/with-params 标记为已实现（解析器层面支持）
• 注解状态修正：@Group/@Order/@Range/@Color/@Enum/@Hidden/@Locked/@Description/@Deprecated 标记为已实现（解析器层面支持）
• 部分实现函数状态更新：convert 标记为已实现（基础坐标转换）
• ku.html 重构：从静态 HTML 改为从 ku-data.json 动态加载，支持按完成状态筛选，顶部新增统计面板
• ku-data.json 数据更新：309 个函数全部录入，294 个已实现，15 个部分实现，0 个未实现

• 目录结构总览：/www/wwwroot/nl2cga-service/library/ 下共 83 个 .cga 文件，总计 3,811 行，平均 46 行/文件
• 第一层：总调度入口：main.cga（250行）— 解析 buildingType + buildingStyle 双维度路由，通过 case 分支调用对应分类的 Generate() 规则
• 第二层：全局配置层：config/ 目录含 3 个文件 — global_params.cga（全局参数/属性默认值）、lod_settings.cga（Lod0~Lod3 分级阈值）、style_mapping.cga（风格编码 → CGA 分类映射表，112行）
• 第三层：基础组件层：base/ 目录含 6 个文件 — roof.cga（5种屋顶+LOD分级，45行）、facade.cga（窗框/门廊+LOD分级，48行）、material.cga（PBR材质/纹理映射，44行）、structure.cga（柱网/梁架，35行）、decoration.cga（雕花/瓦片，35行）、utils.cga（工具函数，21行）
• 第四层：分类建筑层：8 大分类共 73 个文件 — residential 居住(33个) / commercial 商业(8个) / industrial 工业(7个) / public 公共(6个) / religious_monumental 宗教纪念(8个) / transportation 交通(7个) / agricultural_rural 农业乡村(4个) / special 特殊(4个)。每个分类暴露统一接口 Generate(floorCount, lod)
• 第五层：示例与扩展：examples/（3个场景：中式村落/欧洲城市/现代街区）+ custom/（2个用户自定义风格预留接口）
• 数据流：用户输入 → 意图识别 → main.cga 调度 → import config + base → 分类 Generate() → 调用 roof/facade/material/structure/decoration → 引擎编译器 → Three.js BufferGeometry → GLB/OBJ/JSON 输出
• 架构设计原则：分层解耦 / 统一接口 / LOD 分级 / import 链完整 / 风格映射 / 用户扩展隔离
• 现状与改进：平均 46 行/文件偏薄（框架代码为主），计划提升至 100+ 行（补充 LOD L2 细部）；base 层计划新增 lighting.cga（光照系统）和 terrain.cga（地形适配）；config 层计划新增 climate_config.cga（气候带）和 era_config.cga（时代配置）
• 详细文档：/www/wwwroot/www.rulepackage.com/docs/NL2CGA-CGA-LIBRARY-ARCHITECTURE.md（20KB，含完整目录树、层次图、数据流图、行数统计表）

• 引擎函数库深度诊断：基于 CityEngine 2025.1 官方文档与当前代码库（177+ 内置函数 / 80+ 几何操作）全面对比，识别出 8 个 P0 必须实现、10 个 P1 重要缺失、6 个 P2 中期增强 函数/操作
• P0 核心缺失：inset（多边形内偏移）、setPivotMatrix（矩阵级 pivot 控制）、writeTextFile/writeFloatTable/writeStringTable（文件写出）、geometry.angle/du/dv/uMin/uMax/vMin/vMax（修复硬编码返回值）等
• P1 重要缺失：trim（当前 no-op）、convexify（仅 2D）、alignScopeToGeometry（归零简化）、insert/i（仅 stub）、asset*Sort*（伪排序）、convert（no-op）等
• 解析器改进：补齐 StyleDecl / ExtensionDef / ImportDecl 的 AST→Evaluator 链路；增加 strictMode 错误恢复；修复多维索引 ragged array 支持；Lexer 增加 \n/\t/\uXXXX 转义
• 测试覆盖补强：当前仅 ~28 个函数有测试，~140+ 个无测试。计划分五阶段补测：Math/String/Array/Color（2周）→ Geometry Query（2周）→ File I/O（1周）→ Context（1周）→ Roof 家族（1周）
• NL2CGA 诊断：Tier 1 预建模板 11 个（无参数化）、Tier 2 参数化模板仅 9 个（全部中国古建）、知识库实体仅 8 个（全部中国宫殿）、CGA 资产库 60+ 文件但平均仅 30 行、意图识别纯关键词匹配无语义
• NL2CGA 六阶段提升方案：
  • Phase 1：参数化模板从 9→50+，覆盖全球主要建筑风格（中国/伊斯兰/哥特/巴洛克/现代/装饰艺术/日式/印度/非洲/基础设施/景观）
  • Phase 2：Tier 1 预建模板增强参数化，新增清真寺/哥特教堂/现代文化馆
  • Phase 3：知识库实体从 8→50+，覆盖全球标志性建筑
  • Phase 4：意图识别升级 Embedding 语义匹配（BGE / text-embedding-3-small）
  • Phase 5：修复规则从 10→30+，覆盖语义错误（roof 参数、comp 选择器、case 穷尽性等）
  • Phase 6：AST 直接生成（绕过文本 parse，零语法错误）
• 关键 KPI：引擎测试覆盖率 15%→85%；NL2CGA Tier 3 首次编译成功率 40-60%→70-85%；修复后成功率 60-75%→85-95%；引擎与 CityEngine 兼容度 25%→55%
• 详细报告：/www/wwwroot/www.rulepackage.com/docs/CGAJS-ENGINE-NL2CGA-ROADMAP.md（19KB 完整方案）

• 备份目录：/root/backups/cgajs_prod_20260611_043125
• 备份大小：636 MB，共 29,435 个文件
• 备份内容：
  • 前端 www.rulepackage.com（IDE、首页、文档、管理后台等全部静态文件）
  • API 后端 cgajs-api（FastAPI 路由、模型、服务、配置、训练数据）
  • 引擎 cgajs-engine（TypeScript 源码、dist/dist-stable 构建产物、测试）
  • 子站点（Marketplace / 图床 pic / API文档 apihand / NL2CGA服务 / cgajs-project）
  • Nginx 配置（sites-enabled / conf.d / nginx.conf）
  • SSL 证书（Let's Encrypt + panel 证书）
  • systemd 服务配置（cgajs-api.service 等）
• 备份习惯：每次重大修改前执行全站备份，保留历史快照，支持随时回滚

• 愿景：让程序化的力量重塑三维世界 —— 从单体建筑到完整城市，从静态模型到动态生态系统，成为生成式 3D 时代的核心基础设施
• Phase 1 — 引擎夯实期（2026 Q3，7~9月）
  • Boolean CSG 替换：引入 three-bvh-csg 或 manifold 实现真正的网格布尔运算（开窗、阳台切割不再出错）
  • Split 非 Box 裁剪完善：实现基于几何包围盒的局部坐标裁剪，旋转/复杂网格的 split 结果精确
  • Instance 实例化实现：scene-builder 中检测同材质+同几何，使用 THREE.InstancedMesh 降低 Draw Call
  • 模板引擎扩展至 50 个：覆盖全球主要建筑风格（哥特式/巴洛克/日式/伊斯兰/现代主义等）
  • AST 直接组装：跳过文本 parse 阶段，Python 层直接组装 AST 节点调用引擎，速度提升 10 倍
  • 构件库建立：柱/梁/窗/门/屋顶/栏杆等标准构件，支持组合式生成
  • Import 跨文件支持：引擎层实现 import 加载器，模块化 CGA 开发
  • IDE 实时预览：requestAnimationFrame 循环 + Stats.js + OrbitControls 相机控制
  • 目标：编译成功率 >95%，模板生成延迟 <500ms
• Phase 2 — 城市级生成（2026 Q4，10~12月）
  • LOD 四级系统：Lod0~Lod3 在 CGA 层和渲染层同时实现，根据相机距离自动切换
  • 道路网络生成：L-System 道路生长算法，主干道/次干道/支路三级网络
  • 地块划分：Voronoi 图 + 用地类型（住宅/商业/工业/绿化/公共服务）
  • 建筑批量生成：根据用地类型自动选择 CGA 规则模板，批量参数化生成
  • 植被填充：Scatter 操作 + 气候带植被库（热带/温带/寒带/沙漠）
  • 地形适配：Perlin Noise 地形生成，建筑自动贴合地形坡度
  • 水体系统：河流/湖泊/海洋生成，支持水面反射和波浪动画
  • 材质图集：自动打包纹理为图集，Draw Call 从数百降至个位数
  • 目标：场景规模从单体建筑扩展至 城市街区（~500万三角面）
• Phase 3 — 智能模拟（2027 Q1，1~3月）
  • 多智能体城市模拟：居民 Agent（行为树驱动工作/居住/购物/娱乐）、车辆 Agent（A*路径规划+流量模拟）、建筑 Agent（能耗/寿命/维护状态）
  • 时间系统：昼夜循环（光照/阴影/建筑灯光自动开关）、四季变化（植被/天气/人群）
  • 天气系统：晴/雨/雪/雾，影响光照、材质、交通流量
  • 事件系统：自然灾害（地震/洪水）、政策变化（ zoning 调整）、经济波动
  • 城市演化：建筑老化→拆除→重建，城市形态随时间自然演变
  • 资产管道完善：OBJ/GLB/FBX 导入，外部模型与 CGA 生成几何融合
  • PBR 材质库：200+ 预设材质，支持自定义导入和实时编辑
  • 目标：场景规模 完整城市（~1000万三角面），支持实时模拟
• Phase 4 — AI 深度融合（2027 Q2，4~6月）
  • NeRF 照片重建：用户上传建筑照片 → NeRF 重建 3D 模型 → 自动提取 CGA 规则参数
  • 风格迁移：将实景建筑照片风格迁移到 CGA 生成模型，一键统一城市风格
  • 虚实融合：NeRF 实景背景 + CGA 程序化前景，数字孪生基础
  • 自进化引擎：LLM 根据需求描述自动生成缺失的 CGA 函数实现，语法自动扩展
  • 自动性能优化：编译结果自动分析瓶颈 → 生成优化建议 → 自动应用
  • 训练数据自动化：每日自动从成功案例导出训练数据，触发增量 LoRA 微调
  • 目标：NL2CGA 编译成功率 >98%，无人干预的引擎自动进化
• Phase 5 — 元宇宙（2027 Q3~Q4，7~12月）
  • WebXR 支持：VR/AR 模式下沉浸式浏览生成场景，手柄交互编辑
  • WebGPU 渲染：从 WebGL 迁移至 WebGPU，性能提升 3~5 倍，支持 ~5000万三角面
  • 实时协作：多用户同时编辑同一场景，WebSocket 同步，冲突自动合并
  • 数字孪生：对接 IoT 传感器数据（温度/人流/能耗），实时更新建筑状态
  • 区块链资产：CGA 规则作为 NFT，交易市场支持版权追踪和收益分配
  • 云端渲染：复杂场景云端光追渲染，前端流式传输
  • UGC 生态：用户创作 CGA 规则 → Marketplace 交易 → 游戏/影视/城市规划使用
  • 目标：构建完整的 程序化 3D 元宇宙 生态
• 关键技术指标演进

  指标	当前	Phase 1	Phase 2	Phase 3	Phase 5
  编译成功率	~85%	>95%	>95%	>95%	>98%
  生成延迟	3~5s	<500ms	<1s	<1s	<500ms
  场景规模	单体建筑	单体建筑	城市街区	完整城市	元宇宙城市
  三角面数	~50万	~100万	~500万	~1000万	~5000万
  FPS	~30	~60	~30	~30	~60 (WebGPU)
  自动化	人工驱动	半自动	自动	智能	自治

• 详细报告：完整架构分析 + 发展规划已保存至 /www/wwwroot/www.rulepackage.com/docs/CGAJS-ARCHITECTURE-REPORT.md

• 顶部导航清理：移除失效的「函数库」和「知识库」导航链接，当前仅保留「首页」「CGA 市场」「报告问题」三个入口
• CGA 市场从下拉改为模态窗口：点击「🏪 CGA 市场」按钮后弹出居中模态窗口（而非顶部下拉面板），含搜索框 + 结果列表 + 前往 Marketplace 链接，点击外部或 × 关闭
• 编辑器/AI/市场三独立：编辑器保持中间左侧、AI 生成保持右侧边栏、CGA 市场为独立弹窗，三者不再挤在同一个标签面板内
• 检查器移除 LotSize：Inspector 面板去掉「地块尺寸 (Lot Size)」区块（含 X/Z 滑块和 10m/50m/100m 预设按钮），该功能已由 @LotSize 自声明机制替代
• 缓存清除：inspector-enhance.js 版本号从 v=prod-1.3.2 升级到 v=prod-1.3.3，强制浏览器加载最新版本
• 备份：ide.html / enhance.js / inspector-enhance.js 均已备份（时间戳 1781122073）

• 8 大建筑分类，92 个 .cga 文件：
  • base/ 6 个 — 屋顶/立面/结构/材质/装饰/工具（LOD 集中控制层）
  • config/ 3 个 — 全局参数 / LOD 设置 / 风格映射常量表（共 60+ 常量）
  • residential/ 33 个 — 亚洲传统(5) + 欧洲传统(10) + 美洲传统(8) + 现代当代(10)
  • public/ 6 个 — 教育/医疗/文化/体育/会展/行政
  • commercial/ 8 个 — 零售(3) + 酒店度假(2) + 餐饮/金融/服务
  • industrial/ 7 个 — 重工业/轻工业/高新技术/仓库/物流/堆场/能源
  • transportation/ 7 个 — 公路/铁路/地铁/停车/桥梁/港口/机场
  • religious_monumental/ 8 个 — 基督教/伊斯兰教/佛教/道教/印度教/犹太教/锡克教/纪念性
  • agricultural_rural/ 4 个 — 种植/养殖/加工/乡村公共
  • special/ 4 个 — 军事/娱乐/应急/市政
  • custom/ 2 个 — 用户自定义风格占位
  • examples/ 3 个 — 中式村落/欧洲街区/现代商务区
• main.cga 总调度入口（248 行）：按 buildingType + buildingStyle 自动路由到对应分类规则，统一对外接口 Generate(floorCount, lod)
• LOD 集中控制设计：L0/L1/L2 三级精度仅在 base/roof.cga 和 base/facade.cga 中实现，上层分类规则只覆盖风格参数（roofAngle / wallColor / windowWidth），不写 LOD 逻辑
• 风格参数化：每个 .cga 文件顶部定义 attr 风格参数，支持前端 UI 动态调整或 GIS 批量导入
• 关键发现：引擎 evaluator 当前不支持 import 跨文件规则调用（parser 已解析 import 声明，但 evaluator 未加载被 import 的文件）。短期通过 NL2CGA Python 层内联组装解决，中期需在引擎层实现 import 加载器
• 代码位置：/www/wwwroot/nl2cga-service/library/

• 三层生成架构：
  • Layer 1 模板引擎：常见建筑直接匹配模板，AST 组装生成，0轮LLM调用，精度100%
  • Layer 2 结构化组装（未来）：从构件库组合，跳过文本parse阶段
  • Layer 3 LLM辅助：创意建筑兜底，Prompt注入白名单函数约束
• 5个参数化模板：
  • 太和殿（重檐庑殿顶）— 11个参数：面阔/进深/坡度/柱网/颜色
  • 天安门（重檐歇山顶）— 6个参数
  • 六角亭（攒尖顶）— 5个参数
  • 牌坊（牌楼）— 5个参数
  • 城墙 — 4个参数
• 编译验证闭环：生成 → 编译 → 错误 → 自动修复 → 再验证，最多3轮
• NL2CGA 集成：用户说"生成太和殿" → 模板引擎匹配 → 0ms生成 → 编译通过 → 输出代码，不经过LLM
• 速度对比：模板引擎 100ms vs LLM 3-5s，快30-50倍
• 代码位置：/www/wwwroot/cgajs-api/nl2cga/template_engine/

• 去掉手动调节：移除 Inspector 地块尺寸滑块，用户不再需要手动猜地块大小
• CGA 自声明机制：代码第一行添加 # @LotSize(宽, 深)，IDE 编译前自动解析并设置初始 shape
• 示例已更新：所有标准示例均加入 @LotSize 声明
  • 柱子/柱础 → @LotSize(2, 2)
  • 斗拱 → @LotSize(3, 3)
  • 庑殿顶/歇山顶 → @LotSize(17, 13)
  • 太和殿 → @LotSize(64, 37)
• NL2CGA 自动生成：Prompt 已更新，LLM 生成时会根据建筑实体库的 recommended_lot 自动加入 @LotSize
• 向后兼容：没有 @LotSize 的代码仍使用默认 10×10m 地块

• union 去重优化：合并几何时启用顶点焊接（tolerance=0.001），消除重复顶点，减少面数
• subtract 精确化：从重心测试升级为顶点级包围盒测试（全部在内→剔除/全部在外→保留/部分重叠→保留），大幅减少误删
• intersect 保持：Sutherland-Hodgman 多边形裁剪，精度中等，已满足基本需求
• inline 支持：append（默认）/ unify / recompose 三种合并策略
• 5个标准古建示例已发布到 CGA 市场：
  • #1084 标准柱子 — 圆柱+方形柱础，参数化柱高/柱径/颜色
  • #1085 标准柱础 — 方形底座+圆形鼓镜+方形覆盆三层
  • #1086 标准斗拱 — 坐斗+三层交错出跳拱+散斗
  • #1087 重檐庑殿顶 — 四坡五脊，下檐+上檐两层 roofHip
  • #1088 重檐歇山顶 — 四面坡+山面三角形山花
• 示例代码位置：/www/wwwroot/www.cgajs.com/assets/examples-standard/（01-column.cga ~ 05-gable-roof-double.cga）
• 稳定性：npm test 19/19 文件通过，374/374 测试通过

• 地块尺寸控制面板：IDE Inspector 面板新增"地块尺寸(Lot Size)"区域，含 X/Z 方向滑块（5-200m）和 10m/50m/100m 一键预设按钮。调节后自动触发重新编译
• 默认地块扩展：原 createScope(0,0,0,0,0,0,10,1,10)（10×10m）改为通过 window.__lotSize 全局变量控制，支持任意尺寸地块
• 太和殿地块适配：CGA 代码中加入 scale_factor = min(scope.sx/64, scope.sz/37, 1.0) 自动缩放，小地块也能生成比例正确的太和殿（但会提示"效果会失真"）
• 建筑实体库地块要求：8个实体均加入 min_lot_size 和 recommended_lot。太和殿：最小 50m×30m，推荐 64m×37m
• NL2CGA Prompt 注入地块警告：知识检索器现在输出 "⚠ 重要：太和殿需要至少 50m × 30m 的地块，否则柱网比例会失真"，大模型生成时会被告知地块要求
• 文件位置：
  • 完整LOD版：https://rulepackage.com/assets/private-examples/taihe-palace-lod.cga
  • 简化适配版：https://rulepackage.com/assets/private-examples/taihe-palace-lod-minimal.cga（294行，含LOD+地块缩放）

• 太和殿面数预估：高精度（Lod3）约 146万三角面，远超引擎50万面流畅阈值。瓦片占55.9%（91万面）、斗拱占25.5%（42万面）是两大瓶颈
• LOD四级精度体系：
  • Lod0 极远鸟瞰：~4.7万面，方块柱+纯色屋顶，Draw Call ~47
  • Lod1 城市级：~14万面，6面柱+贴图瓦片，Draw Call ~142
  • Lod2 街区级：~75万面，10面柱+简化瓦片，Draw Call ~751
  • Lod3 特写级：~146万面，16面柱+完整瓦片+斗拱，Draw Call ~1,458
• CGA层LOD控制：taihe-palace-lod.cga 新增 @Enum("Lod0","Lod1","Lod2","Lod3") attr lodstep，通过 column_facenum / tile_density / has_dougong 等LOD驱动常量，在代码层面控制几何精度
• 渲染器FPS监控：ide-core.js?v=19 新增性能面板（左上角），实时显示：
  • FPS 帧率
  • Mesh 数量
  • 三角面数（K为单位）
  • 当前LOD级别
  • 自动建议（⚠ FPS<25持续3秒建议降级 / ▲ FPS>50持续5秒建议升级）
• 自动LOD逻辑：渲染器每帧统计FPS，维护10秒历史窗口。低FPS持续触发降级建议，高FPS持续触发升级建议，用户可在Attributes面板手动调整 lodstep 参数
• 面数瓶颈分析：瓦片随机颜色（rand()）导致无法按材质合并Mesh，是Draw Call飙升的主因。Lod1用贴图替代几何瓦片可解决此问题
• LOD模板：lod-control-template.cga 提供通用LOD控制代码片段，可复制到任意建筑CGA中使用

• NL2CGA增强架构：从"直接丢给大模型"升级为"意图识别 → 知识检索 → Prompt注入 → 大模型生成 → 编译器验证"五级流水线
• 意图识别器：intent_router.py 支持5类意图：generic（通用）/ entity（建筑实体）/ pattern（CGA模式）/ fix（报错修复）/ explain（解释询问）。实体关键词覆盖太和殿/角楼/千秋亭/保和殿/中和殿/紫禁城/城墙/瓦片等
• 知识检索器：knowledge_retriever.py 检索3层知识库：
  • 建筑实体库（8个实体：柱网比例、屋顶层数、关键函数、推荐参数）
  • CGA模式库（11大模式：柱网/重檐/歇山/斗拱/F形网格等）
  • RAG向量索引（361代码片段，本地TF-IDF检索）
• Prompt组装器：prompt_assembler.py 自动将检索到的实体信息、模式模板、RAG代码片段注入System Prompt，大模型生成时拥有"太和殿是67×31柱网、三层roofHip嵌套"等精确知识
• API集成：nl2cga_service.py 在RAG检索后新增步骤2.5（私有知识库检索），已集成到 POST /api/v1/nl2cga/generate 主流程，语法验证通过
• 建筑实体库：building-entities.json 定义8个实体：
  • 太和殿（67×31柱网，重檐庑殿顶，3层屋顶）
  • 角楼（F形十字布局，十字脊重檐）
  • 千秋亭（圆形攒尖顶，递归屋顶）
  • 保和殿（53×25柱网，歇山顶，LOD四级）
  • 中和殿（31×31柱网，攒尖顶，斗拱系统）
  • 宫殿城市布局（setback+splitArea+innerRectangle）
  • 城墙系统（墙垛+城门楼+马道）
  • 瓦片系统（高精度瓦片+随机颜色）
• 注释与知识库更新机制：
  • ✅ 注释越清楚，RAG检索准确率越高（注释是TF-IDF检索的核心文本）
  • ⚠️ 当前不会自动更新：RAG索引是静态文件，代码内容相同但注释更新后，需要手动运行 build_rag_index.py 重建索引
  • 📝 建议流程：更新注释 → 运行重建脚本 → 验证新索引包含新注释
• 效果示例：用户说"生成太和殿" → 意图识别为ENTITY → 检索到"67×31柱网、base_roof_angle=27、三层roofHip" → Prompt注入 → 大模型生成精确代码

• 解析层：evaluator.ts 中 94 个唯一 simple operation（103 个 case label，含 9 组大小写别名）全部有实现或别名映射，无空占位
• 内置函数层：builtins.ts + 12 类插件共注册 163 个 built-in 函数（math 29、asset 22、string 20、array 17、list 16、color 15、file 13、context 9、conversion 9、misc 7、probability 2 等）
• 测试通过率：
  • 函数契约测试 64/64 通过，100%（A级 12/12、B级 27/27、C级 25/25）
  • 函数基础审计 82/82 通过，100%（0 parse failed、0 runtime crashed）
• 核心选择器：comp() 支持 8 个选择器 — f e v fe fv g m h top
• 全功能可用函数（约 60+）：extrude、s/t/r、translate/scale/rotate、rotateScope、center、mirror、primitiveCube/Sphere/Cylinder/Cone/Disk/Quad/Pyramid、roofGable/Hip/Pyramid/Ridge/Shed/Radial/Dutch/Gambrel/HalfHip/Round、comp(f/e/v/fe/fv/g/m/h/top)、split、setback、setbackPerEdge、setbackToArea、innerRectangle、splitAndSetbackPerimeter、color、texture、setupProjection、projectUV、rotateUV/scaleUV/translateUV/tileUV/deleteUV/normalizeUV/copyUV、tag/untag/label、union/subtract/intersect、print/report/assert 等
• 部分实现 / 简化函数（约 15~20）：
  • insert / i：有解析分发，但未完整接入 OBJ/gltf 资产加载管线
  • scatter / search：基础 case 存在，算法较简化
  • shapeL / shapeU / shapeO / modify / offset / envelope：有实现，但与 CityEngine 完整行为存在差距
  • geometry.* 部分属性：isConcave/nHoles/isPlanar/hasTags 等多为 fallback 默认值，未做真实几何分析
• 与 CityEngine 对比：CityEngine 约 200+ operations + 150+ functions；当前核心建筑生成能力（extrude/split/comp/roof/transform/material）覆盖度约 70~80%，全功能可用率约 30%，解析覆盖率约 45%
• 结论：常用建筑生成函数基本齐全，可支撑 NL2CGA 生成标准中式/现代建筑；资产插入、高级几何修改、上下文感知、LOD/报告类函数仍是后续重点补齐方向

• CityEngine 文档爬取：成功获取 220 个官方文档页面列表，对比分析后确认核心函数覆盖率 > 95%
• 新增 isnull 函数：空值检查函数 isnull(value) → 1/0，注册于 builtins.ts
• 新增 10 个函数别名：projectUv/rotateUv/scaleUv/tileUv/translateUv/deleteUv/insertAlongUv/alignScopeToGeometryBox/normalizeUv/copyUv → 对应驼峰命名，兼容 CityEngine 大小写不敏感风格
• Marketplace 批量发布：18 个新 CGA 示例（ID #1066~#1083），含纹理 UV 操作、primitives、transformations、shapeU、roofs、materials、offset、stochastic、repeat 等教程
• 引擎构建：npm run build 零错误，dist 已同步到 dist-stable，ide.html importmap v=18

• 全站备份：351MB 完整备份（含 PostgreSQL dump 1.6MB + SQLite + SSL 证书 + Nginx 配置 + systemd）
• 性能检测：API 响应 50-100ms，内存 46-108MB，磁盘 42%，并发 20 请求 ~1s/次，无异常日志
• 新增 14 个 CityEngine 兼容函数：assert(condition, msg)、flatten(y)、geometry.area、geometry.volume、geometry.height、geometry.boundaryLength、geometry.nFaces、geometry.nEdges、geometry.nVertices、geometry.isPlanar、geometry.isRectangular、geometry.hasTags、geometry.hasUVs
• Marketplace 新发布：ID #1065「CityEngine 官方风格商业大厦 (10层)」— 展示 assert + geometry.area + 完整 split(y) 楼层分割
• 本地贴图上传功能：✅ 已完成 — Attributes 面板 texture() 参数旁添加 📤 上传按钮，支持点击选择和拖拽上传，上传后自动替换 CodeMirror 中的 URL

• 根因：computeMergedFaceScope 使用最长边界边作为 xAxis。建筑侧面最长边是高度（120），导致 comp(f) 后 scope.x = 高度、scope.y = 长度/宽度
• 后果：用户写 split(y) 期望沿高度分楼层，实际沿水平方向分割；setupProjection(0, scope.xy) 投影平面错误 → 两个对面贴图正确、另两个对面拉伸
• 修复：垂直面（法向量接近水平）优先使用世界水平方向（x/z 轴）作为 xAxis，yAxis 保持垂直方向。所有侧面 scope.y = 高度，split(y) 统一沿高度分割
• 验证：npm test 374/374 全过，已部署 dist-stable?v=5

• 贴图透明/不显示修复：scene-builder.ts 中 setIndex(Float32BufferAttribute) → setIndex(Uint32BufferAttribute)，index buffer 类型错误导致三角面索引解析失败，面片错乱/消失
• 纹理颜色空间修复：ide-core.js 添加 renderer.outputColorSpace = THREE.SRGBColorSpace，纹理颜色从暗淡恢复为正常
• SSL 统一证书：rulepackage-com-unified 证书覆盖 rulepackage.com + www/api/marketplace/pic/beta/vip/apihand 共 8 个域名，自动续期
• Marketplace 外部贴图替换：6 个文件中的 raw.githubusercontent.com / images.unsplash.com 链接全部替换为 pic.rulepackage.com
• 构建验证：npm test 374/374 全过，npm run build 零错误

• pic.rulepackage.com SSL 证书：Let's Encrypt 申请成功，HTTPS 正常访问，CORS 跨域头已配置
• Marketplace 发布：ID #1064「现代商业办公楼 (纹理贴图示例)」— 使用 pic.rulepackage.com 6 种贴图（红砖/石材/玻璃/金属/屋顶瓦片/混凝土），展示完整 setupProjection + projectUV + texture 工作流
• roadmap.html 更新：Phase 1/2/2.5 标记完成，新增 Phase 5「渲染器性能与材质系统」8 项任务看板
• 渲染器承载数据：优化前 ~1000 Mesh @ 60fps → 优化后 ~50万三角面 @ 60fps

• 新建贴图站点：https://pic.rulepackage.com — 11 种测试材质（混凝土/砖/木/金属/玻璃/草地/石材/屋顶瓦片），支持 CORS 跨域
• 渲染器性能瓶颈修复：原 buildScene() 为每个 shape 创建独立 Mesh → 24638 三角面分布在 ~8000+ draw call 中严重卡顿
• 按材质自动合并：相同材质（颜色+粗糙度+金属度+纹理）的 shape 自动合并为单个 BufferGeometry，draw call 从 ~8000 降至 ~10
• 承载能力提升：优化前 ~1000 独立 Mesh @ 60fps → 优化后 ~500000 三角面 @ 60fps
• cleanupGeometry 等效实现：无需在 CGA 代码中手动调用，buildScene 层自动完成共面合并
• 构建验证：npm test 374/374 全过，npm run build 零错误，已同步到 dist-stable

• 故障现象：CodeMirror 编辑器无代码显示、3D 渲染窗口黑屏无模型
• 根因：Phase 2 重构时 plugins/context/index.ts 引用了未定义的 getShapeAABB / aabbContains / aabbOverlaps / aabbTouches；plugins/asset/index.ts 引用了未定义的 _assetMetaCache
• Vite 行为：esbuild 报 TS2304 错误但仍继续构建，导致 CONTEXT_FUNCTIONS 变量在产物中缺失，浏览器加载抛出 ReferenceError: CONTEXT_FUNCTIONS is not defined
• 连锁效应：ide-core.js 为 ES 模块，顶层 import 'cgajs-engine' 失败导致整个脚本不执行 → CodeMirror 和 Three.js 均不初始化
• 修复：补充 context 插件 AABB 辅助函数、补充 asset 插件 _assetMetaCache Map，重建后 npm run build 零错误
• 验证：Node.js 模块加载测试通过，dist-stable 已同步，importmap 添加 ?v=2 缓存清除
• 操作：请按 Ctrl+F5 强制刷新浏览器缓存

• 开发计划来源：插件式函数库 + 快速修复系统（dazzler-gamora-rictor.md）
• 新增后端端点：POST /api/v1/nl2cga/diagnose-function — 函数诊断（返回当前实现、测试覆盖率、已知问题）
• 新增后端端点：POST /api/v1/nl2cga/submit-function-fix — 提交修复（保存到 FunctionRepairLog + Nl2CgaHumanFix）
• 前端 AI 面板新增 "🔧 函数诊断" 模态框：搜索函数 → 显示源码 → 在线编辑 → 快速测试 → 提交修复
• MVP 约束：仅支持 builtins（162 个函数），evaluator 操作修复放到 Phase 3
• 备份目录：/root/backups/cgajs_prod_20260609_172916

• 新建目录结构：src/functions/plugins/{math,probability,array,string,conversion,color,list,file,context,edge,asset,misc,topology,user}/ — 13 个插件目录
• 拆分 builtins.ts：原 1243 行集中式文件 → 13 个独立插件文件。每个类别一个插件：MATH(27函数)、PROBABILITY(4函数)、ARRAY(16函数)、STRING(19函数)、COLOR(13函数)、CONVERSION(8函数)、CONTEXT(8函数)、EDGE_ATTR(7函数)、ASSET(5函数)、FILE(16函数)、MISC(12函数)
• 新建 registry.ts：全局插件注册表，支持 registerPlugin()、loadPlugin()（运行时加载用户插件）、unloadPlugin()、getPluginFunctions()
• 提取共享模块： core/random-state.ts — currentRandom/setCurrentRandom/getCurrentRandom/ensureRandom，避免 probability/list 插件与 builtins.ts 循环依赖； core/context-shapes.ts — _contextShapes/setContextShapes，避免 context/edge 插件循环依赖； plugins/file/virtual-files.ts — _virtualFileRegistry/registerVirtualFile/clearVirtualFiles
• builtins.ts 重构为聚合文件：保留 callBuiltin()、BUILTIN_REGISTRY、ALL_BUILTINS、类型定义等核心基础设施，所有函数类别改为从插件目录 import
• 向后兼容：所有现有 import 路径不变，callBuiltin(name, args) 接口不变，旧代码零改动
• 验证：npm run build 零错误通过；npm test 19/19 测试文件通过，374/374 测试通过；dist 已同步到 dist-stable

• 决策：Phase 3 暂停，优先完成 Phase 2.5（参数类型系统扩展到更多函数族）+ Phase 2（插件式目录重构）
• Phase 2 目标：将 builtins.ts（1243行，162个函数）按类别拆分到 src/functions/plugins/ 目录，实现热插拔插件架构
• Phase 2.5 扩展目标：在拆分到插件的同时，为每个函数补充完整签名元数据（参数名、类型、枚举值、默认值）
• 关键约束：① callBuiltin() 接口不变；② BUILTIN_REGISTRY 不变；③ 374测试全部通过；④ 向后兼容旧调用方式
• 执行顺序：设计目录结构 → 逐个类别迁移（math → array → string → color → geometry → probability → file）→ 创建 registry.ts → 验证构建 + 测试
• 备份目录：/root/backups/cgajs_prod_20260609_183706

• 结论：Phase 3 对生产稳定性影响较大，不建议直接在 prod 上执行
• 核心原因：evaluator.ts（1785行）是引擎心脏，60+个操作全部从 switch/case 拆到独立文件。每个操作都直接依赖 EvalContext：ctx.random（确定性随机）、ctx.userFuncs（用户函数）、ctx.script（规则查找）、ctx.currentDepth/maxDepth（递归深度控制）、ctx.traceLog（调试追踪）。拆出后任何一项传递错误都会导致编译失败。
• 具体风险点： ① setCurrentRandom(ctx.random) 在每个操作前调用，拆出后极易遗漏 → 随机结果错乱； ② BlockOperation（comp/split/setback）分支逻辑复杂，迁移容易出错 → 孔洞/面拆分异常； ③ 规则调用时的 ctx.currentDepth++ 和 random fork，拆出后逻辑可能断裂 → 无限递归或随机不一致； ④ 操作链依赖（extrude→comp→split→roofHip）一个错全链失败，374单元测试可能覆盖不了边界case
• 生产影响：cgajs-api 有 12 个常驻 engine_worker 进程，每个编译请求都经过 evaluate()。如果引擎构建产物有 bug，所有编译请求全部失败，网站核心功能瘫痪。
• 建议方案： ❌ 禁止直接修改 prod evaluator.ts； ✅ 必须在 beta 分支完成，374测试全过 + 额外操作链集成测试后再部署； ✅ 分批次迁移：第一批 10 个简单操作（color/texture/translate/rotate）→ 第二批中等复杂度（extrude/primitive*）→ 第三批复杂操作（comp/split/setback/roof）； ✅ 每批次独立构建 + 测试 + beta 验证，通过后再下一批。

• 新增文件：cgajs-engine/src/functions/signatures.ts — 函数签名元数据类型系统，定义 CGAFunctionSignature / CGAParameter 接口，含参数名、类型、枚举值、默认值、可选性、描述
• 修改 roof.ts：9 个 roof 函数全部新增 valueType: RoofValueType = 'byAngle' 参数；新增 resolveRoofAngle() 辅助函数，将 byHeight 按 footprint 半宽自动转换为等效角度
• 修改 evaluator.ts：9 个 roof case 全部支持新旧签名自动识别——如果 argVals[0] 是字符串 byAngle/byHeight 按新签名解析，否则回退旧签名（完全向后兼容）
• 修改 cga-autocomplete.js：roof 系列 9 个函数补全提示全部更新为含 valueType 的新签名；新增 roofGambrel、roofHalfHip 补全条目
• 修改 grammar-knowledge.json：9 个 roof operation 的参数元数据已更新，含 enumValues、optional、example
• 构建验证：npm run build 零错误通过；dist 已同步到 dist-stable
• 编译测试： roofHip(30, 1)（旧签名）✅、 roofHip("byAngle", 30, 1, false) ✅、 roofHip("byHeight", 5, 1, false) ✅ 全部编译通过

• 目标：建立函数签名元数据，让解析器、补全系统、运行时实现三层对齐 CityEngine 2025.1
• 首批修复范围：roof 系列 9 个函数（roofHip/roofGable/roofPyramid/roofShed/roofRidge/roofRadial/roofDutch/roofGambrel/roofHalfHip）
• 签名元数据格式：src/functions/signatures.ts — 定义参数名、类型、枚举值、默认值、是否可选
• 修改文件清单：evaluator.ts（增加 valueType 分支）、roof.ts（支持 byAngle/byHeight）、grammar-knowledge.json（参数类型注入）、cga-autocomplete.js（补全提示更新）
• 备份目录：/root/backups/cgajs_prod_20260609_181534

• 问题发现：以 roofHip 为例，cgajs 当前签名 roofHip(angle, overhang)（2参数），CityEngine 2025.1 官方签名 roofHip(valueType, value, overhang, even)（4参数），缺少 valueType ∈ {byAngle, byHeight} 枚举参数
• 根因定位： cga-autocomplete.js 硬编码签名 roofHip(${1:angle}, ${2:overhang})； grammar-knowledge.json 参数名为 arg1/arg2 无类型信息； evaluator.ts switch/case 直接按位置取值 argVals[0], argVals[1]，无 valueType 分支； 底层 roof.ts 实现同样只接受 angle+overhang
• 影响范围：不仅 roof 系列（roofGable/roofPyramid/roofShed 等均有类似缺失），大量函数的参数类型、枚举值、默认值均未与 CityEngine 2025.1 对齐。这导致：① 代码补全误导用户；② NL2CGA 生成的代码使用错误签名直接编译失败；③ 用户无法使用 byHeight 等高级参数模式
• Phase 2 影响评估： 若仅做目录重构（builtins.ts → plugins/）→ 影响很小，callBuiltin + BUILTIN_REGISTRY 接口不变，374测试可守护兼容性； 但若同时引入参数类型系统 → 影响中等，需在 parser / evaluator / autocomplete / grammar-knowledge 四层联动修改
• 建议执行顺序：Phase 2.5 参数类型系统（先建立签名元数据，修复 roof 等函数实现）→ Phase 2 目录重构（再拆分到插件目录，避免二次重写）→ Phase 3 Evaluator插件化
• roadmap.html 已更新：新增「架构升级路线图」类别，含 Phase 1~4 共 22 项任务看板

• 后端 POST /api/v1/nl2cga/diagnose-function — 从 builtins.ts 提取函数源码、查询修复历史、返回语法知识，已验证通过（abs / rand 等函数正常返回）
• 后端 POST /api/v1/nl2cga/submit-function-fix — 保存修复到 FunctionRepairLog 表，已验证通过（id=5 记录成功入库）
• 前端 IDE AI 面板新增 "🔧 函数诊断与修复" 按钮，点击打开模态框
• 模态框功能：搜索函数 → 显示当前实现源码 + 行号 → 展示已知修复记录 → 在线编辑修复代码 → 填写修复说明 + 测试用例 → 提交保存
• 涉及文件：main.py（+2端点）、nl2cga_service.py（诊断逻辑）、ide.html（CSS+HTML+JS）
• 服务已重启，4 workers 运行正常，内存 177MB

• 修复 uvicorn main:app 启动失败问题，根因：monitoring.py 引入 prometheus_client 和 psutil 但未安装
• 安装缺失依赖后服务恢复正常，4 workers 运行中，内存 169MB
• 所有 NL2CGA 端点验证通过：health / styles / repairs / generate

• export_training_data.py — 从数据库导出训练数据（成功案例+反馈数据）
• train_lora.py — LoRA 微调脚本，基于 unsloth 框架，支持 4bit QLoRA，结构完整（数据量不足时自动跳过）
• evaluate.py — 4 维度评估：编译成功率、BLEU/ROUGE-L、函数正确率、语法完整性
• benchmark.jsonl — 50 样本基准数据集，覆盖 13 种建筑风格，100% 编译通过

• 新增 FunctionRepairLog 数据库表，记录函数修复历史（function_name, file_path, repair_summary, before/after_snippet, test_case）
• NL2CGA Prompt 自动注入最近 7 天/最多 10 条修复记录，让 LLM 了解引擎最新变更
• 前端 IDE 底部展示近期修复列表（GET /api/v1/nl2cga/repairs）
• 已入库 4 条记录：roofGambrel、roofHalfHip、roofRound、compHoles
• 自动捕获脚本：编译失败后自动记录错误上下文到修复队列

• admin-monitor.html — 实时仪表盘：QPS、编译成功率、NL2CGA 调用量、用户活跃度、资源监控
• log_analyzer.py — 每日自动分析 access_log，生成日报（请求量、状态码分布、Top 端点、错误聚类）
• resource_alert.py — CPU/内存/磁盘阈值告警，自动通知
• 数据飞轮自动化：编译失败自动入队、每小时自动测试、每 6 小时高频案例 AI 修复

• callBuiltin 从 O(n) if-else 链重构为 O(1) Map.get() 查找
• BUILTIN_REGISTRY: Map<string, Function> 扁平注册表，分类：MATH(24)、PROBABILITY(4)、ARRAY(16)、STRING(19)、COLOR(13)、CONVERSION(8)、CONTEXT(8)、EDGE_ATTR(7)、ASSET(5)、FILE(16)、TOPOLOGY(2)、MISC(12)
• 保留 ALL_BUILTINS 对象向后兼容
• 验证：TypeScript 编译零错误，374 个现有测试全部通过

• 新增 DeterministicRandom(seed) 基于 xorshift 的确定性随机数生成器
• setCurrentRandom() / getCurrentRandom() 线程本地存储
• EvalContext 新增 random 字段，createEvalContext 中初始化
• 分支间随机隔离：evalStochasticBody 和 evalSplitOperation / evalCompOperation 中使用 ctx.random.fork()
• rand / rand.int / rand.gaussian / p 全部接入
• 验证：相同 seed 产生完全相同的随机序列；374 个现有测试全部通过

• nl2cga_service.py (907 行) 从 createurban-cga-lite 移植，7 个 API 端点
• /api/v1/nl2cga/generate — 预建模板匹配（免认证）+ LLM 生成（需认证）
• /api/v1/nl2cga/refine — 基于 LLM 的代码优化
• /api/v1/nl2cga/fix — 自动修复编译错误
• /api/v1/nl2cga/explain — 代码解释（开放访问）
• /api/v1/nl2cga/validate-code — 语法验证
• 编译闭环：生成 → 编译验证 → 报错 → LLM 修复 → 最多 2 轮自动重试
• 语法注入：build_context_prompt() 自动加载 grammar-knowledge.json 注入当前引擎能力边界

• rag_service.py — Marketplace 188 个 .cga 文件向量化
• 关键词 + 向量混合匹配（Hybrid Search）
• CJK 同义词扩展：中式 → [chinese, temple, pagoda]、玻璃 → [glass, panel, window]
• 检索延迟 ~10-30ms，结果直接拼接到 LLM Few-shot 上下文

• ide.html 新增 320px 可折叠侧边栏
• 功能：自然语言输入、风格选择（11种预建模板）、楼层滑块、生成/复制/插入/解释
• aiGenerate() → POST /api/v1/nl2cga/generate
• aiExplainSelection() → 获取编辑器选中文本 → POST /explain
• 风格列表动态加载：GET /styles
• 底部展示近期修复：GET /repairs

• roofGambrel(shape, angle, height2) — 谷仓屋顶，使用 extractFootprintVerts + breakFrac 控制折线高度
• roofHalfHip(shape, angle, hipFrac=0.3) — 半坡屋顶，ridgeInset 控制 ridge 缩进比例
• roofRound(shape, angle) — 球形穹顶，3 层 ring + peak 球冠近似
• 此前这 3 个函数仅为空壳/异常占位，导致 AI 生成相关代码时直接报错

• compHoles(shape) — 支持两种 hole 来源检测
• 来源 1：PolygonData 显式 holes 数组
• 来源 2：BufferGeometry.userData.contours 内环（如 shapeO 生成的 O-ring）
• 使用 earcut 重新三角化，计算贴合孔洞平面的 scope
• compMeta = { sel: 'hole', index, total }

• extract-grammar-docs.mjs — 自动扫描源码生成结构化语法知识库
• 输出 grammar-knowledge.json：163 个函数 + 90 个操作，含签名、参数、返回值、使用示例
• 输入：CGAGrammar.g4 + builtins.ts + evaluator.ts
• 绑定到构建流程，每次部署自动更新
• NL2CGA Prompt 动态读取，无需人工维护

• ANTLR4 驱动解析器，语法覆盖完整
• 1727 行核心求值器，支持 60+ Shape 操作
• 162 个内置函数基础注册
• 14 组 e2e 测试覆盖 happy path