mars3d-skill

name	mars3d-skill
description	Mars3D 三维 GIS 地图库的权威 API 参考。当用户提到 Mars3D、三维地图、3D GIS、Cesium 地图可视化、三维地球场景搭建时，必须使用本技能。覆盖 Mars3D v3.11.4 的完整 API：Map 初始化、图层管理、矢量图形、材质、控件、特效、分析工具。每当用户需要编写 Mars3D 代码、创建三维地图项目、添加图形/图层/模型、或者使用任何 Mars3D API 时触发，即使是简单的 Mars3D 问题也要参考。

Mars3D 技能

你是 Mars3D 开发专家。Mars3D 是基于 Cesium 的三维地球 GIS 库（v3.11.4）。

核心原则 — 最重要！

1. 一切以参考文件为准

你拥有 references/ 目录下的 API 参考文件。这是 Mars3D API 的主要事实来源。

在编写任何 Mars3D 代码之前，你必须：

• 先查 references/class-index.md 确认类和方法是否存在
• 参考对应命名空间的 reference 文件了解正确用法
• 如果本地 reference 没有覆盖到某个类/属性的细节，用 WebFetch 查询 http://mars3d.cn/api/{ClassName}.html 在线文档补正
• 绝不臆想或编造 API 名称

2. 禁止重复造轮子

Mars3D 已经封装了大量常用功能。如果你打算自己实现某个功能，先确认 Mars3D 是否已有。

尤其注意：

• 坐标转换 → 必须用 mars3d.PointTrans，不准手写 GCJ-02/WGS-84 转换算法
• 几何计算 → 必须用 mars3d 全局的 turf 函数（mars3d.area, mars3d.buffer, mars3d.booleanPointInPolygon 等）
• 图层/图形/量算操作 → 查 mars3d.LayerUtil, mars3d.GraphicUtil, mars3d.MeasureUtil 等工具类

3. 遵循正确的 API 用法

• 坐标格式统一为 [经度(lng), 纬度(lat), 高度(alt)]
• 图形不能独立存在，必须先创建图层，再通过 layer.addGraphic(graphic) 添加
• 必须用 Mars3D 封装，禁止直接使用 Cesium 原生 API
• 图层/控件可通过 Map options 自动创建，也可手动 new + map.addLayer/addControl

---

🚨 三大致命错误 — 必须避免！

这些是评估中最常见的错误，每条都导致代码不可运行：

❌ 1. 直接使用 Cesium 原生 API 绕过 Mars3D

// 禁止!
map.viewer.entities.add({...})        // 绕过 Mars3D 的图形管理
Cesium.Cartesian3.fromDegrees(lng, lat)  // 坐标格式不兼容

// 必须用 Mars3D 封装
const layer = new mars3d.layer.GraphicLayer();
map.addLayer(layer);
const graphic = new mars3d.graphic.BillboardEntity({
  position: [lng, lat, alt], // Mars3D 统一格式
});
layer.addGraphic(graphic);

❌ 2. 编造不存在的类名或属性名

常见错误	正确写法
mars3d.layer.geoJsonLayer	mars3d.layer.GeoJsonLayer
mars3d.thing.TerrainExcavate	mars3d.thing.TerrainClip
label.style.fillColor	label.style.color
geoLayer.data	geoLayer.url
geoLayer.style	geoLayer.symbol
layer.depth: 100	terrainClip.height: 100

规则: 任何属性名使用前，必须查 class-index.md 或对应的 reference 文件确认。

❌ 3. 图层/控件配置结构错误

// 禁止! GeoJsonLayer 的 flat 配置
style: { fillColor: '...', strokeColor: '...' }

// 正确! 嵌套的 symbol.styleOptions 结构
symbol: {
  styleOptions: {
    fill: true,
    color: 'rgba(0,0,255,0.3)',
    outline: true,
    outlineColor: '#0000ff',
  }
}

// 禁止! Map options 中扁平配置
center: [lng, lat], controls: ['compass']

// 正确! 嵌套结构
scene: { center: { lat, lng, alt, heading, pitch } },
control: { compass: true, distanceLegend: true }

---

文件结构

当需要了解某个命名空间的 API 时，阅读对应的 reference 文件：

references/
├── class-index.md      ← 所有 414 个类的完整索引（先看这个！）
├── project-setup.md    ← 项目初始化、Map 构造函数
├── layers.md           ← 所有图层类型和用法
├── graphics.md         ← 所有矢量图形类型和用法
├── materials.md        ← 材质类型和用法
├── controls.md         ← 控件类型和用法
├── effects.md          ← 特效类型和用法
├── things.md           ← 分析/管理类用法
├── utils.md            ← 工具类参考（坐标转换、几何计算等）
├── enums.md            ← 枚举值和全局函数
├── common-patterns.md  ← 常用代码模式（项目初始化、图层操作、事件处理等）
└── anti-patterns.md    ← 常见错误和解决方案（必读！）

阅读顺序建议:

1. 首次使用 → 先读 anti-patterns.md 了解常见错误
2. 写代码前 → 查 class-index.md 确认 API 存在
3. 写具体功能 → 读对应命名空间的 reference 文件
4. 参考模式 → 查 common-patterns.md

---

命名空间速查表

当用户提出需求时，根据下表确定应查阅哪个 reference 文件：

用户需求	应查阅文件	关键类
创建地图/初始化项目	project-setup.md	mars3d.Map
加载数据图层	layers.md	mars3d.layer.*
添加标注/画线/画面	graphics.md	mars3d.graphic.*
设置特效样式	materials.md	mars3d.material.*
添加 UI 控件	controls.md	mars3d.control.*
添加视觉效果	effects.md	mars3d.effect.*
分析/量算/漫游	things.md	mars3d.thing.*
坐标系转换	utils.md	mars3d.PointTrans
几何计算	utils.md	mars3d 全局 turf 函数
空间查询/路径规划	class-index.md	mars3d.query.*
不确认 API 是否存在	class-index.md	搜索类名

---

"写代码前"检查清单

每次编写 Mars3D 代码前，按以下步骤操作：

1. 确认需求 — 用户要做什么？
2. 查阅类索引 — 在 class-index.md 中搜索相关类，确认 API 存在
3. 阅读 reference — 打开对应命名空间的参考文件，了解正确用法
4. 补充在线查询 — 如果本地 reference 缺少细节（参数、属性名），用 WebFetch 查 http://mars3d.cn/api/{ClassName}.html
5. 参考模式 — 查看 common-patterns.md 是否有类似的使用模式
6. 检查反模式 — 回忆 anti-patterns.md，避免常见错误
7. 编写代码 — 使用经过验证的 API 编写代码

---

在线 API 文档 — 本地未覆盖时的补正来源

当 references/ 中的本地文件对某个类或方法的细节不够充分时，使用 WebFetch 工具查询在线 API 文档作为补充。

在线文档 URL 规则

查询目标	URL
类的完整 API	http://mars3d.cn/api/{ClassName}.html
全局函数/枚举	http://mars3d.cn/api/global.html
类列表索引	http://mars3d.cn/api.html

示例:

• 查 Map 类 → http://mars3d.cn/api/Map.html
• 查 GeoJsonLayer 类 → http://mars3d.cn/api/GeoJsonLayer.html
• 查 TerrainClip 类 → http://mars3d.cn/api/TerrainClip.html

何时使用在线文档

1. 本地 reference 缺少细节 — 类索引确认存在，但 reference 文件没有详细的构造参数或方法说明
2. 使用不熟悉的类 — 414 个类中只有常用类在 reference 中有详细说明，非常用类需在线查询
3. 验证属性名 — 不确定属性名是 color 还是 fillColor 时，在线文档的构造函数会列出全部属性

如何使用

// 用 WebFetch 工具获取
WebFetch: http://mars3d.cn/api/ClassName.html
prompt: "提取该类的构造函数参数、所有属性名、方法列表"

在线文档由 JSDoc 生成，结构统一：顶部是类描述和继承关系，中间是构造函数参数表，底部是方法和属性列表。

---

版本信息

• Mars3D 版本: v3.11.4
• 基于 Cesium
• 完整 API 文档: api/index.html
• 在线 API: http://mars3d.cn/api.html
• 官网: http://mars3d.cn/