@anov/gis-skills-cli 0.0.0-stage → 0.3.3

package/skills/anovgis-primitives/SKILL.md

@@ -0,0 +1,482 @@
+---
+name: anovgis-primitives
+description: '@anov/gis Primitive 体系（19 类），SDK 高性能图元层。涵盖 BillboardPrimitive / BounceBillboardPrimitive / BounceLabelPrimitive / CloudPrimitive / DiffuseWallPrimitive / ElecEllipsoidPrimitive / FlowLinePrimitive / GroundPolygonPrimitive / GroundPolylinePrimitive / LabelPrimitive / LightCylinderPrimitive / ModelPrimitive / ModelCollectionPrimitive / PointPrimitive / PolylinePrimitive / ScanCirclePrimitive / TrailLinePrimitive / VideoPrimitive / WaterPrimitive。v1.8.6 起 15 个 Primitive 类新增 `boundingSphere` getter 用于 `viewer.flyTo` 自动定位。触发关键词：Primitive、CloudPrimitive、DiffuseWallPrimitive、FlowLinePrimitive、LightCylinderPrimitive、ScanCirclePrimitive、TrailLinePrimitive、VideoPrimitive、WaterPrimitive、GroundPolygonPrimitive、GroundPolylinePrimitive、BounceBillboard、BounceLabel、ElecEllipsoid、雷达扫描 Primitive 版、尾迹线 Primitive 版、流动线 Primitive 版、扩散墙 Primitive 版、动态水面 Primitive 版。Use when 用 Primitive 版做扫描圆 / 雷达 / 尾迹线 / 流动线 / 扩散墙 / 动态水面 / 云层 / 光柱 / 弹跳图标、把所有 Primitive 类批量加入 PrimitiveLayer、把 Primitive 传给 viewer.flyTo 自动定位。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+
+# anovgis-primitives — @anov/gis Primitive 体系速查
+
+> ⚠️ **优先级**：本 skill 优先于 SDK 源码 / `node_modules/@anov/gis/`。
+> 遇到 API 行为疑问先查本 skill 与 `anovgis-pitfalls`。**严禁**主动 Glob/Grep `node_modules/@anov/gis/src/...` / `dist/...`；除非用户明确要求并承担风险。
+> 调试流程见 `using-anovgis` § 默认调试流程（Chrome DevTools 仅第 5 级兜底）。
+>
+> **Cesium 入口（铁律）**：`const Cesium = window.Cesium`。`@anov/gis` 启动时已把 Cesium 挂到 `window`，**不存在** `ANOVGIS.Cesium` 写法；本 skill 所有 `Cesium.*` 均从此变量取。底层 Cesium API 细节查 `cesiumjs-skills` 对应 skill（API 名通用，`import` 写法换成 `const Cesium = window.Cesium`）。
+
+> `@anov/gis` 中"高性能图元"全部继承自抽象类 `Graphic`，但内部走 `Cesium.Primitive` / `GroundPrimitive` / `BillboardCollection` / `LabelCollection` / `PointPrimitiveCollection` / `PolylineCollection` 等 PrimitiveCollection，**性能高于 Entity 体系**。本 skill 覆盖 **19 个 Primitive 子类** + 通用容器 `PrimitiveLayer` + 通用模式。
+>
+> 源码根：`src/graphic/primitive/`（仅作语义锚点）。
+>
+> **版本基线**：`@anov/gis` v1.8.6；本文档 snippet 基于 v1.8.6 SDK 公开 API 行为锁定。
+
+---
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 `Vector` 16 类（Point / Polyline / Polygon / ...） → `anovgis-vector-graphics`
+- ❌ 不要写 `Model` / `Tileset` 加载 + 调色 + 抽壳 → `anovgis-models-3dtiles`
+- ❌ 不要写 `*MaterialProperty` 版本（Primitive 自带材质 vs Property 挂在 entity） → `anovgis-materials`
+- ❌ 不要写 `Cesium.Primitive` / `Cesium.DrawCommand` 原生用法（直接绘制底层） → v0.3.0 `anovgis-custom-primitive-worker`
+
+---
+
+## 1. 19 类 Primitive 速查表
+
+### 1.1 广告牌 / 文字类（4 个）
+
+| 类 | 构造签名 | 关键 options | 用途 |
+|---|---|---|---|
+| `BillboardPrimitive` | `(position, options)` | `image, scale, color, pixelOffset, scaleByDistance` | 高性能图标（用 `BillboardCollection`） |
+| `BounceBillboardPrimitive` | `(position, icon)` | `size, maxOffsetY, offsetAmount` | 跳动图标（继承 BillboardPrimitive） |
+| `BounceLabelPrimitive` | `(position, text)` | `font, fillColor, outlineColor, maxOffsetY, offsetAmount` | 跳动文字（继承 LabelPrimitive） |
+| `LabelPrimitive` | `(position, options)` | `text, font, fillColor, style, scaleByDistance` | 高性能 Label（用 `LabelCollection`） |
+
+### 1.2 点 / 线 / 面（5 个）
+
+| 类 | 构造签名 | 关键 options | 用途 |
+|---|---|---|---|
+| `PointPrimitive` | `(position, options)` | `color, pixelSize, outlineColor, outlineWidth` | 高性能点（用 `PointPrimitiveCollection`） |
+| `PolylinePrimitive` | `(positions, options)` | `width, material, clampToGround` | 高性能折线（用 `PolylineCollection`） |
+| `GroundPolygonPrimitive` | `(polygonHierarchy, options)` | `material` | 贴地形面（用 `GroundPrimitive`） |
+| `GroundPolylinePrimitive` | `(positions, options)` | `width, material` | 贴地形折线（用 `GroundPolylinePrimitive`） |
+
+### 1.3 流动 / 扩散 / 雷达 / 尾迹（5 个）
+
+| 类 | 构造签名 | 关键 options | 用途 |
+|---|---|---|---|
+| `FlowLinePrimitive` | `(positions, width, options)` | `speed, color, percent` | 流动抛物线（Primitive 版） |
+| `DiffuseWallPrimitive` | `(positions, options)` | `speed, color` | 扩散墙体（Primitive 版） |
+| `ScanCirclePrimitive` | `(position, radius)` | `speed, color` | 雷达扫描圆（Primitive 版） |
+| `TrailLinePrimitive` | `(positions, width=1)` | `color, speed` | 尾迹线（Primitive 版） |
+
+### 1.4 容器 / 模型（3 个）
+
+| 类 | 构造签名 | 关键 options | 用途 |
+|---|---|---|---|
+| `ModelPrimitive` | `(options)` | `url, scale, minimumPixelSize, maximumScale` | 自定义 Primitive 容器（单 glTF） |
+| `ModelCollectionPrimitive` | `(options)` | `models: [...]` | 自定义 Primitive 容器（多模型集合） |
+| `GroundPrimitive`（基础类） | — | — | 贴地形 Primitive 基类（多数 Primitive 内部用） |
+
+### 1.5 装饰 / 特效（4 个）
+
+| 类 | 构造签名 | 关键 options | 用途 |
+|---|---|---|---|
+| `CloudPrimitive` | `(position)` | `scale: {x, y}` | 云层（基于球面贴图） |
+| `LightCylinderPrimitive` | `(center, length, topRadius, bottomRadius)` | `color` | 光柱（底环+旋转圆+渐变柱+粒子） |
+| `WaterPrimitive` | `(positions, holes=[])` | `baseWaterColor, frequency, amplitude, animationSpeed, specularIntensity` | 动态水面（用 `Water` material） |
+| `ElecEllipsoidPrimitive` | `(position, radius)` | `color, speed` | 电磁球 |
+| `VideoPrimitive` | `(options)` | `url, material, scale` | 视频贴图（基于视频材质） |
+| `BounceBillboardPrimitive` | （已列于 1.1） | — | 弹跳图标 |
+| `BounceLabelPrimitive` | （已列于 1.1） | — | 弹跳文字 |
+
+> **去重后 19 类**：Billboard / BounceBillboard / BounceLabel / LabelPrimitive / PointPrimitive / PolylinePrimitive / GroundPolygon / GroundPolyline / FlowLine / DiffuseWall / ScanCircle / TrailLine / ModelPrimitive / ModelCollection / Cloud / LightCylinder / Water / ElecEllipsoid / Video = **19 个**。
+
+### 1.6 通用属性（v1.8.6 新增 `boundingSphere`）
+
+v1.8.6 起，15 个 Primitive 类（除 VideoPrimitive / GroundPolygonPrimitive / GroundPolylinePrimitive 外）新增 `boundingSphere` getter。直接 `viewer.flyTo(primitive)` 时 SDK 用此 getter 自动计算 `range`，无需手动指定。
+
+```js
+// v1.8.6 之前：手动指定 range
+viewer.flyTo(primitive, 2.0, 0, Cesium.Math.toRadians(-45), 0);
+// v1.8.6+：传 Primitive 实例 + range=0，内部用 boundingSphere 兜底
+viewer.flyTo(primitive, 2.0, 0, Cesium.Math.toRadians(-45), 0);
+```
+
+---
+
+## 2. 通用容器 PrimitiveLayer
+
+所有 Primitive 必须通过 `PrimitiveLayer` 接入 viewer：
+
+```js
+// 方式 A：链式
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+
+// 方式 B：标准
+const layer = new ANOVGIS.PrimitiveLayer();
+viewer.addLayer(layer);
+
+// 加图元
+layer.addGraphic(scanCirclePrimitive);
+
+// 移除
+layer.removeGraphic(primitive);
+```
+
+`PrimitiveLayer` 暴露 6 个子集合（与 Cesium `PrimitiveCollection` 子集对应）：
+- `layer.points` — `PointPrimitiveCollection`
+- `layer.labels` — `LabelCollection`
+- `layer.billboards` — `BillboardCollection`
+- `layer.polylines` — `PolylineCollection`
+- `layer.primitives` — `PrimitiveCollection`（云、水、光柱、扩散墙等）
+- `layer.clouds` — 云专用 PrimitiveCollection
+
+---
+
+## 3. Primitive vs *MaterialProperty 边界（重要）
+
+| 视觉 | Primitive 版（独立 Graphic） | Property 版（挂 entity.material） |
+|---|---|---|
+| 雷达扫描 | `ScanCirclePrimitive(pos, radius)` + `setOptions({ speed, color })` | `CircleScanMaterialProperty({ color, speed })` |
+| 流动线 | `FlowLinePrimitive(positions, width, { speed, color, percent })` | `PolylineFlowMaterialProperty({ color, speed, percent, gradient })` |
+| 扩散墙 | `DiffuseWallPrimitive(positions, { speed, color })` | `WallFlowMaterialProperty({ color, duration })` |
+| 尾迹线 | `TrailLinePrimitive(positions, width)` | `PolylineTrailMaterialProperty({ color, speed })` |
+| 水面 | `WaterPrimitive(positions, holes)` | `WaterMaterialProperty({ ... })` |
+| 扩散波 | （无 Primitive 版）| `CircleWaveMaterialProperty({ color, duration, count, gradient })` |
+
+**选择建议**：
+- **Primitive 版**：适合批量创建（数百个以上）、需要精细控制样式（如 `color`/`speed`/`percent`）、单实例性能敏感。
+- **Property 版**：适合挂载到 Entity（图元本身是 Cesium 原生 Entity）、需要时序属性（`CallbackProperty` / `SampledProperty`）、与 material 体系集成。
+
+> ❌ **不要混用**：同一视觉不要同时挂 Property + Primitive，否则样式叠加。
+
+---
+
+## 4. Snippet（19 类全覆盖 + 容器 + 反模式）
+
+### S1. PrimitiveLayer 创建 + 加图元
+
+```js
+// 来源: src/layer/graphic/PrimitiveLayer.js + src/graphic/index.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+// 或
+const layer = new ANOVGIS.PrimitiveLayer();
+viewer.addLayer(layer);
+```
+
+<a id="s2"></a>
+### S2. ScanCirclePrimitive 雷达扫描
+
+```js
+// 来源: examples/public/examples/html/model/cesium_three.html L309-316
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const scan = new ANOVGIS.ScanCirclePrimitive(
+    Cesium.Cartesian3.fromDegrees(119.506, 35.361),  // 中心
+    1000                                            // 半径（米）
+);
+scan.setOptions({
+    speed: 5,
+    color: new ANOVGIS.Color(0.5, 0.8, 1.0, 1.0)
+});
+layer.addGraphic(scan);
+// v1.8.6+: viewer.flyTo(scan, 2.0, 0, -45, 0) // range=0 自动取 boundingSphere
+```
+
+### S3. TrailLinePrimitive 尾迹线
+
+```js
+// 来源: src/graphic/primitive/TrailLinePrimitive.js L7-77
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const trail = new ANOVGIS.TrailLinePrimitive(
+    [[116.3, 39.9], [116.4, 40.0], [116.5, 39.8]],  // positions
+    3                                                // width
+);
+trail.setOptions({
+    color: new Cesium.Color(1.0, 0.0, 0.0, 0.7),    // 红色半透明
+    speed: 5
+});
+layer.addGraphic(trail);
+```
+
+### S4. WaterPrimitive 动态水面
+
+```js
+// 来源: examples/public/examples/html/performance/wall_drawCommand2_Sci0.html L145-170
+// positions 为 Cesium.Cartesian3[]（来自 GeoJsonDataSource 的 polygon hierarchy）
+const layer = new ANOVGIS.PrimitiveLayer();
+viewer.addLayer(layer);
+
+const water = new ANOVGIS.WaterPrimitive(positionCartesian3, holes);
+water.setOptions({
+    baseWaterColor: ANOVGIS.Color.fromCssColorString('rgb(17,38,57)'),
+    frequency: 100.0,         // 波浪频率
+    animationSpeed: 0.01,     // 动画速度
+    amplitude: 10,            // 振幅
+    specularIntensity: 0.2    // 高光强度
+});
+layer.addGraphic(water);
+```
+
+### S5. FlowLinePrimitive 流动抛物线
+
+```js
+// 来源: src/graphic/primitive/FlowLinePrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const flow = new ANOVGIS.FlowLinePrimitive(
+    [[116.30, 39.90, 0], [116.40, 39.95, 200], [116.50, 39.92, 0]],
+    3,                      // width
+    { speed: 5, color: Cesium.Color.CYAN.withAlpha(0.8), percent: 0.5 }
+);
+layer.addGraphic(flow);
+```
+
+### S6. DiffuseWallPrimitive 扩散墙体
+
+```js
+// 来源: src/graphic/primitive/DiffuseWallPrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const wall = new ANOVGIS.DiffuseWallPrimitive(
+    [[116.30, 39.90], [116.35, 39.90], [116.35, 39.95], [116.30, 39.95]],
+    { speed: 5, color: Cesium.Color.fromCssColorString('rgba(255,200,0,0.6)'), height: 200 }
+);
+layer.addGraphic(wall);
+```
+
+<a id="s7"></a>
+### S7. CloudPrimitive 云层
+
+```js
+// 来源: src/graphic/primitive/CloudPrimitive.js L7-18
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const cloud = new ANOVGIS.CloudPrimitive([116.40, 39.90, 1500]);
+cloud.setOptions({ scale: { x: 12, y: 8 } });    // 经向/纬向跨度（度）
+layer.addGraphic(cloud); viewer.flyTo(cloud);
+```
+
+### S8. LightCylinderPrimitive 光柱
+
+```js
+// 来源: src/graphic/primitive/LightCylinderPrimitive.js L14-25
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const beam = new ANOVGIS.LightCylinderPrimitive(
+    [116.40, 39.90, 0],       // center
+    500,                      // length
+    5,                        // topRadius
+    80                        // bottomRadius
+);
+beam.setOptions({ color: Cesium.Color.fromCssColorString('rgba(255,200,80,1)') });
+layer.addGraphic(beam); viewer.flyTo(beam);
+```
+
+### S9. ElecEllipsoidPrimitive 电磁球
+
+```js
+// 来源: src/graphic/primitive/ElecEllipsoidPrimitive.js L7-19
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const elec = new ANOVGIS.ElecEllipsoidPrimitive(
+    [116.40, 39.90, 0],
+    { x: 80, y: 80, z: 80 }     // 椭球半径
+);
+elec.setOptions({
+    color: Cesium.Color.fromCssColorString('rgba(0,255,180,0.9)'),
+    speed: 5
+});
+layer.addGraphic(elec); viewer.flyTo(elec);
+```
+
+### S10. BillboardPrimitive 高性能图标
+
+```js
+// 来源: src/graphic/primitive/BillboardPrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const bb = new ANOVGIS.BillboardPrimitive(
+    [116.40, 39.90],
+    {
+        image: './assets/camera.png',
+        scale: 1.0,
+        color: Cesium.Color.WHITE,
+        scaleByDistance: new Cesium.NearFarScalar(100, 1.0, 10000, 0.1)
+    }
+);
+layer.addGraphic(bb);
+```
+
+### S11. BounceBillboardPrimitive 弹跳图标
+
+```js
+// 来源: src/graphic/primitive/BounceBillboardPrimitive.js L5-39
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const bb = new ANOVGIS.BounceBillboardPrimitive(
+    [116.40, 39.90],
+    ANOVGIS.ShapeUtil.drawCanvalCircle('#ff5500', 48, ['告警'])
+);
+bb.size = [48, 48];
+bb.setOptions({ maxOffsetY: 12, offsetAmount: 0.6 });
+layer.addGraphic(bb);
+```
+
+### S12. BounceLabelPrimitive 弹跳文字
+
+```js
+// 来源: src/graphic/primitive/BounceLabelPrimitive.js L5-39
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const lb = new ANOVGIS.BounceLabelPrimitive([116.40, 39.91], '弹跳标签');
+lb.setOptions({
+    maxOffsetY: 8, offsetAmount: 0.4,
+    font: '20px sans-serif',
+    fillColor: Cesium.Color.YELLOW,
+    outlineColor: Cesium.Color.BLACK, outlineWidth: 2,
+    style: Cesium.LabelStyle.FILL_AND_OUTLINE
+});
+layer.addGraphic(lb);
+```
+
+### S13. LabelPrimitive 高性能文字
+
+```js
+// 来源: src/graphic/primitive/LabelPrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const lb = new ANOVGIS.LabelPrimitive([116.40, 39.90], {
+    text: '高性能文字',
+    font: '30px sans-serif',
+    fillColor: Cesium.Color.WHITE,
+    style: Cesium.LabelStyle.FILL_AND_OUTLINE,
+    outlineColor: Cesium.Color.BLACK, outlineWidth: 2,
+    scaleByDistance: new Cesium.NearFarScalar(100, 1.0, 10000, 0.1)
+});
+layer.addGraphic(lb);
+```
+
+### S14. PointPrimitive 高性能点
+
+```js
+// 来源: src/graphic/primitive/PointPrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const pt = new ANOVGIS.PointPrimitive([116.40, 39.90], {
+    color: Cesium.Color.RED,
+    pixelSize: 12,
+    outlineColor: Cesium.Color.WHITE,
+    outlineWidth: 2,
+    scaleByDistance: new Cesium.NearFarScalar(100, 1.0, 10000, 0.1)
+});
+layer.addGraphic(pt);
+```
+
+### S15. PolylinePrimitive 高性能折线
+
+```js
+// 来源: src/graphic/primitive/PolylinePrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const line = new ANOVGIS.PolylinePrimitive(
+    [[116.30, 39.90], [116.40, 39.95], [116.50, 39.92]],
+    { width: 3, material: Cesium.Color.YELLOW, clampToGround: false }
+);
+layer.addGraphic(line);
+```
+
+### S16. GroundPolygonPrimitive 贴地形面
+
+```js
+// 来源: src/graphic/primitive/GroundPolygonPrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const positions = Cesium.Cartesian3.fromDegreesArray([
+    116.30, 39.90, 116.35, 39.90, 116.35, 39.95, 116.30, 39.95
+]);
+const ground = new ANOVGIS.GroundPolygonPrimitive(
+    new Cesium.PolygonHierarchy(positions),
+    { material: Cesium.Color.fromCssColorString('rgba(0,200,0,0.5)') }
+);
+layer.addGraphic(ground);
+```
+
+### S17. GroundPolylinePrimitive 贴地形折线
+
+```js
+// 来源: src/graphic/primitive/GroundPolylinePrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const positions = Cesium.Cartesian3.fromDegreesArray([
+    116.30, 39.90, 116.35, 39.90, 116.40, 39.95
+]);
+const groundLine = new ANOVGIS.GroundPolylinePrimitive(positions, {
+    width: 3, material: Cesium.Color.YELLOW
+});
+layer.addGraphic(groundLine);
+```
+
+### S18. ModelPrimitive 自定义 Primitive 容器
+
+```js
+// 来源: src/graphic/primitive/ModelPrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const model = new ANOVGIS.ModelPrimitive({
+    url: '/data/model.glb',
+    scale: 1.0,
+    minimumPixelSize: 64,
+    maximumScale: 1.0
+});
+model.setOptions({ color: Cesium.Color.fromCssColorString('rgba(255,200,0,0.8)') });
+layer.addGraphic(model);
+viewer.flyTo(model, 2.0, 0, Cesium.Math.toRadians(-45), 0);
+```
+
+### S19. ModelCollectionPrimitive 多模型集合
+
+```js
+// 来源: src/graphic/primitive/ModelCollectionPrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const collection = new ANOVGIS.ModelCollectionPrimitive({
+    models: [
+        { url: '/data/tree.glb', position: [116.40, 39.90, 0], scale: 2.0 },
+        { url: '/data/tree.glb', position: [116.41, 39.90, 0], scale: 1.5 },
+        { url: '/data/tree.glb', position: [116.42, 39.91, 0], scale: 2.5 }
+    ]
+});
+layer.addGraphic(collection);
+```
+
+### S20. VideoPrimitive 视频贴图
+
+```js
+// 来源: src/graphic/primitive/VideoPrimitive.js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer);
+const video = new ANOVGIS.VideoPrimitive({
+    url: '/data/sample.mp4',
+    positions: Cesium.Cartesian3.fromDegreesArray([
+        116.30, 39.90, 116.35, 39.90, 116.35, 39.95, 116.30, 39.95
+    ]),
+    scale: 1.0
+});
+layer.addGraphic(video);
+```
+
+### S21. v1.8.6 boundingSphere 自动定位（flyTo 0-range）
+
+```js
+// 来源: v1.8.6 起 viewer.flyTo 支持 Primitive + range=0 内部兜底
+// 示例：将所有 Primitive 集中定位
+const allPrimitives = layer.points.values.concat(
+    layer.billboards.values,
+    layer.primitives.values
+);
+allPrimitives.forEach(p => {
+    viewer.flyTo(p, 2.0, 0, Cesium.Math.toRadians(-45), 0); // range=0 自动取 boundingSphere
+});
+```
+
+---
+
+## 5. 反模式
+
+| 错误 | 后果 | 正确做法 |
+|---|---|---|
+| Primitive 与 `*MaterialProperty` 混用同一图元 | 视觉叠加 / 性能浪费 / 样式错乱 | 二选一，按 §3 表选择 |
+| 不用 `PrimitiveLayer` 直接 `addGraphic(primitive)` | 无法触发事件 / 难以批量管理 | 必须 `viewer.addLayer(new ANOVGIS.PrimitiveLayer())` |
+| `viewer.flyTo(primitive, 2, 0, -45, 0)` range 写 0 但 v1.8.5 之前 | 黑屏（无 boundingSphere） | 升级 SDK 到 v1.8.6+ 或手动计算 range |
+| 大量 Primitive（>10000）不分批 | 卡顿 / 帧率下降 | 改用 `PrimitiveCollection` 集合，或降到 `VectorLayer` |
+| `primitive.setOptions({ color: someColor.red })` 改子字段 | P5 陷阱，uniform 不更新 | `primitive.setOptions({ color: new Cesium.Color(...) })` 整体赋值 |
+| 用 Primitive 跑时序动画（每帧 setOptions）| 严重卡顿 | 改用 `CallbackProperty` + `*MaterialProperty` |
+
+---
+
+## 6. 关联阅读
+
+- 抽象类：`src/graphic/Graphic.js`
+- Primitive 源码：`src/graphic/primitive/`（19 个 .js 文件）
+- 容器：`src/layer/graphic/PrimitiveLayer.js`
+- 兄弟 skill：
+  - [`anovgis-vector-graphics`](../anovgis-vector-graphics/SKILL.md) — Vector 16 + Model 2 类
+  - [`anovgis-materials`](../anovgis-materials/SKILL.md) — 18 个 `*MaterialProperty`
+  - [`anovgis-models-3dtiles`](../anovgis-models-3dtiles/SKILL.md) — `Model` / `Tileset` 加载
+  - `anovgis-custom-primitive-worker`（v0.3.0）— Cesium 原生 `DrawCommand` / `GeometryInstance` 自定义图元
+- DOMAINS.md：`#1.1-graphic/` 拆分说明
+- DEMO-SKILL-MAP.md：`#5-model/` 与 `#10-performance/` demo 路由