@dsh-gis/dsh-opengis-skill 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/CHANGELOG.md +89 -1
  2. package/README.md +78 -21
  3. package/adaptations/brutile.md +19 -6
  4. package/adaptations/cesiumjs.md +14 -5
  5. package/adaptations/common.md +49 -16
  6. package/adaptations/deck-gl.md +19 -6
  7. package/adaptations/duckdb-spatial.md +20 -6
  8. package/adaptations/gdal-api.md +24 -6
  9. package/adaptations/gdal.md +22 -6
  10. package/adaptations/geolibre.md +20 -6
  11. package/adaptations/geometry-api-java.md +14 -6
  12. package/adaptations/geometry-api-net.md +17 -6
  13. package/adaptations/geonode.md +17 -6
  14. package/adaptations/geopandas.md +21 -6
  15. package/adaptations/geopipe-agent.md +21 -6
  16. package/adaptations/geos.md +23 -0
  17. package/adaptations/geoserver-cloud.md +17 -6
  18. package/adaptations/geoserver-rest-api.md +17 -6
  19. package/adaptations/geoserver.md +18 -6
  20. package/adaptations/geotools.md +19 -6
  21. package/adaptations/grass-gis.md +24 -6
  22. package/adaptations/jts.md +18 -6
  23. package/adaptations/kepler-gl.md +18 -5
  24. package/adaptations/leaflet.md +25 -6
  25. package/adaptations/mapbox-gl-js.md +23 -6
  26. package/adaptations/maplibre-gl-js.md +20 -0
  27. package/adaptations/maplibre-native.md +19 -0
  28. package/adaptations/mapserver.md +22 -6
  29. package/adaptations/mapsui.md +22 -6
  30. package/adaptations/nettopologysuite.md +19 -6
  31. package/adaptations/opendronemap.md +21 -0
  32. package/adaptations/opengis-all.md +16 -5
  33. package/adaptations/opengis-daf.md +16 -5
  34. package/adaptations/opengis-utils-for-java.md +20 -6
  35. package/adaptations/opengis-utils-for-net.md +23 -6
  36. package/adaptations/openlayers.md +20 -6
  37. package/adaptations/pdal.md +26 -6
  38. package/adaptations/postgis.md +20 -6
  39. package/adaptations/proj.md +20 -6
  40. package/adaptations/projnet4geoapi.md +21 -6
  41. package/adaptations/pyqgis.md +18 -6
  42. package/adaptations/qgis-process.md +21 -6
  43. package/adaptations/qgis-server.md +18 -6
  44. package/adaptations/shapely.md +22 -6
  45. package/adaptations/sharpmap.md +19 -6
  46. package/adaptations/spatialite.md +23 -6
  47. package/adaptations/stac-cog-titiler.md +23 -0
  48. package/adaptations/whitebox-tools.md +19 -6
  49. package/assets/deck-gl/SKILL.md +1 -0
  50. package/assets/duckdb-spatial/SKILL.md +36 -13
  51. package/assets/gdal/SKILL.md +6 -6
  52. package/assets/gdal-api/SKILL.md +2 -2
  53. package/assets/geolibre/SKILL.md +1 -0
  54. package/assets/geonode/SKILL.md +3 -3
  55. package/assets/geopandas/SKILL.md +42 -8
  56. package/assets/geopandas/reference/core-api.md +51 -0
  57. package/assets/geos/SKILL.md +372 -0
  58. package/assets/geoserver/SKILL.md +1 -1
  59. package/assets/geoserver-cloud/SKILL.md +0 -2
  60. package/assets/grass-gis/SKILL.md +31 -7
  61. package/assets/kepler-gl/SKILL.md +1 -0
  62. package/assets/leaflet/SKILL.md +2 -2
  63. package/assets/mapbox-gl-js/SKILL.md +1 -0
  64. package/assets/maplibre-gl-js/SKILL.md +478 -0
  65. package/assets/maplibre-native/SKILL.md +383 -0
  66. package/assets/mapserver/SKILL.md +7 -5
  67. package/assets/mapsui/SKILL.md +4 -2
  68. package/assets/opendronemap/SKILL.md +309 -0
  69. package/assets/opengis-all/SKILL.md +1 -0
  70. package/assets/pdal/SKILL.md +9 -1
  71. package/assets/projnet4geoapi/SKILL.md +1 -1
  72. package/assets/shapely/SKILL.md +24 -4
  73. package/assets/shapely/reference/operations-reference.md +30 -0
  74. package/assets/spatialite/SKILL.md +8 -2
  75. package/assets/stac-cog-titiler/SKILL.md +420 -0
  76. package/assets/whitebox-tools/SKILL.md +20 -4
  77. package/lib/adaptations.d.ts +22 -1
  78. package/lib/adaptations.js +166 -20
  79. package/lib/index.d.ts +13 -9
  80. package/lib/index.js +58 -12
  81. package/lib/taxonomy.d.ts +41 -0
  82. package/lib/taxonomy.js +332 -0
  83. package/locale/en.json +1 -1
  84. package/locale/zh.json +1 -1
  85. package/package.json +10 -4
  86. package/upstream.json +36 -26
@@ -1,8 +1,22 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;正文按 DuckDB 2.0.0 + spatial 扩展编写,函数签名查「核心 API」各表,读文件参数查「ST_Read 常用参数」表,「常见问题」里的报错原文可直接当定位线索。与 GeoPandas 互转用 `skill` 加载 `geopandas`,落盘格式与投影细节用 `skill` 加载 `gdal` 和 `proj`,不要在技能之间 `read` 兄弟目录。
4
- - **执行环境**:`pip install duckdb==2.0.0` 或官方 CLI 走 `ops_bash`;扩展装到用户目录 `~/.duckdb/extensions/<version>/<platform>/`(Windows 上是 `%USERPROFILE%` 下的同名目录),离线环境整目录拷过来即可。大批量 `ST_Read` 加空间 join(正文明确 GDAL 单线程、DuckDB 无 R-Tree)用后台作业跑,`job_output` 收进度,跑偏了 `job_kill`;写 SQL 前先 `todo_write` 列出「验扩展 → 落表 → 投影 → 叠加 → 回读」。
5
- - **先探测版本**:`SELECT duckdb_version()` 拿库版本;正文按 2.0.0 编写,`ST_Area_Spheroid`、`ST_CoverageUnion_Agg` 属较新函数,低版本没有,写例子前先用 `SELECT function_name FROM duckdb_functions() WHERE function_name LIKE 'ST_%'` 探测实际可用集合。`duckdb_extensions()` 里 spatial 的 `loaded` 必须为 true 才算就绪,`extension_version` 随 DuckDB 版本自动匹配、没有独立版本号,报版本对不上时先核对 DuckDB 本身。
6
- - **验证产物**:写完 Parquet 立刻回读,先按 `SELECT count(*), ST_GeometryType(geometry), ST_IsValid(geometry) ...` 分组看类型与无效几何分布,再看 `ST_XMin`、`ST_YMax` 是否落在预期 CRS 的合理范围;MVT 用 `ST_AsMVTGeom` 裁剪后检查空几何比例,别把全空的瓦片当成功。`ST_AsWKB` 只写几何、不写 CRS,输出给下游前要确认投影已记录,命名带步骤前缀,失败时能按步回滚。
7
- - **风险与权限**:`COPY ... TO`、`CREATE OR REPLACE TABLE`、`DROP TABLE` 与 `INSTALL spatial`(联网下载)都可能改盘或改环境,执行前用 `ask_user_question` 确认目标路径与是否可覆盖,优先写新文件名;连生产库或挂载共享目录时不要回显连接串与凭据,也不要在答案里贴完整 DSN。
8
- - **常见失败**:`Extension spatial is not installed` 是只 `LOAD` 没 `INSTALL`,或离线环境拉不到扩展;`Catalog Error: Scalar Function with name ST_Intersects does not exist` 是新连接忘了 `LOAD spatial`,每个连接都要重新 LOAD;`ST_Area` 返回 0 或极小数是经纬度单位“平方度”,改 `ST_Area_Spheroid` 或先 `ST_Transform`;空间 join 极慢就先用 `ST_Intersects_Extent` 粗筛。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 正文按 DuckDB 2.0.0 编写,函数签名查「核心 API」,报错对照查「常见问题」,端到端流程看「典型工作流」。与 GeoPandas 互转用 `skill` 加载 `geopandas`,落盘格式与投影用 `skill` 加载 `gdal`、`proj`
5
+ - 不要在技能之间 `read` 兄弟目录,正文里的相对链接只作目录提示。
6
+ - **执行环境**:`pip install duckdb==2.0.0` 或官方 CLI 走 `ops_bash`
7
+ - 扩展装在 `~/.duckdb/extensions/<version>/<platform>/`(Windows 是 `%USERPROFILE%` 下的同名目录),离线环境整目录拷入即可。
8
+ - 正文的 `INSTALL AND LOAD spatial;` 是 2.0 起的一条语句,旧版拆两步。
9
+ - 大批量 `ST_Read` 与空间 join(GDAL 单线程、索引未必被选中)用后台作业,`job_output` 看进度、`job_kill` 收尾
10
+ - 动手前 `todo_write` 列出「验扩展 → 落表 → 投影 → 叠加 → 回读」。
11
+ - **先探测版本**:`SELECT duckdb_version(), duckdb_proj_version();` 拿库与 PROJ 版本
12
+ - 正文按 2.0.0 编写,`ST_Area_Spheroid`、`ST_CoverageUnion_Agg` 属较新函数。再跑 `SELECT extension_name, loaded FROM duckdb_extensions() WHERE extension_name='spatial';`,loaded 为 true 才算就绪
13
+ - 扩展没有独立版本号,随 DuckDB 版本匹配,报不匹配时先核对 DuckDB 本身。CRS 相关报错另查 `SELECT * FROM duckdb_coordinate_systems();`。
14
+ - **验证产物**:先分清新连接有没有 LOAD:内置的只有 `ST_GeomFromWKB`、`ST_AsWKB`、`ST_AsWKT`/`ST_AsText`、`ST_Intersects_Extent`(`&&`)、`ST_CRS`、`ST_SetCRS`,其余 `ST_*` 报 "does not exist" 是扩展没加载而不是 SQL 语法错。
15
+ - 写完 Parquet 立刻回读 `SELECT count(*), ST_GeometryType(geometry), ST_IsValid(geometry) ...` 看类型与无效几何分布,再用 `ST_Extent_Agg(geom)` 或 `ST_Transform` 后的包围盒核对坐标范围是否落在预期 CRS 内
16
+ - MVT 检查 `ST_AsMVTGeom` 裁剪后的空几何比例,别把全空瓦片当成功。
17
+ - **风险与权限**:`COPY ... TO`、`CREATE OR REPLACE TABLE`、`DROP TABLE` 会覆盖文件或表,`INSTALL spatial` 会联网下载
18
+ - 执行前用 `ask_user_question` 确认目标路径与是否允许覆盖,优先写新文件名。CRS 是类型的一部分(`GEOMETRY('EPSG:4326')` 与无 CRS 的 GEOMETRY 是不同类型),跨 CRS 二元运算先 `ST_Transform`,没有 PostGIS 的 `ST_SRID` 可依赖,别按 PostGIS 习惯写。连生产库时不要回显连接串与凭据。
19
+ - **常见失败**:`Extension spatial is not installed` 是只 LOAD 没 INSTALL 或离线拉不到扩展
20
+ - `Unknown coordinate system` 是 CRS 标识未注册(EPSG 全集要 LOAD spatial 后才注册),必要时 `SET ignore_unknown_crs = true`
21
+ - 带 CRS 的列在旧库文件上报 `storage versions prior v1.5.0`,用 `ATTACH ... (STORAGE_VERSION 'v1.5.0')` 重建或 EXPORT/IMPORT 迁移
22
+ - `ST_Area` 返回极小值是经纬度下按平方度算,改 `ST_Area_Spheroid` 或先投影。
@@ -1,8 +1,26 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文给跨语言类对照表、坐标变换四语言示例、典型工作流与排错表;栅格读取/创建/Translate/Warp/VRT/COG 的完整 API 看 `reference/raster-api.md`,矢量读写、空间过滤、几何操作与 GeoPackage 看 `reference/vector-api.md`。先用 `grep` 搜类名或函数名(如 `GDALRasterBand`、`VectorTranslate`)定位小节,再 `read` 带 `offset`/`limit` 取用,不要整份读。纯命令行替代方案用 `skill` 加载 `gdal`,Python 矢量分析加载 `geopandas`。
4
- - **执行环境**:Python 绑定走 `ops_bash`(Windows 是 MSYS bash,解释器要选装了绑定的那个,conda-forge 的 `conda install -c conda-forge gdal` 最省心);C++ 用 `gdal-config --cflags --libs` 或 CMake `find_package(GDAL REQUIRED)`,编译与链接都在 `ops_bash`;Java 的 `gdalalljni` 定位、`dotnet add package MaxRev.Gdal.Core`、`mvn -v` 这类需要 Windows 原生工具链的走 `pwsh`。正文的 `apt-get install libgdal-dev` 在 Windows 不可用,改用 conda 或 OSGeo4W。大栅格分块处理与批量转换用后台作业,`job_output` 收日志、`job_kill` 收尾。
5
- - **先探测版本**:正文按 GDAL 3.13.3 编写,Java 绑定在 Maven Central 是 3.13.0,NuGet 上 `MaxRev.Gdal.Core` 对应 `3.13.3.611` 且运行时包主版本必须一致。先跑 `python -c "from osgeo import gdal; print(gdal.VersionInfo())"`(返回 `3130300` 这类数字)与 `ogrinfo --version` 确认版本;低版本缺新驱动与部分 SWIG 方法(如 `gdal.VectorTranslate` 的某些参数),C# 侧运行时包与核心包不匹配会直接报本地库加载失败。
6
- - **验证产物**:写完必须重开核对——栅格 `python -c "from osgeo import gdal; ds=gdal.Open('out.tif'); print(ds.GetDriver().ShortName, ds.RasterCount, ds.GetSpatialRef().GetAuthorityCode(None))"` 查驱动、波段数、EPSG;矢量 `ogrinfo -so -al out.gpkg` 查图层名、要素数、字段与 CRS。Python 脚本开头一律 `gdal.UseExceptions()`,否则错误被静默吞掉、写出半成品也算「成功」。资源释放后才算落盘:Python `ds = None`、C++ `GDALClose()`、Java `.delete()`、C# `.Dispose()`;重投影结果用 `read_image` 看一眼是否全黑或错位,成品用 `present` 交付。
7
- - **风险与权限**:以更新模式(`gdal.GA_Update`、`GDALOpen(..., GA_Update)`)打开会直接改原文件,`gdal.Translate`/`gdal.Warp` 输出到已有路径是覆盖;动手前先备份或换输出名,并用 `ask_user_question` 给「换名输出 / 覆盖 / 先备份」选项。装 `libgdal-dev`、加 NuGet/Maven 依赖、写系统目录前先征得同意;连接云存储或数据库的凭据不要写进代码与日志。
8
- - **常见失败**:「驱动未注册」先 `GDALAllRegister()`/`gdal.AllRegister()`,矢量还要 `OGRRegisterAll()`;经纬度顺序颠倒不是数据错——GDAL 3+ 默认纬度在前,需要经度在前时用 `SetAxisMappingStrategy(OAMS_TRADITIONAL_GIS_ORDER)`;多线程崩溃是全局状态非线程安全,每线程用独立 `GDALDataset`;大栅格内存溢出改用 `RasterIO` 窗口分块;报错说不清时 Python 看 `gdal.GetLastErrorMsg()`、C++ 看 `CPLGetLastErrorMsg()`;Java `UnsatisfiedLinkError` 查 `java.library.path` 里的 `gdalalljni`。
3
+ - **加载与引用**:正文给跨语言类对照表、坐标变换四语言示例、典型工作流与排错表
4
+ - 栅格读取/创建/Translate/Warp/VRT/COG 的完整 API 看 `reference/raster-api.md`,矢量读写、空间过滤、几何操作与 GeoPackage 看 `reference/vector-api.md`。
5
+ - 先用 `grep` 搜类名或函数名(如 `GDALRasterBand`、`VectorTranslate`)定位小节,再 `read` 带 `offset`/`limit` 取用,不要整份读。
6
+ - 纯命令行替代方案用 `skill` 加载 `gdal`,Python 矢量分析加载 `geopandas`
7
+ - **执行环境**:Python 绑定走 `ops_bash`(Windows 是 MSYS bash,解释器要选装了绑定的那个,conda-forge 的 `conda install -c conda-forge gdal` 最省心)
8
+ - C++ 用 `gdal-config --cflags --libs` 或 CMake `find_package(GDAL REQUIRED)`,编译与链接都在 `ops_bash`
9
+ - Java 的 `gdalalljni` 定位、`dotnet add package MaxRev.Gdal.Core`、`mvn -v` 这类需要 Windows 原生工具链的走 `pwsh`。
10
+ - 正文的 `apt-get install libgdal-dev` 在 Windows 不可用,改用 conda 或 OSGeo4W。
11
+ - 大栅格分块处理与批量转换用后台作业,`job_output` 收日志、`job_kill` 收尾
12
+ - **先探测版本**:正文按 GDAL 3.13.3 编写,Java 绑定在 Maven Central 是 3.13.0,NuGet 上 `MaxRev.Gdal.Core` 对应 `3.13.3.611` 且运行时包主版本必须一致。
13
+ - 先跑 `python -c "from osgeo import gdal; print(gdal.VersionInfo())"`(返回 `3130300` 这类数字)与 `ogrinfo --version` 确认版本
14
+ - 低版本缺新驱动与部分 SWIG 方法(如 `gdal.VectorTranslate` 的某些参数),C# 侧运行时包与核心包不匹配会直接报本地库加载失败。
15
+ - **验证产物**:写完必须重开核对——栅格 `python -c "from osgeo import gdal; ds=gdal.Open('out.tif'); print(ds.GetDriver().ShortName, ds.RasterCount, ds.GetSpatialRef().GetAuthorityCode(None))"` 查驱动、波段数、EPSG
16
+ - 矢量 `ogrinfo -so -al out.gpkg` 查图层名、要素数、字段与 CRS。Python 脚本开头一律 `gdal.UseExceptions()`,否则错误被静默吞掉、写出半成品也算「成功」。资源释放后才算落盘:Python `ds = None`、C++ `GDALClose()`、Java `.delete()`、C# `.Dispose()`
17
+ - 重投影结果用 `read_image` 看一眼是否全黑或错位,成品用 `present` 交付。
18
+ - **风险与权限**:以更新模式(`gdal.GA_Update`、`GDALOpen(..., GA_Update)`)打开会直接改原文件,`gdal.Translate`/`gdal.Warp` 输出到已有路径是覆盖
19
+ - 动手前先备份或换输出名,并用 `ask_user_question` 给「换名输出 / 覆盖 / 先备份」选项。装 `libgdal-dev`、加 NuGet/Maven 依赖、写系统目录前先征得同意
20
+ - 连接云存储或数据库的凭据不要写进代码与日志。
21
+ - **常见失败**:「驱动未注册」先 `GDALAllRegister()`/`gdal.AllRegister()`,矢量还要 `OGRRegisterAll()`
22
+ - 经纬度顺序颠倒不是数据错——GDAL 3+ 默认纬度在前,需要经度在前时用 `SetAxisMappingStrategy(OAMS_TRADITIONAL_GIS_ORDER)`
23
+ - 多线程崩溃是全局状态非线程安全,每线程用独立 `GDALDataset`
24
+ - 大栅格内存溢出改用 `RasterIO` 窗口分块
25
+ - 报错说不清时 Python 看 `gdal.GetLastErrorMsg()`、C++ 看 `CPLGetLastErrorMsg()`
26
+ - Java `UnsatisfiedLinkError` 查 `java.library.path` 里的 `gdalalljni`。
@@ -1,8 +1,24 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文按任务分三块——矢量看「矢量数据工具(OGR)」、栅格看「栅格数据工具(GDAL)」、环境变量与格式看对应小节;细节参数读 `reference/vector-tools.md` 的 `ogrinfo`/`ogr2ogr` 两节、`reference/raster-tools.md` 的 `gdal_translate`/`gdalwarp`/`gdal_calc.py` 等小节(先读文件开头的 `## Contents` 再按 `offset` 跳读),格式能力表读 `reference/data-formats.md`。一次格式转换通常只需要 vector 参考,不要三个文件全读。需要坐标转换知识时用 `skill` 加载 `proj`,导入后的发布用 `skill` 加载 `geoserver`。
4
- - **执行环境**:命令走 `ops_bash`。Windows 上 `apt-get`/`sudo` 不可用:本机装了 OSGeo4W 时直接调绝对路径(如 `/c/OSGeo4W/bin/ogr2ogr.exe`)或把 `C:\\OSGeo4W\\bin` 加进 `PATH`,否则用 conda-forge(`conda install -c conda-forge gdal`)或容器 `docker run --rm -v "$PWD:/data" -w /data osgeo/gdal:latest`(容器内写成 `/data/...`,别把宿主 `D:\\...` 路径直接传进去)。批量任务前先 `todo_write` 列出「探测版本 → 转换 → 抽检」,千级文件以上分批跑;整目录镶嵌、多源重投影这类几分钟以上的活放后台作业(`run_in_background`),再用 `job_output` 跟进度、`job_kill` 收尾,别让一次调用卡住会话。
5
- - **先探测版本**:`gdalinfo --version`、`ogrinfo --version` 一次拿到实际版本;正文按 3.13.3 编写,统一 CLI `gdal raster`/`gdal vector` 要 3.11+,`gdal dataset check` 要 3.13+,低版本只有 `gdal_translate`/`gdalwarp` 老命令;`gdal_calc.py`/`gdal_merge.py` 依赖随 GDAL 安装的 Python 脚本,缺 Python 绑定时要改用 `gdal raster calc` 或另装。
6
- - **验证产物**:栅格用 `gdalinfo -json out.tif` 核对驱动、尺寸、CRS、NoData 与 `overviews`,矢量用 `ogrinfo -so -al out.gpkg`(或 `-json`)核对图层名、要素数、几何类型与字段;文件存在不代表写成功,批量任务至少抽检首尾两个输出,再对全部输出跑一次 `ogrinfo -so` 汇总退出码。需要给用户看图(切片、渲染、DEM 地形)时用 `read_image` 真看一眼,成品用 `present` 交付。
7
- - **风险与权限**:`-overwrite`、`-append`、`gdal_edit.py`、`gdal_rasterize` 写已有目标路径都是就地改写,先备份或换输出名;`/vsis3/`、`/vsigs/` 需要真实云凭据;安装 GDAL、改 `GDAL_DATA`/`PROJ_LIB`、覆盖已有数据之前先向用户确认——用 `ask_user_question` 给出「换名输出/覆盖/先备份」三个选项,别自己决定。
8
- - **常见失败**:`ERROR 4: … not recognized as a supported file format` 先查路径、扩展名与 `gdalinfo --formats`;驱动或投影异常时开 `CPL_DEBUG=ON` 把输出重定向到 `run.log`,再 `grep -n "^ERROR" run.log | head` 定位第一条真实错误。多步流水线里中间产物命名带步骤前缀,失败时按步骤回滚,不要在半成品上继续叠加。
3
+ - **加载与引用**:正文按任务分三块——矢量看「矢量数据工具(OGR)」、栅格看「栅格数据工具(GDAL)」、环境变量与格式看对应小节
4
+ - 细节参数读 `reference/vector-tools.md` 的 `ogrinfo`/`ogr2ogr` 两节、`reference/raster-tools.md` 的 `gdal_translate`/`gdalwarp`/`gdal_calc.py` 等小节(先读文件开头的 `## Contents` 再按 `offset` 跳读),格式能力表读 `reference/data-formats.md`。
5
+ - 一次格式转换通常只需要 vector 参考,不要三个文件全读。
6
+ - 需要坐标转换知识时用 `skill` 加载 `proj`,导入后的发布用 `skill` 加载 `geoserver`
7
+ - **执行环境**:命令走 `ops_bash`。
8
+ - Windows 上 `apt-get`/`sudo` 不可用:本机装了 OSGeo4W 时直接调绝对路径(如 `/c/OSGeo4W/bin/ogr2ogr.exe`)或把 `C:\\OSGeo4W\\bin` 加进 `PATH`,否则用 conda-forge(`conda install -c conda-forge gdal`)或容器 `docker run --rm -v "$PWD:/data" -w /data osgeo/gdal:latest`(容器内写成 `/data/...`,别把宿主 `D:\\...` 路径直接传进去)。
9
+ - 批量任务前先 `todo_write` 列出「探测版本 → 转换 → 抽检」,千级文件以上分批跑
10
+ - 整目录镶嵌、多源重投影这类几分钟以上的活放后台作业(`run_in_background`),再用 `job_output` 跟进度、`job_kill` 收尾,别让一次调用卡住会话。
11
+ - **先探测版本**:`gdalinfo --version`、`ogrinfo --version` 一次拿到实际版本
12
+ - 正文按 3.13.3 编写,统一 CLI `gdal raster`/`gdal vector` 要 3.11+,`gdal dataset check` 要 3.13+,低版本只有 `gdal_translate`/`gdalwarp` 老命令
13
+ - 3.11+ 的位置参数是「输入 … 输出」,覆盖已有目标要显式 `--overwrite`(如 `gdal vector reproject --output-crs EPSG:3857 in.shp out.gpkg --overwrite`),没有旧式 `-o out`,先 `gdal <cmd> --help` 看 usage 再抄
14
+ - `gdal_calc.py`/`gdal_merge.py` 依赖随 GDAL 安装的 Python 脚本,缺 Python 绑定时要改用 `gdal raster calc` 或另装。
15
+ - **验证产物**:栅格用 `gdalinfo -json out.tif` 核对驱动、尺寸、CRS、NoData 与 `overviews`,矢量用 `ogrinfo -so -al out.gpkg`(或 `-json`)核对图层名、要素数、几何类型与字段
16
+ - 文件存在不代表写成功,批量任务至少抽检首尾两个输出,再对全部输出跑一次 `ogrinfo -so` 汇总退出码
17
+ - 3.13+ 补跑 `gdal dataset check out.gpkg`,退出码 0 才算过,返回 1 表示数据集中有结构错误,`gdalinfo` 能打开不算数。
18
+ - `ogr2ogr -select "id,name"` 之后用 `ogrinfo -so` 核对字段数:几何默认保留,列表里写 `geometry` 只在几何被登记为字段名时才生效,字段少了先查选择列表。
19
+ - 需要给用户看图(切片、渲染、DEM 地形)时用 `read_image` 真看一眼,成品用 `present` 交付
20
+ - **风险与权限**:`--overwrite`/`-overwrite`、`-append`、`gdal_edit.py`、`gdal_rasterize` 写已有目标路径都是就地改写,新统一 CLI 的 `--overwrite` 语义与老命令一样,先备份或换输出名
21
+ - `/vsis3/`、`/vsigs/` 需要真实云凭据
22
+ - 安装 GDAL、改 `GDAL_DATA`/`PROJ_LIB`、覆盖已有数据之前先向用户确认——用 `ask_user_question` 给出「换名输出/覆盖/先备份」三个选项,别自己决定。
23
+ - **常见失败**:`ERROR 4: … not recognized as a supported file format` 先查路径、扩展名与 `gdalinfo --formats`,统一 CLI 把输出路径误当输入时报的也是这条,先 `gdal <cmd> --help` 确认位置参数顺序
24
+ - 驱动或投影异常时开 `CPL_DEBUG=ON` 把输出重定向到 `run.log`,再 `grep -n "^ERROR" run.log | head` 定位第一条真实错误。多步流水线里中间产物命名带步骤前缀,失败时按步骤回滚,不要在半成品上继续叠加。
@@ -1,8 +1,22 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;正文按 GeoLibre 3.7.0 编写,脚本入口读「核心接口 → Python:geolibre.Map」,无头生成读「MCP 服务器」,自托管读「路径四:Docker」与「关键环境变量」表。「常见问题」按症状分条,可当排错入口;SQL 工作区细节用 `skill` 加载 `duckdb-spatial`。
4
- - **执行环境**:`pip install "geolibre[mcp]"` 与 `geolibre-mcp --root ...` 走 `ops_bash`;MCP 是 stdio 常驻进程,让客户端自己 spawn,不要在会话里前台长跑;`docker run` 自托管与 `npm run dev` 属长任务,用后台作业起、`job_output` 收端口与报错、`job_kill` 收尾。Windows 上 MSYS bash 会把 `/data` 当路径改写,挂载写成 `-v "$(pwd -W)/data:/data" -e GEOLIBRE_CONVERSION_ROOTS=/data`,或加 `MSYS_NO_PATHCONV=1`;原生路径与 `$env:` 交给 `pwsh`。
5
- - **先探测版本**:`pip show geolibre` 与 `geolibre-mcp --help`,桌面版看 Help → About;正文按 3.7.0 编写,要求 Python >= 3.11,解释器太旧会直接装不上(别误判成网络问题)。旧教程常对应 3.4/3.5,参数差异以 3.7.0 实测为准;没有 `geolibre` 时先查 `python -c "import sys; print(sys.version)"` 用的是哪个解释器,venv 与系统 Python 混用是常见坑。
6
- - **验证产物**:工程文件先用 `read` 或 `python -c "import json;d=json.load(open('x.geolibre.json'));print(len(d.get('layers',[])),d.get('mapView'))"` 核对图层数与视图,确认 JSON 可解析;再用浏览器打开 `export_html` 的产物,确认底图与图层真的渲染、点要素有弹窗。MCP 返回成功不等于文件可加载,导出 HTML 时还要确认图层引用的是托管 URL,本地路径在别人机器上必然空白;成品 HTML 用 `present` 交付。
7
- - **风险与权限**:`--root` 只给专门放地图的目录,不要给家目录;`GEOLIBRE_CONVERSION_ROOTS` 是 sidecar 的白名单,越界路径会被拒。`export_html`、`save_project` 与 MCP 的覆盖写会改盘,用 `ask_user_question` 确认再写,或先换文件名;`export_html(app_url=...)` 是信任边界,工程内容会 POST 到那个来源,只填用户认可且已列入 `GEOLIBRE_EMBED_ORIGINS` 的地址。只读门户用 `GEOLIBRE_CAPABILITIES=none` 配 `layout=viewer`。
8
- - **常见失败**:`live_` 系列报未连接或超时,先让用户在桌面版打开一次 Processing → Jupyter Notebook 启动中继,超时用 `live_list_layers` 回查而不是重发;自托管转换报路径不允许,是把输出写到了白名单之外;SQL 工作区里 `ST_Intersects` 报函数不存在,先核对引擎与几何列名(DuckDB/PostGIS 是 `geom`,Sedona 是 `geometry`)。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 正文按 GeoLibre 3.7.0 编写,脚本入口读「核心接口 → Python:geolibre.Map」,无头生成读「MCP 服务器」,自托管读「路径四:Docker」与「关键环境变量」表。「常见问题」按症状分条,可当排错入口
5
+ - SQL 工作区细节用 `skill` 加载 `duckdb-spatial`,矢量瓦片渲染与底图样式用 `skill` 加载 `maplibre-gl-js`(GeoLibre 的默认渲染引擎)。
6
+ - **执行环境**:`pip install "geolibre[mcp]"` 与 `geolibre-mcp --root ...` 走 `ops_bash`
7
+ - MCP 是 stdio 常驻进程,让客户端自己 spawn,不要在会话里前台长跑
8
+ - `docker run` 自托管与 `npm run dev` 属长任务,用后台作业起、`job_output` 收端口与报错、`job_kill` 收尾。
9
+ - Windows 上 MSYS bash 会把 `/data` 当路径改写,挂载写成 `-v "$(pwd -W)/data:/data" -e GEOLIBRE_CONVERSION_ROOTS=/data`,或加 `MSYS_NO_PATHCONV=1`
10
+ - 原生路径与 `$env:` 交给 `pwsh`。
11
+ - **先探测版本**:`pip show geolibre` 与 `geolibre-mcp --help`,桌面版看 Help → About
12
+ - 正文按 3.7.0 编写,要求 Python >= 3.11,解释器太旧会直接装不上(别误判成网络问题)。旧教程常对应 3.4/3.5,参数差异以 3.7.0 实测为准
13
+ - 没有 `geolibre` 时先查 `python -c "import sys; print(sys.version)"` 用的是哪个解释器,venv 与系统 Python 混用是常见坑。
14
+ - **验证产物**:工程文件先用 `read` 或 `python -c "import json;d=json.load(open('x.geolibre.json'));print(len(d.get('layers',[])),d.get('mapView'))"` 核对图层数与视图,确认 JSON 可解析
15
+ - 再用浏览器打开 `export_html` 的产物,确认底图与图层真的渲染、点要素有弹窗。MCP 返回成功不等于文件可加载,导出 HTML 时还要确认图层引用的是托管 URL,本地路径在别人机器上必然空白
16
+ - 成品 HTML 用 `present` 交付。
17
+ - **风险与权限**:`--root` 只给专门放地图的目录,不要给家目录
18
+ - `GEOLIBRE_CONVERSION_ROOTS` 是 sidecar 的白名单,越界路径会被拒。`export_html`、`save_project` 与 MCP 的覆盖写会改盘,用 `ask_user_question` 确认再写,或先换文件名
19
+ - `export_html(app_url=...)` 是信任边界,工程内容会 POST 到那个来源,只填用户认可且已列入 `GEOLIBRE_EMBED_ORIGINS` 的地址。只读门户用 `GEOLIBRE_CAPABILITIES=none` 配 `layout=viewer`。
20
+ - **常见失败**:`live_` 系列报未连接或超时,先让用户在桌面版打开一次 Processing → Jupyter Notebook 启动中继,超时用 `live_list_layers` 回查而不是重发
21
+ - 自托管转换报路径不允许,是把输出写到了白名单之外
22
+ - SQL 工作区里 `ST_Intersects` 报函数不存在,先核对引擎与几何列名(DuckDB/PostGIS 是 `geom`,Sedona 是 `geometry`)。
@@ -1,8 +1,16 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;正文按 Maven Central 上的 2.2.4 编写,算子与格式转换查「核心 API 一览」「格式转换」两节,「高级用法:Operator 直接调用」是绕开 `GeometryEngine` 缺失能力的正路。需要活跃维护的替代方案时用 `skill` 加载 `jts`,.NET 同名能力用 `skill` 加载 `geometry-api-net`,不要在技能之间 `read` 兄弟目录。
4
- - **执行环境**:`mvn -v`、`java -version`、`mvn dependency:get` 走 `pwsh`(Windows 上 `mvn` 是 `mvn.cmd`,`JAVA_HOME` 与 `mvn` 实际用的 JDK 可能不是同一个);构建输出重定向到 `build.log`,再用 `grep` 找第一条 `ERROR`。示例建在会话工作区的临时 Maven 工程里,`target/` 与 `~/.m2` 属预期写入,不要写进 assets/。
5
- - **先探测版本**:`mvn dependency:get -Dartifact=com.esri.geometry:esri-geometry-api:2.2.4` 直接确认坐标可解析。2.2.4 是 2020-09 发布、至今仍是 Central 最新;上游 2.3.1(2026-10-09)未发布到 Central,不要把 POM 改成 2.3.1 去试。正文里的 `geometryFromWkt`、`geodesicDistanceOnWGS84` 在 2.2.4 已存在,版本差异主要在算子可见性:`GeometryEngine` 始终没有 `intersects` 与 WKB 方法。
6
- - **验证产物**:写最小 main 断言三件事——`geometryFromWkt` 到 `geometryToWkt` 往返等价、`GeometryEngine.buffer(poly, sr, 2.0).getEnvelope()` 相对原面外扩、`geometryToGeoJson` 能被 `geoJsonToGeometry` 重新读入;再用 `mvn -q -DskipTests package` 证明能编译。编译通过不代表几何正确,把断言结果打到 stdout 并 `grep` 其值;需要给用户看的结果文件用 `present` 交付。
7
- - **风险与权限**:`mvn` 首次会拉依赖,无网或私服缺包报 `Could not resolve dependencies`,不要改 `settings.xml`、加未知仓库或降版本绕过,先用 `ask_user_question` 问用户可用的镜像。`mvn install`/`deploy`、写共享 `settings.xml` 前先确认。参与运算的几何必须带同一 `SpatialReference`;`Operator` 实例非线程安全,批量时每线程持有自己的算子。
8
- - **常见失败**:报 `Unsupported class file major version` 时按 `mvn -v` 显示的 JDK 判断 `JAVA_HOME` 是否指错;找不到 WKB、`intersects`、`generalize` 是去调了 `GeometryEngine`,改用 `OperatorImportFromWkb`、`OperatorIntersects`、`OperatorGeneralize`;面积与长度用 `calculateArea2D()`/`calculateLength2D()`,不要找 `getArea()`。导入几何拓扑无效时先 `simplify()` 再参与运算。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 正文按 Maven Central 上的 2.2.4 编写,算子与格式转换查「核心 API 一览」「格式转换」两节,「高级用法:Operator 直接调用」是绕开 `GeometryEngine` 缺失能力的正路。需要活跃维护的替代方案时用 `skill` 加载 `jts`,.NET 同名能力用 `skill` 加载 `geometry-api-net`,不要在技能之间 `read` 兄弟目录。
5
+ - **执行环境**:`mvn -v`、`java -version`、`mvn dependency:get` 走 `pwsh`(Windows 上 `mvn` 是 `mvn.cmd`,`JAVA_HOME` 与 `mvn` 实际用的 JDK 可能不是同一个)
6
+ - 构建输出重定向到 `build.log`,再用 `grep` 找第一条 `ERROR`。示例建在会话工作区的临时 Maven 工程里,`target/` 与 `~/.m2` 属预期写入,不要写进 assets/。
7
+ - **先探测版本**:`mvn dependency:get -Dartifact=com.esri.geometry:esri-geometry-api:2.2.4` 直接确认坐标可解析。2.2.4 是 2020-09 发布、至今仍是 Central 最新
8
+ - 上游 2.3.1(2026-10-09)未发布到 Central,不要把 POM 改成 2.3.1 去试。正文里的 `geometryFromWkt`、`geodesicDistanceOnWGS84` 在 2.2.4 已存在,版本差异主要在算子可见性:`GeometryEngine` 始终没有 `intersects` 与 WKB 方法。
9
+ - **验证产物**:写最小 main 断言三件事——`geometryFromWkt` 到 `geometryToWkt` 往返等价、`GeometryEngine.buffer(poly, sr, 2.0).getEnvelope()` 相对原面外扩、`geometryToGeoJson` 能被 `geoJsonToGeometry` 重新读入
10
+ - 再用 `mvn -q -DskipTests package` 证明能编译。编译通过不代表几何正确,把断言结果打到 stdout 并 `grep` 其值
11
+ - 需要给用户看的结果文件用 `present` 交付。
12
+ - **风险与权限**:`mvn` 首次会拉依赖,无网或私服缺包报 `Could not resolve dependencies`,不要改 `settings.xml`、加未知仓库或降版本绕过,先用 `ask_user_question` 问用户可用的镜像。`mvn install`/`deploy`、写共享 `settings.xml` 前先确认。参与运算的几何必须带同一 `SpatialReference`
13
+ - `Operator` 实例非线程安全,批量时每线程持有自己的算子。
14
+ - **常见失败**:报 `Unsupported class file major version` 时按 `mvn -v` 显示的 JDK 判断 `JAVA_HOME` 是否指错
15
+ - 找不到 WKB、`intersects`、`generalize` 是去调了 `GeometryEngine`,改用 `OperatorImportFromWkb`、`OperatorIntersects`、`OperatorGeneralize`
16
+ - 面积与长度用 `calculateArea2D()`/`calculateLength2D()`,不要找 `getArea()`。导入几何拓扑无效时先 `simplify()` 再参与运算。
@@ -1,8 +1,19 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文按 NuGet `OpenGIS.Esri.Geometry.Core` 1.0.9 编写,主文件给高频用法;几何类型体系与 `GeometryEngine`/`Operator` 两种风格的完整说明在 `reference/geometry-types.md`,先 `read` 其开头的 `## Contents`,再用 `offset`/`limit` 分段或 `grep` 搜 `GeometryType`、`Operator`,不要整文件硬读。需要几何修复时用 `skill` 加载 `nettopologysuite`,本库没有 `MakeValid`。
4
- - **执行环境**:`dotnet --version`、`dotnet add package`、`dotnet build/test/run` 走 `pwsh`(Windows 下 `dotnet` 是 .cmd,首次 restore 需访问 NuGet)。`dotnet new console -o demo` 建最小工程放会话工作区,`bin/`、`obj/` 不要提交;示例工程与生成数据都别写进 assets/。
5
- - **先探测版本**:`dotnet list package` 与 `dotnet --version` 一起看。正文按 1.0.9(2026-09-21)编写,库目标 `netstandard2.0`,可被 net6/net8/net9/net10 引用;包名与命名空间已从 Esri 版改为 `OpenGIS.Esri.Geometry.*`,原 `Esri/geometry-api-net` 仓库已 404,网上旧代码的 `Esri.ArcGIS.Geometry` 与本库无关。还原报 `NU1101` 说明源或版本不可用,报告依赖不可下载,不要自己编版本号。
6
- - **验证产物**:最小控制台断言四件事——`GeometryEngine.GeometryFromWkt` 到 `GeometryToWkt` 往返、`Contains(polygon, point)` 为 true、`Buffer(new Point(10,20), 5.0).GetEnvelope()` 得 (XMin=5, YMin=15, XMax=15, YMax=25)、`GeometryToGeoJson` 再 `GeometryFromGeoJson` 后 `Equals` 为 true。`dotnet build` 成功只证明能编译;面积不要断言严格等于 25,正文实测约 `24.999998`(默认容差 1e-10)。跑完把控制台输出重定向到文件,用 `grep` 核对每个断言行。
7
- - **风险与权限**:`dotnet restore` 需访问 NuGet,离线先确认本地缓存;改全局 `NuGet.config`、装 SDK、写系统目录前用 `ask_user_question` 征求同意,输出里不要回显私有源凭据。`Polygon.AddRing` 必须首尾闭合,否则面积与包含判断异常;集合运算返回 `Geometry` 基类,转型后再取具体成员;`Simplify` 的 tolerance 必须为正,传 `0.0` 会抛 `ArgumentException: Tolerance must be positive`。
8
- - **常见失败**:`GeodesicDistance` 结果离谱是拿投影坐标(米制)去算,该 API 基于 WGS84,输入必须是经纬度;无法 new 算子实例是因为所有 Operator 都走 `Instance` 懒单例;改 `GetRing()` 或 `GetPath()` 返回值报错是只读视图,需要复制后再改。
3
+ - **加载与引用**:正文按 NuGet `OpenGIS.Esri.Geometry.Core` 1.0.9 编写,主文件给高频用法
4
+ - 几何类型体系与 `GeometryEngine`/`Operator` 两种风格的完整说明在 `reference/geometry-types.md`,先 `read` 其开头的 `## Contents`,再用 `offset`/`limit` 分段或 `grep` 搜 `GeometryType`、`Operator`,不要整文件硬读。
5
+ - 需要几何修复时用 `skill` 加载 `nettopologysuite`,本库没有 `MakeValid`
6
+ - **执行环境**:`dotnet --version`、`dotnet add package`、`dotnet build/test/run` 走 `pwsh`(Windows 下 `dotnet` 是 .cmd,首次 restore 需访问 NuGet)。`dotnet new console -o demo` 建最小工程放会话工作区,`bin/`、`obj/` 不要提交
7
+ - 示例工程与生成数据都别写进 assets/。
8
+ - **先探测版本**:`dotnet list package` 与 `dotnet --version` 一起看。正文按 1.0.9(2026-09-21)编写,库目标 `netstandard2.0`,可被 net6/net8/net9/net10 引用
9
+ - 包名与命名空间已从 Esri 版改为 `OpenGIS.Esri.Geometry.*`,原 `Esri/geometry-api-net` 仓库已 404,网上旧代码的 `Esri.ArcGIS.Geometry` 与本库无关。还原报 `NU1101` 说明源或版本不可用,报告依赖不可下载,不要自己编版本号。
10
+ - **验证产物**:最小控制台断言四件事——`GeometryEngine.GeometryFromWkt` 到 `GeometryToWkt` 往返、`Contains(polygon, point)` 为 true、`Buffer(new Point(10,20), 5.0).GetEnvelope()` 得 (XMin=5, YMin=15, XMax=15, YMax=25)、`GeometryToGeoJson` 再 `GeometryFromGeoJson` 后 `Equals` 为 true。
11
+ - `dotnet build` 成功只证明能编译
12
+ - 面积不要断言严格等于 25,正文实测约 `24.999998`(默认容差 1e-10)。跑完把控制台输出重定向到文件,用 `grep` 核对每个断言行。
13
+ - **风险与权限**:`dotnet restore` 需访问 NuGet,离线先确认本地缓存
14
+ - 改全局 `NuGet.config`、装 SDK、写系统目录前用 `ask_user_question` 征求同意,输出里不要回显私有源凭据。`Polygon.AddRing` 必须首尾闭合,否则面积与包含判断异常
15
+ - 集合运算返回 `Geometry` 基类,转型后再取具体成员
16
+ - `Simplify` 的 tolerance 必须为正,传 `0.0` 会抛 `ArgumentException: Tolerance must be positive`。
17
+ - **常见失败**:`GeodesicDistance` 结果离谱是拿投影坐标(米制)去算,该 API 基于 WGS84,输入必须是经纬度
18
+ - 无法 new 算子实例是因为所有 Operator 都走 `Instance` 懒单例
19
+ - 改 `GetRing()` 或 `GetPath()` 返回值报错是只读视图,需要复制后再改。
@@ -1,8 +1,19 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;正文按 GeoNode 5.1.1 编写,部署读「环境准备 → Docker Compose」,接口读「核心 API」的认证、检索、上传三张表,「典型工作流」给的是上传到取 OGC 地址的完整序列。GeoServer 侧细节用 `skill` 加载 `geoserver`,元数据库用 `skill` 加载 `postgis`,不要在技能之间 `read` 兄弟目录。
4
- - **执行环境**:`docker compose`、`python create-envfile.py`、`curl` 走 `ops_bash`;Windows 下 Docker Desktop 的路径改写会弄坏 `-v "$PWD/x:/x"`,改用 `-v "$(pwd -W)/x:/x"` 或加 `MSYS_NO_PATHCONV=1`。`docker compose up -d` 与 `logs -f django` 是长任务:启动放后台作业,`job_output` 读到 `Executing UWSGI server uwsgi --ini /usr/src/app/uwsgi.ini` 这一行再往下走,不要用固定 sleep 猜就绪。
5
- - **先探测版本**:`curl -s http://localhost/version.txt` 确认 5.1.1,`docker compose ps` 看 django、celery、redis、postgis 是否都在跑;正文按 5.1.1 编写,基于 Django 5.2.18、Celery 5.6.3,源码分支要对应 `5.1.x`。GeoNode 版本与数据库迁移绑定,升级后报 `AttributeError` 或表不存在,先 `docker compose exec django python manage.py migrate`,不要回退代码。
6
- - **验证产物**:上传返回 201 不构成发布成功。依次核对:`logs -f django` 无 Traceback;`GET /api/v2/resources?search=...` 能查到资源且 `subtype` 正确;`resource.alternate` 与 `links[]` 里的 `OGC:WMS` 地址齐全;最后对该 WMS 发一次 `GetMap`,要 200 且 `size_download` 大于 0,`GetCapabilities` 里能找到同一 `alternate`。响应与日志先重定向到文件,再用 `grep` 取关键行,别把整个 JSON 打进上下文。
7
- - **风险与权限**:`action=replace` 整体替换数据、删除资源、`manage.py migrate`、恢复 `pg_dump` 都不可逆,执行前用 `ask_user_question` 让用户确认 `resource_pk` 与备份;两个库 `geonode` 与 `geonode_data` 必须同时备份。`create-envfile.py --env_type prod` 会尝试申请 Let's Encrypt 证书,域名不可达会卡住,试跑先用 `dev`。`ADMIN_PASSWORD`、`clientid/clientsecret` 与 Basic 串从 `.env` 读,不要回显到命令输出或报告。
8
- - **常见失败**:`docker compose up` 后 502 是 django 还在迁移或 collectstatic,或启动失败,用 `job_output` 看首个 Traceback;上传 401 是 `Authorization` 头缺失或 base64 拼错(Windows 下用 `pwsh` 的 `[Convert]::ToBase64String` 生成,别拿 MSYS 的 `base64` 猜编码);403 是用户缺 `base.add_resourcebase` 权限;GetMap 空白图先查图层 bbox 与 CRS 是否匹配。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 正文按 GeoNode 5.1.1 编写,部署读「环境准备 → Docker Compose」,接口读「核心 API」的认证、检索、上传三张表,「典型工作流」给的是上传到取 OGC 地址的完整序列。GeoServer 侧细节用 `skill` 加载 `geoserver`,元数据库用 `skill` 加载 `postgis`,不要在技能之间 `read` 兄弟目录。
5
+ - **执行环境**:`docker compose`、`python create-envfile.py`、`curl` 走 `ops_bash`
6
+ - Windows 下 Docker Desktop 的路径改写会弄坏 `-v "$PWD/x:/x"`,改用 `-v "$(pwd -W)/x:/x"` 或加 `MSYS_NO_PATHCONV=1`。
7
+ - `docker compose up -d` 与 `logs -f django` 是长任务:启动放后台作业,`job_output` 读到 `Executing UWSGI server uwsgi --ini /usr/src/app/uwsgi.ini` 这一行再往下走,不要用固定 sleep 猜就绪
8
+ - **先探测版本**:先用正文给的 `docker compose exec django python -c "import geonode; print(geonode.get_version())"` 确认 5.1.1(旧资料的 `curl http://localhost/version.txt` 在 Docker 部署下不可靠,正文已移除),再 `docker compose ps` 看 django、celery、redis、postgis 是否都在跑
9
+ - 正文按 5.1.1 编写,基于 Django 5.2.18、Celery 5.6.3,源码分支要对应 `5.1.x`。GeoNode 版本与数据库迁移绑定,升级后报 `AttributeError` 或表不存在,先 `docker compose exec django python manage.py migrate`,不要回退代码。
10
+ - **验证产物**:上传返回 201 不构成发布成功。依次核对:`logs -f django` 无 Traceback
11
+ - `GET /api/v2/resources?search=...` 能查到资源且 `subtype` 正确
12
+ - `resource.alternate` 与 `links[]` 里的 `OGC:WMS` 地址齐全
13
+ - 最后对该 WMS 发一次 `GetMap`,要 200 且 `size_download` 大于 0,`GetCapabilities` 里能找到同一 `alternate`。响应与日志先重定向到文件,再用 `grep` 取关键行,别把整个 JSON 打进上下文。
14
+ - **风险与权限**:`action=replace` 整体替换数据、删除资源、`manage.py migrate`、恢复 `pg_dump` 都不可逆,执行前用 `ask_user_question` 让用户确认 `resource_pk` 与备份
15
+ - 两个库 `geonode` 与 `geonode_data` 必须同时备份。`create-envfile.py --env_type prod` 会尝试申请 Let's Encrypt 证书,域名不可达会卡住,试跑先用 `dev`。`ADMIN_PASSWORD`、`clientid/clientsecret` 与 Basic 串从 `.env` 读,不要回显到命令输出或报告。
16
+ - **常见失败**:`docker compose up` 后 502 是 django 还在迁移或 collectstatic,或启动失败,用 `job_output` 看首个 Traceback
17
+ - 上传 401 是 `Authorization` 头缺失或 base64 拼错(Windows 下用 `pwsh` 的 `[Convert]::ToBase64String` 生成,别拿 MSYS 的 `base64` 猜编码)
18
+ - 403 是用户缺 `base.add_resourcebase` 权限
19
+ - GetMap 空白图先查图层 bbox 与 CRS 是否匹配。
@@ -1,8 +1,23 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文按 GeoPandas 1.2.0 编写,主文件覆盖 IO、`sjoin`/`overlay`/`clip`、绘图与常见问题;`GeoSeries`/`GeoDataFrame` 的完整签名在 `reference/core-api.md`——先 `read` 开头的 `## Contents` 定位小节,再按 `offset`/`limit` 分段,或用 `grep` 搜 `to_file(`、`buffer(` 之类签名,不要整文件硬读。底层几何用 `skill` 加载 `shapely`,命令行转换用 `skill` 加载 `gdal`。
4
- - **执行环境**:`python`/`pip` 命令走 `ops_bash`,Windows 上用 `pwsh` 设 `$env:` 更稳;先 `python -c "import sys; print(sys.executable, sys.version)"` 确认解释器不是 QGIS/GDAL 自带的那个。装 `geopandas[all]` 属环境改动,先 `ask_user_question` 征得同意;批量读几百个文件或跑大面 `overlay` 时用后台作业,`job_output` 看进度,不要再串行空等。
5
- - **先探测版本**:`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}`),1.2 里 `buffer(resolution=...)` 已弃用改 `quad_segs`。再查后端:`python -c "import pyogrio, pyproj; print(pyogrio.__version__, pyproj.__version__, pyproj.datadir.get_data_dir())"`,PROJ 目录为空正是后面 `CRSError` 的根因。
6
- - **验证产物**:写完立刻重开核对:`gdf = gpd.read_file("out.gpkg", layer="result"); print(gdf.crs, len(gdf), gdf.is_valid.all(), gdf.total_bounds)`,并确认面积与长度是在投影坐标系下算的(经纬度下 `.area` 的单位是平方度)。制图产物落成 PNG 后必须用 `read_image` 看一眼范围、图例与空几何,成品用 `present` 交付;`to_parquet` 输出要回读列名与 CRS 元数据。
7
- - **风险与权限**:`to_file()` 默认整表覆盖、`to_postgis(if_exists="replace")` 会删表重建,执行前用 `ask_user_question` 确认路径与表名;连接串里的密码不要出现在命令、日志或回答里。Shapefile 字段名超 10 字符会被截断且不支持空值与日期时间,要保真就换 `.gpkg` 或 GeoParquet。
8
- - **常见失败**:`ValueError: GeoDataFrame does not support multiple columns using the geometry column name` 是存在重名列,用 `set_geometry()` 或先改名;`sjoin` 无结果先比两个 GDF 的 `.crs`;`to_crs("EPSG:3857")` 抛 `CRSError` 是 PROJ 数据目录缺失,不是坐标写错;`DriverError` 写入失败先查驱动名与文件是否被占用。
3
+ - **加载与引用**:正文按 GeoPandas 1.2.0 编写,主文件覆盖 IO、`sjoin`/`overlay`/`clip`、绘图与常见问题
4
+ - `GeoSeries`/`GeoDataFrame` 的完整签名在 `reference/core-api.md`——先 `read` 开头的 `## Contents` 定位小节,再按 `offset`/`limit` 分段,或用 `grep` 搜 `to_file(`、`buffer(` 之类签名,不要整文件硬读。
5
+ - 底层几何用 `skill` 加载 `shapely`,命令行转换用 `skill` 加载 `gdal`
6
+ - **执行环境**:`python`/`pip` 命令走 `ops_bash`,Windows 上用 `pwsh` 设 `$env:` 更稳
7
+ - 先 `python -c "import sys; print(sys.executable, sys.version)"` 确认解释器不是 QGIS/GDAL 自带的那个。装 `geopandas[all]` 属环境改动,先 `ask_user_question` 征得同意
8
+ - 批量读几百个文件或跑大面 `overlay` 时用后台作业,`job_output` 看进度,不要再串行空等。
9
+ - **先探测版本**:`python -c "import geopandas as gpd; print(gpd.__version__, gpd.options.io_engine)"`
10
+ - 正文按 1.2.0 / Python >= 3.11 编写,低版本缺 `make_grid`、`read_file_info`(均为 1.2 新增)与 `to_parquet(write_covering_bbox=...)`
11
+ - 1.2 里 `buffer(resolution=...)` 已弃用改 `quad_segs`。
12
+ - 再查 pyogrio 后端:`python -c "import pyogrio, pyproj; print(pyogrio.__version__, pyproj.__version__, pyproj.datadir.get_data_dir())"`,`fid_as_index`、`use_arrow`、`bbox` 参数都由 pyogrio 提供,pyogrio 低于 0.8 或 PROJ 目录为空正是 `CRSError` 与 `read_file_info` 不可用的根因
13
+ - **验证产物**:写完立刻重开核对:`gdf = gpd.read_file("out.gpkg", layer="result"); print(gdf.crs, len(gdf), gdf.is_valid.all(), gdf.total_bounds)`,并确认面积与长度是在投影坐标系下算的(经纬度下 `.area` 的单位是平方度)。
14
+ - 只想按矩形范围裁剪时给 `gpd.clip()` 传四元素范围(如 `(minx, miny, maxx, maxy)`)会走更快的 `clip_by_rect()`,比多边形裁剪快但结果不保证拓扑有效,边角情形可能与多边形裁剪略异,交付前用 `is_valid` 复核。
15
+ - `to_parquet` 回读要核对列名、CRS 与 `schema_version`:不传时默认写 1.1.0,显式写 `"2.0.0"` 下游可能读不了
16
+ - `write_covering_bbox=True` 才让后续 `read_parquet(bbox=...)` 真正生效。制图产物落成 PNG 后必须用 `read_image` 看一眼范围、图例与空几何,成品用 `present` 交付。
17
+ - **风险与权限**:`to_file()` 默认整表覆盖、`to_postgis(if_exists="replace")` 会删表重建,执行前用 `ask_user_question` 确认路径与表名
18
+ - 连接串里的密码不要出现在命令、日志或回答里。Shapefile 字段名超 10 字符会被截断且不支持空值与日期时间,要保真就换 `.gpkg` 或 GeoParquet。
19
+ - **常见失败**:`AttributeError: module 'geopandas' has no attribute 'make_grid'` / `read_file_info` 是装到了 1.2 之前的版本,先确认版本再改代码
20
+ - `ValueError: GeoDataFrame does not support multiple columns using the geometry column name` 是存在重名列,用 `set_geometry()` 或先改名
21
+ - `sjoin` 无结果先比两个 GDF 的 `.crs`
22
+ - `to_crs("EPSG:3857")` 抛 `CRSError` 是 PROJ 数据目录缺失,不是坐标写错
23
+ - `DriverError` 写入失败先查驱动名与文件是否被占用。
@@ -1,8 +1,23 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文主文件给步骤目录、引用语法、`when`/`on_error` 与能力缺口闭环;细节分散在 `reference/steps-reference.md`(36 个步骤的完整参数)、`reference/pipeline-schema.md`(YAML 全字段)、`reference/workflows.md`(可直接套用的五个 YAML)、`reference/backends.md`(7 种后端可用性)、`reference/self-extension.md`(探测→检索→取得能力→验证→沉淀)、`reference/knowledge.md`。先看主文件的步骤表判断要不要展开,再用 `read` 的 `offset`/`limit` 或 `grep` 取单节,不要一次读完六个文件。
4
- - **执行环境**:`geopipe-agent` 是源码安装的 Python CLI(未上 PyPI),在工作区建独立 venv 后 `pip install -e ".[analysis,network]"`,不要往 QGIS/GDAL 自带解释器里装。命令走 `ops_bash`(Windows 是 MSYS bash,venv 解释器写 `/d/work/venv/Scripts/python.exe`);`pip show geopipe-agent | Select-String Version` 这类 PowerShell 写法与 `$env:` 变量走 `pwsh`。全量 YAML 流水线与大范围栅格处理用后台作业起,`job_output` 收 JSON 报告,`job_kill` 收尾;三步以上先 `todo_write` 列出「建 venv → validate → run → 核对产物」。
5
- - **先探测版本**:正文按 0.1.0 编写,且明确未发布到 PyPI——`pip install geopipe-agent` 会 404,必须先 clone 再 `-e` 安装。先跑 `geopipe-agent --help` 确认装的是源码版,再 `geopipe-agent backends` 看当前环境有哪些后端可用(默认 `native_python`,`qgis_process`/`gdal_cli` 需要对应命令在 PATH),最后 `geopipe-agent list-steps --format json` 拿真实步骤 ID;版本与能力不符时以 `list-steps` 的实际输出为准。
6
- - **验证产物**:`geopipe-agent validate pipeline.yaml` 先过校验,再 `run pipeline.yaml`,不要跳过 validate 直接跑。跑完读 JSON 报告的 `qc_summary` 与各步骤统计(重定向到 `run.json` 再 `read` 分段看),随后重开输出文件核对:`geopipe-agent info output/result.geojson`,装了 GDAL 时用 `ogrinfo -so output/result.geojson 图层名` 确认要素数与 CRS。栅格或热力图产物用 `read_image` 真看一眼;最终成果用 `present` 交付。注意 QC 步骤是「检查即透传」,`output` 就是输入,问题在 `$step.issues`,不看 issues 会误判通过。
7
- - **风险与权限**:`network.geocode`、`http.request`、`curl_api` 会把数据发到外部服务,执行前用 `ask_user_question` 确认是否允许出网,并检查 `user_agent` 与凭据不要写进 YAML 提交;`io.write_vector`/`io.write_raster` 指向已有文件是覆盖,批量改写前先备份或换输出名。建 venv、装包、`pip install -e .` 前也先征得同意;网络请求与流水线日志里不要回显 API key。
8
- - **常见失败**:`validate` 报 `not registered` 不要猜参数,先用 `geopipe-agent resolve "<需求>"` 与 `geopipe-agent knowledge search` 查候选能力,再走直通步骤 `gdal.cli`/`qgis.algorithm`;步骤引用解析失败常见于 ID 含点号或引用了更晚定义的步骤;`when` 引用不存在的属性会按 false **静默跳过**,条件步骤没触发先查引用链;`analysis.*`/`network.*` 报 ImportError 是没装可选依赖,补 `".[analysis,network]"` 后重装;新增 `@step` 后要重新 `pip install -e .` 才会被 `pkgutil` 发现。
3
+ - **加载与引用**:正文主文件给步骤目录、引用语法、`when`/`on_error` 与能力缺口闭环
4
+ - 细节分散在 `reference/steps-reference.md`(36 个步骤的完整参数)、`reference/pipeline-schema.md`(YAML 全字段)、`reference/workflows.md`(可直接套用的五个 YAML)、`reference/backends.md`(7 种后端可用性)、`reference/self-extension.md`(探测→检索→取得能力→验证→沉淀)、`reference/knowledge.md`。
5
+ - 先看主文件的步骤表判断要不要展开,再用 `read` 的 `offset`/`limit` 或 `grep` 取单节,不要一次读完六个文件
6
+ - **执行环境**:`geopipe-agent` 是源码安装的 Python CLI(未上 PyPI),在工作区建独立 venv 后 `pip install -e ".[analysis,network]"`,不要往 QGIS/GDAL 自带解释器里装。命令走 `ops_bash`(Windows 是 MSYS bash,venv 解释器写 `/d/work/venv/Scripts/python.exe`)
7
+ - `pip show geopipe-agent | Select-String Version` 这类 PowerShell 写法与 `$env:` 变量走 `pwsh`。全量 YAML 流水线与大范围栅格处理用后台作业起,`job_output` 收 JSON 报告,`job_kill` 收尾
8
+ - 三步以上先 `todo_write` 列出「建 venv → validate → run → 核对产物」。
9
+ - **先探测版本**:正文按 0.1.0 编写,且明确未发布到 PyPI——`pip install geopipe-agent` 会 404,必须先 clone 再 `-e` 安装。
10
+ - 先跑 `geopipe-agent --help` 确认装的是源码版,再 `geopipe-agent backends` 看当前环境有哪些后端可用(默认 `native_python`,`qgis_process`/`gdal_cli` 需要对应命令在 PATH),最后 `geopipe-agent list-steps --format json` 拿真实步骤 ID
11
+ - 版本与能力不符时以 `list-steps` 的实际输出为准。
12
+ - **验证产物**:`geopipe-agent validate pipeline.yaml` 先过校验,再 `run pipeline.yaml`,不要跳过 validate 直接跑。
13
+ - 跑完读 JSON 报告的 `qc_summary` 与各步骤统计(重定向到 `run.json` 再 `read` 分段看),随后重开输出文件核对:`geopipe-agent info output/result.geojson`,装了 GDAL 时用 `ogrinfo -so output/result.geojson 图层名` 确认要素数与 CRS。
14
+ - 栅格或热力图产物用 `read_image` 真看一眼
15
+ - 最终成果用 `present` 交付。注意 QC 步骤是「检查即透传」,`output` 就是输入,问题在 `$step.issues`,不看 issues 会误判通过。
16
+ - **风险与权限**:`network.geocode`、`http.request`、`curl_api` 会把数据发到外部服务,执行前用 `ask_user_question` 确认是否允许出网,并检查 `user_agent` 与凭据不要写进 YAML 提交
17
+ - `io.write_vector`/`io.write_raster` 指向已有文件是覆盖,批量改写前先备份或换输出名。建 venv、装包、`pip install -e .` 前也先征得同意
18
+ - 网络请求与流水线日志里不要回显 API key。
19
+ - **常见失败**:`validate` 报 `not registered` 不要猜参数,先用 `geopipe-agent resolve "<需求>"` 与 `geopipe-agent knowledge search` 查候选能力,再走直通步骤 `gdal.cli`/`qgis.algorithm`
20
+ - 步骤引用解析失败常见于 ID 含点号或引用了更晚定义的步骤
21
+ - `when` 引用不存在的属性会按 false **静默跳过**,条件步骤没触发先查引用链
22
+ - `analysis.*`/`network.*` 报 ImportError 是没装可选依赖,补 `".[analysis,network]"` 后重装
23
+ - 新增 `@step` 后要重新 `pip install -e .` 才会被 `pkgutil` 发现。
@@ -0,0 +1,23 @@
1
+ ## DeepSeek Harness 使用建议
2
+
3
+ - **加载与引用**:单文件技能,没有 reference 目录,正文的「环境准备」「C API 基础骨架」「核心 API」「典型工作流」「常见问题」按需跳读即可。
4
+ - 要对照 Java 上游实现用 `skill` 加载 `jts`,要在 Python 侧复现同一套几何运算用 `skill` 加载 `shapely`(它内嵌的 GEOS 版本可能与本机不同,跨语言比对前先核对),入库与发布用 `skill` 加载 `postgis`、`gdal`
5
+ - 不要用 `read` 翻兄弟目录的 SKILL.md。
6
+ - **执行环境**:编译与运行走 `ops_bash`(Windows 下是 MSYS bash,工程建在 `/d/work` 这类路径)。
7
+ - 正文的 `apt-get`/`sudo` 在 Windows 不成立:装库走 vcpkg(`vcpkg install geos:x64-windows`)或 conda-forge(`conda install -c conda-forge geos`),装好后确认 `geos_c.dll` 与 exe 同目录或在 `PATH` 里
8
+ - MSVC 工程用 `pwsh` 调 `cl /I <include> demo.c <lib>\geos_c.lib`,不要拿 bash 的 `-lgeos_c` 硬套。
9
+ - 源码构建 `cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$PWD/install" ..` 后 `cmake --build . --parallel`,整套几分钟起,用 `run_in_background` 起作业再 `job_output` 收尾,不要在前台干等
10
+ - 安装前缀先指到会话工作区,别急着写系统目录。
11
+ - **先探测版本**:`geos-config --version` 与 `pkg-config --modversion geos` 两个都跑:前者查二进制、后者查 `.pc` 登记值,两者不一致说明 PATH 里混了多套安装。
12
+ - 再确认编译期头文件版本 `grep -h "GEOS_VERSION " "$(geos-config --prefix)/include/geos/version.h"`,与 `geos-config --version` 对不上就是 include 与 lib 不同源,链接阶段会报符号找不到。
13
+ - 正文按 3.15.0 编写
14
+ - 3.12 起 WKTWriter 默认 trim、3.9 起默认 OverlayNG,按探测到的实际版本决定是否还要显式设置。
15
+ - **验证产物**:别只看程序退出码。用 `write` 落一个最小 C 程序:两块 10x10 面错位 5 相交,`GEOSArea` 应恰为 25 而不是 0
16
+ - 再 `GEOSBuffer` 半径 0.5,面积应略大于 25。`GEOSisValid` 必须为 1,把输出 WKT 重新读回再比一次面积与顶点数
17
+ - Windows 上再 `dumpbin /dependents demo.exe` 确认真的链到 `geos_c.dll`,否则运行期才报找不到模块。要看几何形状就写 WKT 转 PNG 的旁路,用 `read_image` 看一眼,纯白图与空结果等价。
18
+ - **风险与权限**:`make install` 默认写 `/usr/local`、conda/vcpkg 安装会改环境变量与 PATH,执行前用 `ask_user_question` 给出「装到工作区前缀/替换系统库/取消」三个选项。本机若已有 QGIS、PostGIS、GDAL 自带的 `geos_c.dll`,覆盖它会让这些程序一起坏掉,先备份或改用独立前缀
19
+ - 升级 GEOS 后 C++ 侧必须重编(无 ABI 承诺),生产几何回归先在只读副本上跑。
20
+ - **常见失败**:`TopologyException: side location conflict` 先 `GEOSisValid`+`GEOSMakeValid`,别急着加重试
21
+ - `undefined reference to GEOSIntersection` 是 C API 却只链了 `-lgeos`
22
+ - 谓词结果反了是把 char 当布尔(1 真/2 假/0 异常)
23
+ - `free()` 释放 `GEOSWKTWriter_write` 返回的字符串在 Windows 上必崩,改用 `GEOSFree`。
@@ -1,8 +1,19 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;正文按 GeoServer Cloud 3.0.2.1、配套 Helm chart 3.0.3 编写,部署看「环境准备与快速启动(docker-compose)」「Kubernetes(Helm)」,排障看「常见问题」,路径对照「核心 API:网关路由与端点」。数据准备与发布自动化用 `skill` 加载 `gdal`、`postgis`、`geoserver-rest-api`,不要用 `read` 去读兄弟目录的 SKILL.md。
4
- - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。正文的 `wget` 在 Windows 不存在,改用 `curl.exe -LO`(`pwsh` 里用 `Invoke-WebRequest`);`/tmp`、`export`、heredoc 一律换成会话工作区与单行命令。`docker compose pull/up -d` 要拉十几个镜像、启动十个服务,属长任务:用 `ops_bash` 的 `run_in_background`,再用 `job_output` 分段收日志、失败用 `job_kill` 收尾。三步以上(拉取 → 起服务 → 探活 → GetMap)先 `todo_write`。
5
- - **先探测版本**:正文按 3.0.2.1 编写,先跑 `docker compose version`、`docker version`、`kubectl version --client`、`helm version`,再用 `curl.exe -s -u admin:geoserver http://localhost:9090/geoserver/cloud/rest/about/version.json` 确认网关后面的 GeoServer 版本。低版本差异:3.x 起不再发布 `geoservercloud/geoserver-cloud-discovery` 镜像(Docker Hub 已 404),服务发现改用 `hashicorp/consul`;旧资料的 `jdbcconfig` 后端已被 `pgconfig` 取代。同一套部署里所有 `geoserver-cloud-*` 镜像必须同标签,chart 版本(3.0.3)与镜像标签不必一致,升级前先查 chart 默认镜像标签。
6
- - **验证产物**:分层验证——`docker compose ps` 全 Up 只是第一层,再取 `http://localhost:9090/actuator/health` 的 `{"status":"UP"}`、`http://localhost:8500/v1/catalog/services` 里 wms/wfs 已注册、网关 `.../rest/workspaces.json` 返回合法 JSON,最后发一次 WMS `GetMap` 存成 png 并用 `read_image` 真看一眼非空、坐标没错。actuator 被 profile 关掉时改用 `kubectl -n gis get pods` 判活。
7
- - **风险与权限**:`docker compose down -v`、`helm uninstall`、删 PVC、重置 `PGCONFIG_SCHEMA` 都会连数据目录与配置一起丢;扩容到生产、`--scale wms=3` 会改资源占用。执行前用 `ask_user_question` 给「先备份快照 / 只扩容 / 重建并丢数据」三个选项。`admin:geoserver`、`PGCONFIG_PASSWORD` 与 RabbitMQ 口令写进 `.env` 且不得回显到报告或日志。
8
- - **常见失败**:502 先查 Consul 注册与目标服务健康(`kubectl -n gis logs deploy/<wms>` 或 `docker compose logs wms > run.log 2>&1` 后 `grep -n "^ERROR" run.log`);配置改了不同步查 RabbitMQ 可达与 `GEOSERVER_BUS_ENABLED=true`;瓦片 404 查 gwc 是否部署、`GEOSERVER_BASE_PATH` 前缀是否与请求一致(网关先 StripBasePath 再转发)。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 正文按 GeoServer Cloud 3.0.2.1、配套 Helm chart 3.0.3 编写,部署看「环境准备与快速启动(docker-compose)」「Kubernetes(Helm)」,排障看「常见问题」,路径对照「核心 API:网关路由与端点」。
5
+ - 数据准备与发布自动化用 `skill` 加载 `gdal`、`postgis`、`geoserver-rest-api`,不要用 `read` 去读兄弟目录的 SKILL.md
6
+ - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。正文的 `wget` 在 Windows 不存在,改用 `curl.exe -LO`(`pwsh` 里用 `Invoke-WebRequest`)
7
+ - `/tmp`、`export`、heredoc 一律换成会话工作区与单行命令。
8
+ - `docker compose pull/up -d` 要拉十几个镜像、启动十个服务,属长任务:用 `ops_bash` 的 `run_in_background`,再用 `job_output` 分段收日志、失败用 `job_kill` 收尾。
9
+ - 三步以上(拉取 → 起服务 → 探活 → GetMap)先 `todo_write`
10
+ - **先探测版本**:正文按 3.0.2.1 编写,先跑 `docker compose version`、`docker version`、`kubectl version --client`、`helm version`,再用 `curl.exe -s -u admin:geoserver http://localhost:9090/geoserver/cloud/rest/about/version.json` 确认网关后面的 GeoServer 版本。
11
+ - 低版本差异:3.x 起不再发布 `geoservercloud/geoserver-cloud-discovery` 镜像(Docker Hub 已 404),服务发现改用 `hashicorp/consul`
12
+ - 旧资料的 `jdbcconfig` 后端已被 `pgconfig` 取代。同一套部署里所有 `geoserver-cloud-*` 镜像必须同标签,chart 版本(3.0.3)与镜像标签不必一致,升级前先查 chart 默认镜像标签。
13
+ - **验证产物**:分层验证——`docker compose ps` 全 Up 只是第一层,再取 `http://localhost:9090/actuator/health` 的 `{"status":"UP"}`、`http://localhost:8500/v1/catalog/services` 里 wms/wfs 已注册、网关 `.../rest/workspaces.json` 返回合法 JSON,最后发一次 WMS `GetMap` 存成 png 并用 `read_image` 真看一眼非空、坐标没错。
14
+ - actuator 被 profile 关掉时改用 `kubectl -n gis get pods` 判活
15
+ - **风险与权限**:`docker compose down -v`、`helm uninstall`、删 PVC、重置 `PGCONFIG_SCHEMA` 都会连数据目录与配置一起丢
16
+ - 扩容到生产、`--scale wms=3` 会改资源占用。执行前用 `ask_user_question` 给「先备份快照 / 只扩容 / 重建并丢数据」三个选项。`admin:geoserver`、`PGCONFIG_PASSWORD` 与 RabbitMQ 口令写进 `.env` 且不得回显到报告或日志。
17
+ - **常见失败**:502 先查 Consul 注册与目标服务健康(`kubectl -n gis logs deploy/<wms>` 或 `docker compose logs wms > run.log 2>&1` 后 `grep -n "^ERROR" run.log`)
18
+ - 配置改了不同步查 RabbitMQ 可达与 `GEOSERVER_BUS_ENABLED=true`
19
+ - 瓦片 404 查 gwc 是否部署、`GEOSERVER_BASE_PATH` 前缀是否与请求一致(网关先 StripBasePath 再转发)。
@@ -1,8 +1,19 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文按 GeoServer 3.0.2(2026-10-19 安全修复版)编写,端点全表在 `reference/endpoints.md`:先用 `read` 读该文件的 `## Contents` 定位小节,再按 `offset`/`limit` 取用,或 `grep` 搜 `/rest/security`、`coveragestores` 这类关键词,不要整文件硬读。正文的 10 个示例只覆盖高频操作;C# 客户端用法看「C# 客户端」一节,不打算用 .NET 就整段跳过。
4
- - **执行环境**:请求走 `ops_bash`(MSYS bash)里的 `curl.exe`——Windows 上 `curl` 是 PowerShell 别名、参数语义不同,脚本里一律写全名。正文的 `\` 续行在 `pwsh` 里无效,压缩成单行;JSON 请求体现在 bash 单引号里可用,但更稳的是写成 `body.json` 再用 `curl.exe --data-binary "@body.json"`,绕开各 shell 的引号与转义差异。批量发布(建 workspace → 传数据 → 绑样式)三步以上,先 `todo_write` 列步骤。
5
- - **先探测版本**:先 `curl.exe -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json` 拿到实际版本与组件清单,再决定用哪套端点。正文按 3.0.2 编写:本机若是 2.x,`/rest/services/{wms|wfs}/settings` 这类较新的服务设置端点可能不存在;3.x 的安全规则模型与 2.x 教程有差异,端点返回 404/405 时以 `reference/endpoints.md` 与官方 stable 文档为准,不要照抄正文示例。注意 cloud 版前缀是 `/geoserver/cloud/rest`,单体版是 `/geoserver/rest`。
6
- - **验证产物**:写操作后立刻 GET 回读同一资源(`.../rest/workspaces/myws.json`、`.../rest/layers/myws:roads.json`),再用 `curl.exe -o getmap.png -w "%{http_code}"` 发一次 WMS `GetMap`,用 `read_image` 看 png 非空、图例与范围合理;只凭 201 或退出码不算验证。改样式后要清 GWC 缓存(`/gwc/rest/seed/...` 的 truncate 请求),再用同一图层不同 `styles=` 对比出图。只取状态码、把响应体落盘,可避免上万行 XML 灌进上下文。
7
- - **风险与权限**:`?recurse=true` 删 workspace/store、`POST /rest/reset`、`PUT /rest/security/*` 改访问规则、改 admin 密码、清 GWC 缓存都不可逆或会断服务;连生产 GeoServer 前用 `ask_user_question` 给「先备份 / 只在测试实例跑 / 直接执行」选项。凭据用环境变量 `curl -u "$GS_USER:$GS_PASS"`,不写进脚本、不回显到报告;写操作先对测试实例演一遍。
8
- - **常见失败**:GET 200 但 POST/PUT 401 是认证或安全规则问题,不是版本问题;POST 400 且资源没建多半是漏了单层包装 `{"workspace":{...}}` 或 `Content-Type`;上传 Shapefile 失败检查 ZIP 内含 `.shp/.shx/.dbf/.prj` 且 PUT 到 `.../file.shp`;改配置没生效用 `POST /rest/reload`;循环建资源时逐条检查 HTTP 码,一失败即停,半套配置留在服务端比报错更难查。
3
+ - **加载与引用**:正文按 GeoServer 3.0.2(2026-10-19 安全修复版)编写,端点全表在 `reference/endpoints.md`:先用 `read` 读该文件的 `## Contents` 定位小节,再按 `offset`/`limit` 取用,或 `grep` 搜 `/rest/security`、`coveragestores` 这类关键词,不要整文件硬读。
4
+ - 正文的 10 个示例只覆盖高频操作
5
+ - C# 客户端用法看「C# 客户端」一节,不打算用 .NET 就整段跳过。
6
+ - **执行环境**:请求走 `ops_bash`(MSYS bash)里的 `curl.exe`——Windows 上 `curl` 是 PowerShell 别名、参数语义不同,脚本里一律写全名。正文的 `\` 续行在 `pwsh` 里无效,压缩成单行
7
+ - JSON 请求体现在 bash 单引号里可用,但更稳的是写成 `body.json` 再用 `curl.exe --data-binary "@body.json"`,绕开各 shell 的引号与转义差异。批量发布(建 workspace → 传数据 → 绑样式)三步以上,先 `todo_write` 列步骤。
8
+ - **先探测版本**:先 `curl.exe -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json` 拿到实际版本与组件清单,再决定用哪套端点。正文按 3.0.2 编写:本机若是 2.x,`/rest/services/{wms|wfs}/settings` 这类较新的服务设置端点可能不存在
9
+ - 3.x 的安全规则模型与 2.x 教程有差异,端点返回 404/405 时以 `reference/endpoints.md` 与官方 stable 文档为准,不要照抄正文示例。注意 cloud 版前缀是 `/geoserver/cloud/rest`,单体版是 `/geoserver/rest`。
10
+ - **验证产物**:写操作后立刻 GET 回读同一资源(`.../rest/workspaces/myws.json`、`.../rest/layers/myws:roads.json`),再用 `curl.exe -o getmap.png -w "%{http_code}"` 发一次 WMS `GetMap`,用 `read_image` 看 png 非空、图例与范围合理
11
+ - 只凭 201 或退出码不算验证。改样式后要清 GWC 缓存(`/gwc/rest/seed/...` 的 truncate 请求),再用同一图层不同 `styles=` 对比出图。只取状态码、把响应体落盘,可避免上万行 XML 灌进上下文。
12
+ - **风险与权限**:`?recurse=true` 删 workspace/store、`POST /rest/reset`、`PUT /rest/security/*` 改访问规则、改 admin 密码、清 GWC 缓存都不可逆或会断服务
13
+ - 连生产 GeoServer 前用 `ask_user_question` 给「先备份 / 只在测试实例跑 / 直接执行」选项。凭据用环境变量 `curl -u "$GS_USER:$GS_PASS"`,不写进脚本、不回显到报告
14
+ - 写操作先对测试实例演一遍。
15
+ - **常见失败**:GET 200 但 POST/PUT 401 是认证或安全规则问题,不是版本问题
16
+ - POST 400 且资源没建多半是漏了单层包装 `{"workspace":{...}}` 或 `Content-Type`
17
+ - 上传 Shapefile 失败检查 ZIP 内含 `.shp/.shx/.dbf/.prj` 且 PUT 到 `.../file.shp`
18
+ - 改配置没生效用 `POST /rest/reload`
19
+ - 循环建资源时逐条检查 HTTP 码,一失败即停,半套配置留在服务端比报错更难查。
@@ -1,8 +1,20 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;正文按 GeoServer 3.0.2 编写,发布流程看「发布矢量图层(PostGIS)」与「典型工作流」,WMS/WFS/WMTS/MVT 的 URL 模板、SLD 示例、GWC seed 请求都可在正文直接取;「常见问题」按症状分条,先对表再深挖。REST 自动化用 `skill` 加载 `geoserver-rest-api`,数据源侧用 `skill` 加载 `postgis`,不要在技能之间 `read` 兄弟目录。
4
- - **执行环境**:`curl`、`unzip`、`java -version` 走 `ops_bash`,原生 Windows 路径与 `Expand-Archive`、`$env:` 走 `pwsh`。正文的 `sh bin/startup.sh` 在 Windows 不可用,改用 `bin` 下的 `startup.bat`(`pwsh -File .\bin\startup.bat`),或直接用镜像 `docker.osgeo.org/geoserver:3.0.2`;GeoServer 是常驻服务,必须用后台作业起,`job_output` 读到启动完成行再验证,收尾 `job_kill`,不要让 8080 端口一直挂着。发布、改样式、seed 三步以上先 `todo_write`。
5
- - **先探测版本**:`java -version` 必须是 17 或 21,低于 17 启动即报 `UnsupportedClassVersionError`,3.0.x 分发包无法运行;服务起来后 `curl -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json` 核对 GeoServer 3.0.2、GeoTools 35.2、GeoWebCache 2.0.2。升级前先备份数据目录,正文强调 3.0.2 是安全修复版,生产应优先升级。
6
- - **验证产物**:发布图层的判据是「200 + 非空字节 + 画面正确」:用 `curl -s -o out.png -w "%{http_code} %{size_download}"` 请求 `request=GetMap`,再用 `read_image` 看 `out.png` 是不是真画出了要素,空白图与 0 字节一样算失败;再拉 `GetCapabilities` 确认图层已注册。改了 SLD 预览不变,先在 Tile Caching 里 truncate 该图层或给 GetMap 加 `&tiled=false`;REST 建完 workspace/store 用同路径 GET 回读,删除后应得 404。
7
- - **风险与权限**:`admin:geoserver` 默认凭据不要写进脚本、日志或报告,用环境变量传入;删 workspace(`?recurse=true`)、truncate GWC 缓存、改 `-Xmx`、重启容器前用 `ask_user_question` 让用户拍板;seed 大范围瓦片会撑爆磁盘,先小 zoom 单图层试。
8
- - **常见失败**:WMS 返回空白图先查图层 native bounds 与 SRS 是否对不上;Shapefile 中文乱码改 Store 的 `charset`(UTF-8 或 GBK);WFS-T 403 是 Data 规则没给 `w` 权限;忘记管理员密码去数据目录 `security/users.properties` 恢复后重启。日志里的报错用 `grep` 定位第一条真实错误,不要从头逐行读。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 正文按 GeoServer 3.0.2 编写,发布流程看「发布矢量图层(PostGIS)」与「典型工作流」,WMS/WFS/WMTS/MVT 的 URL 模板、SLD 示例、GWC seed 请求都可在正文直接取
5
+ - 「常见问题」按症状分条,先对表再深挖。REST 自动化用 `skill` 加载 `geoserver-rest-api`,数据源侧用 `skill` 加载 `postgis`,不要在技能之间 `read` 兄弟目录。
6
+ - **执行环境**:`curl`、`unzip`、`java -version` 走 `ops_bash`,原生 Windows 路径与 `Expand-Archive`、`$env:` 走 `pwsh`。
7
+ - 正文的 `sh bin/startup.sh` 在 Windows 不可用,改用 `bin` 下的 `startup.bat`(`pwsh -File .\bin\startup.bat`),或直接用镜像 `docker.osgeo.org/geoserver:3.0.2`
8
+ - GeoServer 是常驻服务,必须用后台作业起,`job_output` 读到启动完成行再验证,收尾 `job_kill`,不要让 8080 端口一直挂着。发布、改样式、seed 三步以上先 `todo_write`。
9
+ - **先探测版本**:`java -version` 必须是 17 或 21,低于 17 启动即报 `UnsupportedClassVersionError`,3.0.x 分发包无法运行
10
+ - 服务起来后 `curl -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json` 核对 GeoServer 3.0.2、GeoTools 35.2、GeoWebCache 2.0.2。升级前先备份数据目录,正文强调 3.0.2 是安全修复版,生产应优先升级。
11
+ - **验证产物**:发布图层的判据是「200 + 非空字节 + 画面正确」:用 `curl -s -o out.png -w "%{http_code} %{size_download}"` 请求 `request=GetMap`,再用 `read_image` 看 `out.png` 是不是真画出了要素,空白图与 0 字节一样算失败
12
+ - 再拉 `GetCapabilities` 确认图层已注册。改了 SLD 预览不变,先在 Tile Caching 里 truncate 该图层或给 GetMap 加 `&tiled=false`
13
+ - REST 建完 workspace/store 用同路径 GET 回读,删除后应得 404。
14
+ - **风险与权限**:`admin:geoserver` 默认凭据不要写进脚本、日志或报告,用环境变量传入
15
+ - 删 workspace(`?recurse=true`)、truncate GWC 缓存、改 `-Xmx`、重启容器前用 `ask_user_question` 让用户拍板
16
+ - seed 大范围瓦片会撑爆磁盘,先小 zoom 单图层试。
17
+ - **常见失败**:WMS 返回空白图先查图层 native bounds 与 SRS 是否对不上
18
+ - Shapefile 中文乱码改 Store 的 `charset`(UTF-8 或 GBK)
19
+ - WFS-T 403 是 Data 规则没给 `w` 权限
20
+ - 忘记管理员密码:默认 XML 用户/组服务在数据目录 `security/usergroup/<name>/users.xml`(默认服务名 `default`),改完重启,或 Docker 部署用 `GEOSERVER_ADMIN_PASSWORD` 重置。日志里的报错用 `grep` 定位第一条真实错误,不要从头逐行读。
@@ -1,8 +1,21 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文按 GeoTools 35.2(JDK 17)编写。读文件顺序:先看「环境准备与快速集成」的仓库配置与模块表,再按任务跳「CRS 与坐标转换」「CQL / ECQL」「几何操作」。矢量读写完整示例在 `reference/vector-io.md`、栅格与 StreamingRenderer 出图在 `reference/raster-rendering.md`:先用 `read` 读文件开头的小节清单,再按 `offset`/`limit` 取用,或 `grep` 搜 `FileDataStore`、`StreamingRenderer` 定位,不要整篇读。几何算法细节用 `skill` 加载 `jts`,发布链路用 `skill` 加载 `geoserver`。
4
- - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。正文的 `mvn`/`java` 要先探测:`java -version` 必须是 17(35.x 用 JDK 8/11 编译直接失败),`mvn -v` 不存在时用 Maven wrapper 或官方 zip 解压后把 `bin` 加进 PATH;正文里的 `sudo apt-get install openjdk-17-jdk` 在 Windows 改用 Temurin 官方安装包或 `conda install -c conda-forge openjdk=17`,装不了本机 JDK 就退回 Docker(`docker run --rm -v "$PWD:/w" -w /w maven:3.9-eclipse-temurin-17 mvn ...`)。首次 `mvn` 要下载 OSGeo 仓库里几百 MB 依赖:用 `ops_bash` 的 `run_in_background` 跑,`job_output` 收日志,卡住用 `job_kill` 收尾。
5
- - **先探测版本**:`mvn dependency:tree -Dincludes=org.geotools` 确认真的解析到 35.2 且没被别的依赖压回旧版(GeoTools 不在 Maven Central,仓库里没 `repo.osgeo.org` 就直接失败)。正文按 35.2 编写,对应 JDK 17、JTS 包名 `org.locationtech.jts`;低版本差异:≤33 分支是 JDK 11、34 起才要 17,老教程里的 `com.vividsolutions.jts` 在 20+ 已废弃。JDK 21 是 35.x 的可选支持,别用 8/11 硬跑。`pom.xml` 里 `<geotools.version>` 统一成一个属性,别混版本。
6
- - **验证产物**:`mvn -q -DskipTests package` 只说明编译过,必须再跑一个最小 main:`FileDataStoreFinder` 打开 shapefile → `getFeatures()` 打印 count、schema 与 CRS → `JTS.transform` 重投影后打印首点坐标。写出的 GeoPackage/PNG 用独立命令回读,渲染图用 `read_image` 真看一眼不是空白、图例与范围对。`CRS.decode("EPSG:4326")` 抛异常说明缺 `gt-epsg-hsql`;`getDataStore()` 返回 null 说明对应 SPI 模块没进 classpath。`DataStore`/`SimpleFeatureIterator`/`MapContent` 没 dispose 会导致文件锁与不写盘,验证前先确认进程已退出。
7
- - **风险与权限**:写 PostGIS/Oracle 生产库、`SimpleFeatureStore` 批量覆盖、跳过测试打包上线都不可逆,动手前用 `ask_user_question` 给「只读实例 / 写到新表 / 直接写正式库」三选项;连接串、用户名、密码只放环境变量且不得回显到报告。`mvn clean` 会删本地产物,确认目录再跑。
8
- - **常见失败**:出现 `com.vividsolutions.jts` 是包名没升级;`CRS.decode` 报 `No such authority code` 多半缺 EPSG 模块;文件句柄泄漏或数据未写盘是漏了 `dispose()`/`try-with-resources`;多线程共享 `SimpleFeatureIterator` 会抛异常,每线程各开一个。把 `mvn -X` 日志重定向到 `run.log` 再 `grep -n "BUILD FAILURE" run.log`,不要全文读。
3
+ - **加载与引用**:正文按 GeoTools 35.2(JDK 17)编写。
4
+ - 读文件顺序:先看「环境准备与快速集成」的仓库配置与模块表,再按任务跳「CRS 与坐标转换」「CQL / ECQL」「几何操作」。
5
+ - 矢量读写完整示例在 `reference/vector-io.md`、栅格与 StreamingRenderer 出图在 `reference/raster-rendering.md`:先用 `read` 读文件开头的小节清单,再按 `offset`/`limit` 取用,或 `grep` 搜 `FileDataStore`、`StreamingRenderer` 定位,不要整篇读。
6
+ - 几何算法细节用 `skill` 加载 `jts`,发布链路用 `skill` 加载 `geoserver`
7
+ - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。正文的 `mvn`/`java` 要先探测:`java -version` 必须是 17(35.x 用 JDK 8/11 编译直接失败),`mvn -v` 不存在时用 Maven wrapper 或官方 zip 解压后把 `bin` 加进 PATH
8
+ - 正文里的 `sudo apt-get install openjdk-17-jdk` 在 Windows 改用 Temurin 官方安装包或 `conda install -c conda-forge openjdk=17`,装不了本机 JDK 就退回 Docker(`docker run --rm -v "$PWD:/w" -w /w maven:3.9-eclipse-temurin-17 mvn ...`)。
9
+ - 首次 `mvn` 要下载 OSGeo 仓库里几百 MB 依赖:用 `ops_bash` 的 `run_in_background` 跑,`job_output` 收日志,卡住用 `job_kill` 收尾
10
+ - **先探测版本**:`mvn dependency:tree -Dincludes=org.geotools` 确认真的解析到 35.2 且没被别的依赖压回旧版(GeoTools 不在 Maven Central,仓库里没 `repo.osgeo.org` 就直接失败)。正文按 35.2 编写,对应 JDK 17、JTS 包名 `org.locationtech.jts`
11
+ - 低版本差异:≤33 分支是 JDK 11、34 起才要 17,老教程里的 `com.vividsolutions.jts` 在 20+ 已废弃。JDK 21 是 35.x 的可选支持,别用 8/11 硬跑。`pom.xml` 里 `<geotools.version>` 统一成一个属性,别混版本。
12
+ - **验证产物**:`mvn -q -DskipTests package` 只说明编译过,必须再跑一个最小 main:`FileDataStoreFinder` 打开 shapefile → `getFeatures()` 打印 count、schema 与 CRS → `JTS.transform` 重投影后打印首点坐标。
13
+ - 写出的 GeoPackage/PNG 用独立命令回读,渲染图用 `read_image` 真看一眼不是空白、图例与范围对。
14
+ - `CRS.decode("EPSG:4326")` 抛异常说明缺 `gt-epsg-hsql`
15
+ - `getDataStore()` 返回 null 说明对应 SPI 模块没进 classpath。`DataStore`/`SimpleFeatureIterator`/`MapContent` 没 dispose 会导致文件锁与不写盘,验证前先确认进程已退出。
16
+ - **风险与权限**:写 PostGIS/Oracle 生产库、`SimpleFeatureStore` 批量覆盖、跳过测试打包上线都不可逆,动手前用 `ask_user_question` 给「只读实例 / 写到新表 / 直接写正式库」三选项
17
+ - 连接串、用户名、密码只放环境变量且不得回显到报告。`mvn clean` 会删本地产物,确认目录再跑。
18
+ - **常见失败**:出现 `com.vividsolutions.jts` 是包名没升级
19
+ - `CRS.decode` 报 `No such authority code` 多半缺 EPSG 模块
20
+ - 文件句柄泄漏或数据未写盘是漏了 `dispose()`/`try-with-resources`
21
+ - 多线程共享 `SimpleFeatureIterator` 会抛异常,每线程各开一个。把 `mvn -X` 日志重定向到 `run.log` 再 `grep -n "BUILD FAILURE" run.log`,不要全文读。