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

package/.editorconfig

@@ -0,0 +1,19 @@
+# Editor defaults for the repository. Mirrors the LF normalization in
+# .gitattributes; editors that support EditorConfig apply these automatically.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{js,mjs}]
+indent_style = tab
+
+[*.{json,jsonc,yaml,yml,md}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.3] - 2026-10-20
+
+### Added
+
+- Every GIS skill now ends with a `## DeepSeek Harness 使用建议` section covering skill
+  loading and reference reads, shell-tool mapping (`pwsh` and `run_code`), version
+  probes, artifact verification, and permission/secret handling. Generic "AI 使用建议"
+  sections were replaced rather than duplicated, so most skills got shorter.
+- Descriptions rewritten for skill discovery: concrete commands, package coordinates,
+  formats, and error symptoms, still starting with "Use when" and within the upstream
+  500-character limit.
+
+### Changed
+
+- Synced the vendored GIS skills to opengis-skills commit `4b64b89`; version claims
+  re-verified against upstream releases on 2026-10-20.
+- GeoServer (plus `geoserver-rest-api` and the `opengis-all` image tag) 3.0.1 → 3.0.2:
+  SourceForge binary URL, Docker tag, Java 17/21 prerequisite, and the 2026-10-19
+  security-release note.
+- GeoServer Cloud 3.0.1.1 → 3.0.2 and Helm chart `geoservercloud` 3.0.1 → 3.0.2.
+- GeoTools 35.1 → 35.2 (JDK 17); NetTopologySuite notes now pin IO.GeoJSON 4.0.0,
+  IO.Esri.Shapefile 1.2.0, and ProjNet 2.1.0.
+
+### Fixed
+
+- QGIS Server guidance probes the installed QGIS version instead of assuming a
+  `qgis_mapserver --version` binary; Cesium no longer asserts a 1.150 removal date;
+  Mapsui notes that 5.2.0-beta.1 is a prerelease.
+- Escaped inner quotes in rewritten frontmatter descriptions so the strict DSH
+  frontmatter parser accepts every skill.
+
+## [0.1.2] - 2026-10-19
+
+### Added
+
+- Tests for the frontmatter parser, the catalog builder, Markdown link resolution,
+  and the sync/validate scripts, plus expanded provider coverage in `test/plugin.test.mjs`.
+- A SHA-256 integrity manifest in `upstream.json` (`schemaVersion: 1`,
+  `hashAlgorithm: "sha256"`, `files` keyed by the POSIX path relative to `assets/`),
+  so validation no longer needs an upstream checkout.
+- Generated README sections: the skill count and skill table are rendered from the
+  vendored assets and verified by `npm run validate`.
+- `.editorconfig` and this changelog.
+
+### Changed
+
+- Compatibility: `engines.dsh` widened to `>=0.2.0-rc.2 <0.3.0-0`. The registry API
+  and candidate/definition contract of `@deepseek-ai/dsh-skill` are byte-identical
+  between 0.2.0-rc.2 and 0.2.1-rc.2, and 0.2.0-rc.2 already supports
+  `dsh.bundle.patch`, locale and icon metadata, so the old `>=0.2.1-rc.2` gate
+  needlessly blocked users on the npm-latest DSH 0.2.0-rc.2.
+- Runtime hardening: canonical provider registration via
+  `ctx.skills.registerProvider(() => provider)` (the returned disposer is owned by
+  the calling fiber, so no extra `ctx.effect` wrapper), a strict BOM-tolerant
+  frontmatter parser, a clear error when the asset root is missing, and
+  forward-slash `resourceBase` paths on Windows.
+- Tooling hardening: two-way `sync:check` (drift plus upstream additions/removals),
+  SHA-256 manifest verification, generated README count/table verification,
+  validation of every relative Markdown link in the repository docs and assets,
+  and CRLF detection.
+- CI: the test matrix now covers Ubuntu (Node 22/24) and Windows (Node 24), and a
+  new `sync` job verifies the vendored snapshot against the pinned upstream commit.
+- `npm run check` (`validate && test`) added; `prepublishOnly` now runs it.
+- Docs refreshed: README rewritten without hardcoded skill counts, with an English
+  summary, a compatibility note, install/uninstall/update notes, upstream integrity
+  docs and a troubleshooting section; package description and locale metadata
+  updated.
+
+### Fixed
+
+- `SKILL.md` files with a UTF-8 BOM are parsed correctly; frontmatter parsing is
+  strict and reports unterminated quotes or block scalars instead of silently
+  ignoring them.
+- A missing `assets/` directory now fails with a clear error that names the expected
+  asset root instead of an opaque `ENOENT`.
+- `resourceBase` paths are emitted with forward slashes on Windows, so relative
+  references resolve consistently across platforms.
+- Stale hardcoded skill counts removed from the README, locale metadata and the npm
+  description; count and table are generated from the vendored assets.
+- CRLF line endings in vendored assets are detected and reported by validation.
+- Sync refuses a `--from` directory that is not itself a git checkout root, so an
+  enclosing repository's HEAD can no longer be recorded as forged upstream
+  provenance; the manifest commit is now mandatory and validated.
+- Sync rejects `gis/` directories without `SKILL.md` and stray files at the
+  `assets/` root instead of silently dropping or blessing them.
+- Stray files at the `assets/` root are pruned by sync and rejected by
+  validation, so `assets/` publishes only skill directories.
+- CI actions are pinned to release commit SHAs, and the external upstream
+  checkout disables persisted credentials.
+- Validation checks the bundle row structurally, the locale file grammar, and the
+  engine range shape instead of accepting any non-empty string.
+
+## [0.1.1] - 2026-10-19
+
+### Fixed
+
+- Vendored skill assets are written with LF bytes regardless of the source
+  checkout's line endings, so the snapshot matches the upstream git blob on every
+  platform.
+- Corrected the release documentation shipped with 0.1.0.
+
+## [0.1.0] - 2026-10-19
+
+### Added
+
+- Initial public release: a DeepSeek Harness bundle and plugin that vendors the
+  `gis/` skills of opengis-skills and registers one skill provider (`opengis`) on
+  `ctx.skills`.
+- Bundled assets under `assets/<skill>/` (`SKILL.md` plus `reference/*.md`), bundle
+  wiring (`cordis.patch.yml`), locale metadata, icon, and npm packaging.
+- Source-repository tooling: `npm run sync` / `npm run sync:check`, `npm run
+  validate`, `npm test`, and GitHub Actions CI.
+
+## [0.0.0-stage] - 2026-10-19
+
+### Added
+
+- First staging release: bundle/plugin skeleton, vendored skill assets, locale and
+  icon metadata, and the initial sync/validate/test scripts for installation
+  checks.

package/README.md

@@ -1,61 +1,83 @@
 # @dsh-gis/dsh-opengis-skill
 
-DeepSeek Harness 的 **OpenGIS 技能包插件**：把 [opengis-skills](https://github.com/znlgis/opengis-skills) 中 **gis/ 分类的 32 个 GIS 技能**打包成可安装、可启停的 DSH bundle。会话技能目录只列出名称与描述，技能正文与参考资料按需加载。
+> **English summary** — A DeepSeek Harness bundle that packages the `gis/` skills of
+> [opengis-skills](https://github.com/znlgis/opengis-skills) as installable, toggleable skills.
+> The session catalog lists names and descriptions only; skill bodies and their
+> `reference/*.md` files are loaded on demand, and every body carries DeepSeek Harness
+> execution guidance (tool mapping, version probes, verification, permissions). Zero
+> runtime dependencies: every asset ships inside the npm package.
+>
+> Compatibility: DeepSeek Harness `>=0.2.0-rc.2 <0.3.0-0`; Node.js `>=22` for development
+> only. MIT licensed.
+
+DeepSeek Harness 的 **OpenGIS 技能包插件**：把 [opengis-skills](https://github.com/znlgis/opengis-skills) 中 `gis/` 分类的 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 全流程索引。
+- **覆盖 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 包内自带全部资产（约 660 KB），不 import DSH 内部包。
-- **可同步上游**：`npm run sync` 从 opengis-skills 检出复制资产，记录上游 commit 到 `upstream.json`，并重新生成本文下方技能表。
+- **零运行时依赖**：只用 Node 内置模块，不 import DSH 内部包；全部资产随 npm 包分发，整个包解包后约 720 kB。
+- **可同步上游**：`npm run sync` 从 opengis-skills 检出复制资产，记录上游 commit 与每个文件的 SHA-256 到 `upstream.json`，并重新生成本文下方技能清单。
 - **可启停**：单包同时是 bundle 与插件（`dsh.bundle.patch` 插入自身行），在 Plugins 里启用/停用即可。
+- **面向 DSH 的执行建议**：每个技能末尾都有 `## DeepSeek Harness 使用建议`，写明如何按需读 reference、Windows 下如何映射 shell 命令、先跑哪个版本探测命令、如何重新打开产物验证，以及哪些安装/覆盖/凭据操作要先确认。
+
+## 兼容性
+
+- **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 内部包。
 
 ## 技能清单
 
+<!-- skills:count:start -->
+共 **32** 个技能，描述取自上游 frontmatter。
+<!-- skills:count:end -->
+
 <!-- 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. |
+| `cesiumjs` | Use when building browser-based 3D globes, 3D Tiles, CZML/time-dynamic data, or glTF models with npm cesium 1.146.0 — Viewer, Cesium3DTileset, Ion token (Cesium.Ion.defaultAccessToken), CESIUM_BASE_URL for Workers/Assets/Widgets, GCJ-02 tile offset, or debugging a black screen after a Vite/Webpack build. |
+| `deck-gl` | Use when visualizing large geospatial datasets in the browser with deck.gl 9.4.0 — ScatterplotLayer/GeoJsonLayer, HexagonLayer/ScreenGridLayer aggregation, MVTLayer/TileLayer, @deck.gl/mapbox MapboxOverlay over MapLibre, or debugging blank canvases, stale data props and mismatched @deck.gl/* subpackage versions. |
+| `gdal` | Use when processing geospatial raster/vector data via GDAL/OGR CLI — ogr2ogr format conversion (Shapefile/GeoPackage/GeoJSON), gdalwarp reprojection, gdal_translate, gdal_calc.py NDVI, COG, mosaicking, DEM contours, gdalinfo -json checks — or diagnosing "not recognized as a supported file format"; also covers the 3.9+ unified gdal raster / gdal vector CLI. |
+| `gdal-api` | Use when programming against GDAL/OGR in C, C++, Python, Java, or .NET — raster/vector I/O, gdal.UseExceptions, OGRSpatialReference transforms, gdal.Translate / gdal.Warp, VRT/COG, or fixing "no driver registered" and UnsatisfiedLinkError; C++ gdal-config, Maven org.gdal:gdal 3.13.0, NuGet MaxRev.Gdal.Core. |
+| `geometry-api-java` | Use when working with Esri geometry types (Point, Polyline, Polygon, Envelope) in Java — GeometryEngine, com.esri.geometry:esri-geometry-api:2.2.4, WKT/WKB/GeoJSON/Esri JSON I/O, geodesic distance; also when GeometryEngine has no intersects or WKB method and you need OperatorFactoryLocal, or when 2.3.1 coordinates fail to resolve on Maven Central. Esri Geometry API for Java. |
+| `geometry-api-net` | Use when working with Esri geometry types (Point, Polyline, Polygon, Envelope) in .NET/C# — GeometryEngine, NuGet OpenGIS.Esri.Geometry.Core 1.0.9, WKT/EWKT, WKB, GeoJSON and Esri JSON I/O, System.Text.Json converters, geodesic distance; also for unclosed polygon rings, Geometry base-class casts after overlay, or the retired Esri/geometry-api-net repo. Esri Geometry API for .NET. |
+| `geopandas` | Use when doing vector spatial analysis in Python — gpd.read_file/to_file via pyogrio (GPKG, Shapefile, GeoParquet), sjoin/sjoin_nearest, overlay, clip, dissolve, to_crs vs set_crs, gdf.plot choropleth; also for CRSError from a missing PROJ data dir, area/distance computed in degrees, or GeoDataFrame geometry-column conflicts. GeoPandas 1.2.0 extends pandas DataFrames with geometry columns. |
+| `geopipe-agent` | Use when building YAML GIS pipelines with GeoPipeAgent — geopipe-agent validate/run, io.read_vector → vector.buffer → io.write_vector chains, 33 built-in steps, qc.geometry_validity/attribute_completeness/topology, native_python\|qgis_process\|gdal_cli backends, $step.output refs; also for validate "not registered" errors, silent when-condition skips, and resolve/knowledge capability gaps. 0.1.0, source install only (not on PyPI). |
+| `geoserver` | Use when deploying GeoServer 3.0.x to publish WMS/WFS/WMTS/WCS/MVT, or configuring SLD/CSS styles, RBAC security, and GeoWebCache seeding. Covers geoserver-3.0.2-bin.zip, docker.osgeo.org/geoserver:3.0.2 on Java 17/21, /rest/about/version.json, blank GetMap from wrong native bounds, and Shapefile charset mojibake. |
+| `geoserver-cloud` | Use when deploying GeoServer Cloud 3.0.2 on Docker Compose or Kubernetes — gateway serving WMS/WFS/WCS/WPS/GWC microservices under /geoserver/cloud, PgConfig vs datadir backends, RabbitMQ config-bus sync, Helm chart geoservercloud 3.0.2, and diagnosing 502s via actuator/health and Consul registration. |
+| `geoserver-rest-api` | Use when automating GeoServer 3.0.2 over REST — POST /rest/workspaces, datastores, featuretypes, PUT Shapefile ZIP to file.shp, GeoTIFF to coveragestores, upload SLD as application/vnd.ogc.sld+xml, ?recurse=true deletes. curl -u admin:geoserver, single-key JSON like {"workspace":{...}}, 401 on POST but 200 on GET, GWC cache masking style changes. |
+| `geotools` | Use when building Java GIS apps on GeoTools 35.2 (JDK 17) — org.geotools:gt-main / gt-shapefile / gt-geopkg / gt-epsg-hsql from repo.osgeo.org (not Maven Central), CQL/ECQL filters, CRS.decode plus JTS.transform reprojection, StreamingRenderer PNG output, and disposing DataStore/SimpleFeatureIterator. |
 | `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. |
+| `jts` | Use when doing precise 2D computational geometry in Java with org.locationtech.jts:jts-core 1.20.0 — GeometryFactory construction, contains/intersects predicates, overlay via OverlayNGRobust, buffer, STRtree and PreparedGeometry speedups, WKT/WKB/GeoJSON I/O, and fixing TopologyException or unclosed rings. |
+| `leaflet` | Use when adding lightweight 2D tile maps to web pages with leaflet 1.9.4 — L.map/L.tileLayer, markers, popups, GeoJSON overlays, layer control, [lat, lng] ordering, or debugging blank maps, broken default marker icons after bundling, and sizing fixed by invalidateSize(). |
+| `mapbox-gl-js` | Use when building vector web maps with mapbox-gl 3.33.0 — WebGL rendering, Style Spec layers, data-driven expressions, setTerrain raster-dem, fill-extrusion, or debugging 401 'A valid Mapbox access token is required', 'Style is not done loading', and pk./sk. token handling. Note: v2+ is proprietary under Mapbox TOS and requires a token; MapLibre GL JS is the open-source fork. |
+| `mapserver` | Use when publishing WMS/WFS/WCS/OGC API Features from a MapServer 8.6.6 .map mapfile — MAP/LAYER/CLASS/STYLE objects, STATUS/PROJECTION/EXTENT errors, WEB.METADATA wms_enable_request and wfs_enable_request, SLD binding, FastCGI plus MS_MAP_PATTERN hardening, and blank GetMap / "No query information to decode" symptoms. |
+| `mapsui` | Use when embedding interactive 2D maps in .NET desktop (WPF/WinUI/WinForms) or mobile (MAUI/Avalonia/Blazor) apps with Mapsui 5.1.0 (net8.0/net9.0) — Mapsui.Wpf/Mapsui.Maui packages, Map and Layers, OpenStreetMap.CreateTileLayer, Shapefile/GeoJSON via Mapsui.Nts, SphericalMercator.FromLonLat, or fixing a blank MapControl. |
+| `nettopologysuite` | Use when doing 2D computational geometry in .NET with NuGet NetTopologySuite 2.6.0 — GeometryFactory with SRID, Contains/Intersects predicates, Intersection/Union/Buffer overlays, STRtree, GeometryFixer, WKT/WKB/GeoJSON I/O, Shapefile via IO.Esri, and EF Core spatial queries on SQL Server/Npgsql. |
+| `opengis-all` | Use when navigating end-to-end GIS workflows — GDAL CLI/API (ogr2ogr, gdalwarp, gdal_calc.py), qgis_process and PyQGIS analysis, GeoServer REST publishing, and OpenLayers/CesiumJS visualization. One-stop index covering the complete open-source GIS data pipeline. |
+| `opengis-daf` | Use when building JSON-plan GIS analysis or QC pipelines with OpenGisDAF (.NET 10 / C# 14) — daf validate/run, operators buffer/clip/intersect_check/containment_check/coordinate_transform, DAG upstream bindings, GeoJSON/Shapefile/PostGIS sinks, qcMode QC reports, AssemblyLoadContext plugins; also for "zero tests ran" exit code 5, missing --recurse-submodules GDAL build errors, or PostGIS Layer already exists. Plan-driven ETL. |
+| `opengis-utils-for-java` | Use when needing common GIS utilities in Java — OguLayerUtil layer read/write, GeometryUtil 60+ ops, CrsUtil CGCS2000 (EPSG:4490, 4502-4554), Shapefile/GeoJSON/FileGDB/PostGIS/land TXT I/O, topology validation; also for GDAL UnsatisfiedLinkError on gdal_jni, missing osgeo repo on GeoTools, or resolving com.znlgis.ogu4j:ogu4j:1.0.0 that is not on Maven Central. OGU4J. |
+| `opengis-utils-for-net` | Use when needing common GIS utilities in .NET/C# — OguLayerUtil ReadLayer/WriteLayer/ConvertFormat, GeometryUtil 50+ ops, CrsUtil CGCS2000 transforms, Shapefile/GeoJSON/FileGDB/GeoPackage/KML/PostGIS I/O; also for Unable to load DLL gdal / DllNotFoundException, GBK shapefile mojibake, or ArgumentException from Geojson2Wkt on a whole FeatureCollection. OpenGIS.Utils 1.1.2. |
+| `openlayers` | Use when adding interactive 2D maps to web apps with npm ol 10.11.0 — Map/View, fromLonLat to EPSG:3857, WMS/WMTS/XYZ sources, MVT with featureClass, Draw/Modify/Snap interactions, or debugging blank layers (missing setStyle), offset centers and ol/... module-not-found errors. |
 | `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. |
+| `postgis` | Use when extending PostgreSQL with PostGIS 3.6.4 — geometry/geography/raster types, GiST and KNN <-> indexes, ST_Intersects/ST_Buffer/ST_Transform/ST_AsMVT, shp2pgsql -I and raster2pgsql import, and fixing "Operation on mixed SRID", slow spatial joins, and invalid polygons with ST_MakeValid. |
+| `proj` | Use when transforming coordinates or inspecting CRS definitions from the command line — cs2cs, projinfo -s/-t, proj projection math, cct, EPSG lookup, datum shift with grid files, WKT/PROJJSON export, or debugging "Cannot find proj.db" and latitude-first axis order. PROJ 9.9.0: the OSGeo engine behind GDAL/QGIS, with the proj.db SQLite database. |
+| `pyqgis` | Use when scripting QGIS with Python — QgsApplication standalone init, QgsVectorLayer / QgsRasterLayer loading, processing.run after Processing.initialize(), QgsGeometry / QgsExpression, QgsMapSettings rendering and QgsLayoutExporter PDF/PNG export, qgis._3d, or debugging "import qgis.core" failures. PyQGIS for QGIS 4.2.3 and LTR 3.44.15, Python 3.12. |
+| `qgis-process` | Use when running QGIS geoprocessing headless via qgis_process — native:buffer / native:reprojectlayer / native:clip, qgis_process list / help --json / run --json, .model3 models and .py scripts, batch CI pipelines, or debugging "Algorithm ... not found!"; includes QT_QPA_PLATFORM=offscreen and the qgis/qgis images (stable 4.2, ltr 3.44). |
+| `qgis-server` | Use when publishing QGIS projects (.qgs/.qgz) as OGC web services — WMS GetMap/GetPrint, WFS and WFS-T, WMTS, OGC API Features via qgis_mapserv.fcgi with Apache mod_fcgid, Nginx, or Docker, plus QGIS_SERVER_* tuning (MAX_THREADS, PARALLEL_RENDERING, LOG_STDERR); covers "Service unknown or unsupported" and MAP/GetCapabilities checks. QGIS 4.2.3 and LTR 3.44.15. |
+| `shapely` | Use when doing computational geometry in Python — shapely.intersection/union/buffer/convex_hull/simplify, STRtree queries, from_wkt/to_wkt/to_geojson, make_valid, GEOS-gated ops (coverage_clean, split); also for TopologyException on self-intersecting polygons or OOP vs function buffer quad_segs mismatch. Shapely 2.2.0 binds GEOS. |
+| `sharpmap` | Use when rendering 2D maps in legacy .NET Framework 4.7.2 WinForms or ASP.NET WebForms apps with SharpMap 1.2.0 — Map.GetMap() to PNG, ShapeFile/PostGIS providers, VectorLayer with CustomTheme, TileAsyncLayer via BruTile, ProjNet4GeoAPI transforms, or debugging blank output and GDI+ handle leaks. New projects should use Mapsui. |
 <!-- skills:end -->
 
 ## 安装
 
 ### 方式一：Plugins 界面（本地目录，适合开发）
 
-1. 打开 DSH 的 **Plugins / 插件** 页面，选择安装 bundle（安装本地包目录）。
-2. 目标填本仓库的绝对路径，例如 `D:\self\code\dsh-opengis-skill`。
-3. 在列表中找到 **OpenGIS 技能包** 并启用。
+1. 在 DSH 中打开 **Plugins / 插件** 页面，选择安装 bundle（本地目录方式）。
+2. 目标填**包根目录**的绝对路径，也就是包含 `package.json` 的目录，例如本仓库 `D:\self\code\dsh-opengis-skill`。
+3. 安装后在列表中找到 **OpenGIS 技能包** 并启用；记录写入当前所选 profile 的插件配置。
+4. 本地目录方式直接引用源码目录，改动会随重载生效，适合开发与试用；正式使用建议走下面的 npm 方式，便于升级与版本校验。
 
 ### 方式二：npm
 
@@ -63,11 +85,19 @@ DeepSeek Harness 的 **OpenGIS 技能包插件**：把 [opengis-skills](https://
 dsh plugin --profile <profile> add @dsh-gis/dsh-opengis-skill
 ```
 
-安装后在 Plugins 页面启用该 bundle。desktop profile 由 Electron 应用独占，推荐直接用 Plugins 界面操作；安装、升级或启停之后，需要新会话（或重启 dsh）才会出现最新的技能目录。
+安装后在 Plugins 页面启用该 bundle。卸载：
+
+```bash
+dsh plugin --profile <profile> remove @dsh-gis/dsh-opengis-skill
+```
+
+- desktop profile 由 Electron 应用独占，推荐直接使用 Plugins 界面操作。
+- 安装、升级或启停之后，需要重载/重启 dsh，并**新开会话**，技能目录才会反映最新状态（bundle 与技能目录在会话启动时装配）。
+- 升级到新版本后同样需要重载 + 新会话；本地目录方式改动 `package.json` 或 `assets/` 后也一样。
 
 ## 使用
 
-- 技能目录会列出 32 个技能的名称与描述；模型用 `skill("gdal")` 之类的调用加载，用户也可以在输入框直接输入 `/gdal`。
+- 技能目录只列出每个技能的名称与描述；模型用 `skill("gdal")` 之类的调用加载，用户也可以在输入框直接输入 `/gdal`。
 - 常用入口：
   - `opengis-all` — 端到端 GIS 流程索引（GDAL → 处理 → GeoServer → 可视化）；
   - `gdal` / `gdal-api` — 命令行与编程式栅格/矢量处理；
@@ -75,10 +105,20 @@ dsh plugin --profile <profile> add @dsh-gis/dsh-opengis-skill
   - `geoserver` + `geoserver-rest-api` — 发布与管理 OGC 服务；
   - `postgis` — 空间数据库；`proj` — 坐标转换；
   - `openlayers` / `cesiumjs` / `deck-gl` — Web 2D/3D 可视化。
-- 加载结果会给出该技能的 Base directory；正文中的 `reference/*.md` 与 `../<其他技能>/SKILL.md` 相对链接都据此解析（资源随包全量分发）。
+- 加载结果会给出该技能的 **Base directory**；正文中的 `reference/*.md` 与 `../<其他技能>/SKILL.md` 相对链接都据此解析。因为全部技能资产随同一个包一起分发，跨技能链接不需要额外安装或配置。
+
+## DeepSeek Harness 适配
+
+- 每个技能正文末尾都有 `## DeepSeek Harness 使用建议`：先加载哪个技能、哪些 `reference/*.md` 值得按需读取、先跑什么版本探测命令、产物怎样重新打开验证、哪些操作要先征得用户同意。
+- 命令统一走 DSH 的 shell 工具：Windows 用 `pwsh`；若当前会话只暴露 `run_code`，则在其中调用 `tools.pwsh`。正文里的 Bash 示例（`sudo`、`/tmp`、heredoc、反引号）按平台改写。
+- 文件与日志优先用 `read` / `grep` / `glob` 分段读取；大输出先落盘，长任务放后台作业。技能目录和运行时是只读资源，脚本与产物写到会话工作区。
+- 技能正文标注的是 2026-10-20 核验的上游版本（例如 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` 未包含它们），安装用户无需执行这些命令。
+
 ```bash
 # 默认从 ../opengis-skills 读取，也可用 --from 或 OPENGIS_SKILLS_DIR 指定
 npm run sync -- --from ../opengis-skills
@@ -87,45 +127,76 @@ npm run sync -- --from ../opengis-skills
 npm run sync:check -- --from ../opengis-skills
 ```
 
-同步脚本会：逐文件复制 `gis/<skill>/`（文本统一为 LF，保证与上游 git blob 跨平台字节一致）、校验 frontmatter（name 必须为 kebab-case 且与目录同名）、清理上游已删除的技能目录、更新 `upstream.json`（仓库地址、commit、同步时间、技能清单）以及本文的技能表。
+同步脚本会：逐文件复制 `gis/<skill>/`（文本统一为 LF，保证与上游 git blob 跨平台字节一致）、校验 frontmatter（name 必须为 kebab-case 且与目录同名）、清理上游已删除的技能目录、更新 `upstream.json`，并重新生成 README 中的技能数量与技能表（生成区域由 `<!-- skills:count:* -->` 与 `<!-- skills:* -->` 标记界定）。`sync:check` 做双向比较：既检查已同步文件是否漂移，也检查上游新增/删除的技能是否遗漏。
+
+为避免伪造来源，`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+。
+
 ```bash
-npm test            # Node 内置测试运行器，覆盖 provider 目录/加载/链接
-npm run validate    # 资产、元数据、bundle 接线与打包校验
+npm run check       # validate + test，发布前必跑（也是 prepublishOnly）
+npm run validate    # 资产、元数据、bundle 接线、完整性清单与断链校验
+npm test            # Node 内置测试运行器
 npm pack --dry-run  # 查看实际发布内容
 ```
 
+编辑器默认值见 [.editorconfig](./.editorconfig)（UTF-8、LF、最终换行；JS/MJS 用 Tab，JSON/YAML/Markdown 用 2 空格；Markdown 保留行尾空格）。版本变更记录见 [CHANGELOG.md](./CHANGELOG.md)。
+
 ### 目录结构
 
 ```text
 dsh-opengis-skill/
-├── package.json            # dsh.bundle.patch、engines、files、icons/locales 导出
-├── cordis.patch.yml        # bundle 层：把 opengis-skill provider 行插入 Host
+├── package.json                  # dsh.bundle.patch、engines、files、图标/本地化导出
+├── 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、同步时间与技能清单
+│   ├── index.js                  # provider 插件（注册 ctx.skills、list/get）
+│   ├── catalog.js                # 扫描 assets/ 构建技能目录、生成 README 区域
+│   ├── markdown-links.js         # Markdown 相对链接解析与断链校验
+│   ├── skill-file.js             # SKILL.md frontmatter 解析（插件/脚本/测试共用）
+│   └── *.d.ts                    # 手写类型声明
+├── assets/<skill>/               # 技能资产（SKILL.md + reference/*.md，随上游同步）
+├── locale/{en,zh}.json           # Plugins 里显示的标题与描述
+├── icon.svg                      # bundle 图标
+├── scripts/
+│   ├── sync-opengis-skills.mjs   # 上游同步（assets/、upstream.json、README 生成区域）
+│   └── validate-skills.mjs       # 发布前校验（自包含，无需上游 checkout）
+├── test/
+│   ├── plugin.test.mjs           # provider 目录/加载/链接
+│   ├── 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` 时扫描 `assets/*/SKILL.md`，解析并校验名称与描述，然后 `ctx.effect(() => ctx.skills.registerProvider(...))`；provider 名为 `opengis`，候选 rank 为 600（与官方内置技能包一致），模型与用户均可调用。
-- 目录（list）只含元数据；正文（get）每次重新读盘，因此编辑资产后重新加载插件即可生效，无需清缓存。插件不注册工具、不注入提示段、不写会话状态。
-- 相对链接不做改写：包内是全量 32 个技能目录，`reference/*.md` 与 `../<skill>/SKILL.md` 都能解析；如果将来裁剪技能，`npm run validate` 会报断链。
+- **规范注册**：`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` 每次重新读盘并解析正文，因此编辑资产后重新加载插件即可生效，无需清缓存。插件不注册工具、不注入提示段、不写会话状态。
+- **运行时加固**：frontmatter 解析严格且容忍 UTF-8 BOM（`name` 必须为 kebab-case、`description` 必填，未闭合引号或块标量会报可读错误）；`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` 重新生成。
 
 ## 与 @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 技能），不提供工具，可与上述插件同时安装。
+- 本包：纯知识型技能包，不提供工具，可与上述插件同时安装。
 
 ## 许可
 

package/THIRD_PARTY_NOTICES.md

@@ -31,10 +31,14 @@ SOFTWARE.
 ```
 
 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`, which lives in the source repository
-(<https://github.com/znlgis/dsh-opengis-skill>) and is not part of the
-published package. Text files are vendored with LF line endings so the
+recorded in [`upstream.json`](./upstream.json), together with a SHA-256
+integrity manifest of the snapshot: `schemaVersion` 1, `hashAlgorithm`
+`sha256`, and a `files` map from every vendored file's POSIX path (relative
+to `assets/`) to its digest. `npm run validate` recomputes those digests and
+fails when the vendored bytes drift from the recorded manifest. The copy is
+performed by `scripts/sync-opengis-skills.mjs`, which lives in the source
+repository (<https://github.com/znlgis/dsh-opengis-skill>) and is not part of
+the published package. Text files are vendored with LF line endings so the
 snapshot matches the upstream git blob on every platform. The skills are
 documentation: each one describes an independent open-source project (GDAL,
 QGIS, GeoServer, PostGIS, JTS, CesiumJS, OpenLayers, and others) and links to

package/assets/cesiumjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Use when building browser-based 3D globes, 3D Tiles, CZML/time-dynamic data, or glTF models with npm cesium 1.146.0 — Viewer, Cesium3DTileset, Ion token (Cesium.Ion.defaultAccessToken), CESIUM_BASE_URL for Workers/Assets/Widgets, GCJ-02 tile offset, or debugging a black screen after a Vite/Webpack build."
 tags:
   - javascript
   - webgl
@@ -49,7 +49,7 @@ npm install cesium
 <script src="https://cdn.jsdelivr.net/npm/cesium/Build/Cesium/Cesium.js"></script>
 ```
 
-> **1.146 变更：** 数学/几何/时间/工具类被拆分为新包 `@cesium/core`。从 `cesium` 主包导入的代码不受影响；直接按子路径引用 `@cesium/engine` 的代码需改从 `@cesium/core` 导入（旧导出将在 1.150 移除）。
+> **1.146 变更：** 数学/几何/时间/工具类被拆分为新包 `@cesium/core`（`cesium@1.146.0` 依赖 `@cesium/core@^0.1.0`）。从 `cesium` 主包导入的代码不受影响；直接按子路径引用 `@cesium/engine` 的代码需改从 `@cesium/core` 导入（旧导出计划在后续版本移除，1.146 仍可用）。
 
 ### Vite 集成
 
@@ -263,17 +263,16 @@ viewer.trackedEntity = entity;
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-
-### 关键注意事项
-
-- **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` 目录正确复制到输出目录
+- **加载与引用**：用 `skill("cesiumjs")` 加载（用户也可输入 `/cesiumjs`）；本技能无 reference 子目录，示例代码直接落到会话工作区的工程里，技能目录只读。
+- **执行环境**：`npm install`、`npm run build` 交给 `pwsh`；Windows 下 `npm` 实为 `npm.cmd`，脚本里写 `cmd /c npm run build` 更稳；装包和大构建用后台作业，输出重定向到文件再分段读。
+- **先探测版本**：`npm ls cesium`（未安装时 `npm view cesium version`）。本技能按 1.146.0 编写：该版本依赖 `@cesium/core@^0.1.0`，数学/几何/时间/工具类已拆到 `@cesium/core`，低于 1.146 的工程不要照搬这条迁移建议。
+- **验证产物**：`npm run build` 通过后用 `npx serve dist` 或 `python -m http.server 5173 -d dist` 起静态服务，用 `curl.exe -I` 检查 `http://localhost:5173/Cesium.js` 与 `.../Cesium/Widgets/widgets.css` 返回 200（404 或 text/html 说明资源没拷贝）；DSH 不打开浏览器，把 URL 和预期画面交给用户，有截图再用 `read_image` 核对。
+- **Ion 与部署**：`Cesium.Ion.defaultAccessToken` 从环境变量注入（Vite 用 `import.meta.env.VITE_CESIUM_ION_TOKEN`），不要写进源码或提交；黑屏先查 `window.CESIUM_BASE_URL` 与 `Workers/Assets/Widgets` 是否随构建产物发布。
+- **坐标与性能**：定位一律 `Cesium.Cartesian3.fromDegrees(lon, lat, height)`；大量静态要素用 Primitive，少量动态要素才用 Entity；`clampToGround` 只在需要贴地时开启。
+- **常见症状**：瓦片整体错位是国内底图的 GCJ-02 偏移，需先纠偏；ion 服务 401/403 多为 token 未设置或失效；`tileset.destroy()`、`viewer.dataSources.remove()` 不调用会持续占用显存。
+- **安全与权限**：安装依赖、启动 dev server、改端口前先征得用户同意；日志和回答中不要回显 Ion token。
 
 ## 相关技能
 

package/assets/deck-gl/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deck-gl
-description: "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."
+description: "Use when visualizing large geospatial datasets in the browser with deck.gl 9.4.0 — ScatterplotLayer/GeoJsonLayer, HexagonLayer/ScreenGridLayer aggregation, MVTLayer/TileLayer, @deck.gl/mapbox MapboxOverlay over MapLibre, or debugging blank canvases, stale data props and mismatched @deck.gl/* subpackage versions."
 tags:
   - javascript
   - web
@@ -439,12 +439,13 @@ map.addControl(overlay);
 - **leaflet** — 轻量 2D 瓦片地图，适合中小数据量与简单场景：[../leaflet/SKILL.md](../leaflet/SKILL.md)
 - **cesiumjs** — 三维地球与 3D Tiles 可视化：[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-- **版本对齐**：生成代码时统一使用 `@deck.gl/*` 9.4.0，并提醒用户各子包版本必须同步，避免混用不同大版本
-- **导入路径**：`Deck` 来自 `@deck.gl/core`，基础图层来自 `@deck.gl/layers`，聚合图层来自 `@deck.gl/aggregation-layers`，瓦片与 MVT 来自 `@deck.gl/geo-layers`，不要写错包名
-- **坐标顺序**：位置一律 `[经度, 纬度]`，与 GeoJSON 一致；半径默认单位为米，像素半径需显式设 `radiusUnits: 'pixels'`
-- **数据引用**：示例代码避免在渲染函数内生成新数组，优先用 `useMemo` 或模块级常量缓存
-- **拾取默认值**：需要 tooltip 或点击的图层必须显式写 `pickable: true`，其余保持默认关闭
-- **底图选择**：用户要求开源或免 token 时用 MapLibre（`maplibregl` + `MapboxOverlay`），需要 Mapbox 专有能力时才用 `mapbox-gl` 并提醒配置 token
-- **不虚构 API**：属性名以官方文档为准（如聚合权重用 `getColorWeight` / `getElevationWeight`），不确定时先查 <https://deck.gl/docs/api-reference/layers> 再生成
+- **加载与引用**：用 `skill("deck-gl")` 加载（用户也可输入 `/deck-gl`）；本技能无 reference 子目录，示例代码写入会话工作区工程，技能目录只读。
+- **执行环境**：`npm install`、`npm run build` 交给 `pwsh`；子包多、安装输出长，重定向到文件再分段读。
+- **先探测版本**：`npm ls deck.gl @deck.gl/core @deck.gl/layers @deck.gl/geo-layers`；所有 `@deck.gl/*` 必须是同一版本 9.4.0，混版会报 `Cannot read properties of undefined`。本技能按 9.4.0 编写。
+- **验证产物**：`npm run build` 后 `npx serve dist`，`curl.exe -I http://localhost:5173/` 确认入口；WebGL 是否真出图只能由浏览器确认，DSH 不打开浏览器，请用户看画面和控制台，有截图再用 `read_image`。
+- **无 GPU 环境**：无头/CI 环境无法验证 WebGL，构建通过不等于渲染正确，不要据此报告“已渲染”。
+- **数据与坐标**：位置一律 `[经度, 纬度]`；保持 `data` 引用稳定，不要在渲染路径里 `filter`/`map` 生成新数组，否则 GPU 缓冲反复重建。
+- **常见症状**：空白画布先查容器高度与底图；数据变了画面不变用 `updateTriggers`；tooltip 无反应是 `pickable` 默认 false。
+- **安全与权限**：装包、起 dev server 前先征得用户同意；用 Mapbox 底图时提醒 token 与计费。