@dsh-gis/dsh-opengis-skill 0.1.3 → 0.3.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 (117) hide show
  1. package/CHANGELOG.md +95 -0
  2. package/README.md +68 -28
  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 +19 -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 +9 -0
  30. package/adaptations/opengis-daf.md +9 -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 +283 -0
  46. package/assets/cesiumjs/SKILL.md +81 -35
  47. package/assets/deck-gl/SKILL.md +26 -34
  48. package/assets/duckdb-spatial/SKILL.md +363 -0
  49. package/assets/gdal/SKILL.md +55 -33
  50. package/assets/gdal/reference/raster-tools.md +14 -0
  51. package/assets/gdal/reference/vector-tools.md +5 -0
  52. package/assets/gdal-api/SKILL.md +12 -18
  53. package/assets/gdal-api/reference/raster-api.md +7 -0
  54. package/assets/gdal-api/reference/vector-api.md +9 -0
  55. package/assets/geolibre/SKILL.md +357 -0
  56. package/assets/geometry-api-java/SKILL.md +10 -16
  57. package/assets/geometry-api-net/SKILL.md +70 -32
  58. package/assets/geometry-api-net/reference/geometry-types.md +5 -0
  59. package/assets/geonode/SKILL.md +340 -0
  60. package/assets/geopandas/SKILL.md +21 -24
  61. package/assets/geopandas/reference/core-api.md +4 -0
  62. package/assets/geopipe-agent/SKILL.md +29 -31
  63. package/assets/geopipe-agent/reference/steps-reference.md +12 -0
  64. package/assets/geopipe-agent/reference/workflows.md +8 -0
  65. package/assets/geoserver/SKILL.md +10 -15
  66. package/assets/geoserver-cloud/SKILL.md +25 -33
  67. package/assets/geoserver-rest-api/SKILL.md +17 -19
  68. package/assets/geoserver-rest-api/reference/endpoints.md +16 -0
  69. package/assets/geotools/SKILL.md +12 -17
  70. package/assets/geotools/reference/raster-rendering.md +5 -0
  71. package/assets/geotools/reference/vector-io.md +7 -0
  72. package/assets/grass-gis/SKILL.md +26 -33
  73. package/assets/jts/SKILL.md +12 -16
  74. package/assets/jts/reference/geometry-operations.md +13 -0
  75. package/assets/kepler-gl/SKILL.md +306 -0
  76. package/assets/leaflet/SKILL.md +58 -40
  77. package/assets/mapbox-gl-js/SKILL.md +26 -33
  78. package/assets/mapserver/SKILL.md +21 -29
  79. package/assets/mapsui/SKILL.md +109 -63
  80. package/assets/nettopologysuite/SKILL.md +96 -31
  81. package/assets/opengis-all/SKILL.md +91 -289
  82. package/assets/opengis-all/reference/data-stages.md +269 -4
  83. package/assets/opengis-all/reference/workflow-cheatsheets.md +7 -0
  84. package/assets/opengis-daf/SKILL.md +10 -17
  85. package/assets/opengis-utils-for-java/SKILL.md +58 -49
  86. package/assets/opengis-utils-for-java/reference/common-tasks.md +16 -12
  87. package/assets/opengis-utils-for-net/SKILL.md +109 -48
  88. package/assets/opengis-utils-for-net/reference/code-patterns.md +15 -11
  89. package/assets/opengis-utils-for-net/reference/util-classes.md +35 -26
  90. package/assets/openlayers/SKILL.md +81 -28
  91. package/assets/pdal/SKILL.md +25 -27
  92. package/assets/postgis/SKILL.md +80 -35
  93. package/assets/proj/SKILL.md +32 -41
  94. package/assets/projnet4geoapi/SKILL.md +293 -0
  95. package/assets/pyqgis/SKILL.md +33 -30
  96. package/assets/pyqgis/reference/processing-rendering.md +6 -0
  97. package/assets/pyqgis/reference/vector-raster-layers.md +6 -0
  98. package/assets/qgis-process/SKILL.md +75 -33
  99. package/assets/qgis-process/reference/algorithm-cheatsheet.md +6 -0
  100. package/assets/qgis-server/SKILL.md +25 -31
  101. package/assets/shapely/SKILL.md +136 -84
  102. package/assets/shapely/reference/operations-reference.md +12 -0
  103. package/assets/sharpmap/SKILL.md +97 -60
  104. package/assets/spatialite/SKILL.md +358 -0
  105. package/assets/whitebox-tools/SKILL.md +262 -0
  106. package/lib/adaptations.d.ts +53 -0
  107. package/lib/adaptations.js +343 -0
  108. package/lib/catalog.d.ts +7 -1
  109. package/lib/catalog.js +9 -1
  110. package/lib/index.d.ts +10 -1
  111. package/lib/index.js +34 -3
  112. package/lib/skill-file.d.ts +12 -0
  113. package/lib/skill-file.js +133 -18
  114. package/locale/en.json +1 -1
  115. package/locale/zh.json +1 -1
  116. package/package.json +12 -2
  117. package/upstream.json +73 -57
@@ -0,0 +1,262 @@
1
+ ---
2
+ name: whitebox-tools
3
+ description: "Use when doing advanced raster, terrain or LiDAR geoprocessing with WhiteboxTools v2.4.0 — whitebox_tools --run=Slope/FillDepressions/BreachDepressions/FlowAccumulationFullWorkflow/Watershed/ExtractStreams, lidar_* tools for LAS point clouds, or the whitebox (whitebox-python 2.3.6) WhiteboxTools wrapper in Python. Also for 'whitebox_tools: command not found', mismatched Python frontend versions, and missing DEM/flow-accumulation intermediate outputs."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "geospatial, raster, terrain-analysis, hydrology, lidar, dem, command-line, python, rust, geoprocessing"
8
+ ---
9
+
10
+ > **项目地址:** <https://github.com/jblindsay/whitebox-tools>
11
+ >
12
+ > **官方文档:** 用户手册 <https://jblindsay.github.io/wbt_book/intro.html>(GHRG 手册站镜像;上游 README 里的 `www.whiteboxgeo.com/manual/wbt_book/preface.html` 实测 404,改用本地址)
13
+ >
14
+ > **最新版本:** 2.4.0(截至 2026-11,[GitHub Release](https://github.com/jblindsay/whitebox-tools/releases);conda-forge `whitebox_tools` 亦为 2.4.0)
15
+ >
16
+ > **PyPI 前端:** `whitebox` 2.3.6(whitebox-python 封装,仅负责下载与调用二进制,版本号落后于核心库)
17
+ >
18
+ > **许可证:** MIT
19
+ >
20
+ > **注意:** 上游仓库 README 已标记为 legacy,新开发转向 <https://github.com/jblindsay/whitebox_next_gen>;但 2.4.0 仍是当前稳定可用的开源版本,本文以其为基准。
21
+
22
+ ## 概述
23
+
24
+ WhiteboxTools 是圭尔夫大学 GHRG 实验室(John Lindsay)用 Rust 编写的独立地理空间分析引擎,面向「分析后端」而非制图:它不渲染地图,只接收栅格/矢量/LAS 输入并产出分析结果。相比通用 GIS 桌面软件,它的优势在于命令行与脚本化,几百个工具都能通过统一参数形式批量执行,适合 DEM 地形分析、水文建模与 LiDAR 处理流水线。
25
+
26
+ - **地形分析**:坡度、坡向、曲率、山体阴影、相对高程、地形位置指数(TPI)、多尺度位置分析
27
+ - **水文分析**:洼地填充/决口、D8/DInf/FD8 流向与流量累积、河网提取、Strahler 分级、流域划分
28
+ - **LiDAR**:点云信息与直方图、按类别过滤、去噪、地面点分类、插值成 DEM、密度与强度栅格
29
+ - **栅格与矢量工具**:栅格计算器、重分类、分区统计、矢量栅格互转、要素裁剪与合并
30
+ - **统一接口**:`whitebox_tools --run=<ToolName> [参数]`,另有 `--toolhelp`、`--toolparameters` 查询元数据
31
+
32
+ ---
33
+
34
+ ## 环境准备
35
+
36
+ ### 方式一:下载预编译二进制(推荐)
37
+
38
+ 到 <https://github.com/jblindsay/whitebox-tools/releases> 下载对应平台的预编译压缩包,解压后目录内含 `whitebox_tools`(Windows 为 `whitebox_tools.exe`)与 `WBT` 插件目录。
39
+
40
+ ```bash
41
+ cd /opt/WBT # 解压后的 WBT 目录
42
+ ./whitebox_tools --version
43
+ ./whitebox_tools --listtools slope | head -5
44
+ ```
45
+
46
+ ```powershell
47
+ # Windows PowerShell
48
+ cd C:\Tools\WBT
49
+ .\whitebox_tools.exe --version
50
+ ```
51
+
52
+ ### 方式二:源码编译(适合无预编译包的平台)
53
+
54
+ 需要 Rust 工具链;Windows 上还需 MSVC 或 GNU 链接器。仓库根目录的 `build.py` 会调用 `cargo` 并把产物整理到 `WBT/`。
55
+
56
+ ```bash
57
+ git clone https://github.com/jblindsay/whitebox-tools.git
58
+ cd whitebox-tools
59
+ python build.py
60
+ ./WBT/whitebox_tools --version
61
+ ```
62
+
63
+ ### 方式三:Python 前端(`whitebox` 包)
64
+
65
+ `whitebox-python` 是社区维护的封装,首次运行会下载 / 复用 WBT 二进制;它不提升核心工具版本,因此工具能力以二进制实际版本为准。
66
+
67
+ ```bash
68
+ pip install whitebox==2.3.6
69
+
70
+ # 或 conda
71
+ conda install -c conda-forge whitebox
72
+ ```
73
+
74
+ ```python
75
+ import whitebox
76
+ print(whitebox.__version__) # 2.3.6 —— 这是 Python 封装版本
77
+
78
+ wbt = whitebox.WhiteboxTools()
79
+ wbt.set_verbose_mode(False)
80
+ print(wbt.version()) # 打印底层 WhiteboxTools 二进制版本
81
+ ```
82
+
83
+ **验证要点**:`--version` 输出的是核心库版本;Python 包版本号与核心库不一致属正常现象,排错时以 `--version` 为准。
84
+
85
+ ---
86
+
87
+ ## 核心命令
88
+
89
+ ### 命令行骨架
90
+
91
+ ```bash
92
+ whitebox_tools --wd="data/" --run=Slope --dem=input.tif --output=slope.tif --units=degrees -v
93
+ ```
94
+
95
+ | 参数 | 作用 |
96
+ |------|------|
97
+ | `--wd` / `--cd` | 切换工作目录;与 `--run` 连用,之后的相对路径都基于它 |
98
+ | `-r` / `--run` | 指定工具名(CamelCase),如 `Slope`、`FillDepressions` |
99
+ | `-v` | 详细模式,打印进度与耗时;`-v=false` 关闭 |
100
+ | `--listtools [关键词]` | 列出工具及描述,可按关键词过滤 |
101
+ | `--toolhelp=<Tool>` | 打印某工具的使用帮助 |
102
+ | `--toolparameters=<Tool>` | 以 JSON 输出参数定义,适合脚本动态组装参数 |
103
+ | `--version` | 版本信息 |
104
+
105
+ **不要凭记忆写参数名**:不同工具的参数差异很大(例如坡度用 `--units`,流量累积工作流用五个 `--out_*` 参数)。写脚本前先 `--toolparameters` 取 JSON,再据此拼参数。
106
+
107
+ ### 常用工具速查
108
+
109
+ | 工具名 | 作用 | 关键参数 |
110
+ |--------|------|----------|
111
+ | `Slope` | 坡度栅格 | `--dem`、`--output`、`--units`(degrees/radians/percent)、`--zfactor` |
112
+ | `Aspect` | 坡向 | `--dem`、`--output` |
113
+ | `Hillshade` | 山体阴影 | `--dem`、`--output`、`--azimuth`、`--altitude`、`--zfactor` |
114
+ | `FillDepressions` | 填洼 | `--dem`、`--output`、`--fix_flats`、`--flat_increment` |
115
+ | `BreachDepressions` | 洼地决口(保留更多地形细节) | `--dem`、`--output`、`--max_depth`、`--max_length`、`--fill_pits` |
116
+ | `D8Pointer` | D8 流向 | `--dem`、`--output`、`--esri_pntr` |
117
+ | `D8FlowAccumulation` | D8 流量累积 | `--input`、`--output`、`--out_type` |
118
+ | `FlowAccumulationFullWorkflow` | 一键:决口 + 流向 + 累积 | `--dem`、`--out_dem`、`--out_pntr`、`--out_accum`、`--out_type` |
119
+ | `ExtractStreams` | 阈值法提取河网 | `--flow_accum`、`--output`、`--threshold` |
120
+ | `StrahlerStreamOrder` | 河网 Strahler 分级 | `--streams`、`--d8_pntr`、`--output` |
121
+ | `Watershed` | 由流向与倾泻点划分流域 | `--d8_pntr`、`--pour_pts`、`--output` |
122
+ | `LidarInfo` | LAS/LAZ 基本信息 | `--input` |
123
+ | `LidarPointDensity` | 点密度栅格 | `--input`、`--output`、`--cell_size` |
124
+ | `LidarHillshade` | 点云生成山体阴影 | `--input`、`--output`、`--azimuth`、`--altitude` |
125
+ | `Mosaic` | 多栅格拼接 | `--inputs`、`--output` |
126
+ | `Clip` | 按矢量范围裁剪栅格 | `--input`、`--clip`、`--output` |
127
+
128
+ 完整列表用 `whitebox_tools --listtools`;以下为常用子集,参数以 `--toolparameters` 输出为准。
129
+
130
+ ### Python 调用
131
+
132
+ ```python
133
+ from whitebox import WhiteboxTools
134
+
135
+ wbt = WhiteboxTools()
136
+ wbt.set_working_dir("data")
137
+ wbt.set_verbose_mode(False)
138
+
139
+ # 方法名是工具名的 snake_case 形式,参数名与 CLI 的路由一致
140
+ wbt.slope(dem="dem.tif", output="slope.tif", units="degrees")
141
+ wbt.hillshade(dem="dem.tif", output="hillshade.tif", azimuth=315.0, altitude=30.0)
142
+
143
+ # 任何工具都能用 run_tool 统一调用
144
+ wbt.run_tool("FillDepressions", ["--dem=dem.tif", "--output=dem_filled.tif", "--fix_flats=true"])
145
+ ```
146
+
147
+ `run_tool(tool_name, args)` 的 `args` 是 `--flag=value` 字符串列表,适合官方封装尚未覆盖的新工具;两种方式可混用。
148
+
149
+ ---
150
+
151
+ ## 典型工作流
152
+
153
+ 从原始 DEM 到河网与流域的完整水文分析:
154
+
155
+ **输入**:`data/dem.tif`(投影坐标系 DEM,水平与垂直单位一致)
156
+ **输出**:`watershed.tif`、`streams.tif`、`accum.tif`
157
+
158
+ 1. 先检查 DEM 是否有异常值与坐标系单位
159
+ 2. 用 `FlowAccumulationFullWorkflow` 一次完成决口、流向与流量累积,避免中间文件散落
160
+ 3. 用流量累积的阈值提取河网
161
+ 4. 按倾泻点划分流域(倾泻点可先用 `SnapPourPoints` 吸附到河网)
162
+ 5. 如需河网矢量,用 `RasterStreamsToVector`
163
+
164
+ ```bash
165
+ cd /opt/WBT
166
+
167
+ # 1) 决口 + D8 流向 + 流量累积
168
+ ./whitebox_tools --wd="D:/work/hydro" --run=FlowAccumulationFullWorkflow \
169
+ --dem=dem.tif --out_dem=dem_breached.tif \
170
+ --out_pntr=flow_pntr.tif --out_accum=accum.tif --out_type=cells -v
171
+
172
+ # 2) 阈值提取河网(阈值随分辨率与气候区调整,先看累积值分布)
173
+ ./whitebox_tools --wd="D:/work/hydro" --run=ExtractStreams \
174
+ --flow_accum=accum.tif --output=streams.tif --threshold=1000 -v
175
+
176
+ # 3) 倾泻点吸附后划分流域
177
+ ./whitebox_tools --wd="D:/work/hydro" --run=SnapPourPoints \
178
+ --pour_pts=pour_pts.shp --flow_accum=accum.tif --snap_dist=3 --output=pour_pts_snapped.shp -v
179
+ ./whitebox_tools --wd="D:/work/hydro" --run=Watershed \
180
+ --d8_pntr=flow_pntr.tif --pour_pts=pour_pts_snapped.shp --output=watershed.tif -v
181
+
182
+ # 4) 河网转矢量(可选)
183
+ ./whitebox_tools --wd="D:/work/hydro" --run=RasterStreamsToVector \
184
+ --streams=streams.tif --d8_pntr=flow_pntr.tif --output=streams.shp -v
185
+ ```
186
+
187
+ Python 等价写法:
188
+
189
+ ```python
190
+ from whitebox import WhiteboxTools
191
+
192
+ wbt = WhiteboxTools()
193
+ wbt.set_working_dir("D:/work/hydro")
194
+
195
+ wbt.flow_accumulation_full_workflow(
196
+ dem="dem.tif",
197
+ out_dem="dem_breached.tif",
198
+ out_pntr="flow_pntr.tif",
199
+ out_accum="accum.tif",
200
+ out_type="cells",
201
+ )
202
+ wbt.extract_streams(flow_accum="accum.tif", output="streams.tif", threshold=1000)
203
+ wbt.watershed(d8_pntr="flow_pntr.tif", pour_pts="pour_pts_snapped.shp", output="watershed.tif")
204
+ ```
205
+
206
+ **检查点**:`accum.tif` 的极值应与流域面积量级相符;若所有像元值都是 1,通常是 DEM 单位不一致或流向计算被平坦区阻断。
207
+
208
+ ---
209
+
210
+ ## 最佳实践
211
+
212
+ 1. **统一单位与坐标系**:DEM 用投影坐标系,水平/垂直单位不同时显式传 `--zfactor`,否则坡度与累积结果会有系统性偏差
213
+ 2. **决口优先于填洼**:`BreachDepressions` 保留更多真实地形细节,平坦区多时才回退 `FillDepressions`
214
+ 3. **阈值要试算**:`ExtractStreams` 的 `--threshold` 与分辨率强相关,先统计累积栅格分布,再取值对比
215
+ 4. **用 `--toolparameters` 驱动脚本**:自动化流水线里先取 JSON 参数定义,避免版本升级后参数改名导致静默失败
216
+ 5. **中间文件显式命名**:把 `dem_breached`、`flow_pntr`、`accum` 分开存,便于复算与排错
217
+ 6. **LiDAR 先探测再处理**:`LidarInfo` 确认点数、范围与坐标系,再做分类与插值;大文件先 `LidarTile` 分块
218
+ 7. **批量任务按 CPU 数并行**:多个独立工具调用可并行,同一 DEM 的上下游步骤必须串行
219
+
220
+ ---
221
+
222
+ ## 常见问题
223
+
224
+ | 问题 | 原因与解决 |
225
+ |------|------------|
226
+ | `whitebox_tools: command not found` | 二进制目录未加入 PATH:`cd` 到 WBT 目录执行,或把该目录加进 PATH;Windows 注意加 `.exe` |
227
+ | 运行后没有任何输出文件,也没有报错 | 相对路径基于 `--wd`:确认 `--wd` 指向数据目录,或全部改用绝对路径 |
228
+ | `--run` 后提示工具不存在 | 工具名必须是 CamelCase(如 `FillDepressions`);用 `--listtools` 确认真实名称 |
229
+ | 参数名报错或参数被忽略 | 参数名随工具而异:用 `--toolparameters=<Tool>` 取 JSON 定义,不要照抄别的工具的参数 |
230
+ | Python 里 `wbt.version()` 与 pip 版本不一致 | 正常现象:pip 版本是 Python 封装版本,二进制版本由下载器决定;能力差异以二进制为准 |
231
+ | 水系的流量累积结果异常(全为 1 或极大值) | DEM 未决口/填洼,或单位不一致;先跑 `BreachDepressions` 并检查 `--zfactor` |
232
+ | 平坦区出现大片无流向像元 | 填洼时未处理平坦区:`FillDepressions` 打开 `--fix_flats=true`,或改用 `BreachDepressions` |
233
+ | LiDAR 工具报格式不支持 | 输入需为 LAS/LAZ;若为其他点云格式,先用 PDAL 转换 |
234
+ | 处理大 DEM 时内存占用过高 | 先 `Clip` 到研究区,或分块处理后再 `Mosaic` 合并 |
235
+
236
+ ---
237
+
238
+ ## AI 使用建议
239
+
240
+ - **执行环境**:`python build.py` 编译耗时可达数分钟,放后台任务;`pip install whitebox` 首次调用会联网下载二进制,离线环境需先手动放置 WBT。命令行优先用预编译二进制([GitHub Releases](https://github.com/jblindsay/whitebox-tools/releases);`whiteboxgeo.com` 的下载页已 404,以 Releases 为准),源码编译只作无二进制平台的兜底。
241
+ - **先探测版本**:`whitebox_tools --version` 确认核心版本(本文基准 2.4.0);`python -c "import whitebox; print(whitebox.__version__)"` 确认前端(2.3.6)。两者不一致时以二进制为准并明确告知用户。
242
+ - **验证产物**:用 `ls -l` 检查输出文件是否生成,再用 GDAL(`gdalinfo` / `python -c "import rasterio..."`)读取数值范围做断言;只看命令退出码不足以证明分析正确。
243
+ - **失败信号**:无输出且无报错几乎都是工作目录或路径问题;参数被忽略多为参数名拼错,用 `--toolparameters` 核对。
244
+ - **常见症状**:累积值异常先查决口与单位;平坦区无流向查 `--fix_flats`;LiDAR 报错先查 LAS/LAZ 格式。
245
+ - **安全与权限**:编译、安装、下载二进制前先征得用户同意;批量处理前确认磁盘占用。
246
+
247
+ ## 相关技能
248
+
249
+ - **gdal** — 栅格/矢量格式转换与重投影,常作为 WBT 前后处理:[../gdal/SKILL.md](../gdal/SKILL.md)
250
+ - **pdal** — LiDAR 点云格式转换与滤波,与 WBT 的 LiDAR 工具互补:[../pdal/SKILL.md](../pdal/SKILL.md)
251
+ - **grass-gis** — 另一套水文与地形分析工具链,可交叉验证结果:[../grass-gis/SKILL.md](../grass-gis/SKILL.md)
252
+ - **qgis-process** — 通过 qgis_process 调用 QGIS 原生算法,做流程编排与出图:[../qgis-process/SKILL.md](../qgis-process/SKILL.md)
253
+ - **proj** — 坐标系定义与转换,处理 DEM CRS 时常用:[../proj/SKILL.md](../proj/SKILL.md)
254
+
255
+ ## 参考资源
256
+
257
+ - 用户手册:<https://jblindsay.github.io/wbt_book/intro.html>(含全部工具的参数与示例)
258
+ - 仓库 README 与 `UserManual.txt`:<https://github.com/jblindsay/whitebox-tools>(README 内指向的 `whiteboxgeo.com` 手册地址已失效,以上面的镜像为准)
259
+ - 源码与 Issue:<https://github.com/jblindsay/whitebox-tools>
260
+ - 后继项目:<https://github.com/jblindsay/whitebox_next_gen>
261
+ - Python 封装:<https://github.com/opengeos/whitebox-python>
262
+ - 预编译二进制:<https://github.com/jblindsay/whitebox-tools/releases>
@@ -0,0 +1,53 @@
1
+ /** Directory (relative to the package root) holding the DSH adaptation files. */
2
+ export declare const ADAPTATION_DIRECTORY: "adaptations";
3
+
4
+ /** File name of the guidance shared by every skill. */
5
+ export declare const COMMON_FILE: "common.md";
6
+
7
+ /** Heading the shared guidance must start with. */
8
+ export declare const COMMON_HEADING: "## DeepSeek Harness 通用约定";
9
+
10
+ /** Heading every per-skill guidance must start with. */
11
+ export declare const SKILL_HEADING: "## DeepSeek Harness 使用建议";
12
+
13
+ /** Separator between the upstream body and the DSH guidance block. */
14
+ export declare const SKILL_SEPARATOR: string;
15
+
16
+ /** Labels every per-skill guidance must keep, in this order. */
17
+ export declare const REQUIRED_LABELS: readonly string[];
18
+
19
+ /** DeepSeek Harness tools the guidance may name, used to prove harness specificity. */
20
+ export declare const DSH_TOOLS: readonly string[];
21
+
22
+ /** List the distinct DeepSeek Harness tool names cited in backticks, in citation order. */
23
+ export declare function citedTools(text: string): string[];
24
+
25
+ /** Build the path of one per-skill adaptation file. */
26
+ export declare function adaptationFile(root: string, name: string): string;
27
+
28
+ /** Build the path of the shared adaptation file. */
29
+ export declare function commonFile(root: string): string;
30
+
31
+ /** Read and normalize one per-skill adaptation file (synchronous). */
32
+ export declare function readAdaptationSync(root: string, name: string): string;
33
+
34
+ /** Read and normalize the shared adaptation file (synchronous). */
35
+ export declare function readCommonSync(root: string): string;
36
+
37
+ /** Read one per-skill adaptation file (asynchronous). */
38
+ export declare function readAdaptation(root: string, name: string, signal?: AbortSignal): Promise<string>;
39
+
40
+ /** Read the shared adaptation file (asynchronous). */
41
+ export declare function readCommon(root: string, signal?: AbortSignal): Promise<string>;
42
+
43
+ /** List the adaptation file base names (without ".md"), sorted. */
44
+ export declare function listAdaptations(root: string): string[];
45
+
46
+ /** Append the DSH guidance block to one upstream skill body. */
47
+ export declare function composeSkillContent(base: string, adaptation: string, common: string): string;
48
+
49
+ /** Report every problem with one per-skill adaptation file. */
50
+ export declare function adaptationProblems(name: string, text: string): string[];
51
+
52
+ /** Report every problem with the shared adaptation file. */
53
+ export declare function commonProblems(text: string): string[];
@@ -0,0 +1,343 @@
1
+ /**
2
+ * DeepSeek Harness adaptation layer for the vendored GIS skills.
3
+ *
4
+ * The files under "assets/" are an exact snapshot of the upstream
5
+ * opengis-skills repository, so they are never edited here: "upstream.json"
6
+ * records one SHA-256 digest per vendored file and "npm run sync" restores the
7
+ * snapshot byte for byte. DSH-specific execution guidance therefore lives in
8
+ * "adaptations/": "common.md" carries the rules that apply to every skill and
9
+ * "<skill>.md" carries the skill-specific notes. The provider appends both to
10
+ * the upstream body when a skill is loaded.
11
+ *
12
+ * Every function here is pure Node built-ins and takes the adaptation root as
13
+ * an argument, so the plugin, the validation script, and the tests share one
14
+ * implementation. No DeepSeek Harness imports.
15
+ *
16
+ * @module @dsh-gis/dsh-opengis-skill/adaptations
17
+ */
18
+
19
+ import { readdirSync, readFileSync } from "node:fs";
20
+ import { readFile } from "node:fs/promises";
21
+ import { join } from "node:path";
22
+
23
+ /** Directory (relative to the package root) holding the DSH adaptation files. */
24
+ export const ADAPTATION_DIRECTORY = "adaptations";
25
+
26
+ /** File name of the guidance shared by every skill. */
27
+ export const COMMON_FILE = "common.md";
28
+
29
+ /** Heading the shared guidance must start with. */
30
+ export const COMMON_HEADING = "## DeepSeek Harness 通用约定";
31
+
32
+ /** Heading every per-skill guidance must start with. */
33
+ export const SKILL_HEADING = "## DeepSeek Harness 使用建议";
34
+
35
+ /** Separator between the upstream body and the DSH guidance block. */
36
+ export const SKILL_SEPARATOR = "\n\n---\n\n";
37
+
38
+ /** Labels every per-skill guidance must keep, in this order. */
39
+ export const REQUIRED_LABELS = ["加载与引用", "执行环境", "先探测版本", "验证产物", "风险与权限"];
40
+
41
+ /**
42
+ * DeepSeek Harness tools and primitives the guidance may name. Per-skill files
43
+ * must cite SKILL_MIN_TOOLS distinct names and the shared file COMMON_MIN_TOOLS,
44
+ * which keeps the adaptation layer about *this* harness instead of repeating
45
+ * tool-agnostic advice that the upstream body already carries.
46
+ */
47
+ export const DSH_TOOLS = [
48
+ "skill",
49
+ "ops_bash",
50
+ "pwsh",
51
+ "run_code",
52
+ "read",
53
+ "grep",
54
+ "glob",
55
+ "write",
56
+ "edit",
57
+ "read_image",
58
+ "present",
59
+ "todo_write",
60
+ "subagent",
61
+ "ask_user_question",
62
+ "job_output",
63
+ "job_kill",
64
+ "web_fetch",
65
+ "web_search",
66
+ "working_directory",
67
+ "load_workspace_dependencies"
68
+ ];
69
+
70
+ /** Minimum distinct DSH tool names one per-skill guidance must cite. */
71
+ const SKILL_MIN_TOOLS = 2;
72
+
73
+ /** Minimum distinct DSH tool names the shared guidance must cite. */
74
+ const COMMON_MIN_TOOLS = 6;
75
+
76
+ /** Minimum bullets in the shared guidance. */
77
+ const COMMON_MIN_BULLETS = 12;
78
+
79
+ /** Minimum characters in the shared guidance. */
80
+ const COMMON_MIN_CHARACTERS = 1800;
81
+
82
+ /** Maximum characters in the shared guidance. */
83
+ const COMMON_MAX_CHARACTERS = 9000;
84
+
85
+ /** Minimum characters in one per-skill guidance file. */
86
+ const SKILL_MIN_CHARACTERS = 900;
87
+
88
+ /** Maximum characters in one per-skill guidance file. */
89
+ const SKILL_MAX_CHARACTERS = 4000;
90
+
91
+ /** Markers that mean an adaptation file was left unfinished. */
92
+ const UNFINISHED = /\b(?:TODO|FIXME|TBD|待补充|占位)\b/u;
93
+
94
+ /**
95
+ * Build the path of one per-skill adaptation file.
96
+ *
97
+ * @param root - absolute adaptations directory.
98
+ * @param name - kebab-case skill name.
99
+ * @returns the absolute Markdown path.
100
+ */
101
+ export function adaptationFile(root, name) {
102
+ return join(root, name + ".md");
103
+ }
104
+
105
+ /**
106
+ * Build the path of the shared adaptation file.
107
+ *
108
+ * @param root - absolute adaptations directory.
109
+ * @returns the absolute Markdown path.
110
+ */
111
+ export function commonFile(root) {
112
+ return join(root, COMMON_FILE);
113
+ }
114
+
115
+ /**
116
+ * Normalize one adaptation file for use inside a skill body.
117
+ *
118
+ * @param text - the file contents.
119
+ * @returns the text with CRLF collapsed to LF and the edges trimmed.
120
+ */
121
+ function normalizeAdaptation(text) {
122
+ return text.replace(/\r\n?/gu, "\n").trim();
123
+ }
124
+
125
+ /**
126
+ * Read and normalize one per-skill adaptation file.
127
+ *
128
+ * @param root - absolute adaptations directory.
129
+ * @param name - kebab-case skill name.
130
+ * @returns the normalized guidance text.
131
+ * @throws when the file is missing or does not start with the required heading.
132
+ */
133
+ export function readAdaptationSync(root, name) {
134
+ const file = adaptationFile(root, name);
135
+ let text;
136
+ try {
137
+ text = readFileSync(file, "utf8");
138
+ } catch (cause) {
139
+ throw new Error('missing DSH adaptation for skill "' + name + '": ' + file + " (run npm run validate)", { cause });
140
+ }
141
+ return assertAdaptation(name, normalizeAdaptation(text));
142
+ }
143
+
144
+ /**
145
+ * Read and normalize the shared adaptation file.
146
+ *
147
+ * @param root - absolute adaptations directory.
148
+ * @returns the normalized guidance text.
149
+ * @throws when the file is missing or does not start with the required heading.
150
+ */
151
+ export function readCommonSync(root) {
152
+ const file = commonFile(root);
153
+ let text;
154
+ try {
155
+ text = readFileSync(file, "utf8");
156
+ } catch (cause) {
157
+ throw new Error("missing shared DSH adaptation: " + file + " (run npm run validate)", { cause });
158
+ }
159
+ return assertCommon(normalizeAdaptation(text));
160
+ }
161
+
162
+ /**
163
+ * Read one per-skill adaptation file without blocking the event loop.
164
+ *
165
+ * @param root - absolute adaptations directory.
166
+ * @param name - kebab-case skill name.
167
+ * @param signal - optional abort signal handed to the read.
168
+ * @returns the normalized guidance text.
169
+ * @throws when the file is missing or does not start with the required heading.
170
+ */
171
+ export async function readAdaptation(root, name, signal) {
172
+ const file = adaptationFile(root, name);
173
+ let text;
174
+ try {
175
+ text = await readFile(file, { encoding: "utf8", signal });
176
+ } catch (cause) {
177
+ if (cause?.name === "AbortError") throw cause;
178
+ throw new Error('missing DSH adaptation for skill "' + name + '": ' + file + " (run npm run validate)", { cause });
179
+ }
180
+ return assertAdaptation(name, normalizeAdaptation(text));
181
+ }
182
+
183
+ /**
184
+ * Read the shared adaptation file without blocking the event loop.
185
+ *
186
+ * @param root - absolute adaptations directory.
187
+ * @param signal - optional abort signal handed to the read.
188
+ * @returns the normalized guidance text.
189
+ * @throws when the file is missing or does not start with the required heading.
190
+ */
191
+ export async function readCommon(root, signal) {
192
+ const file = commonFile(root);
193
+ let text;
194
+ try {
195
+ text = await readFile(file, { encoding: "utf8", signal });
196
+ } catch (cause) {
197
+ if (cause?.name === "AbortError") throw cause;
198
+ throw new Error("missing shared DSH adaptation: " + file + " (run npm run validate)", { cause });
199
+ }
200
+ return assertCommon(normalizeAdaptation(text));
201
+ }
202
+
203
+ /**
204
+ * List the adaptation file names (without the ".md" suffix), sorted.
205
+ *
206
+ * @param root - absolute adaptations directory.
207
+ * @returns the file base names, including "common".
208
+ * @throws when the directory is missing.
209
+ */
210
+ export function listAdaptations(root) {
211
+ return readdirSync(root, { withFileTypes: true })
212
+ .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
213
+ .map((entry) => entry.name.slice(0, -".md".length))
214
+ .sort(compareCodePoints);
215
+ }
216
+
217
+ /**
218
+ * Append the DSH guidance block to one upstream skill body.
219
+ *
220
+ * @param base - the upstream instruction body, already trimmed and LF-normalized.
221
+ * @param adaptation - the per-skill guidance.
222
+ * @param common - the shared guidance.
223
+ * @returns the body a DeepSeek Harness session should read.
224
+ */
225
+ export function composeSkillContent(base, adaptation, common) {
226
+ return base.trimEnd() + SKILL_SEPARATOR + adaptation.trim() + "\n\n" + common.trim() + "\n";
227
+ }
228
+
229
+ /**
230
+ * List the distinct DeepSeek Harness tool names cited in backticks.
231
+ *
232
+ * Only the identifiers declared in DSH_TOOLS count, so prose that happens to
233
+ * mention "read a file" does not satisfy the harness-specificity requirement.
234
+ *
235
+ * @param text - the normalized adaptation text.
236
+ * @returns the distinct tool names found, in first-citation order.
237
+ */
238
+ export function citedTools(text) {
239
+ const found = [];
240
+ for (const match of text.matchAll(/`([a-z][a-z0-9_]*)`/gu)) {
241
+ const name = match[1];
242
+ if (DSH_TOOLS.includes(name) && !found.includes(name)) found.push(name);
243
+ }
244
+ return found;
245
+ }
246
+
247
+ /**
248
+ * Report every problem with one per-skill adaptation file.
249
+ *
250
+ * The checks keep the 40 files comparable: each one states how to load it,
251
+ * where the commands run, how to probe the installed version, how to verify
252
+ * the artifact, and which operations need the user's consent.
253
+ *
254
+ * @param name - kebab-case skill name, used in every message.
255
+ * @param text - the normalized adaptation text.
256
+ * @returns human-readable problems, empty when the file is valid.
257
+ */
258
+ export function adaptationProblems(name, text) {
259
+ const problems = [];
260
+ const label = ADAPTATION_DIRECTORY + "/" + name + ".md";
261
+ if (text.includes("\r")) problems.push(label + ": contains CR bytes; adaptations must use LF");
262
+ if (!text.startsWith(SKILL_HEADING)) problems.push(label + ': must start with "' + SKILL_HEADING + '"');
263
+ if (/^# /mu.test(text)) problems.push(label + ": must not carry a top-level heading");
264
+ if (text.length < SKILL_MIN_CHARACTERS) problems.push(label + ": " + text.length + " characters is too short for DSH guidance (minimum " + SKILL_MIN_CHARACTERS + ")");
265
+ if (text.length > SKILL_MAX_CHARACTERS) problems.push(label + ": " + text.length + " characters exceeds the " + SKILL_MAX_CHARACTERS + "-character budget");
266
+ const bullets = text.split("\n").filter((line) => line.startsWith("- **"));
267
+ if (bullets.length < REQUIRED_LABELS.length) problems.push(label + ": needs at least " + REQUIRED_LABELS.length + ' bullets of the form "- **label**:…"');
268
+ const positions = [];
269
+ for (const required of REQUIRED_LABELS) {
270
+ const index = text.indexOf("- **" + required + "**");
271
+ if (index === -1) problems.push(label + ': missing the "' + required + '" bullet');
272
+ else positions.push(index);
273
+ }
274
+ for (let index = 1; index < positions.length; index += 1) {
275
+ if (positions[index] < positions[index - 1]) {
276
+ problems.push(label + ": required bullets must keep the order " + REQUIRED_LABELS.join(" → "));
277
+ break;
278
+ }
279
+ }
280
+ if (!/`[^`]+`/u.test(text)) problems.push(label + ": must name at least one concrete command or tool in backticks");
281
+ const tools = citedTools(text);
282
+ if (tools.length < SKILL_MIN_TOOLS) {
283
+ problems.push(label + ": cites " + tools.length + " DeepSeek Harness tool(s), needs at least " + SKILL_MIN_TOOLS + " (one of " + DSH_TOOLS.slice(0, 6).join("/") + "/…)");
284
+ }
285
+ if (UNFINISHED.test(text)) problems.push(label + ": still contains an unfinished marker (TODO/FIXME/TBD/待补充/占位)");
286
+ return problems;
287
+ }
288
+
289
+ /**
290
+ * Report every problem with the shared adaptation file.
291
+ *
292
+ * @param text - the normalized common guidance.
293
+ * @returns human-readable problems, empty when the file is valid.
294
+ */
295
+ export function commonProblems(text) {
296
+ const problems = [];
297
+ const label = ADAPTATION_DIRECTORY + "/" + COMMON_FILE;
298
+ if (text.includes("\r")) problems.push(label + ": contains CR bytes; adaptations must use LF");
299
+ if (!text.startsWith(COMMON_HEADING)) problems.push(label + ': must start with "' + COMMON_HEADING + '"');
300
+ if (/^# /mu.test(text)) problems.push(label + ": must not carry a top-level heading");
301
+ if (text.length < COMMON_MIN_CHARACTERS) problems.push(label + ": " + text.length + " characters is too short for the shared guidance (minimum " + COMMON_MIN_CHARACTERS + ")");
302
+ if (text.length > COMMON_MAX_CHARACTERS) problems.push(label + ": " + text.length + " characters exceeds the " + COMMON_MAX_CHARACTERS + "-character budget");
303
+ const bullets = text.split("\n").filter((line) => line.startsWith("- **"));
304
+ if (bullets.length < COMMON_MIN_BULLETS) problems.push(label + ": needs at least " + COMMON_MIN_BULLETS + ' bullets of the form "- **label**:…"');
305
+ const tools = citedTools(text);
306
+ if (tools.length < COMMON_MIN_TOOLS) problems.push(label + ": cites " + tools.length + " DeepSeek Harness tool(s), needs at least " + COMMON_MIN_TOOLS);
307
+ if (UNFINISHED.test(text)) problems.push(label + ": still contains an unfinished marker (TODO/FIXME/TBD/待补充/占位)");
308
+ return problems;
309
+ }
310
+
311
+ /**
312
+ * Reject a per-skill adaptation that cannot be appended to a skill body.
313
+ *
314
+ * @param name - kebab-case skill name.
315
+ * @param text - the normalized adaptation text.
316
+ * @returns the same text.
317
+ * @throws when the file is empty or does not start with the required heading.
318
+ */
319
+ function assertAdaptation(name, text) {
320
+ if (!text.startsWith(SKILL_HEADING)) {
321
+ throw new Error('DSH adaptation for skill "' + name + '" must start with "' + SKILL_HEADING + '": ' + adaptationFile("<adaptations>", name));
322
+ }
323
+ return text;
324
+ }
325
+
326
+ /**
327
+ * Reject a shared adaptation that cannot be appended to a skill body.
328
+ *
329
+ * @param text - the normalized common guidance.
330
+ * @returns the same text.
331
+ * @throws when the file is empty or does not start with the required heading.
332
+ */
333
+ function assertCommon(text) {
334
+ if (!text.startsWith(COMMON_HEADING)) throw new Error('shared DSH adaptation must start with "' + COMMON_HEADING + '"');
335
+ return text;
336
+ }
337
+
338
+ /** Compare two strings by Unicode code point, independent of the locale. */
339
+ function compareCodePoints(left, right) {
340
+ if (left < right) return -1;
341
+ if (left > right) return 1;
342
+ return 0;
343
+ }
package/lib/catalog.d.ts CHANGED
@@ -4,6 +4,12 @@ export interface SkillEntry {
4
4
  name: string;
5
5
  /** Required routing description. */
6
6
  description: string;
7
+ /** SPDX-style license declared by the frontmatter, when present. */
8
+ license?: string;
9
+ /** Nested "metadata" block: category plus the parsed tag list. */
10
+ metadata: { category?: string; tags: string[] };
11
+ /** Top-level frontmatter fields in source order. */
12
+ frontmatterFields: string[];
7
13
  /** Absolute skill directory. */
8
14
  directory: string;
9
15
  /** Absolute path to SKILL.md. */
@@ -16,7 +22,7 @@ export declare const SKILL_FILE: "SKILL.md";
16
22
  /** Read one skill directory, or undefined when it has no SKILL.md. */
17
23
  export declare function readSkillEntry(directory: string, expectedName?: string): SkillEntry | undefined;
18
24
 
19
- /** Read every skill directory under one asset root, sorted by name. */
25
+ /** Read every skill directory under one asset root. */
20
26
  export declare function readSkillCatalog(assetRoot: string): SkillEntry[];
21
27
 
22
28
  /** Render one skill directory as a registry resource base. */