@dsh-gis/dsh-opengis-skill 0.1.2 → 0.1.3

package/assets/nettopologysuite/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nettopologysuite
-description: "Use when performing 2D computational geometry in .NET — spatial predicates, overlay operations, buffering, WKT/WKB I/O. NetTopologySuite: the .NET port of JTS, available via NuGet for spatial analysis in C# applications."
+description: "Use when doing 2D computational geometry in .NET with NuGet NetTopologySuite 2.6.0 — GeometryFactory with SRID, Contains/Intersects predicates, Intersection/Union/Buffer overlays, STRtree, GeometryFixer, WKT/WKB/GeoJSON I/O, Shapefile via IO.Esri, and EF Core spatial queries on SQL Server/Npgsql."
 tags:
   - dotnet
   - csharp
@@ -38,13 +38,13 @@ NTS 与 JTS API 几乎一一对应（C# 命名风格）：
 ## 环境准备
 
 ```bash
-dotnet add package NetTopologySuite
-dotnet add package NetTopologySuite.IO.GeoJSON
-dotnet add package NetTopologySuite.IO.Esri.Shapefile   # Shapefile 读写（Shapefile.ReadAllFeatures 等）
-dotnet add package ProjNet                              # 坐标变换（可选）
+dotnet add package NetTopologySuite --version 2.6.0
+dotnet add package NetTopologySuite.IO.GeoJSON --version 4.0.0
+dotnet add package NetTopologySuite.IO.Esri.Shapefile --version 1.2.0   # Shapefile 读写（Shapefile.ReadAllFeatures 等）
+dotnet add package ProjNet --version 2.1.0                              # 坐标变换（可选）
 ```
 
-**.NET 6+** 推荐。
+**.NET 6+** 推荐；IO 包需与主库 2.6 对齐（IO.GeoJSON 4.0.0 / IO.Esri.Shapefile 1.2.0 / ProjNet 2.1.0）。
 
 ---
 
@@ -228,21 +228,19 @@ foreach (var p in points) if (prep.Contains(p)) ...
 | Z/M 坐标丢失 | 配置 `WKBWriter` 的 `HandleOrdinates` |
 | Buffer 慢 | 减小 quadrantSegments、并行处理 |
 | Shapefile 读取写法报错 | 使用 `NetTopologySuite.IO.Esri.Shapefile` 包与 `NetTopologySuite.IO.Esri` 命名空间（`Shapefile.ReadAllFeatures`） |
-| 依赖版本不匹配（NTS 2.6 与旧 IO 包） | 各 IO 包选择与 NetTopologySuite 2.6 兼容的最新版本 |
+| 依赖版本不匹配（NTS 2.6 与旧 IO 包） | 对齐版本：IO.GeoJSON 4.0.0、IO.Esri.Shapefile 1.2.0、ProjNet 2.1.0 |
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-
-### 关键注意事项
-
-- **GeometryFactory 共享**：固定 SRID，复用 `GeometryFactory` 实例
-- **拓扑异常修复**：无效几何使用 `GeometryFixer.Fix()` 修复
-- **PreparedGeometry**：重复空间关系判断时使用 `PreparedGeometryFactory.Prepare()` 大幅提速
-- **STRtree 批量查询**：先 `Build()` 再 `Query()`，大数据量场景优于逐几何判断
-- **WKB vs WKT**：WKB 比 WKT 更快更紧凑，数据库交互优先使用 WKB
-- **Z/M 坐标**：`WKBWriter` 需配置 `HandleOrdinates` 保留 Z/M 坐标
+- **加载与引用**：`skill("nettopologysuite")` 加载；技能目录只读，示例工程与测试数据写到会话工作区。
+- **执行环境**：命令交给 dsh 的 `pwsh`；先 `dotnet --version` 确认 SDK 6.0+，`dotnet restore` 需要访问 NuGet。
+- **先探测版本**：`dotnet list package` 核对 `NetTopologySuite` 2.6.0、`NetTopologySuite.IO.GeoJSON` 4.0.0、`NetTopologySuite.IO.Esri.Shapefile` 1.2.0、`ProjNet` 2.1.0；IO 包与主库错配是常见编译/运行期报错源。
+- **验证产物**：`dotnet build` 后跑 `dotnet test`，或最小控制台做 WKT 往返 + `IsValid` 断言；`GeoJsonConverterFactory` 序列化后再反序列化，比对坐标数而不是只打日志。
+- **失败信号**：`TopologyException` 先 `GeometryFixer.Fix`；程序集加载/`TypeInitializationException` 多为 IO 包版本不匹配；EF Core 类型冲突是同时引了 `Microsoft.SqlServer.Types`。
+- **注意事项**：NTS 的 SRID 只是元数据、计算在平面进行，跨投影交给 ProjNet；`WKBWriter` 默认丢 Z/M，需设 `HandleOrdinates`。
+- **按需读文件**：本 SKILL 代码块较多，先按章节标题定位再用 `read` 取行区间，比整篇读更省上下文。
 
 ## NTS 家族与相关库
 

package/assets/opengis-all/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opengis-all
-description: "Use when navigating end-to-end GIS workflows — discover the full toolchain from GDAL data processing through GeoServer publishing to CesiumJS/OpenLayers visualization. One-stop index covering the complete open-source GIS data pipeline."
+description: "Use when navigating end-to-end GIS workflows — GDAL CLI/API (ogr2ogr, gdalwarp, gdal_calc.py), qgis_process and PyQGIS analysis, GeoServer REST publishing, and OpenLayers/CesiumJS visualization. One-stop index covering the complete open-source GIS data pipeline."
 
 tags:
   - gis
@@ -91,7 +91,7 @@ export QT_QPA_PLATFORM=offscreen
 
 ```bash
 # Docker 方式（推荐）
-docker run -d -p 8080:8080 docker.osgeo.org/geoserver:3.0.1
+docker run -d -p 8080:8080 docker.osgeo.org/geoserver:3.0.2
 
 # 验证
 curl -u admin:geoserver "http://localhost:8080/geoserver/rest/about/version.json"
@@ -407,34 +407,14 @@ exporter.exportToPdf("/data/output.pdf", QgsLayoutExporter.PdfExportSettings())
 
 ---
 
-## AI 使用建议
-
-### 工具选择指南
-
-| 场景 | 推荐工具 | 原因 |
-|------|----------|------|
-| 快速格式转换 | GDAL 命令行（ogr2ogr / gdal_translate） | 最简洁，适合脚本 |
-| 复杂空间分析 | qgis_process 或 PyQGIS | 算法丰富，参数统一 |
-| 编程集成 | GDAL API 或 PyQGIS | 灵活控制，适合程序嵌入 |
-| 栅格波段运算 | gdal_calc.py | NumPy 语法，简单直观 |
-| DEM 分析 | qgis_process (gdal:slope 等) | 一行命令完成 |
-| 几何级别操作 | GDAL OGR API 或 PyQGIS QgsGeometry | 精确控制每个几何操作 |
-| 服务发布 | GeoServer REST API | 唯一选择，HTTP 接口标准 |
-| CI/CD 自动化 | qgis_process + GDAL CLI + curl | 命令行驱动，JSON 输出 |
-
-
-### 关键注意事项
-
-1. **始终使用绝对路径**：避免工作目录不确定导致文件找不到。
-2. **始终使用 `--json` 选项**：JSON 输出结构化、易解析，是 AI 最友好的交互方式。
-3. **先查 help 再构造参数**：`qgis_process help <id> --json` 确认参数定义。
-4. **Headless 环境设置 `QT_QPA_PLATFORM=offscreen`**：在无显示器的服务器上必须设置。
-5. **坐标系一致性**：空间运算前确保所有数据使用相同 CRS。
-6. **文件上传格式**：GeoServer 上传 Shapefile 时需打包为 ZIP，且 ZIP 内须含 `.shp`、`.shx`、`.dbf`、`.prj`。
-7. **GeoServer JSON 包装**：REST API 的 JSON 请求/响应均使用单层包装（如 `{"workspace":{...}}`）。
-8. **recurse 参数**：删除 GeoServer 工作空间/数据存储时，添加 `?recurse=true` 级联删除。
-9. **大数据优化**：启用 `GDAL_NUM_THREADS=ALL_CPUS`，增大 `GDAL_CACHEMAX`；PyQGIS 中使用 `QgsSpatialIndex`。
-10. **始终备份**：GDAL 可就地修改文件（如 `gdal_edit.py`），操作前做好备份。
+## DeepSeek Harness 使用建议
+
+- **加载与引用**：用 `skill("opengis-all")` 加载（用户也可输入 `/opengis-all`）；本页是阶段索引，详细步骤在 `reference/data-stages.md` 与 `reference/workflow-cheatsheets.md`，按当前阶段 `read`，不要一次全读。
+- **执行环境**：命令交给 dsh 的 shell 工具（Windows 用 `pwsh`；仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行）。示例是 Linux/bash 写法，按平台改写 `apt`、`/tmp`、`export` 与反引号；Windows 路径加引号。
+- **先探测工具链**：`gdalinfo --version`、`qgis_process --version`、`python3 -c "from osgeo import gdal; print(gdal.VersionInfo())"`、`curl -u admin:geoserver "http://localhost:8080/geoserver/rest/about/version.json"`；缺哪个阶段就加载相邻技能（如 `skill("gdal")`、`skill("qgis-process")`）。
+- **分阶段交付**：每阶段产物落盘到工作区（GeoPackage/COG/GeoJSON），下一阶段只读取产物；先用 `ogrinfo -so`、`gdalinfo -json` 看摘要，不要把大文件或大段输出贴进上下文。
+- **验证**：转换后重新打开结果核对 CRS、范围、要素数；发布后用 `curl` 回读 REST 资源或 `GetCapabilities`；无显示器环境设置 `QT_QPA_PLATFORM=offscreen`；`qgis_process` 参数先用 `qgis_process help <id> --json` 确认。
+- **安全**：`gdal_edit.py`、覆盖输出、GeoServer `?recurse=true` 删除均不可逆；先备份并确认路径，安装 GDAL/QGIS、启动服务或使用数据库凭据前先征得用户同意。
 
 ---
 

package/assets/opengis-daf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opengis-daf
-description: "Use when building plan-driven GIS data analysis or data quality-check pipelines with OpenGisDAF (.NET 10 / C# 14): define buffer, clip, intersect/containment checks, coordinate transform, field calculator, attribute/geometry QC rules purely in JSON plans, run the daf CLI, chain operators via DAG upstream bindings, output to GeoJSON/Shapefile/PostGIS, or extend with plugin operators loaded via AssemblyLoadContext."
+description: "Use when building JSON-plan GIS analysis or QC pipelines with OpenGisDAF (.NET 10 / C# 14) — daf validate/run, operators buffer/clip/intersect_check/containment_check/coordinate_transform, DAG upstream bindings, GeoJSON/Shapefile/PostGIS sinks, qcMode QC reports, AssemblyLoadContext plugins; also for \"zero tests ran\" exit code 5, missing --recurse-submodules GDAL build errors, or PostGIS Layer already exists. Plan-driven ETL."
 
 tags:
   - gis
@@ -237,19 +237,16 @@ dotnet demo/plugin/OpenGisDAF.PluginHostDemo/bin/Release/net10.0/OpenGisDAF.Plug
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **先读文档与 Demo**：优先阅读 `docs/quickstart.md`、`docs/plan-config-guide.md`、`docs/operator-reference.md`、`docs/cli-reference.md`，并对照 `demo/`（`demo/run-demo.ps1` / `run-demo.sh`）理解方案结构
-2. **先校验、再质检、后分析**：先用 `daf validate --plan <path>` 校验 21 条规则，再用 `qcMode: true` 的质检方案生成 `{plan}.qc-report.json` 修复数据，最后跑分析方案
-3. **串联用 upstream**：多步流程用 `InputBinding.type: "upstream"` 引用上游 item 输出，由 DAG 自动拓扑排序调度
-
-### 关键注意事项
-
-- **核心概念**：方案（AnalysisPlan）由 `items[]`（每项一次算子调用）与 `inputs`/`parameters`/`output` 组成，算子通过 `upstream` 绑定串成 DAG
-- **常见错误**：插件目录勿复制 `OpenGisDAF.Core.dll`（Type 不同源会被静默跳过）；`buffer` 单位与数据坐标系一致（度数坐标系需先 `coordinate_transform` 转米制投影）；PostGIS 目标表已存在会报错，绝不静默覆盖
-- **退出码**：`0` 成功、`1` 任何失败或跳过，便于 CI 判断
+- **加载与引用**：用 `skill("opengis-daf")` 加载（用户也可输入 `/opengis-daf`）；本技能没有 `reference/` 子目录，方案文档在上游仓库 `docs/`；技能目录只读，方案 JSON 与输出写到会话工作区。
+- **执行环境**：先 `dotnet --version`，必须是 **10.0**（仓库 `global.json` 锁定），Windows 用 `pwsh`；克隆必须 `git clone --recurse-submodules`，漏了子模块 `opengis-utils-for-net` 会在编译期报 GDAL 绑定类型缺失。
+- **源码构建（无 NuGet 包）**：`dotnet build` 或 `./build.sh`，再 `dotnet run --project src/OpenGisDAF.Cli -- help` 确认 CLI 可用；这是自有项目，不要写 `dotnet add package OpenGisDAF`。
+- **测试两步走**：`dotnet build OpenGisDAF.slnx -c Release` 后 `dotnet test OpenGisDAF.slnx -c Release --no-build`——同一条 `dotnet test` 在 xunit.v3 工具链下会报“运行了零个测试”并以退出码 5 失败。
+- **验证产物**：先 `daf validate --plan plans/my.json`（只校验 21 条规则）再 `daf run --plan plans/my.json`；退出码 `0` 才是成功（失败或跳过都返回 1），随后重开输出 GeoJSON 核对 `crs` 与要素数，并查看 `{plan}.qc-report.json` 的 `totalChecked/failed/passRate`（仅 `qcMode: true` 才生成）。
+- **典型误操**：`buffer` 的 `distance` 单位随数据坐标系（EPSG:4326 下 800 就是 800 度），先 `coordinate_transform` 转米制；`daf operator import` 只对当前进程有效，要让插件参与 `daf run` 必须用同进程宿主（`demo/plugin/OpenGisDAF.PluginHostDemo`）。
+- **插件坑**：插件工程引用 `OpenGisDAF.Core` 时必须 `Private="false" ExcludeAssets="runtime"`，把 `OpenGisDAF.Core.dll` 复制进插件目录会让 `IOperator` 类型不同源，算子被静默跳过。
+- **安全与权限**：PostGIS 输出的 `encryptedPassword` 只接受当前用户上下文生成的密文（DPAPI / AES-256-GCM），明文或跨用户密文会失败；`daf plan` 写入 `%APPDATA%\opengis-daf\plans`，覆盖已有方案或输出文件前先确认路径。
 
 ---
 

package/assets/opengis-utils-for-java/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opengis-utils-for-java
-description: "Use when needing common GIS utility functions in Java — CRS utilities, geometry helpers, format converters, spatial validation. OpenGIS Utils for Java: convenience toolkit for Java GIS projects."
+description: "Use when needing common GIS utilities in Java — OguLayerUtil layer read/write, GeometryUtil 60+ ops, CrsUtil CGCS2000 (EPSG:4490, 4502-4554), Shapefile/GeoJSON/FileGDB/PostGIS/land TXT I/O, topology validation; also for GDAL UnsatisfiedLinkError on gdal_jni, missing osgeo repo on GeoTools, or resolving com.znlgis.ogu4j:ogu4j:1.0.0 that is not on Maven Central. OGU4J."
 tags:
   - java
   - gis
@@ -277,24 +277,16 @@ RuntimeException
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **选择引擎**：`GisEngineType.AUTO` 自动选择最优引擎（GDAL 优先）
-2. **读取数据**：使用 `OguLayerUtil.readLayer()` 统一入口读取各类矢量格式
-3. **空间分析**：JTS Geometry 对象用 `GeometryUtil`（60+ 方法），WKT 字符串用 `*Wkt` 后缀方法
-4. **坐标转换**：使用 `CrsUtil.transform()` 进行 CGCS2000 系列坐标系变换
-5. **写出结果**：使用 `OguLayerUtil.writeLayer()` 写出为目标格式
-
-### 关键注意事项
-
-- **始终使用 `OguLayerUtil` 作为主入口**：自动处理引擎选择和格式路由
-- **几何以 WKT 存储**：`OguFeature.geometry` 存储 WKT 字符串；空间运算时转为 JTS Geometry
-- **引擎选择**：`GEOTOOLS`（纯 Java，无原生依赖）vs `GDAL`（需本地库，支持 FileGDB）
-- **CGCS2000 坐标系**：EPSG:4490 为默认地理 CRS，投影 CRS 范围 EPSG:4502-4554
-- **Shapefile 字段名限 10 字符**：使用 `ShpUtil.formatFieldName()` 自动截断
-- **资源释放**：`DataStore` 和 OGR `DataSource` 必须在 finally 块中释放
+- **加载与引用**：用 `skill("opengis-utils-for-java")` 加载（用户也可输入 `/opengis-utils-for-java`）；`reference/common-tasks.md` 按需 `read`，路径相对加载结果中的 Base directory；技能目录只读，验证工程建在会话工作区。
+- **执行环境**：先 `java -version` 与 `mvn -version`（需 JDK 17+、Maven 3.8+），Windows 用 `pwsh`；`mvn -v` 里显示的 JDK 才是 Maven 实际使用的，与 shell 的 `java` 不一致时改 `JAVA_HOME` 再重试。
+- **源码安装（本库未发布到 Central）**：`git clone https://github.com/znlgis/opengis-utils-for-java.git` 后 `mvn install -DskipTests`，产物落在 `~/.m2/repository/com/znlgis/ogu4j/ogu4j/1.0.0/`；用 `mvn dependency:tree -Dincludes=com.znlgis.ogu4j` 确认坐标可解析。不要在 `pom.xml` 里直接写 `ogu4j:1.0.0` 后指望从 Central 下载。
+- **仓库与网络**：GeoTools 依赖不在 Central，`pom.xml` 必须带 `https://repo.osgeo.org/repository/release/`，否则 `Could not resolve dependencies for org.geotools:*`；离线或私服缺包时如实报告依赖不可下载，不要自行换版本或加未知仓库。
+- **原生 GDAL 匹配**：GDAL 引擎绑定 `org.gdal:gdal` 3.13.0，本机需装 GDAL 3.13.x 且 `java.library.path` 能找到 `gdal_jni`（Windows 上 `java -XshowSettings:properties -version 2>&1 | Select-String library.path`）；报 `UnsatisfiedLinkError: no gdal_jni in java.library.path` 说明原生库缺失或版本不符，此时改用 `GisEngineType.GEOTOOLS`。
+- **验证产物**：写最小 main 读一个 Shapefile/GeoJSON → `OguLayerUtil.readLayer(DataFormatType.SHP, path, null, null, null, GisEngineType.AUTO)`，打印 `layer.getWkid()`、`layer.getFeatureCount()`，再 `writeLayer` 成 GeoJSON 并重新读回比对要素数与 CRS；`mvn -q -DskipTests package` 只说明能编译。
+- **常见误操**：`AUTO` 在本机有原生 GDAL 时会优先走 GDAL，想复现纯 Java 结果必须显式传 `GisEngineType.GEOTOOLS`；`OguFeature.geometry` 是 WKT 字符串，做运算前先 `GeometryUtil.wkt2Geometry()`；`DataStore` 与 OGR `DataSource` 要在 `finally` 里释放，否则文件被占用后 `writeLayer` 覆盖失败。
+- **安全与权限**：PostGIS 连接串（`PG: host=... password=...`）里的密码不要回显到输出；`mvn install` 会写 `~/.m2`、示例代码会写 `/data` 等绝对路径，覆盖已有数据前先确认路径并征得用户同意。
 
 ## Important Notes for AI Developers
 

package/assets/opengis-utils-for-net/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opengis-utils-for-net
-description: "Use when needing common GIS utility functions in .NET/C# — CRS utilities, geometry helpers, format converters, spatial validation. OpenGIS Utils for .NET: convenience toolkit for .NET GIS projects."
+description: "Use when needing common GIS utilities in .NET/C# — OguLayerUtil ReadLayer/WriteLayer/ConvertFormat, GeometryUtil 50+ ops, CrsUtil CGCS2000 transforms, Shapefile/GeoJSON/FileGDB/GeoPackage/KML/PostGIS I/O; also for Unable to load DLL gdal / DllNotFoundException, GBK shapefile mojibake, or ArgumentException from Geojson2Wkt on a whole FeatureCollection. OpenGIS.Utils 1.1.2."
 tags:
   - dotnet
   - csharp
@@ -367,16 +367,16 @@ Properties: `GdbPath` (`string?`), `LayerNames` (`List<string>`)
 
 > 常用代码模式完整示例见 [reference/code-patterns.md](reference/code-patterns.md)
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-
-### 关键注意事项
-
-- **GDAL 自动初始化**：无需手动调用 `GdalConfiguration.ConfigureGdal()`
-- **GeoJSON 字符串可直接解析**：`Geojson2Wkt()` 和 `Geojson2Geometry()` 通过 GDAL 解析裸几何、`Feature` 或 `FeatureCollection`（取第一个要素的几何），无法解析时抛 `ArgumentException`；整文件请从文件加载
-- **几何以 WKT 存储**：`OguFeature.Wkt` 存储 WKT 字符串；多数 `GeometryUtil` 方法有 `*Wkt` 变体
-- **.NET 的 GDAL 实现**：`GEOTOOLS` 枚举值仅为兼容保留并重定向到 GDAL（Java 版本为双引擎）
-- **线程安全**：GDAL 初始化线程安全，但单个 GDAL 几何对象非线程安全
+- **加载与引用**：用 `skill("opengis-utils-for-net")` 加载（用户也可输入 `/opengis-utils-for-net`）；`reference/code-patterns.md`、`reference/util-classes.md` 按需 `read`，路径相对加载结果中的 Base directory；技能目录只读，验证工程建在会话工作区。
+- **执行环境**：先 `dotnet --version`；库目标 .NET Standard 2.0，可被 .NET Core 2.0+ / .NET 5+ / .NET Framework 4.6.1+ 引用，Windows 用 `pwsh`；用 `dotnet new console -o demo && cd demo` 起最小工程。
+- **依赖坐标**：`dotnet add package OpenGIS.Utils --version 1.1.2`（NuGet 最新 1.1.2），原生 GDAL 运行时随包分发（`MaxRev.Gdal.Universal`）；用 `dotnet list package --include-transitive | Select-String OpenGIS.Utils` 核对解析出的版本，`NU1101`/`NU1102` 表示源或版本不可用，如实报告而不是改版本号重试。
+- **平台与原生库**：运行时与 RID 绑定，`DllNotFoundException` 或 `Unable to load DLL 'gdal'` 多因 `-r win-x64`/`linux-x64` 与运行环境不一致；`dotnet publish -r win-x64` 后跑发布目录，不要只跑 `bin/Debug` 里的半成品。
+- **验证产物**：最小程序 `OguLayerUtil.ReadLayer(DataFormatType.SHP, path)` 读入（完整重载见 `reference/code-patterns.md`）→ 打印 `layer.GetFeatureCount()` 与 `layer.Wkid`，再 `WriteLayer` 写出 GeoJSON 并重新读回，核对要素数与 CRS；`dotnet build` 成功只说明编译通过，GDAL 原生库是运行期才加载的。
+- **常见误操**：`Geojson2Wkt()` 只接受裸几何 / `Feature` / `FeatureCollection` 字符串，传整文件内容会抛 `ArgumentException`，整文件走 `OguLayerUtil.ReadLayer`；`OgrGeometry` 是 `IDisposable`，用完 `Dispose()`；`GEOTOOLS` 枚举仅为兼容，在 .NET 版实际重定向到 GDAL。
+- **构建与测试**：在仓库 checkout 内 `dotnet build OpenGIS.Utils.sln`、`dotnet test tests/OpenGIS.Utils.Tests/`，输出在 `bin/`、`obj/`（不要提交）；只看某一条测试时加 `--filter FullyQualifiedName~关键字`。
+- **安全与权限**：写入 Shapefile/GeoPackage 会覆盖同名文件，执行前确认目标路径；PostGIS 连接串与 GDAL 配置里的密码不要回显；`dotnet restore`、安装 SDK 或改 `NuGet.config` 前先征得用户同意。
 
 ## 典型工作流
 

package/assets/openlayers/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openlayers
-description: "Use when adding interactive 2D maps to web applications — WMS/WFS/WMTS layers, vector styling, map controls, popups. OpenLayers: the most full-featured open-source JavaScript web mapping library."
+description: "Use when adding interactive 2D maps to web apps with npm ol 10.11.0 — Map/View, fromLonLat to EPSG:3857, WMS/WMTS/XYZ sources, MVT with featureClass, Draw/Modify/Snap interactions, or debugging blank layers (missing setStyle), offset centers and ol/... module-not-found errors."
 tags:
   - javascript
   - web
@@ -259,16 +259,16 @@ new VectorLayer({ source: clusterSource, style: clusterStyleFn });
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-
-### 关键注意事项
-
-- **投影一致**：经纬度需 `fromLonLat()` 转为 EPSG:3857；自定义投影需注册 proj4
-- **WMS 参数**：`LAYERS` 参数需使用完整名称（如 `workspace:layer`），检查 CORS
-- **矢量瓦片字段**：MVT 格式需设置 `featureClass: Feature` 保留属性
-- **样式缓存**：使用函数式 Style 时，缓存 Style 实例避免重复创建
-- **批量添加**：使用 `addFeatures([])` 而非循环 `addFeature`，显著提升性能
+- **加载与引用**：用 `skill("openlayers")` 加载（用户也可输入 `/openlayers`）；本技能无 reference 子目录，示例代码直接写进会话工作区工程，技能目录只读。
+- **执行环境**：`npm install`、`npm run build` 交给 `pwsh`；Windows 下 `npm` 是 `npm.cmd`，长构建用后台作业并把输出落盘再读。
+- **先探测版本**：`npm ls ol`（未装则 `npm view ol version`）；本技能按 10.11.0 编写，只使用 `ol/Map.js`、`ol/layer/Tile.js` 等 ESM 子路径，旧版 `ol.source.*` 全量命名空间写法不要混用。
+- **验证产物**：`npm run build` 后用 `npx serve dist`（或 `python -m http.server 5173 -d dist`）起静态服务，`curl.exe -I http://localhost:5173/` 与打包出的 `assets/*.js` 应为 200；DSH 不打开浏览器，请用户看页面与控制台，有截图再用 `read_image`。
+- **投影**：经纬度必须 `fromLonLat()` 转 EPSG:3857，自定义投影先 `register(proj4)`；否则中心点偏移或图层不显示。
+- **图层样式**：矢量图层不设样式默认不渲染，务必 `setStyle()`；MVT 源要用 `MVT({ featureClass: Feature })` 才能保留属性。
+- **常见症状**：WMS 空白先查 CORS、`LAYERS` 全名与 `SRS`；`ol/...` 模块找不到说明打包器没按 ESM 解析；容器尺寸变化后调用 `map.updateSize()`。
+- **安全与权限**：装包、起 dev server、对外暴露端口前先征得用户同意；内网 WMS 地址与凭据不要写进示例。
 
 ## 相关技能
 

package/assets/pdal/SKILL.md

@@ -339,10 +339,12 @@ for las_file in glob.glob("tiles/*.las"):
 - **geopandas** — Python 矢量数据处理：[../geopandas/SKILL.md](../geopandas/SKILL.md)
 - **shapely** — 几何对象计算，与裁剪范围构造相关：[../shapely/SKILL.md](../shapely/SKILL.md)
 
-## AI 使用建议
-
-1. 探索数据先跑 `pdal info input.las --summary`，确认坐标系与范围后再设计 pipeline
-2. 生成 pipeline 后先用 `pdal pipeline --validate` 校验，再实际运行
-3. 大文件避免一次性标准模式处理，优先流式 stage 或分块
-4. 需要修改参数时优先在 pipeline JSON 中修改，而不是堆叠长命令行
-5. Python 场景用 `json.dumps` 构造 stage 列表，便于程序化生成与复用
+## DeepSeek Harness 使用建议
+
+- **加载与引用**：用 `skill("pdal")` 加载（用户也可输入 `/pdal`）；本技能没有 reference 子目录，stage 参数以 `pdal --options filters.smrf` 这类命令现场核对为准；技能目录只读，pipeline JSON 与输出点云写到会话工作区。
+- **执行环境**：命令交给 dsh 的 shell 工具（Windows 用 `pwsh`；仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行）。正文的 `sudo apt`、`conda activate` 是 Bash/Linux 写法，Windows 改用 OSGeo4W 或 conda；Docker 挂载写成 `docker run --rm -v "${PWD}:/data" -w /data pdal/pdal pdal pipeline pipeline.json`。
+- **先探测版本**：`pdal --version`（应为 2.10.2）、`pdal --drivers`；`pdal ground` 自 2.6 起弃用，低版本缺少 `filters.expression` 等 stage，回答里要写明按哪个版本写。
+- **验证产物**：`pdal info --summary out.laz` 核对 `num_points`、`bounds`、`srs`；DEM 用 `gdalinfo -json dem.tif` 核对波段数与范围；pipeline 先 `pdal pipeline --validate` 再实跑，不要只看退出码。
+- **注意执行模式**：stream mode 不能跑 `filters.outlier`、`filters.smrf` 这类需要全局统计的 stage，大文件先按 tile 拆分；`writers.gdal` 默认 `output_type: "all"` 会输出多波段，单波段 DEM 要显式写 `idw`/`mean`。
+- **Python 场景**：`pipeline.execute()` 返回处理的点数而不是数组，数据在 `pipeline.arrays`（NumPy 结构化数组）；排查失败看 `pipeline.log`，不要只看异常栈。
+- **安全与权限**：`pdal translate` 与各 writer 会覆盖同名输出，先确认目标文件名；`pdal pipeline --stdin` 和 Docker 挂载以调用者/容器用户写盘，Linux 下注意属主；安装 PDAL 或下载大点云前先征得用户同意。

package/assets/postgis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: postgis
-description: "Use when extending PostgreSQL with spatial data types, spatial indexes (GiST/SP-GiST), geometry functions (ST_Intersects, ST_Buffer, ST_Transform), and spatial queries. PostGIS: the most widely used open-source spatial database extension."
+description: "Use when extending PostgreSQL with PostGIS 3.6.4 — geometry/geography/raster types, GiST and KNN <-> indexes, ST_Intersects/ST_Buffer/ST_Transform/ST_AsMVT, shp2pgsql -I and raster2pgsql import, and fixing \"Operation on mixed SRID\", slow spatial joins, and invalid polygons with ST_MakeValid."
 tags:
   - postgresql
   - database
@@ -30,7 +30,7 @@ PostGIS 是基于 PostgreSQL 的开源空间数据库扩展，遵循 OGC Simple
 - **坐标参考系**：内置 6000+ EPSG 投影，自动 ST_Transform
 - **数据导入导出**：与 GDAL/ogr2ogr/shp2pgsql 无缝集成
 
-**版本要求：** PostgreSQL 12–18 配合 PostGIS 3.x（最新稳定版 3.6.4，3.7 处于 RC 阶段，截至 2026-10）；GEOS ≥ 3.8（部分新算子需 GEOS ≥ 3.14）
+**版本要求：** PostgreSQL 12–18 配合 PostGIS 3.x（最新稳定版 3.6.4；3.7 仍处 RC 阶段、尚未正式发布，候选版为 3.7.0rc2，截至 2026-10）；GEOS ≥ 3.8（部分新算子需 GEOS ≥ 3.14）
 
 ---
 
@@ -228,17 +228,15 @@ SELECT ST_Clip(rast, geom, true) FROM dem, region WHERE region.id=1;
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-
-### 关键注意事项
-
-- **geometry vs geography**：`geometry`（平面计算，速度快）vs `geography`（球面计算，距离单位为米）
-- **SRID 必须一致**：跨 SRID 运算必须先 `ST_Transform`，否则报 `Operation on mixed SRID`
-- **用 `&&` 让查询走索引**：`WHERE geom && ST_MakeEnvelope(...)` 粗筛 + `ST_Within` 精筛
-- **KNN 用 `<->`**：`ORDER BY geom <-> point LIMIT 10` 走 GiST 索引，比 `ST_Distance` 快几个数量级
-- **大几何优化**：使用 `ST_Subdivide` 切分大面几何加速空间连接
-- **导入后 ANALYZE**：大批量数据导入后执行 `VACUUM ANALYZE` 更新统计信息
+- **加载与引用**：`skill("postgis")` 加载；技能目录只读，SQL 脚本、导出与测试数据写到会话工作区。
+- **执行环境**：命令交给 dsh 的 `pwsh`（Windows 用 `psql.exe`，或 `docker exec -i pg psql -U postgres`）；psql 元命令（`\d`、`\c`）用 `psql -c "\d poi"` 单条传入，别依赖交互式会话。
+- **先探测版本**：`psql -c "SELECT version(), PostGIS_Full_Version();"` 核对 PostgreSQL、PostGIS 3.6.4 与 GEOS/PROJ；扩展缺失时先看 `SELECT * FROM pg_available_extensions WHERE name LIKE 'postgis%';`。
+- **验证产物**：导入后别只看 `INSERT 0 n`，跑 `SELECT count(*), ST_SRID(geom), ST_IsValid(geom) FROM t GROUP BY 2,3;` 核对要素数、SRID 与无效几何；性能结论必须用 `EXPLAIN (ANALYZE, BUFFERS)` 证明索引被使用。
+- **写操作回读**：`CREATE/ALTER`、`UpdateGeometrySRID` 或批量 `UPDATE` 后回读 `\d+ t` 与 `geometry_columns`，确认列类型与 SRID 真的落库。
+- **安全与权限**：密码不要写进命令行或报告（用 `PGPASSWORD`/`.pgpass`/连接串环境变量）；`DROP TABLE/SCHEMA`、整表改写 geom、`VACUUM FULL`、重启 PostgreSQL 前必须先向用户确认并备份。
+- **大表 DDL**：`UPDATE`/`CREATE INDEX` 尽量放在可控事务里避免长时间锁表；`CREATE INDEX CONCURRENTLY` 不能包在事务块中执行。
 
 ## 相关技能
 

package/assets/proj/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: proj
-description: "Use when performing coordinate reference system (CRS) transformation, reprojection, datum shift or EPSG lookup from the command line — converting coordinates between WGS 84, UTM, Web Mercator and CGCS2000. PROJ: the OSGeo library that powers GDAL/QGIS transformations, with projinfo, cs2cs, proj, cct and the proj.db SQLite database."
+description: "Use when transforming coordinates or inspecting CRS definitions from the command line — cs2cs, projinfo -s/-t, proj projection math, cct, EPSG lookup, datum shift with grid files, WKT/PROJJSON export, or debugging \"Cannot find proj.db\" and latitude-first axis order. PROJ 9.9.0: the OSGeo engine behind GDAL/QGIS, with the proj.db SQLite database."
 tags:
   - proj
   - crs
@@ -335,23 +335,12 @@ echo 116.391 39.907 | cs2cs EPSG:4326 EPSG:4547 --only-best
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **先查询、后转换**：任何转换前先用 `projinfo <code>` 确认 CRS 名称与轴序，再用 `projinfo -s A -t B` 确认转换路径。
-   ```bash
-   projinfo EPSG:4490
-   projinfo -s EPSG:4326 -t EPSG:4547 --summary
-   ```
-2. **用结构化输出便于解析**：`projinfo -o PROJJSON -q EPSG:4326 | jq .`，避免解析缩进文本。
-3. **点转换用 `cs2cs`，文件重投影用 GDAL**：`cs2cs` 只处理坐标流；`ogr2ogr -t_srs`/`gdalwarp -t_srs` 处理数据文件，二者共享 `PROJ_DATA`。
-4. **高精度场景显式下载网格**：先 `projsync --bbox ...` 或设 `PROJ_NETWORK=ON`，再加 `--only-best` 验证。
-5. **核对环境变量**：脚本中显式设置 `PROJ_DATA`，避免依赖不可控的默认搜索路径。
-
-### 关键注意事项
-
-- **不要凭记忆写 proj 字符串**：参数名（如 `+lat_ts`、`+zone`、`+ellps`）须与文档一致，优先用 EPSG 代码。
-- **轴序是最常见的错误来源**：`EPSG:4326` 纬度在前，`proj` 命令经度在前。
-- **转换前确认单位与高程**：三维转换需 `--3d`，并确认目标 CRS 的高程基准（如 EGM96）。
-- **版本即数据版本**：PROJ 9.x 的 `proj.db` 布局随版本变化，混用不同版本会报版本不匹配错误。
+- **加载与引用**：用 `skill("proj")` 加载（用户也可输入 `/proj`）；本技能没有 reference 子目录，正文即全部内容，更细的参数用 `projinfo --help`、`cs2cs --help`、`projinfo --list-crs` 现场查；技能目录只读，脚本与结果写到会话工作区。
+- **执行环境**：命令交给 dsh 的 shell 工具（Windows 用 `pwsh`；仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行）。正文的 `export PROJ_DATA=...` 在 PowerShell 写作 `$env:PROJ_DATA = "C:\OSGeo4W\share\proj"`；heredoc（`<<EOF`）在 pwsh 不可用，改用管道 `"56 12" | cs2cs EPSG:4326 EPSG:25832` 或先把输入写成文件再重定向。
+- **先探测版本**：`projinfo --version`（同时打印 `proj.db` 路径）、`projinfo --searchpaths`；本技能按 PROJ 9.9.0 编写，低于 9.1 用 `PROJ_LIB` 而非 `PROJ_DATA`，低于 9.3 的 `proj` 不能直接接受 `EPSG:xxxx`。
+- **验证转换**：用已知点对拍——`echo "116.391 39.907" | cs2cs EPSG:4326 EPSG:32650` 应得到东坐标约 45 万、北坐标约 442 万，量级不对通常是轴序或单位问题；结构化核对用 `projinfo -o PROJJSON -q EPSG:4326`，转换路径用 `projinfo -s A -t B --summary` 看候选操作与精度。
+- **轴序与降级**：`EPSG:4326` 纬度在前（输入先 lat 后 lon），`proj` 命令内部经度在前要用 `-r`；高精度转换加 `--only-best`，否则缺网格时会静默退回精度更低的操作。
+- **大输出处理**：`projinfo EPSG:4326` 的 WKT 有上百行，重定向到文件再分段 `read`；批量转换把 `cs2cs EPSG:4326 EPSG:3857 points.txt` 一次跑完，不要逐行起进程。
+- **安全与权限**：`projsync --all` 会从 CDN 下载数 GB 网格、`PROJ_NETWORK=ON` 也会联网，先确认网络与磁盘；`sqlite3 proj.db` 只做只读查询，不要写库；改 `PROJ_DATA` 会影响同机 GDAL/PostGIS，先征得用户同意。

package/assets/pyqgis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pyqgis
-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."
+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."
 tags:
   - python
   - qgis
@@ -380,49 +380,15 @@ qgs.exitQgis()
 
 更多工作流（批量缓冲融合、栅格裁剪、打印布局导出）见 [reference/processing-rendering.md](reference/processing-rendering.md)。
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **初始化环境**：独立脚本需 `QgsApplication` 初始化；QGIS 控制台中可直接使用
-2. **加载数据**：使用 `QgsVectorLayer` / `QgsRasterLayer` 加载数据源
-3. **执行分析**：优先使用 `processing.run()` 调用算法（参数统一、算法丰富）；精细操作使用 `QgsGeometry` 方法
-4. **导出结果**：使用 `QgsVectorFileWriter` 写出矢量，`QgsRasterFileWriter` 写出栅格
-5. **清理退出**：独立脚本调用 `qgs.exitQgis()`
-
-### 关键注意事项
-
-1. **始终检查图层有效性**：加载图层后必须检查 `layer.isValid()`，无效时检查路径和 Provider。
-2. **坐标系一致性**：空间运算前确保所有图层使用相同 CRS；使用 `native:reprojectlayer` 或 `QgsCoordinateTransform` 进行转换。
-3. **编辑模式**：修改图层数据需 `startEditing()` → 操作 → `commitChanges()`；失败可 `rollBack()`。
-4. **Processing 内存输出**：将 OUTPUT 设为 `'memory:name'` 可得到内存图层，避免创建临时文件。
-5. **椭球面计算**：对地理坐标（经纬度）计算距离/面积时，使用 `QgsDistanceArea` 并设置椭球体，或使用 Processing 算法指定椭球体。
-6. **Headless 环境**：无显示器的服务器上必须设置 `QT_QPA_PLATFORM=offscreen`。
-7. **文件路径使用绝对路径**：避免工作目录不确定导致文件找不到。
-8. **大数据量优化**：使用 `QgsSpatialIndex` 加速空间查询；使用 `QgsFeatureRequest` 限制返回字段和范围。
-9. **表达式语法**：字段名用双引号 `"field"`，字符串值用单引号 `'value'`。
-10. **QGIS 版本兼容**：部分 API 在不同版本间有变化，建议使用 LTR 版本（[查看当前 LTR](https://qgis.org/download/)）以获得稳定接口；QGIS 当前稳定版为 4.2.3（2026-09 发布），3.44 LTR（最新 3.44.15）仍受支持（截至 2026-10）。
-
-### 错误处理
-
-```python
-# 图层加载失败
-layer = QgsVectorLayer(path, name, provider)
-if not layer.isValid():
-    print(f"图层加载失败: {layer.error().message()}")
-
-# Processing 算法错误
-try:
-    result = processing.run("native:buffer", params, feedback=feedback)
-except Exception as e:
-    print(f"算法执行失败: {e}")
-
-# 编辑提交失败
-if not layer.commitChanges():
-    errors = layer.commitErrors()
-    print(f"提交失败: {errors}")
-    layer.rollBack()
-```
+- **加载与引用**：用 `skill("pyqgis")` 加载（用户也可输入 `/pyqgis`）；`reference/vector-raster-layers.md`、`reference/processing-rendering.md` 按需 `read`，路径相对 Base directory；技能目录只读，脚本、导出图与中间数据写到会话工作区。
+- **执行环境**：必须用 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"`。
+- **先探测版本**：`python -c "from qgis.core import Qgis; print(Qgis.QGIS_VERSION)"`；本技能同时覆盖 4.2.3（最新）与 3.44.15（LTR），4.x 与 3.x 存在 API 差异，回答里要写明按哪个版本写、低版本哪些类/方法不可用。
+- **验证产物**：独立脚本按 `QgsApplication` → `initQgis()` → 处理 → `exitQgis()` 收尾；写出后重开图层核对 `isValid()`、`featureCount()`、`crs().authid()`，`processing.run()` 的返回值只给路径，结果要二次打开；渲染或布局导出的 PNG 可用 `read_image` 看是否空白。
+- **模块名易错**：3D 模块是 `qgis._3d`（下划线，不是 `qgis.3d`），例如 `from qgis._3d import Qgs3DMapSettings`；`processing.run()` 前必须先 `Processing.initialize()`，否则报算法不存在。
+- **进程与日志**：批量脚本不要跨任务复用同一个 `QgsProject.instance()`；长任务放后台作业，QGIS 日志（`QgsApplication.messageLog()`）与 stderr 重定向到文件后分段 `read`。
+- **安全与权限**：`startEditing()`/`commitChanges()` 直接改源数据（Shapefile、PostGIS），先备份或把中间结果写 `memory:`；覆盖已有输出文件、安装 QGIS、把数据写进系统目录前先征得用户同意。
 
 ---
 

package/assets/qgis-process/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qgis-process
-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."
+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)."
 tags:
   - cli
   - qgis
@@ -302,37 +302,15 @@ qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp
 
 > 常用内置算法速查、参数类型参考与典型工作流示例见 [reference/algorithm-cheatsheet.md](reference/algorithm-cheatsheet.md)
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 推荐工作流
-
-1. **发现算法**：`qgis_process list` → 获取所有可用算法 ID
-2. **查看帮助**：`qgis_process help <algorithm_id> --json` → 获取参数定义的 JSON
-3. **构造参数**：根据 JSON 帮助信息构造参数
-4. **执行算法**：`qgis_process run <algorithm_id> --json -- PARAM=VALUE ...` 或通过 STDIN 传入 JSON
-5. **解析结果**：解析 JSON 输出获取结果路径和日志信息
-
-### 关键注意事项
-
-1. **始终使用 `--json` 选项**：JSON 输出结构化、易解析，是 AI 最友好的交互方式。
-2. **先查 help 再构造参数**：每个算法的参数名和类型不同，先用 `help --json` 确认参数定义。
-3. **枚举类型传数字索引**：枚举参数用数字（如 `0`、`1`）而非文字。help 输出的 `available_options` 提供了索引到含义的映射。
-4. **多值参数多次指定**：如 `LAYERS=a.shp LAYERS=b.shp`（在 `--` 之后，参数不带前导 `--`）。
-5. **复杂参数用 STDIN JSON**：字典类型的参数值适合通过 STDIN JSON 方式传入。
-6. **文件路径使用绝对路径**：避免工作目录不确定导致的文件找不到。
-7. **Headless 环境设置 `QT_QPA_PLATFORM=offscreen`**：在无显示器的服务器上必须设置。
-8. **需要项目文件的算法**：某些算法（如打印布局导出）需要通过 `--project_path` 指定项目文件。
-9. **取消正在运行的算法**：使用 `CTRL+C` 可取消执行中的算法。
-10. **`--no-python` 和 `--skip-loading-plugins` 可加速启动**：如果不需要第三方插件提供的算法，使用这两个选项可显著缩短启动时间。
-
-### 错误处理
-
-- 算法不存在：`Algorithm <id> not found!`
-- 缺少必填参数：`The following mandatory parameters were not specified`
-- 模型文件无效：`File <path> is not a valid Processing model!`
-- Python 脚本无效：`File <path> is not a valid Processing script!`
-- 算法不可在命令行使用：`The "<id>" algorithm is not available for use outside of the QGIS desktop application`
-- 需要项目文件：`The "<id>" algorithm requires a QGIS project to execute`
+- **加载与引用**：用 `skill("qgis-process")` 加载（用户也可输入 `/qgis-process`）；`reference/algorithm-cheatsheet.md` 按需 `read`，但算法参数一律以 `qgis_process help <id> --json` 的实时输出为准；技能目录只读，输出数据写会话工作区。
+- **执行环境**：命令交给 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`。
+- **先探测版本**：`qgis_process --version`（QGIS 4.2.3 或 LTR 3.44.15）、`qgis_process list`；低于 3.16 没有 `qgis_process`，只能改用 PyQGIS 脚本；`--no-python`、`--skip-loading-plugins` 可显著加快启动。
+- **验证产物**：`run ... --json` 里的 `results.OUTPUT` 是实际写出的绝对路径，再用 `ogrinfo -so`（矢量）或 `gdalinfo -json`（栅格）核对要素数、CRS、范围；日志中出现 `returned non-zero` 说明算法内部失败，不要只看进程退出码。
+- **参数约定**：`--` 之后的参数不带前导 `--`；枚举传数字索引（`help --json` 里的 `available_options` 是映射表）；多值参数重复同一键（`LAYERS=a.shp LAYERS=b.shp`）；路径含空格或中文时加引号，尽量用绝对路径。
+- **常见报错**：`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`。
+- **安全与权限**：`OUTPUT=` 指向已有文件会被覆盖；`--project_path` 会加载项目内的数据源与凭证，注意不要把含密码的项目传给外部环境；启动 Docker 或安装 QGIS 前先征得用户同意，长任务放后台作业。
 
 ---
 
@@ -363,6 +341,7 @@ qgis_process run /path/to/my_script.py -- INPUT=data.shp OUTPUT=result.shp
 | 多值参数只生效一项 | 在 `--` 之后多次指定同一参数（如 `LAYERS=a.shp LAYERS=b.shp`） |
 | 路径含空格或中文时报错 | 使用绝对路径并对参数值加引号 |
 | 启动速度慢 | 不需要 Python/插件时添加 `--no-python` 与 `--skip-loading-plugins` |
+| 模型/脚本或算法不可用 | 报 `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 脚本 |
 
 ---
 

package/assets/qgis-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qgis-server
-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."
+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."
 tags:
   - qgis
   - server
@@ -228,23 +228,12 @@ location /qgis {
 
 ---
 
-## AI 使用建议
+## DeepSeek Harness 使用建议
 
-### 关键注意事项
-
-- **`MAP` 必填**：几乎所有 QGIS 扩展请求都要求 `MAP` 指向存在的项目文件；用 `QGIS_PROJECT_FILE` 可设默认值。
-- **版本匹配**：生成项目的 Desktop 与服务端版本尽量一致，跨大版本先在小环境验证。
-- **日志优先 stderr**：`QGIS_SERVER_LOG_FILE` 已废弃，统一用 `QGIS_SERVER_LOG_STDERR`。
-- **发布开关**：图层是否出现在服务中取决于项目 `OWS Server` 页的 `published`/`queryable` 设置，而非仅由 URL 决定。
-
-### 常见配置模式
-
-```text
-QGIS Desktop 项目 (.qgz)
-  └── 项目属性 ▸ QGIS Server / OWS Server ──→ 启用 WMS/WFS/WMTS
-        └── FastCGI (qgis_mapserv.fcgi)
-              ├── Apache mod_fcgid
-              ├── Nginx + spawn-fcgi / fcgiwrap
-              └── Docker (qgis-server + nginx)
-                    └── MAP / QGIS_PROJECT_FILE + QGIS_SERVER_* 环境变量
-```
+- **加载与引用**：用 `skill("qgis-server")` 加载（用户也可输入 `/qgis-server`）；本技能没有 reference 子目录，服务能力以 `GetCapabilities` 实测为准；技能目录只读，配置片段与导出的能力文档写到会话工作区。
+- **执行环境**：命令交给 dsh 的 shell 工具（Windows 用 `pwsh`；仅暴露 `run_code` 的会话在 `tools.pwsh` 中执行），Windows 上 `curl` 要写 `curl.exe`；Apache/Nginx 片段属于目标服务器配置，本机会话改不了远端，需在主机上执行或用容器验证。
+- **先探测版本**：用同一安装的 `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 与服务端大版本应一致。
+- **验证服务**：先 `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`。
+- **常见报错**：`Service unknown or unsupported` 是缺 `SERVICE`/`MAP` 参数而非服务故障；`GetMap` 空白先查 `MAP` 路径可读性与项目 `OWS Server` 页的 `published` 勾选，再查 CRS/`BBOX`。
+- **日志与生效**：`QGIS_SERVER_LOG_STDERR=1` 交给 journald 或容器日志；`QGIS_SERVER_LOG_FILE` 已废弃，不要再用；`QGIS_SERVER_*` 改动要重启 FCGI 进程（或容器）才生效。
+- **安全与权限**：启动容器、开放端口、改 Web 服务器配置前先征得用户同意；`GetPrint` 在无 X 的 Linux 上需 `Xvfb`；项目文件可能含数据库凭证，命令与回答里不要回显密码。