@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
@@ -0,0 +1,299 @@
1
+ ---
2
+ name: projnet4geoapi
3
+ description: "Use when transforming coordinates or reading CRS definitions in .NET with ProjNet 2.1.0 (NuGet ProjNet, repo ProjNet4GeoAPI) — CoordinateSystemFactory.CreateFromWkt, CoordinateTransformationFactory.CreateFromCoordinateSystems, MathTransform.Transform, CoordinateSystemServices SRID registration. Also for 'no suitable transformation' / null from GetCoordinateSystem, EPSG codes beyond 4326 and 3857 returning null, and SharpMap projects needing the legacy ProjNet4GeoAPI 1.4.1 GeoAPI build."
4
+ tags:
5
+ - dotnet
6
+ - csharp
7
+ - coordinate-systems
8
+ - projection
9
+ - epsg
10
+ - wkt
11
+ - geospatial
12
+ - netstandard
13
+ - sharpmap
14
+ ---
15
+
16
+ > **项目地址:** <https://github.com/NetTopologySuite/ProjNet4GeoAPI>
17
+ >
18
+ > **NuGet(2.x):** `ProjNet` 2.1.0(netstandard2.0 / netstandard2.1,截至 2026-10)
19
+ >
20
+ > **NuGet(1.x,旧版):** `ProjNet4GeoAPI` 1.4.1(面向 GeoAPI 接口的项目,如 SharpMap 1.2)
21
+ >
22
+ > **官方文档:** <https://github.com/NetTopologySuite/ProjNet4GeoAPI/wiki>
23
+ >
24
+ > **许可证:** LGPL-2.1-or-later
25
+ >
26
+ > **维护状态:** 上游 README 明确说明维护资源不足,官方给出的替代方案是 SharpProj、DotSpatial.Projections、GDAL;新项目在需要完整 EPSG 支持时应优先考虑这些方案。
27
+
28
+ ## 概述
29
+
30
+ ProjNet 是 SharpMap 时代延续下来的 .NET 坐标参考系与投影引擎,按 OGC Simple Features 模型描述坐标系,负责「点对点」的坐标转换:源坐标系 → 目标坐标系,中间可能包含基准面转换(datum transformation)。它不提供地图渲染,也不自带 EPSG 数据库,坐标系定义要么用内置常量(WGS84、WebMercator),要么由调用方提供 WKT。
31
+
32
+ - **坐标系模型**:地理坐标系、地心坐标系、投影坐标系、垂直坐标系、复合坐标系
33
+ - **转换能力**:基准面转换、地理↔投影、投影↔投影,支持 Albers、Mercator、Transverse Mercator、Lambert Conformal Conic、Polar Stereographic、Krovak 等常用投影
34
+ - **定义读写**:WKT 与 XML 互转(`CreateFromWkt` / `CreateFromXml`)
35
+ - **服务容器**:`CoordinateSystemServices` 维护 SRID → 坐标系映射与转换工厂,默认只注册 EPSG:4326 与 EPSG:3857
36
+ - **两代包**:2.x 用自带类型体系(`ProjNet.CoordinateSystems`),1.x 实现 GeoAPI 接口供 SharpMap 等老库使用
37
+
38
+ ---
39
+
40
+ ## 环境准备
41
+
42
+ ### 安装(.NET 6+ / netstandard2.0 兼容项目)
43
+
44
+ ```bash
45
+ # 2.x 系列(推荐)
46
+ dotnet add package ProjNet --version 2.1.0
47
+
48
+ # 1.x 系列:只在必须实现 GeoAPI 接口的老项目里使用(如 SharpMap 1.2)
49
+ dotnet add package ProjNet4GeoAPI --version 1.4.1
50
+ ```
51
+
52
+ ```powershell
53
+ # Package Manager Console
54
+ Install-Package ProjNet -Version 2.1.0
55
+ ```
56
+
57
+ 两个包的程序集名都是 `ProjNET.dll`,**不能同时引用**;同时引用会出现类型冲突与「找到多个同名类型」的编译错误。
58
+
59
+ ### 验证
60
+
61
+ ```csharp
62
+ using ProjNet.CoordinateSystems;
63
+ using ProjNet.CoordinateSystems.Transformations;
64
+
65
+ var src = GeographicCoordinateSystem.WGS84;
66
+ var tgt = ProjectedCoordinateSystem.WebMercator;
67
+ var transform = new CoordinateTransformationFactory()
68
+ .CreateFromCoordinateSystems(src, tgt);
69
+
70
+ double[] xy = transform.MathTransform.Transform(new[] {116.397, 39.908});
71
+ Console.WriteLine($"{xy[0]:F2}, {xy[1]:F2}"); // 约 12957254.80, 4852582.10
72
+ ```
73
+
74
+ ```bash
75
+ dotnet run # 能打印出 Web Mercator 米制坐标即环境正常
76
+ ```
77
+
78
+ ### 目标框架
79
+
80
+ | 包 | 目标框架 | 说明 |
81
+ |----|----------|------|
82
+ | `ProjNet` 2.1.0 | netstandard2.0 / netstandard2.1 | .NET Framework 4.6.1+、.NET 6/8/9 均可引用;netstandard2.0 版本额外依赖 `System.Memory` 4.6.0 |
83
+ | `ProjNet4GeoAPI` 1.4.1 | net35-client / net40-client / net45 / netstandard2.0 | 2018 年发布,只为兼容 GeoAPI 生态 |
84
+
85
+ ---
86
+
87
+ ## 核心 API
88
+
89
+ ### 坐标系工厂
90
+
91
+ ```csharp
92
+ using ProjNet.CoordinateSystems;
93
+
94
+ var factory = new CoordinateSystemFactory();
95
+
96
+ // 从 WKT 解析(EPSG 官网、GDAL 的 projinfo、QGIS 都能导出 WKT)
97
+ CoordinateSystem wgs84Utm50 = factory.CreateFromWkt(wktText);
98
+
99
+ // 从 XML 解析
100
+ CoordinateSystem fromXml = factory.CreateFromXml(xmlText);
101
+
102
+ // 组合式构造:以已有地理坐标系 + 投影参数创建投影坐标系
103
+ var gcs = GeographicCoordinateSystem.WGS84;
104
+ ```
105
+
106
+ | 成员 | 说明 |
107
+ |------|------|
108
+ | `CreateFromWkt(string)` | 解析 WKT,返回 `CoordinateSystem`;失败时可能返回 `null` |
109
+ | `CreateFromXml(string)` | 解析 ProjNet 自身的 XML 表示 |
110
+ | `CreateProjectedCoordinateSystem(...)` | 手工组装投影坐标系(名称、地理坐标系、投影、线性单位、轴) |
111
+ | `CreateGeographicCoordinateSystem(...)` | 手工组装地理坐标系(角度单位、基准面、本初子午线、轴) |
112
+ | `CreateProjection(name, className, parameters)` | 按投影类名与参数创建投影 |
113
+
114
+ 内置常量只有少数几个:`GeographicCoordinateSystem.WGS84`、`ProjectedCoordinateSystem.WebMercator`。其余坐标系必须自带 WKT。
115
+
116
+ ### 坐标转换
117
+
118
+ ```csharp
119
+ using ProjNet.CoordinateSystems;
120
+ using ProjNet.CoordinateSystems.Transformations;
121
+
122
+ var ctFactory = new CoordinateTransformationFactory();
123
+ ICoordinateTransformation ct = ctFactory.CreateFromCoordinateSystems(
124
+ sourceCS: factory.CreateFromWkt(wgs84Wkt),
125
+ targetCS: factory.CreateFromWkt(cgcs2000GaussKrugerWkt));
126
+
127
+ MathTransform mt = ct.MathTransform;
128
+
129
+ // 单点
130
+ double[] projected = mt.Transform(new[] {116.397, 39.908});
131
+
132
+ // 单点(元组重载,免去数组分配)
133
+ var (x, y) = mt.Transform(116.397, 39.908);
134
+
135
+ // 多点:一次调用处理整批,比循环 new 数组快得多
136
+ double[][] points = {new[] {116.0, 39.0}, new[] {117.0, 40.0}};
137
+ IList<double[]> projectedPoints = mt.TransformList(points);
138
+ ```
139
+
140
+ | 类型 / 成员 | 说明 |
141
+ |-------------|------|
142
+ | `ICoordinateTransformation.SourceCS` / `TargetCS` | 源与目标坐标系 |
143
+ | `ICoordinateTransformation.MathTransform` | 实际执行数值转换的数学变换 |
144
+ | `MathTransform.Transform(double[])` | 单点转换,输入 `[x, y]` 或 `[x, y, z]`,维度由变换决定 |
145
+ | `MathTransform.Transform(double x, double y)` | 元组重载,返回 `(x, y)` |
146
+ | `MathTransform.TransformList(IList<double[]>)` | 批量转换,返回转换后的点数组列表 |
147
+ | `MathTransform.Transform(Span<double> xs, Span<double> ys)` | 分离数组的 SOA 批量转换,适合大数组 |
148
+ | `MathTransform.Inverse()` | 取逆变换,用于反向换算 |
149
+
150
+ 坐标按 `x, y` 顺序解释(经度/东坐标在前,纬度/北坐标在后),ProjNet **不做轴序交换**;若拿到的 WKT 声明了 `AXIS["Latitude", NORTH]` 之类的轴序,需要调用方自行判断是否交换。
151
+
152
+ ### CoordinateSystemServices:SRID 与转换缓存
153
+
154
+ ```csharp
155
+ using ProjNet.CoordinateSystems;
156
+ using ProjNet.CoordinateSystems.Transformations;
157
+
158
+ var services = new CoordinateSystemServices();
159
+
160
+ // 默认只有 4326 与 3857
161
+ var wgs84 = services.GetCoordinateSystem(4326);
162
+ var mercator = services.GetCoordinateSystem(3857);
163
+
164
+ // 注册任意 EPSG 编码(值为 WKT 字符串)
165
+ var defs = new[]
166
+ {
167
+ new KeyValuePair<int, string>(4490, cgcs2000Wkt),
168
+ new KeyValuePair<int, string>(4547, cgcs2000GkCmwWkt),
169
+ };
170
+ var withDefs = new CoordinateSystemServices(defs);
171
+
172
+ ICoordinateTransformation ct = withDefs.CreateTransformation(4490, 4547);
173
+ double[] xy = ct.MathTransform.Transform(new[] {116.397, 39.908});
174
+ ```
175
+
176
+ | 成员 | 说明 |
177
+ |------|------|
178
+ | `new CoordinateSystemServices()` | 默认注册 4326、3857 两个坐标系 |
179
+ | `new CoordinateSystemServices(IEnumerable<KeyValuePair<int,string>>)` | 用 SRID → WKT 批量注册 |
180
+ | `GetCoordinateSystem(int srid)` | 按 SRID 取坐标系;未注册返回 `null` |
181
+ | `GetCoordinateSystem(string authority, long code)` | 按授权名与编码取(内部仍走 SRID 映射) |
182
+ | `GetSRID(string authority, long code)` | 反查 SRID,未注册返回 `null` |
183
+ | `CreateTransformation(int sourceSrid, int targetSrid)` | 按 SRID 建转换,最常用 |
184
+ | `CreateTransformation(CoordinateSystem, CoordinateSystem)` | 按对象建转换 |
185
+
186
+ 失败的 WKT 会被静默跳过:`CreateCoordinateSystem` 内部捕获异常并返回 `null`,因此「注册了但查不到」优先怀疑 WKT 本身不被支持(例如带 `ELLIPSOID` 关键字或使用了未实现的投影)。
187
+
188
+ ---
189
+
190
+ ## 典型工作流
191
+
192
+ 把一批 WGS84 经纬度点位转换到 CGCS2000 3 度带高斯-克吕格投影(EPSG:4547),并写回 CSV:
193
+
194
+ **输入**:`points.csv`(`lon,lat`)
195
+ **输出**:`points_projected.csv`(`lon,lat,x,y`)
196
+
197
+ 1. 用 `projinfo`(PROJ 命令行)导出目标坐标系的 WKT,避免手写投影参数
198
+ 2. 在代码里用 `CoordinateSystemServices` 注册 4490 与 4547
199
+ 3. 批量读取点位,调用 `MathTransform.Transform` 逐点或打包转换
200
+ 4. 输出前校验坐标量级(高斯投影的东坐标通常在 6 位数字量级)
201
+
202
+ ```bash
203
+ # 导出 WKT(PROJ 9.x)
204
+ projinfo EPSG:4547 -o WKT2:2019
205
+ ```
206
+
207
+ ```csharp
208
+ using System.Globalization;
209
+ using ProjNet.CoordinateSystems;
210
+ using ProjNet.CoordinateSystems.Transformations;
211
+
212
+ var cgcs2000 = File.ReadAllText("wkt/epsg4490.wkt");
213
+ var gk3d = File.ReadAllText("wkt/epsg4547.wkt");
214
+
215
+ var services = new CoordinateSystemServices(new[]
216
+ {
217
+ new KeyValuePair<int, string>(4490, cgcs2000),
218
+ new KeyValuePair<int, string>(4547, gk3d),
219
+ });
220
+
221
+ var ct = services.CreateTransformation(4490, 4547);
222
+ var mt = ct.MathTransform;
223
+
224
+ using var reader = new StreamReader("points.csv");
225
+ using var writer = new StreamWriter("points_projected.csv");
226
+ writer.WriteLine("lon,lat,x,y");
227
+
228
+ reader.ReadLine(); // 跳过表头
229
+ string? line;
230
+ while ((line = reader.ReadLine()) is not null)
231
+ {
232
+ var parts = line.Split(',');
233
+ double lon = double.Parse(parts[0], CultureInfo.InvariantCulture);
234
+ double lat = double.Parse(parts[1], CultureInfo.InvariantCulture);
235
+
236
+ double[] xy = mt.Transform(new[] {lon, lat});
237
+ writer.WriteLine(string.Join(",",
238
+ lon.ToString(CultureInfo.InvariantCulture),
239
+ lat.ToString(CultureInfo.InvariantCulture),
240
+ xy[0].ToString("F3", CultureInfo.InvariantCulture),
241
+ xy[1].ToString("F3", CultureInfo.InvariantCulture)));
242
+ }
243
+ ```
244
+
245
+ **检查点**:转换后东坐标应是 6 位数(含带号则 8 位),北坐标在 0–5000000 量级;若数值仍是 116 / 39 这样的量级,说明取错了坐标系或 WKT 解析失败被静默跳过。
246
+
247
+ ---
248
+
249
+ ## 最佳实践
250
+
251
+ 1. **WKT 由专业工具生成**:用 `projinfo`、`gdalsrsinfo` 或 EPSG 官网导出,不要手写 `PROJCS` 字符串,参数顺序错一位结果就偏
252
+ 2. **一次构造、复用实例**:`CoordinateTransformationFactory`、`CoordinateSystemFactory` 与 `MathTransform` 都可复用,避免在循环里重复解析 WKT
253
+ 3. **批量用 `TransformList` 或 `Span` 重载**:`MathTransform.TransformList(IList<double[]>)` 一次处理整批点;SOA 结构的大数组用 `Transform(Span<double> xs, Span<double> ys)` 避免装箱
254
+ 4. **校验转换前后的量级与范围**:投影坐标是米,经纬度是度;写一条断言比肉眼检查可靠
255
+ 5. **明确轴序**:ProjNet 只做 `x, y` 算术,不理会 WKT 的 `AXIS` 声明,跨系统交换数据时显式约定顺序
256
+ 6. **坐标是数值不是几何**:ProjNet 只处理点数组,几何对象的转换要自己遍历坐标(或用 NTS 的坐标过滤器)
257
+ 7. **考虑替代方案**:需要完整 EPSG 库、网格文件(NTv2/GTX)或 3D 基准转换时,用 SharpProj 或 GDAL,不要指望 ProjNet 覆盖
258
+
259
+ ---
260
+
261
+ ## 常见问题
262
+
263
+ | 问题 | 原因与解决 |
264
+ |------|------------|
265
+ | `CreateFromCoordinateSystems` 返回 `null` 或抛异常 | 源/目标坐标系类型组合不受支持(如两个地理坐标系之间只差基准面而缺少转换参数):改用「地理 → 投影」或先转 WGS84 再转目标 |
266
+ | `GetCoordinateSystem(4490)` 返回 `null` | `CoordinateSystemServices` 默认只注册 4326 与 3857:用 SRID → WKT 的构造函数注册,或直接 `CreateFromWkt` |
267
+ | 转换结果与 QGIS/GDAL 差几十米 | ProjNet 没有网格文件与最新基准面参数,只做近似七参数/三参数转换:高精度场景改用 SharpProj 或 GDAL |
268
+ | 注册了 WKT 但查不到坐标系 | `CreateCoordinateSystem` 会吞掉解析异常:先用 `new CoordinateSystemFactory().CreateFromWkt(wkt)` 单独验证,确认返回非 `null` |
269
+ | 经纬度转换结果是反的 | 输入数组按 `[x, y]` 解释,即经度在前:把 `[lat, lon]` 改成 `[lon, lat]` |
270
+ | 同时引用两个包后大量类型冲突 | `ProjNet` 2.x 与 `ProjNet4GeoAPI` 1.x 程序集同名:只保留一个;SharpMap 1.2 项目必须用 1.4.1 |
271
+ | 老项目里 `CoordinateTransformation` 赋值编译失败 | SharpMap 1.2 期望 GeoAPI 的 `ICoordinateTransformation`,2.x 不再实现该接口:换成 `ProjNet4GeoAPI` 1.4.1 |
272
+ | 大文件转换极慢 | 在循环里反复解析 WKT 或逐点 new 转换对象:把工厂、坐标系、`MathTransform` 提到循环外,并用打包数组接口 |
273
+
274
+ ---
275
+
276
+ ## AI 使用建议
277
+
278
+ - **执行环境**:`dotnet add package`、`dotnet build`、`dotnet run` 在终端中执行;首次 restore 需要访问 NuGet,失败时先看是否离线。
279
+ - **先探测版本**:`dotnet list package` 确认是 `ProjNet 2.1.0` 还是 `ProjNet4GeoAPI 1.4.1`——两者的命名空间与接口完全不同,写代码前必须确认,不要凭 `using ProjNet.CoordinateSystems` 猜。
280
+ - **WKT 来源**:让用户提供或先跑 `projinfo EPSG:xxxx -o WKT2:2019` 生成,再写进示例;不要凭空编造 `PROJCS` 参数。
281
+ - **验证产物**:编译后运行最小断言(如 116.397, 39.908 → Web Mercator 约 (12957254.8, 4852582.1)),数值量级不对就说明坐标系或轴序取错。
282
+ - **失败信号**:`null` 返回值优先怀疑 WKT 解析;结果偏差固定为几十米量级,是缺少网格文件而非代码错误。
283
+ - **安全与权限**:新建工程、装包前征得用户同意;示例里的 WKT 文件路径用占位符,不要写入用户真实数据路径。
284
+
285
+ ## 相关技能
286
+
287
+ - **nettopologysuite** — .NET 几何运算,常与 ProjNet 搭配做「几何转换 + 空间分析」:[../nettopologysuite/SKILL.md](../nettopologysuite/SKILL.md)
288
+ - **sharpmap** — 旧版 .NET 地图渲染库,坐标变换依赖 ProjNet/ProjNet4GeoAPI:[../sharpmap/SKILL.md](../sharpmap/SKILL.md)
289
+ - **mapsui** — 现代跨平台 .NET 地图组件,新项目优先考虑:[../mapsui/SKILL.md](../mapsui/SKILL.md)
290
+ - **proj** — PROJ 命令行,用于导出 WKT 与核对转换结果:[../proj/SKILL.md](../proj/SKILL.md)
291
+ - **gdal** — GDAL/OGR 命令行,可做高精度重投影与批量转换:[../gdal/SKILL.md](../gdal/SKILL.md)
292
+
293
+ ## 参考资源
294
+
295
+ - Wiki(FAQ、常用 WKT):<https://github.com/NetTopologySuite/ProjNet4GeoAPI/wiki>
296
+ - 源码:<https://github.com/NetTopologySuite/ProjNet4GeoAPI>
297
+ - NuGet(2.x):<https://www.nuget.org/packages/ProjNet>
298
+ - NuGet(1.x):<https://www.nuget.org/packages/ProjNet4GeoAPI>
299
+ - EPSG 坐标系查询:<https://epsg.org/>(EPSG 官方注册库;<https://spatialreference.org/> 可查 OGC WKT)
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: pyqgis
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, Python 3.12."
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,18 +386,6 @@ qgs.exitQgis()
380
386
 
381
387
  更多工作流(批量缓冲融合、栅格裁剪、打印布局导出)见 [reference/processing-rendering.md](reference/processing-rendering.md)。
382
388
 
383
- ## DeepSeek Harness 使用建议
384
-
385
- - **加载与引用**:用 `skill("pyqgis")` 加载(用户也可输入 `/pyqgis`);`reference/vector-raster-layers.md`、`reference/processing-rendering.md` 按需 `read`,路径相对 Base directory;技能目录只读,脚本、导出图与中间数据写到会话工作区。
386
- - **执行环境**:必须用 QGIS 自带的解释器(Windows 在 `C:\Program Files\QGIS 4.2\apps\Python312\python.exe`,LTR 为 `QGIS 3.44`),不要用系统 Python;命令交给 dsh 的 shell 工具(Windows 用 `pwsh`;仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行),`export QT_QPA_PLATFORM=offscreen` 改写为 `$env:QT_QPA_PLATFORM = "offscreen"`。
387
- - **先探测版本**:`python -c "from qgis.core import Qgis; print(Qgis.QGIS_VERSION)"`;本技能同时覆盖 4.2.3(最新)与 3.44.15(LTR),4.x 与 3.x 存在 API 差异,回答里要写明按哪个版本写、低版本哪些类/方法不可用。
388
- - **验证产物**:独立脚本按 `QgsApplication` → `initQgis()` → 处理 → `exitQgis()` 收尾;写出后重开图层核对 `isValid()`、`featureCount()`、`crs().authid()`,`processing.run()` 的返回值只给路径,结果要二次打开;渲染或布局导出的 PNG 可用 `read_image` 看是否空白。
389
- - **模块名易错**:3D 模块是 `qgis._3d`(下划线,不是 `qgis.3d`),例如 `from qgis._3d import Qgs3DMapSettings`;`processing.run()` 前必须先 `Processing.initialize()`,否则报算法不存在。
390
- - **进程与日志**:批量脚本不要跨任务复用同一个 `QgsProject.instance()`;长任务放后台作业,QGIS 日志(`QgsApplication.messageLog()`)与 stderr 重定向到文件后分段 `read`。
391
- - **安全与权限**:`startEditing()`/`commitChanges()` 直接改源数据(Shapefile、PostGIS),先备份或把中间结果写 `memory:`;覆盖已有输出文件、安装 QGIS、把数据写进系统目录前先征得用户同意。
392
-
393
- ---
394
-
395
389
  ## 常见问题
396
390
 
397
391
  | 问题 | 解决 |
@@ -407,6 +401,18 @@ qgs.exitQgis()
407
401
 
408
402
  ---
409
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
+
410
416
  ## 相关技能
411
417
 
412
418
  - **qgis-process** — QGIS 命令行处理工具:[../qgis-process/SKILL.md](../qgis-process/SKILL.md)
@@ -418,8 +424,10 @@ qgs.exitQgis()
418
424
  ## 参考资源
419
425
 
420
426
  - **QGIS 源码仓库:** <https://github.com/qgis/QGIS>
421
- - **PyQGIS 开发者手册(3.44):** <https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/>
422
- - **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/>
423
429
  - **QGIS 文档仓库:** <https://github.com/qgis/QGIS-Documentation>
424
- - **QGIS 用户手册:** <https://docs.qgis.org/3.44/en/docs/user_manual/>
425
- - **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/> 为准。
@@ -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,17 +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
- ## DeepSeek Harness 使用建议
305
+ ## 典型工作流
306
306
 
307
- - **加载与引用**:用 `skill("qgis-process")` 加载(用户也可输入 `/qgis-process`);`reference/algorithm-cheatsheet.md` 按需 `read`,但算法参数一律以 `qgis_process help <id> --json` 的实时输出为准;技能目录只读,输出数据写会话工作区。
308
- - **执行环境**:命令交给 dsh 的 shell 工具(Windows 用 `pwsh`;仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行)。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`。
309
- - **先探测版本**:`qgis_process --version`(QGIS 4.2.3 或 LTR 3.44.15)、`qgis_process list`;低于 3.16 没有 `qgis_process`,只能改用 PyQGIS 脚本;`--no-python`、`--skip-loading-plugins` 可显著加快启动。
310
- - **验证产物**:`run ... --json` 里的 `results.OUTPUT` 是实际写出的绝对路径,再用 `ogrinfo -so`(矢量)或 `gdalinfo -json`(栅格)核对要素数、CRS、范围;日志中出现 `returned non-zero` 说明算法内部失败,不要只看进程退出码。
311
- - **参数约定**:`--` 之后的参数不带前导 `--`;枚举传数字索引(`help --json` 里的 `available_options` 是映射表);多值参数重复同一键(`LAYERS=a.shp LAYERS=b.shp`);路径含空格或中文时加引号,尽量用绝对路径。
312
- - **常见报错**:`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`。
313
- - **安全与权限**:`OUTPUT=` 指向已有文件会被覆盖;`--project_path` 会加载项目内的数据源与凭证,注意不要把含密码的项目传给外部环境;启动 Docker 或安装 QGIS 前先征得用户同意,长任务放后台作业。
307
+ 目标:把 `data/points.shp` 做 50 m 缓冲区写入 GeoPackage,并在 CI 中批量重复同一流程。
308
+
309
+ ### 1. 先用 help 确认参数,不要凭记忆
310
+
311
+ ```bash
312
+ qgis_process help native:buffer --json > buffer-help.json
313
+ ```
314
+
315
+ 读取 `parameters` 中 `INPUT` / `DISTANCE` / `SEGMENTS` / `OUTPUT` 的名称与类型;`DISTANCE` 是 `distance` 类型,单位取图层 CRS 单位(投影坐标系下即米,地理坐标系下是度,极易算错)。
316
+
317
+ ### 2. 运行算法写出 GPKG
318
+
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
+ ```
335
+
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 脚本 |
314
367
 
315
368
  ---
316
369
 
@@ -329,19 +382,15 @@ qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp
329
382
 
330
383
  ---
331
384
 
332
- ## 常见问题
385
+ ## AI 使用建议
333
386
 
334
- | 问题 | 解决方案 |
335
- |------|---------|
336
- | 提示 `command not found: qgis_process` | 将 QGIS 的 `bin` 目录加入 `PATH`;Windows 下改用 OSGeo4W Shell 运行 |
337
- | 无显示器的服务器上崩溃或卡住 | 设置环境变量 `QT_QPA_PLATFORM=offscreen` |
338
- | `Algorithm <id> not found!` | 用 `qgis_process list` 确认算法 ID 与 Provider 前缀(如 `native:`、`gdal:`) |
339
- | 缺少必填参数 | 先用 `qgis_process help <id> --json` 查看参数名、类型与默认值 |
340
- | 枚举参数报错 | 枚举值需传数字索引,`help --json` 中的 `available_options` 提供索引映射 |
341
- | 多值参数只生效一项 | 在 `--` 之后多次指定同一参数(如 `LAYERS=a.shp LAYERS=b.shp`) |
342
- | 路径含空格或中文时报错 | 使用绝对路径并对参数值加引号 |
343
- | 启动速度慢 | 不需要 Python/插件时添加 `--no-python` 与 `--skip-loading-plugins` |
344
- | 模型/脚本或算法不可用 | 报 `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 脚本 |
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 前先征得用户同意,长任务放后台运行。
345
394
 
346
395
  ---
347
396
 
@@ -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
- ## 参考资源
214
+ ## AI 使用建议
212
215
 
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>
219
-
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,12 +229,11 @@ location /qgis {
228
229
 
229
230
  ---
230
231
 
231
- ## DeepSeek Harness 使用建议
232
+ ## 参考资源
232
233
 
233
- - **加载与引用**:用 `skill("qgis-server")` 加载(用户也可输入 `/qgis-server`);本技能没有 reference 子目录,服务能力以 `GetCapabilities` 实测为准;技能目录只读,配置片段与导出的能力文档写到会话工作区。
234
- - **执行环境**:命令交给 dsh 的 shell 工具(Windows 用 `pwsh`;仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行),Windows 上 `curl` 要写 `curl.exe`;Apache/Nginx 片段属于目标服务器配置,本机会话改不了远端,需在主机上执行或用容器验证。
235
- - **先探测版本**:用同一安装的 `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 与服务端大版本应一致。
236
- - **验证服务**:先 `curl "http://localhost/cgi-bin/qgis_mapserv.fcgi?MAP=/data/world.qgz&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities"` 存盘后核对 `<Service>` 与 `<Layer>` 清单,再测 `GetMap` 出图(PNG 可 `read_image` 看是否空白)、`GetFeature`、`GetTile`。
237
- - **常见报错**:`Service unknown or unsupported` 是缺 `SERVICE`/`MAP` 参数而非服务故障;`GetMap` 空白先查 `MAP` 路径可读性与项目 `OWS Server` 页的 `published` 勾选,再查 CRS/`BBOX`。
238
- - **日志与生效**:`QGIS_SERVER_LOG_STDERR=1` 交给 journald 或容器日志;`QGIS_SERVER_LOG_FILE` 已废弃,不要再用;`QGIS_SERVER_*` 改动要重启 FCGI 进程(或容器)才生效。
239
- - **安全与权限**:启动容器、开放端口、改 Web 服务器配置前先征得用户同意;`GetPrint` 在无 X 的 Linux 上需 `Xvfb`;项目文件可能含数据库凭证,命令与回答里不要回显密码。
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>