@dsh-gis/dsh-opengis-skill 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +48 -22
  3. package/THIRD_PARTY_NOTICES.md +9 -0
  4. package/adaptations/brutile.md +8 -0
  5. package/adaptations/cesiumjs.md +8 -0
  6. package/adaptations/common.md +16 -0
  7. package/adaptations/deck-gl.md +8 -0
  8. package/adaptations/duckdb-spatial.md +8 -0
  9. package/adaptations/gdal-api.md +8 -0
  10. package/adaptations/gdal.md +8 -0
  11. package/adaptations/geolibre.md +8 -0
  12. package/adaptations/geometry-api-java.md +8 -0
  13. package/adaptations/geometry-api-net.md +8 -0
  14. package/adaptations/geonode.md +8 -0
  15. package/adaptations/geopandas.md +8 -0
  16. package/adaptations/geopipe-agent.md +8 -0
  17. package/adaptations/geoserver-cloud.md +8 -0
  18. package/adaptations/geoserver-rest-api.md +8 -0
  19. package/adaptations/geoserver.md +8 -0
  20. package/adaptations/geotools.md +8 -0
  21. package/adaptations/grass-gis.md +8 -0
  22. package/adaptations/jts.md +8 -0
  23. package/adaptations/kepler-gl.md +8 -0
  24. package/adaptations/leaflet.md +8 -0
  25. package/adaptations/mapbox-gl-js.md +8 -0
  26. package/adaptations/mapserver.md +8 -0
  27. package/adaptations/mapsui.md +8 -0
  28. package/adaptations/nettopologysuite.md +8 -0
  29. package/adaptations/opengis-all.md +8 -0
  30. package/adaptations/opengis-daf.md +8 -0
  31. package/adaptations/opengis-utils-for-java.md +8 -0
  32. package/adaptations/opengis-utils-for-net.md +8 -0
  33. package/adaptations/openlayers.md +8 -0
  34. package/adaptations/pdal.md +8 -0
  35. package/adaptations/postgis.md +8 -0
  36. package/adaptations/proj.md +8 -0
  37. package/adaptations/projnet4geoapi.md +8 -0
  38. package/adaptations/pyqgis.md +8 -0
  39. package/adaptations/qgis-process.md +8 -0
  40. package/adaptations/qgis-server.md +8 -0
  41. package/adaptations/shapely.md +8 -0
  42. package/adaptations/sharpmap.md +8 -0
  43. package/adaptations/spatialite.md +8 -0
  44. package/adaptations/whitebox-tools.md +8 -0
  45. package/assets/brutile/SKILL.md +289 -0
  46. package/assets/cesiumjs/SKILL.md +73 -23
  47. package/assets/deck-gl/SKILL.md +19 -20
  48. package/assets/duckdb-spatial/SKILL.md +370 -0
  49. package/assets/gdal/SKILL.md +50 -21
  50. package/assets/gdal-api/SKILL.md +6 -4
  51. package/assets/geolibre/SKILL.md +364 -0
  52. package/assets/geometry-api-java/SKILL.md +5 -6
  53. package/assets/geometry-api-net/SKILL.md +65 -21
  54. package/assets/geonode/SKILL.md +347 -0
  55. package/assets/geopandas/SKILL.md +17 -15
  56. package/assets/geopipe-agent/SKILL.md +25 -20
  57. package/assets/geoserver/SKILL.md +6 -4
  58. package/assets/geoserver-cloud/SKILL.md +14 -15
  59. package/assets/geoserver-rest-api/SKILL.md +13 -8
  60. package/assets/geotools/SKILL.md +7 -5
  61. package/assets/grass-gis/SKILL.md +19 -20
  62. package/assets/jts/SKILL.md +7 -4
  63. package/assets/kepler-gl/SKILL.md +313 -0
  64. package/assets/leaflet/SKILL.md +41 -19
  65. package/assets/mapbox-gl-js/SKILL.md +18 -19
  66. package/assets/mapserver/SKILL.md +17 -19
  67. package/assets/mapsui/SKILL.md +85 -48
  68. package/assets/nettopologysuite/SKILL.md +91 -20
  69. package/assets/opengis-all/SKILL.md +78 -270
  70. package/assets/opengis-all/reference/data-stages.md +262 -4
  71. package/assets/opengis-daf/SKILL.md +6 -5
  72. package/assets/opengis-utils-for-java/SKILL.md +52 -39
  73. package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
  74. package/assets/opengis-utils-for-net/SKILL.md +105 -39
  75. package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
  76. package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
  77. package/assets/openlayers/SKILL.md +66 -9
  78. package/assets/pdal/SKILL.md +21 -17
  79. package/assets/postgis/SKILL.md +61 -11
  80. package/assets/proj/SKILL.md +28 -30
  81. package/assets/projnet4geoapi/SKILL.md +299 -0
  82. package/assets/pyqgis/SKILL.md +28 -20
  83. package/assets/qgis-process/SKILL.md +71 -22
  84. package/assets/qgis-server/SKILL.md +20 -20
  85. package/assets/shapely/SKILL.md +132 -75
  86. package/assets/sharpmap/SKILL.md +93 -50
  87. package/assets/spatialite/SKILL.md +365 -0
  88. package/assets/whitebox-tools/SKILL.md +269 -0
  89. package/lib/adaptations.d.ts +47 -0
  90. package/lib/adaptations.js +268 -0
  91. package/lib/index.d.ts +1 -1
  92. package/lib/index.js +14 -2
  93. package/lib/skill-file.js +31 -7
  94. package/locale/en.json +1 -1
  95. package/locale/zh.json +1 -1
  96. package/package.json +12 -2
  97. package/upstream.json +56 -40
@@ -22,7 +22,7 @@ tags:
22
22
  >
23
23
  > **示例:** <https://leafletjs.com/examples.html>
24
24
  >
25
- > **最新版本:** 1.9.4(截至2026-10,npm `leaflet`)
25
+ > **最新版本:** 1.9.4(截至 2026-10,npm `leaflet`)
26
26
  >
27
27
  > **许可证:** BSD-2-Clause
28
28
 
@@ -187,19 +187,42 @@ map.off('mousemove', handler); // 显式移除,避免内存泄漏
187
187
 
188
188
  ## 典型工作流
189
189
 
190
+ 以「底图 + GeoJSON 点位 + 弹窗 + 图层切换」为例:输入 `data/poi.geojson`(`[lng, lat]`),输出可缩放、可点选、可切层的单页地图。
191
+
190
192
  1. **初始化地图**:`L.map('map', { center, zoom })`,容器须有确定高度
191
193
  2. **添加底图**:`L.tileLayer(urlTemplate, { attribution }).addTo(map)`
192
- 3. **叠加数据**:`L.marker` 或 `L.geoJSON(data, { style, onEachFeature })`
194
+ 3. **叠加数据**:`L.geoJSON(data, { style, pointToLayer, onEachFeature })`
193
195
  4. **绑定交互**:`layer.bindPopup()` / `map.on('click', fn)`
194
196
  5. **图层管理**:`L.control.layers(baseLayers, overlays).addTo(map)`
195
197
  6. **自适应视图**:`map.fitBounds(layer.getBounds())`
196
198
  7. **销毁清理**:组件卸载时调用 `map.remove()`
197
199
 
198
200
  ```javascript
199
- const layer = L.geoJSON(data).addTo(map);
200
- map.fitBounds(layer.getBounds(), { padding: [20, 20] });
201
+ const map = L.map('map', { center: [39.9042, 116.4074], zoom: 11 });
202
+
203
+ const osm = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
204
+ maxZoom: 19,
205
+ attribution: '&copy; OpenStreetMap contributors'
206
+ }).addTo(map);
207
+
208
+ // GeoJSON 坐标是 [lng, lat],Leaflet 需要 [lat, lng]
209
+ fetch('/data/poi.geojson')
210
+ .then((r) => r.json())
211
+ .then((geojson) => {
212
+ const poiLayer = L.geoJSON(geojson, {
213
+ pointToLayer: (feature, latlng) => L.circleMarker(latlng, { radius: 6, color: '#e74c3c' }),
214
+ onEachFeature: (feature, layer) => {
215
+ layer.bindPopup(feature.properties.name);
216
+ }
217
+ }).addTo(map);
218
+
219
+ map.fitBounds(poiLayer.getBounds(), { padding: [20, 20] });
220
+ L.control.layers({ OSM: osm }, { POI: poiLayer }).addTo(map);
221
+ });
201
222
  ```
202
223
 
224
+ **验收**:页面先出现 OSM 底图,数据加载后视野自动收缩到点位范围,点击圆点弹出名称;右上角图层控件可切换 POI 显隐。
225
+
203
226
  ---
204
227
 
205
228
  ## 插件生态
@@ -327,13 +350,15 @@ export default function MapView() {
327
350
 
328
351
  ---
329
352
 
330
- ## 参考资源
353
+ ## AI 使用建议
331
354
 
332
- - 官方文档:<https://leafletjs.com/>
333
- - API 参考:<https://leafletjs.com/reference.html>
334
- - 官方示例:<https://leafletjs.com/examples.html>
335
- - 插件列表:<https://leafletjs.com/plugins.html>
336
- - 源码仓库:<https://github.com/Leaflet/Leaflet>
355
+ - **执行环境**:`npm install`、`npm run build` 在终端中执行;纯静态页面可用 `python -m http.server 5173` 起服务(`python` 不存在时用 `py -3`)。
356
+ - **先探测版本**:`npm ls leaflet`(未装则 `npm view leaflet version`);本技能按 1.9.4 编写,CDN 的 `integrity` SRI 哈希只对应 1.9.4,换版本必须同步换哈希。
357
+ - **验证产物**:构建后 `curl.exe -I http://localhost:5173/assets/<入口>.js` 确认 200;联网时还可 `curl.exe -I https://unpkg.com/leaflet@1.9.4/dist/leaflet.js` 核对 CDN 版本;AI 助手通常看不到浏览器画面,把 URL 和“应看到瓦片与标记”交给用户,环境支持读图时用截图核对。
358
+ - **图标与坐标**:npm + 打包器下默认 marker 图标会 404,需显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`;坐标一律 `[lat, lng]`,GeoJSON 是 `[lng, lat]`。
359
+ - **生命周期**:SPA 卸载必须 `map.remove()` 并解绑自定义事件;容器隐藏或尺寸变化后 `map.invalidateSize()`。
360
+ - **常见症状**:地图区域空白多为容器没设高度;`L is not defined` 是脚本顺序或 CDN 失败;漏引 `leaflet.css` 会导致控件错位。
361
+ - **安全与权限**:装包、起服务、改端口前先征得用户同意;天地图等瓦片服务的 `tk` 不要硬编码进提交的前端代码。
337
362
 
338
363
  ## 相关技能
339
364
 
@@ -341,13 +366,10 @@ export default function MapView() {
341
366
  - **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
342
367
  - **geoserver** — 发布 WMS/WFS/瓦片服务作为 Leaflet 数据源:[../geoserver/SKILL.md](../geoserver/SKILL.md)
343
368
 
344
- ## DeepSeek Harness 使用建议
369
+ ## 参考资源
345
370
 
346
- - **加载与引用**:用 `skill("leaflet")` 加载(用户也可输入 `/leaflet`);本技能无 reference 子目录,示例代码直接落到会话工作区工程,技能目录只读。
347
- - **执行环境**:`npm install`、`npm run build` 交给 `pwsh`;纯静态页面可用 `python -m http.server 5173` 起服务(`python` 不存在时用 `py -3`)。
348
- - **先探测版本**:`npm ls leaflet`(未装则 `npm view leaflet version`);本技能按 1.9.4 编写,CDN 的 `integrity` SRI 哈希只对应 1.9.4,换版本必须同步换哈希。
349
- - **验证产物**:构建后 `curl.exe -I http://localhost:5173/assets/<入口>.js` 确认 200;联网时还可 `curl.exe -I https://unpkg.com/leaflet@1.9.4/dist/leaflet.js` 核对 CDN 版本;DSH 不打开浏览器,把 URL 和“应看到瓦片与标记”交给用户,有截图再用 `read_image`。
350
- - **图标与坐标**:npm + 打包器下默认 marker 图标会 404,需显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`;坐标一律 `[lat, lng]`,GeoJSON 是 `[lng, lat]`。
351
- - **生命周期**:SPA 卸载必须 `map.remove()` 并解绑自定义事件;容器隐藏或尺寸变化后 `map.invalidateSize()`。
352
- - **常见症状**:地图区域空白多为容器没设高度;`L is not defined` 是脚本顺序或 CDN 失败;漏引 `leaflet.css` 会导致控件错位。
353
- - **安全与权限**:装包、起服务、改端口前先征得用户同意;天地图等瓦片服务的 `tk` 不要硬编码进提交的前端代码。
371
+ - 官方文档:<https://leafletjs.com/>
372
+ - API 参考:<https://leafletjs.com/reference.html>
373
+ - 官方示例:<https://leafletjs.com/examples.html>
374
+ - 插件列表:<https://leafletjs.com/plugins.html>
375
+ - 源码仓库:<https://github.com/Leaflet/Leaflet>
@@ -19,7 +19,7 @@ tags:
19
19
  >
20
20
  > **API 参考:** <https://docs.mapbox.com/mapbox-gl-js/api/>
21
21
  >
22
- > **最新版本:** 3.33.0(截至2026-10,npm `mapbox-gl` 与 GitHub Release 一致)
22
+ > **最新版本:** 3.33.0(截至 2026-10,npm `mapbox-gl` 与 GitHub Release 一致)
23
23
  >
24
24
  > **许可证:** v2+ 为 Mapbox 专有许可(v1.x 为 BSD-3-Clause;需 Mapbox 账号 access token)
25
25
 
@@ -406,16 +406,15 @@ map.on('load', () => {
406
406
 
407
407
  ---
408
408
 
409
- ## 参考资源
409
+ ## AI 使用建议
410
410
 
411
- - 官方文档:<https://docs.mapbox.com/mapbox-gl-js/>
412
- - API 参考:<https://docs.mapbox.com/mapbox-gl-js/api/>
413
- - 官方示例:<https://docs.mapbox.com/mapbox-gl-js/examples/>
414
- - Style Spec 样式规范:<https://docs.mapbox.com/style-spec/>
415
- - Expressions 表达式参考:<https://docs.mapbox.com/style-spec/reference/expressions/>
416
- - 源码仓库与发布记录:<https://github.com/mapbox/mapbox-gl-js>
417
- - 开源替代 MapLibre GL JS:<https://github.com/maplibre/maplibre-gl-js>
418
- - 价格说明:<https://www.mapbox.com/pricing>
411
+ - **执行环境**:`npm install`、`npm run build` 在终端中执行;Windows 下用 `npm.cmd`,长构建放后台运行。
412
+ - **先探测版本**:`npm ls mapbox-gl`(未装则 `npm view mapbox-gl version`);本技能按 3.33.0 编写,CDN 的 JS 与 CSS 必须同为 `v3.33.0`,联网时 `curl.exe -I https://api.mapbox.com/mapbox-gl-js/v3.33.0/mapbox-gl.js` 应为 200。
413
+ - **验证产物**:`npm run build` 后 `npx serve dist`,`curl.exe -I http://localhost:5173/` 确认入口;地图是否真加载、有没有 401 只能看浏览器 Network(`api.mapbox.com`),AI 助手通常看不到浏览器画面,请用户确认或提供截图后再判断。
414
+ - **token 安全**:前端只允许 `pk.` 公开 token,`sk.` 绝不能进构建产物;用 `VITE_MAPBOX_TOKEN` 等环境变量注入,提交前用 agent 的 `grep` 搜 `sk.` 与硬编码 `pk.`,回答和日志里不要回显 token。
415
+ - **许可提醒**:v2+ 是 Mapbox 专有许可并受配额计费约束;用户要求开源或免 token 时改写为 MapLibre(`maplibregl` 替代 `mapboxgl`,`mapbox://` 样式换成自建瓦片)。
416
+ - **常见症状**:`Style is not done loading` 是 `load` 事件前调了 `addSource`/`addLayer`;空白先查容器高度和 `map.resize()`;`e.features` 只在回调内有效。
417
+ - **安全与权限**:装包、起 dev server、调用计费接口前先征得用户同意,并说明可能产生费用。
419
418
 
420
419
  ## 相关技能
421
420
 
@@ -424,13 +423,13 @@ map.on('load', () => {
424
423
  - **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
425
424
  - **geoserver** — 发布 WMS/WFS/MVT 服务作为矢量瓦片数据源:[../geoserver/SKILL.md](../geoserver/SKILL.md)
426
425
 
427
- ## DeepSeek Harness 使用建议
426
+ ## 参考资源
428
427
 
429
- - **加载与引用**:用 `skill("mapbox-gl-js")` 加载(用户也可输入 `/mapbox-gl-js`);本技能无 reference 子目录,示例代码写入会话工作区工程,技能目录只读。
430
- - **执行环境**:`npm install`、`npm run build` 交给 `pwsh`;Windows 下用 `npm.cmd`,长构建用后台作业。
431
- - **先探测版本**:`npm ls mapbox-gl`(未装则 `npm view mapbox-gl version`);本技能按 3.33.0 编写,CDN 的 JS 与 CSS 必须同为 `v3.33.0`,联网时 `curl.exe -I https://api.mapbox.com/mapbox-gl-js/v3.33.0/mapbox-gl.js` 应为 200。
432
- - **验证产物**:`npm run build` 后 `npx serve dist`,`curl.exe -I http://localhost:5173/` 确认入口;地图是否真加载、有没有 401 只能看浏览器 Network(`api.mapbox.com`),DSH 不打开浏览器,请用户确认或提供截图后再 `read_image`。
433
- - **token 安全**:前端只允许 `pk.` 公开 token,`sk.` 绝不能进构建产物;用 `VITE_MAPBOX_TOKEN` 等环境变量注入,提交前用 dsh 的 `grep` 搜 `sk.` 与硬编码 `pk.`,回答和日志里不要回显 token。
434
- - **许可提醒**:v2+ 是 Mapbox 专有许可并受配额计费约束;用户要求开源或免 token 时改写为 MapLibre(`maplibregl` 替代 `mapboxgl`,`mapbox://` 样式换成自建瓦片)。
435
- - **常见症状**:`Style is not done loading` 是 `load` 事件前调了 `addSource`/`addLayer`;空白先查容器高度和 `map.resize()`;`e.features` 只在回调内有效。
436
- - **安全与权限**:装包、起 dev server、调用计费接口前先征得用户同意,并说明可能产生费用。
428
+ - 官方文档:<https://docs.mapbox.com/mapbox-gl-js/>
429
+ - API 参考:<https://docs.mapbox.com/mapbox-gl-js/api/>
430
+ - 官方示例:<https://docs.mapbox.com/mapbox-gl-js/examples/>
431
+ - Style Spec 样式规范:<https://docs.mapbox.com/style-spec/>
432
+ - Expressions 表达式参考:<https://docs.mapbox.com/style-spec/reference/expressions/>
433
+ - 源码仓库与发布记录:<https://github.com/mapbox/mapbox-gl-js>
434
+ - 开源替代 MapLibre GL JS:<https://github.com/maplibre/maplibre-gl-js>
435
+ - 价格说明:<https://www.mapbox.com/pricing>
@@ -17,7 +17,7 @@ tags:
17
17
  >
18
18
  > **官方文档:** <https://mapserver.org/>
19
19
  >
20
- > **最新版本:** 8.6.6(rel-8-6-6,[发布记录](https://github.com/MapServer/MapServer/releases))
20
+ > **最新版本:** 8.6.6(rel-8-6-6,2026-09-06 发布,截至 2026-10;[发布记录](https://github.com/MapServer/MapServer/releases))
21
21
  >
22
22
  > **许可证:** MIT
23
23
 
@@ -52,12 +52,13 @@ sudo systemctl restart apache2
52
52
 
53
53
  ### 方式二:源码编译(CMake)
54
54
 
55
- MapServer 8.x 需要支持 C++11/C99 的编译器,8.4.0 起要求 CMake 3.16+。先装依赖(GDAL、PROJ、libpng、FreeType、zlib、libcurl 为常用项):
55
+ MapServer 8.0 起需要支持 C++11/C99 的编译器;8.4.0 起要求 CMake 3.16+(官方 Unix 安装文档实测)。先装依赖(GDAL、PROJ、libpng、FreeType、zlib、libcurl 为常用项):
56
56
 
57
57
  ```bash
58
58
  sudo apt install -y build-essential cmake libgdal-dev libproj-dev \
59
59
  libpng-dev libfreetype6-dev zlib1g-dev libcurl4-openssl-dev
60
60
 
61
+ curl -fLO https://download.osgeo.org/mapserver/mapserver-8.6.6.tar.gz
61
62
  tar -zxvf mapserver-8.6.6.tar.gz
62
63
  cd mapserver-8.6.6 && mkdir build && cd build
63
64
  cmake -DCMAKE_INSTALL_PREFIX=/opt \
@@ -265,16 +266,14 @@ ogr2ogr -f GPKG clip.gpkg countries.gpkg -clipsrc 100 20 130 50
265
266
 
266
267
  ---
267
268
 
268
- ## 参考资源
269
+ ## AI 使用建议
269
270
 
270
- - 官方文档:<https://mapserver.org/>
271
- - Unix 编译安装:<https://mapserver.org/installation/unix.html>
272
- - Mapfile 参考:<https://mapserver.org/mapfile/index.html>
273
- - WMS Server:<https://mapserver.org/ogc/wms_server.html>
274
- - WFS Server:<https://mapserver.org/ogc/wfs_server.html>
275
- - 在线示例服务:<https://demo.mapserver.org/>
276
-
277
- ---
271
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 OSGeo4W 的 `mapserv.exe`);`sudo apt`、`tar -zxvf` 不跨平台,Windows 改 `Expand-Archive`,装包或改系统目录前先问用户。
272
+ - **先探测版本**:`mapserv -v`,确认输出含 `MapServer version 8.6.6` 且 `SUPPORTS=` 里有需要的 `WMS_SERVER`/`WFS_SERVER`;缺项说明该构建没编进对应库,改 mapfile 无用。
273
+ - **验证产物**:先离线 `map2img -m demo.map -o out.png -s 600 400` 看渲染,再 `mapserv -nh "QUERY_STRING=map=/abs/demo.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities"` 抓能力文档,最后才 `curl -sI "http://host/cgi-bin/mapserv?map=...&REQUEST=GetMap..."` 确认 200 与 `Content-Type: image/png`。
274
+ - **排障分流**:空白图查 `EXTENT`/`BBOX`/`PROJECTION`/`STATUS ON`;能力文档缺图层查 `wms_enable_request`、`wfs_enable_request` 与 `NAME` 是否字母开头;WFS 无属性字段是 8.x 默认行为,补 `gml_include_items`。
275
+ - **安全与权限**:`map=` 可读任意路径是 MapServer 最典型误配置,生产必须设 `MS_MAP_PATTERN`/`MS_MAP_NO_PATH`;重启 Apache/nginx 或改 CGI 权限前先向用户确认。
276
+ - **改一处验一处**:改 `WEB.METADATA` 后只重跑 `GetCapabilities`,改 `LAYER` 样式后只重跑 `map2img`,缩小排查范围。
278
277
 
279
278
  ## 相关技能
280
279
 
@@ -285,12 +284,11 @@ ogr2ogr -f GPKG clip.gpkg countries.gpkg -clipsrc 100 20 130 50
285
284
 
286
285
  ---
287
286
 
288
- ## DeepSeek Harness 使用建议
287
+ ## 参考资源
289
288
 
290
- - **加载与引用**:`skill("mapserver")` 加载;技能目录只读,mapfile、SLD 与测试数据写到会话工作区。
291
- - **执行环境**:命令交给 dsh 的 `pwsh`(Windows 用 OSGeo4W 的 `mapserv.exe`);`sudo apt`、`tar -zxvf` 不跨平台,Windows 改 `Expand-Archive`,装包或改系统目录前先问用户。
292
- - **先探测版本**:`mapserv -v`,确认输出含 `MapServer version 8.6.6` 且 `SUPPORTS=` 里有需要的 `WMS_SERVER`/`WFS_SERVER`;缺项说明该构建没编进对应库,改 mapfile 无用。
293
- - **验证产物**:先离线 `map2img -m demo.map -o out.png -s 600 400` 看渲染,再 `mapserv -nh "QUERY_STRING=map=/abs/demo.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities"` 抓能力文档,最后才 `curl -sI "http://host/cgi-bin/mapserv?map=...&REQUEST=GetMap..."` 确认 200 与 `Content-Type: image/png`。
294
- - **排障分流**:空白图查 `EXTENT`/`BBOX`/`PROJECTION`/`STATUS ON`;能力文档缺图层查 `wms_enable_request`、`wfs_enable_request` 与 `NAME` 是否字母开头;WFS 无属性字段是 8.x 默认行为,补 `gml_include_items`。
295
- - **安全与权限**:`map=` 可读任意路径是 MapServer 最典型误配置,生产必须设 `MS_MAP_PATTERN`/`MS_MAP_NO_PATH`;重启 Apache/nginx 或改 CGI 权限前先向用户确认。
296
- - **改一处验一处**:改 `WEB.METADATA` 后只重跑 `GetCapabilities`,改 `LAYER` 样式后只重跑 `map2img`,缩小排查范围。
289
+ - 官方文档:<https://mapserver.org/>
290
+ - Unix 编译安装:<https://mapserver.org/installation/unix.html>
291
+ - Mapfile 参考:<https://mapserver.org/mapfile/index.html>
292
+ - WMS Server:<https://mapserver.org/ogc/wms_server.html>
293
+ - WFS Server:<https://mapserver.org/ogc/wfs_server.html>
294
+ - 在线示例服务:<https://demo.mapserver.org/>
@@ -36,11 +36,24 @@ tags:
36
36
  ## 安装
37
37
 
38
38
  ```bash
39
- dotnet add package Mapsui.Wpf # 或 Mapsui.Maui / Mapsui.Avalonia / ...
40
- dotnet add package Mapsui.Tiling
41
- dotnet add package Mapsui.Nts
39
+ # 按 UI 框架选一个
40
+ dotnet add package Mapsui.Wpf --version 5.1.0 # WPF(net8.0-windows / net9.0-windows)
41
+ dotnet add package Mapsui.Maui --version 5.1.0 # MAUI,或 Mapsui.Avalonia / Mapsui.WinUI / Mapsui.Blazor
42
+ # 按数据源按需追加
43
+ dotnet add package Mapsui.Tiling --version 5.1.0 # 瓦片底图
44
+ dotnet add package Mapsui.Nts --version 5.1.0 # NTS 几何 / Shapefile
42
45
  ```
43
46
 
47
+ ### 验证
48
+
49
+ ```bash
50
+ dotnet --list-sdks # 需 .NET 8/9 SDK
51
+ dotnet restore # 能解析 Mapsui 5.1.0 即包可用
52
+ dotnet build # 编译通过后才进入渲染验证
53
+ ```
54
+
55
+ > 所有 `Mapsui.*` 子包版本必须一致(同样写 5.1.0),混版会在运行时抛类型加载异常。
56
+
44
57
  ---
45
58
 
46
59
  ## WPF 入门
@@ -85,19 +98,27 @@ MapControl.Map = map;
85
98
  ```csharp
86
99
  using Mapsui.Nts;
87
100
  using Mapsui.Styles;
101
+ using NetTopologySuite.NtsGeometryServices;
88
102
 
89
- var features = new List<IFeature>();
90
- foreach (var f in geoJsonFeatures)
91
- features.Add(new GeometryFeature(f.Geometry) {
103
+ // 视图坐标系为 EPSG:3857,经纬度数据必须先投影
104
+ var factory = NtsGeometryServices.Instance.CreateGeometryFactory(3857);
105
+
106
+ var features = new List<IFeature>
107
+ {
108
+ new GeometryFeature(factory.CreatePoint(SphericalMercator.FromLonLat(116.397, 39.908).ToCoordinate()))
109
+ {
92
110
  Styles = { new VectorStyle {
93
111
  Fill = new Brush(Color.Red),
94
112
  Outline = new Pen(Color.Black, 1)
95
113
  }}
96
- });
114
+ }
115
+ };
97
116
 
98
117
  map.Layers.Add(new MemoryLayer("Roads") { Features = features, Style = null });
99
118
  ```
100
119
 
120
+ > 线/面要素用 `factory.CreateLineString(coords)` / `factory.CreatePolygon(shell, holes)`,坐标同样要先 `SphericalMercator.FromLonLat` 投影。
121
+
101
122
  ---
102
123
 
103
124
  ## Shapefile
@@ -179,85 +200,101 @@ MapControl.Info += (s, e) => {
179
200
 
180
201
  ---
181
202
 
182
- ## 性能优化
183
-
184
- 1. 海量点 → `RasterizingTileLayer` 包一层(按瓦片预渲染)
185
- 2. 优先 `MemoryLayer` + 缓存 Feature
186
- 3. 异步加载 + `await Layer.WaitForFinishedRefresh()`
187
- 4. 共享 Brush/Pen/Style 实例
188
- 5. SkiaSharp 关闭抗锯齿对极小符号有性能提升
189
-
190
- ---
191
-
192
- ## 常见问题
193
-
194
- | 问题 | 解决 |
195
- |------|------|
196
- | WPF 无图 | NuGet 缺 `Mapsui.Wpf` 或没设置 `MapControl.Map` |
197
- | 找不到 `Mapsui.UI.Wpf` 包 | NuGet 包名为 `Mapsui.Wpf`(v3 起启用该名称;程序集仍为 `Mapsui.UI.Wpf.dll`) |
198
- | 投影错误 | `SphericalMercator.FromLonLat` 转换 |
199
- | MAUI 空白 | `MauiProgram` 中 `UseSkiaSharp()` + `UseMapsui()` |
200
- | Shapefile 中文乱码 | 指定 Encoding |
201
- | `GeometryFeature` / 瓦片类型找不到 | 矢量要素需安装 `Mapsui.Nts`,瓦片图层需安装 `Mapsui.Tiling` |
202
-
203
- ---
204
-
205
203
  ## 典型工作流
206
204
 
207
205
  ### 工作流 1:加载底图 + GeoJSON 矢量数据
208
206
 
207
+ 输入 POI 记录(含 `Lon` / `Lat` / `Name`),输出 WPF 窗口里可拖拽缩放的底图 + 红色点图层。
208
+
209
209
  ```csharp
210
210
  using Mapsui;
211
211
  using Mapsui.Tiling;
212
212
  using Mapsui.Nts;
213
213
  using Mapsui.Styles;
214
- using NetTopologySuite.IO;
214
+ using Mapsui.Projections;
215
215
 
216
216
  var map = new Map();
217
217
 
218
- // 1. 添加 OSM 底图
218
+ // 1. OSM 底图(来自 Mapsui.Tiling)
219
219
  map.Layers.Add(OpenStreetMap.CreateTileLayer());
220
220
 
221
- // 2. 读取 GeoJSON 并添加为矢量图层
222
- var gjReader = new GeoJsonReader();
221
+ // 2. 构造点图层。Mapsui 的视图坐标系默认是 Web Mercator(EPSG:3857),
222
+ // GeoJSON/业务数据里的经纬度必须先投影,否则会画到南太平洋附近。
223
223
  var features = new List<IFeature>();
224
- foreach (var f in geojsonFeatures)
224
+ var factory = NetTopologySuite.NtsGeometryServices.Instance.CreateGeometryFactory(3857);
225
+
226
+ foreach (var item in poiList) // item:含 Lon / Lat / Name 的 POI 记录
225
227
  {
226
- features.Add(new GeometryFeature(f.Geometry)
228
+ var p = SphericalMercator.FromLonLat(item.Lon, item.Lat).ToCoordinate();
229
+ var feature = new GeometryFeature(factory.CreatePoint(p)) { ["name"] = item.Name };
230
+ feature.Styles.Add(new SymbolStyle
227
231
  {
228
- Styles = { new VectorStyle { Fill = new Brush(Color.Red) } }
232
+ SymbolScale = 0.8,
233
+ Fill = new Brush(Color.Red),
234
+ Outline = new Pen(Color.White, 1)
229
235
  });
236
+ features.Add(feature);
230
237
  }
231
- map.Layers.Add(new MemoryLayer("Data") { Features = features });
238
+ var dataLayer = new MemoryLayer("Data") { Features = features, Style = null };
239
+ map.Layers.Add(dataLayer);
232
240
 
233
- // 3. 定位
241
+ // 3. 定位到北京
234
242
  var center = SphericalMercator.FromLonLat(116.4, 39.9).ToMPoint();
235
243
  map.Navigator.CenterOnAndZoomTo(center, map.Navigator.Resolutions[10]);
236
244
 
237
- MapControl.Map = map;
245
+ MapControl.Map = map; // 忘记这一步窗口就是空白
238
246
  ```
239
247
 
240
248
  ### 工作流 2:Shapefile + WMS 叠加
241
249
 
250
+ 输入 `data/china.shp` 与返回 `rivers` 图层的 WMS,输出底图 + 行政界 + 河流栅格图层。
251
+
242
252
  ```csharp
243
- // Shapefile 图层
244
- var shpProvider = new ShapeFile("china.shp", true);
253
+ using Mapsui.Nts.Providers.Shapefile;
254
+ using Mapsui.Providers.Wms;
255
+
256
+ // 1. Shapefile 矢量层(需 Mapsui.Nts)
257
+ var shpProvider = new ShapeFile("data/china.shp", true);
245
258
  map.Layers.Add(new Layer("China") { DataSource = shpProvider });
246
259
 
247
- // WMS 图层(叠加)
260
+ // 2. WMS 栅格层:构造参数依次为服务地址,图层名数组
248
261
  var wmsProvider = new WmsProvider("https://geo.example.com/wms?", new[] { "rivers" });
249
262
  map.Layers.Add(new ImageLayer("Rivers") { DataSource = wmsProvider });
250
263
 
251
264
  map.ZoomToExtents();
252
265
  ```
253
266
 
254
- ## DeepSeek Harness 使用建议
267
+ **验证产物**:`dotnet build` 通过不等于出图。无头环境用 `Mapsui.Rendering.Skia.MapRenderer` 把 `map` 渲染成 PNG 再打开 PNG 检查;有窗口时请用户运行后提供截图。
268
+
269
+ ## 性能优化
270
+
271
+ 1. 海量点 → `RasterizingTileLayer` 包一层(按瓦片预渲染)
272
+ 2. 优先 `MemoryLayer` + 缓存 Feature
273
+ 3. 异步加载 + `await Layer.WaitForFinishedRefresh()`
274
+ 4. 共享 Brush/Pen/Style 实例
275
+ 5. SkiaSharp 关闭抗锯齿对极小符号有性能提升
276
+
277
+ ---
278
+
279
+ ## 常见问题
280
+
281
+ | 问题 | 解决 |
282
+ |------|------|
283
+ | WPF 无图 | NuGet 缺 `Mapsui.Wpf` 或没设置 `MapControl.Map` |
284
+ | 找不到 `Mapsui.UI.Wpf` 包 | NuGet 包名为 `Mapsui.Wpf`(v3 起启用该名称;程序集仍为 `Mapsui.UI.Wpf.dll`) |
285
+ | 投影错误 | `SphericalMercator.FromLonLat` 转换 |
286
+ | MAUI 空白 | `MauiProgram` 中 `UseSkiaSharp()` + `UseMapsui()` |
287
+ | Shapefile 中文乱码 | Mapsui 的 DBF 默认按 UTF-7 解析,中文会乱码:`.dbf` 缺 .cpg 声明时按实际编码赋值 `new ShapeFile(path, true) { Encoding = Encoding.GetEncoding("GBK") }`(属性赋值,不是构造参数) |
288
+ | `GeometryFeature` / 瓦片类型找不到 | 矢量要素需安装 `Mapsui.Nts`,瓦片图层需安装 `Mapsui.Tiling` |
289
+
290
+ ---
291
+
292
+ ## AI 使用建议
255
293
 
256
- - **加载与引用**:用 `skill("mapsui")` 加载(用户也可输入 `/mapsui`);示例写入会话工作区的 .NET 工程,技能目录只读。
257
- - **执行环境**:先 `dotnet --list-sdks`;Mapsui 5.1.0 的目标框架是 net8.0/net9.0(`Mapsui.Wpf` 为 net8.0-windows/net9.0-windows),低于 .NET 8 的工程不能直接引用。命令交给 `pwsh`,例如 `dotnet add package Mapsui.Wpf --version 5.1.0`。
258
- - **验证产物**:`dotnet build` 只证明编译通过;无头渲染用 `Mapsui.Rendering.Skia.MapRenderer.RenderToBitmapStream(map, ...)` 输出 PNG 的 MemoryStream(参数以 IntelliSense 为准),落盘后 `read_image` 检查;WinForms/WPF 窗口 DSH 看不到,需用户运行后提供截图。
294
+ - **执行环境**:先 `dotnet --list-sdks`;Mapsui 5.1.0 的目标框架是 net8.0/net9.0(`Mapsui.Wpf` 为 net8.0-windows/net9.0-windows),低于 .NET 8 的工程不能直接引用。命令在终端中执行,例如 `dotnet add package Mapsui.Wpf --version 5.1.0`。
295
+ - **验证产物**:`dotnet build` 只证明编译通过;无头渲染用 `Mapsui.Rendering.Skia.MapRenderer.RenderToBitmapStream(map, ...)` 输出 PNG 的 MemoryStream(参数以 IntelliSense 为准),落盘后打开 PNG 检查;WinForms/WPF 窗口 AI 助手 看不到,需用户运行后提供截图。
259
296
  - **投影**:定位坐标必须 `SphericalMercator.FromLonLat(lon, lat)` 转换,直接用经纬度会定位到南太平洋。
260
- - **数据**:Shapefile 中文要指定 `Encoding`(UTF8 或 GBK);矢量要素装 `Mapsui.Nts`,瓦片装 `Mapsui.Tiling`,UI 包装 `Mapsui.Wpf`/`Mapsui.Maui`。
297
+ - **数据**:Shapefile 中文要设 `ShapeFile.Encoding`(UTF8 或 GBK);矢量要素装 `Mapsui.Nts`,瓦片装 `Mapsui.Tiling`,UI 包装 `Mapsui.Wpf`/`Mapsui.Maui`。
261
298
  - **常见症状**:`MapControl` 空白先查是否赋值 `MapControl.Map`;MAUI 空白查 `UseSkiaSharp()` 与 `UseMapsui()` 是否注册。
262
299
  - **安全与权限**:新建工程、装包、运行桌面程序前先征得用户同意;PostGIS/瓦片服务的密码不要写进代码或回答。
263
300
 
@@ -39,21 +39,29 @@ NTS 与 JTS API 几乎一一对应(C# 命名风格):
39
39
 
40
40
  ```bash
41
41
  dotnet add package NetTopologySuite --version 2.6.0
42
- dotnet add package NetTopologySuite.IO.GeoJSON --version 4.0.0
43
- dotnet add package NetTopologySuite.IO.Esri.Shapefile --version 1.2.0 # Shapefile 读写(Shapefile.ReadAllFeatures 等)
44
- dotnet add package ProjNet --version 2.1.0 # 坐标变换(可选)
42
+
43
+ # GeoJSON:按序列化框架二选一(不要同时装)
44
+ dotnet add package NetTopologySuite.IO.GeoJSON --version 4.0.0 # Newtonsoft.Json
45
+ dotnet add package NetTopologySuite.IO.GeoJSON4STJ --version 4.0.0 # System.Text.Json
46
+
47
+ dotnet add package NetTopologySuite.IO.Esri.Shapefile --version 1.2.0 # Shapefile 读写
48
+ dotnet add package ProjNet --version 2.1.0 # 坐标变换(可选)
45
49
  ```
46
50
 
47
- **.NET 6+** 推荐;IO 包需与主库 2.6 对齐(IO.GeoJSON 4.0.0 / IO.Esri.Shapefile 1.2.0 / ProjNet 2.1.0)。
51
+ **.NET 6+** 推荐;各 IO 包需与主库 2.6 对齐(IO.GeoJSON / IO.GeoJSON4STJ / IO.Esri.Shapefile 均为 4.0.0、1.2.0 一档,ProjNet 2.1.0)。
48
52
 
49
53
  ---
50
54
 
51
55
  ## 核心 API:几何工厂
52
56
 
53
57
  ```csharp
58
+ using NetTopologySuite;
54
59
  using NetTopologySuite.Geometries;
55
60
 
56
- var gf = new GeometryFactory(new PrecisionModel(), 4326);
61
+ // 推荐:由 NtsGeometryServices 提供工厂(也可继续用 new GeometryFactory(new PrecisionModel(), 4326))
62
+ var gf = NtsGeometryServices.Instance.CreateGeometryFactory(srid: 4326);
63
+
64
+ // 等价旧写法:var gf = new GeometryFactory(new PrecisionModel(), 4326);
57
65
 
58
66
  var p = gf.CreatePoint(new Coordinate(116.397, 39.908));
59
67
  var ls = gf.CreateLineString(new[] {
@@ -90,22 +98,45 @@ bool ok = polyA.Relate(polyB, "T*F**F***");
90
98
  ## WKT / WKB / GeoJSON
91
99
 
92
100
  ```csharp
101
+ using NetTopologySuite;
93
102
  using NetTopologySuite.IO;
94
103
 
95
- var rdr = new WKTReader();
104
+ // NTS 2.6 起推荐由 NtsGeometryServices 提供工厂(WKTReader(GeometryFactory) 已标记过时)
105
+ var services = NtsGeometryServices.Instance;
106
+ var rdr = new WKTReader(services);
96
107
  var g = rdr.Read("POINT (116.4 39.9)");
97
108
 
98
109
  string wkt = new WKTWriter().Write(g);
99
110
  byte[] wkb = new WKBWriter().Write(g);
111
+ ```
100
112
 
101
- using NetTopologySuite.IO.Converters;
113
+ GeoJSON 有两种包,按序列化框架二选一(两者都需与主库 2.6 对齐,均取 4.0.0):
114
+
115
+ | 包 | 序列化框架 | 用法 |
116
+ |---|---|---|
117
+ | `NetTopologySuite.IO.GeoJSON` | Newtonsoft.Json 13.x | `new GeoJsonReader()` / `new GeoJsonWriter()` |
118
+ | `NetTopologySuite.IO.GeoJSON4STJ` | System.Text.Json | `opts.Converters.Add(new GeoJsonConverterFactory())` |
119
+
120
+ ```csharp
121
+ using NetTopologySuite.IO.Converters; // 来自 NetTopologySuite.IO.GeoJSON4STJ
102
122
  using System.Text.Json;
123
+
103
124
  var opts = new JsonSerializerOptions();
104
125
  opts.Converters.Add(new GeoJsonConverterFactory());
105
126
  string json = JsonSerializer.Serialize(g, opts);
106
127
  var g2 = JsonSerializer.Deserialize<Geometry>(json, opts);
107
128
  ```
108
129
 
130
+ Newtonsoft 方案:
131
+
132
+ ```csharp
133
+ using NetTopologySuite.IO;
134
+
135
+ var writer = new GeoJsonWriter();
136
+ string json2 = writer.Write(g);
137
+ var g3 = new GeoJsonReader().Read(json2);
138
+ ```
139
+
109
140
  ---
110
141
 
111
142
  ## Shapefile
@@ -196,11 +227,50 @@ double[] xy = ct.MathTransform.Transform(new[] { 116.397, 39.908 });
196
227
 
197
228
  ## 典型工作流
198
229
 
199
- 1. **创建几何工厂**:使用 `new GeometryFactory(new PrecisionModel(), 4326)` 创建工厂,SRID 指定坐标系
200
- 2. **创建几何对象**:通过工厂方法 `CreatePoint()`、`CreateLineString()`、`CreatePolygon()` 创建几何
201
- 3. **空间运算**:直接调用几何对象方法 `Intersects()`、`Intersection()`、`Buffer()` 等
202
- 4. **格式读写**:使用 `WKTReader`/`WKTWriter`、`GeoJsonConverterFactory` 进行序列化
203
- 5. **EF Core 集成**:`UseNetTopologySuite()` 启用空间查询翻译为 SQL
230
+ 端到端:WKT 读入 → 有效性修复 → 空间运算 → 写 GeoJSON / 入库。
231
+
232
+ ```csharp
233
+ using NetTopologySuite;
234
+ using NetTopologySuite.Geometries;
235
+ using NetTopologySuite.Geometries.Utilities;
236
+ using NetTopologySuite.IO;
237
+ using NetTopologySuite.IO.Converters; // NetTopologySuite.IO.GeoJSON4STJ
238
+ using System.Text.Json;
239
+
240
+ // 1. 读入两个输入几何(第二个是自相交的"蝴蝶结",无效)
241
+ var services = NtsGeometryServices.Instance;
242
+ var reader = new WKTReader(services);
243
+ Geometry parcel = reader.Read("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))");
244
+ Geometry zone = reader.Read("POLYGON ((5 5, 15 15, 15 5, 5 15, 5 5))");
245
+
246
+ // 2. 校验并修复(GeometryFixer 可能把无效面拆成 MultiPolygon)
247
+ Console.WriteLine(zone.IsValid); // False
248
+ if (!zone.IsValid)
249
+ zone = GeometryFixer.Fix(zone); // 修成 MultiPolygon,IsValid=True
250
+
251
+ // 3. 空间运算:求交 + 缓冲
252
+ Geometry overlap = parcel.Intersection(zone);
253
+ Geometry buffered = overlap.Buffer(1.0);
254
+ Console.WriteLine(overlap.Area); // 12.5(两三角形在方形内的部分)
255
+
256
+ // 4. 写 GeoJSON(System.Text.Json 转换器,需 GeoJSON4STJ 包)
257
+ var opts = new JsonSerializerOptions();
258
+ opts.Converters.Add(new GeoJsonConverterFactory());
259
+ string geoJson = JsonSerializer.Serialize(buffered, opts);
260
+
261
+ // 5. 回读校验
262
+ Geometry back = JsonSerializer.Deserialize<Geometry>(geoJson, opts);
263
+ Console.WriteLine(back.IsValid); // True
264
+ ```
265
+
266
+ **输出与验收**:`geoJson` 能以 `JsonSerializer.Deserialize<Geometry>` 读回且 `back.IsValid` 为 `true`;`overlap.Area` 为 12.5(面积只在投影/平面坐标下有实际含义,经纬度下是平面近似值)。
267
+
268
+ **其他常用步骤**:
269
+
270
+ 1. **创建几何工厂**:跨方法共享同一个 `GeometryFactory` 并固定 SRID,避免几何间 SRID 不一致
271
+ 2. **空间索引**:数据量超过几千条时先建 `STRtree`,再做批量 `Intersects` 粗筛
272
+ 3. **格式读写**:`WKTReader`/`WKTWriter`、`GeoJsonConverterFactory`;Shapefile 走 `NetTopologySuite.IO.Esri`
273
+ 4. **EF Core 集成**:`UseNetTopologySuite()` 让 `Distance()`/`Intersects()` 翻译为空间 SQL
204
274
 
205
275
  ---
206
276
 
@@ -226,30 +296,31 @@ foreach (var p in points) if (prep.Contains(p)) ...
226
296
  | `TopologyException` | `GeometryFixer.Fix` 修复无效几何 |
227
297
  | EF Core 类型冲突 | 用 `UseNetTopologySuite()` 而非 `Microsoft.SqlServer.Types` |
228
298
  | Z/M 坐标丢失 | 配置 `WKBWriter` 的 `HandleOrdinates` |
299
+ | 找不到 `GeoJsonConverterFactory` | 该类属于 `NetTopologySuite.IO.GeoJSON4STJ`(System.Text.Json),不是 `NetTopologySuite.IO.GeoJSON`(Newtonsoft) |
229
300
  | Buffer 慢 | 减小 quadrantSegments、并行处理 |
230
301
  | Shapefile 读取写法报错 | 使用 `NetTopologySuite.IO.Esri.Shapefile` 包与 `NetTopologySuite.IO.Esri` 命名空间(`Shapefile.ReadAllFeatures`) |
231
302
  | 依赖版本不匹配(NTS 2.6 与旧 IO 包) | 对齐版本:IO.GeoJSON 4.0.0、IO.Esri.Shapefile 1.2.0、ProjNet 2.1.0 |
232
303
 
233
304
  ---
234
305
 
235
- ## DeepSeek Harness 使用建议
306
+ ## AI 使用建议
236
307
 
237
- - **加载与引用**:`skill("nettopologysuite")` 加载;技能目录只读,示例工程与测试数据写到会话工作区。
238
- - **执行环境**:命令交给 dsh 的 `pwsh`;先 `dotnet --version` 确认 SDK 6.0+,`dotnet restore` 需要访问 NuGet。
239
- - **先探测版本**:`dotnet list package` 核对 `NetTopologySuite` 2.6.0、`NetTopologySuite.IO.GeoJSON` 4.0.0、`NetTopologySuite.IO.Esri.Shapefile` 1.2.0、`ProjNet` 2.1.0;IO 包与主库错配是常见编译/运行期报错源。
308
+ - **执行环境**:命令在终端 / shell 中执行;先 `dotnet --version` 确认 SDK 6.0+,`dotnet restore` 需要访问 NuGet。
309
+ - **先探测版本**:`dotnet list package` 核对 `NetTopologySuite` 2.6.0、`NetTopologySuite.IO.GeoJSON`(或 `IO.GeoJSON4STJ`)4.0.0、`NetTopologySuite.IO.Esri.Shapefile` 1.2.0、`ProjNet` 2.1.0;IO 包与主库错配是常见编译/运行期报错源。
240
310
  - **验证产物**:`dotnet build` 后跑 `dotnet test`,或最小控制台做 WKT 往返 + `IsValid` 断言;`GeoJsonConverterFactory` 序列化后再反序列化,比对坐标数而不是只打日志。
241
311
  - **失败信号**:`TopologyException` 先 `GeometryFixer.Fix`;程序集加载/`TypeInitializationException` 多为 IO 包版本不匹配;EF Core 类型冲突是同时引了 `Microsoft.SqlServer.Types`。
242
312
  - **注意事项**:NTS 的 SRID 只是元数据、计算在平面进行,跨投影交给 ProjNet;`WKBWriter` 默认丢 Z/M,需设 `HandleOrdinates`。
243
- - **按需读文件**:本 SKILL 代码块较多,先按章节标题定位再用 `read` 取行区间,比整篇读更省上下文。
313
+ - **按需读文件**:本 SKILL 代码块较多,先按章节标题定位再分段读取,比整篇读更省上下文。
244
314
 
245
315
  ## NTS 家族与相关库
246
316
 
247
317
  | 包 | 用途 |
248
318
  |----|------|
249
319
  | `NetTopologySuite.IO.VectorTiles` | Mapbox Vector Tiles(MVT)读写 |
250
- | `NetTopologySuite.IO.GeoJSON` | GeoJSON 读写 |
251
- | `NetTopologySuite.IO.Esri` | Shapefile(ESRI)读写 |
252
- | `ProjNet4GeoAPI` | 坐标参考系与投影变换 |
320
+ | `NetTopologySuite.IO.GeoJSON` | GeoJSON 读写(Newtonsoft.Json) |
321
+ | `NetTopologySuite.IO.GeoJSON4STJ` | GeoJSON 读写(System.Text.Json,提供 `GeoJsonConverterFactory`) |
322
+ | `NetTopologySuite.IO.Esri.Shapefile` | Shapefile 读写(命名空间 `NetTopologySuite.IO.Esri`) |
323
+ | `ProjNet` | 坐标参考系与投影变换(当前主线 2.1.0;旧包 `ProjNet4GeoAPI` 停在 1.4.1,新项目用 `ProjNet`) |
253
324
 
254
325
  ## 相关技能
255
326