@dsh-gis/dsh-opengis-skill 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +53 -8
  3. package/adaptations/brutile.md +19 -6
  4. package/adaptations/cesiumjs.md +14 -5
  5. package/adaptations/common.md +49 -20
  6. package/adaptations/deck-gl.md +19 -6
  7. package/adaptations/duckdb-spatial.md +20 -6
  8. package/adaptations/gdal-api.md +24 -6
  9. package/adaptations/gdal.md +22 -6
  10. package/adaptations/geolibre.md +20 -6
  11. package/adaptations/geometry-api-java.md +14 -6
  12. package/adaptations/geometry-api-net.md +17 -6
  13. package/adaptations/geonode.md +17 -6
  14. package/adaptations/geopandas.md +21 -6
  15. package/adaptations/geopipe-agent.md +21 -6
  16. package/adaptations/geos.md +21 -6
  17. package/adaptations/geoserver-cloud.md +17 -6
  18. package/adaptations/geoserver-rest-api.md +17 -6
  19. package/adaptations/geoserver.md +18 -6
  20. package/adaptations/geotools.md +19 -6
  21. package/adaptations/grass-gis.md +24 -6
  22. package/adaptations/jts.md +18 -6
  23. package/adaptations/kepler-gl.md +18 -5
  24. package/adaptations/leaflet.md +25 -6
  25. package/adaptations/mapbox-gl-js.md +23 -6
  26. package/adaptations/maplibre-gl-js.md +18 -6
  27. package/adaptations/maplibre-native.md +17 -6
  28. package/adaptations/mapserver.md +22 -6
  29. package/adaptations/mapsui.md +22 -6
  30. package/adaptations/nettopologysuite.md +19 -6
  31. package/adaptations/opendronemap.md +19 -6
  32. package/adaptations/opengis-all.md +16 -5
  33. package/adaptations/opengis-daf.md +16 -5
  34. package/adaptations/opengis-utils-for-java.md +20 -6
  35. package/adaptations/opengis-utils-for-net.md +23 -6
  36. package/adaptations/openlayers.md +20 -6
  37. package/adaptations/pdal.md +26 -6
  38. package/adaptations/postgis.md +20 -6
  39. package/adaptations/proj.md +20 -6
  40. package/adaptations/projnet4geoapi.md +21 -6
  41. package/adaptations/pyqgis.md +18 -6
  42. package/adaptations/qgis-process.md +21 -6
  43. package/adaptations/qgis-server.md +18 -6
  44. package/adaptations/shapely.md +22 -6
  45. package/adaptations/sharpmap.md +19 -6
  46. package/adaptations/spatialite.md +23 -6
  47. package/adaptations/stac-cog-titiler.md +21 -6
  48. package/adaptations/whitebox-tools.md +19 -6
  49. package/lib/adaptations.d.ts +9 -0
  50. package/lib/adaptations.js +64 -0
  51. package/lib/index.d.ts +13 -9
  52. package/lib/index.js +32 -12
  53. package/lib/taxonomy.d.ts +41 -0
  54. package/lib/taxonomy.js +332 -0
  55. package/package.json +3 -2
@@ -1,8 +1,22 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference 目录;`projinfo` 的 WKT 输出动辄上百行,重定向到文件再分段 `read`/`grep`,或直接加 `-q`(只出字符串本体)、`-o PROJJSON -q`(结构化,可交给 `jq`),不要把整段 WKT 贴进上下文。工具清单与坑都在正文;重投影栅格/矢量文件改用 `skill` 加载 `gdal`,`ST_Transform` 侧加载 `postgis`。
4
- - **执行环境**:`projinfo`、`cs2cs`、`proj`、`cct`、`projsync`、`geod` 都在 `ops_bash` 里跑。正文的 heredoc(`<<'EOF'`)在 bash 可用、在 `pwsh` 不可用,Windows 优先用管道 `echo 39.907 116.391 | cs2cs EPSG:4326 EPSG:32650`,或把坐标写成文件再重定向。设数据目录在 bash 是 `export PROJ_DATA=...`,在 `pwsh` 是 `$env:PROJ_DATA = "C:\OSGeo4W\share\proj"`。本机 PROJ 一般随 GDAL/QGIS 安装包(OSGeo4W)自带,`command -v projinfo` 找不到时先定位其 bin 目录。
5
- - **先探测版本**:`projinfo --version` 会同时打印版本与 `proj.db` 路径,是最可靠的入口;`projinfo --searchpaths` 看搜索路径。`proj` 直接执行会进交互模式,不能当版本检查用。正文按 PROJ 9.9.0 编写:9.1 起变量是 `PROJ_DATA`(旧名 `PROJ_LIB` 仍兼容),9.3 起 `proj` 才能直接接受 `EPSG:xxxx`;低版本遇到 `PROJ_DATA` 不识别先查 `--version` 实际值。`projinfo --list-crs` 确认某个 EPSG 代码在本地库里是否存在。
6
- - **验证产物**:用已知点对拍——`echo 39.907 116.391 | cs2cs EPSG:4326 EPSG:32650` 应得到东坐标约 44 万、北坐标约 442 万,量级明显不对通常是轴序或单位问题;`echo 30.5 114.0 | cs2cs EPSG:4326 EPSG:4547` 核对 CGCS2000 3 度带结果。转换路径用 `projinfo -s EPSG:4326 -t EPSG:4547 --summary` 看候选操作与精度,结构化核对用 `projinfo -o PROJJSON -q EPSG:4326`。批量转换后抽首尾各一行回算,逐行只打日志不算验证。
7
- - **风险与权限**:`projsync --all` 会从 CDN 下载数 GB 网格、`PROJ_NETWORK=ON` 也会联网,先确认网络与磁盘,用 `projsync --bbox` 按区域只取需要的网格;`sqlite3 proj.db` 只做只读查询,不要写库。改 `PROJ_DATA` 会连带影响同机 GDAL/QGIS/PostGIS 的坐标运算,动手前用 `ask_user_question` 让用户确认;涉及基准面转换的成果,交付时要说明用了哪个转换、精度多少、是否需要 `--only-best`。
8
- - **常见失败**:`Cannot find proj.db` 查 `PROJ_DATA` 与 `projinfo --searchpaths`;`DATABASE.LAYOUT.VERSION` 不匹配是多套 PROJ 副本混用;`The EPSG code is unknown` 是本地库没有该码,升级 PROJ 或改用等效 WKT/PROJJSON;`cs2cs` 输出轴序相反用 `-r` 反输入、`-s` 反输出;精度不足加 `projsync` 网格与 `--only-best`,否则会静默退回低精度操作。
3
+ - **加载与引用**:单文件技能,无 reference 目录
4
+ - `projinfo` 的 WKT 输出动辄上百行,重定向到文件再分段 `read`/`grep`,或直接加 `-q`(只出字符串本体)、`-o PROJJSON -q`(结构化,可交给 `jq`),不要把整段 WKT 贴进上下文。工具清单与坑都在正文
5
+ - 重投影栅格/矢量文件改用 `skill` 加载 `gdal`,`ST_Transform` 侧加载 `postgis`。
6
+ - **执行环境**:`projinfo`、`cs2cs`、`proj`、`cct`、`projsync`、`geod` 都在 `ops_bash` 里跑。
7
+ - 正文的 heredoc(`<<'EOF'`)在 bash 可用、在 `pwsh` 不可用,Windows 优先用管道 `echo 39.907 116.391 | cs2cs EPSG:4326 EPSG:32650`,或把坐标写成文件再重定向。
8
+ - 设数据目录在 bash 是 `export PROJ_DATA=...`,在 `pwsh` 是 `$env:PROJ_DATA = "C:\OSGeo4W\share\proj"`。
9
+ - 本机 PROJ 一般随 GDAL/QGIS 安装包(OSGeo4W)自带,`command -v projinfo` 找不到时先定位其 bin 目录
10
+ - **先探测版本**:`projinfo --version` 会同时打印版本与 `proj.db` 路径,是最可靠的入口
11
+ - `projinfo --searchpaths` 看搜索路径。`proj` 直接执行会进交互模式,不能当版本检查用。正文按 PROJ 9.9.0 编写:9.1 起变量是 `PROJ_DATA`(旧名 `PROJ_LIB` 仍兼容),9.3 起 `proj` 才能直接接受 `EPSG:xxxx`
12
+ - 低版本遇到 `PROJ_DATA` 不识别先查 `--version` 实际值。`projinfo --list-crs` 确认某个 EPSG 代码在本地库里是否存在。
13
+ - **验证产物**:用已知点对拍——`echo 39.907 116.391 | cs2cs EPSG:4326 EPSG:32650` 应得到东坐标约 44 万、北坐标约 442 万,量级明显不对通常是轴序或单位问题
14
+ - `echo 30.5 114.0 | cs2cs EPSG:4326 EPSG:4547` 核对 CGCS2000 3 度带结果。转换路径用 `projinfo -s EPSG:4326 -t EPSG:4547 --summary` 看候选操作与精度,结构化核对用 `projinfo -o PROJJSON -q EPSG:4326`。批量转换后抽首尾各一行回算,逐行只打日志不算验证。
15
+ - **风险与权限**:`projsync --all` 会从 CDN 下载数 GB 网格、`PROJ_NETWORK=ON` 也会联网,先确认网络与磁盘,用 `projsync --bbox` 按区域只取需要的网格
16
+ - `sqlite3 proj.db` 只做只读查询,不要写库。改 `PROJ_DATA` 会连带影响同机 GDAL/QGIS/PostGIS 的坐标运算,动手前用 `ask_user_question` 让用户确认
17
+ - 涉及基准面转换的成果,交付时要说明用了哪个转换、精度多少、是否需要 `--only-best`。
18
+ - **常见失败**:`Cannot find proj.db` 查 `PROJ_DATA` 与 `projinfo --searchpaths`
19
+ - `DATABASE.LAYOUT.VERSION` 不匹配是多套 PROJ 副本混用
20
+ - `The EPSG code is unknown` 是本地库没有该码,升级 PROJ 或改用等效 WKT/PROJJSON
21
+ - `cs2cs` 输出轴序相反用 `-r` 反输入、`-s` 反输出
22
+ - 精度不足加 `projsync` 网格与 `--only-best`,否则会静默退回低精度操作。
@@ -1,8 +1,23 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;正文「环境准备」教装包、「核心 API」给坐标系与转换接口、「典型工作流」给 CSV 批量转换、「常见问题」给报错对照。坐标转换的标准起手式是正文的「WKT 由专业工具生成」:先用 PROJ 导出 WKT 再写代码,不手写 `PROJCS`。需要坐标系定义与命令行核对时可 `skill` 加载 `proj`,几何运算加载 `nettopologysuite`,老项目兼容 1.4.1 时参考 `sharpmap`。
4
- - **执行环境**:`dotnet add package`、`dotnet build`、`dotnet run` 走 `ops_bash`(Windows 下是 MSYS bash,C# 工程路径写 `/d/work/proj-demo`);PowerShell 专有写法(`Install-Package`、`$env:` 变量)走 `pwsh`。首次 restore 必须能访问 NuGet,离线时先确认本地缓存或私有源再动工。临时工程建在会话工作区,不要写进 `assets/`。
5
- - **先探测版本**:正文按 `ProjNet` 2.1.0 编写(netstandard2.0/2.1),1.x 侧是 `ProjNet4GeoAPI` 1.4.1。先跑 `dotnet list package` 看实际装的是哪个:2.x 用 `ProjNet.CoordinateSystems` 自带类型,1.x 实现 GeoAPI 接口,两者程序集同名 `ProjNET.dll`,`using` 与接口名完全不同,项目里只应出现一个,混装会报「找到多个同名类型」。`MathTransform.TransformList` 与 `Transform(Span<double>, Span<double>, int strideX = 1, int strideY = 1)` 这批批量重载只出现在正文的 2.x 清单里,1.x 上照抄前先编译确认;数组有交错间隔时直接传 `strideX`/`strideY`,不要先手工拆成两份数组。
6
- - **验证产物**:编译后先跑正文的最小判据:`CreateFromCoordinateSystems(GeographicCoordinateSystem.WGS84, ProjectedCoordinateSystem.WebMercator)` 转换 `{116.397, 39.908}`,输出应约为 `12957254.80, 4852582.10`;批量转换后用高斯投影量级判断——东坐标 6 位(含带号 8 位)、北坐标 0–5000000,若仍是 116/39 量级说明坐标系取错或 WKT 解析失败被静默跳过。再拿 `projinfo EPSG:4547 -o WKT2:2019` 的 WKT 用 `CreateFromWkt` 单独解析一次,返回 `null` 就是这份 WKT 不被支持。与 QGIS/GDAL 差几十米属正文已知精度限制,不是代码错误。
7
- - **风险与权限**:新建工程、`dotnet add package`、在 1.x/2.x 之间换包都会改 `*.csproj` 与 `obj/`,动手前先 `read` 现有工程文件确认引用;两个包互斥且替换会自动卸载旧包,改动别人的工程依赖前用 `ask_user_question` 让用户在「只加 2.x / 保留 1.x / 先备份 csproj」之间选。`CoordinateSystemServices` 只认识传入的 SRID 与默认 4326/3857,不要当 EPSG 库用;示例里的 WKT 与数据路径用占位符,不要写进用户真实路径或凭据。
8
- - **常见失败**:`CreateFromCoordinateSystems` 返回 `null` 或抛异常,多半是「两个地理坐标系只差基准面而缺转换参数」,改成地理→投影两段式;`GetCoordinateSystem(4490)` 返回 `null` 是默认只注册 4326/3857,用 `KeyValuePair<int, string>` 构造函数注册;整列结果反号是输入按 `[x, y]` 解释,把 `[lat, lon]` 改成 `[lon, lat]`;转换极慢是工厂与 `MathTransform` 建在循环里,提到循环外并改用批量重载。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 正文「环境准备」教装包、「核心 API」给坐标系与转换接口、「典型工作流」给 CSV 批量转换、「常见问题」给报错对照。
5
+ - 坐标转换的标准起手式是正文的「WKT 由专业工具生成」:先用 PROJ 导出 WKT 再写代码,不手写 `PROJCS`。
6
+ - 需要坐标系定义与命令行核对时可 `skill` 加载 `proj`,几何运算加载 `nettopologysuite`,老项目兼容 1.4.1 时参考 `sharpmap`
7
+ - **执行环境**:`dotnet add package`、`dotnet build`、`dotnet run` 走 `ops_bash`(Windows 下是 MSYS bash,C# 工程路径写 `/d/work/proj-demo`)
8
+ - PowerShell 专有写法(`Install-Package`、`$env:` 变量)走 `pwsh`。首次 restore 必须能访问 NuGet,离线时先确认本地缓存或私有源再动工。临时工程建在会话工作区,不要写进 `assets/`。
9
+ - **先探测版本**:正文按 `ProjNet` 2.1.0 编写(netstandard2.0/2.1),1.x 侧是 `ProjNet4GeoAPI` 1.4.1。
10
+ - 先跑 `dotnet list package` 看实际装的是哪个:2.x 用 `ProjNet.CoordinateSystems` 自带类型,1.x 实现 GeoAPI 接口,两者程序集同名 `ProjNET.dll`,`using` 与接口名完全不同,项目里只应出现一个,混装会报「找到多个同名类型」。
11
+ - `MathTransform.TransformList` 与 `Transform(Span<double>, Span<double>, int strideX = 1, int strideY = 1)` 这批批量重载只出现在正文的 2.x 清单里,1.x 上照抄前先编译确认
12
+ - 数组有交错间隔时直接传 `strideX`/`strideY`,不要先手工拆成两份数组。
13
+ - **验证产物**:编译后先跑正文的最小判据:`CreateFromCoordinateSystems(GeographicCoordinateSystem.WGS84, ProjectedCoordinateSystem.WebMercator)` 转换 `{116.397, 39.908}`,输出应约为 `12957254.80, 4852582.10`
14
+ - 批量转换后用高斯投影量级判断——东坐标 6 位(含带号 8 位)、北坐标 0–5000000,若仍是 116/39 量级说明坐标系取错或 WKT 解析失败被静默跳过。
15
+ - 再拿 `projinfo EPSG:4547 -o WKT2:2019` 的 WKT 用 `CreateFromWkt` 单独解析一次,返回 `null` 就是这份 WKT 不被支持。
16
+ - 与 QGIS/GDAL 差几十米属正文已知精度限制,不是代码错误
17
+ - **风险与权限**:新建工程、`dotnet add package`、在 1.x/2.x 之间换包都会改 `*.csproj` 与 `obj/`,动手前先 `read` 现有工程文件确认引用
18
+ - 两个包互斥且替换会自动卸载旧包,改动别人的工程依赖前用 `ask_user_question` 让用户在「只加 2.x / 保留 1.x / 先备份 csproj」之间选。`CoordinateSystemServices` 只认识传入的 SRID 与默认 4326/3857,不要当 EPSG 库用
19
+ - 示例里的 WKT 与数据路径用占位符,不要写进用户真实路径或凭据。
20
+ - **常见失败**:`CreateFromCoordinateSystems` 返回 `null` 或抛异常,多半是「两个地理坐标系只差基准面而缺转换参数」,改成地理→投影两段式
21
+ - `GetCoordinateSystem(4490)` 返回 `null` 是默认只注册 4326/3857,用 `KeyValuePair<int, string>` 构造函数注册
22
+ - 整列结果反号是输入按 `[x, y]` 解释,把 `[lat, lon]` 改成 `[lon, lat]`
23
+ - 转换极慢是工厂与 `MathTransform` 建在循环里,提到循环外并改用批量重载。
@@ -1,8 +1,20 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文主文件给高频类与方法表,完整参数与示例在 `reference/vector-raster-layers.md`(矢量/栅格图层、要素读写、数据提供者 URI)和 `reference/processing-rendering.md`(`processing.run` 参数、地图渲染、`QgsLayoutExporter` 导出、典型工作流)。先用 `read` 读文件开头的目录定位小节,再按 `offset`/`limit` 跳读,或用 `grep` 搜类名,不要把两份参考整份读进上下文。要命令行跑算法时用 `skill` 加载 `qgis-process`,纯几何计算加载 `shapely`。
4
- - **执行环境**:必须用 QGIS 发行包自带的解释器(4.2 在 `C:/Program Files/QGIS 4.2/apps/Python312/python.exe`,LTR 在 `QGIS 3.44` 下同构),系统 Python `pip install qgis` 装不上绑定。命令走 `ops_bash`(Windows 是 MSYS bash,解释器路径写成带引号的 `/c/Program\ Files/...` 形式);只在 PowerShell 能表达的写法(`$env:QT_QPA_PLATFORM = "offscreen"`)走 `pwsh`,正文的 `export QT_QPA_PLATFORM=offscreen` 在 bash 里只能作单条命令前缀。批量渲染与长脚本用后台作业起,再 `job_output` 收进度、`job_kill` 收尾。
5
- - **先探测版本**:正文按 QGIS 4.2.3(最新)与 LTR 3.44.15 双版本编写。先跑 `python -c "from qgis.core import Qgis; print(Qgis.QGIS_VERSION)"` 确认版本,再确认 prefix 指向哪套安装;4.x 与 3.x 的类与方法有出入,低版本没有的 API 不要照抄,拿不准先查 `qgis.org/pyqgis/4.2/` 的签名。3D 模块是 `qgis._3d`(下划线),写成 `qgis.3d` 会 ImportError。
6
- - **验证产物**:独立脚本按 `QgsApplication` → `initQgis()` → 处理 → `exitQgis()` 收尾,中途抛异常也要保证退出,否则残留进程占着文件锁。写出后重新 `QgsVectorLayer(path, name, "ogr")` 打开,核对 `isValid()`、`featureCount()`、`crs().authid()` 三项;`processing.run()` 只返回路径,不等于算法成功,必须二次打开。渲染或布局导出的 PNG/PDF 用 `read_image` 真看一眼是否空白、范围对不对,成品用 `present` 交付。建议先跑正文的最小闭环(`native:buffer` + `assert layer.isValid()`)再往上叠逻辑。
7
- - **风险与权限**:`startEditing()`/`commitChanges()`、`QgsVectorFileWriter` 覆盖已有路径、`QgsProject.write()` 都会就地改写源数据或工程文件,动手前先备份或把中间结果写 `memory:`;覆盖已有输出、安装 QGIS、连 PostGIS 生产库之前用 `ask_user_question` 给「换名输出 / 覆盖 / 先备份」三个选项。`postgres` provider 的 URI 可能带明文口令,命令、日志与回复里都不要回显;`QgsApplication.messageLog()` 与 stderr 重定向到 `run.log` 后再分段看。
8
- - **常见失败**:`import qgis.core` 失败先查解释器与 `PYTHONPATH`(Windows 指向 `apps/qgis` 下的 `python` 目录);图层 `isValid()` 为 false 时打印 `layer.error().message()` 并核对 provider 拼写(`ogr`/`gdal`/`postgres`);`processing.run()` 报算法不存在是漏了 `Processing.initialize()` 或插件未启用;无显示环境崩溃设 offscreen 平台;渲染空白先查 `QgsMapSettings` 的 extent、CRS 与输出尺寸。
3
+ - **加载与引用**:正文主文件给高频类与方法表,完整参数与示例在 `reference/vector-raster-layers.md`(矢量/栅格图层、要素读写、数据提供者 URI)和 `reference/processing-rendering.md`(`processing.run` 参数、地图渲染、`QgsLayoutExporter` 导出、典型工作流)。
4
+ - 先用 `read` 读文件开头的目录定位小节,再按 `offset`/`limit` 跳读,或用 `grep` 搜类名,不要把两份参考整份读进上下文。
5
+ - 要命令行跑算法时用 `skill` 加载 `qgis-process`,纯几何计算加载 `shapely`
6
+ - **执行环境**:必须用 QGIS 发行包自带的解释器(4.2 在 `C:/Program Files/QGIS 4.2/apps/Python312/python.exe`,LTR 在 `QGIS 3.44` 下同构),系统 Python `pip install qgis` 装不上绑定。
7
+ - 命令走 `ops_bash`(Windows 是 MSYS bash,解释器路径写成带引号的 `/c/Program\ Files/...` 形式)
8
+ - 只在 PowerShell 能表达的写法(`$env:QT_QPA_PLATFORM = "offscreen"`)走 `pwsh`,正文的 `export QT_QPA_PLATFORM=offscreen` 在 bash 里只能作单条命令前缀。批量渲染与长脚本用后台作业起,再 `job_output` 收进度、`job_kill` 收尾。
9
+ - **先探测版本**:正文按 QGIS 4.2.3(最新)与 LTR 3.44.15 双版本编写。先跑 `python -c "from qgis.core import Qgis; print(Qgis.QGIS_VERSION)"` 确认版本,再确认 prefix 指向哪套安装
10
+ - 4.x 与 3.x 的类与方法有出入,低版本没有的 API 不要照抄,拿不准先查 `qgis.org/pyqgis/4.2/` 的签名。3D 模块是 `qgis._3d`(下划线),写成 `qgis.3d` 会 ImportError。
11
+ - **验证产物**:独立脚本按 `QgsApplication` → `initQgis()` → 处理 → `exitQgis()` 收尾,中途抛异常也要保证退出,否则残留进程占着文件锁。写出后重新 `QgsVectorLayer(path, name, "ogr")` 打开,核对 `isValid()`、`featureCount()`、`crs().authid()` 三项
12
+ - `processing.run()` 只返回路径,不等于算法成功,必须二次打开。渲染或布局导出的 PNG/PDF 用 `read_image` 真看一眼是否空白、范围对不对,成品用 `present` 交付。建议先跑正文的最小闭环(`native:buffer` + `assert layer.isValid()`)再往上叠逻辑。
13
+ - **风险与权限**:`startEditing()`/`commitChanges()`、`QgsVectorFileWriter` 覆盖已有路径、`QgsProject.write()` 都会就地改写源数据或工程文件,动手前先备份或把中间结果写 `memory:`
14
+ - 覆盖已有输出、安装 QGIS、连 PostGIS 生产库之前用 `ask_user_question` 给「换名输出 / 覆盖 / 先备份」三个选项。`postgres` provider 的 URI 可能带明文口令,命令、日志与回复里都不要回显
15
+ - `QgsApplication.messageLog()` 与 stderr 重定向到 `run.log` 后再分段看。
16
+ - **常见失败**:`import qgis.core` 失败先查解释器与 `PYTHONPATH`(Windows 指向 `apps/qgis` 下的 `python` 目录)
17
+ - 图层 `isValid()` 为 false 时打印 `layer.error().message()` 并核对 provider 拼写(`ogr`/`gdal`/`postgres`)
18
+ - `processing.run()` 报算法不存在是漏了 `Processing.initialize()` 或插件未启用
19
+ - 无显示环境崩溃设 offscreen 平台
20
+ - 渲染空白先查 `QgsMapSettings` 的 extent、CRS 与输出尺寸。
@@ -1,8 +1,23 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文给命令行语法、`help --json` 的结构、`run` 的 JSON 结果与常见报错;内置算法 ID、参数类型与枚举索引查 `reference/algorithm-cheatsheet.md`。先 `read` 文件开头的目录定位到目标算法小节,再用 `grep` 搜算法 ID(如 `native:buffer`),不要整份读。需要 Python 里循环调用时用 `skill` 加载 `pyqgis`,栅格导出后的检查加载 `gdal`。
4
- - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash,可执行文件写 `/c/Program\ Files/QGIS\ 4.2/bin/qgis_process.exe`,路径含空格必须整体加引号);`$env:QT_QPA_PLATFORM = "offscreen"` 这类环境变量赋值走 `pwsh`,正文的 `export QT_QPA_PLATFORM=offscreen` 在 bash 里只能写成单条命令前缀 `QT_QPA_PLATFORM=offscreen qgis_process ...`。Linux 的 `sudo apt install qgis` 不可用,Windows 上装 OSGeo4W 组件或直接跑容器 `docker run --rm -v "$PWD:/data" qgis/qgis:ltr qgis_process --version`(容器内写 `/data/...`,别把宿主 `D:\...` 路径传进去)。批量循环与全量处理用后台作业起,`job_output` 看进度,`job_kill` 停掉跑偏的任务;三次以上步骤先 `todo_write` 列「探测 → help 取参 → 跑单个 → 批量 → 校验」。
5
- - **先探测版本**:正文按 QGIS 4.2.3(stable)与 LTR 3.44.15 编写,`qgis_process` 自 3.16 起才有。先跑 `qgis_process --version`,低于 3.16 只能退回 `pyqgis` 的 `processing.run()`;用容器时用镜像 tag(`stable` / `ltr`)确认,不要假设本机 PATH 里的就是 4.2。启动慢时加 `--no-python`、`--skip-loading-plugins`,但依赖 Python 插件 provider(`saga` 等)的算法就别加。
6
- - **验证产物**:`run ... --json` 的 `results.OUTPUT` 是实际写出的绝对路径,用它的值去校验,不要自己拼路径。矢量跑 `ogrinfo -so out.gpkg 图层名` 核对要素数、CRS、几何类型;栅格跑 `gdalinfo -json out.tif` 核对尺寸、CRS、NoData;切片或渲染出图用 `read_image` 真看一眼。正文明确:日志里出现 `returned non-zero` 时即使进程退出码为 0 也算失败,所以要 `grep -n "returned non-zero" run.log` 再下结论,别只看 `$?`。
7
- - **风险与权限**:`OUTPUT=` 指向已有文件会被直接覆盖,`--project_path=` 会加载项目里的数据源与数据库凭证;覆盖已有图层、启动 Docker、安装 QGIS、把含密码的工程传给外部环境前用 `ask_user_question` 让用户在「换名输出 / 覆盖 / 先备份」之间选。`qgis_process run` 每次新起一个 QGIS 进程(数秒开销),千级文件别用 shell 循环硬扛,改单进程 PyQGIS。日志先重定向到 `run.log` 再 `grep`,不要把整段 JSON 日志刷进上下文。
8
- - **常见失败**:`Algorithm <id> not found!` 先用 `qgis_process list` 核对 provider 前缀(`native:`/`gdal:`/`grass:`),插件 provider 还要求 `metadata.txt` 里 `hasProcessingProvider=yes`;`The following mandatory parameters were not specified` 回看 `help --json`;枚举参数传数字索引而不是文本;多值参数在 `--` 之后重复同一键(`LAYERS=a.shp LAYERS=b.shp`);路径含空格或中文加引号并用绝对路径。
3
+ - **加载与引用**:正文给命令行语法、`help --json` 的结构、`run` 的 JSON 结果与常见报错
4
+ - 内置算法 ID、参数类型与枚举索引查 `reference/algorithm-cheatsheet.md`。先 `read` 文件开头的目录定位到目标算法小节,再用 `grep` 搜算法 ID(如 `native:buffer`),不要整份读。需要 Python 里循环调用时用 `skill` 加载 `pyqgis`,栅格导出后的检查加载 `gdal`。
5
+ - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash,可执行文件写 `/c/Program\ Files/QGIS\ 4.2/bin/qgis_process.exe`,路径含空格必须整体加引号)
6
+ - `$env:QT_QPA_PLATFORM = "offscreen"` 这类环境变量赋值走 `pwsh`,正文的 `export QT_QPA_PLATFORM=offscreen` 在 bash 里只能写成单条命令前缀 `QT_QPA_PLATFORM=offscreen qgis_process ...`。
7
+ - Linux 的 `sudo apt install qgis` 不可用,Windows 上装 OSGeo4W 组件或直接跑容器 `docker run --rm -v "$PWD:/data" qgis/qgis:ltr qgis_process --version`(容器内写 `/data/...`,别把宿主 `D:\...` 路径传进去)。
8
+ - 批量循环与全量处理用后台作业起,`job_output` 看进度,`job_kill` 停掉跑偏的任务
9
+ - 三次以上步骤先 `todo_write` 列「探测 → help 取参 → 跑单个 → 批量 → 校验」。
10
+ - **先探测版本**:正文按 QGIS 4.2.3(stable)与 LTR 3.44.15 编写,`qgis_process` 自 3.16 起才有。先跑 `qgis_process --version`,低于 3.16 只能退回 `pyqgis` 的 `processing.run()`
11
+ - 用容器时用镜像 tag(`stable` / `ltr`)确认,不要假设本机 PATH 里的就是 4.2。启动慢时加 `--no-python`、`--skip-loading-plugins`,但依赖 Python 插件 provider(`saga` 等)的算法就别加。
12
+ - **验证产物**:`run ... --json` 的 `results.OUTPUT` 是实际写出的绝对路径,用它的值去校验,不要自己拼路径。矢量跑 `ogrinfo -so out.gpkg 图层名` 核对要素数、CRS、几何类型
13
+ - 栅格跑 `gdalinfo -json out.tif` 核对尺寸、CRS、NoData
14
+ - 切片或渲染出图用 `read_image` 真看一眼。正文明确:日志里出现 `returned non-zero` 时即使进程退出码为 0 也算失败,所以要 `grep -n "returned non-zero" run.log` 再下结论,别只看 `$?`。
15
+ - **风险与权限**:`OUTPUT=` 指向已有文件会被直接覆盖,`--project_path=` 会加载项目里的数据源与数据库凭证
16
+ - 覆盖已有图层、启动 Docker、安装 QGIS、把含密码的工程传给外部环境前用 `ask_user_question` 让用户在「换名输出 / 覆盖 / 先备份」之间选。
17
+ - `qgis_process run` 每次新起一个 QGIS 进程(数秒开销),千级文件别用 shell 循环硬扛,改单进程 PyQGIS。
18
+ - 日志先重定向到 `run.log` 再 `grep`,不要把整段 JSON 日志刷进上下文
19
+ - **常见失败**:`Algorithm <id> not found!` 先用 `qgis_process list` 核对 provider 前缀(`native:`/`gdal:`/`grass:`),插件 provider 还要求 `metadata.txt` 里 `hasProcessingProvider=yes`
20
+ - `The following mandatory parameters were not specified` 回看 `help --json`
21
+ - 枚举参数传数字索引而不是文本
22
+ - 多值参数在 `--` 之后重复同一键(`LAYERS=a.shp LAYERS=b.shp`)
23
+ - 路径含空格或中文加引号并用绝对路径。
@@ -1,8 +1,20 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;部署方式看「环境准备」(Debian 包 / OSGeo4W / Docker),请求示例看「核心 API / 命令」,变量与排查看「服务端环境变量」「常见问题」。服务端插件逻辑与项目自动化用 `skill` 加载 `pyqgis`,另一套 OGC 方案加载 `geoserver`,数据源侧加载 `postgis`。
4
- - **执行环境**:`docker`、`curl.exe` 走 `ops_bash`(Windows 是 MSYS bash),原生 Windows 写法与 `$env:` 变量走 `pwsh`,多步编排可用 `run_code` 串起来。服务端部署在 Linux/容器,本机是 Windows 会话,所以默认路径是 Docker:`docker run -d --name qgis-server ... qgis/qgis:ltr` 起容器再用 `curl`(Windows 下必须写 `curl.exe`)打请求,容器与端口用 `ops_bash` 的 `run_in_background` 起、`job_output` 收日志、`job_kill` 停容器。正文的 `sudo apt install qgis-server`、`/usr/lib/cgi-bin/qgis_mapserv.fcgi`、Apache/Nginx 片段都是目标服务器写法,本机会话改不了远端主机,要么在主机上执行,要么全部在容器里验证;OSGeo4W 路线在本机装 `QGIS Desktop + QGIS Server + apache + mod_fcgid` 后才可用。`SetEnv`/`fastcgi_param` 属于服务器配置,别当本地命令跑。
5
- - **先探测版本**:正文按 QGIS Server 4.2.3(最新)与 LTR 3.44.15 编写。先确认服务端版本:`qgis --version`、`qgis_process --version`、`dpkg -l qgis-server` 或看镜像 tag;生成项目的 QGIS Desktop 与服务端应同一主版本,否则旧项目可能打不开。直接执行 `qgis_mapserv.fcgi`(无参数)在 Linux 上应返回含 `ServiceExceptionReport` 的 XML,这是「装上且能跑」的最低判据,Windows/Docker 下用功能更全的 `GetCapabilities` 代替。
6
- - **验证产物**:`curl.exe -sS "http://localhost/cgi-bin/qgis_mapserv.fcgi?MAP=/data/world.qgz&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities" -o caps.xml` 存盘后 `grep -n "<Layer>" caps.xml` 核对图层清单(名字、CRS、样式),确认不是空文档或异常报告;再发 `GetMap` 拿 PNG 用 `read_image` 真看一眼是否空白、范围是否正确,`GetFeature` 取 GeoJSON 检查要素字段。只看到 HTTP 200 不算通过,正文明确 `GetMap` 的 500/空白要回查 `MAP` 路径可读性、图层 `published` 勾选与 CRS/`BBOX`。
7
- - **风险与权限**:启动容器、映射 80 端口、改 Web 服务器配置、把服务暴露到非回环地址之前必须用 `ask_user_question` 让用户确认(尤其本机已有 Apache/Nginx 占用端口时);工程文件可能含数据库连接串与口令,命令行、日志与回复里不要回显,二进制用 `QGIS_PROJECT_FILE` 环境变量引用而不是把密码拼进 URL。`GetPrint` 在无 X 的 Linux 上要 `Xvfb`(`DISPLAY=:99`),别指望它直接出图;`QGIS_SERVER_LOG_FILE` 已废弃,统一 `QGIS_SERVER_LOG_STDERR=1` 交给日志系统。
8
- - **常见失败**:`Service unknown or unsupported` 不是服务坏了,而是缺 `SERVICE`/`MAP` 参数;`GetCapabilities` 里图层名是长 ID 说明项目开着「Use layer ids as names」;中文乱码设 `QGIS_SERVER_OVERRIDE_SYSTEM_LOCALE=en_US.UTF-8`;WFS `Transaction` 必须 POST 且数据源可写;`QGIS_SERVER_*` 改动要重启 FCGI 进程或容器才生效,改了没反应先确认进程真的重启过。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 部署方式看「环境准备」(Debian 包 / OSGeo4W / Docker),请求示例看「核心 API / 命令」,变量与排查看「服务端环境变量」「常见问题」。服务端插件逻辑与项目自动化用 `skill` 加载 `pyqgis`,另一套 OGC 方案加载 `geoserver`,数据源侧加载 `postgis`。
5
+ - **执行环境**:`docker`、`curl.exe` 走 `ops_bash`(Windows 是 MSYS bash),原生 Windows 写法与 `$env:` 变量走 `pwsh`,多步编排可用 `run_code` 串起来。
6
+ - 服务端部署在 Linux/容器,本机是 Windows 会话,所以默认路径是 Docker:`docker run -d --name qgis-server ... qgis/qgis:ltr` 起容器再用 `curl`(Windows 下必须写 `curl.exe`)打请求,容器与端口用 `ops_bash` 的 `run_in_background` 起、`job_output` 收日志、`job_kill` 停容器。
7
+ - 正文的 `sudo apt install qgis-server`、`/usr/lib/cgi-bin/qgis_mapserv.fcgi`、Apache/Nginx 片段都是目标服务器写法,本机会话改不了远端主机,要么在主机上执行,要么全部在容器里验证
8
+ - OSGeo4W 路线在本机装 `QGIS Desktop + QGIS Server + apache + mod_fcgid` 后才可用。`SetEnv`/`fastcgi_param` 属于服务器配置,别当本地命令跑。
9
+ - **先探测版本**:正文按 QGIS Server 4.2.3(最新)与 LTR 3.44.15 编写。先确认服务端版本:`qgis --version`、`qgis_process --version`、`dpkg -l qgis-server` 或看镜像 tag
10
+ - 生成项目的 QGIS Desktop 与服务端应同一主版本,否则旧项目可能打不开。直接执行 `qgis_mapserv.fcgi`(无参数)在 Linux 上应返回含 `ServiceExceptionReport` 的 XML,这是「装上且能跑」的最低判据,Windows/Docker 下用功能更全的 `GetCapabilities` 代替。
11
+ - **验证产物**:`curl.exe -sS "http://localhost/cgi-bin/qgis_mapserv.fcgi?MAP=/data/world.qgz&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities" -o caps.xml` 存盘后 `grep -n "<Layer>" caps.xml` 核对图层清单(名字、CRS、样式),确认不是空文档或异常报告
12
+ - 再发 `GetMap` 拿 PNG 用 `read_image` 真看一眼是否空白、范围是否正确,`GetFeature` 取 GeoJSON 检查要素字段。只看到 HTTP 200 不算通过,正文明确 `GetMap` 的 500/空白要回查 `MAP` 路径可读性、图层 `published` 勾选与 CRS/`BBOX`。
13
+ - **风险与权限**:启动容器、映射 80 端口、改 Web 服务器配置、把服务暴露到非回环地址之前必须用 `ask_user_question` 让用户确认(尤其本机已有 Apache/Nginx 占用端口时)
14
+ - 工程文件可能含数据库连接串与口令,命令行、日志与回复里不要回显,二进制用 `QGIS_PROJECT_FILE` 环境变量引用而不是把密码拼进 URL。`GetPrint` 在无 X 的 Linux 上要 `Xvfb`(`DISPLAY=:99`),别指望它直接出图
15
+ - `QGIS_SERVER_LOG_FILE` 已废弃,统一 `QGIS_SERVER_LOG_STDERR=1` 交给日志系统。
16
+ - **常见失败**:`Service unknown or unsupported` 不是服务坏了,而是缺 `SERVICE`/`MAP` 参数
17
+ - `GetCapabilities` 里图层名是长 ID 说明项目开着「Use layer ids as names」
18
+ - 中文乱码设 `QGIS_SERVER_OVERRIDE_SYSTEM_LOCALE=en_US.UTF-8`
19
+ - WFS `Transaction` 必须 POST 且数据源可写
20
+ - `QGIS_SERVER_*` 改动要重启 FCGI 进程或容器才生效,改了没反应先确认进程真的重启过。
@@ -1,8 +1,24 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:正文主文件给类型、双 API、创建与常见问题,完整构造操作、谓词、集合运算、度量、STRtree、仿射与线性参考在 `reference/operations-reference.md`。先用 `read` 读该文件开头的小节目录定位,再 `offset`/`limit` 分段取用,或 `grep` 搜函数名(如 `coverage_clean`),不要整份读进上下文。矢量表读写用 `skill` 加载 `geopandas`,坐标投影按正文「坐标投影」一节用 pyproj,QGIS 内几何计算加载 `pyqgis`。
4
- - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash),Python 解释器要用装了 shapely 的那一个,先 `python -c "import sys; print(sys.executable, sys.version)"` 确认不是 QGIS/GDAL 自带环境,否则可能装到别的 site-packages。正文的 `pip install shapely` 在 Windows 上同样可用(wheel 自带 GEOS),但装包前需用户同意;纯命令行的 Windows 专有操作(`Get-ChildItem`、`$env:PATH`)走 `pwsh`。批量处理十万级几何用后台作业跑,`job_output` 收进度、`job_kill` 收尾。
5
- - **先探测版本**:正文按 Shapely 2.2.0 编写(Python 3.11+、NumPy >= 1.26、GEOS >= 3.10,PyPI wheel 内嵌 GEOS 3.14.1;2.1.2 的 wheel 才是 3.13.1)。先跑 `python -c "import shapely; print(shapely.__version__, shapely.geos_version)"` 拿到两个版本:GEOS 低于门槛的函数会直接报错或缺失——`concave_hull`/`remove_repeated_points` 要 3.11,`coverage_simplify`/`has_m`/`get_m` 要 3.12,`coverage_clean` 要 3.14,顶层 `shapely.split` 要 3.15(低版本自动回退 `shapely.ops.split`)。`minimum_width`、`get_segments`、`transform_coordseq` 是 2.2 才有的顶层函数,缺失说明装的是旧版。`shapely.ops.transform` 与 `multithreading_enabled` 在 2.2 已弃用,改 `shapely.transform`/`shapely.transform_coordseq`。
6
- - **验证产物**:先用 `shapely.is_valid(g)` 与 `shapely.is_valid_reason(g)` 报出无效原因,再断言面积/长度量级;序列化回读 `shapely.from_wkt(shapely.to_wkt(g, rounding_precision=-1)).equals(g)`,改过几何后再核对 `geom_type` 与 `get_num_geometries()`。正文的端到端验收标准可直接照用:`clipped.geojson` 每个 Feature 能被 `shapely.from_geojson()` 读回、`is_valid()` 全为 True、面积与输入同阶。产出的图(`shapely.plotting` 或后续渲染)用 `read_image` 真看一眼,成品用 `present` 交付。
7
- - **风险与权限**:`pip install shapely`、升级 GEOS 环境、改共享 conda 环境前用 `ask_user_question` 确认;`set_coordinates()`/`shapely.prepare()` 是原地修改,动手前先 `.copy()`,覆盖用户数据文件前先备份或换输出名。WKT/坐标导出前确认数据敏感度(精确坐标可反推位置),大几何别 dump 到终端刷屏,写到文件再 `read` 分段看。
8
- - **常见失败**:`TopologyException: side location conflict` 基本是输入自相交,先 `make_valid()` 再算,不要用 `buffer(0)` 糊过去;`UnsupportedGEOSVersionError` 是底层 GEOS 太旧,核对 `shapely.geos_version`,升级 wheel(自带 GEOS)而不是只升级系统 GEOS;面积/距离为 0 或极小是地理坐标系按度算,先投影到米制;`contains` 对边界点返回 False,改用 `covers()`;OOP 与函数式结果不同是 `buffer` 默认 `quad_segs` 不同(16 vs 8),比较前显式传参;`STRtree` 查空先排除 `None`/`Empty` 与 CRS 不一致。
3
+ - **加载与引用**:正文主文件给类型、双 API、创建与常见问题,完整构造操作、谓词、集合运算、度量、STRtree、仿射与线性参考在 `reference/operations-reference.md`。
4
+ - 先用 `read` 读该文件开头的小节目录定位,再 `offset`/`limit` 分段取用,或 `grep` 搜函数名(如 `coverage_clean`),不要整份读进上下文。
5
+ - 矢量表读写用 `skill` 加载 `geopandas`,坐标投影按正文「坐标投影」一节用 pyproj,QGIS 内几何计算加载 `pyqgis`
6
+ - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash),Python 解释器要用装了 shapely 的那一个,先 `python -c "import sys; print(sys.executable, sys.version)"` 确认不是 QGIS/GDAL 自带环境,否则可能装到别的 site-packages。
7
+ - 正文的 `pip install shapely` 在 Windows 上同样可用(wheel 自带 GEOS),但装包前需用户同意
8
+ - 纯命令行的 Windows 专有操作(`Get-ChildItem`、`$env:PATH`)走 `pwsh`。批量处理十万级几何用后台作业跑,`job_output` 收进度、`job_kill` 收尾。
9
+ - **先探测版本**:正文按 Shapely 2.2.0 编写(Python 3.11+、NumPy >= 1.26、GEOS >= 3.10,PyPI wheel 内嵌 GEOS 3.14.1;2.1.2 的 wheel 才是 3.13.1)。
10
+ - 先跑 `python -c "import shapely; print(shapely.__version__, shapely.geos_version)"` 拿到两个版本:GEOS 低于门槛的函数会直接报错或缺失——`concave_hull`/`remove_repeated_points` 要 3.11,`coverage_simplify`/`has_m`/`get_m` 要 3.12,`coverage_clean` 要 3.14,顶层 `shapely.split` 要 3.15(低版本自动回退 `shapely.ops.split`)。
11
+ - `minimum_width`、`get_segments`、`transform_coordseq` 是 2.2 才有的顶层函数,缺失说明装的是旧版。
12
+ - `shapely.ops.transform` 与 `multithreading_enabled` 在 2.2 已弃用,改 `shapely.transform`/`shapely.transform_coordseq`
13
+ - **验证产物**:先用 `shapely.is_valid(g)` 与 `shapely.is_valid_reason(g)` 报出无效原因,再断言面积/长度量级
14
+ - 序列化回读 `shapely.from_wkt(shapely.to_wkt(g, rounding_precision=-1)).equals(g)`,改过几何后再核对 `geom_type` 与 `get_num_geometries()`。
15
+ - 正文的端到端验收标准可直接照用:`clipped.geojson` 每个 Feature 能被 `shapely.from_geojson()` 读回、`is_valid()` 全为 True、面积与输入同阶。
16
+ - 产出的图(`shapely.plotting` 或后续渲染)用 `read_image` 真看一眼,成品用 `present` 交付
17
+ - **风险与权限**:`pip install shapely`、升级 GEOS 环境、改共享 conda 环境前用 `ask_user_question` 确认
18
+ - `set_coordinates()`/`shapely.prepare()` 是原地修改,动手前先 `.copy()`,覆盖用户数据文件前先备份或换输出名。WKT/坐标导出前确认数据敏感度(精确坐标可反推位置),大几何别 dump 到终端刷屏,写到文件再 `read` 分段看。
19
+ - **常见失败**:`TopologyException: side location conflict` 基本是输入自相交,先 `make_valid()` 再算,不要用 `buffer(0)` 糊过去
20
+ - `UnsupportedGEOSVersionError` 是底层 GEOS 太旧,核对 `shapely.geos_version`,升级 wheel(自带 GEOS)而不是只升级系统 GEOS
21
+ - 面积/距离为 0 或极小是地理坐标系按度算,先投影到米制
22
+ - `contains` 对边界点返回 False,改用 `covers()`
23
+ - OOP 与函数式结果不同是 `buffer` 默认 `quad_segs` 不同(16 vs 8),比较前显式传参
24
+ - `STRtree` 查空先排除 `None`/`Empty` 与 CRS 不一致。
@@ -1,8 +1,21 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;装包与目标框架看「安装」,图层与样式看「核心 API」及 WinForms/PostGIS/瓦片示例,「常见问题」给无图、乱码、类型冲突的对照。坐标变换细节用 `skill` 加载 `projnet4geoapi`,几何运算加载 `nettopologysuite`,新项目迁移到 `mapsui`。
4
- - **执行环境**:`dotnet add package`、`dotnet restore`、`dotnet build` 走 `ops_bash`(Windows 是 MSYS bash,工程路径写 `/d/work/maptest`);`dotnet --list-sdks`、`Get-Command dotnet`、`$env:` 变量等 Windows 原生命令走 `pwsh`。关键约束:`SharpMap.UI` 只支持 .NET Framework 4.7.2,csproj 目标框架必须写 `net472`,不能写成 `net8.0`;只有核心包 `SharpMap`(netstandard2.0)能被新框架引用。渲染与批量出图用后台作业,`job_output` 收日志,`job_kill` 停掉卡住的任务。
5
- - **先探测版本**:正文按 SharpMap 1.2.0 编写(2021-03 发布,仓库未归档但维护低频),坐标变换一侧必须用 `ProjNet4GeoAPI` 1.4.1。先跑 `dotnet --version` 与 `dotnet list package` 确认目标框架与包版本:`dotnet restore` 输出 NU1902/NU1903/NU1904 漏洞告警是已知状态(传递依赖 `NetTopologySuite.Core` 1.15.3、`System.Drawing.Common` 4.6.0 等),不是装失败,但要在回复里说明而不是静默忽略。正文只覆盖 1.2.0,没有 2.x,别照抄别的技能里的 ProjNet 2.x 写法。
6
- - **验证产物**:最终判据是图不是编译:`map.GetMap()` 取 `System.Drawing.Image` 后 `Save("output.png")`,再按正文的验收——能看到按人口分档的面、标注文字、底图瓦片齐全才算渲染正确。构建只算前置:`dotnet build` 通过后必须打开 PNG 核对,会看图就用 `read_image` 真看一眼是否空白或整片偏移。SRID 一致性要单独查:`map.SRID` 与图层坐标系不一致时图能出但位置全错(例如 OSM 底图必须 3857),这属于正文「无图」以外更隐蔽的失败。
7
- - **风险与权限**:新建工程、装包、连 PostGIS、把 SharpMap 1.2.0 引入既有解决方案前用 `ask_user_question` 让用户确认(该包维护低频且带已知漏洞告警);PostGIS 连接串的密码不要写进代码、日志或回复,示例里用占位符。`ShapeFile` 构造函数没有 `Encoding` 重载,中文乱码要单独设 `shp.Encoding = Encoding.GetEncoding("GBK")`;`Brush`/`Pen`/`Bitmap` 必须 `using`/`Dispose`,否则 GDI+ 句柄泄漏会拖垮长驻进程。
8
- - **常见失败**:无图先查 `SRID` 与有没有调 `ZoomToExtents()`;找不到 `SharpMap.UI.WinForms` 是因为包名不存在,控件在 `SharpMap.UI` 里;`CoordinateTransformation` 赋值编译失败是引了 ProjNet 2.x,换回 `ProjNet4GeoAPI` 1.4.1;`TileAsyncLayer` 找不到要装 `SharpMap.Layers.BruTile`;文字模糊设 DPI Aware 并调 `MapTransform`。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 装包与目标框架看「安装」,图层与样式看「核心 API」及 WinForms/PostGIS/瓦片示例,「常见问题」给无图、乱码、类型冲突的对照。坐标变换细节用 `skill` 加载 `projnet4geoapi`,几何运算加载 `nettopologysuite`,新项目迁移到 `mapsui`。
5
+ - **执行环境**:`dotnet add package`、`dotnet restore`、`dotnet build` 走 `ops_bash`(Windows 是 MSYS bash,工程路径写 `/d/work/maptest`)
6
+ - `dotnet --list-sdks`、`Get-Command dotnet`、`$env:` 变量等 Windows 原生命令走 `pwsh`。关键约束:`SharpMap.UI` 只支持 .NET Framework 4.7.2,csproj 目标框架必须写 `net472`,不能写成 `net8.0`
7
+ - 只有核心包 `SharpMap`(netstandard2.0)能被新框架引用。渲染与批量出图用后台作业,`job_output` 收日志,`job_kill` 停掉卡住的任务。
8
+ - **先探测版本**:正文按 SharpMap 1.2.0 编写(2021-03 发布,仓库未归档但维护低频),坐标变换一侧必须用 `ProjNet4GeoAPI` 1.4.1。
9
+ - 先跑 `dotnet --version` 与 `dotnet list package` 确认目标框架与包版本:`dotnet restore` 输出 NU1902/NU1903/NU1904 漏洞告警是已知状态(传递依赖 `NetTopologySuite.Core` 1.15.3、`System.Drawing.Common` 4.6.0 等),不是装失败,但要在回复里说明而不是静默忽略。
10
+ - 正文只覆盖 1.2.0,没有 2.x,别照抄别的技能里的 ProjNet 2.x 写法
11
+ - **验证产物**:最终判据是图不是编译:`map.GetMap()` 取 `System.Drawing.Image` 后 `Save("output.png")`,再按正文的验收——能看到按人口分档的面、标注文字、底图瓦片齐全才算渲染正确。
12
+ - 构建只算前置:`dotnet build` 通过后必须打开 PNG 核对,会看图就用 `read_image` 真看一眼是否空白或整片偏移。
13
+ - SRID 一致性要单独查:`map.SRID` 与图层坐标系不一致时图能出但位置全错(例如 OSM 底图必须 3857),这属于正文「无图」以外更隐蔽的失败
14
+ - **风险与权限**:新建工程、装包、连 PostGIS、把 SharpMap 1.2.0 引入既有解决方案前用 `ask_user_question` 让用户确认(该包维护低频且带已知漏洞告警)
15
+ - PostGIS 连接串的密码不要写进代码、日志或回复,示例里用占位符。`ShapeFile` 构造函数没有 `Encoding` 重载,中文乱码要单独设 `shp.Encoding = Encoding.GetEncoding("GBK")`
16
+ - `Brush`/`Pen`/`Bitmap` 必须 `using`/`Dispose`,否则 GDI+ 句柄泄漏会拖垮长驻进程。
17
+ - **常见失败**:无图先查 `SRID` 与有没有调 `ZoomToExtents()`
18
+ - 找不到 `SharpMap.UI.WinForms` 是因为包名不存在,控件在 `SharpMap.UI` 里
19
+ - `CoordinateTransformation` 赋值编译失败是引了 ProjNet 2.x,换回 `ProjNet4GeoAPI` 1.4.1
20
+ - `TileAsyncLayer` 找不到要装 `SharpMap.Layers.BruTile`
21
+ - 文字模糊设 DPI Aware 并调 `MapTransform`。
@@ -1,8 +1,25 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;加载方式见「环境准备」与「核心 API → 加载扩展」,DDL 与函数表见「核心 API」,端到端导入查询导出见「典型工作流」,报错对照见「常见问题」。GDAL 侧的导入导出用 `skill` 加载 `gdal`,Python 侧读写用 `skill` 加载 `geopandas`,坐标转换细节加载 `proj`。
4
- - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash);Linux 的 `sudo apt install libsqlite3-mod-spatialite` 在 Windows 不可用,改用 conda-forge:`conda install -c conda-forge libspatialite`(会同时给出 `mod_spatialite.dll` 与 `sqlite3`),或解压官方 Windows 包后把 DLL 目录加进 PATH。`.load mod_spatialite` 是 sqlite shell 的内置命令而不是 SQL,Windows 下要写成 `.load mod_spatialite.dll` 并注意 shell 与 DLL 位数一致。一次性执行按正文写法把选项放库文件之前:`spatialite -cmd ".load mod_spatialite" mydb.sqlite "SELECT spatialite_version();"`;多条语句用 heredoc 从 stdin 送 `.load` + SQL,比转义引号稳。批量导入与大表建索引放后台作业,`job_output` 收进度、`job_kill` 收尾。
5
- - **先探测版本**:正文按 libspatialite 5.1.0(2023-08-04)与 spatialite-tools 5.1.0a 编写,截至 2026-11 仍为最新。先按正文三条验证依次过:库文件是否存在(Windows 是 `mod_spatialite.dll`)、CLI 能否加载并报版本 `spatialite -cmd ".load mod_spatialite" :memory: "SELECT spatialite_version();"`(Windows 上把库名写成 `mod_spatialite.dll`)、Python 侧 `python -c "import sqlite3; c=sqlite3.connect(':memory:'); c.enable_load_extension(True); c.load_extension('mod_spatialite'); print(c.execute('SELECT spatialite_version()').fetchone())"`;三条任一失败先解决加载问题,再动 SQL。发行版包常落后(如 bookworm 是 5.0.1),4.x 与 5.x 函数集不同(`GeosMakeValid`、`InitSpatialMetaData` 重载 5.x 才齐全),拿到版本号再决定用哪个函数名。
6
- - **验证产物**:导入或建索引后回读 `geometry_columns`:`SELECT f_table_name, f_geometry_column, geometry_type, srid, spatial_index_enabled FROM geometry_columns;` 确认几何列、SRID 与索引开关;再跑 `SELECT CheckSpatialIndex('表','geom');` 确认 RTree 与主表同步,返回 -1 就是没建好。导出的 GPKG 用 `ogrinfo -so out.gpkg 图层名` 核对要素数与 CRS。查询结果先 `SELECT count(*)` 再抽样几行,确认单位没有混用(4326 下 `ST_Distance` 返回度,米制要 `ST_Transform` 到 3857)。成品库文件用 `present` 交付。
7
- - **风险与权限**:`DROP TABLE`、`DisableSpatialIndex`、批量 `DELETE`/`UPDATE` 都改不回旧状态(事务只保护单次会话),执行前先备份 `.sqlite` 文件或复制成新路径,并用 `ask_user_question` 给「先备份 / 换新库 / 直接改」三个选项。GDAL 的 `-dsco SPATIALITE=YES` 会重建库结构,覆盖已有输出前先确认;`InitSpatialMetaData` 对已初始化库重复调用返回 0、不破坏数据,但仍应只跑一次。
8
- - **常见失败**:`no such function: InitSpatialMetaData` 是扩展没加载或加载的是空壳库,先 `.load` 再用 `spatialite_version()` 验证;`no such module: mod_spatialite` 给绝对路径加载;CLI 里 `.load` 报失败先查 shell 与库位数/构建是否匹配,再改用 Python 或 `ogrinfo` 路径;`CreateSpatialIndex` 返回 -1 是表里有名为 `rowid` 的物理列遮蔽了真 ROWID,重命名后再建;`geometry has invalid SRID` 是混入 SRID -1/0 的几何,用 `GeomFromText(wkt, 4326)` 赋回;查询慢是只用 `ST_Distance` 没加 `MbrWithin` 粗筛。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 加载方式见「环境准备」与「核心 API → 加载扩展」,DDL 与函数表见「核心 API」,端到端导入查询导出见「典型工作流」,报错对照见「常见问题」。GDAL 侧的导入导出用 `skill` 加载 `gdal`,Python 侧读写用 `skill` 加载 `geopandas`,坐标转换细节加载 `proj`。
5
+ - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash)
6
+ - Linux 的 `sudo apt install libsqlite3-mod-spatialite` 在 Windows 不可用,改用 conda-forge:`conda install -c conda-forge libspatialite`(会同时给出 `mod_spatialite.dll` 与 `sqlite3`),或解压官方 Windows 包后把 DLL 目录加进 PATH。
7
+ - `.load mod_spatialite` 是 sqlite shell 的内置命令而不是 SQL,Windows 下要写成 `.load mod_spatialite.dll` 并注意 shell 与 DLL 位数一致。
8
+ - 一次性执行按正文写法把选项放库文件之前:`spatialite -cmd ".load mod_spatialite" mydb.sqlite "SELECT spatialite_version();"`
9
+ - 多条语句用 heredoc 从 stdin 送 `.load` + SQL,比转义引号稳。批量导入与大表建索引放后台作业,`job_output` 收进度、`job_kill` 收尾。
10
+ - **先探测版本**:正文按 libspatialite 5.1.0(2023-08-04)与 spatialite-tools 5.1.0a 编写,截至 2026-11 仍为最新。
11
+ - 先按正文三条验证依次过:库文件是否存在(Windows 是 `mod_spatialite.dll`)、CLI 能否加载并报版本 `spatialite -cmd ".load mod_spatialite" :memory: "SELECT spatialite_version();"`(Windows 上把库名写成 `mod_spatialite.dll`)、Python 侧 `python -c "import sqlite3; c=sqlite3.connect(':memory:'); c.enable_load_extension(True); c.load_extension('mod_spatialite'); print(c.execute('SELECT spatialite_version()').fetchone())"`
12
+ - 三条任一失败先解决加载问题,再动 SQL。发行版包常落后(如 bookworm 是 5.0.1),4.x 与 5.x 函数集不同(`GeosMakeValid`、`InitSpatialMetaData` 重载 5.x 才齐全),拿到版本号再决定用哪个函数名。
13
+ - **验证产物**:导入或建索引后回读 `geometry_columns`:`SELECT f_table_name, f_geometry_column, geometry_type, srid, spatial_index_enabled FROM geometry_columns;` 确认几何列、SRID 与索引开关
14
+ - 再跑 `SELECT CheckSpatialIndex('表','geom');` 确认 RTree 与主表同步,返回 -1 就是没建好。
15
+ - 导出的 GPKG 用 `ogrinfo -so out.gpkg 图层名` 核对要素数与 CRS。
16
+ - 查询结果先 `SELECT count(*)` 再抽样几行,确认单位没有混用(4326 下 `ST_Distance` 返回度,米制要 `ST_Transform` 到 3857)。
17
+ - 成品库文件用 `present` 交付
18
+ - **风险与权限**:`DROP TABLE`、`DisableSpatialIndex`、批量 `DELETE`/`UPDATE` 都改不回旧状态(事务只保护单次会话),执行前先备份 `.sqlite` 文件或复制成新路径,并用 `ask_user_question` 给「先备份 / 换新库 / 直接改」三个选项。GDAL 的 `-dsco SPATIALITE=YES` 会重建库结构,覆盖已有输出前先确认
19
+ - `InitSpatialMetaData` 对已初始化库重复调用返回 0、不破坏数据,但仍应只跑一次。
20
+ - **常见失败**:`no such function: InitSpatialMetaData` 是扩展没加载或加载的是空壳库,先 `.load` 再用 `spatialite_version()` 验证
21
+ - `no such module: mod_spatialite` 给绝对路径加载
22
+ - CLI 里 `.load` 报失败先查 shell 与库位数/构建是否匹配,再改用 Python 或 `ogrinfo` 路径
23
+ - `CreateSpatialIndex` 返回 -1 是表里有名为 `rowid` 的物理列遮蔽了真 ROWID,重命名后再建
24
+ - `geometry has invalid SRID` 是混入 SRID -1/0 的几何,用 `GeomFromText(wkt, 4326)` 赋回
25
+ - 查询慢是只用 `ST_Distance` 没加 `MbrWithin` 粗筛。
@@ -1,8 +1,23 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,没有 reference 目录;正文「核心概念与命令」的 COG/STAC/TiTiler 三段与「典型工作流」三条链路是主线,「常见问题」按症状查。COG 侧命令与校验的通用细节用 `skill` 加载 `gdal`,pgstac 的库侧知识用 `postgis`,前端消费 TileJSON 用 `maplibre-gl-js`;不要 `read` 兄弟目录的 SKILL.md。
4
- - **执行环境**:Python 依赖装进会话工作区的 venv(`python -m venv .venv` 后 `.venv/Scripts/python -m pip install ...`,MSYS bash 里路径写 `/d/work/.venv/Scripts/python.exe`)。不要拿 `load_workspace_dependencies` 返回的随包 Python 试 `import rasterio`:那套解释器有 numpy/Pillow,但没有 GDAL/rasterio 绑定,`rio cogeo` 直接起不来。Windows 没有系统 GDAL 时装 conda-forge(`conda install -c conda-forge gdal rio-cogeo`)或跑官方镜像。`uvicorn` 与 docker 起的 TiTiler 都是常驻服务,必须 `run_in_background`,`job_output` 读到 `Uvicorn running on http://127.0.0.1:8000` 再发请求,收尾 `job_kill`;起服务前先 `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8000/` 探端口。
5
- - **先探测版本**:`rio cogeo --version` 应为 7.0.4,`python -c "import rasterio; print(rasterio.__version__, rasterio.__gdal_version__)"` 一次确认绑定与底层 GDAL 都在,`python -c "import titiler.core, stac_fastapi.api as m; print(titiler.core.__version__, m.__version__)"` 对 2.4.0 与 7.1.1。`pip install titiler` 装出来是停在 0.25.0 的旧元包、入口完全不同,看到这个版本号就卸掉改装 `titiler.application==2.4.0`;正文要求 Python >= 3.11,`python -V` 低于就先换解释器。
6
- - **验证产物**:COG 以 `rio cogeo validate output_cog.tif` 的返回内容为准(要 valid),再 `rio cogeo info output_cog.tif` 看 overviews 与 blocksize。服务用 `curl -s -o tile.png -w '%{http_code} %{content_type} %{size_download}\n'` 打 `/cog/tiles/WebMercatorQuad/8/210/98.png?url=...`,必须 200 + `image/png` + 非零字节,再用 `read_image` 看瓦片不是全黑或全透明(bidx 与 rescale 错位就长这样)。对象存储的 Range 能力单独验:`curl -s -r 0-1023 -o /dev/null -w '%{http_code}' <cog-url>` 要 206,回 200 说明 CDN 忽略了 Range,后续 416 与出图慢都从这里来。
7
- - **风险与权限**:对象存储凭据只放环境变量(`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` 由外部注入,命令里只引用变量名),不写进脚本、不贴进汇报;pgstac 迁移要超级用户且会改库结构,连生产库前用 `ask_user_question` 确认。对外暴露 8000/8080、把 COG 传到第三方桶、发布别人的影像之前确认许可,STAC 只描述数据、不改变版权;`cogeo-mosaic create` 会覆盖同名 `mosaic.json`,先换名输出。
8
- - **常见失败**:416 是文件没按 tile 组织或被截断,回 `rio cogeo validate` 重转;瓦片全黑先查 `bidx` 顺序与 `rescale`,单波段没拉伸也会全白;403 是服务进程没拿到桶凭据,改用预签名 URL 或配 IAM;`/stac/tiles` 400 多为 `url` 没做 URL 编码或 `assets` 键名与 Item 不符,先 `curl` 打开 Item JSON 核对。
3
+ - **加载与引用**:单文件技能,没有 reference 目录
4
+ - 正文「核心概念与命令」的 COG/STAC/TiTiler 三段与「典型工作流」三条链路是主线,「常见问题」按症状查。COG 侧命令与校验的通用细节用 `skill` 加载 `gdal`,pgstac 的库侧知识用 `postgis`,前端消费 TileJSON 用 `maplibre-gl-js`
5
+ - 不要 `read` 兄弟目录的 SKILL.md。
6
+ - **执行环境**:Python 依赖装进会话工作区的 venv(`python -m venv .venv` 后 `.venv/Scripts/python -m pip install ...`,MSYS bash 里路径写 `/d/work/.venv/Scripts/python.exe`)。
7
+ - 不要拿 `load_workspace_dependencies` 返回的随包 Python 试 `import rasterio`:那套解释器有 numpy/Pillow,但没有 GDAL/rasterio 绑定,`rio cogeo` 直接起不来。
8
+ - Windows 没有系统 GDAL 时装 conda-forge(`conda install -c conda-forge gdal rio-cogeo`)或跑官方镜像。
9
+ - `uvicorn` 与 docker 起的 TiTiler 都是常驻服务,必须 `run_in_background`,`job_output` 读到 `Uvicorn running on http://127.0.0.1:8000` 再发请求,收尾 `job_kill`
10
+ - 起服务前先 `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8000/` 探端口。
11
+ - **先探测版本**:`rio cogeo --version` 应为 7.0.4,`python -c "import rasterio; print(rasterio.__version__, rasterio.__gdal_version__)"` 一次确认绑定与底层 GDAL 都在,`python -c "import titiler.core, stac_fastapi.api as m; print(titiler.core.__version__, m.__version__)"` 对 2.4.0 与 7.1.1。
12
+ - `pip install titiler` 装出来是停在 0.25.0 的旧元包、入口完全不同,看到这个版本号就卸掉改装 `titiler.application==2.4.0`
13
+ - 正文要求 Python >= 3.11,`python -V` 低于就先换解释器。
14
+ - **验证产物**:COG 以 `rio cogeo validate output_cog.tif` 的返回内容为准(要 valid),再 `rio cogeo info output_cog.tif` 看 overviews 与 blocksize。
15
+ - 服务用 `curl -s -o tile.png -w '%{http_code} %{content_type} %{size_download}\n'` 打 `/cog/tiles/WebMercatorQuad/8/210/98.png?url=...`,必须 200 + `image/png` + 非零字节,再用 `read_image` 看瓦片不是全黑或全透明(bidx 与 rescale 错位就长这样)。
16
+ - 对象存储的 Range 能力单独验:`curl -s -r 0-1023 -o /dev/null -w '%{http_code}' <cog-url>` 要 206,回 200 说明 CDN 忽略了 Range,后续 416 与出图慢都从这里来
17
+ - **风险与权限**:对象存储凭据只放环境变量(`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` 由外部注入,命令里只引用变量名),不写进脚本、不贴进汇报
18
+ - pgstac 迁移要超级用户且会改库结构,连生产库前用 `ask_user_question` 确认。对外暴露 8000/8080、把 COG 传到第三方桶、发布别人的影像之前确认许可,STAC 只描述数据、不改变版权
19
+ - `cogeo-mosaic create` 会覆盖同名 `mosaic.json`,先换名输出。
20
+ - **常见失败**:416 是文件没按 tile 组织或被截断,回 `rio cogeo validate` 重转
21
+ - 瓦片全黑先查 `bidx` 顺序与 `rescale`,单波段没拉伸也会全白
22
+ - 403 是服务进程没拿到桶凭据,改用预签名 URL 或配 IAM
23
+ - `/stac/tiles` 400 多为 `url` 没做 URL 编码或 `assets` 键名与 Item 不符,先 `curl` 打开 Item JSON 核对。
@@ -1,8 +1,21 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;命令骨架与常用工具参数看「核心命令」,DEM→河网→流域的完整流程看「典型工作流」,报错对照看「常见问题」,完整工具清单按正文给的「工具索引」链接查。前后处理(重投影、栅格裁剪、格式转换)用 `skill` 加载 `gdal`,点云格式转换加载 `pdal`,交叉验证结果加载 `grass-gis`。
4
- - **执行环境**:`whitebox_tools` 二进制命令走 `ops_bash`(Windows 是 MSYS bash,写 `/d/tools/WBT/whitebox_tools.exe` 并整体加引号);正文里的 `cd /opt/WBT` 是 Linux 路径,Windows 下先 `pwsh` 里确认解压目录(`Get-ChildItem C:\Tools\WBT`)再用绝对路径调用。`python build.py` 源码编译要 Rust 工具链且耗时数分钟,必须用后台作业跑(`run_in_background` + `job_output` 看进度);`pip install whitebox` 首次调用会联网下载二进制,离线环境要手动放置 WBT 目录。
5
- - **先探测版本**:核心库正文按 2.4.0 编写(conda-forge 的 `whitebox_tools` 同为 2.4.0),PyPI 前端 `whitebox` 是 2.3.6,两者版本号不一致属正常。先跑 `whitebox_tools --version` 拿二进制版本,再跑 `python -c "import whitebox; print(whitebox.__version__)"` 拿封装版本;工具能力以二进制为准,回答里要说明按哪个版本写。查工具与参数用正文那组封装方法,不要猜:`wbt.list_tools()`(可按关键词过滤)、`wbt.tool_help("Slope")`、`wbt.tool_parameters("Slope")`、`wbt.version()`;CLI 侧对应 `--listtools`、`--toolhelp`、`--toolparameters`、`--toolbox`、`--viewcode`(在浏览器打开该工具源码页,远程会话里慎用)。
6
- - **验证产物**:退出码 0 不算完成。先 `gdalinfo -json accum.tif` 看极值:流量累积的最大值应与流域面积/像元数同量级,若全是 1 说明 DEM 未决口或单位不一致;坡度在 0–90 度、坡向在 0–360;再 `ogrinfo -so streams.shp` 核对河网要素数与 CRS。渲染或阴影产物(`Hillshade`、`LidarHillshade`)用 `read_image` 真看一眼是否通体灰或空白。多步水文流水线用 `todo_write` 列「探测 → 决口 → 流向/累积 → 提河网 → 流域」并逐项核对中间文件。
7
- - **风险与权限**:`--wd` 之后的相对路径与 `--output=` 指向已有文件会直接覆盖,跑批量前先备份或换输出名,并用 `ask_user_question` 让用户在「换名输出 / 覆盖 / 先备份」之间选;下载二进制、源码编译装 Rust、改动 PATH 前也要先征得同意。大 DEM 内存占用高,先 `Clip` 到研究区或分块处理;`--toolparameters` 或 `wbt.tool_parameters()` 的 JSON 先写文件再 `read`/`grep`,不要整段刷进上下文。
8
- - **常见失败**:`whitebox_tools: command not found` 是目录没进 PATH,`cd` 到 WBT 目录或写绝对路径(Windows 记得 `.exe`);跑完既无输出也无报错,几乎都是相对路径没对上 `--wd`,改用绝对路径重跑一次;CLI 的 `--run` 与 Python 便捷方法命名不同:CLI 用 CamelCase(`FillDepressions`),`wbt` 便捷方法是 snake_case(`wbt.fill_depressions()`),`wbt.run_tool` 两种都接受但参数仍是 `--flag=value` 列表;工具名不存在先用 `wbt.list_tools()` 或 `--listtools` 确认真名;参数被忽略是照抄了别的工具的参数名,用 `wbt.tool_parameters()` / `--toolparameters` 取真实定义。
3
+ - **加载与引用**:单文件技能,无 reference
4
+ - 命令骨架与常用工具参数看「核心命令」,DEM→河网→流域的完整流程看「典型工作流」,报错对照看「常见问题」,完整工具清单按正文给的「工具索引」链接查。前后处理(重投影、栅格裁剪、格式转换)用 `skill` 加载 `gdal`,点云格式转换加载 `pdal`,交叉验证结果加载 `grass-gis`。
5
+ - **执行环境**:`whitebox_tools` 二进制命令走 `ops_bash`(Windows 是 MSYS bash,写 `/d/tools/WBT/whitebox_tools.exe` 并整体加引号)
6
+ - 正文里的 `cd /opt/WBT` 是 Linux 路径,Windows 下先 `pwsh` 里确认解压目录(`Get-ChildItem C:\Tools\WBT`)再用绝对路径调用。`python build.py` 源码编译要 Rust 工具链且耗时数分钟,必须用后台作业跑(`run_in_background` + `job_output` 看进度)
7
+ - `pip install whitebox` 首次调用会联网下载二进制,离线环境要手动放置 WBT 目录。
8
+ - **先探测版本**:核心库正文按 2.4.0 编写(conda-forge 的 `whitebox_tools` 同为 2.4.0),PyPI 前端 `whitebox` 是 2.3.6,两者版本号不一致属正常。先跑 `whitebox_tools --version` 拿二进制版本,再跑 `python -c "import whitebox; print(whitebox.__version__)"` 拿封装版本
9
+ - 工具能力以二进制为准,回答里要说明按哪个版本写。查工具与参数用正文那组封装方法,不要猜:`wbt.list_tools()`(可按关键词过滤)、`wbt.tool_help("Slope")`、`wbt.tool_parameters("Slope")`、`wbt.version()`
10
+ - CLI 侧对应 `--listtools`、`--toolhelp`、`--toolparameters`、`--toolbox`、`--viewcode`(在浏览器打开该工具源码页,远程会话里慎用)。
11
+ - **验证产物**:退出码 0 不算完成。先 `gdalinfo -json accum.tif` 看极值:流量累积的最大值应与流域面积/像元数同量级,若全是 1 说明 DEM 未决口或单位不一致
12
+ - 坡度在 0–90 度、坡向在 0–360
13
+ - 再 `ogrinfo -so streams.shp` 核对河网要素数与 CRS。渲染或阴影产物(`Hillshade`、`LidarHillshade`)用 `read_image` 真看一眼是否通体灰或空白。多步水文流水线用 `todo_write` 列「探测 → 决口 → 流向/累积 → 提河网 → 流域」并逐项核对中间文件。
14
+ - **风险与权限**:`--wd` 之后的相对路径与 `--output=` 指向已有文件会直接覆盖,跑批量前先备份或换输出名,并用 `ask_user_question` 让用户在「换名输出 / 覆盖 / 先备份」之间选
15
+ - 下载二进制、源码编译装 Rust、改动 PATH 前也要先征得同意。大 DEM 内存占用高,先 `Clip` 到研究区或分块处理
16
+ - `--toolparameters` 或 `wbt.tool_parameters()` 的 JSON 先写文件再 `read`/`grep`,不要整段刷进上下文。
17
+ - **常见失败**:`whitebox_tools: command not found` 是目录没进 PATH,`cd` 到 WBT 目录或写绝对路径(Windows 记得 `.exe`)
18
+ - 跑完既无输出也无报错,几乎都是相对路径没对上 `--wd`,改用绝对路径重跑一次
19
+ - CLI 的 `--run` 与 Python 便捷方法命名不同:CLI 用 CamelCase(`FillDepressions`),`wbt` 便捷方法是 snake_case(`wbt.fill_depressions()`),`wbt.run_tool` 两种都接受但参数仍是 `--flag=value` 列表
20
+ - 工具名不存在先用 `wbt.list_tools()` 或 `--listtools` 确认真名
21
+ - 参数被忽略是照抄了别的工具的参数名,用 `wbt.tool_parameters()` / `--toolparameters` 取真实定义。
@@ -19,6 +19,15 @@ export declare const REQUIRED_LABELS: readonly string[];
19
19
  /** Labels whose bullet must carry a concrete command or tool in backticks. */
20
20
  export declare const CONCRETE_LABELS: readonly string[];
21
21
 
22
+ /** How many required labels must decompose into indented sub-bullets. */
23
+ export declare const MIN_NESTED_LABELS: number;
24
+
25
+ /** Minimum indented sub-bullets across one per-skill guidance file. */
26
+ export declare const MIN_NESTED_BULLETS: number;
27
+
28
+ /** List the indented sub-bullets of one label section, or of the whole file. */
29
+ export declare function nestedBullets(text: string, label?: string): string[];
30
+
22
31
  /** DeepSeek Harness tools every supported build exposes; the citation minimums count these. */
23
32
  export declare const CORE_TOOLS: readonly string[];
24
33
 
@@ -59,6 +59,29 @@ export const REQUIRED_LABELS = ["加载与引用", "执行环境", "先探测版
59
59
  */
60
60
  export const CONCRETE_LABELS = ["先探测版本", "验证产物"];
61
61
 
62
+ /**
63
+ * How many of the required labels must decompose into indented sub-bullets, and
64
+ * how many sub-bullets a file must carry in total.
65
+ *
66
+ * A flat file with six 600-character bullets is technically complete and
67
+ * practically unreadable: the model sees one paragraph per label and cannot
68
+ * tell which sentence applies now. Sub-bullets are the cheapest fix that keeps
69
+ * the five required labels and the character budget intact.
70
+ */
71
+ export const MIN_NESTED_LABELS = 4;
72
+
73
+ /** Minimum indented sub-bullets across one per-skill guidance file. */
74
+ export const MIN_NESTED_BULLETS = 8;
75
+
76
+ /**
77
+ * Words that mark an optional-plugin capability as guarded.
78
+ *
79
+ * Guidance may name tools such as "spawn_teammate", but a bare citation breaks
80
+ * in a session without that plugin. The same line must say what happens when
81
+ * the capability is absent, so the fallback travels with the citation.
82
+ */
83
+ const FALLBACK = /退回|没有|不一定|可选插件|未启用|不存在/u;
84
+
62
85
  /**
63
86
  * DeepSeek Harness tools that every supported build exposes. Guidance may
64
87
  * depend on these unconditionally.
@@ -319,6 +342,25 @@ function bulletBody(text, label) {
319
342
  return next === -1 ? rest : rest.slice(0, next);
320
343
  }
321
344
 
345
+ /**
346
+ * List the indented sub-bullets of one "\"- **label**:…\"" section.
347
+ *
348
+ * Sub-bullets are written two spaces in, so they stay inside their parent
349
+ * section and never count as one of the five required top-level bullets.
350
+ *
351
+ * @param text - the normalized adaptation text.
352
+ * @param label - the label between the asterisks; omit to count the whole file.
353
+ * @returns the sub-bullet lines, already trimmed.
354
+ */
355
+ export function nestedBullets(text, label) {
356
+ const source = label === undefined ? text : bulletBody(text, label);
357
+ if (source === undefined) return [];
358
+ return source
359
+ .split("\n")
360
+ .filter((line) => /^[ \t]+-[ \t]+\S/u.test(line))
361
+ .map((line) => line.trim());
362
+ }
363
+
322
364
  /**
323
365
  * Report every problem with one per-skill adaptation file.
324
366
  *
@@ -360,6 +402,22 @@ export function adaptationProblems(name, text) {
360
402
  if (body === undefined) continue;
361
403
  if (!/`[^`]+`/u.test(body)) problems.push(label + ': "' + required + '" must cite a concrete command or tool in backticks, not just prose');
362
404
  }
405
+ const emptyLabels = REQUIRED_LABELS.filter((required) => nestedBullets(text, required).length === 0);
406
+ if (REQUIRED_LABELS.length - emptyLabels.length < MIN_NESTED_LABELS) {
407
+ problems.push(
408
+ label +
409
+ ": " +
410
+ (REQUIRED_LABELS.length - emptyLabels.length) +
411
+ " label(s) decompose into sub-bullets, needs at least " +
412
+ MIN_NESTED_LABELS +
413
+ "; add two-space \"- \" items under " +
414
+ emptyLabels.slice(0, REQUIRED_LABELS.length - MIN_NESTED_LABELS).join(" / ")
415
+ );
416
+ }
417
+ const nested = nestedBullets(text);
418
+ if (nested.length < MIN_NESTED_BULLETS) {
419
+ problems.push(label + ": carries " + nested.length + " sub-bullet(s), needs at least " + MIN_NESTED_BULLETS + " so each label breaks into concrete items");
420
+ }
363
421
  const tools = citedCoreTools(text);
364
422
  if (tools.length < SKILL_MIN_CORE_TOOLS) {
365
423
  problems.push(label + ": cites " + tools.length + " core DeepSeek Harness tool(s), needs at least " + SKILL_MIN_CORE_TOOLS + " (one of " + CORE_TOOLS.slice(0, 6).join("/") + "/…); optional-plugin tools do not count");
@@ -386,6 +444,12 @@ export function commonProblems(text) {
386
444
  if (bullets.length < COMMON_MIN_BULLETS) problems.push(label + ": needs at least " + COMMON_MIN_BULLETS + ' bullets of the form "- **label**:…"');
387
445
  const tools = citedCoreTools(text);
388
446
  if (tools.length < COMMON_MIN_CORE_TOOLS) problems.push(label + ": cites " + tools.length + " core DeepSeek Harness tool(s), needs at least " + COMMON_MIN_CORE_TOOLS);
447
+ for (const line of text.split("\n")) {
448
+ const optional = OPTIONAL_TOOLS.filter((tool) => line.includes("`" + tool + "`"));
449
+ if (optional.length > 0 && !FALLBACK.test(line)) {
450
+ problems.push(label + ": cites optional-plugin tool(s) " + optional.join("/") + " without stating the fallback for sessions that do not expose them");
451
+ }
452
+ }
389
453
  if (UNFINISHED.test(text)) problems.push(label + ": still contains an unfinished marker (TODO/FIXME/TBD/待补充/占位)");
390
454
  return problems;
391
455
  }
package/lib/index.d.ts CHANGED
@@ -16,12 +16,16 @@ export interface OpenGisResourceBase {
16
16
  path: string;
17
17
  }
18
18
 
19
- /** Upstream routing metadata carried on a candidate (never on a definition). */
19
+ /** Routing metadata carried on a candidate (never on a definition). */
20
20
  export interface OpenGisSkillMetadata {
21
21
  /** Upstream category directory, always "gis" for this pack. */
22
22
  category?: string;
23
23
  /** Parsed upstream metadata.tags. */
24
24
  tags: string[];
25
+ /** Coarse groups from lib/taxonomy.js, used by the plugin config filter. */
26
+ groups: string[];
27
+ /** Local trigger phrases from lib/taxonomy.js, in request wording. */
28
+ keywords: string[];
25
29
  }
26
30
 
27
31
  /** One skill summary returned by the provider catalog. */
@@ -57,12 +61,12 @@ export interface OpenGisSkillProvider {
57
61
  get(candidate: OpenGisSkillCandidate, options?: { signal?: AbortSignal }): Promise<OpenGisSkillDefinition>;
58
62
  }
59
63
 
60
- /** Cordis context surface used by this plugin. */
61
- export interface OpenGisSkillHost {
62
- skills: {
63
- registerProvider(create: (control: { signal: AbortSignal; invalidate(): void }) => OpenGisSkillProvider): unknown;
64
- };
64
+ /** Plugin config: trim the bundled catalog without editing the package. */
65
+ export interface OpenGisSkillConfig {
66
+ /** Groups to union; ignored when "skills" is non-empty. */
67
+ groups?: string[];
68
+ /** Explicit skill allow list; wins over "groups". */
69
+ skills?: string[];
70
+ /** Skill deny list, applied last. */
71
+ exclude?: string[];
65
72
  }
66
-
67
- /** Register the bundled OpenGIS skill provider on "ctx.skills". */
68
- export declare function apply(ctx: OpenGisSkillHost): void;