cgajs.com 与 rulepackage.com 解耦后职责、通信与功能砍留报告

未来直接在服务器上开发，不再走“本地开发 → 部署”模式。本报告明确两个站点各自保留什么、砍掉什么、如何通信。

一、核心设计原则

二、解耦后职责分工

三、功能砍留详细说明

3.1 cgajs.com 会砍掉 / 弱化的功能

3.2 rulepackage.com 会砍掉 / 弱化的功能

四、跨站通信 API 与数据流

4.1 rulepackage.com 对外暴露的 API

4.2 cgajs.com 对外暴露的 API

4.3 数据流向

4.4 同步机制

• 引擎产物同步：cgajs.com CI 通过后，执行 scripts/promote-to-prod.sh，把 dist-stable 同步到 rulepackage.com 的 /www/wwwroot/cgajs-engine/dist-stable，并同时更新两站的 site-version.json。
• 语料同步：rulepackage.com 更新 cga_assets 表或 marketplace 文件后，调用 cgajs.com 的 /api/v1/webhook/corpus-updated；cgajs.com 再拉取 /api/v1/cga-corpus 重建本地缓存。若无 webhook，则每 30 分钟 cron 兜底。
• Golden case 同步：Omega 上传端在 rulepackage.com；cgajs.com 通过 /api/v1/omega/sync-to-cgajs 按 batch_id 拉取，导入 tests/golden/omega-imports/。
• 认证：跨站 API 调用携带 cgajs.com 签发的 X-API-Key 或 JWT；rulepackage.com 只接受 cgajs.com IP / 固定密钥白名单。

五、服务器直接开发工作流

5.1 cgajs.com 上的开发流程

1. 在 /www/wwwroot/cgajs-engine 修改 parser / geometry / runtime。
2. 本地跑 npm test（unit + e2e + cga-corpus）。
3. 提交并生成 dist-stable。
4. 执行 scripts/promote-to-prod.sh：同步 dist-stable 到 rulepackage.com，并 bump 两站 site-version.json。

5.2 rulepackage.com 上的开发流程

1. 在 /www/wwwroot/www.rulepackage.com、cgajs-api、marketplace.rulepackage.com 修改前端 / API / 资产脚本。
2. 新增 / 修改 CGA 文件后，执行 scripts/build_cga_corpus.py 重新索引。
3. Omega 上传后，后台自动调用 /api/v1/omega/sync-to-cgajs 供 cgajs.com 拉取。
4. 提交代码；Marketplace enrichment 脚本生成 manifest 与预览图。

5.3 禁止做的事

• 在 rulepackage.com 直接修改 /www/wwwroot/cgajs-engine/src 的引擎源码（会被 cgajs.com 同步覆盖）。
• 在 cgajs.com 直接修改 /www/wwwroot/marketplace.rulepackage.com/files 的 CGA 文件（会被 rulepackage.com 同步覆盖）。
• 两站直接读写对方数据库；所有数据交换必须走 API。

六、风险与兜底

七、一句话总结

八、cgajs.com 当前状态评估与修复方案

基于 2026-06-15 对 cgajs.com 实际代码与运行状态的扫描，对比 architecture-report 的目标架构，形成以下修复清单。

8.1 当前结构快照

8.2 与目标架构的差距

8.3 修复方案

P0：引擎仓库清理与提交（1 天）

1. 在 cgajs.com 上进入 /www/wwwroot/cgajs-engine，先运行完整备份：

   tar czf /root/cgajs-engine-pre-commit-$(date +%Y%m%d).tgz /www/wwwroot/cgajs-engine

2. 删除历史备份目录：

   git rm -r src/_src_backup_*
   rm -rf src/_src_backup_*

3. 确认 dist-beta 删除意图并提交：

   git rm -r dist-beta
   rm -rf dist-beta

4. 重建 dist-stable：

   npm run build
   rsync -av --delete dist/ dist-stable/

5. 分批次提交：

   git add src/ tests/
   git commit -m "feat(engine): insert/inset/convert/asset-loader and comprehensive test suite"
   git add dist-stable/
   git commit -m "chore(dist): rebuild dist-stable from latest source"
   git add .github/workflows/ci.yml cli-wrapper.cjs
   git commit -m "ci(cli): stricter CI and workspace resolver support"

6. 清理未跟踪的临时文件（debug_*.mjs 等已删除，无需额外处理）。

P1：统一引擎版本并同步到 rulepackage.com（1 天）

1. 在 cgajs.com 新增 /www/wwwroot/cgajs-engine/scripts/promote-to-prod.sh：

   #!/bin/bash
   set -e
   cd /www/wwwroot/cgajs-engine
   npm run build
   npm test
   rsync -av --delete dist/ dist-stable/
   NEW_V=$(date +%s)
   echo '{"engine":"'"$NEW_V"'",...}' > /www/wwwroot/www.cgajs.com/site-version.json
   # 同步到 rulepackage.com
   rsync -av --delete dist-stable/ root@8.216.94.109:/www/wwwroot/cgajs-engine/dist-stable/
   rsync -av --delete dist/ root@8.216.94.109:/www/wwwroot/cgajs-engine/dist/
   scp /www/wwwroot/www.cgajs.com/site-version.json root@8.216.94.109:/www/wwwroot/www.rulepackage.com/site-version.json
   # 更新 rulepackage.com ide.html 的 importmap 版本戳（可选：改为动态读取 site-version.json）

2. 运行 promote-to-prod，使 rulepackage.com 的 engine 版本从 v24 升级到与 cgajs.com 一致。
3. 修改 www.cgajs.com/ide.html 与 www.rulepackage.com/ide.html，让 importmap 的 ?v= 从 site-version.json 读取，避免未来手动改版本戳。

P2：NL2CGA 服务形态决策（0.5 天）

• 方案 A（推荐）：保持 cgajs-api 内嵌 NL2CGA 端点，删除/归档独立 nl2cga-service 目录，减少维护面。
• 方案 B：启动独立服务，新增 systemd nl2cga.service，Nginx 配置 nl2cga.cgajs.com 子域，cgajs-api 做反向代理。

在做出选择前，先压测 /api/v1/nl2cga/generate 确认内嵌端点是否满足并发需求。

P3：打通 rulepackage.com → cgajs.com 实时同步（1 天）

1. 在 cgajs.com 环境变量中配置 RULEPACKAGE_WEBHOOK_SECRET（两个服务器共享同一密钥，存于 /etc/cgajs/cgajs-api.env）。
2. 在 rulepackage.com cgajs-api 中新增 webhook 发送逻辑：
   • CGA 资产创建/更新/删除时调用 cgajs.com POST /api/v1/webhooks/rulepackage。
   • Omega 批次完成时调用 cgajs.com /api/v1/omega/sync-to-cgajs。
3. 在 cgajs.com 新增 cron：每 5 分钟拉取 rulepackage.com Omega reports，兜底夜间 backup-files.sh。

P4：CGA 语料索引持续维护（0.5 天）

1. 确保 cgajs.com /api/v1/cga-corpus 在新增资产后自动重新索引（webhook 触发或每晚 cron）。
2. 将解析/渲染状态写回 CgaAsset 表，标记 nl2cga_ready 与 compile_status。

P5：parser ambiguity 与长期质量（持续）

1. 在 CI 中增加 ambiguity 统计：收集测试 stderr 中的 [Parser Ambiguity] 数量，禁止新增。
2. 为高频 ambiguity 用例建 issue，逐步调整 grammar 或源码写法。

8.4 预期修复后的验收标准

8.5 立即可以做的 3 件事

1. 在 cgajs.com 执行 git status --short | wc -l，确认 448 条变更；备份后分批提交。
2. 配置 RULEPACKAGE_WEBHOOK_SECRET 并在 rulepackage.com 加 webhook 发送。
3. 运行一次 scripts/promote-to-prod.sh，把 cgajs.com 最新 dist-stable 同步到 rulepackage.com，统一 engine 版本。

九、rulepackage.com 能力矩阵与发展路线图

rulepackage.com 不只是“存 CGA 文件”，而是 CGA 资产、测试体系、共享记忆与跨站同步的控制中心。下面是已实现能力、实现方式，以及下一步可开发的功能。

9.1 当前能力矩阵

9.2 实现方式汇总

9.3 可进一步开发的功能

9.4 推荐下一步

1. Marketplace 元数据化：先让 380 个 UUID 文件变成有标题、标签、预览图、manifest 的可售资产。
2. 打通 webhook：配置 secret，让 rulepackage.com 资产变更实时同步到 cgajs.com。
3. CGA 语料 RAG 库：把 534 个文件解析成 NL2CGA 可用的结构化语料。