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

package/assets/gdal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdal
-description: "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)."
+description: "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."
 
 tags:
   - gdal
@@ -415,49 +415,15 @@ gdaltindex -recursive -of GPKG \
 
 ---
 
-## AI 使用建议
-
-### 推荐工作流
-
-1. **探索数据**：
-   ```bash
-   gdalinfo input.tif  # 栅格信息
-   ogrinfo input.shp   # 矢量信息
-   ```
-
-2. **检查支持的格式和驱动**：
-   ```bash
-   gdalinfo --formats
-   ogrinfo --formats
-   ```
-
-3. **分步处理**（避免大内存操作）：
-   ```bash
-   # 不要直接镶嵌所有文件
-   # 改为逐个处理和合并
-   ```
-
-4. **使用 JSON 输出**（便于解析）：
-   ```bash
-   gdalinfo -json input.tif | jq '.coordinateSystem'
-   ogrinfo -json input.shp | jq '.layers[0].featureCount'
-   ```
-
-5. **优化性能**：
-   ```bash
-   # 启用多线程、内存缓存、COG 格式
-   export GDAL_NUM_THREADS=ALL_CPUS
-   export GDAL_CACHEMAX=2048
-   ```
-
-### 关键注意事项
-
-- **始终备份**：GDAL 可以就地修改文件（如 `gdal_edit.py`）
-- **使用绝对路径**：避免工作目录问题
-- **验证坐标系**：重投影前确认源和目标坐标系
-- **测试小数据**：在大数据集上运行前，用小样本测试
-- **使用 VRT（虚拟数据集）**：避免创建多个副本
-- **环境变量**：设置适当的 `GDAL_CACHEMAX` 和 `GDAL_NUM_THREADS`
+## DeepSeek Harness 使用建议
+
+- **加载与引用**：用 `skill("gdal")` 加载（用户也可输入 `/gdal`）；`reference/raster-tools.md`、`reference/vector-tools.md`、`reference/data-formats.md` 按需 `read`，路径相对加载结果中的 Base directory；技能目录只读，产物写到会话工作区。
+- **执行环境**：命令交给 dsh 的 shell 工具（Windows 用 `pwsh`；仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行）。正文的 `apt-get`、`sudo`、`export VAR=` 是 Bash 写法：Windows 改为 `$env:GDAL_NUM_THREADS = "ALL_CPUS"`，无 `sudo`/`apt` 时改用 conda-forge 或 `docker run --rm -v "${PWD}:/data" -w /data osgeo/gdal:latest ...`。
+- **先探测版本**：`gdalinfo --version`、`ogrinfo --version`；本技能按 GDAL 3.13.3 编写，低于 3.9 没有 `gdal <command>` 新式 CLI（`gdal vector`/`gdal raster`），须退回 `ogr2ogr`/`gdalwarp`，且 `gdal_calc.py` 等脚本工具还需要 Python 绑定。
+- **验证产物**：栅格用 `gdalinfo -json out.tif` 核对 `driverShortName`、`size`、`coordinateSystem.wkt`、`bands[].noDataValue`；矢量用 `ogrinfo -so out.shp layer`（或 `ogrinfo -json out.gpkg`）核对 `Feature Count`、`Geometry`、字段列表；不要只凭退出码报告成功。
+- **先看错误再改参数**：`ERROR 4: ... not recognized as a supported file format` 先查路径与 `gdalinfo --formats`；`--debug on` 或 `CPL_DEBUG=ON` 看驱动细节；输出很长时重定向到文件再分段 `read`，不要一次打印全文。
+- **批处理与中间产物**：批量循环建议用 Python 生成命令，中间结果用 `gdalbuildvrt` 写 `.vrt` 而不是反复 `gdalwarp`；耗时命令放后台作业，避免一次重投影全部数据。
+- **安全与权限**：`gdal_edit.py`、`ogr2ogr` 写已有目标、`-overwrite`/`-append` 会就地改写或覆盖数据，先备份或换输出名；安装 GDAL、改 `GDAL_DATA`/`PROJ_LIB`、访问 `/vsis3/`（需 `AWS_SECRET_ACCESS_KEY`）前先征得用户同意，回答里不要回显密钥。
 
 ---
 

package/assets/gdal-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdal-api
-description: "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."
+description: "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."
 
 tags:
   - gdal
@@ -102,7 +102,7 @@ dotnet add package MaxRev.Gdal.LinuxRuntime.Minimal   # Linux
 dotnet add package MaxRev.Gdal.WindowsRuntime.Minimal  # Windows
 ```
 
-**注意：** 官方 SWIG 绑定命名空间为 `OSGeo.GDAL`、`OSGeo.OGR`、`OSGeo.OSR`。NuGet 包 `MaxRev.Gdal.Core` 是社区维护的跨平台封装。
+**注意：** 官方 SWIG 绑定命名空间为 `OSGeo.GDAL`、`OSGeo.OGR`、`OSGeo.OSR`。NuGet 包 `MaxRev.Gdal.Core` 是社区维护的跨平台封装，2026-10 的最新版为 `3.13.3.583`（对应 GDAL 3.13.3），运行时包需与 `MaxRev.Gdal.Core` 主版本一致。
 
 ---
 
@@ -315,34 +315,15 @@ src_ds = None                             # 释放数据源
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **语言选择**：Python 优先（NumPy 集成、语法简洁），性能敏感用 C++，.NET 项目用 C#，Java 项目用 Java
-2. **驱动注册**：任何 GDAL 操作前先调用注册函数（C++: `GDALAllRegister()`, Python 默认已注册）
-3. **探索数据**：先 `gdalinfo`/`ogrinfo` 命令行查数据结构，再编写 API 代码
-4. **异常处理**：Python 脚本开头加 `gdal.UseExceptions()` 启用异常模式
-5. **分块读写**：大栅格使用 `RasterIO` 指定窗口，避免全量加载到内存
-
-### 关键注意事项
-
-- **资源释放**：C++ 用 `GDALClose()`，Python 赋值 `None`，Java 用 `.delete()`，C# 用 `.Dispose()`
-- **坐标轴顺序**：GDAL 3.0+ 默认纬度在前，可用 `SetAxisMappingStrategy` 切换
-- **Python NumPy 集成**：`ReadAsArray()` 直接返回 NumPy 数组，是 Python 最大优势
-- **CS 平台依赖**：C# 需安装对应平台运行时包（Linux/Windows）
-- **JA 本地库**：Java 需确保 `gdalalljni` 在 `java.library.path` 中
-
-### 各语言适用场景
-
-| 场景 | Python | C++ | Java | C# |
-|------|--------|-----|------|-----|
-| 数据处理脚本 | （推荐）首选 | | | |
-| 生产级服务 | | （推荐）首选 | （推荐） | （推荐） |
-| GIS 桌面插件 | （推荐） | | | |
-| .NET 企业应用 | | | | （推荐） |
-| Android GIS | | | （推荐） | |
-| 嵌入式系统 | | （推荐） | | |
+- **加载与引用**：用 `skill("gdal-api")` 加载（用户也可输入 `/gdal-api`）；`reference/raster-api.md`（栅格读写的完整 API）、`reference/vector-api.md`（OGR 图层与 GeoPackage）按需 `read`，路径相对 Base directory；技能目录只读，示例代码与产物写到会话工作区。
+- **执行环境**：编译与运行交给 dsh 的 shell 工具（Windows 用 `pwsh`；仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行）。C++ 用 `gdal-config --cflags --libs` 或 CMake `find_package(GDAL REQUIRED)`；Python 用装好绑定的解释器；Java 的 `gdalalljni`、.NET 的 MaxRev 运行时包必须与平台、架构匹配。
+- **先探测版本**：`ogrinfo --version`、`python -c "from osgeo import gdal; print(gdal.VersionInfo())"`（返回 `3130300` 这类数字）、`mvn -v`、`dotnet --version`；本技能按 GDAL 3.13.3、Java 绑定 3.13.0 编写，低版本缺少新驱动与部分 SWIG 方法，回答里要说明差异。
+- **验证产物**：写完后重新打开核对——`python -c "from osgeo import gdal; ds=gdal.Open('out.tif'); print(ds.GetDriver().ShortName, ds.RasterCount, ds.GetSpatialRef().GetAuthorityCode(None))"`；矢量用 `ogrinfo -al -so out.gpkg` 看要素数与字段；Python 一律先 `gdal.UseExceptions()`，否则错误被静默吞掉。
+- **语言选择**：数据处理脚本优先 Python（`ReadAsArray()` 直通 NumPy）；生产服务与嵌入式优先 C++；Java 注意用 `java.util.Vector<String>` 传选项；.NET 用 `OSGeo.GDAL`/`OSGeo.OGR` 命名空间，或 MaxRev 封装 + 对应平台运行时包。
+- **资源与轴序**：Python 置 `ds = None`、C++ `GDALClose()`、Java `.delete()`、C# `.Dispose()` 之后才算落盘；GDAL 3+ 默认纬度在前，需要经度在前时用 `SetAxisMappingStrategy(OAMS_TRADITIONAL_GIS_ORDER)`，轴序改错是坐标错位最常见的原因。
+- **安全与权限**：以更新模式（`gdal.GA_Update`、`GDALOpen(..., GA_Update)`）打开会直接改原文件；覆盖已有输出前先确认；安装 `libgdal-dev`、`dotnet add package`、写系统目录前先征得用户同意。
 
 ## 相关技能
 

package/assets/geometry-api-java/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geometry-api-java
-description: "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."
+description: "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."
 tags:
   - java
   - geometry
@@ -376,23 +376,16 @@ if (hit) {
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **创建几何对象**：使用 `Point`、`Polyline`、`Polygon` 等构造函数创建几何
-2. **设置空间参考**：通过 `SpatialReference.create(wkid)` 指定坐标系
-3. **空间运算**：优先使用 `GeometryEngine` 静态方法（线程安全、API 简洁）；批量处理使用 `OperatorFactoryLocal` + `GeometryCursor`
-4. **格式转换**：使用 `GeometryEngine.geometryToGeoJson()` / `geometryFromWkt()` 等方法进行 WKT、GeoJSON、Esri JSON 互转；WKB 通过 `OperatorImportFromWkb` / `OperatorExportToWkb` 算子
-5. **大地测量**：经纬度距离使用 `GeometryEngine.geodesicDistanceOnWGS84()`（返回米）；椭球面积/长度算子未对外公开，需要时改用 JTS / GeoTools
-
-### 关键注意事项
-
-- **坐标系一致**：进行空间运算前，确保所有几何对象使用相同的 `SpatialReference`
-- **简化几何**：导入外部数据后，使用 `GeometryEngine.simplify()` 确保拓扑正确
-- **大地测量 vs 平面**：经纬度距离用 `geodesicDistanceOnWGS84()`；椭球面积/长度算子未公开，建议改用 JTS/GeoTools
-- **性能优化**：批量操作使用 `OperatorFactoryLocal` + `GeometryCursor`，而非逐个调用 `GeometryEngine` 静态方法
-- **线程安全**：`GeometryEngine` 静态方法是线程安全的；`Operator` 实例非线程安全
+- **加载与引用**：用 `skill("geometry-api-java")` 加载（用户也可输入 `/geometry-api-java`）；本技能没有 `reference/` 子目录，示例都在正文；技能目录只读，Maven 工程建在会话工作区。
+- **执行环境**：先 `mvn -v` 与 `java -version` 确认工具链（JDK 8+ 即可编译，建议 17/21 运行），Windows 上用 `pwsh` 执行；`%JAVA_HOME%`/`JAVA_HOME` 与 `mvn` 实际使用的 JDK 可能不同，报 `Unsupported class file major version` 时按 `mvn -v` 显示的 JDK 判断。
+- **依赖坐标**：`com.esri.geometry:esri-geometry-api:2.2.4` 是 Maven Central 最新（2020-09 发布）；上游 2.3.1（2026-10-09）未发布到 Central。先 `mvn dependency:get -Dartifact=com.esri.geometry:esri-geometry-api:2.2.4` 确认可解析，解析失败时报告“依赖不可下载”，不要自行改成 2.3.1 或别处坐标。
+- **离线与网络**：首次 `mvn` 会拉依赖，无网或私服缺包时报 `Could not resolve dependencies`；不要为绕过它去改 `settings.xml`、加未知仓库或降级版本，先向用户要可用镜像。
+- **验证产物**：写最小 main（或 JUnit）断言三件事——`geometryFromWkt` → `geometryToWkt` 往返等价、`GeometryEngine.buffer(poly, sr, 2.0)` 后 `getEnvelope()` 向外扩张、`geometryToGeoJson` 能被 `geoJsonToGeometry` 重新读入；`mvn -q -DskipTests package` 只证明能编译，不代表几何正确。
+- **编译期陷阱**：`GeometryEngine` 没有 `intersects` 和 WKB 方法，分别用 `OperatorIntersects.local().execute(a, b, sr, null)` 与 `OperatorImportFromWkb`/`OperatorExportToWkb`；面积/长度用 `geometry.calculateArea2D()` / `calculateLength2D()`，不要去找 `getArea()`。
+- **坐标与线程**：参与运算的几何必须带同一 `SpatialReference`；`GeometryEngine` 静态方法可并发调用，`Operator` 实例非线程安全，批量时用 `OperatorFactoryLocal` + `GeometryCursor` 并每线程持有自己的算子。
+- **安全与权限**：`mvn` 会写 `~/.m2` 与工作区 `target/`，属预期行为；执行 `mvn install`/`deploy`、改动共享 `settings.xml` 或写入系统目录前先征得用户同意。
 
 ## 相关技能
 

package/assets/geometry-api-net/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geometry-api-net
-description: "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."
+description: "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."
 tags:
   - dotnet
   - geometry
@@ -304,23 +304,16 @@ dotnet run --project samples/OpenGIS.Esri.Geometry.Samples
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **创建几何对象**：使用 `Point`、`Polyline`、`Polygon` 等构造函数创建几何
-2. **空间运算**：优先使用 `GeometryEngine` 静态方法（API 最简洁）；需要精细控制时使用 `Operator.Instance` 单例模式
-3. **格式转换**：使用 `GeometryEngine.GeometryToGeoJson()` / `GeometryFromWkt()` 等方法进行 WKT、WKB、GeoJSON、Esri JSON 互转
-4. **大地测量**：对地理坐标的距离/面积计算，使用 `GeometryEngine.GeodesicDistance()` / `GeodesicArea()`
-5. **序列化集成**：使用 `OpenGIS.Esri.Geometry.Json.Converters` 命名空间的 `System.Text.Json` 转换器
-
-### 关键注意事项
-
-- **Polygon 环必须闭合**：首尾点必须相同
-- **返回类型需转换**：集合运算返回 `Geometry` 基类，需根据实际类型做类型转换
-- **大地测量基于 WGS84**：`GeodesicDistance` 使用 Vincenty 公式
-- **GeoJSON 导出规则**：单路径 Polyline 导出为 `LineString`，多路径导出为 `MultiLineString`
-- **Operator 使用 Lazy 单例**：所有 Operator 类通过 `Instance` 属性获取单例实例
+- **加载与引用**：用 `skill("geometry-api-net")` 加载（用户也可输入 `/geometry-api-net`）；`reference/geometry-types.md` 按需 `read`，路径相对加载结果中的 Base directory；技能目录只读，示例工程建在会话工作区。
+- **执行环境**：先 `dotnet --version`（库目标 `netstandard2.0`，可被 net6/net8/net9/net10 引用）；Windows 上用 `pwsh` 执行 `dotnet` 命令，`dotnet new console -o demo && cd demo` 建最小工程。
+- **依赖坐标**：`dotnet add package OpenGIS.Esri.Geometry.Core --version 1.0.9`（NuGet 最新 1.0.9，2026-09-21），需要 `System.Text.Json` 转换器时再装 `OpenGIS.Esri.Geometry.Json`；还原失败报 `NU1101` 说明源或版本不可用，报告“依赖不可下载”，不要自己编版本号。
+- **验证产物**：最小控制台程序断言三件事——`GeometryEngine.GeometryFromWkt` → `GeometryToWkt` 往返、`GeometryEngine.Contains(polygon, point)` 返回 true、`GeometryEngine.Buffer(point, 5.0).GetEnvelope()` 为 (XMin=5,YMin=15,XMax=15,YMax=25)，再 `dotnet run` 看实际输出；`dotnet build` 成功不代表几何结果正确。
+- **构建与测试**：`dotnet build` 编译、`dotnet test` 跑 xUnit、`dotnet run --project samples/OpenGIS.Esri.Geometry.Samples` 跑示例（需在仓库 checkout 内，且该路径存在）；输出在 `bin/`、`obj/`，不要提交。
+- **编译期陷阱**：`Polygon.AddRing` 必须闭合（首尾点相同）否则面积/包含判断异常；集合运算返回 `Geometry` 基类，要按 `Point`/`Polygon` 转型后再用；容差 `GeometryConstants.DefaultTolerance`（1e-10）是内部常量，无法外部调整。
+- **大地测量前提**：`GeodesicDistance`/`GeodesicArea` 基于 WGS84（Vincenty），输入必须是经纬度；对投影坐标（如 EPSG:3857 米制）调用会得到无意义结果。
+- **安全与权限**：`dotnet restore` 需访问 NuGet 源，离线时先确认本地缓存；修改全局 `NuGet.config`、安装 SDK 或写入系统目录前先征得用户同意，命令输出里不要回显私有源凭据。
 
 ## 常见问题
 

package/assets/geopandas/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geopandas
-description: "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."
+description: "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."
 tags:
   - python
   - pandas
@@ -356,24 +356,16 @@ m = gdf.explore(column="population", cmap="viridis",
 | `DriverError` 无法写入 | 驱动不支持或文件被占用 | 检查驱动名拼写、关闭已打开的文件 |
 | `align=True` 导致意外 NaN | 二元操作默认按索引对齐 | 传入 `align=False` 或重置索引 |
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **读取数据**：使用 `gpd.read_file()` 读取矢量文件，或 `gpd.read_parquet()` 读取 GeoParquet
-2. **检查 CRS**：始终先检查 `gdf.crs`，需要在投影坐标系（非地理坐标系）下进行面积/距离计算
-3. **空间分析**：使用 `gpd.sjoin()` 进行空间连接，`gpd.overlay()` 进行叠加分析，`gpd.clip()` 进行裁剪
-4. **可视化**：使用 `.plot()` 快速静态出图，`.explore()` 生成交互式地图
-5. **输出**：使用 `gdf.to_file()` 或 `gdf.to_parquet()` 保存结果，优先使用 GeoPackage 或 GeoParquet 格式
-
-### 关键注意事项
-
-- **`set_crs()` vs `to_crs()`**：`set_crs()` 仅标记坐标系不转换坐标，`to_crs()` 执行实际坐标变换——切勿混用
-- **面积/距离计算前投影**：地理坐标系（EPSG:4326）下面积单位为度²无意义，应使用 `gdf.to_crs(gdf.estimate_utm_crs())` 投影后再计算
-- **空间操作前统一 CRS**：确保参与 `sjoin`、`overlay`、`clip` 的所有 GeoDataFrame 使用相同 CRS
-- **优先使用 GeoParquet**：比 Shapefile/GeoJSON 读写快 5-10 倍，且无字段名长度限制
-- **向量化操作**：避免逐行循环，使用 GeoSeries 的向量化方法（`buffer()`、`intersection()` 等）批量处理
-- **空间索引自动构建**：`.sindex` 自动维护 STRtree，`query()` 和 `nearest()` 可大幅加速空间查询
+- **加载与引用**：用 `skill("geopandas")` 加载（用户也可输入 `/geopandas`）；`reference/core-api.md` 按需 `read`，路径相对加载结果中的 Base directory；技能目录只读，脚本与产物写到会话工作区。
+- **执行环境**：命令交给 dsh 的 shell 工具（Windows 用 `pwsh`，仅暴露 `run_code` 的会话在 `tools.pwsh` 里跑）；不要假设 `python` 是 QGIS/GDAL 自带的解释器，先 `python -c "import sys; print(sys.executable, sys.version)"`。
+- **先探测版本**：`python -c "import geopandas as gpd; print(gpd.__version__, gpd.options.io_engine)"`；本技能按 1.2.0 / Python >= 3.11 编写，低版本会缺 `to_arrow`、`to_parquet(geometry_encoding=...)` 与 1.2 新绘图参数（`tiles=`、`legend_kwds={"colorbar": True}`），回答时说明差异而不是硬写。
+- **检查依赖后端**：`python -c "import pyogrio, pyproj; print(pyogrio.__version__, pyproj.__version__, pyproj.datadir.get_data_dir())"`；PROJ 数据目录缺失时 `to_crs("EPSG:3857")` 抛 `CRSError: Invalid projection`，装 `pyproj`/`pyogrio` 前先征得用户同意。
+- **验证产物（必做）**：写完立即重开核对，`gdf = gpd.read_file("out.gpkg", layer="result"); print(gdf.crs, len(gdf), gdf.is_valid.all(), gdf.total_bounds)`，并确认面积/长度是在投影坐标系下算的。
+- **落图后看图**：`ax = gdf.plot(column="pop", legend=True, figsize=(12, 8)); ax.figure.savefig("map.png", dpi=100)`（需 matplotlib），再用 `read_image("map.png")` 检查范围、图例与空几何，不要只凭退出码报告成功。
+- **典型误操**：`set_crs()` 只标记不改坐标、`to_file()` 默认整表覆盖、`to_postgis(if_exists="replace")` 会删表重建——执行前确认目标路径/表名，Shapefile 字段名超 10 字符会被截断，改用 `.gpkg`。
+- **安全**：数据库连接串里的密码不要回显在命令输出里；`pip install geopandas[all]`、写入系统目录或覆盖生产数据前先得到用户确认。
 
 ## 相关技能
 

package/assets/geopipe-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geopipe-agent
-description: "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."
+description: "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)."
 tags:
   - gis
   - agent
@@ -247,26 +247,16 @@ QC 步骤遵循 **「检查即透传」** 模式：输入数据原样通过为 `
 | 网络分析 | `io.read_vector → network.shortest_path → network.service_area → io.write_vector ×2` |
 | 空间聚类 + 热力图 | `io.read_vector → analysis.cluster(dbscan) → analysis.heatmap → io.write_vector + io.write_raster` |
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **理解需求**：用户要做什么 GIS 分析？
-2. **列出可用步骤**：`geopipe-agent list-steps` 或查阅步骤表
-3. **编写 YAML**：按 `io.read_vector → 处理步骤 → io.write_vector` 模式编排
-4. **加入 QC**：在关键步骤前后插入质检步骤
-5. **执行**：`geopipe-agent run pipeline.yaml`
-6. **解读结果**：检查 JSON 报告中的 `qc_summary` 和统计信息
-
-### 关键注意事项
-
-- **步骤 ID 规则**：只能用小写字母、数字、下划线和连字符，不能含点号（`.` 保留用于属性引用）
-- **引用链完整性**：确保每个 `$step_id` 引用的步骤在当前步骤之前定义
-- **QC 链式调用**：QC 步骤可串联（如 `qc.geometry_validity → qc.attribute_completeness → qc.topology`），问题汇总到管道报告的 `qc_summary` 中；请使用 `geopipe-agent list-steps --category qc` 列出的真实步骤 ID，写错 ID 会导致校验失败
-- **后端选择**：默认 `native_python`（纯 Python，无外部依赖）；可在步骤上用 `backend: <名称>` 指定 gdal_cli / gdal_python / qgis_process / pyqgis / generic_cli / curl_api，用 `geopipe-agent backends` 查看当前环境可用后端。注意：**只有声明了 backends 的步骤会读取该字段**（当前为 6 个矢量步骤），其余步骤写 `backend:` 会被忽略
-- **路径使用绝对路径**：避免工作目录问题
-- **未实现的能力**：若某个步骤 ID 尚未实现，`validate` 会直接报错；此时不要猜测参数，改用 `geopipe-agent resolve "<需求>"` 获取候选能力与回退路径
-- **大数据注意**：管道在内存中运行，超大栅格建议先裁剪
+- **加载与引用**：用 `skill("geopipe-agent")` 加载（用户也可输入 `/geopipe-agent`）；`reference/steps-reference.md`、`pipeline-schema.md`、`workflows.md`、`self-extension.md` 按需 `read`，路径相对加载结果中的 Base directory；技能目录只读，YAML 与输出写到会话工作区。
+- **执行环境**：命令交给 dsh 的 shell 工具（Windows 用 `pwsh`）；`python` 可能指向 QGIS/GDAL 自带解释器，建议在工作区建独立 venv 后 `pip install -e .`，避免污染系统环境。
+- **源码安装（未上 PyPI）**：`git clone https://github.com/znlgis/GeoPipeAgent.git && pip install -e ".[analysis,network]"`；验证 `geopipe-agent --help`、`geopipe-agent list-steps --category qc`、`pip show geopipe-agent | Select-String Version`。不要写 `pip install geopipe-agent`——PyPI 上还没有这个包。
+- **先探测能力**：`geopipe-agent backends` 看当前环境可用后端（默认 `native_python`），`geopipe-agent list-steps --format json` 拿真实步骤 ID；`validate` 报 `not registered` 时先用 `geopipe-agent resolve "<需求>"` 与 `knowledge search`，不要猜参数。
+- **验证产物**：`geopipe-agent validate pipeline.yaml` 通过后再 `run pipeline.yaml`，检查 JSON 报告里的 `qc_summary` 与各步骤统计，随后重开输出文件核对（`geopipe-agent info output/result.geojson`，装了 GDAL 时也可 `ogrinfo -so output/result.geojson result`），确认要素数与 CRS 而不是只看“执行成功”。
+- **典型误操**：步骤 ID 不能含点号，`$step_id` 必须由更早步骤提供，`when` 引用不存在的属性会按 false **静默跳过**；`backend:` 只有声明了 backends 的 6 个矢量步骤会读取，其余步骤写了也被忽略。
+- **性能与内存**：管道全程在内存中运行，超大栅格先 `raster.clip` 或 `io.read_raster` 只读所需波段；QC 步骤是“检查即透传”，`output` 就是输入，问题在 `$step.issues` / `issues_gdf`。
+- **安全与权限**：`network.geocode` 与 `curl_api`、`http.request` 会把数据发到外部服务，执行前确认是否允许出网并检查 `user_agent`/凭据；`pip install`、覆盖已有输出文件、批量改写数据前先征得用户同意。
 
 ---
 

package/assets/geoserver/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geoserver
-description: "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."
+description: "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."
 tags:
   - java
   - server
@@ -20,7 +20,9 @@ tags:
 >
 > **下载：** <https://geoserver.org/release/stable/>
 >
-> **最新版本：** 3.0.1（截至 2026-10，[官方下载](https://geoserver.org/release/stable/)）
+> **最新版本：** 3.0.2（2026-10-19，安全修复版，生产应优先升级；[官方下载](https://geoserver.org/release/stable/)）
+>
+> **运行环境：** Java 17 或 21；3.0.2 内含 GeoTools 35.2、GeoWebCache 2.0.2
 >
 > **许可证：** GPL-2.0
 
@@ -41,11 +43,15 @@ GeoServer 提供：
 
 ## 安装部署
 
+### 前置：JDK
+
+3.0.x 需要 **Java 17 或 21**；先 `java -version` 确认（低于 17 的 JVM 无法启动 3.x 分发包）。
+
 ### 二进制
 
 ```bash
-wget https://sourceforge.net/projects/geoserver/files/GeoServer/3.0.1/geoserver-3.0.1-bin.zip
-unzip geoserver-3.0.1-bin.zip && cd geoserver-3.0.1
+curl -fLO https://sourceforge.net/projects/geoserver/files/GeoServer/3.0.2/geoserver-3.0.2-bin.zip
+unzip geoserver-3.0.2-bin.zip && cd geoserver-3.0.2
 sh bin/startup.sh         # http://localhost:8080/geoserver  (admin/geoserver)
 ```
 
@@ -56,7 +62,7 @@ docker run --name gs -p 8080:8080 \
   -e SKIP_DEMO_DATA=true \
   -e EXTRA_JAVA_OPTS="-Xms512m -Xmx2g" \
   -v $PWD/data:/opt/geoserver_data \
-  docker.osgeo.org/geoserver:3.0.1
+  docker.osgeo.org/geoserver:3.0.2
 ```
 
 ### 数据目录
@@ -169,7 +175,7 @@ curl -u admin:geoserver -XPOST \
 
 ## 典型工作流
 
-1. **部署 GeoServer**：优先使用 Docker 镜像 `docker.osgeo.org/geoserver:3.0.1`
+1. **部署 GeoServer**：优先使用 Docker 镜像 `docker.osgeo.org/geoserver:3.0.2`（安全修复版；从旧版本升级前先备份数据目录）
 2. **创建 Workspace**：为每个项目创建独立工作空间实现命名隔离
 3. **添加数据存储**：根据数据类型选择 PostGIS（矢量）、Shapefile（文件矢量）、GeoTIFF（栅格）
 4. **发布图层**：设置 SRS（坐标参考系）、计算 Native Bounds、配置样式
@@ -202,26 +208,15 @@ curl -u admin:geoserver -XPOST \
 
 ---
 
-## AI 使用建议
-
-
-### 关键注意事项
+## DeepSeek Harness 使用建议
 
-- **数据源编码**：Shapefile 中文乱码时在 Store 设置 `charset=UTF-8` 或 `GBK`
-- **Native Bounds**：必须正确计算图层的原始范围，否则 WMS 请求可能返回空白
-- **级联删除**：删除 Workspace/Store 时添加 `?recurse=true` 参数
-- **JVM 调优**：生产环境建议 `-Xms2g -Xmx4g -XX:+UseG1GC`
-- **CORS 配置**：跨域访问需在 `web.xml` 中配置 CORS 过滤器
-- **SLD 样式**：使用 SLD Cookbook 快速参考常用样式模板
-
-### 常见配置模式
-
-```text
-工作空间(Workspace)
-  ├── 数据存储(Store) ─→ PostGIS / Shapefile / GeoTIFF
-  │    └── 图层(Layer) ─→ 设置 SRS + 绑定样式(Style)
-  └── 图层组(LayerGroup) ─→ 组合多个图层统一发布
-```
+- **加载与引用**：`skill("geoserver")` 加载；技能目录只读，SLD、脚本、日志等产物写到会话工作区。
+- **执行环境**：命令交给 dsh 的 shell 工具（Windows 用 `pwsh`）；`wget`/`unzip` 换成 `curl.exe -LO` 与 `Expand-Archive`，`$PWD` 换成 `(Get-Location)`。
+- **先探测版本**：`curl -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json`（无 jq 时管道给 `python -m json.tool`），核对 GeoServer、GeoWebCache 与 JVM；`java -version` 必须是 17 或 21，否则 3.0.2 包直接启动失败。
+- **验证产物**：发布后用 `curl -s -o out.png -w "%{http_code} %{size_download}\n" "http://localhost:8080/geoserver/my_ws/wms?service=WMS&version=1.1.0&request=GetMap&layers=my_ws:poi&srs=EPSG:4326&bbox=...&width=512&height=512&format=image/png"`，要 200 且字节数大于 0；再拉一次 `GetCapabilities` 确认图层已注册，不要只凭 UI 回显。
+- **写后回读**：REST 建 workspace/store/layer 或上传 SLD 后，用同路径 GET 回读；`?recurse=true` 删除后再 GET 应得 404。
+- **安全与权限**：`admin:geoserver` 凭据不要回显到命令输出或报告里（用环境变量传入）；重启容器、改 `-Xmx`、删除 workspace、清 GWC 缓存前先征得用户同意。
+- **常见误操作**：WMS 返回空白图先查 native bounds 与 SRS 是否对不上；Shapefile 中文乱码改 Store 的 `charset`；seed 大范围瓦片会撑爆磁盘，先小 zoom 范围试。
 
 ## 相关技能
 

package/assets/geoserver-cloud/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geoserver-cloud
-description: "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."
+description: "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."
 tags:
   - java
   - server
@@ -18,9 +18,9 @@ tags:
 >
 > **官方文档：** <https://geoserver.org/geoserver-cloud/>
 >
-> **Docker Hub：** <https://hub.docker.com/u/geoservercloud>（镜像标签与 GeoServer 主版本对应，如 `3.0.1.1`）
+> **Docker Hub：** <https://hub.docker.com/u/geoservercloud>（镜像标签与 GeoServer 主版本对应，如 `3.0.2`）
 >
-> **最新版本：** 3.0.1.1（截至 2026-10，[GitHub Releases](https://github.com/geoserver/geoserver-cloud/releases)）
+> **最新版本：** 3.0.2（2026-10-20，[GitHub Releases](https://github.com/geoserver/geoserver-cloud/releases)）
 >
 > **许可证：** GPL-2.0
 
@@ -98,7 +98,7 @@ PGCONFIG_SCHEMA: "pgconfig"          # 启动时自动创建 schema
 ## Kubernetes（Helm）
 
 ```bash
-# Chart：camptocamp/helm-geoserver-cloud（chart 名 geoservercloud，最新 3.0.1）
+# Chart：camptocamp/helm-geoserver-cloud（chart 名 geoservercloud，最新 3.0.2）
 helm repo add geoserver-cloud https://camptocamp.github.io/helm-geoserver-cloud
 helm repo update
 ```
@@ -110,7 +110,7 @@ helm repo update
 > dependencies:
 >   - name: geoservercloud
 >     repository: https://camptocamp.github.io/helm-geoserver-cloud
->     version: 3.0.1
+>     version: 3.0.2
 > ```
 >
 > ```yaml
@@ -182,7 +182,7 @@ management:
 ```bash
 docker run -e SPRING_PROFILES_ACTIVE=datadir \
   -v /mnt/gsdata:/opt/app/data_directory \
-  geoservercloud/geoserver-cloud-wms:3.0.1.1
+  geoservercloud/geoserver-cloud-wms:3.0.2
 ```
 
 ---
@@ -247,25 +247,15 @@ kubectl -n gis get deploy | grep wms
 kubectl -n gis scale deploy <wms-deployment> --replicas=10
 ```
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **确定架构**：根据业务需求选择配置后端（生产推荐 PgConfig）
-2. **部署基础设施**：先部署 RabbitMQ + PostgreSQL（PgConfig 目录库），再启动微服务
-3. **启动服务**：下载官方稳定版 docker-compose 文件或用 Helm Chart 部署
-4. **验证服务**：通过 Gateway (`localhost:9090/geoserver/cloud`) 访问 Web UI
-5. **配置监控**：启用 Prometheus + Grafana 监控各微服务状态
-6. **弹性伸缩**：按负载独立扩缩 WMS/WFS 等服务的副本数
-
-### 关键注意事项
-
-- **启动顺序**：先启动 discovery/Consul → config → 数据库/RabbitMQ → 各业务服务
-- **配置同步**：确保 `GEOSERVER_BUS_ENABLED=true` 且 RabbitMQ 可达
-- **路径前缀**：默认 `GEOSERVER_BASE_PATH=/geoserver/cloud`，构造服务 URL 时不要漏掉
-- **PgConfig 一致性**：多副本共享同一个 PgConfig 数据库实现强一致
-- **JVM 独立调优**：每个微服务根据负载独立设置 `-Xmx`，避免 OOM
-- **不部署不需要的服务**：如不使用 WPS/WCS，直接从 docker-compose 中移除
+- **加载与引用**：`skill("geoserver-cloud")` 加载；技能目录只读，compose/values 覆写文件写到会话工作区。
+- **执行环境**：命令交给 dsh 的 `pwsh`（Windows 无 `wget`，改 `curl.exe -LO`）；先用 `docker version`、`helm version`、`kubectl version --client` 确认工具在 PATH。
+- **先探测版本**：`curl.exe -s -u admin:geoserver http://localhost:9090/geoserver/cloud/rest/about/version.json` 读 GeoServer 版本；`curl.exe -s http://localhost:9090/actuator/health` 取 `{"status":"UP"}`（被 profile 关掉时改用 `kubectl -n gis get pods` 判活）。
+- **验证产物**：部署后逐服务探活，再经网关 `.../rest/workspaces.json` 与一次 WMS `GetMap` 走通全链路；`docker compose ps` 显示 Up 不等于 OGC 服务可用。
+- **排障顺序**：502 → 查 Consul 注册与目标服务健康（`kubectl -n gis logs deploy/<wms>`）；配置不生效 → 查 RabbitMQ 与 `GEOSERVER_BUS_ENABLED`；瓦片 404 → 查 gwc 是否部署、`GEOSERVER_BASE_PATH` 前缀是否一致。
+- **安全与权限**：`admin:geoserver`、`PGCONFIG_PASSWORD`、RabbitMQ 口令不要回显到报告；`docker compose down -v`、`helm uninstall`、删 PVC 或 PgConfig schema 会丢配置，先向用户确认并备份。
+- **先本地复现**：能在 docker compose 复现的问题再上 K8s；镜像标签与 chart 版本保持同一版本号（3.0.2），避免网关与服务错配。
 
 ## 相关技能
 

package/assets/geoserver-rest-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geoserver-rest-api
-description: "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."
+description: "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."
 tags:
   - rest
   - api
@@ -20,7 +20,7 @@ tags:
 >
 > **API 参考：** <https://docs.geoserver.org/stable/en/user/rest/api/index.html>
 >
-> **最新版本：** GeoServer 3.0.1（截至 2026-10，[官方下载](https://geoserver.org/release/stable/)）
+> **最新版本：** GeoServer 3.0.2（2026-10-19，安全修复版；[官方下载](https://geoserver.org/release/stable/)）
 >
 > **许可证：** GPL-2.0
 
@@ -354,25 +354,15 @@ await workspaceService.CreateWorkspaceAsync("myws");
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **确认 GeoServer 运行**：先验证 `http://localhost:8080/geoserver/rest/about/version.json` 可访问
-2. **创建工作空间**：POST `/rest/workspaces` → 创建命名空间
-3. **添加数据存储**：根据数据类型 POST datastores（矢量）或 coveragestores（栅格）
-4. **发布图层**：POST featuretypes（矢量）或 coverages（栅格）
-5. **配置样式**：POST styles + PUT SLD 文件 → PUT layers 绑定样式
-6. **验证发布**：GET `/rest/layers.json` 确认图层列表，访问 WMS GetMap 测试
-
-### 关键注意事项
-
-- **JSON 包装结构**：GeoServer REST API 的 JSON 请求/响应使用单层包装（如 `{"workspace":{...}}`）
-- **recurse 参数**：删除 Workspace/Store 时务必添加 `?recurse=true` 级联删除
-- **Shapefile 上传**：必须打包为 ZIP（含 .shp/.shx/.dbf/.prj），用 PUT 方式上传
-- **URL 后缀**：可用 `.json` / `.xml` 后缀替代 `Accept` 头指定响应格式
-- **Content-Type**：样式上传使用 `application/vnd.ogc.sld+xml`，栅格上传使用 `image/tiff`
-- **认证**：所有 POST/PUT/DELETE 操作需要 HTTP Basic Auth（默认 admin:geoserver）
+- **加载与引用**：`skill("geoserver-rest-api")` 加载；完整端点清单按需 `read` [reference/endpoints.md](reference/endpoints.md)（路径相对技能 Base directory），不要整份通读。
+- **执行环境**：示例交给 dsh 的 `pwsh`（显式 `curl.exe`，Windows 的 `curl` 是别名、参数不同）；`\` 续行在 pwsh 无效，压成单行；请求体先写成 `body.json`，用 `curl.exe --data "@body.json"` 传，避开各 shell 的引号差异。
+- **先探测版本**：`curl.exe -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json`，确认是 3.0.2 并顺带看到组件版本；返回 401 是凭据/安全规则问题，不是版本问题。
+- **验证产物**：写操作后立刻 GET 回读同一资源（`.../rest/workspaces/myws.json`、`.../rest/layers/myws:roads.json`），再发一次 WMS `GetMap` 取 `image/png` 确认非空图；不要只凭 201 或退出码报告成功。
+- **幂等与坑**：同名资源重复 POST 会报已存在（重跑脚本前先 GET 判断或改 PUT）；改了样式记得清 GWC 缓存，否则瓦片还是旧的。
+- **安全与权限**：`admin:geoserver` 不要硬编码进脚本或回显到报告；`?recurse=true` 删除 workspace、`POST /rest/reset`、清缓存均不可逆，执行前向用户确认。
+- **批量脚本**：循环建资源时检查 `$LASTEXITCODE`，一失败即停；半套配置留在服务端比报错更难排查。
 
 ## 相关技能
 

package/assets/geotools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geotools
-description: "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."
+description: "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."
 tags:
   - java
   - gis
@@ -18,7 +18,7 @@ tags:
 >
 > **Maven GroupId：** `org.geotools`
 >
-> **最新版本：** 35.1（截至 2026-10，[OSGeo Maven 仓库](https://repo.osgeo.org/repository/release/)）
+> **最新版本：** 35.2（2026-10-16，[OSGeo Maven 仓库](https://repo.osgeo.org/repository/release/)）
 >
 > **许可证：** LGPL 2.1
 >
@@ -60,7 +60,7 @@ GeoTools 发布在 OSGeo Maven 仓库，需在 `pom.xml` 中添加：
 
 ```xml
 <properties>
-    <geotools.version>35.1</geotools.version><!-- 最新稳定版；版本列表见 https://geotools.org/ -->
+    <geotools.version>35.2</geotools.version><!-- 最新稳定版；版本列表见 https://geotools.org/ -->
 </properties>
 
 <dependencies>
@@ -386,25 +386,15 @@ store.dispose();
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **配置 Maven 仓库**：在 `pom.xml` 中添加 OSGeo 仓库（`https://repo.osgeo.org/repository/release/`）
-2. **引入必要模块**：`gt-main`（核心）、`gt-shapefile` / `gt-geopkg`（数据源）、`gt-epsg-hsql`（CRS）、`gt-cql`（查询）、`gt-render`（渲染）
-3. **打开数据源**：使用 `FileDataStoreFinder.getDataStore()`（文件）或 `DataStoreFinder.getDataStore(params)`（数据库）
-4. **执行查询**：使用 `CQL.toFilter()` 构建过滤器 → `featureSource.getFeatures(filter)`
-5. **处理结果**：遍历 `SimpleFeatureIterator`，使用 JTS 几何方法进行空间运算
-6. **释放资源**：`store.dispose()`、关闭 `SimpleFeatureIterator`
-
-### 关键注意事项
-
-- **Maven 仓库必需**：GeoTools 不在 Maven Central，必须配置 OSGeo 仓库
-- **EPSG 数据库**：使用 CRS 功能需引入 `gt-epsg-hsql`，否则 `CRS.decode()` 抛出异常
-- **资源释放**：`DataStore`、`Reader`、`Writer`、`MapContent` 使用后必须调用 `dispose()`
-- **坐标轴顺序**：GeoTools 默认遵循 EPSG 规范（纬度在前），使用 `CRS.decode("EPSG:4326", true)` 强制经度在前
-- **线程安全**：`DataStore` 线程安全可共享；`SimpleFeatureIterator` 非线程安全
-- **JTS 包名**：GeoTools 20+ 使用 `org.locationtech.jts`（GeoTools ≤19 为旧版 `com.vividsolutions.jts`）
+- **加载与引用**：`skill("geotools")` 加载；完整示例在 [reference/vector-io.md](reference/vector-io.md) 与 [reference/raster-rendering.md](reference/raster-rendering.md)，按需 `read`（路径相对技能 Base directory）。
+- **执行环境**：命令交给 dsh 的 `pwsh`；先 `java -version` 与 `mvn -v` 确认 JDK 17，35.x 在 JDK 8/11 下编译即失败。
+- **先探测版本**：`mvn dependency:tree -Dincludes=org.geotools` 确认解析到 35.2 且未被其他依赖压回旧版；`pom.xml` 里必须有指向 `repo.osgeo.org/repository/release/` 的 `<repository>`。
+- **验证产物**：`mvn -q -DskipTests package` 后跑最小读图层程序（`FileDataStoreFinder` → `getFeatures()` → 打印 count 与 CRS）或 `mvn -q test`；`CRS.decode("EPSG:4326")` 抛异常说明缺 `gt-epsg-hsql`。
+- **常见失败信号**：`getDataStore()` 返回 null 或报找不到工厂，是 SPI 模块没进 classpath；出现 `com.vividsolutions.jts` 是包名没升级（GeoTools 20+ 用 `org.locationtech.jts`）。
+- **安全与权限**：测试别全量加载要素到内存（用 `Query` 限制属性与 bbox）；连接串/密码不要回显，对生产库批量写入前先向用户确认。
+- **按需读文件**：本 SKILL 较长，先按章节标题定位，再用 `read` 的 offset/limit 只取相关段，避免整篇占满上下文。
 
 ## 相关技能