@dsh-gis/dsh-opengis-skill 0.4.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 (55) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +53 -8
  3. package/adaptations/brutile.md +19 -6
  4. package/adaptations/cesiumjs.md +14 -5
  5. package/adaptations/common.md +49 -20
  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 +21 -6
  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 +18 -6
  27. package/adaptations/maplibre-native.md +17 -6
  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 +19 -6
  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 +21 -6
  48. package/adaptations/whitebox-tools.md +19 -6
  49. package/lib/adaptations.d.ts +9 -0
  50. package/lib/adaptations.js +64 -0
  51. package/lib/index.d.ts +13 -9
  52. package/lib/index.js +32 -12
  53. package/lib/taxonomy.d.ts +41 -0
  54. package/lib/taxonomy.js +332 -0
  55. package/package.json +3 -2
@@ -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
- - **先探测版本**:先用正文给的 `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 是否都在跑;正文按 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 编写,低版本缺 `make_grid`、`read_file_info`(均为 1.2 新增)与 `to_parquet(write_covering_bbox=...)`;1.2 里 `buffer(resolution=...)` 已弃用改 `quad_segs`。再查 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` 不可用的根因。
6
- - **验证产物**:写完立刻重开核对:`gdf = gpd.read_file("out.gpkg", layer="result"); print(gdf.crs, len(gdf), gdf.is_valid.all(), gdf.total_bounds)`,并确认面积与长度是在投影坐标系下算的(经纬度下 `.area` 的单位是平方度)。只想按矩形范围裁剪时给 `gpd.clip()` 传四元素范围(如 `(minx, miny, maxx, maxy)`)会走更快的 `clip_by_rect()`,比多边形裁剪快但结果不保证拓扑有效,边角情形可能与多边形裁剪略异,交付前用 `is_valid` 复核。`to_parquet` 回读要核对列名、CRS 与 `schema_version`:不传时默认写 1.1.0,显式写 `"2.0.0"` 下游可能读不了;`write_covering_bbox=True` 才让后续 `read_parquet(bbox=...)` 真正生效。制图产物落成 PNG 后必须用 `read_image` 看一眼范围、图例与空几何,成品用 `present` 交付。
7
- - **风险与权限**:`to_file()` 默认整表覆盖、`to_postgis(if_exists="replace")` 会删表重建,执行前用 `ask_user_question` 确认路径与表名;连接串里的密码不要出现在命令、日志或回答里。Shapefile 字段名超 10 字符会被截断且不支持空值与日期时间,要保真就换 `.gpkg` 或 GeoParquet。
8
- - **常见失败**:`AttributeError: module 'geopandas' has no attribute 'make_grid'` / `read_file_info` 是装到了 1.2 之前的版本,先确认版本再改代码;`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` 发现。
@@ -1,8 +1,23 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,没有 reference 目录,正文的「环境准备」「C API 基础骨架」「核心 API」「典型工作流」「常见问题」按需跳读即可。要对照 Java 上游实现用 `skill` 加载 `jts`,要在 Python 侧复现同一套几何运算用 `skill` 加载 `shapely`(它内嵌的 GEOS 版本可能与本机不同,跨语言比对前先核对),入库与发布用 `skill` 加载 `postgis`、`gdal`;不要用 `read` 翻兄弟目录的 SKILL.md。
4
- - **执行环境**:编译与运行走 `ops_bash`(Windows 下是 MSYS bash,工程建在 `/d/work` 这类路径)。正文的 `apt-get`/`sudo` 在 Windows 不成立:装库走 vcpkg(`vcpkg install geos:x64-windows`)或 conda-forge(`conda install -c conda-forge geos`),装好后确认 `geos_c.dll` 与 exe 同目录或在 `PATH` 里;MSVC 工程用 `pwsh` 调 `cl /I <include> demo.c <lib>\geos_c.lib`,不要拿 bash 的 `-lgeos_c` 硬套。源码构建 `cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$PWD/install" ..` 后 `cmake --build . --parallel`,整套几分钟起,用 `run_in_background` 起作业再 `job_output` 收尾,不要在前台干等;安装前缀先指到会话工作区,别急着写系统目录。
5
- - **先探测版本**:`geos-config --version` 与 `pkg-config --modversion geos` 两个都跑:前者查二进制、后者查 `.pc` 登记值,两者不一致说明 PATH 里混了多套安装。再确认编译期头文件版本 `grep -h "GEOS_VERSION " "$(geos-config --prefix)/include/geos/version.h"`,与 `geos-config --version` 对不上就是 include 与 lib 不同源,链接阶段会报符号找不到。正文按 3.15.0 编写;3.12 起 WKTWriter 默认 trim、3.9 起默认 OverlayNG,按探测到的实际版本决定是否还要显式设置。
6
- - **验证产物**:别只看程序退出码。用 `write` 落一个最小 C 程序:两块 10x10 面错位 5 相交,`GEOSArea` 应恰为 25 而不是 0;再 `GEOSBuffer` 半径 0.5,面积应略大于 25。`GEOSisValid` 必须为 1,把输出 WKT 重新读回再比一次面积与顶点数;Windows 上再 `dumpbin /dependents demo.exe` 确认真的链到 `geos_c.dll`,否则运行期才报找不到模块。要看几何形状就写 WKT 转 PNG 的旁路,用 `read_image` 看一眼,纯白图与空结果等价。
7
- - **风险与权限**:`make install` 默认写 `/usr/local`、conda/vcpkg 安装会改环境变量与 PATH,执行前用 `ask_user_question` 给出「装到工作区前缀/替换系统库/取消」三个选项。本机若已有 QGIS、PostGIS、GDAL 自带的 `geos_c.dll`,覆盖它会让这些程序一起坏掉,先备份或改用独立前缀;升级 GEOS 后 C++ 侧必须重编(无 ABI 承诺),生产几何回归先在只读副本上跑。
8
- - **常见失败**:`TopologyException: side location conflict` 先 `GEOSisValid`+`GEOSMakeValid`,别急着加重试;`undefined reference to GEOSIntersection` 是 C API 却只链了 `-lgeos`;谓词结果反了是把 char 当布尔(1 真/2 假/0 异常);`free()` 释放 `GEOSWKTWriter_write` 返回的字符串在 Windows 上必崩,改用 `GEOSFree`。
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` 权限;忘记管理员密码:默认 XML 用户/组服务在数据目录 `security/usergroup/<name>/users.xml`(默认服务名 `default`),改完重启,或 Docker 部署用 `GEOSERVER_ADMIN_PASSWORD` 重置。日志里的报错用 `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`,不要全文读。
@@ -1,8 +1,26 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;正文按 GRASS GIS 8.5.0(8.4 LTR 最新补丁 8.4.2)编写,按任务跳「grass 启动器与无头执行」「g.region 计算区域管理」「数据导入导出」,Python 脚本化看「Python 脚本化」一节。本技能几乎不需要 `read` 参考文件,但和 `gdal`(`r.out.gdal` 后的格式与元数据核对)、`qgis-process` 经常连用,用 `skill` 按名加载,别去读兄弟目录的 SKILL.md。
4
- - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。正文的 `sudo apt install grass` 在 Windows 不存在:先探测 `grass --version`,没有就走 OSGeo4W 安装器(装好后在 OSGeo4W Shell 里用),或 `conda install -c conda-forge grass`,再不行 `docker run --rm -v "$PWD:/data" -w /data osgeo/grass-gis:latest grass ...`(容器内路径写 `/data`,别把 `D:\\...` 传进去)。`$HOME/grassdata` 换成会话工作区里的固定目录,避免每次换路径。正文 `--exec sh -c '...'` 的多行引用在 Windows 上不可靠,改写成单个 `.py` 脚本再用 `grass --tmp-project EPSG:3857 --exec python3 analysis.py`。整条地形分析链(import → slope → 导出)是长任务,用 `ops_bash` 的 `run_in_background` 跑,`job_output` 看日志。8.5 一个地图集可存多份掩膜,`r.mask.status` 查当前掩膜;Python 里切区域/掩膜用 `gs.RegionManager`/`gs.MaskManager` 上下文,退出自动还原,别手工 `g.region -d` 猜状态。
5
- - **先探测版本**:`grass --version` 拿到实际版本,再跑 `grass --tmp-project EPSG:3857 --exec g.version -rge` 确认能起无头会话。正文按 8.5.0 编写:8.5 要求 GDAL 3.7+、PROJ 9.0+、Python 3.10+(`g.version -rge` 输出里能读到 gdal/proj 实际版本,低于要求先升级依赖而不是怀疑数据);`grass.tools` 是 **8.5 新增**且官方标为实验性(预计 8.6 稳定),生产脚本先留在 `grass.script`,`ImportError` 就是版本不够,8.4.x/LTR 上只能用 `run_command`/`parse_command`;`--tmp-project` 在老 7.x 叫 `--tmp-location`,命令名不同。Docker 镜像标签形如 `8.5.0-ubuntu`,与本机版本不一致时先对齐再抄命令。
6
- - **验证产物**:`--tmp-project` 内的地图结束时随目录删除,必须先在脚本里 `r.out.gdal input=slope output=/work/slope.tif format=GTiff --overwrite` 导出,再用 `gdalinfo -json slope.tif` 核对 CRS、行列数、NoData 与范围;会话内核对用 `g.region -p format=json`(确认 rows/cols/res 符合预期)和 `g.list type=raster format=json`;8.5 起 `r.univar`/`r.stats`/`v.info` 等大量模块支持 `format=json`,脚本里一律 `gs.parse_command(..., format="json")` 取 dict,不要 `grep` 人类可读表格——列宽会随 locale 变。出图类结果(`d.rast` 转 PNG 或 gdal 渲染)用 `read_image` 真看一眼不是空白。判定依据是数值对得上,不是「模块没报错」。
7
- - **风险与权限**:`--overwrite`、`g.remove`、`g.rename`、`t.connect` 会改或删地图集数据,`t.rast.aggregate` 覆盖已有 strds 同理;这些操作先 `ask_user_question` 给「换新名字 / 先备份地图集 / 直接覆盖」三选项。Docker 里结果文件属主是 root,`--user=$(id -u):$(id -g)` 加 `--env HOME=/data/` 之前确认写入路径。时空数据库按地图集独立,连错地图集会看到空数据集而不是报错。
8
- - **常见失败**:`Exec format error` 是 `--exec` 脚本缺 shebang 或没有可执行权限;`GISBASE not defined` 说明 Python 在 GRASS 会话外跑,改用 `grass --exec python3` 或先 `gs.setup.init(...)`;`Raster map <x> not found` 先用 `g.list type=raster` 确认地图名与地图集;结果范围或分辨率不对几乎总是 `g.region` 没设对。模块错误以 `ERROR:` 或 `WARNING:` 开头并回非零码,按第一条真实错误定位。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 正文按 GRASS GIS 8.5.0(8.4 LTR 最新补丁 8.4.2)编写,按任务跳「grass 启动器与无头执行」「g.region 计算区域管理」「数据导入导出」,Python 脚本化看「Python 脚本化」一节。
5
+ - 本技能几乎不需要 `read` 参考文件,但和 `gdal`(`r.out.gdal` 后的格式与元数据核对)、`qgis-process` 经常连用,用 `skill` 按名加载,别去读兄弟目录的 SKILL.md
6
+ - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。
7
+ - 正文的 `sudo apt install grass` 在 Windows 不存在:先探测 `grass --version`,没有就走 OSGeo4W 安装器(装好后在 OSGeo4W Shell 里用),或 `conda install -c conda-forge grass`,再不行 `docker run --rm -v "$PWD:/data" -w /data osgeo/grass-gis:latest grass ...`(容器内路径写 `/data`,别把 `D:\\...` 传进去)。
8
+ - `$HOME/grassdata` 换成会话工作区里的固定目录,避免每次换路径。
9
+ - 正文 `--exec sh -c '...'` 的多行引用在 Windows 上不可靠,改写成单个 `.py` 脚本再用 `grass --tmp-project EPSG:3857 --exec python3 analysis.py`。
10
+ - 整条地形分析链(import → slope → 导出)是长任务,用 `ops_bash` 的 `run_in_background` 跑,`job_output` 看日志。
11
+ - 8.5 一个地图集可存多份掩膜,`r.mask.status` 查当前掩膜
12
+ - Python 里切区域/掩膜用 `gs.RegionManager`/`gs.MaskManager` 上下文,退出自动还原,别手工 `g.region -d` 猜状态。
13
+ - **先探测版本**:`grass --version` 拿到实际版本,再跑 `grass --tmp-project EPSG:3857 --exec g.version -rge` 确认能起无头会话。正文按 8.5.0 编写:8.5 要求 GDAL 3.7+、PROJ 9.0+、Python 3.10+(`g.version -rge` 输出里能读到 gdal/proj 实际版本,低于要求先升级依赖而不是怀疑数据)
14
+ - `grass.tools` 是 **8.5 新增**且官方标为实验性(预计 8.6 稳定),生产脚本先留在 `grass.script`,`ImportError` 就是版本不够,8.4.x/LTR 上只能用 `run_command`/`parse_command`
15
+ - `--tmp-project` 在老 7.x 叫 `--tmp-location`,命令名不同。Docker 镜像标签形如 `8.5.0-ubuntu`,与本机版本不一致时先对齐再抄命令。
16
+ - **验证产物**:`--tmp-project` 内的地图结束时随目录删除,必须先在脚本里 `r.out.gdal input=slope output=/work/slope.tif format=GTiff --overwrite` 导出,再用 `gdalinfo -json slope.tif` 核对 CRS、行列数、NoData 与范围
17
+ - 会话内核对用 `g.region -p format=json`(确认 rows/cols/res 符合预期)和 `g.list type=raster format=json`
18
+ - 8.5 起 `r.univar`/`r.stats`/`v.info` 等大量模块支持 `format=json`,脚本里一律 `gs.parse_command(..., format="json")` 取 dict,不要 `grep` 人类可读表格——列宽会随 locale 变。
19
+ - 出图类结果(`d.rast` 转 PNG 或 gdal 渲染)用 `read_image` 真看一眼不是空白。
20
+ - 判定依据是数值对得上,不是「模块没报错」
21
+ - **风险与权限**:`--overwrite`、`g.remove`、`g.rename`、`t.connect` 会改或删地图集数据,`t.rast.aggregate` 覆盖已有 strds 同理
22
+ - 这些操作先 `ask_user_question` 给「换新名字 / 先备份地图集 / 直接覆盖」三选项。Docker 里结果文件属主是 root,`--user=$(id -u):$(id -g)` 加 `--env HOME=/data/` 之前确认写入路径。时空数据库按地图集独立,连错地图集会看到空数据集而不是报错。
23
+ - **常见失败**:`Exec format error` 是 `--exec` 脚本缺 shebang 或没有可执行权限
24
+ - `GISBASE not defined` 说明 Python 在 GRASS 会话外跑,改用 `grass --exec python3` 或先 `gs.setup.init(...)`
25
+ - `Raster map <x> not found` 先用 `g.list type=raster` 确认地图名与地图集
26
+ - 结果范围或分辨率不对几乎总是 `g.region` 没设对。模块错误以 `ERROR:` 或 `WARNING:` 开头并回非零码,按第一条真实错误定位。
@@ -1,8 +1,20 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文按 jts-core 1.20.0 编写,空间关系、集合运算、格式读写、空间索引的完整示例在 `reference/geometry-operations.md`:先 `read` 开头的小节清单再按 `offset`/`limit` 分段取,或 `grep` 搜 `STRtree`、`OverlayNGRobust` 定位,不要整读。主文件只需要「几何对象创建」「典型工作流」两节;要 GeoJSON 写出才需要 `jts-io-common`,别为跑通一个 buffer 就把两个模块都引进来。.NET 侧对应实现用 `skill` 加载 `nettopologysuite`,几何与地图结合用 `skill` 加载 `geotools`。
4
- - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。`jts-core` 在 Maven Central,不依赖 OSGeo 仓库,JDK 8+ 就能编译;先用 `java -version`、`mvn -v` 探测,没装 Maven 用 Maven wrapper 或官方 zip,Java 用 Temurin 安装包或 `conda install -c conda-forge openjdk`,都没有则 `docker run --rm -v "$PWD:/w" -w /w maven:3.9-eclipse-temurin-17 mvn ...`。首次解析依赖会下载几十 MB,用 `ops_bash` 的 `run_in_background` 跑、`job_output` 收日志;大几何批量运算(百万级要素 union)写在 main 里限时分批,别让一次调用超时。
5
- - **先探测版本**:`mvn dependency:tree -Dincludes=org.locationtech.jts` 确认解析到 1.20.0,同时 `grep -rn "vividsolutions" pom.xml src` 确认没有遗留旧包名——JTS 1.15+ 已从 `com.vividsolutions.jts` 迁到 `org.locationtech.jts`。1.20.0 的叠加引擎以 `OverlayNGRobust` 为推荐入口,低版本(1.16/1.17 早期)只有旧叠加引擎、更容易抛拓扑异常;`GeometryFixer` 也需要较新版本,老版本没有这个类。
6
- - **验证产物**:`mvn -q test` 之外必须跑最小 main 并断言:WKT 读入 → `isValid()` → `buffer(0)` → 坐标数比对;写 GeoJSON 后用 `GeoJsonReader` 读回、比对 geometry 数量与首点坐标(用 `System.out` 打一行摘要,别打整段坐标串)。测面积/长度这类结果时给两个已知几何写死期望值做断言,只打印「跑完了」不算验证。
7
- - **风险与权限**:JTS 的 SRID 只是元数据、全部运算在笛卡尔平面,把经纬度当平面算缓冲区出来的距离是「度」不是米——涉及真实距离先用 `skill` 加载 `proj` 投影再算,或用 `ask_user_question` 跟用户确认单位与坐标系。读外部几何前先 `IsValidOp` 校验,非法几何参与叠加会污染结果;覆盖已有数据、批量写库前先确认。
8
- - **常见失败**:`TopologyException` 换 `OverlayNGRobust.overlay()`;`isValid()` 为 false 先 `GeometryFixer.fix()`;点不进面多半是坐标写成了 `(lat, lon)`(JTS 是 `(x, y)` 即经度、纬度);写 GeoJSON 抛 `NoClassDefFoundError: org/json/simple/JSONAware` 是手工 classpath 丢了 `json-simple` 传递依赖;`WKTReader`/`WKTWriter` 线程不安全,多线程共享会出随机错误,每线程各建一个。
3
+ - **加载与引用**:正文按 jts-core 1.20.0 编写,空间关系、集合运算、格式读写、空间索引的完整示例在 `reference/geometry-operations.md`:先 `read` 开头的小节清单再按 `offset`/`limit` 分段取,或 `grep` 搜 `STRtree`、`OverlayNGRobust` 定位,不要整读。主文件只需要「几何对象创建」「典型工作流」两节
4
+ - 要 GeoJSON 写出才需要 `jts-io-common`,别为跑通一个 buffer 就把两个模块都引进来。.NET 侧对应实现用 `skill` 加载 `nettopologysuite`,几何与地图结合用 `skill` 加载 `geotools`。
5
+ - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash)。`jts-core` 在 Maven Central,不依赖 OSGeo 仓库,JDK 8+ 就能编译
6
+ - 先用 `java -version`、`mvn -v` 探测,没装 Maven 用 Maven wrapper 或官方 zip,Java 用 Temurin 安装包或 `conda install -c conda-forge openjdk`,都没有则 `docker run --rm -v "$PWD:/w" -w /w maven:3.9-eclipse-temurin-17 mvn ...`。
7
+ - 首次解析依赖会下载几十 MB,用 `ops_bash` 的 `run_in_background` 跑、`job_output` 收日志
8
+ - 大几何批量运算(百万级要素 union)写在 main 里限时分批,别让一次调用超时。
9
+ - **先探测版本**:`mvn dependency:tree -Dincludes=org.locationtech.jts` 确认解析到 1.20.0,同时 `grep -rn "vividsolutions" pom.xml src` 确认没有遗留旧包名——JTS 1.15+ 已从 `com.vividsolutions.jts` 迁到 `org.locationtech.jts`。
10
+ - 1.20.0 的叠加引擎以 `OverlayNGRobust` 为推荐入口,低版本(1.16/1.17 早期)只有旧叠加引擎、更容易抛拓扑异常
11
+ - `GeometryFixer` 也需要较新版本,老版本没有这个类。
12
+ - **验证产物**:`mvn -q test` 之外必须跑最小 main 并断言:WKT 读入 → `isValid()` → `buffer(0)` → 坐标数比对
13
+ - 写 GeoJSON 后用 `GeoJsonReader` 读回、比对 geometry 数量与首点坐标(用 `System.out` 打一行摘要,别打整段坐标串)。测面积/长度这类结果时给两个已知几何写死期望值做断言,只打印「跑完了」不算验证。
14
+ - **风险与权限**:JTS 的 SRID 只是元数据、全部运算在笛卡尔平面,把经纬度当平面算缓冲区出来的距离是「度」不是米——涉及真实距离先用 `skill` 加载 `proj` 投影再算,或用 `ask_user_question` 跟用户确认单位与坐标系。读外部几何前先 `IsValidOp` 校验,非法几何参与叠加会污染结果
15
+ - 覆盖已有数据、批量写库前先确认。
16
+ - **常见失败**:`TopologyException` 换 `OverlayNGRobust.overlay()`
17
+ - `isValid()` 为 false 先 `GeometryFixer.fix()`
18
+ - 点不进面多半是坐标写成了 `(lat, lon)`(JTS 是 `(x, y)` 即经度、纬度)
19
+ - 写 GeoJSON 抛 `NoClassDefFoundError: org/json/simple/JSONAware` 是手工 classpath 丢了 `json-simple` 传递依赖
20
+ - `WKTReader`/`WKTWriter` 线程不安全,多线程共享会出随机错误,每线程各建一个。
@@ -1,8 +1,21 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference。正文按 Kepler.gl **3.3.0-alpha.20**(npm `latest` 与 GitHub Release 一致,仍是 3.3 预发布线、4.0 无稳定版)与 Python 侧 `keplergl` **0.4.0** 编写。按任务读:「环境准备」区分 npm 整包/子包、UMD、Jupyter 三条路;「核心 API」四节讲 dataset 结构、Redux 接入、`addDataToMap`、配置导出;「常见问题」表的报错原文可直接对照。定位性细节(Redux 接线、config 还原)要先读完全节再写代码,组件 prop 表在「KeplerGl 组件」。自定义图层底座用 `skill` 加载 `deck-gl`,默认底图与矢量瓦片用 `skill` 加载 `maplibre-gl-js`(免 token;只有要 Mapbox 官方样式与 token 时才加载 `mapbox-gl-js`),数据预处理用 `skill` 加载 `geopandas`。
4
- - **执行环境**:npm/pip 命令走 `ops_bash`(Windows 下是 MSYS bash),`chrome`、`Get-Command` 这类走 `pwsh`。安装依赖(`npm install kepler.gl` 会拉 deck.gl、maplibre 等上百个包)和 `npm run build` 都是长任务:用 `ops_bash` 的 `run_in_background` 跑,`job_output` 分段收日志,失败用 `job_kill` 收尾;输出重定向到 `build.log` 再 `grep -n "ERR\|error" build.log`,别把整段 webpack 输出打进上下文。没有浏览器可用的环境无法验证 WebGL 渲染,不要假装渲染成功。三步以上(装包 → 建工程 → build → 起静态服务)先 `todo_write`。
5
- - **先探测版本**:`npm ls kepler.gl @kepler.gl/components @kepler.gl/actions` 一次确认主包与子包版本是否一致(正文明确要求子包与主包同为 3.3.0-alpha.20,混版会出现难定位的运行时错误);Python 侧 `python -c "import keplergl; print(keplergl.__version__)"` 应为 0.4.0。差异点:3.3 线是预发布,写 `^3.3.0` 可能解析不到 alpha 版本,要精确锁定;`keplergl` 0.4.0 依赖 Python >= 3.9、JupyterLab >= 4 或 Notebook >= 7,conda-forge 尚停在 0.3.2,要 0.4.0 只能用 pip。不看版本直接抄正文示例是这类项目最常见的返工来源。
6
- - **验证产物**:`npm run build` 通过只说明 TypeScript/打包没问题。再 `npx serve dist` 起静态服务(后台作业),用浏览器或无头浏览器打开页面截图,再用 `read_image` 真看一眼:底图有没有出来、有没有图层、侧栏数据条数对不对;同时看控制台第一条报错。Python 侧验证 `save_to_html` 的输出时,检查 HTML 文件确实含内嵌数据、浏览器打开后图层可见,成品用 `present` 交给用户。判据是「图上看得见正确图层」,不是「build 退出码 0」。
3
+ - **加载与引用**:单文件技能,无 reference。正文按 Kepler.gl **3.3.0-alpha.20**(npm `latest` 与 GitHub Release 一致,仍是 3.3 预发布线、4.0 无稳定版)与 Python 侧 `keplergl` **0.4.0** 编写。按任务读:「环境准备」区分 npm 整包/子包、UMD、Jupyter 三条路
4
+ - 「核心 API」四节讲 dataset 结构、Redux 接入、`addDataToMap`、配置导出
5
+ - 「常见问题」表的报错原文可直接对照。
6
+ - 定位性细节(Redux 接线、config 还原)要先读完全节再写代码,组件 prop 表在「KeplerGl 组件」。
7
+ - 自定义图层底座用 `skill` 加载 `deck-gl`,默认底图与矢量瓦片用 `skill` 加载 `maplibre-gl-js`(免 token;只有要 Mapbox 官方样式与 token 时才加载 `mapbox-gl-js`),数据预处理用 `skill` 加载 `geopandas`
8
+ - **执行环境**:npm/pip 命令走 `ops_bash`(Windows 下是 MSYS bash),`chrome`、`Get-Command` 这类走 `pwsh`。
9
+ - 安装依赖(`npm install kepler.gl` 会拉 deck.gl、maplibre 等上百个包)和 `npm run build` 都是长任务:用 `ops_bash` 的 `run_in_background` 跑,`job_output` 分段收日志,失败用 `job_kill` 收尾
10
+ - 输出重定向到 `build.log` 再 `grep -n "ERR\|error" build.log`,别把整段 webpack 输出打进上下文。没有浏览器可用的环境无法验证 WebGL 渲染,不要假装渲染成功。三步以上(装包 → 建工程 → build → 起静态服务)先 `todo_write`。
11
+ - **先探测版本**:`npm ls kepler.gl @kepler.gl/components @kepler.gl/actions` 一次确认主包与子包版本是否一致(正文明确要求子包与主包同为 3.3.0-alpha.20,混版会出现难定位的运行时错误)
12
+ - Python 侧 `python -c "import keplergl; print(keplergl.__version__)"` 应为 0.4.0。差异点:3.3 线是预发布,写 `^3.3.0` 可能解析不到 alpha 版本,要精确锁定
13
+ - `keplergl` 0.4.0 依赖 Python >= 3.9、JupyterLab >= 4 或 Notebook >= 7,conda-forge 尚停在 0.3.2,要 0.4.0 只能用 pip。不看版本直接抄正文示例是这类项目最常见的返工来源。
14
+ - **验证产物**:`npm run build` 通过只说明 TypeScript/打包没问题。再 `npx serve dist` 起静态服务(后台作业),用浏览器或无头浏览器打开页面截图,再用 `read_image` 真看一眼:底图有没有出来、有没有图层、侧栏数据条数对不对
15
+ - 同时看控制台第一条报错。Python 侧验证 `save_to_html` 的输出时,检查 HTML 文件确实含内嵌数据、浏览器打开后图层可见,成品用 `present` 交给用户。判据是「图上看得见正确图层」,不是「build 退出码 0」。
7
16
  - **风险与权限**:装 npm/pip 包、把用户数据写进可分享的 HTML、把含 token 的工程提交进仓库都要先确认——用 `ask_user_question` 给「只装本地 / 用 Docker node 镜像跑 / 先不装」这类选项。Mapbox token 有计费与泄露风险:只用 CARTO/MapLibre 样式时 `mapboxApiAccessToken` 传空串,绝不硬编码进配置或 HTML。
8
- - **常见失败**:组件空白且控制台报 `Could not find ... in the context of Connect(...)`,是 reducer 没挂 `keplerGl` 键或 `getState` 指错;有数据没图层查 `datasets.info.id` 与 `config` 的 `dataId` 是否一致、字段类型是否为数值;时间轴不生效是缺少 `{type: 'timestamp', format: ...}`;点位全堆 (0,0) 是坐标系没转 EPSG:4326;`Cannot find module '@kepler.gl/components'` 是装了整包却按子包路径 import。一次 `addDataToMap` 塞几十万行会卡死主线程,先聚合或用 Arrow。
17
+ - **常见失败**:组件空白且控制台报 `Could not find ... in the context of Connect(...)`,是 reducer 没挂 `keplerGl` 键或 `getState` 指错
18
+ - 有数据没图层查 `datasets.info.id` 与 `config` 的 `dataId` 是否一致、字段类型是否为数值
19
+ - 时间轴不生效是缺少 `{type: 'timestamp', format: ...}`
20
+ - 点位全堆 (0,0) 是坐标系没转 EPSG:4326
21
+ - `Cannot find module '@kepler.gl/components'` 是装了整包却按子包路径 import。一次 `addDataToMap` 塞几十万行会卡死主线程,先聚合或用 Arrow。
@@ -1,8 +1,27 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference。正文按 Leaflet **1.9.4** 编写(2023-05 发布,至今仍是稳定版;npm 与 GitHub Release 一致)。按任务读三节:「核心 API」查 `L.map`/`L.tileLayer`/`L.geoJSON` 的选项表;「与 Vue / React 集成」拿生命周期写法;「常见问题」表的报错原文可直接对照定位。CSS 与 SRI 哈希只对 1.9.4 有效,改版本要连哈希一起换。数据源是 WMS/WFS 时用 `skill` 加载 `geoserver`,要更强投影与 MVT 能力用 `skill` 加载 `openlayers`。
4
- - **执行环境**:`npm install`、`npm run build` 走 `ops_bash`(Windows 下是 MSYS bash),`Get-Command`、`Invoke-WebRequest` 这类 Windows 原生命令走 `pwsh`。正文用 `python -m http.server 5173` 起静态服务,Windows 上 `python` 不在 PATH 时改用 `py -3 -m http.server 5173`;起服务、`npm install` 都是长任务,用 `ops_bash` 的 `run_in_background` 跑,`job_output` 收日志、`job_kill` 收尾。三步以上(装包 → build → 起服务 → 截图核对)先 `todo_write`。没有 node 时用 `docker run --rm -v "$PWD:/w" -w /w node:22 bash -lc "npm i && npm run build"`。
5
- - **先探测版本**:`npm ls leaflet` 看实际装到哪版,没装则 `npm view leaflet version`;页面里 `console.log(L.version)` 应为 `"1.9.4"`。差异点:正文明确 1.9.4 仍是当前稳定版,2.0 只有 beta(`v2.0.0-beta.3`,2026-11-10 发布)且 API/插件兼容性仍在变动,回答与示例默认给 1.9.4 方案,用户明确要试 2.0 时先说明是预发布、`npm view leaflet dist-tags` 核对 `next` 指向哪版;网上大量 1.7/1.8 教程;CDN 的 `integrity` 哈希与版本强绑定,把 1.9.4 的哈希贴到别的版本上会直接白屏。正文按 1.9.4 写的 API(如 `coordsToLatLng`、`L.Draw.Event`)在 1.6 前的插件里可能不同名。
6
- - **验证产物**:正文给了明确验收:页面先出 OSM 底图 → 数据加载后视野收到点位范围 → 点圆点弹名称 → 右上角能切 POI。先在 `ops_bash` 里 `curl.exe -I http://localhost:5173/` 与入口 js 确认 200,再让浏览器打开页面,环境允许时截图并用 `read_image` 真看一眼瓦片、标记、控件都在位。判据是「图上看得见正确图层与弹窗」,不是构建退出码 0;SPA 里还要检查切路由后没有重复实例与内存增长。
7
- - **风险与权限**:`npm install` 改依赖树、`npm run build` 覆盖 `dist/`、起服务占端口,都先 `ask_user_question` 给「只本地跑 / 用 Docker 沙箱跑 / 先不装」选项,别默认占 80 端口。天地图等瓦片服务的 `tk`、含 token 的底图 URL 不要硬编码进提交的前端代码;使用 OSM 必须保留 `attribution`,别把版权信息抹掉。
8
- - **常见失败**:`Uncaught Error: Map container is already initialized.` 是同一容器 `L.map()` 两次(React StrictMode、热更新最常见),先 `map.remove()` 并把引用置空;`Map container not found.` 是 DOM 还没挂载;`L is not defined` 是脚本顺序或 CDN 失败;区域空白基本是容器没设 `height`;`invalidateSize()` 只在容器尺寸变化后调用;npm + 打包器下默认 marker 图标 404,要显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`。坐标一律 `[lat, lng]`,GeoJSON 是 `[lng, lat]`,别混。
3
+ - **加载与引用**:单文件技能,无 reference。正文按 Leaflet **1.9.4** 编写(2023-05 发布,至今仍是稳定版;npm 与 GitHub Release 一致)。按任务读三节:「核心 API」查 `L.map`/`L.tileLayer`/`L.geoJSON` 的选项表
4
+ - 「与 Vue / React 集成」拿生命周期写法
5
+ - 「常见问题」表的报错原文可直接对照定位。CSS 与 SRI 哈希只对 1.9.4 有效,改版本要连哈希一起换。数据源是 WMS/WFS 时用 `skill` 加载 `geoserver`,要更强投影与 MVT 能力用 `skill` 加载 `openlayers`。
6
+ - **执行环境**:`npm install`、`npm run build` 走 `ops_bash`(Windows 下是 MSYS bash),`Get-Command`、`Invoke-WebRequest` 这类 Windows 原生命令走 `pwsh`。
7
+ - 正文用 `python -m http.server 5173` 起静态服务,Windows 上 `python` 不在 PATH 时改用 `py -3 -m http.server 5173`
8
+ - 起服务、`npm install` 都是长任务,用 `ops_bash` 的 `run_in_background` 跑,`job_output` 收日志、`job_kill` 收尾。
9
+ - 三步以上(装包 → build → 起服务 → 截图核对)先 `todo_write`。
10
+ - 没有 node 时用 `docker run --rm -v "$PWD:/w" -w /w node:22 bash -lc "npm i && npm run build"`
11
+ - **先探测版本**:`npm ls leaflet` 看实际装到哪版,没装则 `npm view leaflet version`
12
+ - 页面里 `console.log(L.version)` 应为 `"1.9.4"`。
13
+ - 差异点:正文明确 1.9.4 仍是当前稳定版,2.0 只有 beta(`v2.0.0-beta.3`,2026-11-10 发布)且 API/插件兼容性仍在变动,回答与示例默认给 1.9.4 方案,用户明确要试 2.0 时先说明是预发布、`npm view leaflet dist-tags` 核对 `next` 指向哪版
14
+ - 网上大量 1.7/1.8 教程
15
+ - CDN 的 `integrity` 哈希与版本强绑定,把 1.9.4 的哈希贴到别的版本上会直接白屏。正文按 1.9.4 写的 API(如 `coordsToLatLng`、`L.Draw.Event`)在 1.6 前的插件里可能不同名。
16
+ - **验证产物**:正文给了明确验收:页面先出 OSM 底图 → 数据加载后视野收到点位范围 → 点圆点弹名称 → 右上角能切 POI。
17
+ - 先在 `ops_bash` 里 `curl.exe -I http://localhost:5173/` 与入口 js 确认 200,再让浏览器打开页面,环境允许时截图并用 `read_image` 真看一眼瓦片、标记、控件都在位。
18
+ - 判据是「图上看得见正确图层与弹窗」,不是构建退出码 0
19
+ - SPA 里还要检查切路由后没有重复实例与内存增长。
20
+ - **风险与权限**:`npm install` 改依赖树、`npm run build` 覆盖 `dist/`、起服务占端口,都先 `ask_user_question` 给「只本地跑 / 用 Docker 沙箱跑 / 先不装」选项,别默认占 80 端口。天地图等瓦片服务的 `tk`、含 token 的底图 URL 不要硬编码进提交的前端代码
21
+ - 使用 OSM 必须保留 `attribution`,别把版权信息抹掉。
22
+ - **常见失败**:`Uncaught Error: Map container is already initialized.` 是同一容器 `L.map()` 两次(React StrictMode、热更新最常见),先 `map.remove()` 并把引用置空
23
+ - `Map container not found.` 是 DOM 还没挂载
24
+ - `L is not defined` 是脚本顺序或 CDN 失败
25
+ - 区域空白基本是容器没设 `height`
26
+ - `invalidateSize()` 只在容器尺寸变化后调用
27
+ - npm + 打包器下默认 marker 图标 404,要显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`。坐标一律 `[lat, lng]`,GeoJSON 是 `[lng, lat]`,别混。