@dsh-gis/dsh-opengis-skill 0.1.2 → 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 +71 -0
  2. package/README.md +79 -43
  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 +78 -29
  47. package/assets/deck-gl/SKILL.md +20 -20
  48. package/assets/duckdb-spatial/SKILL.md +370 -0
  49. package/assets/gdal/SKILL.md +50 -55
  50. package/assets/gdal-api/SKILL.md +12 -29
  51. package/assets/geolibre/SKILL.md +364 -0
  52. package/assets/geometry-api-java/SKILL.md +11 -19
  53. package/assets/geometry-api-net/SKILL.md +66 -29
  54. package/assets/geonode/SKILL.md +347 -0
  55. package/assets/geopandas/SKILL.md +22 -28
  56. package/assets/geopipe-agent/SKILL.md +25 -30
  57. package/assets/geoserver/SKILL.md +21 -24
  58. package/assets/geoserver-cloud/SKILL.md +23 -34
  59. package/assets/geoserver-rest-api/SKILL.md +18 -23
  60. package/assets/geotools/SKILL.md +13 -21
  61. package/assets/grass-gis/SKILL.md +19 -20
  62. package/assets/jts/SKILL.md +12 -17
  63. package/assets/kepler-gl/SKILL.md +313 -0
  64. package/assets/leaflet/SKILL.md +42 -17
  65. package/assets/mapbox-gl-js/SKILL.md +19 -18
  66. package/assets/mapserver/SKILL.md +18 -18
  67. package/assets/mapsui/SKILL.md +87 -58
  68. package/assets/nettopologysuite/SKILL.md +96 -27
  69. package/assets/opengis-all/SKILL.md +80 -292
  70. package/assets/opengis-all/reference/data-stages.md +262 -4
  71. package/assets/opengis-daf/SKILL.md +12 -14
  72. package/assets/opengis-utils-for-java/SKILL.md +52 -47
  73. package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
  74. package/assets/opengis-utils-for-net/SKILL.md +106 -40
  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 +71 -14
  78. package/assets/pdal/SKILL.md +21 -15
  79. package/assets/postgis/SKILL.md +66 -18
  80. package/assets/proj/SKILL.md +29 -42
  81. package/assets/projnet4geoapi/SKILL.md +299 -0
  82. package/assets/pyqgis/SKILL.md +28 -54
  83. package/assets/qgis-process/SKILL.md +67 -39
  84. package/assets/qgis-server/SKILL.md +21 -32
  85. package/assets/shapely/SKILL.md +133 -84
  86. package/assets/sharpmap/SKILL.md +96 -61
  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
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: pyqgis
3
- description: "Use when extending QGIS with Python plugins, automating map composition, or scripting QGIS processing algorithms. PyQGIS: QGIS Python API for custom tools, processing scripts, and plugin development."
3
+ description: "Use when scripting QGIS with Python — QgsApplication standalone init, QgsVectorLayer / QgsRasterLayer loading, processing.run after Processing.initialize(), QgsGeometry / QgsExpression, QgsMapSettings rendering and QgsLayoutExporter PDF/PNG export, qgis._3d, or debugging \"import qgis.core\" failures. PyQGIS for QGIS 4.2.3 and LTR 3.44.15 (use the interpreter bundled with QGIS, not system Python)."
4
4
  tags:
5
5
  - python
6
6
  - qgis
@@ -39,7 +39,7 @@ PyQGIS 主要包含以下模块:
39
39
  | `qgis.core` | 核心类——图层、要素、几何、坐标系、项目、Processing 等 |
40
40
  | `qgis.gui` | GUI 组件——地图画布、地图工具、符号选择器等 |
41
41
  | `qgis.analysis` | 空间分析——插值、网络分析、栅格计算等 |
42
- | `qgis.processing` | Processing 算法调用入口(`processing.run()`) |
42
+ | `processing` | Processing 算法调用入口(独立 Python 模块,`processing.run()`;非 `qgis.processing`) |
43
43
  | `qgis.server` | QGIS Server Python 插件接口 |
44
44
  | `qgis._3d` | 3D 地图视图相关类 |
45
45
  | `qgis.PyQt` | PyQt5/PyQt6 兼容层 |
@@ -51,7 +51,13 @@ PyQGIS 主要包含以下模块:
51
51
  ### 前置条件
52
52
 
53
53
  - 安装 QGIS 4.2+(当前稳定版)或 3.44 LTR(长期支持版)([查看 QGIS LTR/最新版](https://qgis.org/download/))
54
- - Python 3.12+(QGIS 4.x 自带的 Python 环境)
54
+ - 使用 **QGIS 发行包自带的 Python 解释器**(4.2 的 Windows 安装目录为 `apps/Python312`),不要用系统 Python 直接 `pip install qgis`
55
+
56
+ 探测发行包实际使用的解释器版本(在任何 QGIS Python 环境里):
57
+
58
+ ```bash
59
+ python -c "import sys; print(sys.version)"
60
+ ```
55
61
 
56
62
  ### 在 QGIS Python 控制台中使用
57
63
 
@@ -176,7 +182,7 @@ python3 my_pyqgis_script.py
176
182
 
177
183
  | 类 | 模块 | 用途 |
178
184
  |---|---|---|
179
- | `processing.run()` | `qgis.processing` | **执行 Processing 算法的核心入口** |
185
+ | `processing.run()` | `processing`(QGIS 插件目录模块) | **执行 Processing 算法的核心入口** |
180
186
  | `QgsProcessingFeedback` | `qgis.core` | 算法执行反馈(进度、日志) |
181
187
  | `QgsProcessingContext` | `qgis.core` | 算法执行上下文 |
182
188
  | `QgsProcessingAlgorithm` | `qgis.core` | 自定义算法基类 |
@@ -380,52 +386,6 @@ qgs.exitQgis()
380
386
 
381
387
  更多工作流(批量缓冲融合、栅格裁剪、打印布局导出)见 [reference/processing-rendering.md](reference/processing-rendering.md)。
382
388
 
383
- ## AI 使用建议
384
-
385
- ### 推荐工作流
386
-
387
- 1. **初始化环境**:独立脚本需 `QgsApplication` 初始化;QGIS 控制台中可直接使用
388
- 2. **加载数据**:使用 `QgsVectorLayer` / `QgsRasterLayer` 加载数据源
389
- 3. **执行分析**:优先使用 `processing.run()` 调用算法(参数统一、算法丰富);精细操作使用 `QgsGeometry` 方法
390
- 4. **导出结果**:使用 `QgsVectorFileWriter` 写出矢量,`QgsRasterFileWriter` 写出栅格
391
- 5. **清理退出**:独立脚本调用 `qgs.exitQgis()`
392
-
393
- ### 关键注意事项
394
-
395
- 1. **始终检查图层有效性**:加载图层后必须检查 `layer.isValid()`,无效时检查路径和 Provider。
396
- 2. **坐标系一致性**:空间运算前确保所有图层使用相同 CRS;使用 `native:reprojectlayer` 或 `QgsCoordinateTransform` 进行转换。
397
- 3. **编辑模式**:修改图层数据需 `startEditing()` → 操作 → `commitChanges()`;失败可 `rollBack()`。
398
- 4. **Processing 内存输出**:将 OUTPUT 设为 `'memory:name'` 可得到内存图层,避免创建临时文件。
399
- 5. **椭球面计算**:对地理坐标(经纬度)计算距离/面积时,使用 `QgsDistanceArea` 并设置椭球体,或使用 Processing 算法指定椭球体。
400
- 6. **Headless 环境**:无显示器的服务器上必须设置 `QT_QPA_PLATFORM=offscreen`。
401
- 7. **文件路径使用绝对路径**:避免工作目录不确定导致文件找不到。
402
- 8. **大数据量优化**:使用 `QgsSpatialIndex` 加速空间查询;使用 `QgsFeatureRequest` 限制返回字段和范围。
403
- 9. **表达式语法**:字段名用双引号 `"field"`,字符串值用单引号 `'value'`。
404
- 10. **QGIS 版本兼容**:部分 API 在不同版本间有变化,建议使用 LTR 版本([查看当前 LTR](https://qgis.org/download/))以获得稳定接口;QGIS 当前稳定版为 4.2.3(2026-09 发布),3.44 LTR(最新 3.44.15)仍受支持(截至 2026-10)。
405
-
406
- ### 错误处理
407
-
408
- ```python
409
- # 图层加载失败
410
- layer = QgsVectorLayer(path, name, provider)
411
- if not layer.isValid():
412
- print(f"图层加载失败: {layer.error().message()}")
413
-
414
- # Processing 算法错误
415
- try:
416
- result = processing.run("native:buffer", params, feedback=feedback)
417
- except Exception as e:
418
- print(f"算法执行失败: {e}")
419
-
420
- # 编辑提交失败
421
- if not layer.commitChanges():
422
- errors = layer.commitErrors()
423
- print(f"提交失败: {errors}")
424
- layer.rollBack()
425
- ```
426
-
427
- ---
428
-
429
389
  ## 常见问题
430
390
 
431
391
  | 问题 | 解决 |
@@ -441,6 +401,18 @@ if not layer.commitChanges():
441
401
 
442
402
  ---
443
403
 
404
+ ## AI 使用建议
405
+
406
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/processing-rendering.md`、`reference/vector-raster-layers.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
407
+ - **执行环境**:必须用 QGIS 自带的解释器(Windows 在 `C:\Program Files\QGIS 4.2\apps\Python312\python.exe`,LTR 为 `QGIS 3.44`),不要用系统 Python;命令在终端 / shell 中执行(Windows 用 PowerShell),`export QT_QPA_PLATFORM=offscreen` 改写为 `$env:QT_QPA_PLATFORM = "offscreen"`。
408
+ - **先探测版本**:`python -c "from qgis.core import Qgis; print(Qgis.QGIS_VERSION)"`;本技能同时覆盖 4.2.3(最新)与 3.44.15(LTR),4.x 与 3.x 存在 API 差异,回答里要写明按哪个版本写、低版本哪些类/方法不可用。
409
+ - **验证产物**:独立脚本按 `QgsApplication` → `initQgis()` → 处理 → `exitQgis()` 收尾;写出后重开图层核对 `isValid()`、`featureCount()`、`crs().authid()`,`processing.run()` 的返回值只给路径,结果要二次打开;渲染或布局导出的 PNG 要实际打开看是否空白。
410
+ - **模块名易错**:3D 模块是 `qgis._3d`(下划线,不是 `qgis.3d`),例如 `from qgis._3d import Qgs3DMapSettings`;`processing.run()` 前必须先 `Processing.initialize()`,否则报算法不存在。
411
+ - **进程与日志**:批量脚本不要跨任务复用同一个 `QgsProject.instance()`;长任务放后台运行,QGIS 日志(`QgsApplication.messageLog()`)与 stderr 重定向到文件后分段查看。
412
+ - **安全与权限**:`startEditing()`/`commitChanges()` 直接改源数据(Shapefile、PostGIS),先备份或把中间结果写 `memory:`;覆盖已有输出文件、安装 QGIS、把数据写进系统目录前先征得用户同意。
413
+
414
+ ---
415
+
444
416
  ## 相关技能
445
417
 
446
418
  - **qgis-process** — QGIS 命令行处理工具:[../qgis-process/SKILL.md](../qgis-process/SKILL.md)
@@ -452,8 +424,10 @@ if not layer.commitChanges():
452
424
  ## 参考资源
453
425
 
454
426
  - **QGIS 源码仓库:** <https://github.com/qgis/QGIS>
455
- - **PyQGIS 开发者手册(3.44):** <https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/>
456
- - **PyQGIS API 参考(3.44):** <https://qgis.org/pyqgis/3.44/>
427
+ - **PyQGIS 开发者手册(3.44,4.2 章节尚未定稿):** <https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/>
428
+ - **PyQGIS API 参考(4.2):** <https://qgis.org/pyqgis/4.2/>
457
429
  - **QGIS 文档仓库:** <https://github.com/qgis/QGIS-Documentation>
458
- - **QGIS 用户手册:** <https://docs.qgis.org/3.44/en/docs/user_manual/>
459
- - **PyQGIS 速查表:** <https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/cheat_sheet.html>
430
+ - **QGIS 用户手册(3.44):** <https://docs.qgis.org/3.44/en/docs/user_manual/>
431
+ - **PyQGIS 速查表(3.44):** <https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/cheat_sheet.html>
432
+
433
+ > **注意:** `docs.qgis.org/4.2/...` 目前会 302 跳到 `/testing/`,4.2 的 cookbook 与用户手册尚未定稿;查阅 4.2 类与方法签名以 <https://qgis.org/pyqgis/4.2/> 为准。
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: qgis-process
3
- description: "Use when running QGIS geoprocessing tools headless from command line or CI/CD — buffer, clip, reproject, raster analysis without GUI. QGIS Processing: batch spatial analysis via qgis_process CLI."
3
+ description: "Use when running QGIS geoprocessing headless via qgis_process — native:buffer / native:reprojectlayer / native:clip, qgis_process list / help --json / run --json, .model3 models and .py scripts, batch CI pipelines, or debugging \"Algorithm ... not found!\"; includes QT_QPA_PLATFORM=offscreen and the qgis/qgis images (stable 4.2, ltr 3.44)."
4
4
  tags:
5
5
  - cli
6
6
  - qgis
@@ -20,7 +20,7 @@ tags:
20
20
  >
21
21
  > **在线文档:** <https://docs.qgis.org/4.2/en/docs/user_manual/processing/standalone.html>
22
22
  >
23
- > **最新版本:** QGIS 4.2.3;3.44 LTR 最新 3.44.15(截至2026-10,GitHub Releases;`qgis_process` 自 QGIS 3.16 起可用)
23
+ > **最新版本:** QGIS 4.2.3;3.44 LTR 最新 3.44.15(截至 2026-10,GitHub Releases;`qgis_process` 自 QGIS 3.16 起可用)
24
24
  >
25
25
  > **许可证:** GPL-2.0+
26
26
 
@@ -300,39 +300,70 @@ qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp
300
300
 
301
301
  ---
302
302
 
303
- > 常用内置算法速查、参数类型参考与典型工作流示例见 [reference/algorithm-cheatsheet.md](reference/algorithm-cheatsheet.md)
303
+ > 常用内置算法速查与参数类型参考见 [reference/algorithm-cheatsheet.md](reference/algorithm-cheatsheet.md)
304
304
 
305
- ## AI 使用建议
305
+ ## 典型工作流
306
+
307
+ 目标:把 `data/points.shp` 做 50 m 缓冲区写入 GeoPackage,并在 CI 中批量重复同一流程。
306
308
 
307
- ### 推荐工作流
309
+ ### 1. 先用 help 确认参数,不要凭记忆
308
310
 
309
- 1. **发现算法**:`qgis_process list` → 获取所有可用算法 ID
310
- 2. **查看帮助**:`qgis_process help <algorithm_id> --json` → 获取参数定义的 JSON
311
- 3. **构造参数**:根据 JSON 帮助信息构造参数
312
- 4. **执行算法**:`qgis_process run <algorithm_id> --json -- PARAM=VALUE ...` 或通过 STDIN 传入 JSON
313
- 5. **解析结果**:解析 JSON 输出获取结果路径和日志信息
311
+ ```bash
312
+ qgis_process help native:buffer --json > buffer-help.json
313
+ ```
314
314
 
315
- ### 关键注意事项
315
+ 读取 `parameters` 中 `INPUT` / `DISTANCE` / `SEGMENTS` / `OUTPUT` 的名称与类型;`DISTANCE` 是 `distance` 类型,单位取图层 CRS 单位(投影坐标系下即米,地理坐标系下是度,极易算错)。
316
316
 
317
- 1. **始终使用 `--json` 选项**:JSON 输出结构化、易解析,是 AI 最友好的交互方式。
318
- 2. **先查 help 再构造参数**:每个算法的参数名和类型不同,先用 `help --json` 确认参数定义。
319
- 3. **枚举类型传数字索引**:枚举参数用数字(如 `0`、`1`)而非文字。help 输出的 `available_options` 提供了索引到含义的映射。
320
- 4. **多值参数多次指定**:如 `LAYERS=a.shp LAYERS=b.shp`(在 `--` 之后,参数不带前导 `--`)。
321
- 5. **复杂参数用 STDIN JSON**:字典类型的参数值适合通过 STDIN JSON 方式传入。
322
- 6. **文件路径使用绝对路径**:避免工作目录不确定导致的文件找不到。
323
- 7. **Headless 环境设置 `QT_QPA_PLATFORM=offscreen`**:在无显示器的服务器上必须设置。
324
- 8. **需要项目文件的算法**:某些算法(如打印布局导出)需要通过 `--project_path` 指定项目文件。
325
- 9. **取消正在运行的算法**:使用 `CTRL+C` 可取消执行中的算法。
326
- 10. **`--no-python` 和 `--skip-loading-plugins` 可加速启动**:如果不需要第三方插件提供的算法,使用这两个选项可显著缩短启动时间。
317
+ ### 2. 运行算法写出 GPKG
327
318
 
328
- ### 错误处理
319
+ ```bash
320
+ qgis_process run native:buffer --json -- \
321
+ INPUT=data/points.shp \
322
+ DISTANCE=50 \
323
+ SEGMENTS=8 \
324
+ DISSOLVE=false \
325
+ OUTPUT=out/points_buffer_50m.gpkg
326
+ ```
327
+
328
+ `results.OUTPUT` 是实际写出的绝对路径,用它决定后续校验对象,不要自己拼路径。
329
+
330
+ ### 3. 校验产物
331
+
332
+ ```bash
333
+ ogrinfo -so out/points_buffer_50m.gpkg points_buffer_50m
334
+ ```
329
335
 
330
- - 算法不存在:`Algorithm <id> not found!`
331
- - 缺少必填参数:`The following mandatory parameters were not specified`
332
- - 模型文件无效:`File <path> is not a valid Processing model!`
333
- - Python 脚本无效:`File <path> is not a valid Processing script!`
334
- - 算法不可在命令行使用:`The "<id>" algorithm is not available for use outside of the QGIS desktop application`
335
- - 需要项目文件:`The "<id>" algorithm requires a QGIS project to execute`
336
+ 核对要素数、CRS、几何类型;GPKG 内图层名默认取输出文件名(去扩展名)。`log` 里出现 `returned non-zero` 时即使进程退出码为 0 也算失败。
337
+
338
+ ### 4. 批量循环(CI 脚本)
339
+
340
+ ```bash
341
+ mkdir -p out
342
+ for f in data/*.shp; do
343
+ base=$(basename "$f" .shp)
344
+ qgis_process run native:buffer --json -- \
345
+ INPUT="$f" DISTANCE=50 OUTPUT="out/${base}_buffer.gpkg" \
346
+ || { echo "FAILED: $f" >&2; exit 1; }
347
+ done
348
+ ```
349
+
350
+ 每次 `run` 都会新起一个 QGIS 进程(数秒开销);文件量大时改用 PyQGIS 的 `processing.run()` 在单进程内循环,见 [../pyqgis/SKILL.md](../pyqgis/SKILL.md)。
351
+
352
+ 输入 `data/points.shp` → `native:buffer` → `out/points_buffer_50m.gpkg` → `ogrinfo` 校验,构成 qgis_process 批处理的最小闭环。
353
+
354
+ ## 常见问题
355
+
356
+ | 问题 | 解决方案 |
357
+ |------|---------|
358
+ | 提示 `command not found: qgis_process` | 将 QGIS 的 `bin` 目录加入 `PATH`;Windows 下改用 OSGeo4W Shell 运行 |
359
+ | 无显示器的服务器上崩溃或卡住 | 设置环境变量 `QT_QPA_PLATFORM=offscreen` |
360
+ | `Algorithm <id> not found!` | 用 `qgis_process list` 确认算法 ID 与 Provider 前缀(如 `native:`、`gdal:`) |
361
+ | 缺少必填参数 | 先用 `qgis_process help <id> --json` 查看参数名、类型与默认值 |
362
+ | 枚举参数报错 | 枚举值需传数字索引,`help --json` 中的 `available_options` 提供索引映射 |
363
+ | 多值参数只生效一项 | 在 `--` 之后多次指定同一参数(如 `LAYERS=a.shp LAYERS=b.shp`) |
364
+ | 路径含空格或中文时报错 | 使用绝对路径并对参数值加引号 |
365
+ | 启动速度慢 | 不需要 Python/插件时添加 `--no-python` 与 `--skip-loading-plugins` |
366
+ | 模型/脚本或算法不可用 | 报 `File <path> is not a valid Processing model!` / `... is not a valid Processing script!` / `not available for use outside of the QGIS desktop application` 时,改用 QGIS 桌面或 PyQGIS 脚本 |
336
367
 
337
368
  ---
338
369
 
@@ -351,18 +382,15 @@ qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp
351
382
 
352
383
  ---
353
384
 
354
- ## 常见问题
385
+ ## AI 使用建议
355
386
 
356
- | 问题 | 解决方案 |
357
- |------|---------|
358
- | 提示 `command not found: qgis_process` | 将 QGIS 的 `bin` 目录加入 `PATH`;Windows 下改用 OSGeo4W Shell 运行 |
359
- | 无显示器的服务器上崩溃或卡住 | 设置环境变量 `QT_QPA_PLATFORM=offscreen` |
360
- | `Algorithm <id> not found!` | 用 `qgis_process list` 确认算法 ID 与 Provider 前缀(如 `native:`、`gdal:`) |
361
- | 缺少必填参数 | 先用 `qgis_process help <id> --json` 查看参数名、类型与默认值 |
362
- | 枚举参数报错 | 枚举值需传数字索引,`help --json` 中的 `available_options` 提供索引映射 |
363
- | 多值参数只生效一项 | 在 `--` 之后多次指定同一参数(如 `LAYERS=a.shp LAYERS=b.shp`) |
364
- | 路径含空格或中文时报错 | 使用绝对路径并对参数值加引号 |
365
- | 启动速度慢 | 不需要 Python/插件时添加 `--no-python` 与 `--skip-loading-plugins` |
387
+ - **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/algorithm-cheatsheet.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
388
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell)。Windows 下 `qgis_process` 在 `C:\Program Files\QGIS 4.2\bin`(LTR 为 `C:\Program Files\QGIS 3.44\bin`)或 OSGeo4W Shell 里;PowerShell 设 `$env:QT_QPA_PLATFORM = "offscreen"`,不要照抄 `export`。
389
+ - **先探测版本**:`qgis_process --version`(QGIS 4.2.3 或 LTR 3.44.15)、`qgis_process list`;低于 3.16 没有 `qgis_process`,只能改用 PyQGIS 脚本;`--no-python`、`--skip-loading-plugins` 可显著加快启动。
390
+ - **验证产物**:`run ... --json` 里的 `results.OUTPUT` 是实际写出的绝对路径,再用 `ogrinfo -so`(矢量)或 `gdalinfo -json`(栅格)核对要素数、CRS、范围;日志中出现 `returned non-zero` 说明算法内部失败,不要只看进程退出码。
391
+ - **参数约定**:`--` 之后的参数不带前导 `--`;枚举传数字索引(`help --json` 里的 `available_options` 是映射表);多值参数重复同一键(`LAYERS=a.shp LAYERS=b.shp`);路径含空格或中文时加引号,尽量用绝对路径。
392
+ - **常见报错**:`Algorithm <id> not found!` 先查 provider 前缀(`native:`、`gdal:`、`grass:`),`The following mandatory parameters were not specified` 回看 `help --json`,`requires a QGIS project to execute` 补 `--project_path`。
393
+ - **安全与权限**:`OUTPUT=` 指向已有文件会被覆盖;`--project_path` 会加载项目内的数据源与凭证,注意不要把含密码的项目传给外部环境;启动 Docker 或安装 QGIS 前先征得用户同意,长任务放后台运行。
366
394
 
367
395
  ---
368
396
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: qgis-server
3
- description: "Use when publishing QGIS projects (.qgs/.qgz) as OGC web services (WMS, WFS, WMTS, OGC API Features) via FastCGI, Docker, or Apache/Nginx, and when tuning QGIS_SERVER_* environment variables. QGIS Server: the C++ map server that renders QGIS Desktop projects over HTTP."
3
+ description: "Use when publishing QGIS projects (.qgs/.qgz) as OGC web services — WMS GetMap/GetPrint, WFS and WFS-T, WMTS, OGC API Features via qgis_mapserv.fcgi with Apache mod_fcgid, Nginx, or Docker, plus QGIS_SERVER_* tuning (MAX_THREADS, PARALLEL_RENDERING, LOG_STDERR); covers \"Service unknown or unsupported\" and MAP/GetCapabilities checks. QGIS 4.2.3 and LTR 3.44.15."
4
4
  tags:
5
5
  - qgis
6
6
  - server
@@ -15,9 +15,9 @@ tags:
15
15
 
16
16
  > **项目地址:** <https://github.com/qgis/QGIS>
17
17
  >
18
- > **官方文档:** <https://docs.qgis.org/latest/en/docs/server_manual/>
18
+ > **官方文档:** <https://docs.qgis.org/3.44/en/docs/server_manual/>(`/latest/` 目前 302 到 3.44 手册,4.2 手册尚未单独发布)
19
19
  >
20
- > **最新版本:** 4.2.3(截至 2026-10);LTR 3.44.15
20
+ > **最新版本:** 4.2.3(稳定版);LTR 3.44.15(截至 2026-10,实测 `qgis/qgis` 镜像 tag 与 <https://qgis.org/download/>)
21
21
  >
22
22
  > **许可证:** GPL-2.0
23
23
 
@@ -119,7 +119,9 @@ WMS 的 `LAYERS` 支持按短名或图层 ID 选择,多个图层用逗号分
119
119
 
120
120
  WMTS 的 `TILEMATRIXSET` 定义金字塔所用 CRS(形如 `EPSG:XXXX`),`TILEMATRIX`/`TILEROW`/`TILECOL` 定位具体瓦片;`FORMAT` 仅支持 `jpg`/`jpeg`/`image/jpeg`/`image/png`,其余值回退为 PNG。`GetFeatureInfo` 的 `INFOFORMAT` 默认 `text/plain`,用 `I`/`J` 指定像素坐标。
121
121
 
122
- OGC API - Features(WFS3)是面向 REST 的 JSON 接口,按项目发布,端点位于服务根路径下(如 `/wfs3/collections`、`/wfs3/collections/{id}/items`),支持 `limit`、`bbox`、`datetime` 等查询参数。该服务是否可用取决于项目 `OWS Server` 页的发布设置。
122
+ OGC API - Features(OAPIF,旧称 WFS3)是面向 REST 的 JSON/HTML 接口,按项目发布,服务根为 `/wfs3`(如 `/wfs3/collections`、`/wfs3/collections/{id}/items`),`/wfs3/api` 提供自描述文档,支持 `limit`、`bbox`、`datetime` 等查询参数。该服务是否可用取决于项目 `OWS Server` 页的发布设置。
123
+
124
+ > 官方注意:OAPIF 遵循 OpenAPI 规范,不接受额外查询参数,因此**不建议**在 URL 里暴露 `MAP`;改用 `QGIS_PROJECT_FILE` 环境变量或 Web 服务器重写规则指定项目(实测 QGIS 3.44/4.2 Server 手册 "OGC API Features" 一节)。
123
125
 
124
126
  ### 在项目中启用服务
125
127
 
@@ -205,19 +207,18 @@ location /qgis {
205
207
  | `GetPrint` 报错或输出空白 | Linux 无 X 环境,需安装并启动 `Xvfb`,在 Web 服务器配置 `DISPLAY=:99` |
206
208
  | WFS `Transaction` 提交失败 | 需通过 POST 提交(删除可用 `OPERATION`),且数据源必须可写、图层勾选相应发布权限 |
207
209
  | 高并发下响应缓慢 | 开启 `QGIS_SERVER_PARALLEL_RENDERING`、调大 `QGIS_SERVER_MAX_THREADS` 与项目缓存 |
210
+ | 直接执行 `qgis_mapserv.fcgi` 无输出 | 正常:FCGI 需由 Web 服务器以 FastCGI 协议调用;用 `curl` 带 `SERVICE=WMS&REQUEST=GetCapabilities` 验证 |
208
211
 
209
212
  ---
210
213
 
211
- ## 参考资源
212
-
213
- - QGIS Server 手册:<https://docs.qgis.org/latest/en/docs/server_manual/>
214
- - 配置与环境变量:<https://docs.qgis.org/latest/en/docs/server_manual/config.html>
215
- - WMS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wms.html>
216
- - WFS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wfs.html>
217
- - WMTS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wmts.html>
218
- - 容器化部署:<https://docs.qgis.org/latest/en/docs/server_manual/containerized_deployment.html>
214
+ ## AI 使用建议
219
215
 
220
- ---
216
+ - **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell),Windows 上 `curl` 要写 `curl.exe`;Apache/Nginx 片段属于目标服务器配置,本机会话改不了远端,需在主机上执行或用容器验证。
217
+ - **先探测版本**:用同一安装的 `qgis --version` / `qgis_process --version`(或 `dpkg -l qgis-server`、容器镜像 tag)确认服务端版本;Debian/Ubuntu 的服务入口是 `/usr/lib/cgi-bin/qgis_mapserv.fcgi`,直接执行返回 `ServiceExceptionReport` 即安装可用。本技能覆盖 4.2.3(最新)与 3.44.15(LTR),生成项目的 QGIS Desktop 与服务端大版本应一致。
218
+ - **验证服务**:先 `curl "http://localhost/cgi-bin/qgis_mapserv.fcgi?MAP=/data/world.qgz&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities"` 存盘后核对 `<Service>` 与 `<Layer>` 清单,再测 `GetMap` 出图(导出的 PNG 要实际打开看是否空白)、`GetFeature`、`GetTile`。
219
+ - **常见报错**:`Service unknown or unsupported` 是缺 `SERVICE`/`MAP` 参数而非服务故障;`GetMap` 空白先查 `MAP` 路径可读性与项目 `OWS Server` 页的 `published` 勾选,再查 CRS/`BBOX`。
220
+ - **日志与生效**:`QGIS_SERVER_LOG_STDERR=1` 交给 journald 或容器日志;`QGIS_SERVER_LOG_FILE` 已废弃,不要再用;`QGIS_SERVER_*` 改动要重启 FCGI 进程(或容器)才生效。
221
+ - **安全与权限**:启动容器、开放端口、改 Web 服务器配置前先征得用户同意;`GetPrint` 在无 X 的 Linux 上需 `Xvfb`;项目文件可能含数据库凭证,命令与回答里不要回显密码。
221
222
 
222
223
  ## 相关技能
223
224
 
@@ -228,23 +229,11 @@ location /qgis {
228
229
 
229
230
  ---
230
231
 
231
- ## AI 使用建议
232
-
233
- ### 关键注意事项
234
-
235
- - **`MAP` 必填**:几乎所有 QGIS 扩展请求都要求 `MAP` 指向存在的项目文件;用 `QGIS_PROJECT_FILE` 可设默认值。
236
- - **版本匹配**:生成项目的 Desktop 与服务端版本尽量一致,跨大版本先在小环境验证。
237
- - **日志优先 stderr**:`QGIS_SERVER_LOG_FILE` 已废弃,统一用 `QGIS_SERVER_LOG_STDERR`。
238
- - **发布开关**:图层是否出现在服务中取决于项目 `OWS Server` 页的 `published`/`queryable` 设置,而非仅由 URL 决定。
239
-
240
- ### 常见配置模式
232
+ ## 参考资源
241
233
 
242
- ```text
243
- QGIS Desktop 项目 (.qgz)
244
- └── 项目属性 ▸ QGIS Server / OWS Server ──→ 启用 WMS/WFS/WMTS
245
- └── FastCGI (qgis_mapserv.fcgi)
246
- ├── Apache mod_fcgid
247
- ├── Nginx + spawn-fcgi / fcgiwrap
248
- └── Docker (qgis-server + nginx)
249
- └── MAP / QGIS_PROJECT_FILE + QGIS_SERVER_* 环境变量
250
- ```
234
+ - QGIS Server 手册:<https://docs.qgis.org/latest/en/docs/server_manual/>
235
+ - 配置与环境变量:<https://docs.qgis.org/latest/en/docs/server_manual/config.html>
236
+ - WMS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wms.html>
237
+ - WFS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wfs.html>
238
+ - WMTS 服务:<https://docs.qgis.org/latest/en/docs/server_manual/services/wmts.html>
239
+ - 容器化部署:<https://docs.qgis.org/latest/en/docs/server_manual/containerized_deployment.html>