@dsh-gis/dsh-opengis-skill 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @dsh-gis/dsh-opengis-skill
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DeepSeek Harness 的 **OpenGIS 技能包插件**：把 [opengis-skills](https://github.com/znlgis/opengis-skills) 中 **gis/ 分类的 32 个 GIS 技能**打包成可安装、可启停的 DSH bundle。会话技能目录只列出名称与描述，技能正文与参考资料按需加载。
+
+## 特性
+
+- **32 个 GIS 技能**：GDAL、GDAL API、QGIS（qgis_process / PyQGIS / QGIS Server）、GeoServer（含 REST API 与 Cloud）、MapServer、PostGIS、PROJ、PDAL、GRASS GIS、JTS、NetTopologySuite、Esri Geometry API（Java/.NET）、Shapely、GeoPandas、GeoPipeAgent、OpenGisDAF、CesiumJS、OpenLayers、Leaflet、Mapbox GL JS、deck.gl、SharpMap、Mapsui、GeoTools、OpenGIS Utils（Java/.NET）、opengis-all 全流程索引。
+- **按需加载**：注册的是 skill provider（`ctx.skills.registerProvider`），发现阶段只读 frontmatter；正文每次加载时读取，参考资料（`reference/*.md`）通过技能目录（resource base）相对解析。
+- **零运行时依赖**：只用 Node 内置模块，npm 包内自带全部资产（约 640 KB），不 import DSH 内部包。
+- **可同步上游**：`npm run sync` 从 opengis-skills 检出复制资产，记录上游 commit 到 `upstream.json`，并重新生成本文下方技能表。
+- **可启停**：单包同时是 bundle 与插件（`dsh.bundle.patch` 插入自身行），在 Plugins 里启用/停用即可。
+
+## 技能清单
+
+<!-- skills:start -->
+| Skill | Description (upstream frontmatter) |
+| --- | --- |
+| `cesiumjs` | Use when building browser-based 3D globes, 3D Tiles visualization, time-dynamic geospatial data, or virtual globe applications. CesiumJS: high-performance WebGL 3D geospatial engine for interactive earth visualization. |
+| `deck-gl` | Use when visualizing large geospatial or tabular datasets in the browser with GPU rendering — millions of points, GeoJSON polygons, vector tiles, aggregation layers (hexagon, screen grid, heatmap), and overlaying them on a MapLibre/Mapbox GL JS base map via @deck.gl/mapbox. |
+| `gdal` | Use when processing geospatial raster/vector data via command line — format conversion (Shapefile to GeoJSON), reprojection, DEM analysis, NDVI calculation, mosaicking. GDAL/OGR CLI: the industry standard for batch geospatial data processing with 50+ command-line tools (ogr2ogr, gdalwarp, gdal_translate, gdal_calc). |
+| `gdal-api` | Use when programming against GDAL/OGR in C, C++, Python, Java, or .NET for raster/vector I/O, coordinate transformation, or custom geospatial algorithms. GDAL API: low-level programming interface for reading/writing 70+ geospatial formats. |
+| `geometry-api-java` | Use when working with Esri geometry types (Point, Polyline, Polygon, Envelope) in Java — spatial operations, JSON/GeoJSON/WKT I/O, geodesic calculations. Esri Geometry API for Java. |
+| `geometry-api-net` | Use when working with Esri geometry types (Point, Polyline, Polygon, Envelope) in .NET/C# — spatial operations, JSON/GeoJSON/WKT I/O, geodesic calculations. Esri Geometry API for .NET. |
+| `geopandas` | Use when performing vector spatial data analysis in Python — reading/writing shapefiles, spatial joins, overlay operations, choropleth maps. GeoPandas: extends pandas DataFrames with geometry columns for Pythonic spatial analysis. |
+| `geopipe-agent` | Use when building AI-driven GIS data pipelines with YAML-defined steps — format conversion, spatial validation, QC reporting, and self-extending capability gaps. GeoPipe Agent: YAML-driven GIS ETL pipeline agent with a built-in offline GIS knowledge layer. |
+| `geoserver` | Use when deploying OGC-compliant map services (WMS, WFS, WMTS, WCS) or configuring SLD styling, security, and tile caching. GeoServer: the leading open-source Java map server for publishing spatial data to the web. |
+| `geoserver-cloud` | Use when deploying GeoServer on Kubernetes as cloud-native microservices with auto-scaling, service discovery, and centralized configuration. GeoServer Cloud: break monolithic GeoServer into independently scalable WMS/WFS/WCS services. |
+| `geoserver-rest-api` | Use when automating GeoServer management — programmatic workspace, datastore, and layer creation, style upload, service configuration via REST API. GeoServer REST API: manage GeoServer without GUI using curl, Python, or any HTTP client. |
+| `geotools` | Use when building Java GIS applications — feature reading/writing, coordinate transformations, map styling, spatial filters, WMS/WFS clients. GeoTools: the Java GIS toolkit and OGC standards reference implementation. |
+| `grass-gis` | Use when doing GIS geoprocessing with GRASS GIS headlessly — grass --exec and --tmp-project for servers and CI, g.region computational region management, r.* raster, v.* vector, r3.* 3D raster and t.* temporal modules, r.import/v.import data import, or Python scripting with grass.script, grass.script.array and grass.tools. |
+| `jts` | Use when performing precise 2D computational geometry in Java — spatial predicates (contains, intersects), overlay operations, buffering, triangulation. JTS (Java Topology Suite): the canonical geometry engine used as blueprint for GEOS, Shapely, and NetTopologySuite. |
+| `leaflet` | Use when adding lightweight interactive 2D maps to web pages — tile layers, markers, GeoJSON overlays, layer control, popups. Leaflet: compact, mobile-friendly open-source JavaScript web mapping library. |
+| `mapbox-gl-js` | Use when building interactive vector web maps with Mapbox GL JS — WebGL rendering, Style Spec, data-driven expressions, 3D terrain, layer-level events. Note: v2+ is proprietary under Mapbox TOS with an access token requirement; MapLibre GL JS is the open-source API-compatible fork. |
+| `mapserver` | Use when publishing spatial data as OGC web services (WMS, WFS, WCS) from a mapfile, styling layers with SLD, or deploying the mapserv CGI/FastCGI. MapServer: the C-based OSGeo open-source map server for the web. |
+| `mapsui` | Use when embedding interactive 2D maps in .NET desktop (WinForms/WPF) or mobile (MAUI) applications — tile layers, vector features, map controls. Mapsui: cross-platform .NET map component library. |
+| `nettopologysuite` | Use when performing 2D computational geometry in .NET — spatial predicates, overlay operations, buffering, WKT/WKB I/O. NetTopologySuite: the .NET port of JTS, available via NuGet for spatial analysis in C# applications. |
+| `opengis-all` | Use when navigating end-to-end GIS workflows — discover the full toolchain from GDAL data processing through GeoServer publishing to CesiumJS/OpenLayers visualization. One-stop index covering the complete open-source GIS data pipeline. |
+| `opengis-daf` | Use when building plan-driven GIS data analysis or data quality-check pipelines with OpenGisDAF (.NET 10 / C# 14): define buffer, clip, intersect/containment checks, coordinate transform, field calculator, attribute/geometry QC rules purely in JSON plans, run the daf CLI, chain operators via DAG upstream bindings, output to GeoJSON/Shapefile/PostGIS, or extend with plugin operators loaded via AssemblyLoadContext. |
+| `opengis-utils-for-java` | Use when needing common GIS utility functions in Java — CRS utilities, geometry helpers, format converters, spatial validation. OpenGIS Utils for Java: convenience toolkit for Java GIS projects. |
+| `opengis-utils-for-net` | Use when needing common GIS utility functions in .NET/C# — CRS utilities, geometry helpers, format converters, spatial validation. OpenGIS Utils for .NET: convenience toolkit for .NET GIS projects. |
+| `openlayers` | Use when adding interactive 2D maps to web applications — WMS/WFS/WMTS layers, vector styling, map controls, popups. OpenLayers: the most full-featured open-source JavaScript web mapping library. |
+| `pdal` | Use when processing point cloud data (LAS/LAZ/BPF/EPT/COPC) via CLI or Python — pipeline JSON workflows, format conversion, reprojection, cropping, outlier removal, ground classification (SMRF), and DEM generation from LiDAR. PDAL (Point Data Abstraction Library) is the point cloud equivalent of GDAL: pdal info/translate/pipeline commands plus pdal.Pipeline Python bindings. |
+| `postgis` | Use when extending PostgreSQL with spatial data types, spatial indexes (GiST/SP-GiST), geometry functions (ST_Intersects, ST_Buffer, ST_Transform), and spatial queries. PostGIS: the most widely used open-source spatial database extension. |
+| `proj` | Use when performing coordinate reference system (CRS) transformation, reprojection, datum shift or EPSG lookup from the command line — converting coordinates between WGS 84, UTM, Web Mercator and CGCS2000. PROJ: the OSGeo library that powers GDAL/QGIS transformations, with projinfo, cs2cs, proj, cct and the proj.db SQLite database. |
+| `pyqgis` | Use when extending QGIS with Python plugins, automating map composition, or scripting QGIS processing algorithms. PyQGIS: QGIS Python API for custom tools, processing scripts, and plugin development. |
+| `qgis-process` | Use when running QGIS geoprocessing tools headless from command line or CI/CD — buffer, clip, reproject, raster analysis without GUI. QGIS Processing: batch spatial analysis via qgis_process CLI. |
+| `qgis-server` | Use when publishing QGIS projects (.qgs/.qgz) as OGC web services (WMS, WFS, WMTS, OGC API Features) via FastCGI, Docker, or Apache/Nginx, and when tuning QGIS_SERVER_* environment variables. QGIS Server: the C++ map server that renders QGIS Desktop projects over HTTP. |
+| `shapely` | Use when performing computational geometry in Python — intersection, union, buffer, convex hull, simplification. Shapely: Python bindings for GEOS, the C++ geometry engine that powers PostGIS. |
+| `sharpmap` | Use when rendering 2D maps in legacy .NET WinForms or ASP.NET WebForms applications. SharpMap: an older .NET 2D mapping library. For new projects, prefer Mapsui. |
+<!-- skills:end -->
+
+## 安装
+
+### 方式一：Plugins 界面（本地目录，适合开发）
+
+1. 打开 DSH 的 **Plugins / 插件** 页面，选择安装 bundle（安装本地包目录）。
+2. 目标填本仓库的绝对路径，例如 `D:\self\code\dsh-opengis-skill`。
+3. 在列表中找到 **OpenGIS 技能包** 并启用。
+
+### 方式二：npm
+
+```bash
+dsh plugin --profile <profile> add @dsh-gis/dsh-opengis-skill
+```
+
+安装后在 Plugins 页面启用该 bundle。desktop profile 由 Electron 应用独占，推荐直接用 Plugins 界面操作；安装、升级或启停之后，需要新会话（或重启 dsh）才会出现最新的技能目录。
+
+## 使用
+
+- 技能目录会列出 32 个技能的名称与描述；模型用 `skill("gdal")` 之类的调用加载，用户也可以在输入框直接输入 `/gdal`。
+- 常用入口：
+  - `opengis-all` — 端到端 GIS 流程索引（GDAL → 处理 → GeoServer → 可视化）；
+  - `gdal` / `gdal-api` — 命令行与编程式栅格/矢量处理；
+  - `qgis-process` / `pyqgis` — QGIS 批处理与二次开发；
+  - `geoserver` + `geoserver-rest-api` — 发布与管理 OGC 服务；
+  - `postgis` — 空间数据库；`proj` — 坐标转换；
+  - `openlayers` / `cesiumjs` / `deck-gl` — Web 2D/3D 可视化。
+- 加载结果会给出该技能的 Base directory；正文中的 `reference/*.md` 与 `../<其他技能>/SKILL.md` 相对链接都据此解析（资源随包全量分发）。
+
+## 上游同步
+
+```bash
+# 默认从 ../opengis-skills 读取，也可用 --from 或 OPENGIS_SKILLS_DIR 指定
+npm run sync -- --from ../opengis-skills
+
+# 只检查是否与上游一致（CI 可用）
+npm run sync:check -- --from ../opengis-skills
+```
+
+同步脚本会：逐文件复制 `gis/<skill>/`（不含任何改写）、校验 frontmatter（name 必须为 kebab-case 且与目录同名）、清理上游已删除的技能目录、更新 `upstream.json`（仓库地址、commit、同步时间、技能清单）以及本文的技能表。
+
+## 开发
+
+```bash
+npm test            # Node 内置测试运行器，覆盖 provider 目录/加载/链接
+npm run validate    # 资产、元数据、bundle 接线与打包校验
+npm pack --dry-run  # 查看实际发布内容
+```
+
+### 目录结构
+
+```text
+dsh-opengis-skill/
+├── package.json            # dsh.bundle.patch、engines、files、icons/locales 导出
+├── cordis.patch.yml        # bundle 层：把 opengis-skill provider 行插入 Host
+├── lib/
+│   ├── index.js            # provider 插件（扫描 assets、注册 ctx.skills）
+│   ├── skill-file.js       # SKILL.md frontmatter 解析（插件/脚本/测试共用）
+│   └── *.d.ts              # 手写类型声明
+├── assets/<skill>/         # 32 个技能资产（SKILL.md + reference/*.md，随上游同步）
+├── locale/{en,zh}.json     # Plugins 里显示的标题与描述
+├── icon.svg                # bundle 图标
+├── scripts/                # 同步与校验脚本
+├── test/plugin.test.mjs    # 单元测试
+└── upstream.json           # 上游仓库、commit、同步时间与技能清单
+```
+
+### 设计说明
+
+- `apply` 时扫描 `assets/*/SKILL.md`，解析并校验名称与描述，然后 `ctx.effect(() => ctx.skills.registerProvider(...))`；provider 名为 `opengis`，候选 rank 为 600（与官方内置技能包一致），模型与用户均可调用。
+- 目录（list）只含元数据；正文（get）每次重新读盘，因此编辑资产后重新加载插件即可生效，无需清缓存。插件不注册工具、不注入提示段、不写会话状态。
+- 相对链接不做改写：包内是全量 32 个技能目录，`reference/*.md` 与 `../<skill>/SKILL.md` 都能解析；如果将来裁剪技能，`npm run validate` 会报断链。
+
+## 与 @dsh-gis 其他插件的关系
+
+- ```dsh-gis/dsh-gis`：GIS 工具与地图界面（inspect/query/CRS/OGC/UI）。
+- ```dsh-gis/dsh-prompt-gis`：一段 GIS system-prompt 与两个内联技能（`gis-inspect-first`、`gis-query-patterns`）。
+- 本包：纯知识型技能包（32 个 GIS 技能），不提供工具，可与上述插件同时安装。
+
+## 许可
+
+MIT，见 [LICENSE](./LICENSE)。技能正文与参考资料来自 [opengis-skills](https://github.com/znlgis/opengis-skills)（MIT © 2024-2026 znlgis），详见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,26 @@
+# Third-party notices
+
+## opengis-skills
+
+The skill instructions under `assets/` are copied verbatim from the
+[opengis-skills](https://github.com/znlgis/opengis-skills) repository
+(`gis/` category), which is licensed under the MIT License:
+
+> MIT License
+>
+> Copyright (c) 2024-2026 znlgis
+
+The exact upstream commit, sync time, and the list of vendored skills are
+recorded in [`upstream.json`](./upstream.json); the copy is performed by
+[`scripts/sync-opengis-skills.mjs`](./scripts/sync-opengis-skills.mjs). The
+skills are documentation: each one describes an independent open-source project
+(GDAL, QGIS, GeoServer, PostGIS, JTS, CesiumJS, OpenLayers, and others) and
+links to that project's own repository, documentation, and license. Those
+projects keep their own licenses; nothing in this package re-licenses them.
+
+## DeepSeek Harness
+
+This package registers a skill provider on the public `ctx.skills` service of
+DeepSeek Harness and mirrors the standard bundled-provider rank (600) documented
+by `@deepseek-ai/dsh-skill`. No DeepSeek Harness source code is copied into
+or redistributed with this package; DeepSeek Harness itself is MIT licensed.

package/assets/cesiumjs/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: cesiumjs
+description: "Use when building browser-based 3D globes, 3D Tiles visualization, time-dynamic geospatial data, or virtual globe applications. CesiumJS: high-performance WebGL 3D geospatial engine for interactive earth visualization."
+tags:
+  - javascript
+  - webgl
+  - 3d
+  - 3d-tiles
+  - gltf
+  - earth
+  - map
+  - web
+  - visualization
+---
+
+> **项目地址：** <https://github.com/CesiumGS/cesium>
+>
+> **官方文档：** <https://cesium.com/learn/cesiumjs-learn/>
+>
+> **API 参考：** <https://cesium.com/learn/cesiumjs/ref-doc/>
+>
+> **Sandcastle：** <https://sandcastle.cesium.com/>
+>
+> **最新版本：** 1.146.0（截至2026-10，npm `cesium`）
+>
+> **许可证：** Apache-2.0
+
+## 概述
+
+CesiumJS 提供：
+
+- **三维全球**：WGS84 椭球体、地形（Quantized-Mesh）、卫星影像
+- **3D Tiles**：海量三维流式（倾斜摄影、BIM、点云、城市模型）
+- **glTF / GLB 模型**：标准 PBR 渲染
+- **CZML / Entity API**：高层声明式数据模型，时序动画
+- **Primitive API**：底层高性能 API
+- **可视化分析**：通视/剖面/缓冲/裁剪/视频投影/光影
+
+---
+
+## 安装
+
+```bash
+npm install cesium
+```
+
+```html
+<link href="https://cdn.jsdelivr.net/npm/cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/cesium/Build/Cesium/Cesium.js"></script>
+```
+
+> **1.146 变更：** 数学/几何/时间/工具类被拆分为新包 `@cesium/core`。从 `cesium` 主包导入的代码不受影响；直接按子路径引用 `@cesium/engine` 的代码需改从 `@cesium/core` 导入（旧导出将在 1.150 移除）。
+
+### Vite 集成
+
+```js
+import { defineConfig } from 'vite';
+import cesium from 'vite-plugin-cesium';
+export default defineConfig({ plugins: [cesium()] });
+```
+
+### Webpack 集成
+
+需将 `node_modules/cesium/Build/Cesium/{Workers,Assets,Widgets}` 拷贝到输出目录，并设置 `window.CESIUM_BASE_URL`。
+
+---
+
+## 快速上手
+
+```html
+<div id="cesiumContainer" style="width:100%;height:100vh"></div>
+<script type="module">
+  import * as Cesium from 'cesium';
+  import 'cesium/Build/Cesium/Widgets/widgets.css';
+
+  Cesium.Ion.defaultAccessToken = 'YOUR_ION_TOKEN';
+
+  const viewer = new Cesium.Viewer('cesiumContainer', {
+    terrainProvider: await Cesium.createWorldTerrainAsync(),
+    timeline: false, animation: false
+  });
+
+  viewer.camera.flyTo({
+    destination: Cesium.Cartesian3.fromDegrees(116.397, 39.908, 5000)
+  });
+</script>
+```
+
+---
+
+## 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| `Viewer` | 顶层容器 |
+| `Scene` | 渲染场景，含 globe/camera/primitives |
+| `Entity` | 高层数据对象，时序、属性、可视化封装 |
+| `DataSource` | Entity 集合（CZML/GeoJSON/KML） |
+| `Primitive` | 低层渲染单元，性能最优 |
+| `Cesium3DTileset` | 3D Tiles 数据集 |
+
+---
+
+## 影像与地形
+
+```js
+viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({
+  url: 'https://webst02.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}'
+}));
+
+viewer.terrainProvider = await Cesium.createWorldTerrainAsync({
+  requestVertexNormals: true,
+  requestWaterMask: true
+});
+```
+
+---
+
+## Entity 数据驱动
+
+```js
+const ds = await Cesium.GeoJsonDataSource.load('/data/poi.geojson', {
+  stroke: Cesium.Color.RED, fill: Cesium.Color.RED.withAlpha(0.3),
+  strokeWidth: 2, clampToGround: true
+});
+viewer.dataSources.add(ds);
+viewer.flyTo(ds);
+
+viewer.entities.add({
+  position: Cesium.Cartesian3.fromDegrees(116.397, 39.908),
+  point: { pixelSize: 10, color: Cesium.Color.YELLOW },
+  label: { text: '天安门', font: '14px sans-serif',
+           verticalOrigin: Cesium.VerticalOrigin.BOTTOM }
+});
+
+viewer.entities.add({
+  polyline: {
+    positions: Cesium.Cartesian3.fromDegreesArray([116, 39, 121, 31]),
+    width: 3, material: Cesium.Color.CYAN, clampToGround: true
+  }
+});
+
+viewer.entities.add({
+  polygon: {
+    hierarchy: Cesium.Cartesian3.fromDegreesArray([116,39, 117,39, 117,40, 116,40]),
+    material: Cesium.Color.RED.withAlpha(0.5),
+    extrudedHeight: 1000
+  }
+});
+```
+
+---
+
+## 3D Tiles
+
+```js
+const tileset = await Cesium.Cesium3DTileset.fromUrl('https://server/tileset.json', {
+  maximumScreenSpaceError: 16
+});
+viewer.scene.primitives.add(tileset);
+viewer.flyTo(tileset);
+
+tileset.style = new Cesium.Cesium3DTileStyle({
+  color: { conditions: [
+    ['${height} >= 100', 'rgba(255,0,0,0.8)'],
+    ['true', 'rgb(180,180,180)']
+  ]}
+});
+```
+
+---
+
+## glTF 模型
+
+```js
+viewer.entities.add({
+  position: Cesium.Cartesian3.fromDegrees(116.4, 39.9, 0),
+  model: { uri: '/models/airplane.glb', minimumPixelSize: 64, maximumScale: 200 }
+});
+```
+
+---
+
+## 时序动画（CZML）
+
+```js
+const czml = [
+  { id: 'document', name: 'demo', version: '1.0',
+    clock: { interval: '2024-01-01/2024-01-02', currentTime: '2024-01-01' } },
+  { id: 'plane',
+    position: { epoch: '2024-01-01T00:00:00Z',
+      cartographicDegrees: [0, 116, 39, 1000, 3600, 117, 40, 1000] },
+    point: { color: { rgba: [255, 0, 0, 255] }, pixelSize: 10 } }
+];
+viewer.dataSources.add(Cesium.CzmlDataSource.load(czml));
+```
+
+---
+
+## 交互与拾取
+
+```js
+const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
+handler.setInputAction(e => {
+  const picked = viewer.scene.pick(e.position);
+  if (Cesium.defined(picked)) console.log(picked.id);
+
+  const c3 = viewer.camera.pickEllipsoid(e.position);
+  if (c3) {
+    const c = Cesium.Cartographic.fromCartesian(c3);
+    console.log(Cesium.Math.toDegrees(c.longitude),
+                Cesium.Math.toDegrees(c.latitude));
+  }
+}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+```
+
+---
+
+## 摄像机
+
+```js
+viewer.camera.flyTo({
+  destination: Cesium.Cartesian3.fromDegrees(116.4, 39.9, 5000),
+  orientation: { heading: 0, pitch: -Cesium.Math.PI_OVER_FOUR, roll: 0 },
+  duration: 2
+});
+viewer.trackedEntity = entity;
+```
+
+---
+
+## 典型工作流
+
+1. **初始化 Viewer**：使用 `Cesium.Viewer` 创建三维地球，设置地形和影像提供者
+2. **加载数据**：根据数据类型选择合适 API——GeoJSON/CZML 用 `DataSource`，3D 瓦片用 `Cesium3DTileset`，单模型用 `Entity.model`
+3. **设置相机**：使用 `camera.flyTo()` 定位到目标区域
+4. **添加交互**：通过 `ScreenSpaceEventHandler` 处理点击拾取
+5. **性能优化**：根据场景复杂度启用 `requestRenderMode`、调整 `maximumScreenSpaceError`
+
+---
+
+## 性能优化
+
+1. 大量静态要素优先用 Primitive 而非 Entity
+2. 3D Tiles 启用 `dynamicScreenSpaceError`、`skipLevelOfDetail`
+3. 影像图层数量 ≤ 4
+4. 启用 `requestRenderMode = true`（按需渲染）
+5. `clampToGround` 适度使用
+6. 释放：`viewer.entities.removeAll()`、`tileset.destroy()`
+7. 监听 `webglcontextlost`
+
+---
+
+## 常见问题
+
+| 问题 | 解决 |
+|------|------|
+| 黑屏 | 检查 `CESIUM_BASE_URL` 与静态资源 |
+| 模型贴地不准 | `HeightReference.CLAMP_TO_GROUND` 或地形采样 |
+| 性能卡顿 | 启用 `requestRenderMode`，降低 `maximumScreenSpaceError` |
+| 国内瓦片偏移 | 使用 GCJ02→WGS84 纠偏 |
+| Token 过期 | 不需要 ion 时不设置 token；或自托管 |
+
+---
+
+## AI 使用建议
+
+
+### 关键注意事项
+
+- **Ion Token**：使用 Cesium ion 服务需要设置 `Cesium.Ion.defaultAccessToken`；自托管数据则无需
+- **坐标转换**：Cesium 内部使用 Cartesian3（地心地固坐标），通过 `Cesium.Cartesian3.fromDegrees(lon, lat, height)` 将经纬度转为内部坐标
+- **Entity vs Primitive**：少量动态要素用 Entity API（简洁），大量静态要素用 Primitive API（高性能）
+- **贴地（clampToGround）**：在三维地形上，需要明确设置 `clampToGround: true` 或 `HeightReference.CLAMP_TO_GROUND`
+- **资源释放**：不再使用的 `DataSource` 调用 `viewer.dataSources.remove(ds)`，3D Tileset 调用 `tileset.destroy()`
+- **静态资源部署**：使用 Webpack/Vite 时，确保 `Assets`、`Workers`、`Widgets` 目录正确复制到输出目录
+
+## 相关技能
+
+- **openlayers** — 二维 Web 地图库：[../openlayers/SKILL.md](../openlayers/SKILL.md)
+- **geoserver** — 地图服务发布：[../geoserver/SKILL.md](../geoserver/SKILL.md)
+- **geoserver-rest-api** — REST 自动化管理：[../geoserver-rest-api/SKILL.md](../geoserver-rest-api/SKILL.md)
+- **postgis** — 空间数据库：[../postgis/SKILL.md](../postgis/SKILL.md)
+- **mapsui** — .NET 跨平台地图组件：[../mapsui/SKILL.md](../mapsui/SKILL.md)
+
+## 参考资源
+
+- 学习中心：<https://cesium.com/learn/>
+- API：<https://cesium.com/learn/cesiumjs/ref-doc/>
+- Sandcastle：<https://sandcastle.cesium.com/>
+- 中文教程（znlgis）：<https://znlgis.github.io/gis/tutorial/cesium/>