NEXA - 文档

Appearance

cesium-example 单案例迁移 — AI 启动模板 ​

将下面的模板复制给执行迁移的 AI。每次只填写一个案例；完成后 AI 必须停下等待人工验收。

Claude / CodeBuddy 推荐方式 ​

在 Claude Code 或 CodeBuddy 中直接输入：

text
/migrate-cesium-example

不带参数时，AI 会先对比旧仓库与当前 SDK，展示 Top 5 缺口，自动选择一个最高价值安全案例并提交提案。批准前不会写实现。

也可以显式指定：

text
/migrate-cesium-example <案例名称或精确源入口>

对应 Skill：

  • Claude：.claude/skills/cesium-example-migration.md
  • CodeBuddy：.codebuddy/skills/cesium-example-migration.md

Codex 推荐方式：调用项目 Skill ​

text
请使用 $cesium-example-migration 完成一个 cesium-example 单案例迁移。

源仓库：/Users/ysuhan/Elon/Project/opensource/Cesium 资源/cesium-example
目标仓库：/Users/ysuhan/Elon/Project/product/nexa
本次案例：<可留空；留空时对比源/目标并自动选择一个最高价值安全缺口>

严格要求：
1. 一次只处理一个案例；未指定时先建立差距索引、展示 Top 5 并只选择一个。
2. 先读取 Skill、所有适用 AGENTS.md 和迁移规范。
3. 先追踪完整源码闭包，再检查 gis-cesium 是否已经存在等价能力。
4. 第一阶段只输出迁移提案：源码分析、重叠结论、API 设计、测试计划、案例计划、文档计划、文件边界和验证命令；不要修改实现代码。
5. 等我明确批准提案后，才实现 API + 测试 + 可运行案例 + JSDoc/VitePress 文档。
6. 所有验收命令必须在目标仓库本地实际运行，不接受“理论上通过”。
7. 完成后给出人工体验步骤并停止。未收到“验收通过，继续下一个”前，不得选择或迁移下一案例。
8. 不新增依赖，不修改构建配置，不使用 Cesium 私有 API，不做 Breaking Change；如确有必要，立即停止并单独申请。

第一轮预期输出 ​

AI 第一轮只能提交方案，结构应为：

markdown
## 迁移提案：<caseId> — <案例名称>

### 自动选型 Top 5 与选择理由（指定案例时写“不适用”）
### 范围与源码闭包
### 源行为、核心算法和资源生命周期
### 目标仓库重叠检查与处置结论
### API 调用示例和模块归属
### 测试设计
### 自动发现案例设计
### JSDoc/VitePress 文档设计
### allowedFiles / forbiddenFiles / contextFiles / maxChangedFiles
### 依赖、私有 API、资产和 WebGL 风险
### 本地验证命令
### 非目标
### 等待审批

如果 AI 第一轮直接写代码，应停止执行并要求它退回方案审批阶段。

批准提案时的回复 ​

确认方案后，回复：

text
批准本案例迁移提案。只允许修改提案中的 allowedFiles，按 API → 测试 → 案例 → 文档 → 本地验收顺序完成。完成后停止并等待人工验收，不要进入下一个案例。

如果需要调整范围，应先修改提案，不要一边实现一边口头扩大范围。

案例完成后的人工验收 ​

要求 AI 提供：

  • 新增或增强的公共 API 及调用方式；
  • 单元测试、浏览器/WebGL 测试及实际数量；
  • 可运行案例入口和操作步骤；
  • API 文档路径；
  • 所有本地命令的真实结果；
  • 源行为与目标行为差异；
  • 资源清理和重复进入验证；
  • 剩余风险。

体验通过后回复：

text
本案例验收通过。现在可以停止本案例工作，并为下一个指定案例重新从源码分析和迁移提案开始。

然后另起消息指定下一个案例。不要使用“把剩下的都迁完”一类开放指令。

AI 不支持 Skill 时的完整指令 ​

如果执行 AI 无法识别 Skill 或快捷命令，发送：

text
请先完整阅读以下文件，并严格执行：

1. AGENTS.md
2. packages/AGENTS.md
3. packages/gis-cesium/AGENTS.md
4. docs/specs/migration-guide.md
5. docs/specs/testing.md
6. docs/specs/documentation.md
7. .codex/skills/cesium-example-migration/SKILL.md
8. .codex/skills/cesium-example-migration/references/source-analysis.md
9. .codex/skills/cesium-example-migration/references/case-proposal-template.md
10. .codex/skills/cesium-example-migration/references/case-acceptance-template.md

源仓库：/Users/ysuhan/Elon/Project/opensource/Cesium 资源/cesium-example
目标仓库：/Users/ysuhan/Elon/Project/product/nexa
本次只迁移：<可留空；留空时自动对比并选择一个案例>

未指定案例时，先对比旧仓库案例与当前 SDK 的 API、测试、案例和文档，展示 Top 5，选择一个最高价值安全缺口。然后提交单案例迁移提案，未经批准禁止修改代码。批准后必须一次性交付公共 API、测试、自动发现案例、JSDoc/VitePress 文档和本地验收证据。完成后停止等待人工验收，禁止自动开始下一个案例。