@dsh-gis/dsh-opengis-skill 0.1.3 → 0.2.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 (97) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/README.md +48 -22
  3. package/THIRD_PARTY_NOTICES.md +9 -0
  4. package/adaptations/brutile.md +8 -0
  5. package/adaptations/cesiumjs.md +8 -0
  6. package/adaptations/common.md +16 -0
  7. package/adaptations/deck-gl.md +8 -0
  8. package/adaptations/duckdb-spatial.md +8 -0
  9. package/adaptations/gdal-api.md +8 -0
  10. package/adaptations/gdal.md +8 -0
  11. package/adaptations/geolibre.md +8 -0
  12. package/adaptations/geometry-api-java.md +8 -0
  13. package/adaptations/geometry-api-net.md +8 -0
  14. package/adaptations/geonode.md +8 -0
  15. package/adaptations/geopandas.md +8 -0
  16. package/adaptations/geopipe-agent.md +8 -0
  17. package/adaptations/geoserver-cloud.md +8 -0
  18. package/adaptations/geoserver-rest-api.md +8 -0
  19. package/adaptations/geoserver.md +8 -0
  20. package/adaptations/geotools.md +8 -0
  21. package/adaptations/grass-gis.md +8 -0
  22. package/adaptations/jts.md +8 -0
  23. package/adaptations/kepler-gl.md +8 -0
  24. package/adaptations/leaflet.md +8 -0
  25. package/adaptations/mapbox-gl-js.md +8 -0
  26. package/adaptations/mapserver.md +8 -0
  27. package/adaptations/mapsui.md +8 -0
  28. package/adaptations/nettopologysuite.md +8 -0
  29. package/adaptations/opengis-all.md +8 -0
  30. package/adaptations/opengis-daf.md +8 -0
  31. package/adaptations/opengis-utils-for-java.md +8 -0
  32. package/adaptations/opengis-utils-for-net.md +8 -0
  33. package/adaptations/openlayers.md +8 -0
  34. package/adaptations/pdal.md +8 -0
  35. package/adaptations/postgis.md +8 -0
  36. package/adaptations/proj.md +8 -0
  37. package/adaptations/projnet4geoapi.md +8 -0
  38. package/adaptations/pyqgis.md +8 -0
  39. package/adaptations/qgis-process.md +8 -0
  40. package/adaptations/qgis-server.md +8 -0
  41. package/adaptations/shapely.md +8 -0
  42. package/adaptations/sharpmap.md +8 -0
  43. package/adaptations/spatialite.md +8 -0
  44. package/adaptations/whitebox-tools.md +8 -0
  45. package/assets/brutile/SKILL.md +289 -0
  46. package/assets/cesiumjs/SKILL.md +73 -23
  47. package/assets/deck-gl/SKILL.md +19 -20
  48. package/assets/duckdb-spatial/SKILL.md +370 -0
  49. package/assets/gdal/SKILL.md +50 -21
  50. package/assets/gdal-api/SKILL.md +6 -4
  51. package/assets/geolibre/SKILL.md +364 -0
  52. package/assets/geometry-api-java/SKILL.md +5 -6
  53. package/assets/geometry-api-net/SKILL.md +65 -21
  54. package/assets/geonode/SKILL.md +347 -0
  55. package/assets/geopandas/SKILL.md +17 -15
  56. package/assets/geopipe-agent/SKILL.md +25 -20
  57. package/assets/geoserver/SKILL.md +6 -4
  58. package/assets/geoserver-cloud/SKILL.md +14 -15
  59. package/assets/geoserver-rest-api/SKILL.md +13 -8
  60. package/assets/geotools/SKILL.md +7 -5
  61. package/assets/grass-gis/SKILL.md +19 -20
  62. package/assets/jts/SKILL.md +7 -4
  63. package/assets/kepler-gl/SKILL.md +313 -0
  64. package/assets/leaflet/SKILL.md +41 -19
  65. package/assets/mapbox-gl-js/SKILL.md +18 -19
  66. package/assets/mapserver/SKILL.md +17 -19
  67. package/assets/mapsui/SKILL.md +85 -48
  68. package/assets/nettopologysuite/SKILL.md +91 -20
  69. package/assets/opengis-all/SKILL.md +78 -270
  70. package/assets/opengis-all/reference/data-stages.md +262 -4
  71. package/assets/opengis-daf/SKILL.md +6 -5
  72. package/assets/opengis-utils-for-java/SKILL.md +52 -39
  73. package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
  74. package/assets/opengis-utils-for-net/SKILL.md +105 -39
  75. package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
  76. package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
  77. package/assets/openlayers/SKILL.md +66 -9
  78. package/assets/pdal/SKILL.md +21 -17
  79. package/assets/postgis/SKILL.md +61 -11
  80. package/assets/proj/SKILL.md +28 -30
  81. package/assets/projnet4geoapi/SKILL.md +299 -0
  82. package/assets/pyqgis/SKILL.md +28 -20
  83. package/assets/qgis-process/SKILL.md +71 -22
  84. package/assets/qgis-server/SKILL.md +20 -20
  85. package/assets/shapely/SKILL.md +132 -75
  86. package/assets/sharpmap/SKILL.md +93 -50
  87. package/assets/spatialite/SKILL.md +365 -0
  88. package/assets/whitebox-tools/SKILL.md +269 -0
  89. package/lib/adaptations.d.ts +47 -0
  90. package/lib/adaptations.js +268 -0
  91. package/lib/index.d.ts +1 -1
  92. package/lib/index.js +14 -2
  93. package/lib/skill-file.js +31 -7
  94. package/locale/en.json +1 -1
  95. package/locale/zh.json +1 -1
  96. package/package.json +12 -2
  97. package/upstream.json +56 -40
@@ -19,19 +19,18 @@ tags:
19
19
  >
20
20
  > **NuGet:** `OpenGIS.Esri.Geometry.Core`(最新 1.0.9,截至 2026-10)
21
21
  >
22
- > **注意:** 原 Esri 仓库(github.com/Esri/geometry-api-net)已不再维护(404)。此分支由 znlgis 社区维护,已重命名为 OpenGIS.Esri.Geometry。
23
- >
24
22
  > **许可证:** LGPL-2.1
25
- >
26
- > 本文件旨在帮助 AI 快速理解并使用 geometry-api-net 库进行空间几何开发。
23
+ >
24
+ > **注意:** 原 Esri 仓库(github.com/Esri/geometry-api-net)已停止维护(404);此分支由 znlgis 社区维护,包名与命名空间已改为 `OpenGIS.Esri.Geometry`。
27
25
 
28
26
  ## 概述
29
27
 
30
- 这是一个 .NET Standard 2.0 的空间几何计算库,提供 6 种几何类型、28 个空间运算算子(含 DE-9IM 驱动的 9 个谓词、多边形布尔运算、缓冲/简化/MakeValid 与大地测量)和 4 种序列化格式(WKT/EWKT、WKB/EWKB、GeoJSON、Esri JSON),核心引擎已与 PostGIS/GEOS 交叉验证。
28
+ 这是一个 .NET Standard 2.0 的空间几何计算库,提供 6 种几何类型(Point、MultiPoint、Line、Polyline、Polygon、Envelope)、35 个算子类(`Operators` 命名空间 27 个几何算子 + `IO` 命名空间 8 个读写算子,含 8 个 DE-9IM 谓词:Contains/Crosses/Disjoint/Equals/Intersects/Overlaps/Touches/Within)和 4 种序列化格式(WKT/EWKT、WKB/EWKB、GeoJSON、Esri JSON)。
31
29
 
32
- - **核心包**: `OpenGIS.Esri.Geometry.Core`
33
- - **JSON 扩展包**: `OpenGIS.Esri.Geometry.Json`
34
- - **许可证**: LGPL-2.1-only
30
+ - **核心包**:`OpenGIS.Esri.Geometry.Core`(`GeometryEngine` 提供 39 个静态便捷方法)
31
+ - **JSON 扩展包**:`OpenGIS.Esri.Geometry.Json`(System.Text.Json 转换器)
32
+ - **许可证**:LGPL-2.1-only
33
+ - **能力边界**:不提供 `MakeValid`,`Simplify` 只做抽稀、不修复自相交环;需要几何修复请在上游(GEOS/PostGIS/JTS)完成后再导入。
35
34
 
36
35
  ## 快速开始
37
36
 
@@ -166,6 +165,50 @@ result.IsRightSide // bool, 是否在多路径几何的右侧
166
165
 
167
166
  ---
168
167
 
168
+ ## 典型工作流
169
+
170
+ 端到端:WKT 读入 → 有效性校验 → 叠加分析 → 输出 GeoJSON 与 Esri JSON。
171
+
172
+ ```csharp
173
+ using OpenGIS.Esri.Geometry.Core;
174
+ using OpenGIS.Esri.Geometry.Core.Geometries;
175
+ using OpenGIS.Esri.Geometry.Core.IO;
176
+
177
+ // 1. 从 WKT 读入输入几何(环由库自动闭合)
178
+ Geometry parcel = GeometryEngine.GeometryFromWkt(
179
+ "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))");
180
+ Geometry zone = GeometryEngine.GeometryFromWkt(
181
+ "POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))");
182
+
183
+ // 2. 校验:先确认几何本身可用,不要拿 0 容差去"修复"
184
+ if (!parcel.IsValid() || !zone.IsValid())
185
+ throw new InvalidOperationException("输入几何无效,请先修正数据");
186
+
187
+ // 3. 叠加:求交集(5×5 的方形重叠区)
188
+ Geometry overlapArea = GeometryEngine.Intersection(parcel, zone);
189
+ bool intersects = GeometryEngine.Intersects(parcel, zone); // true
190
+ double area = GeometryEngine.Area(overlapArea); // 约 25(内部容差带来 1e-6 级误差)
191
+
192
+ // 4. 输出两种格式
193
+ string geoJson = GeometryEngine.GeometryToGeoJson(overlapArea);
194
+ string esriJson = EsriJsonExportOperator.Instance.Execute(overlapArea);
195
+
196
+ // 5. 回读校验:序列化再反序列化,几何应一致
197
+ Geometry roundTrip = GeometryEngine.GeometryFromGeoJson(geoJson);
198
+ bool same = GeometryEngine.Equals(overlapArea, roundTrip);
199
+ ```
200
+
201
+ **输出与验收**:
202
+
203
+ - `overlapArea` 是 `(5,5)-(10,10)` 的矩形,`GeometryEngine.Area()` 实测约 `24.999998`(默认容差 `1e-10` 下的浮点结果,不要断言严格等于 25)。
204
+ - `geoJson` 形如 `{"type":"Polygon","coordinates":[[[10,5],...]]}`;`esriJson` 形如 `{"rings":[[[10,5],...]]}`。
205
+ - `same` 必须为 `true`;若为 `false`,先检查环是否闭合、坐标顺序是否一致。
206
+ - `GeometryEngine.Simplify(geometry, tolerance)` 的 `tolerance` 必须为正,传 `0.0` 会抛 `ArgumentException: Tolerance must be positive`;且 `Simplify` 只做抽稀,不保证把自相交环修成有效面,需修复无效数据请在上游处理。
207
+
208
+ > 注意:集合运算返回 `Geometry` 基类,需要面积/环等具体成员时按实际类型(`Polygon`/`Polyline`)转型后再用。
209
+
210
+ ---
211
+
169
212
  ## 常见开发场景
170
213
 
171
214
  ### 场景 1:判断点是否在多边形内
@@ -304,30 +347,31 @@ dotnet run --project samples/OpenGIS.Esri.Geometry.Samples
304
347
 
305
348
  ---
306
349
 
307
- ## DeepSeek Harness 使用建议
308
-
309
- - **加载与引用**:用 `skill("geometry-api-net")` 加载(用户也可输入 `/geometry-api-net`);`reference/geometry-types.md` 按需 `read`,路径相对加载结果中的 Base directory;技能目录只读,示例工程建在会话工作区。
310
- - **执行环境**:先 `dotnet --version`(库目标 `netstandard2.0`,可被 net6/net8/net9/net10 引用);Windows 上用 `pwsh` 执行 `dotnet` 命令,`dotnet new console -o demo && cd demo` 建最小工程。
311
- - **依赖坐标**:`dotnet add package OpenGIS.Esri.Geometry.Core --version 1.0.9`(NuGet 最新 1.0.9,2026-09-21),需要 `System.Text.Json` 转换器时再装 `OpenGIS.Esri.Geometry.Json`;还原失败报 `NU1101` 说明源或版本不可用,报告“依赖不可下载”,不要自己编版本号。
312
- - **验证产物**:最小控制台程序断言三件事——`GeometryEngine.GeometryFromWkt` → `GeometryToWkt` 往返、`GeometryEngine.Contains(polygon, point)` 返回 true、`GeometryEngine.Buffer(point, 5.0).GetEnvelope()` 为 (XMin=5,YMin=15,XMax=15,YMax=25),再 `dotnet run` 看实际输出;`dotnet build` 成功不代表几何结果正确。
313
- - **构建与测试**:`dotnet build` 编译、`dotnet test` 跑 xUnit、`dotnet run --project samples/OpenGIS.Esri.Geometry.Samples` 跑示例(需在仓库 checkout 内,且该路径存在);输出在 `bin/`、`obj/`,不要提交。
314
- - **编译期陷阱**:`Polygon.AddRing` 必须闭合(首尾点相同)否则面积/包含判断异常;集合运算返回 `Geometry` 基类,要按 `Point`/`Polygon` 转型后再用;容差 `GeometryConstants.DefaultTolerance`(1e-10)是内部常量,无法外部调整。
315
- - **大地测量前提**:`GeodesicDistance`/`GeodesicArea` 基于 WGS84(Vincenty),输入必须是经纬度;对投影坐标(如 EPSG:3857 米制)调用会得到无意义结果。
316
- - **安全与权限**:`dotnet restore` 需访问 NuGet 源,离线时先确认本地缓存;修改全局 `NuGet.config`、安装 SDK 或写入系统目录前先征得用户同意,命令输出里不要回显私有源凭据。
317
-
318
350
  ## 常见问题
319
351
 
320
352
  | 问题 | 解决 |
321
353
  |------|------|
322
354
  | NuGet 安装后找不到命名空间 | 同时安装 `OpenGIS.Esri.Geometry.Core` 与(可选)`OpenGIS.Esri.Geometry.Json`;命名空间为 `OpenGIS.Esri.Geometry.Core.*` |
323
- | Polygon 面积 / 包含判断异常 | 环必须闭合(首尾点相同),可先用 `GeometryEngine.Simplify` 修复 |
324
- | 浮点坐标比较误差 | 内部容差 `GeometryConstants.DefaultTolerance`(1e-10),为内部常量、不可外部配置 |
355
+ | Polygon 面积 / 包含判断异常 | 环必须闭合(首尾点相同);注意 `IsValid()` 对自相交环较宽松,可能返回 true |
356
+ | `Simplify` 抛 `ArgumentException: Tolerance must be positive` | 容差必须为正,不能传 `0.0`;`Simplify` 只抽稀,不修复自相交 |
357
+ | 浮点坐标比较误差 | 内部容差 `GeometryConstants.DefaultTolerance`(1e-10),为内部常量、不可外部配置;面积等断言用近似比较 |
325
358
  | 集合运算返回值类型不符预期 | 返回 `Geometry` 基类,需按实际类型做类型转换后使用 |
326
359
  | 无法 `new` 算子实例 | 所有 Operator 类通过 `Instance` 属性获取 Lazy 单例 |
327
360
  | 修改 `GetRing()` / `GetPath()` 结果报错 | 返回 `IReadOnlyList<Point>` 只读视图,需要复制后修改 |
328
361
  | `GeodesicDistance` 结果异常 | 基于 WGS84(Vincenty 公式),输入必须是经纬度坐标;`GeodesicArea` 使用球面超量公式 |
329
362
  | GeoJSON 导出类型与预期不符 | 单路径 Polyline 导出为 `LineString`,多路径导出为 `MultiLineString`;Envelope 导出为 `Polygon` |
330
363
 
364
+ ## AI 使用建议
365
+
366
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/geometry-types.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
367
+ - **执行环境**:先 `dotnet --version`(库目标 `netstandard2.0`,可被 net6/net8/net9/net10 引用);Windows 上用 PowerShell 执行 `dotnet` 命令,`dotnet new console -o demo && cd demo` 建最小工程。
368
+ - **依赖坐标**:`dotnet add package OpenGIS.Esri.Geometry.Core --version 1.0.9`(NuGet 最新 1.0.9,2026-09-21),需要 `System.Text.Json` 转换器时再装 `OpenGIS.Esri.Geometry.Json`;还原失败报 `NU1101` 说明源或版本不可用,报告“依赖不可下载”,不要自己编版本号。
369
+ - **验证产物**:最小控制台程序断言三件事——`GeometryEngine.GeometryFromWkt` → `GeometryToWkt` 往返、`GeometryEngine.Contains(polygon, point)` 返回 true、`GeometryEngine.Buffer(point, 5.0).GetEnvelope()` 为 (XMin=5,YMin=15,XMax=15,YMax=25),再 `dotnet run` 看实际输出;`dotnet build` 成功不代表几何结果正确。
370
+ - **构建与测试**:`dotnet build` 编译、`dotnet test` 跑 xUnit、`dotnet run --project samples/OpenGIS.Esri.Geometry.Samples` 跑示例(需在仓库 checkout 内,且该路径存在);输出在 `bin/`、`obj/`,不要提交。
371
+ - **编译期陷阱**:`Polygon.AddRing` 必须闭合(首尾点相同)否则面积/包含判断异常;集合运算返回 `Geometry` 基类,要按 `Point`/`Polygon` 转型后再用;容差 `GeometryConstants.DefaultTolerance`(1e-10)是内部常量,无法外部调整。
372
+ - **大地测量前提**:`GeodesicDistance`/`GeodesicArea` 基于 WGS84(Vincenty),输入必须是经纬度;对投影坐标(如 EPSG:3857 米制)调用会得到无意义结果。
373
+ - **安全与权限**:`dotnet restore` 需访问 NuGet 源,离线时先确认本地缓存;修改全局 `NuGet.config`、安装 SDK 或写入系统目录前先征得用户同意,命令输出里不要回显私有源凭据。
374
+
331
375
  ## 相关技能
332
376
 
333
377
  - **nettopologysuite** — .NET JTS 移植(几何计算核心):[../nettopologysuite/SKILL.md](../nettopologysuite/SKILL.md)
@@ -0,0 +1,347 @@
1
+ ---
2
+ name: geonode
3
+ description: "Use when deploying or automating GeoNode 5.1.1 — docker compose with create-envfile.py, geonode/geonode:5.1.1 image, django4geonode logs, /api/v2/resources and /api/v2/uploads/upload (action=upload|replace|upsert|create), OGC WMS/WFS links from resource.links[], geonode-project customization; also for 502 after compose up, 'GeoNode has no attribute' after upgrade, and upload 401/403 with Basic vs Bearer auth."
4
+ tags:
5
+ - geonode
6
+ - gis
7
+ - django
8
+ - python
9
+ - docker
10
+ - postgis
11
+ - geoserver
12
+ - rest-api
13
+ - metadata
14
+ - webgis
15
+ ---
16
+
17
+ > **项目地址:** <https://github.com/GeoNode/geonode>
18
+ >
19
+ > **官方文档:** <https://docs.geonode.org/en/latest/>
20
+ >
21
+ > **演示站:** <https://development.demo.geonode.org>
22
+ >
23
+ > **最新版本:** 5.1.1(GitHub Release 与 PyPI 均为 5.1.1,截至 2026-10);官方镜像 `geonode/geonode:5.1.1`
24
+ >
25
+ > **运行环境:** Python >= 3.10(PyPI 元数据),依赖 Django 5.2.18、psycopg2 2.9.13、Celery 5.6.3
26
+ >
27
+ > **许可证:** GPL-2.0-or-later
28
+
29
+ ## 概述
30
+
31
+ GeoNode 是一个基于 Django 的地理空间内容管理系统(CMS),把数据发布、元数据编目、地图制作与权限管理整合到一个 Web 平台。它不是单个 GIS 组件,而是把成熟开源组件编排成一套可运营的服务。
32
+
33
+ 核心构成:
34
+
35
+ - **Django 应用**:资源(dataset / map / document / geostory / dashboard)、用户与权限、元数据
36
+ - **GeoServer**:实际提供 WMS / WFS / WCS 服务与样式渲染
37
+ - **PostgreSQL + PostGIS**:元数据库 `geonode` 与数据库 `geonode_data` 两个库
38
+ - **pycsw**:CSW 目录服务与 ISO 元数据发布
39
+ - **Celery + Redis**:异步任务(上传解析、缩略图、元数据更新)
40
+ - **uWSGI + nginx(或仅 Django 开发服务器)**:对外服务与静态资源
41
+ - **REST API v2**:`/api/v2/*`,资源检索、上传、元数据编辑;旧版 Tastypie 接口仍在 `/api/*`
42
+
43
+ 适合的场景是"要给一个组织提供数据门户":统一登录、按用户/组授权、自动生成 OGC 服务与元数据记录。若只需要发几个 WMS 图层,GeoServer 单独部署更轻。
44
+
45
+ ## 环境准备
46
+
47
+ ### 方式一:Docker Compose(推荐,官方主路径)
48
+
49
+ ```bash
50
+ git clone https://github.com/GeoNode/geonode.git
51
+ cd geonode
52
+
53
+ # 生成 .env(随机密码、OAuth2 client、站点地址)
54
+ python create-envfile.py --env_type dev --hostname localhost
55
+
56
+ # 构建并启动
57
+ docker compose build
58
+ docker compose up -d
59
+ ```
60
+
61
+ `create-envfile.py` 的关键参数:
62
+
63
+ | 参数 | 作用 |
64
+ |------|------|
65
+ | `--env_type` | `dev`(DEBUG 开、无 SSL)、`test`(自签证书)、`prod`(申请 Let's Encrypt 证书) |
66
+ | `--hostname` | 对外访问域名/主机名,默认 `localhost` |
67
+ | `--email` | 管理员邮箱(`prod` 下用于证书签发) |
68
+ | `--geonodepwd` / `--geoserverpwd` | GeoNode / GeoServer 管理员密码;留空则随机生成并写入 .env |
69
+ | `--pgpwd` / `--dbpwd` / `--geodbpwd` | PostgreSQL 超级用户、GeoNode 库用户、数据库用户密码 |
70
+ | `--clientid` / `--clientsecret` | GeoServer 侧 OAuth2 客户端凭据 |
71
+
72
+ 启动后访问 `http://localhost`,管理员账号为 `admin`,密码见生成的 `.env`(若未显式传入)。
73
+
74
+ ```bash
75
+ # 跟踪初始化日志(迁移、fixtures、静态文件、词表加载)
76
+ docker compose logs -f django
77
+
78
+ # 或直接进容器
79
+ docker exec -it django4geonode /bin/bash
80
+ ```
81
+
82
+ 日志里出现 `Executing UWSGI server uwsgi --ini /usr/src/app/uwsgi.ini` 即表示应用已就绪。
83
+
84
+ ### 方式二:预构建镜像
85
+
86
+ ```bash
87
+ docker run -d --name geonode -p 8000:8000 geonode/geonode:5.1.1
88
+ ```
89
+
90
+ 单容器镜像适合快速试跑;缺少 PostGIS、GeoServer、Redis 的编排时功能不完整,正式部署仍应用 compose。
91
+
92
+ ### 方式三:裸机安装(Ubuntu 24.04)
93
+
94
+ ```bash
95
+ # 1) 虚拟环境
96
+ python3 -m venv ~/.virtualenvs/geonode
97
+ source ~/.virtualenvs/geonode/bin/activate
98
+
99
+ # 2) 源码与依赖
100
+ sudo mkdir -p /opt/geonode
101
+ sudo chown -R "$USER":www-data /opt/geonode
102
+ cd /opt && git clone https://github.com/GeoNode/geonode.git -b 5.1.x geonode
103
+ cd /opt/geonode
104
+ pip install -r requirements.txt --upgrade
105
+ pip install -e . --upgrade
106
+ ```
107
+
108
+ 分支要与版本对应:5.1.1 对应 `5.1.x`(旧文档里的 `5.0.x` 是上一个系列)。
109
+
110
+ ```bash
111
+ # 3) PostGIS 两个库
112
+ sudo apt install -y postgresql-15 postgresql-15-postgis-3 postgresql-15-postgis-3-scripts
113
+ sudo -u postgres createuser -P geonode
114
+ sudo -u postgres createdb -O geonode geonode
115
+ sudo -u postgres createdb -O geonode geonode_data
116
+
117
+ for db in geonode geonode_data; do
118
+ sudo -u postgres psql -d "$db" -c 'CREATE EXTENSION postgis;'
119
+ sudo -u postgres psql -d "$db" -c 'GRANT ALL ON geometry_columns TO PUBLIC;'
120
+ sudo -u postgres psql -d "$db" -c 'GRANT ALL ON spatial_ref_sys TO PUBLIC;'
121
+ done
122
+ ```
123
+
124
+ ```bash
125
+ # 4) 初始化应用
126
+ cd /opt/geonode
127
+ export DJANGO_SETTINGS_MODULE=geonode.settings
128
+ python manage.py migrate
129
+ python manage.py collectstatic --noinput
130
+ python manage.py createsuperuser
131
+ python manage.py runserver 0.0.0.0:8000
132
+ ```
133
+
134
+ 裸机路径还需要单独装 GeoServer 并配置 OAuth2 代理,官方文档的 bare installation 章节会逐步给出;不想折腾就用 Docker。
135
+
136
+ ### 验证
137
+
138
+ ```bash
139
+ # 版本
140
+ curl -s http://localhost/version.txt
141
+
142
+ # API 是否可用(公开资源无需认证)
143
+ curl -s "http://localhost/api/v2/resources?page_size=1" | head -c 300
144
+
145
+ # OGC 服务是否由 GeoServer 提供
146
+ curl -s "http://localhost/geoserver/web/" -o /dev/null -w "%{http_code}\n"
147
+ ```
148
+
149
+ ## 核心 API
150
+
151
+ ### 认证
152
+
153
+ | 方式 | 请求头 | 说明 |
154
+ |------|--------|------|
155
+ | 匿名 | 无 | 只能读公开资源 |
156
+ | Basic | `Authorization: Basic base64(user:pass)` | 最简单,脚本首选 |
157
+ | Bearer | `Authorization: Bearer <token>` | 由 OAuth2 提供方 `/o/token/` 颁发 |
158
+
159
+ ```bash
160
+ # 用 OAuth2 换取 token(client 凭据来自 .env 的 clientid / clientsecret)
161
+ curl -s -X POST http://localhost/o/token/ \
162
+ -d "grant_type=password" \
163
+ -d "username=admin" -d "password=<admin-password>" \
164
+ -d "client_id=<clientid>" -d "client_secret=<clientsecret>"
165
+ ```
166
+
167
+ ### 资源检索
168
+
169
+ | 目的 | 请求 |
170
+ |------|------|
171
+ | 列出全部资源 | `GET /api/v2/resources` |
172
+ | 资源详情 | `GET /api/v2/resources/{pk}` |
173
+ | 按类型过滤 | `/api/v2/resources?filter{resource_type}=dataset` |
174
+ | 按子类型过滤 | `/api/v2/resources?filter{subtype}=vector` |
175
+ | 按关键词/分类/区域 | `?filter{keywords.name}=...`、`?filter{category.identifier}=...`、`?filter{regions.name}=...` |
176
+ | 按所有者 | `?filter{owner.username}=...` |
177
+ | 全文搜索 | `?search=text&search_fields=title&search_fields=abstract` |
178
+ | 只看已发布/已审核 | `?filter{is_published}=true`、`?filter{is_approved}=true` |
179
+ | 按范围 | `?extent=-180,-90,180,90` |
180
+
181
+ `filter{...}` 支持 `.in` 与 `.icontains` 后缀,例如 `?filter{regions.name.icontains}=global`。
182
+
183
+ ```bash
184
+ curl -s "http://localhost/api/v2/resources?filter{resource_type}=dataset&page_size=5" \
185
+ -H "Authorization: Basic $(printf 'admin:secret' | base64)"
186
+ ```
187
+
188
+ ### 上传与更新数据集
189
+
190
+ 统一入口 `POST /api/v2/uploads/upload`(成功返回 201),由 `action` 参数决定行为:
191
+
192
+ | action | 用途 | 额外必填 |
193
+ |--------|------|----------|
194
+ | `upload`(默认) | 上传新数据集 | 无 |
195
+ | `replace` | 用新数据替换已有数据集 | `resource_pk` |
196
+ | `upsert` | 按关键字段合并(存在则更新,否则插入) | `resource_pk`(可选 `upsert_key`,默认 `fid`) |
197
+ | `create` | 建空数据集(不上传文件) | `title`、`geom`、`attributes` |
198
+ | `resource_style_upload` | 给已有数据集应用 SLD 样式 | `resource_pk` + SLD 文件 |
199
+ | `resource_metadata_upload` | 给已有数据集应用 XML 元数据 | `resource_pk` + XML 文件 |
200
+
201
+ 支持的格式:Shapefile(zip)、GeoTIFF、CSV、ZIP 归档、XML 元数据、SLD。
202
+
203
+ ```python
204
+ import requests
205
+
206
+ url = "http://localhost/api/v2/uploads/upload"
207
+ headers = {"Authorization": "Basic <base64(admin:password)>"}
208
+ with open("data/BoulderCityLimits.zip", "rb") as fh:
209
+ files = [("base_file", ("BoulderCityLimits.zip", fh, "application/zip"))]
210
+ print(requests.post(url, headers=headers, data={"action": "upload"}, files=files).status_code)
211
+ ```
212
+
213
+ ### 元数据与下载
214
+
215
+ | 目的 | 请求 / 字段 |
216
+ |------|-------------|
217
+ | 数据集元数据 | `PUT /api/v2/datasets/{id}/metadata` |
218
+ | 默认格式下载 | `resource.download_url`(矢量转 Shapefile,栅格转 GeoTIFF) |
219
+ | 元数据文档链接 | `resource.links[]` 中 `link_type == "metadata"` 的条目 |
220
+ | OGC 服务地址 | `links[]` 中 `link_type` 为 `OGC:WMS` / `OGC:WFS` / `OGC:WCS` |
221
+ | OGC 图层名 | `resource.alternate`(形如 `workspace:layername`) |
222
+ | 嵌入 iframe | `resource.embed_url` |
223
+
224
+ ### 管理命令与运维
225
+
226
+ ```bash
227
+ # 容器内的 Django 管理命令
228
+ docker compose exec django python manage.py migrate
229
+ docker compose exec django python manage.py createsuperuser
230
+ docker compose exec django python manage.py collectstatic --noinput
231
+
232
+ # 备份 / 恢复
233
+ docker compose exec db pg_dump -U postgres geonode > geonode.sql
234
+ docker compose exec db pg_dump -U postgres geonode_data > geonode_data.sql
235
+ ```
236
+
237
+ `tasks.py`(Invoke 任务)提供了 `update`、`migrations`、`statics`、`fixtures`、`updateadmin` 等编排步骤,compose 的入口脚本在首次启动时会按顺序调它们。
238
+
239
+ ## 典型工作流:上传 Shapefile → 补元数据 → 取 OGC 服务
240
+
241
+ 目标:把一个 Shapefile 发布成带元数据的矢量数据集,并拿到可直接给前端用的 WMS 地址。
242
+
243
+ **步骤 1:上传**
244
+
245
+ ```bash
246
+ BASE=http://localhost
247
+ AUTH="Authorization: Basic $(printf 'admin:<password>' | base64)"
248
+
249
+ curl -s -X POST "$BASE/api/v2/uploads/upload" \
250
+ -H "$AUTH" \
251
+ -F "action=upload" \
252
+ -F "base_file=@data/roads.zip" \
253
+ -o upload.json -w "%{http_code}\n"
254
+ ```
255
+
256
+ 返回体里带执行请求 id;上传解析是异步的,稍等片刻再查资源列表。
257
+
258
+ **步骤 2:确认资源已建好**
259
+
260
+ ```bash
261
+ curl -s "$BASE/api/v2/resources?search=roads&page_size=5" -H "$AUTH" \
262
+ | python -c "import json,sys;d=json.load(sys.stdin);print([(r['pk'], r['title'], r['subtype']) for r in d['resources']])"
263
+ ```
264
+
265
+ **步骤 3:补元数据(标题、摘要、关键词、许可)**
266
+
267
+ ```bash
268
+ curl -s -X PATCH "$BASE/api/v2/resources/<pk>" -H "$AUTH" \
269
+ -H "Content-Type: application/json" \
270
+ -d '{"title": "城市道路", "abstract": "2026 年道路中心线", "is_published": true}'
271
+ ```
272
+
273
+ 需要完整 ISO 元数据时,改用 `action=resource_metadata_upload` 或 `PUT /api/v2/datasets/{id}/metadata`。若上面的 `PATCH` 在某个部署上返回 405,改用 `PUT` 全量提交,或直接在后台 `/admin/` 的资源编辑页修改。
274
+
275
+ **步骤 4:取 OGC 地址并验证**
276
+
277
+ ```python
278
+ import requests
279
+
280
+ r = requests.get("http://localhost/api/v2/resources/<pk>",
281
+ headers={"Authorization": "Basic <base64>"}).json()
282
+
283
+ wms = next(l["url"] for l in r["links"] if l["link_type"] == "OGC:WMS")
284
+ layer = r["alternate"] # 形如 workspace:roads
285
+ print(wms, layer)
286
+ print(requests.get(wms, params={
287
+ "service": "WMS", "version": "1.3.0", "request": "GetMap",
288
+ "layers": layer, "crs": "EPSG:4326",
289
+ "bbox": "116.0,39.5,116.6,40.1", "width": "512", "height": "512",
290
+ "format": "image/png",
291
+ }).status_code)
292
+ ```
293
+
294
+ 期望拿到 200 与 PNG 字节;返回 404 通常是图层名(`alternate`)写错,返回 400 多半是 bbox 顺序或 CRS 不匹配。
295
+
296
+ **步骤 5:验收**
297
+
298
+ - 后台 `/admin/` 能看到该数据集,状态为已发布
299
+ - `GetCapabilities` 里能找到 `alternate` 对应的图层
300
+ - `download_url` 能下载到 Shapefile
301
+
302
+ ## 最佳实践
303
+
304
+ 1. **用 `--env_type dev` 试跑,正式环境再上 `prod`**:`prod` 会尝试申请 Let's Encrypt 证书,域名不可达时会卡住或失败。
305
+ 2. **两个数据库都要建 PostGIS**:`geonode` 存元数据、`geonode_data` 存业务数据,漏建任何一个都会在上传时报扩展错误。
306
+ 3. **自定义就走 geonode-project**:不要直接改核心源码;用 <https://github.com/GeoNode/geonode-project> 模板生成项目,升级时只合并自己的改动。
307
+ 4. **上传走异步,别立刻查**:上传接口返回的是执行请求 id,解析完成前资源可能还不完整;轮询 `/api/v2/resources` 或用后台任务状态确认。
308
+ 5. **批量更新用 upsert**:`action=replace` 会整体替换数据,`action=upsert` 才能按 `upsert_key` 合并增量。
309
+ 6. **OGC 地址从 API 取,不要手拼**:`links[]` 与 `alternate` 是权威来源,手拼工作区名在改名后会失效。
310
+ 7. **备份两个库**:`geonode` 与 `geonode_data` 必须同时备份,只备份其一恢复后会缺资源定义或数据表。
311
+
312
+ ## 常见问题
313
+
314
+ | 问题 | 原因 | 解决方案 |
315
+ |------|------|---------|
316
+ | `docker compose up` 后页面 502 | Django 容器还在迁移/收集静态文件,或启动失败 | `docker compose logs -f django` 看到 uWSGI 启动行为止;失败时看首个 Traceback,常见是数据库连不上 |
317
+ | 上传接口返回 401 | 缺少或错误的 Authorization 头 | 用 Basic 或 Bearer;确认 base64 编码的是 `用户名:密码` 且未带多余空格 |
318
+ | 上传返回 403 | 用户没有 `base.add_resourcebase` 权限 | 换管理员账号,或在后台给该用户/组授予上传权限 |
319
+ | 管理员密码不知道 | `create-envfile.py` 随机生成了密码 | 查 `.env` 里的 `ADMIN_PASSWORD`/`GEONODE_ADMIN_PASSWORD`;已丢失则进容器 `python manage.py changepassword admin` |
320
+ | 上传后资源一直是"处理中" | Celery worker 未运行或 Redis 不可达 | `docker compose ps` 确认 celery/redis 状态;看 worker 日志 |
321
+ | GetMap 返回空白图 | 图层没有数据范围,或 CRS/bbox 不匹配 | 在后台重新计算边界(`UpdateLayerStatistics` 类似操作),并用 `resource.bbox` 核对 |
322
+ | 升级后报错 `AttributeError` / 表不存在 | 未执行迁移 | `docker compose exec django python manage.py migrate`;自定义项目先合并上游 settings 变更 |
323
+ | `docs.geonode.org` 某些深链 404 | 文档站路径随版本调整 | 从首页导航进入;或直接读仓库 `docs/src/` 下对应 Markdown |
324
+ | 裸机安装 GeoServer 登录失败 | OAuth2 client 与 GeoNode 不一致 | 按官方 OAuth2 章节核对 `clientid/clientsecret` 与 GeoServer 过滤器配置 |
325
+
326
+ ## AI 使用建议
327
+
328
+ - **先确认版本与入口**:`curl -s http://localhost/version.txt` 确认 5.1.1;Docker 部署优先用 `docker compose exec` 而不是宿主机的 `manage.py`,避免环境错位。
329
+ - **API 用 `/api/v2/`**:旧 Tastypie 的 `/api/*` 仍在,但新代码一律用 `/api/v2/resources` 与 `/api/v2/uploads/upload`;两者返回结构不同,不要混用。
330
+ - **认证信息不要进日志**:用环境变量传 `Authorization`,示例里出现的 `<base64>` 必须替换,不要把真实凭据写进脚本或报告。
331
+ - **验证产物**:上传后回读资源详情,核对 `subtype`、`alternate`、`links[]` 与 `download_url`,再对 WMS 发一次 `GetMap`;只看 201 响应不构成"发布成功"。
332
+ - **写操作确认**:`action=replace`、删除资源、`migrate`、恢复数据库都不可逆;执行前备份两个库并确认 `resource_pk`。
333
+
334
+ ## 相关技能
335
+
336
+ - **geoserver** — GeoNode 背后的 OGC 服务引擎:[../geoserver/SKILL.md](../geoserver/SKILL.md)
337
+ - **geoserver-rest-api** — 直接操作 GeoServer 的 REST 接口:[../geoserver-rest-api/SKILL.md](../geoserver-rest-api/SKILL.md)
338
+ - **postgis** — 元数据库与数据库的底层扩展:[../postgis/SKILL.md](../postgis/SKILL.md)
339
+ - **gdal** — 上传前的数据准备与格式转换:[../gdal/SKILL.md](../gdal/SKILL.md)
340
+ - **opengis-all** — 全流程 GIS 索引:[../opengis-all/SKILL.md](../opengis-all/SKILL.md)
341
+
342
+ ## 参考资源
343
+ - 官方文档:<https://docs.geonode.org/en/latest/>
344
+ - 快速安装:<https://docs.geonode.org/en/latest/overview/quick/>
345
+ - API 使用指南:<https://github.com/GeoNode/geonode/blob/master/docs/src/development/api.md>
346
+ - 项目模板(自定义部署):<https://github.com/GeoNode/geonode-project>
347
+ - 演示站:<https://demo.geonode.org>
@@ -18,7 +18,7 @@ tags:
18
18
  >
19
19
  > **官网:** <https://geopandas.org>
20
20
  >
21
- > **最新版本:** 1.2.0(截至2026-10,PyPI)
21
+ > **最新版本:** 1.2.0(截至 2026-10,PyPI)
22
22
  >
23
23
  > **许可证:** BSD-3-Clause
24
24
 
@@ -342,6 +342,18 @@ m = gdf.explore(column="population", cmap="viridis",
342
342
 
343
343
  ---
344
344
 
345
+ ## 性能提示
346
+
347
+ - **GeoParquet** 比 Shapefile/GeoJSON 读写快 5-10 倍,优先使用
348
+ - **空间索引** `.sindex` 自动构建 STRtree,`query()` 和 `nearest()` 可大幅加速空间查询
349
+ - **矩形裁剪** `clip_by_rect()` 或 `clip(gdf, (xmin,ymin,xmax,ymax))` 比多边形裁剪快
350
+ - **`pyogrio` 引擎**(默认)比 `fiona` 快 2-5 倍
351
+ - 大数据集用 `read_file(rows=slice(0, 1000))` 先预览
352
+ - `dissolve()` 使用 `method="coverage"` 对已知不重叠的多边形更快
353
+ - 避免逐行循环几何操作,使用向量化方法(如 `buffer()`, `intersection()` 等)
354
+
355
+ ---
356
+
345
357
  ## 常见问题
346
358
 
347
359
  | 问题 | 原因 | 解决方案 |
@@ -356,14 +368,14 @@ m = gdf.explore(column="population", cmap="viridis",
356
368
  | `DriverError` 无法写入 | 驱动不支持或文件被占用 | 检查驱动名拼写、关闭已打开的文件 |
357
369
  | `align=True` 导致意外 NaN | 二元操作默认按索引对齐 | 传入 `align=False` 或重置索引 |
358
370
 
359
- ## DeepSeek Harness 使用建议
371
+ ## AI 使用建议
360
372
 
361
- - **加载与引用**:用 `skill("geopandas")` 加载(用户也可输入 `/geopandas`);`reference/core-api.md` 按需 `read`,路径相对加载结果中的 Base directory;技能目录只读,脚本与产物写到会话工作区。
362
- - **执行环境**:命令交给 dsh 的 shell 工具(Windows 用 `pwsh`,仅暴露 `run_code` 的会话在 `tools.pwsh` 里跑);不要假设 `python` 是 QGIS/GDAL 自带的解释器,先 `python -c "import sys; print(sys.executable, sys.version)"`。
373
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/core-api.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
374
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell);不要假设 `python` 是 QGIS/GDAL 自带的解释器,先 `python -c "import sys; print(sys.executable, sys.version)"`。
363
375
  - **先探测版本**:`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}`),回答时说明差异而不是硬写。
364
376
  - **检查依赖后端**:`python -c "import pyogrio, pyproj; print(pyogrio.__version__, pyproj.__version__, pyproj.datadir.get_data_dir())"`;PROJ 数据目录缺失时 `to_crs("EPSG:3857")` 抛 `CRSError: Invalid projection`,装 `pyproj`/`pyogrio` 前先征得用户同意。
365
377
  - **验证产物(必做)**:写完立即重开核对,`gdf = gpd.read_file("out.gpkg", layer="result"); print(gdf.crs, len(gdf), gdf.is_valid.all(), gdf.total_bounds)`,并确认面积/长度是在投影坐标系下算的。
366
- - **落图后看图**:`ax = gdf.plot(column="pop", legend=True, figsize=(12, 8)); ax.figure.savefig("map.png", dpi=100)`(需 matplotlib),再用 `read_image("map.png")` 检查范围、图例与空几何,不要只凭退出码报告成功。
378
+ - **落图后看图**:`ax = gdf.plot(column="pop", legend=True, figsize=(12, 8)); ax.figure.savefig("map.png", dpi=100)`(需 matplotlib),再打开该 PNG 检查范围、图例与空几何(能读图的环境可直接查看截图),不要只凭退出码报告成功。
367
379
  - **典型误操**:`set_crs()` 只标记不改坐标、`to_file()` 默认整表覆盖、`to_postgis(if_exists="replace")` 会删表重建——执行前确认目标路径/表名,Shapefile 字段名超 10 字符会被截断,改用 `.gpkg`。
368
380
  - **安全**:数据库连接串里的密码不要回显在命令输出里;`pip install geopandas[all]`、写入系统目录或覆盖生产数据前先得到用户确认。
369
381
 
@@ -375,16 +387,6 @@ m = gdf.explore(column="population", cmap="viridis",
375
387
  - **postgis** — 空间数据库:[../postgis/SKILL.md](../postgis/SKILL.md)
376
388
  - **geopipe-agent** — AI 原生分析流水线:[../geopipe-agent/SKILL.md](../geopipe-agent/SKILL.md)
377
389
 
378
- ## 性能提示
379
-
380
- - **GeoParquet** 比 Shapefile/GeoJSON 读写快 5-10 倍,优先使用
381
- - **空间索引** `.sindex` 自动构建 STRtree,`query()` 和 `nearest()` 可大幅加速空间查询
382
- - **矩形裁剪** `clip_by_rect()` 或 `clip(gdf, (xmin,ymin,xmax,ymax))` 比多边形裁剪快
383
- - **`pyogrio` 引擎**(默认)比 `fiona` 快 2-5 倍
384
- - 大数据集用 `read_file(rows=slice(0, 1000))` 先预览
385
- - `dissolve()` 使用 `method="coverage"` 对已知不重叠的多边形更快
386
- - 避免逐行循环几何操作,使用向量化方法(如 `buffer()`, `intersection()` 等)
387
-
388
390
  ---
389
391
 
390
392
  ## 参考资源
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: geopipe-agent
3
- description: "Use when building YAML GIS pipelines with GeoPipeAgent — geopipe-agent validate/run, io.read_vector → vector.buffer → io.write_vector chains, 33 built-in steps, qc.geometry_validity/attribute_completeness/topology, native_python|qgis_process|gdal_cli backends, $step.output refs; also for validate \"not registered\" errors, silent when-condition skips, and resolve/knowledge capability gaps. 0.1.0, source install only (not on PyPI)."
3
+ description: "Use when building YAML GIS pipelines with GeoPipeAgent — geopipe-agent validate/run, io.read_vector → vector.buffer → io.write_vector chains, 36 built-in steps (33 analysis + 3 passthrough), qc.geometry_validity/attribute_completeness/topology, native_python|qgis_process|gdal_cli backends, $step.output refs; also for validate "not registered" errors, silent when-condition skips, and resolve/knowledge gaps. 0.1.0, source install only (not on PyPI)."
4
4
  tags:
5
5
  - gis
6
6
  - agent
@@ -16,7 +16,9 @@ tags:
16
16
 
17
17
  > **项目地址:** <https://github.com/znlgis/GeoPipeAgent>
18
18
  >
19
- > **最新版本:** 0.1.0(截至2026-10,源码 `pyproject.toml`;发布包名 `geopipe-agent` 尚未上传 PyPI,需从源码安装)
19
+ > **文档:** <https://github.com/znlgis/GeoPipeAgent#readme>(README + `cookbook/` 示例 + `docs/`)
20
+ >
21
+ > **版本:** 0.1.0(截至 2026-10,实测 `pyproject.toml`;`geopipe-agent` 未发布到 PyPI,只能源码安装)
20
22
  >
21
23
  > **许可证:** MIT
22
24
 
@@ -27,7 +29,7 @@ GeoPipeAgent 是一个 **AI 原生的 GIS 分析流水线引擎**。核心理念
27
29
  **核心能力:**
28
30
 
29
31
  - **声明式流水线**:YAML 定义分析步骤,AI 友好
30
- - **丰富步骤库**:33 个内置步骤,覆盖矢量分析、栅格分析、网络分析、空间聚类、数据质检
32
+ - **步骤库**:33 个内置分析步骤(IO 4、矢量 7、栅格 5、空间分析 4、网络 3、质检 10)+ 3 个零代码直通步骤(`gdal.cli` / `qgis.algorithm` / `http.request`),README 合计 36 个
31
33
  - **多后端支持**:7 种后端可切换(native_python / gdal_cli / gdal_python / qgis_process / pyqgis / generic_cli / curl_api),按环境自动检测可用性
32
34
  - **质检框架**:10 种 QC 检查,支持错误/警告/信息三级
33
35
  - **结构化报告**:JSON 输出,含统计信息和 QC 汇总
@@ -247,16 +249,18 @@ QC 步骤遵循 **「检查即透传」** 模式:输入数据原样通过为 `
247
249
  | 网络分析 | `io.read_vector → network.shortest_path → network.service_area → io.write_vector ×2` |
248
250
  | 空间聚类 + 热力图 | `io.read_vector → analysis.cluster(dbscan) → analysis.heatmap → io.write_vector + io.write_raster` |
249
251
 
250
- ## DeepSeek Harness 使用建议
252
+ ## 常见问题
251
253
 
252
- - **加载与引用**:用 `skill("geopipe-agent")` 加载(用户也可输入 `/geopipe-agent`);`reference/steps-reference.md`、`pipeline-schema.md`、`workflows.md`、`self-extension.md` 按需 `read`,路径相对加载结果中的 Base directory;技能目录只读,YAML 与输出写到会话工作区。
253
- - **执行环境**:命令交给 dsh 的 shell 工具(Windows 用 `pwsh`);`python` 可能指向 QGIS/GDAL 自带解释器,建议在工作区建独立 venv 后 `pip install -e .`,避免污染系统环境。
254
- - **源码安装(未上 PyPI)**:`git clone https://github.com/znlgis/GeoPipeAgent.git && pip install -e ".[analysis,network]"`;验证 `geopipe-agent --help`、`geopipe-agent list-steps --category qc`、`pip show geopipe-agent | Select-String Version`。不要写 `pip install geopipe-agent`——PyPI 上还没有这个包。
255
- - **先探测能力**:`geopipe-agent backends` 看当前环境可用后端(默认 `native_python`),`geopipe-agent list-steps --format json` 拿真实步骤 ID;`validate` 报 `not registered` 时先用 `geopipe-agent resolve "<需求>"` 与 `knowledge search`,不要猜参数。
256
- - **验证产物**:`geopipe-agent validate pipeline.yaml` 通过后再 `run pipeline.yaml`,检查 JSON 报告里的 `qc_summary` 与各步骤统计,随后重开输出文件核对(`geopipe-agent info output/result.geojson`,装了 GDAL 时也可 `ogrinfo -so output/result.geojson result`),确认要素数与 CRS 而不是只看“执行成功”。
257
- - **典型误操**:步骤 ID 不能含点号,`$step_id` 必须由更早步骤提供,`when` 引用不存在的属性会按 false **静默跳过**;`backend:` 只有声明了 backends 的 6 个矢量步骤会读取,其余步骤写了也被忽略。
258
- - **性能与内存**:管道全程在内存中运行,超大栅格先 `raster.clip` 或 `io.read_raster` 只读所需波段;QC 步骤是“检查即透传”,`output` 就是输入,问题在 `$step.issues` / `issues_gdf`。
259
- - **安全与权限**:`network.geocode` 与 `curl_api`、`http.request` 会把数据发到外部服务,执行前确认是否允许出网并检查 `user_agent`/凭据;`pip install`、覆盖已有输出文件、批量改写数据前先征得用户同意。
254
+ | 问题 | 解决 |
255
+ |------|------|
256
+ | 步骤引用解析失败 | 检查步骤 ID 是否含点号,引用目标是否在当前步骤之前定义 |
257
+ | 管线执行超时 | 对大范围栅格先裁剪,减少数据量 |
258
+ | QC 步骤无输出 | QC 步骤透传输入数据,问题在 `$step.issues` 中,`output` 即输入 |
259
+ | 条件步骤未触发 | 检查 `when` 表达式语法,确保引用的 `$step.attr` 存在 |
260
+ | 后端不兼容 | `native_python` 和 `qgis_process` 后端参数可能不同,查阅 `list-steps` 确认 |
261
+ | `pip install geopipe-agent` 报 404 | 该包未上 PyPI:先 `git clone` 源码再 `pip install -e ".[analysis,network]"` |
262
+ | `analysis.*` / `network.*` 步骤报 ImportError | 缺可选依赖:`pip install -e ".[analysis,network]"`(analysis=scipy/scikit-learn/matplotlib,network=networkx/geopy) |
263
+ | `list-steps` 里找不到某步骤 | 直通步骤(`gdal.cli`/`qgis.algorithm`/`http.request`)与自定义 `@step` 需重新 `pip install -e .` 才会被 `pkgutil` 发现 |
260
264
 
261
265
  ---
262
266
 
@@ -271,15 +275,16 @@ QC 步骤遵循 **「检查即透传」** 模式:输入数据原样通过为 `
271
275
 
272
276
  ---
273
277
 
274
- ## 常见问题
278
+ ## AI 使用建议
275
279
 
276
- | 问题 | 解决 |
277
- |------|------|
278
- | 步骤引用解析失败 | 检查步骤 ID 是否含点号,引用目标是否在当前步骤之前定义 |
279
- | 管线执行超时 | 对大范围栅格先裁剪,减少数据量 |
280
- | QC 步骤无输出 | QC 步骤透传输入数据,问题在 `$step.issues` 中,`output` 即输入 |
281
- | 条件步骤未触发 | 检查 `when` 表达式语法,确保引用的 `$step.attr` 存在 |
282
- | 后端不兼容 | `native_python` 和 `qgis_process` 后端参数可能不同,查阅 `list-steps` 确认 |
280
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/backends.md`、`reference/knowledge.md`、`reference/pipeline-schema.md`、`reference/self-extension.md`、`reference/steps-reference.md`、`reference/workflows.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
281
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell);`python` 可能指向 QGIS/GDAL 自带解释器,建议在工作区建独立 venv 后 `pip install -e .`,避免污染系统环境。
282
+ - **源码安装(未上 PyPI)**:`git clone https://github.com/znlgis/GeoPipeAgent.git && pip install -e ".[analysis,network]"`;验证 `geopipe-agent --help`、`geopipe-agent list-steps --category qc`、`pip show geopipe-agent | Select-String Version`。不要写 `pip install geopipe-agent`——PyPI 上还没有这个包。
283
+ - **先探测能力**:`geopipe-agent backends` 看当前环境可用后端(默认 `native_python`),`geopipe-agent list-steps --format json` 拿真实步骤 ID;`validate` 报 `not registered` 时先用 `geopipe-agent resolve "<需求>"` 与 `knowledge search`,不要猜参数。
284
+ - **验证产物**:`geopipe-agent validate pipeline.yaml` 通过后再 `run pipeline.yaml`,检查 JSON 报告里的 `qc_summary` 与各步骤统计,随后重开输出文件核对(`geopipe-agent info output/result.geojson`,装了 GDAL 时也可 `ogrinfo -so output/result.geojson result`),确认要素数与 CRS 而不是只看“执行成功”。
285
+ - **典型误操**:步骤 ID 不能含点号,`$step_id` 必须由更早步骤提供,`when` 引用不存在的属性会按 false **静默跳过**;`backend:` 只有声明了 backends 的 6 个矢量步骤会读取,其余步骤写了也被忽略。
286
+ - **性能与内存**:管道全程在内存中运行,超大栅格先 `raster.clip` 或 `io.read_raster` 只读所需波段;QC 步骤是“检查即透传”,`output` 就是输入,问题在 `$step.issues` / `issues_gdf`。
287
+ - **安全与权限**:`network.geocode` 与 `curl_api`、`http.request` 会把数据发到外部服务,执行前确认是否允许出网并检查 `user_agent`/凭据;`pip install`、覆盖已有输出文件、批量改写数据前先征得用户同意。
283
288
 
284
289
  ---
285
290