开源GIS技能包 znlgis/dsh-opengis-skill

@dsh-gis/dsh-opengis-skill

English summary — 一个 DeepSeek Harness bundle，把 opengis-skills 的 gis/ 技能打包成可安装、可启停的技能。会话目录只列出名称与描述；技能正文及其 reference/.md 文件按需加载。随包分发的正文与上游逐字节一致，加载技能时会追加独立的 adaptations/ 层——每个技能一段 DeepSeek Harness 指引，另有一段共享指引（Windows 上的工具映射、版本探测、产物校验、后台任务、权限）。零运行时依赖：所有资产都随 npm 包分发。

兼容性：DeepSeek Harness >=0.2.0-rc.2 <0.3.0-0；Node.js >=22，仅开发时需要。MIT 许可。

DeepSeek Harness 的 OpenGIS 技能包插件：把 opengis-skills 中 gis/ 分类的 GIS 技能打包成可安装、可启停的 DSH bundle。会话技能目录只列出名称与描述，技能正文与参考资料按需加载。

特性

- 覆盖 GIS 全链路（40 个技能）：GDAL、GDAL API、QGIS（qgis_process / PyQGIS / QGIS Server）、GeoServer（含 REST API 与 Cloud）、GeoNode、MapServer、PostGIS、DuckDB Spatial、SpatiaLite、PROJ、ProjNet4GeoAPI、PDAL、GRASS GIS、WhiteboxTools、JTS、NetTopologySuite、Esri Geometry API（Java/.NET）、Shapely、GeoPandas、GeoPipeAgent、OpenGisDAF、CesiumJS、OpenLayers、Leaflet、BruTile、Mapbox GL JS、deck.gl、Kepler.gl、GeoLibre、SharpMap、Mapsui、GeoTools、OpenGIS Utils（Java/.NET），以及 opengis-all 全流程索引。
- 按需加载：注册的是 skill provider（ctx.skills.registerProvider），发现阶段只读 frontmatter；正文每次加载时读取，参考资料（reference/.md）通过技能目录（resource base）相对解析。
- 零运行时依赖：只用 Node 内置模块，不 import DSH 内部包；全部资产与适配文件随 npm 包分发，整个包解包后约 985 kB（其中技能资产约 800 kB、适配层约 80 kB）。
- 可同步上游：npm run sync 从 opengis-skills 检出复制资产，记录上游 commit 与每个文件的 SHA-256 到 upstream.json，并重新生成本文下方技能清单。
- 可启停：单包同时是 bundle 与插件（dsh.bundle.patch 插入自身行），在 Plugins 里启用/停用即可。
- 分层适配 DSH：assets/ 保持上游逐字节快照（SHA-256 清单可校验），DSH 专属建议单独放在 adaptations/：common.md 是通用执行约定，<skill>.md 是该技能的执行建议（按需读哪个 reference、命令走 ops_bash 还是 pwsh、先探测什么版本、产物怎么验证、哪些操作要先确认）。加载技能时由 provider 把两段拼到正文之后，技能正文保持原样。

兼容性

- DeepSeek Harness：>=0.2.0-rc.2 <0.3.0-0（package.json 的 engines.dsh）。本包通过 Host 提供的 ctx.skills 注册 provider，遵循 @deepseek-ai/dsh-skill 的 registry API 与 candidate/definition 契约；该契约在 0.2.0-rc.2 与 0.2.1-rc.2 之间字节一致，dsh.bundle.patch、locale 与图标元数据在 0.2.0-rc.2 已经可用。
- Node.js：>=22（engines.node）。仅开发脚本与测试需要，插件本身运行在 DSH 内。
- 运行时依赖：无。dependencies 为空，只使用 Node 内置模块，不 import DSH 内部包。

技能清单

共 40 个技能，描述取自上游 frontmatter。

| Skill | Description (upstream frontmatter) |
| brutile | 在 .NET 中用 BruTile 6.0.0 获取或枚举地图瓦片时使用 —— 基于 HttpClient 的 HttpTileSource、KnownTileSources.Create、按视口和分辨率调用 ITileSchema.GetTileInfos、离线 MBTiles 用 MbTilesTileSource，或把瓦片接入 Mapsui/SharpMap。也适用于缺少 'BruTile.Desktop' 包、KnownTileSources 报 CS0246、MBTiles SQLite 原生库加载失败，以及 TMS/OSM y 轴反转导致的 404。 |
| cesiumjs | 用 npm cesium 1.146.0 构建浏览器端 3D 地球、3D Tiles、CZML/时态数据或 glTF 模型时使用 —— Viewer、Cesium3DTileset、Ion token（Cesium.Ion.defaultAccessToken）、Workers/Assets/Widgets 的 CESIUM_BASE_URL、GCJ-02 瓦片偏移，或排查 Vite/Webpack 构建后黑屏。 |
| deck-gl | 在浏览器中用 deck.gl 9.4.0 可视化大规模地理空间数据集时使用 —— ScatterplotLayer/GeoJsonLayer、HexagonLayer/ScreenGridLayer 聚合、MVTLayer/TileLayer、在 MapLibre 上叠加 @deck.gl/mapbox MapboxOverlay，或排查画布空白、数据 props 不更新、@deck.gl/* 子包版本不一致。 |
| duckdb-spatial | 在 DuckDB 数据库或 SQL 管道里做空间分析时使用 —— INSTALL spatial / LOAD spatial、用 ST_Read 读取 Shapefile/GeoPackage/GeoJSON、ST_Point/ST_GeomFromText、ST_Intersects/ST_Contains/ST_Buffer 连接、ST_Area_Spheroid、ST_AsMVT 瓦片、浏览器里的 DuckDB-WASM；也适用于报「Extension spatial is not installed」或空间函数不存在、GEOMETRY 与 WKB_BLOB 之间的摩擦，以及把查询结果导出为 GeoParquet。DuckDB 2.0 内置 spatial 扩展。 |
| gdal | 通过 GDAL/OGR 命令行处理地理空间栅格/矢量数据时使用 —— ogr2ogr 格式转换（Shapefile/GeoPackage/GeoJSON）、gdalwarp 重投影、gdal_translate、gdal_calc.py 算 NDVI、COG、镶嵌、DEM 等高线、gdalinfo -json 检查 —— 或诊断「not recognized as a supported file format」；也涵盖 3.11+ 统一的 gdal raster / gdal vector 命令行。 |
| gdal-api | 用 C、C++、Python、Java 或 .NET 对 GDAL/OGR 编程时使用 —— 栅格/矢量读写、gdal.UseExceptions、OGRSpatialReference 坐标变换、gdal.Translate / gdal.Warp、VRT/COG，或修复「no driver registered」和 UnsatisfiedLinkError；C++ 用 gdal-config，Maven 用 org.gdal:gdal 3.13.0，NuGet 用 MaxRev.Gdal.Core。 |
| geolibre | 为 GeoLibre GIS 应用写脚本或自托管时使用 —— geolibre Python anywidget（Map/add_geojson/add_cog/save_project）、供 AI 智能体使用的 geolibre-mcp stdio 服务器、ghcr.io/opengeos/geolibre Docker 镜像、DuckDB-WASM SQL 工作区、?data= 和 ?url= 深链；也适用于 Linux WebKitGTK 下窗口空白、GEOLIBRE_CONVERSION_ROOTS 不允许 sidecar 路径、Jupyter relay 未连接。GeoLibre 3.5.1。 |
| geometry-api-java | 在 Java 中处理 Esri 几何类型（Point、Polyline、Polygon、Envelope）时使用 —— GeometryEngine、com.esri.geometry:esri-geometry-api:2.2.4、WKT/WKB/GeoJSON/Esri JSON 读写、测地距离；也适用于 GeometryEngine 没有 intersects 或 WKB 方法、需要 OperatorFactoryLocal 的场景，或 2.3.1 坐标在 Maven Central 上无法解析的情况。Esri Geometry API for Java。 |
| geometry-api-net | 在 .NET/C# 中处理 Esri 几何类型（Point、Polyline、Polygon、Envelope）时使用 —— GeometryEngine、NuGet OpenGIS.Esri.Geometry.Core 1.0.9、WKT/EWKT、WKB、GeoJSON 与 Esri JSON 读写、System.Text.Json 转换器、测地距离；也适用于未闭合的多边形环、叠加分析后 Geometry 基类转换，或已退役的 Esri/geometry-api-net 仓库。Esri Geometry API for .NET。 |
| geonode | 部署或自动化 GeoNode 5.1.1 时使用 —— 用 create-envfile.py 跑 docker compose、geonode/geonode:5.1.1 镜像、django4geonode 日志、/api/v2/resources 与 /api/v2/uploads/upload（action=upload\|replace\|upsert\|create）、从 resource.links[] 取 OGC WMS/WFS 链接、geonode-project 定制；也适用于 compose up 后出现 502、升级后报「GeoNode has no attribute」、以及 Basic 与 Bearer 认证下上传返回 401/403 的情况。 |
| geopandas | 在 Python 中做矢量空间分析时使用 —— 通过 pyogrio 调 gpd.read_file/to_file（GPKG、Shapefile、GeoParquet）、sjoin/sjoin_nearest、overlay、clip、dissolve、to_crs 与 set_crs 的区别、gdf.plot 分级设色图；也适用于 PROJ 数据目录缺失导致的 CRSError、以度为单位计算面积/距离、或 GeoDataFrame 几何列冲突。GeoPandas 1.2.0 为 pandas DataFrame 扩展了几何列。 |
| geopipe-agent | 用 GeoPipeAgent 构建 YAML GIS 流水线时使用 —— geopipe-agent validate/run、io.read_vector → vector.buffer → io.write_vector 链、36 个内置步骤（33 个分析 + 3 个透传）、qc.geometry_validity/attribute_completeness/topology、native_python\|qgis_process\|gdal_cli 后端、$step.output 引用；也适用于 validate 报「not registered」错误、when 条件静默跳过、以及 resolve/knowledge 缺口。0.1.0，仅支持源码安装（未上 PyPI）。 |
| geoserver | 部署 GeoServer 3.0.x 发布 WMS/WFS/WMTS/WCS/MVT 时使用，或配置 SLD/CSS 样式、RBAC 安全、GeoWebCache 切片预热。涵盖 geoserver-3.0.2-bin.zip、Java 17/21 上的 docker.osgeo.org/geoserver:3.0.2、/rest/about/version.json、原生边界错误导致 GetMap 空白、以及 Shapefile 字符集乱码。 |
| geoserver-cloud | 在 Docker Compose 或 Kubernetes 上部署 GeoServer Cloud 3.0.2 时使用 —— 网关在 /geoserver/cloud 下提供 WMS/WFS/WCS/WPS/GWC 微服务、PgConfig 与 datadir 后端、RabbitMQ 配置总线同步、Helm chart geoservercloud 3.0.2，以及通过 actuator/health 和 Consul 注册诊断 502。 |
| geoserver-rest-api | 需要通过 REST 自动化操作 GeoServer 3.0.2 时使用 —— POST /rest/workspaces、datastores、featuretypes，PUT Shapefile ZIP 到 file.shp，GeoTIFF 到 coveragestores，以 application/vnd.ogc.sld+xml 上传 SLD，?recurse=true 删除。curl -u admin:geoserver，单键 JSON 如 {"workspace":{...}}，POST 返回 401 但 GET 返回 200，GWC 缓存掩盖样式变更。 |
| geotools | 基于 GeoTools 35.2（JDK 17）构建 Java GIS 应用时使用 —— 从 repo.osgeo.org（不是 Maven Central）获取 org.geotools:gt-main / gt-shapefile / gt-geopkg / gt-epsg-hsql，CQL/ECQL 过滤器，CRS.decode 配合 JTS.transform 重投影，StreamingRenderer 输出 PNG，以及释放 DataStore/SimpleFeatureIterator。 |
| grass-gis | 无头运行 GRASS GIS 做 GIS 地理处理时使用 —— 服务器和 CI 上用 grass --exec 和 --tmp-project，g.region 管理计算区域，r.* 栅格、v.* 矢量、r3.* 三维栅格和 t.* 时序模块，r.import/v.import 导入数据，或用 grass.script、grass.script.array 和 grass.tools 写 Python 脚本。 |
| jts | 用 org.locationtech.jts:jts-core 1.20.0 在 Java 里做精确二维计算几何时使用 —— GeometryFactory 构造，contains/intersects 谓词，通过 OverlayNGRobust 做叠加，buffer，STRtree 和 PreparedGeometry 加速，WKT/WKB/GeoJSON 读写，以及修复 TopologyException 或未闭合环。 |
| kepler-gl | 用 Kepler.gl 3.3.0-alpha.16 构建 React/Redux Web 应用或 Jupyter notebook 做大尺度地理空间可视探索时使用 —— @kepler.gl/components 的 KeplerGl，@kepler.gl/actions 的 addDataToMap，@kepler.gl/processors 的 processGeojson/processCsvData，以及 Python 的 keplergl widget。也用于修复 reducer 缺失或 getState 写错导致的地图空白（react-redux 报 'Could not find ... in the context of Connect(...)'）、Mapbox token 底图报错，以及 addDataToMap 载荷过大。 |
| leaflet | 用 leaflet 1.9.4 给网页加轻量二维瓦片地图时使用 —— L.map/L.tileLayer、标记、弹窗、GeoJSON 叠加、图层控制、[lat, lng] 顺序，或排查地图空白、打包后默认标记图标损坏，以及用 invalidateSize() 修复尺寸问题。 |
| mapbox-gl-js | 用 mapbox-gl 3.33.0 构建矢量 Web 地图时使用 —— WebGL 渲染、Style Spec 图层、数据驱动表达式、setTerrain raster-dem、fill-extrusion，或排查 401 'A valid Mapbox access token is required'、'Style is not done loading' 以及 pk./sk. token 处理。注意：v2+ 按 Mapbox TOS 为专有软件，需要 token；MapLibre GL JS 是开源分支。 |
| mapserver | 从 MapServer 8.6.6 的 .map mapfile 发布 WMS/WFS/WCS/OGC API Features 时使用 —— MAP/LAYER/CLASS/STYLE 对象，STATUS/PROJECTION/EXTENT 报错，WEB.METADATA 的 wms_enable_request 和 wfs_enable_request，SLD 绑定，FastCGI 加 MS_MAP_PATTERN 加固，以及 GetMap 空白 / "No query information to decode" 症状。 |
| mapsui | 在 .NET 桌面（WPF/WinUI/WinForms）或移动（MAUI/Avalonia/Blazor）应用中嵌入交互式 2D 地图时使用，基于 Mapsui 5.1.0（net8.0/net9.0）——Mapsui.Wpf/Mapsui.Maui 包、Map 与 Layers、OpenStreetMap.CreateTileLayer、通过 Mapsui.Nts 处理 Shapefile/GeoJSON、SphericalMercator.FromLonLat，或排查 MapControl 空白问题。 |
| nettopologysuite | 在 .NET 中做 2D 计算几何时使用，基于 NuGet NetTopologySuite 2.6.0——带 SRID 的 GeometryFactory、Contains/Intersects 谓词、Intersection/Union/Buffer 叠加、STRtree、GeometryFixer、WKT/WKB/GeoJSON 读写、通过 IO.Esri 处理 Shapefile，以及在 SQL Server/Npgsql 上执行 EF Core 空间查询。 |
| opengis-all | 梳理端到端 GIS 工作流时使用——GDAL 命令行/API（ogr2ogr、gdalwarp、gdal_calc.py）、qgis_process 与 PyQGIS 分析、GeoServer REST 发布，以及 OpenLayers/CesiumJS 可视化。一站式索引，覆盖完整开源 GIS 数据管线。 |
| opengis-daf | 用 OpenGisDAF（.NET 10 / C# 14）搭建 JSON 计划式 GIS 分析或 QC 管线时使用——daf validate/run、算子 buffer/clip/intersect_check/containment_check/coordinate_transform、DAG 上游绑定、GeoJSON/Shapefile/PostGIS 输出端、qcMode QC 报告、AssemblyLoadContext 插件；也适用于「zero tests ran」退出码 5、缺少 --recurse-submodules 的 GDAL 构建错误，或 PostGIS Layer already exists。计划驱动 ETL。 |
| opengis-utils-for-java | 在 Java 中需要常用 GIS 工具时使用——OguLayerUtil 图层读写、GeometryUtil 60+ 算子、CrsUtil CGCS2000（EPSG:4490、4502-4554）、Shapefile/GeoJSON/FileGDB/PostGIS/land TXT 读写、拓扑校验；也适用于 gdal_jni 上的 GDAL UnsatisfiedLinkError、GeoTools 缺少 osgeo 仓库，或解析 Maven Central 上不存在的 com.znlgis.ogu4j:ogu4j:1.0.0。OGU4J。 |
| opengis-utils-for-net | 在 .NET/C# 中需要常用 GIS 工具时使用——OguLayerUtil ReadLayer/WriteLayer/ConvertFormat、GeometryUtil 50+ 算子、CrsUtil CGCS2000 坐标转换、Shapefile/GeoJSON/FileGDB/GeoPackage/KML/PostGIS 读写；也适用于 Unable to load DLL gdal / DllNotFoundException、GBK shapefile 乱码，或 Geojson2Wkt 对整个 FeatureCollection 抛 ArgumentException。OpenGIS.Utils 1.1.2。 |
| openlayers | 用 npm ol 10.11.0 给 Web 应用加交互式 2D 地图时使用——Map/View、fromLonLat 转 EPSG:3857、WMS/WMTS/XYZ 数据源、带 featureClass 的 MVT、Draw/Modify/Snap 交互，或排查图层空白（漏写 setStyle）、中心偏移和 ol/... 模块找不到错误。 |
| pdal | 通过命令行或 Python 处理点云数据（LAS/LAZ/BPF/EPT/COPC）时使用——pipeline JSON 工作流、格式转换、重投影、裁剪、去噪、地面分类（SMRF），以及从 LiDAR 生成 DEM。PDAL（Point Data Abstraction Library）是点云领域的 GDAL：pdal info/translate/pipeline 命令加 pdal.Pipeline Python 绑定。 |
| postgis | 用 PostGIS 3.6.4 扩展 PostgreSQL 时使用——geometry/geography/raster 类型、GiST 和 KNN <-> 索引、ST_Intersects/ST_Buffer/ST_Transform/ST_AsMVT、shp2pgsql -I 和 raster2pgsql 导入，以及修复「Operation on mixed SRID」、慢速空间连接、用 ST_MakeValid 处理无效多边形。 |
| proj | 在命令行转换坐标或查看 CRS 定义时使用——cs2cs、projinfo -s/-t、proj 投影计算、cct、EPSG 查询、用网格文件做基准面偏移、导出 WKT/PROJJSON，或调试「Cannot find proj.db」和纬度优先的轴顺序。PROJ 9.9.0：GDAL/QGIS 背后的 OSGeo 引擎，带 proj.db 这个 SQLite 数据库。 |
| projnet4geoapi | 在 .NET 中用 ProjNet 2.1.0（NuGet 包 ProjNet，仓库 ProjNet4GeoAPI）转换坐标或读取 CRS 定义时使用——CoordinateSystemFactory.CreateFromWkt、CoordinateTransformationFactory.CreateFromCoordinateSystems、MathTransform.Transform、CoordinateSystemServices 注册 SRID。也适用于「no suitable transformation」、GetCoordinateSystem 返回 null、4326 和 3857 之外的 EPSG 代码返回 null，以及需要旧版 ProjNet4GeoAPI 1.4.1 GeoAPI 构建的 SharpMap 项目。 |
| pyqgis | 用 Python 写 QGIS 脚本时使用——QgsApplication 独立初始化、加载 QgsVectorLayer / QgsRasterLayer、Processing.initialize() 之后调用 processing.run、QgsGeometry / QgsExpression、QgsMapSettings 渲染和 QgsLayoutExporter 导出 PDF/PNG、qgis._3d，或调试「import qgis.core」失败。PyQGIS 对应 QGIS 4.2.3 和 LTR 3.44.15（用 QGIS 自带的解释器，不要用系统 Python）。 |
| qgis-process | 用 qgis_process 无头运行 QGIS 地理处理时使用——native:buffer / native:reprojectlayer / native:clip、qgis_process list / help --json / run --json、.model3 模型和 .py 脚本、批量 CI 流水线，或调试「Algorithm ... not found!」；包含 QT_QPA_PLATFORM=offscreen 和 qgis/qgis 镜像（stable 4.2、ltr 3.44）。 |
| qgis-server | 把 QGIS 工程（.qgs/.qgz）发布为 OGC Web 服务时使用——WMS GetMap/GetPrint、WFS 和 WFS-T、WMTS、通过 qgis_mapserv.fcgi 配合 Apache mod_fcgid、Nginx 或 Docker 提供 OGC API Features，外加 QGIS_SERVER_* 调优（MAX_THREADS、PARALLEL_RENDERING、LOG_STDERR）；涵盖「Service unknown or unsupported」和 MAP/GetCapabilities 检查。QGIS 4.2.3 和 LTR 3.44.15。 |
| shapely | 在 Python 中做计算几何时使用——shapely.intersection/union/buffer/convex_hull/simplify、STRtree 查询、from_wkt/to_wkt/to_geojson、make_valid、受 GEOS 限制的操作（coverage_clean、split）；也适用于自相交多边形上的 TopologyException，或 OOP 与函数式 buffer 的 quad_segs 不一致。Shapely 2.2.0 绑定 GEOS。 |
| sharpmap | 在旧版 .NET Framework 4.7.2 WinForms 或 ASP.NET WebForms 应用里用 SharpMap 1.2.0 渲染 2D 地图时使用——Map.GetMap() 输出 PNG、ShapeFile/PostGIS 服务商、带 CustomTheme 的 VectorLayer、经 BruTile 的 TileAsyncLayer、ProjNet4GeoAPI 坐标转换，或排查空白输出与 GDI+ 句柄泄漏。新项目请用 Mapsui。 |
| spatialite | 用 SpatiaLite 给单文件 SQLite 数据库加空间 SQL 时使用——加载 mod_spatialite、InitSpatialMetaData、AddGeometryColumn、CreateSpatialIndex/MbrWithin、ST_Transform 与 GEOS 谓词、用 spatialite_tool 或 ogr2ogr 导入 Shapefile，以及 GPKG 兜底；也适用于 'no such module: mod_spatialite'、'no such function: InitSpatialMetaData' 和 'the SPATIALITE_SECURITY environment variable' 报错。libspatialite 5.1.0。 |
| whitebox-tools | 用 WhiteboxTools v2.4.0 做高级栅格、地形或 LiDAR 地理处理时使用——whitebox_tools --run=Slope/FillDepressions/BreachDepressions/FlowAccumulationFullWorkflow/Watershed/ExtractStreams、处理 LAS 点云的 lidar_* 工具，或在 Python 里用 whitebox（whitebox-python 2.3.6）WhiteboxTools 封装。也适用于 'whitebox_tools: command not found'、Python 前端版本不匹配、DEM/汇流累积中间产物缺失。 |

安装

方式一：Plugins 界面（本地目录，适合开发）

1. 在 DSH 中打开 Plugins / 插件 页面，选择安装 bundle（本地目录方式）。
2. 目标填包根目录的绝对路径，也就是包含 package.json 的目录，例如本仓库 D:\self\code\dsh-opengis-skill。
3. 安装后在列表中找到 OpenGIS 技能包 并启用；记录写入当前所选 profile 的插件配置。
4. 本地目录方式直接引用源码目录，改动会随重载生效，适合开发与试用；正式使用建议走下面的 npm 方式，便于升级与版本校验。

方式二：npm

dsh plugin --profile <profile> add @dsh-gis/dsh-opengis-skill

安装后在 Plugins 页面启用该 bundle。卸载：

dsh plugin --profile <profile> remove @dsh-gis/dsh-opengis-skill

- desktop profile 由 Electron 应用独占，推荐直接使用 Plugins 界面操作。
- 安装、升级或启停之后，需要重载/重启 dsh，并新开会话，技能目录才会反映最新状态（bundle 与技能目录在会话启动时装配）。
- 升级到新版本后同样需要重载 + 新会话；本地目录方式改动 package.json 或 assets/ 后也一样。

使用

- 技能目录只列出每个技能的名称与描述；模型用 skill("gdal") 之类的调用加载，用户也可以在输入框直接输入 /gdal。
- 常用入口：
- opengis-all — 端到端 GIS 流程索引（GDAL → 处理 → GeoServer → 可视化）；
- gdal / gdal-api — 命令行与编程式栅格/矢量处理；
- qgis-process / pyqgis — QGIS 批处理与二次开发；
- geoserver + geoserver-rest-api — 发布与管理 OGC 服务；
- postgis / duckdb-spatial / spatialite — 空间数据库；proj — 坐标转换；
- whitebox-tools / grass-gis / pdal — 地形水文、点云批处理；
- geonode / geoserver / mapserver / qgis-server — 发布 OGC 服务；
- openlayers / leaflet / cesiumjs / deck-gl / kepler-gl / geolibre — Web 2D/3D 可视化。
- 加载结果会给出该技能的 Base directory；正文中的 reference/.md 与 ../<其他技能>/SKILL.md 相对链接都据此解析。因为全部技能资产随同一个包一起分发，跨技能链接不需要额外安装或配置。

DeepSeek Harness 适配

上游已把仓库与特定 Agent 解耦，技能正文保持通用写法。本包不去改上游快照，而是加一层只在 DSH 里生效的执行指南：

- 分层存放：assets/<skill>/SKILL.md 是上游逐字节快照；adaptations/common.md 是每个技能都会读到的通用约定（工具映射、Windows 改写、版本探测、产物验证、后台作业、沙箱与凭据）；adaptations/<skill>.md 是该技能独有的执行建议（先读哪个 reference、命令跑在哪、探测什么、怎么验证、哪些操作要先确认）。
- 加载时拼接：服务商的 get 把「上游正文 + ## DeepSeek Harness 使用建议 + ## DeepSeek Harness 通用约定」拼成一次加载结果。正文与 reference/.md 的相对链接仍以技能目录为基准解析，不需要额外配置。
- 不随上游漂移：同步只覆盖 assets/ 与 upstream.json，不会碰 adaptations/。上游新增技能时，npm run validate 会点名缺少适配文件的技能，补齐后再发布，避免悄悄发布一个没有 DSH 指南的技能。
- 自检：npm run check:adaptations 只校验适配层（可传入技能名）；npm run validate 会同时校验适配层的结构、长度、相对链接，以及适配文件里用反引号提到的 reference/.md 是否真的存在于该技能目录。
- 命令统一走 DSH 的 shell 工具：Linux/macOS 用 ops_bash（旧文档里叫 bash），Windows 的 Bash 是 MSYS，Windows 原生命令用 pwsh；只暴露 run_code 的会话在 TypeScript 里调用 tools.ops_bash / tools.pwsh。
- 文件与日志优先用 read（分段）/ grep / glob；大输出先落盘，长任务放后台作业并用 job_output 收日志。技能目录与运行时是只读资源，脚本与产物写到会话工作区。
- 技能正文标注的是上游核验时点的版本（例如 GeoServer 3.0.2、GeoTools 35.2、QGIS 4.2.3 / LTR 3.44.15、GDAL 3.13.3）。实际环境版本不同时，先探测版本，再按「低版本降级」或「高版本新增 API」说明差异，不要照搬不存在的命令。
- 技能只是领域知识与执行约定，不会替你安装工具、绕过沙箱或读取凭据；安装依赖、启动服务、覆盖数据、执行破坏性 SQL 前先向用户确认，命令与回答中不要回显密码与 token。

上游同步

本节只适用于本仓库的源码开发。scripts/ 与 test/ 不在 npm 发布包内（package.json 的 files 未包含它们），安装用户无需执行这些命令。

默认从 ../opengis-skills 读取，也可用 --from 或 OPENGIS_SKILLS_DIR 指定
npm run sync -- --from ../opengis-skills

只检查是否与上游一致（CI 可用）
npm run sync:check -- --from ../opengis-skills

同步脚本会：逐文件复制 gis/<skill>/（文本统一为 LF，保证与上游 git blob 跨平台字节一致）、校验 frontmatter（name 必须为 kebab-case 且与目录同名）、清理上游已删除的技能目录、更新 upstream.json，并重新生成 README 中的技能数量与技能表（生成区域由 与 标记界定）。sync:check 做双向比较：既检查已同步文件是否漂移，也检查上游新增/删除的技能是否遗漏。adaptations/ 不参与同步：它属于本仓库的 DSH 适配层，同步只覆盖资产快照；上游新增技能后需要手工补一个 adaptations/<skill>.md，否则校验失败。

为避免伪造来源，npm run sync 要求 --from 指向 opengis-skills 的 git 检出根目录：脚本用 git rev-parse --show-toplevel 校验该目录就是仓库根，避免把外层仓库的 HEAD 误记成上游 commit；无法证明 commit 时同步直接失败。上游 gis/ 下若出现没有 SKILL.md 的目录，同步会报错而不是静默跳过（否则上游改名会静默丢技能）；gis/ 根目录的普通文件（上游分类索引 gis/SKILL.md 等）不参与同步，也不会被当作技能打包。

upstream.json 同时是一份完整性清单：schemaVersion 为 1，hashAlgorithm 为 "sha256"，files 以相对 assets/ 的 POSIX 路径为键、对应文件的 SHA-256 摘要为值。npm run validate 会重新计算并比对全部摘要，因此不依赖上游 checkout 也能发现资产被手改、缺失或未列入清单的情况；CI 的 sync 任务再用固定 commit 的上游检出做一次 sync:check，确保快照与上游一致。

开发

需要 Node.js 22+。

npm run check # validate + test，发布前必跑（也是 prepublishOnly）
npm run check:adaptations [skill...] # 只校验 DSH 适配层，可指定技能
npm run validate # 资产、元数据、bundle 接线、完整性清单、DSH 适配层与断链校验
npm test # Node 内置测试运行器
npm pack --dry-run # 查看实际发布内容

编辑器默认值见 .editorconfig（UTF-8、LF、最终换行；JS/MJS 用 Tab，JSON/YAML/Markdown 用 2 空格；Markdown 保留行尾空格）。版本变更记录见 CHANGELOG.md。

目录结构

dsh-opengis-skill/
├── package.json # dsh.bundle.patch、engines、files、图标/本地化导出 ├── cordis.patch.yml # bundle 层：把 opengis-skill provider 行插入 Host ├── lib/ │ ├── index.js # provider 插件（注册 ctx.skills、list/get） │ ├── adaptations.js # DSH 适配层读取、拼接与结构校验（插件/脚本/测试共用） │ ├── catalog.js # 扫描 assets/ 构建技能目录、生成 README 区域 │ ├── markdown-links.js # Markdown 相对链接解析与断链校验 │ ├── skill-file.js # SKILL.md frontmatter 解析（插件/脚本/测试共用） │ └── .d.ts # 手写类型声明 ├── assets/<skill>/ # 上游技能快照（SKILL.md + reference/.md，逐字节同步，勿手改） ├── adaptations/ # DSH 适配层（不参与上游同步） │ ├── common.md # 每个技能都会读到的通用执行约定 │ └── <skill>.md # 该技能专属的执行建议 ├── locale/{en,zh}.json # Plugins 里显示的标题与描述 ├── icon.svg # bundle 图标 ├── scripts/ │ ├── sync-opengis-skills.mjs # 上游同步（assets/、upstream.json、README 生成区域） │ ├── check-adaptations.mjs # 单独的 DSH 适配层校验（可指定技能） │ └── validate-skills.mjs # 发布前校验（自包含，无需上游 checkout） ├── test/ │ ├── plugin.test.mjs # provider 目录/加载/链接/适配层拼接 │ ├── adaptations.test.mjs # 适配层拼接、覆盖与结构规则 │ ├── skill-file.test.mjs # frontmatter 解析 │ ├── catalog.test.mjs # 目录构建与 README 生成区域 │ ├── markdown-links.test.mjs # 相对链接解析与断链检测 │ └── scripts.test.mjs # 同步/校验脚本（临时目录夹具） ├── .editorconfig # 编辑器默认值 ├── CHANGELOG.md # 版本变更记录 ├── README.md └── upstream.json # 上游仓库、commit、同步时间、技能清单与 SHA-256 清单

设计说明

- 规范注册：apply 时调用 ctx.skills.registerProvider(() => provider)；返回的 disposer 归调用方 fiber 所有，卸载时自动清理，因此不需要再套一层 ctx.effect(...)。
- provider 名为 opengis，source 为 opengis，候选 rank 为 600（即 BUNDLED_SKILL_RANK，与官方内置技能包一致），invocation 为模型与用户均可调用。
- list 只返回元数据（名称、描述、rank、source、locator/path、resourceBase）；get 每次重新读盘并解析正文，因此编辑资产或适配文件后重新加载插件即可生效，无需清缓存。插件不注册工具、不注入提示段、不写会话状态。
- 适配层拼接：get 返回的 content 是「上游正文 + 分隔线 + adaptations/<skill>.md + adaptations/common.md」。正文首部保持上游原样，所以 reference/.md 与 ../<skill>/SKILL.md 的相对链接仍按技能目录解析；共用约定放在最后，保证读到的最后一段是安全与平台约束。适配文件缺失或首行标题不对会直接报错并指出期望路径，而不是静默返回一个没有 DSH 指南的技能。
- 运行时加固：frontmatter 解析严格且容忍 UTF-8 BOM（name 必须为 kebab-case、description 必填，块标量与未闭合引号会报可读错误）；上游部分 description 存在未转义的内层双引号（非法 YAML 但语义明确），解析器按「首尾引号之间全部内容」宽容读取，未知转义保持字面，从而继续与上游字节一致而不必改写快照；assets/ 缺失时报错会指明期望的资产根目录；resourceBase 在 Windows 上也统一输出为正斜杠，跨平台链接一致。
- 相对链接不做改写：包内是全量技能目录，reference/*.md 与 ../<skill>/SKILL.md 都能解析；npm run validate 会扫描全部 Markdown 相对链接，断链或越出 assets/ 都会失败。

故障排查

- 技能目录没有出现：确认 bundle 已在 Plugins 中启用；安装、升级或启停后需要重载/重启 dsh 并新开会话。若用本地目录方式，确认填的是包含 package.json 的包根目录。
- 加载技能失败：错误信息会带出具体资产路径（例如 .../assets/gdal/SKILL.md 的 frontmatter 问题）；按提示修复，或从上游重新同步，不要手工编辑 assets/。
- 本地验证：npm run validate 检查资产、元数据、bundle 接线、完整性清单与链接；npm test 跑单元测试；发布前统一用 npm run check。
- 同名技能冲突：技能注册表按 rank、再按注册顺序决定同名技能的解析优先级；本包 rank 为 600。若其他 provider 也提供了同名技能，检查是否有另一份 OpenGIS 技能包或自定义技能被同时启用。
- 不要手改 assets/：它是上游快照，手工修改会导致 SHA-256 完整性校验与同步检查失败；需要改内容时先改上游，再 npm run sync 重新生成。
- 适配层报错：npm run validate 报 adaptations/<skill>.md: missing 表示上游新增了技能但还没写 DSH 指南，报 ... must start with "## DeepSeek Harness 使用建议" 或 missing the "…" bullet 表示文件结构不符合约定；修好后再发布。

与 @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）。
- 本包：纯知识型技能包，不提供工具，可与上述插件同时安装。

许可

MIT，见 LICENSE。技能正文与参考资料来自 opengis-skills（MIT © 2024-2026 znlgis），详见 THIRD_PARTY_NOTICES.md。