@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,25 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference。正文按 mapbox-gl **3.34.2** 编写,按任务读:「环境准备」讲 token 获取与 npm/CDN 两路;「核心 API」的 Map 初始化、addSource、addLayer 表达式、3D 地形、交互事件是最常改的几节;「常见问题」表里的报错原文可直接对号入座。v2 起是 Mapbox 专有许可(v1.x 才是 BSD-3),用户要开源或零成本时直接 `skill` 加载 `maplibre-gl-js`——本库 v1 的开源分支,免 token、BSD-3-Clause、API 高度兼容,正文给了迁移路径,别默认用 Mapbox 托管的 `mapbox://` 样式。简单瓦片场景用 `skill` 加载 `leaflet`,投影与 MVT 高级需求用 `skill` 加载 `openlayers` 对比,瓦片源用 `skill` 加载 `geoserver` 自建。
4
- - **执行环境**:`npm install`、`npm run build` 走 `ops_bash`(MSYS bash),Windows 原生命令走 `pwsh`;正文提到 Windows 下用 `npm.cmd`。`npm install mapbox-gl` 与打包都是长任务,用 `ops_bash` 的 `run_in_background` 跑、`job_output` 收日志、`job_kill` 收尾;静态预览用 `npx serve dist` 也是常驻进程,同样走后台作业。没有 node 时用 `docker run --rm -v "$PWD:/w" -w /w node:22 bash -lc "npm ci && npm run build"`。三步以上(装包 → 建图 → build → 浏览器核对)先 `todo_write`。
5
- - **先探测版本**:`npm ls mapbox-gl`(没装则 `npm view mapbox-gl version`),CDN 的 JS 与 CSS 必须同为 `v3.34.2`——正文要求固定版本号,混版本会样式失效;控制台里 `map.isStyleLoaded()` 与 `load` 事件可确认运行时真的起来了。差异点:v3 提供 `mapbox-gl/esm` 小体积入口,v2 没有;v2+ 才需要 access token 并受 TOS 约束,v1 是 BSD。写 `^3.34` 会拉到更新的 3.x,行为可能与正文示例不一致,生产要锁精确版本。
6
- - **验证产物**:`npm run build` 通过不是验证。`npx serve dist` 起服务后 `curl.exe -I http://localhost:5173/` 与入口 js 应为 200,再在浏览器打开看底图是否渲染、有没有 `api.mapbox.com` 的 401、图层与地形是否出现;环境允许时截图并用 `read_image` 真看一眼。无浏览器环境下如实说明「未做渲染验证」,不要用构建成功冒充地图可用。若用到 `setTerrain`,看图确认地形起伏与 DEM `encoding` 对得上。
7
- - **风险与权限**:v2+ 受 Mapbox TOS 约束按量计费(免费额度以官方 pricing 页为准),调用前用 `ask_user_question` 说明可能产生费用并给「改用 MapLibre / 用测试 token 小流量验证 / 直接上生产」选项。前端只能放 `pk.` 公开 token,`sk.` 绝不能进构建产物:提交前用 `grep` 搜 `sk.` 与硬编码 `pk.`,日志与回答里不要回显 token;装包、起 dev server 前先确认。
8
- - **常见失败**:401 / `A valid Mapbox access token is required` 查 token 前缀、撤销状态、URL restrictions 与配额;`Style is not done loading` 是在 `load` 前调了 `addSource`/`addLayer`,移进回调;空白先查容器 `height` 与 `map.resize()`;`mapboxgl is not defined` 是 CDN 顺序或 JS/CSS 版本不一致;点击无反应查图层 id 与 `source-layer` 名;feature-state 悬停不生效是要素缺 id(矢量源设 `promoteId`);SPA 卸载别忘 `map.remove()`。
3
+ - **加载与引用**:单文件技能,无 reference。正文按 mapbox-gl **3.34.2** 编写,按任务读:「环境准备」讲 token 获取与 npm/CDN 两路
4
+ - 「核心 API」的 Map 初始化、addSource、addLayer 表达式、3D 地形、交互事件是最常改的几节
5
+ - 「常见问题」表里的报错原文可直接对号入座。
6
+ - v2 起是 Mapbox 专有许可(v1.x 才是 BSD-3),用户要开源或零成本时直接 `skill` 加载 `maplibre-gl-js`——本库 v1 的开源分支,免 token、BSD-3-Clause、API 高度兼容,正文给了迁移路径,别默认用 Mapbox 托管的 `mapbox://` 样式。
7
+ - 简单瓦片场景用 `skill` 加载 `leaflet`,投影与 MVT 高级需求用 `skill` 加载 `openlayers` 对比,瓦片源用 `skill` 加载 `geoserver` 自建
8
+ - **执行环境**:`npm install`、`npm run build` 走 `ops_bash`(MSYS bash),Windows 原生命令走 `pwsh`
9
+ - 正文提到 Windows 下用 `npm.cmd`。`npm install mapbox-gl` 与打包都是长任务,用 `ops_bash` 的 `run_in_background` 跑、`job_output` 收日志、`job_kill` 收尾
10
+ - 静态预览用 `npx serve dist` 也是常驻进程,同样走后台作业。没有 node 时用 `docker run --rm -v "$PWD:/w" -w /w node:22 bash -lc "npm ci && npm run build"`。三步以上(装包 → 建图 → build → 浏览器核对)先 `todo_write`。
11
+ - **先探测版本**:`npm ls mapbox-gl`(没装则 `npm view mapbox-gl version`),CDN 的 JS 与 CSS 必须同为 `v3.34.2`——正文要求固定版本号,混版本会样式失效
12
+ - 控制台里 `map.isStyleLoaded()` 与 `load` 事件可确认运行时真的起来了。差异点:v3 提供 `mapbox-gl/esm` 小体积入口,v2 没有
13
+ - v2+ 才需要 access token 并受 TOS 约束,v1 是 BSD。写 `^3.34` 会拉到更新的 3.x,行为可能与正文示例不一致,生产要锁精确版本。
14
+ - **验证产物**:`npm run build` 通过不是验证。`npx serve dist` 起服务后 `curl.exe -I http://localhost:5173/` 与入口 js 应为 200,再在浏览器打开看底图是否渲染、有没有 `api.mapbox.com` 的 401、图层与地形是否出现
15
+ - 环境允许时截图并用 `read_image` 真看一眼。无浏览器环境下如实说明「未做渲染验证」,不要用构建成功冒充地图可用。若用到 `setTerrain`,看图确认地形起伏与 DEM `encoding` 对得上。
16
+ - **风险与权限**:v2+ 受 Mapbox TOS 约束按量计费(免费额度以官方 pricing 页为准),调用前用 `ask_user_question` 说明可能产生费用并给「改用 MapLibre / 用测试 token 小流量验证 / 直接上生产」选项。
17
+ - 前端只能放 `pk.` 公开 token,`sk.` 绝不能进构建产物:提交前用 `grep` 搜 `sk.` 与硬编码 `pk.`,日志与回答里不要回显 token
18
+ - 装包、起 dev server 前先确认。
19
+ - **常见失败**:401 / `A valid Mapbox access token is required` 查 token 前缀、撤销状态、URL restrictions 与配额
20
+ - `Style is not done loading` 是在 `load` 前调了 `addSource`/`addLayer`,移进回调
21
+ - 空白先查容器 `height` 与 `map.resize()`
22
+ - `mapboxgl is not defined` 是 CDN 顺序或 JS/CSS 版本不一致
23
+ - 点击无反应查图层 id 与 `source-layer` 名
24
+ - feature-state 悬停不生效是要素缺 id(矢量源设 `promoteId`)
25
+ - SPA 卸载别忘 `map.remove()`。
@@ -1,8 +1,20 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,没有 reference 目录,正文的「环境准备」「核心 API」「典型工作流」「常见问题」按任务取用,升级旧代码前先读 v5→v6 破坏性变更表。原生端嵌入用 `skill` 加载 `maplibre-native`,动态影像瓦片后端用 `skill` 加载 `stac-cog-titiler`,大规模数据图层看 `deck-gl`;不要在技能之间 `read` 兄弟目录。
4
- - **执行环境**:`npm install`、`npm run dev` 走 `ops_bash`,Windows 下脚本里写 `cmd /c npm run build` 比直接 `npm` 稳。dev server 与 `npx serve dist` 都是常驻进程,必须 `run_in_background` 起、`job_output` 读到 listening 行确认端口,收尾 `job_kill`,不要让 5173/3000 一直占着;换端口前先 `curl -s -o /dev/null -w '%{http_code}' http://localhost:<port>/` 看是不是已被别的服务占用。页面文件写会话工作区,不要写进只读的技能目录。
5
- - **先探测版本**:`npm ls maplibre-gl` 看实际装的是不是 6.17.0(没装先 `npm view maplibre-gl version` 查上游最新),再 `node -e "import('maplibre-gl').then(m=>console.log(typeof m.Map))"` 确认 ESM 入口能解析、导出里有 `Map`。正文按 6.17.0 / Style Spec v25 编写;报 `Unexpected token 'export'` 是拿 UMD 思路加载了 `.mjs`,`new maplibregl.Map is not a constructor` 是 v5 的 default import 写法没改。
6
- - **验证产物**:shell 里看不到 WebGL 画面,构建成功不代表地图出来了。至少三层:`curl -s -o /dev/null -w '%{http_code}\n'` 打 dev server 首页与 `maplibre-gl.css` 要 200;`curl -s https://demotiles.maplibre.org/style.json | head -c 80` 确认样式源可达(样式 404 会让整图空白且只在 error 事件里报);最后要看到画面:项目里已有 Playwright/Puppeteer 时起无头浏览器截图存 PNG,再用 `read_image` 看是不是真有底图(纯色、全白、空文件都算失败),没有这套环境就用 `ask_user_question` 让用户拍板「装无头浏览器自己截/用户打开看/只交付静态构建产物」。
7
- - **风险与权限**:`npm install` 会下载依赖并改 `package-lock.json`,装 Playwright/Chromium 是几百 MB 的环境改动,都先确认再动手;dev server 绑 `0.0.0.0` 等于把页面暴露到内网,默认只绑 `localhost`。`addProtocol` 与第三方瓦片 URL 会把请求发到外部,先核对来源与条款,别把内网地址写进样式;MapLibre 本身免 token,看到要求填 `accessToken` 的示例说明混进了 Mapbox 代码。
8
- - **常见失败**:`WebGL2 is required` 是无头/远程桌面缺 GPU,换环境或接受无法渲染,不要为此改库;地图空白先查容器有没有显式高度、`addLayer` 是否早于 `load`;截图全黑是 `preserveDrawingBuffer` 默认 false,构造时开 `canvasContextAttributes: { preserveDrawingBuffer: true }`;`styleimagemissing` 里补图不生效是 v6 改成只通知,改用 `setMissingStyleImageResolver`。
3
+ - **加载与引用**:单文件技能,没有 reference 目录,正文的「环境准备」「核心 API」「典型工作流」「常见问题」按任务取用,升级旧代码前先读 v5→v6 破坏性变更表。原生端嵌入用 `skill` 加载 `maplibre-native`,动态影像瓦片后端用 `skill` 加载 `stac-cog-titiler`,大规模数据图层看 `deck-gl`
4
+ - 不要在技能之间 `read` 兄弟目录。
5
+ - **执行环境**:`npm install`、`npm run dev` 走 `ops_bash`,Windows 下脚本里写 `cmd /c npm run build` 比直接 `npm` 稳。
6
+ - dev server 与 `npx serve dist` 都是常驻进程,必须 `run_in_background` 起、`job_output` 读到 listening 行确认端口,收尾 `job_kill`,不要让 5173/3000 一直占着
7
+ - 换端口前先 `curl -s -o /dev/null -w '%{http_code}' http://localhost:<port>/` 看是不是已被别的服务占用。页面文件写会话工作区,不要写进只读的技能目录。
8
+ - **先探测版本**:`npm ls maplibre-gl` 看实际装的是不是 6.17.0(没装先 `npm view maplibre-gl version` 查上游最新),再 `node -e "import('maplibre-gl').then(m=>console.log(typeof m.Map))"` 确认 ESM 入口能解析、导出里有 `Map`。
9
+ - 正文按 6.17.0 / Style Spec v25 编写
10
+ - 报 `Unexpected token 'export'` 是拿 UMD 思路加载了 `.mjs`,`new maplibregl.Map is not a constructor` 是 v5 的 default import 写法没改。
11
+ - **验证产物**:shell 里看不到 WebGL 画面,构建成功不代表地图出来了。至少三层:`curl -s -o /dev/null -w '%{http_code}\n'` 打 dev server 首页与 `maplibre-gl.css` 要 200
12
+ - `curl -s https://demotiles.maplibre.org/style.json | head -c 80` 确认样式源可达(样式 404 会让整图空白且只在 error 事件里报)
13
+ - 最后要看到画面:项目里已有 Playwright/Puppeteer 时起无头浏览器截图存 PNG,再用 `read_image` 看是不是真有底图(纯色、全白、空文件都算失败),没有这套环境就用 `ask_user_question` 让用户拍板「装无头浏览器自己截/用户打开看/只交付静态构建产物」。
14
+ - **风险与权限**:`npm install` 会下载依赖并改 `package-lock.json`,装 Playwright/Chromium 是几百 MB 的环境改动,都先确认再动手
15
+ - dev server 绑 `0.0.0.0` 等于把页面暴露到内网,默认只绑 `localhost`。`addProtocol` 与第三方瓦片 URL 会把请求发到外部,先核对来源与条款,别把内网地址写进样式
16
+ - MapLibre 本身免 token,看到要求填 `accessToken` 的示例说明混进了 Mapbox 代码。
17
+ - **常见失败**:`WebGL2 is required` 是无头/远程桌面缺 GPU,换环境或接受无法渲染,不要为此改库
18
+ - 地图空白先查容器有没有显式高度、`addLayer` 是否早于 `load`
19
+ - 截图全黑是 `preserveDrawingBuffer` 默认 false,构造时开 `canvasContextAttributes: { preserveDrawingBuffer: true }`
20
+ - `styleimagemissing` 里补图不生效是 v6 改成只通知,改用 `setMissingStyleImageResolver`。
@@ -1,8 +1,19 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,没有 reference 目录;正文「环境准备」按 Android/iOS/Node/C++ 分块,「典型工作流」三条链路与「常见问题」表先对症状再深挖。样式 JSON 与前端共用,浏览器侧问题用 `skill` 加载 `maplibre-gl-js`,瓦片与影像后端用 `skill` 加载 `stac-cog-titiler`;不要 `read` 兄弟目录。
4
- - **执行环境**:本队列是 Windows + MSYS bash,四个平台分支里只有 Node 能完整跑通。Node 端 `npm install @maplibre/maplibre-gl-native` 走 `ops_bash`,预编译二进制只覆盖 Node 22/24/26,`node -v` 不在其中就别试;Android 需要 JDK 与 Android SDK(`./gradlew` 构建动辄十几分钟),iOS 的 Bazel/Xcode 只能在 macOS 上跑,本机没有就明说做不了,不要编造构建结果。真跑构建与模拟器时用 `run_in_background` 起作业、`job_output` 跟日志(首次会下载 Gradle 依赖与 SDK),失败再 `job_kill` 收尾。
5
- - **先探测版本**:Node 端 `npm ls @maplibre/maplibre-gl-native` 应为 6.4.1,再 `node -e "const m=require('@maplibre/maplibre-gl-native'); console.log(typeof m.Map)"` 必须打印 `function`,打印 `undefined` 多半是平台或 Node 大版本不在预编译列表内;Android 用 `./gradlew :app:dependencies --configuration debugRuntimeClasspath | grep maplibre` 核对 13.x,iOS 查 `Podfile.lock` 里的 `MapLibre (7.0.0)`,`xcodebuild -version` 在本机大概率直接报「不是内部或外部命令」,那就是没有 iOS 分支。正文按 Android 13.5.4/13.7.1、iOS 7.0.0、Node 6.4.1 编写。
6
- - **验证产物**:Node 分支是唯一能端到端验证的:写一个渲染脚本(`map.render({width:512,height:512,zoom:2,center:[0,0]}, cb)` 拿 RGBA 缓冲写 `tile.png`),再用 `read_image` 看是不是真出一张世界地图——全透明、纯色块、0 字节都算失败,最常见根因是 `request` 回调对某些 `kind` 没 `callback`;同时断言输出 512x512 且 `map.release()` 已调用。Android 有模拟器时 `adb exec-out screencap -p > shot.png` 再用 `read_image` 复核,没有设备就只报告「编译通过」,不能写「地图已显示」。
7
- - **风险与权限**:`npm install` 会下载原生二进制、`git clone --recurse-submodules` 拉整个仓库(数 GB)、装 Android SDK/NDK 与启动模拟器都改环境,动手前用 `ask_user_question` 确认磁盘与时间成本;Android `MapView` 生命周期漏转发会泄漏渲染线程,改这类代码按「编译 → 装机 → 看画面 → `adb logcat` 无崩溃」四步走。离线区域下载受瓦片服务 `Cache-Control` 与服务条款约束,批量抓取前确认授权;样式里不要写内网瓦片地址。
8
- - **常见失败**:Android 绿屏或纯色块是 `MapLibre.getInstance()` 没在 `MapView` 之前调用;跑起来却报找不到 `org.maplibre.android.*` 是依赖坐标写成了旧 Mapbox 的;clone 后缺头文件是没拉 submodule,补 `git submodule update --init --recursive`;iOS 7.0.0 起伞头文件改名 `MapLibre.h`,`#import <Mapbox/Mapbox.h>` 要同步改。
3
+ - **加载与引用**:单文件技能,没有 reference 目录
4
+ - 正文「环境准备」按 Android/iOS/Node/C++ 分块,「典型工作流」三条链路与「常见问题」表先对症状再深挖。样式 JSON 与前端共用,浏览器侧问题用 `skill` 加载 `maplibre-gl-js`,瓦片与影像后端用 `skill` 加载 `stac-cog-titiler`
5
+ - 不要 `read` 兄弟目录。
6
+ - **执行环境**:本队列是 Windows + MSYS bash,四个平台分支里只有 Node 能完整跑通。Node 端 `npm install @maplibre/maplibre-gl-native` 走 `ops_bash`,预编译二进制只覆盖 Node 22/24/26,`node -v` 不在其中就别试
7
+ - Android 需要 JDK 与 Android SDK(`./gradlew` 构建动辄十几分钟),iOS 的 Bazel/Xcode 只能在 macOS 上跑,本机没有就明说做不了,不要编造构建结果。真跑构建与模拟器时用 `run_in_background` 起作业、`job_output` 跟日志(首次会下载 Gradle 依赖与 SDK),失败再 `job_kill` 收尾。
8
+ - **先探测版本**:Node 端 `npm ls @maplibre/maplibre-gl-native` 应为 6.4.1,再 `node -e "const m=require('@maplibre/maplibre-gl-native'); console.log(typeof m.Map)"` 必须打印 `function`,打印 `undefined` 多半是平台或 Node 大版本不在预编译列表内
9
+ - Android 用 `./gradlew :app:dependencies --configuration debugRuntimeClasspath | grep maplibre` 核对 13.x,iOS 查 `Podfile.lock` 里的 `MapLibre (7.0.0)`,`xcodebuild -version` 在本机大概率直接报「不是内部或外部命令」,那就是没有 iOS 分支。
10
+ - 正文按 Android 13.5.4/13.7.1、iOS 7.0.0、Node 6.4.1 编写
11
+ - **验证产物**:Node 分支是唯一能端到端验证的:写一个渲染脚本(`map.render({width:512,height:512,zoom:2,center:[0,0]}, cb)` 拿 RGBA 缓冲写 `tile.png`),再用 `read_image` 看是不是真出一张世界地图——全透明、纯色块、0 字节都算失败,最常见根因是 `request` 回调对某些 `kind` 没 `callback`
12
+ - 同时断言输出 512x512 且 `map.release()` 已调用。Android 有模拟器时 `adb exec-out screencap -p > shot.png` 再用 `read_image` 复核,没有设备就只报告「编译通过」,不能写「地图已显示」。
13
+ - **风险与权限**:`npm install` 会下载原生二进制、`git clone --recurse-submodules` 拉整个仓库(数 GB)、装 Android SDK/NDK 与启动模拟器都改环境,动手前用 `ask_user_question` 确认磁盘与时间成本
14
+ - Android `MapView` 生命周期漏转发会泄漏渲染线程,改这类代码按「编译 → 装机 → 看画面 → `adb logcat` 无崩溃」四步走。离线区域下载受瓦片服务 `Cache-Control` 与服务条款约束,批量抓取前确认授权
15
+ - 样式里不要写内网瓦片地址。
16
+ - **常见失败**:Android 绿屏或纯色块是 `MapLibre.getInstance()` 没在 `MapView` 之前调用
17
+ - 跑起来却报找不到 `org.maplibre.android.*` 是依赖坐标写成了旧 Mapbox 的
18
+ - clone 后缺头文件是没拉 submodule,补 `git submodule update --init --recursive`
19
+ - iOS 7.0.0 起伞头文件改名 `MapLibre.h`,`#import <Mapbox/Mapbox.h>` 要同步改。
@@ -1,8 +1,24 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference。正文按 MapServer **8.6.6** 编写,按任务读:「核心 API / 命令」的 mapfile 对象层次与最小示例、「mapserv CGI 请求参数」「WMS / WFS 请求示例」;样式问题看「SLD 绑定」;「常见问题」表里 `No query information to decode`、空白 GetMap 等原文可直接对号。数据准备用 `skill` 加载 `gdal`(`ogr2ogr`),PostGIS 源用 `skill` 加载 `postgis`,需要 WFS-T 写入时正文已指出 MapServer 只读,应改用 GeoServer。
4
- - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash),Windows 原生命令与 OSGeo4W 的 `mapserv.exe` 走 `pwsh`。正文的 `sudo apt install cgi-mapserver` 在 Windows 不存在:先探测 OSGeo4W 安装目录下有没有 `bin/mapserv.exe`,没有就用 OSGeo4W 安装器勾选 `mapserver` 组件(官方给的就是这条路),或 `docker run --rm -v "$PWD:/data" -w /data ghcr.io/osgeo/mapserver:latest mapserv -v`。源码编译那段的 `tar -zxvf` 在 `pwsh` 里换成 `Expand-Archive`,`make install` 为目标目录时先确认写权限。启动 FastCGI/Apache 常驻服务是长任务,用 `ops_bash` 的 `run_in_background`,`job_output` 收日志、`job_kill` 收尾。
5
- - **先探测版本**:`mapserv -v` 一次拿到版本与 `SUPPORTS=` 列表——正文按 8.6.6 编写,输出里要有 `MapServer version 8.6.6` 且 `SUPPORTS` 含所需的 `WMS_SERVER`/`WFS_SERVER`,缺项说明这份构建根本没编进该库,改 mapfile 无用。差异点:WFS 默认不输出要素属性是 MapServer 4.6 起就有的默认行为(不是 8.x 新增),要属性必须配 `gml_include_items`,老教程里 WFS 直接有属性的写法会「字段全空」;`wms_enable_request` 不设则不启用任何请求。8.0 起 `shp2img` 更名为 `map2img`,用 `command -v map2img` 确认离线渲染工具在,照抄旧教程的 `shp2img` 会直接报命令不存在。
6
- - **验证产物**:三级验证,缺一不可。先离线渲染 `map2img -m demo.map -o out.png -s 600 400`,用 `read_image` 真看一眼 out.png 有图、范围与配色对;再 `mapserv -nh "QUERY_STRING=map=/abs/demo.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities"` 抓能力文档,确认图层名、`wms_srs` 与格式都在;最后 `curl.exe -s -o get.png -w "%{http_code} %{content_type}"` 发一次 `GetMap` 确认 200 和 `image/png`。判据是能力文档与实际出图一致,不是 `mapserv` 进程起来了。
7
- - **风险与权限**:`map=` 参数可读服务器任意路径,是 MapServer 最典型的误配置——上线前必须设 `MS_MAP_PATTERN`/`MS_MAP_NO_PATH` 或用包装脚本;把 `wms_enable_request` 设为 `*` 等于对全网开放包括 `GetFeatureInfo`。重启 Apache/nginx、改 CGI 目录权限(`chmod o+x` 在 Windows 无对应语义,改用 IIS/FastCGI 配置)、覆盖生产 mapfile 前,用 `ask_user_question` 给「先备份 mapfile / 只改测试环境 / 直接生效」选项。
8
- - **常见失败**:`No query information to decode` 只说明 CGI 能执行,缺的是 `SERVICE`/`REQUEST` 参数;GetMap 空白图查 `EXTENT` 与请求 `BBOX` 是否重合、`PROJECTION` 与数据是否一致、图层 `STATUS ON`;WFS 缺属性补 `gml_include_items "all"`(默认不输出属性是 4.6 起的默认行为,不是 8.x 才变);`shp2img: command not found` 就是撞上 8.0 改名,换 `map2img`;SLD 不生效是 `NamedLayer/Name` 与图层 `NAME` 不匹配或 `CLASSITEM` 字段名错;中文注记方框查 mapfile 是否 UTF-8 与 `FONT` 中文字体。改一处只验一处(改 METADATA 只跑能力文档,改样式只跑 `map2img`)。
3
+ - **加载与引用**:单文件技能,无 reference。正文按 MapServer **8.6.6** 编写,按任务读:「核心 API / 命令」的 mapfile 对象层次与最小示例、「mapserv CGI 请求参数」「WMS / WFS 请求示例」
4
+ - 样式问题看「SLD 绑定」
5
+ - 「常见问题」表里 `No query information to decode`、空白 GetMap 等原文可直接对号。数据准备用 `skill` 加载 `gdal`(`ogr2ogr`),PostGIS 源用 `skill` 加载 `postgis`,需要 WFS-T 写入时正文已指出 MapServer 只读,应改用 GeoServer。
6
+ - **执行环境**:命令走 `ops_bash`(Windows 下是 MSYS bash),Windows 原生命令与 OSGeo4W 的 `mapserv.exe` 走 `pwsh`。
7
+ - 正文的 `sudo apt install cgi-mapserver` 在 Windows 不存在:先探测 OSGeo4W 安装目录下有没有 `bin/mapserv.exe`,没有就用 OSGeo4W 安装器勾选 `mapserver` 组件(官方给的就是这条路),或 `docker run --rm -v "$PWD:/data" -w /data ghcr.io/osgeo/mapserver:latest mapserv -v`。
8
+ - 源码编译那段的 `tar -zxvf` 在 `pwsh` 里换成 `Expand-Archive`,`make install` 为目标目录时先确认写权限。
9
+ - 启动 FastCGI/Apache 常驻服务是长任务,用 `ops_bash` 的 `run_in_background`,`job_output` 收日志、`job_kill` 收尾
10
+ - **先探测版本**:`mapserv -v` 一次拿到版本与 `SUPPORTS=` 列表——正文按 8.6.6 编写,输出里要有 `MapServer version 8.6.6` 且 `SUPPORTS` 含所需的 `WMS_SERVER`/`WFS_SERVER`,缺项说明这份构建根本没编进该库,改 mapfile 无用。
11
+ - 差异点:WFS 默认不输出要素属性是 MapServer 4.6 起就有的默认行为(不是 8.x 新增),要属性必须配 `gml_include_items`,老教程里 WFS 直接有属性的写法会「字段全空」
12
+ - `wms_enable_request` 不设则不启用任何请求。8.0 起 `shp2img` 更名为 `map2img`,用 `command -v map2img` 确认离线渲染工具在,照抄旧教程的 `shp2img` 会直接报命令不存在。
13
+ - **验证产物**:三级验证,缺一不可。先离线渲染 `map2img -m demo.map -o out.png -s 600 400`,用 `read_image` 真看一眼 out.png 有图、范围与配色对
14
+ - 再 `mapserv -nh "QUERY_STRING=map=/abs/demo.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities"` 抓能力文档,确认图层名、`wms_srs` 与格式都在
15
+ - 最后 `curl.exe -s -o get.png -w "%{http_code} %{content_type}"` 发一次 `GetMap` 确认 200 和 `image/png`。判据是能力文档与实际出图一致,不是 `mapserv` 进程起来了。
16
+ - **风险与权限**:`map=` 参数可读服务器任意路径,是 MapServer 最典型的误配置——上线前必须设 `MS_MAP_PATTERN`/`MS_MAP_NO_PATH` 或用包装脚本
17
+ - 把 `wms_enable_request` 设为 `*` 等于对全网开放包括 `GetFeatureInfo`。
18
+ - 重启 Apache/nginx、改 CGI 目录权限(`chmod o+x` 在 Windows 无对应语义,改用 IIS/FastCGI 配置)、覆盖生产 mapfile 前,用 `ask_user_question` 给「先备份 mapfile / 只改测试环境 / 直接生效」选项
19
+ - **常见失败**:`No query information to decode` 只说明 CGI 能执行,缺的是 `SERVICE`/`REQUEST` 参数
20
+ - GetMap 空白图查 `EXTENT` 与请求 `BBOX` 是否重合、`PROJECTION` 与数据是否一致、图层 `STATUS ON`
21
+ - WFS 缺属性补 `gml_include_items "all"`(默认不输出属性是 4.6 起的默认行为,不是 8.x 才变)
22
+ - `shp2img: command not found` 就是撞上 8.0 改名,换 `map2img`
23
+ - SLD 不生效是 `NamedLayer/Name` 与图层 `NAME` 不匹配或 `CLASSITEM` 字段名错
24
+ - 中文注记方框查 mapfile 是否 UTF-8 与 `FONT` 中文字体。改一处只验一处(改 METADATA 只跑能力文档,改样式只跑 `map2img`)。
@@ -1,8 +1,24 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference。正文按 Mapsui **5.1.0**(net8.0 / net9.0,上游 5.2.0-beta.1 为预发布不计入)编写。按任务读:「安装」确认 UI 包与数据源包的组合、「WPF 入门」拿最小可运行工程、「核心概念」区分 Map/Layer/Provider、「WMS」一节的 `WmsProvider.CreateAsync` 是 5.x 硬要求、「常见问题」表覆盖空白 MapControl 与中文乱码。几何细节用 `skill` 加载 `nettopologysuite`,服务端发布用 `skill` 加载 `geoserver`,别去读兄弟目录的 SKILL.md。
4
- - **执行环境**:`dotnet` 命令走 `ops_bash`(Windows 下是 MSYS bash),需要看 Windows 原生产物时用 `pwsh`。先探测 `dotnet --list-sdks`:5.1.0 只支持 net8.0/net9.0(`Mapsui.Wpf` 是 net8.0-windows/net9.0-windows),只有 .NET 6/7 的机器必须先装 SDK,不能指望改个 target framework 就编译过。`dotnet add package` 与首次 `dotnet restore` 会拉 NuGet 包,属长任务,用 `ops_bash` 的 `run_in_background` 跑、`job_output` 收日志;本机没有 SDK 时退回 `docker run --rm -v "$PWD:/w" -w /w mcr.microsoft.com/dotnet/sdk:9.0 dotnet build`。新建工程 → 加包 → 编译 → 无头渲染是三步以上,先 `todo_write`。
5
- - **先探测版本**:`dotnet --list-sdks` 与 `dotnet list package` 确认 `Mapsui.Wpf`/`Mapsui.Nts`/`Mapsui.Tiling` 是否都是 5.1.0——正文强调所有 `Mapsui.*` 子包版本必须一致,混版会在运行时抛类型加载异常,编译期看不出来。差异点:5.x 起 WMS 必须用异步工厂 `WmsProvider.CreateAsync`,正文工作流与「WMS」节已统一成这个写法;外部教程里的同步 `new WmsProvider(...)` 在 5.1 上不可用,照抄编译不过。`CreateAsync` 会先拉 `GetCapabilities`,地址写错在这一步就抛异常;创建后 `AddLayer` 的图层名要与能力文档完全一致、`CRS` 与 `Map.CRS` 一致,否则地图空白而不报错。WPF 的 NuGet 包名是 `Mapsui.Wpf`,程序集/命名空间仍是 `Mapsui.UI.Wpf`,网上 v2 教程的包名会装不上。
6
- - **验证产物**:`dotnet restore`/`dotnet build` 通过只说明编译过,正文已明确要求用 `Mapsui.Rendering.Skia.MapRenderer` 把 `map` 渲染成 PNG(参数以 IntelliSense 为准,常见做法是 `RenderToBitmapStream` 写 MemoryStream 再落盘),然后用 `read_image` 真看一眼:底图瓦片有没有、点位是否在预期位置、WMS 层是否出现。桌面窗口本身 AI 看不到,需请用户运行后截图。空白的地图 PNG 与「渲染成功」是两件事,只凭 build 退出码 0 报告成功属于假验证。
7
- - **风险与权限**:新建 .NET 工程、装 NuGet 包、运行桌面程序都会改用户机器状态,先 `ask_user_question` 给「只新建到指定目录 / 用 Docker 构建 / 先不建」选项。连接 PostGIS 或私有 WMS 的密码、token 不要写进代码或回答,改用环境变量或用户机密存储;`Map.ZoomToExtents()` 在无数据图层上会让视图缩到无效范围,别对空 map 调用。
8
- - **常见失败**:窗口空白先查有没有执行 `MapControl.Map = map`,再查 NuGet 里是否缺 `Mapsui.Wpf`;MAUI 空白查 `MauiProgram` 里 `UseSkiaSharp()` 与 `UseMapsui()` 是否注册;点跑到南太平洋是漏了 `SphericalMercator.FromLonLat(lon, lat)`(视图坐标系是 EPSG:3857);Shapefile 中文乱码是 DBF 缺 `.cpg`,用 `new ShapeFile(path, true) { Encoding = ... }` 属性赋值而非构造参数;找不到 `GeometryFeature` 装 `Mapsui.Nts`,找不到瓦片类型装 `Mapsui.Tiling`。
3
+ - **加载与引用**:单文件技能,无 reference。
4
+ - 正文按 Mapsui **5.1.0**(net8.0 / net9.0,上游 5.2.0-beta.1 为预发布不计入)编写。
5
+ - 按任务读:「安装」确认 UI 包与数据源包的组合、「WPF 入门」拿最小可运行工程、「核心概念」区分 Map/Layer/Provider、「WMS」一节的 `WmsProvider.CreateAsync` 是 5.x 硬要求、「常见问题」表覆盖空白 MapControl 与中文乱码。
6
+ - 几何细节用 `skill` 加载 `nettopologysuite`,服务端发布用 `skill` 加载 `geoserver`,别去读兄弟目录的 SKILL.md
7
+ - **执行环境**:`dotnet` 命令走 `ops_bash`(Windows 下是 MSYS bash),需要看 Windows 原生产物时用 `pwsh`。
8
+ - 先探测 `dotnet --list-sdks`:5.1.0 只支持 net8.0/net9.0(`Mapsui.Wpf` 是 net8.0-windows/net9.0-windows),只有 .NET 6/7 的机器必须先装 SDK,不能指望改个 target framework 就编译过。
9
+ - `dotnet add package` 与首次 `dotnet restore` 会拉 NuGet 包,属长任务,用 `ops_bash` 的 `run_in_background` 跑、`job_output` 收日志
10
+ - 本机没有 SDK 时退回 `docker run --rm -v "$PWD:/w" -w /w mcr.microsoft.com/dotnet/sdk:9.0 dotnet build`。新建工程 → 加包 → 编译 → 无头渲染是三步以上,先 `todo_write`。
11
+ - **先探测版本**:`dotnet --list-sdks` 与 `dotnet list package` 确认 `Mapsui.Wpf`/`Mapsui.Nts`/`Mapsui.Tiling` 是否都是 5.1.0——正文强调所有 `Mapsui.*` 子包版本必须一致,混版会在运行时抛类型加载异常,编译期看不出来。
12
+ - 差异点:5.x 起 WMS 必须用异步工厂 `WmsProvider.CreateAsync`,正文工作流与「WMS」节已统一成这个写法
13
+ - 外部教程里的同步 `new WmsProvider(...)` 在 5.1 上不可用,照抄编译不过。`CreateAsync` 会先拉 `GetCapabilities`,地址写错在这一步就抛异常
14
+ - 创建后 `AddLayer` 的图层名要与能力文档完全一致、`CRS` 与 `Map.CRS` 一致,否则地图空白而不报错。WPF 的 NuGet 包名是 `Mapsui.Wpf`,程序集/命名空间仍是 `Mapsui.UI.Wpf`,网上 v2 教程的包名会装不上。
15
+ - **验证产物**:`dotnet restore`/`dotnet build` 通过只说明编译过,正文已明确要求用 `Mapsui.Rendering.Skia.MapRenderer` 把 `map` 渲染成 PNG(参数以 IntelliSense 为准,常见做法是 `RenderToBitmapStream` 写 MemoryStream 再落盘),然后用 `read_image` 真看一眼:底图瓦片有没有、点位是否在预期位置、WMS 层是否出现。
16
+ - 桌面窗口本身 AI 看不到,需请用户运行后截图。
17
+ - 空白的地图 PNG 与「渲染成功」是两件事,只凭 build 退出码 0 报告成功属于假验证
18
+ - **风险与权限**:新建 .NET 工程、装 NuGet 包、运行桌面程序都会改用户机器状态,先 `ask_user_question` 给「只新建到指定目录 / 用 Docker 构建 / 先不建」选项。连接 PostGIS 或私有 WMS 的密码、token 不要写进代码或回答,改用环境变量或用户机密存储
19
+ - `Map.ZoomToExtents()` 在无数据图层上会让视图缩到无效范围,别对空 map 调用。
20
+ - **常见失败**:窗口空白先查有没有执行 `MapControl.Map = map`,再查 NuGet 里是否缺 `Mapsui.Wpf`
21
+ - MAUI 空白查 `MauiProgram` 里 `UseSkiaSharp()` 与 `UseMapsui()` 是否注册
22
+ - 点跑到南太平洋是漏了 `SphericalMercator.FromLonLat(lon, lat)`(视图坐标系是 EPSG:3857)
23
+ - Shapefile 中文乱码是 DBF 缺 `.cpg`,用 `new ShapeFile(path, true) { Encoding = ... }` 属性赋值而非构造参数
24
+ - 找不到 `GeometryFeature` 装 `Mapsui.Nts`,找不到瓦片类型装 `Mapsui.Tiling`。
@@ -1,8 +1,21 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference 目录。正文代码块密集,先按「核心 API:几何工厂」「WKT / WKB / GeoJSON」「空间索引」「几何修复与简化」「EF Core」「ProjNet」「典型工作流」定位小节再 `read` 片段,或 `grep` 搜 `GeometryFixer`、`GeoJsonConverterFactory`、`HandleOrdinates` 直接跳到行号,不要整篇读。需要 Java 原版对照时用 `skill` 加载 `jts`,要 GDAL 侧读写时加载 `opengis-utils-for-net` 或 `gdal`。
4
- - **执行环境**:建工程、装包、构建、运行走 `ops_bash`(本机 Windows 是 MSYS bash,先 `command -v dotnet` 确认);只有需要 `Get-Command` 或带反斜杠的 `.exe` 参数时才换 `pwsh`。探测代码放会话工作区(`dotnet new console -o work/nts-probe`),不要往 `assets/` 写;首次 `dotnet restore` 要访问 NuGet,内网先确认源可用,失败一次就报告,不要反复重试。MSYS 的 `/d/...` 传给 .NET 进程常解析失败,代码里的路径写 `D:\...`。
5
- - **先探测版本**:`dotnet --version` 确认 SDK 6+,`dotnet list package --include-transitive` 核对 `NetTopologySuite` 2.6.0、`NetTopologySuite.IO.GeoJSON`(或 `IO.GeoJSON4STJ`)4.0.0、`IO.Esri.Shapefile` 1.2.0、`ProjNet` 2.1.0——正文按这组版本编写。低于 2.6 没有 `NtsGeometryServices` 工厂重载与 `GeometryFixer`;`WKTReader(GeometryFactory)` 在 2.6 已标记过时,能编但告警;旧 `ProjNet4GeoAPI` 停在 1.4.1,新工程用 `ProjNet`。
6
- - **验证产物**:`dotnet build` 只证明编译过。写最小控制台跑正文「典型工作流」的判据:`parcel.Intersection(zone).Area` 为 12.5、`back.IsValid` 为 `true`、WKT 往返坐标数一致;输出重定向到 `run.log` 再 `read`,或写成 xunit 用例交给 `dotnet test`。Shapefile 产物用 `Shapefile.ReadAllFeatures` 回读要素数,机上有 GDAL 时再 `ogrinfo -so out.shp` 复核。要交付的 GeoJSON 用 `present` 列给用户。
7
- - **风险与权限**:装 SDK、加 NuGet 包、连 SQL Server/PostgreSQL 都要先问人——用 `ask_user_question` 给「只读连接/新建库/跳过」选项,生产库不直接读写。`Shapefile.WriteAllFeatures` 与 `GeoJsonWriter` 写同名文件会覆盖,先换名或备份;EF Core 的 `EnsureCreated`、迁移、批量 `UPDATE` 都改库。`GeometryFixer.Fix` 可能返回 `MultiPolygon`,别照抄正文的 `(Polygon)` 强转;`WKBWriter` 默认丢 Z/M,需要时设 `HandleOrdinates`。
8
- - **常见失败**:`TopologyException` 先用 `GeometryFixer.Fix`;`TypeInitializationException` 或程序集加载失败多为 IO 包与主库版本错配;`GeoJsonConverterFactory` 找不到说明装的是 Newtonsoft 版 `IO.GeoJSON`,该类只在 `IO.GeoJSON4STJ`;EF Core 类型冲突是同时引了 `Microsoft.SqlServer.Types`。
3
+ - **加载与引用**:单文件技能,无 reference 目录。
4
+ - 正文代码块密集,先按「核心 API:几何工厂」「WKT / WKB / GeoJSON」「空间索引」「几何修复与简化」「EF Core」「ProjNet」「典型工作流」定位小节再 `read` 片段,或 `grep` 搜 `GeometryFixer`、`GeoJsonConverterFactory`、`HandleOrdinates` 直接跳到行号,不要整篇读。
5
+ - 需要 Java 原版对照时用 `skill` 加载 `jts`,要 GDAL 侧读写时加载 `opengis-utils-for-net` 或 `gdal`
6
+ - **执行环境**:建工程、装包、构建、运行走 `ops_bash`(本机 Windows 是 MSYS bash,先 `command -v dotnet` 确认)
7
+ - 只有需要 `Get-Command` 或带反斜杠的 `.exe` 参数时才换 `pwsh`。探测代码放会话工作区(`dotnet new console -o work/nts-probe`),不要往 `assets/` 写
8
+ - 首次 `dotnet restore` 要访问 NuGet,内网先确认源可用,失败一次就报告,不要反复重试。MSYS 的 `/d/...` 传给 .NET 进程常解析失败,代码里的路径写 `D:\...`。
9
+ - **先探测版本**:`dotnet --version` 确认 SDK 6+,`dotnet list package --include-transitive` 核对 `NetTopologySuite` 2.6.0、`NetTopologySuite.IO.GeoJSON`(或 `IO.GeoJSON4STJ`)4.0.0、`IO.Esri.Shapefile` 1.2.0、`ProjNet` 2.1.0——正文按这组版本编写。
10
+ - 低于 2.6 没有 `NtsGeometryServices` 工厂重载与 `GeometryFixer`
11
+ - `WKTReader(GeometryFactory)` 在 2.6 已标记过时,能编但告警
12
+ - 旧 `ProjNet4GeoAPI` 停在 1.4.1,新工程用 `ProjNet`。
13
+ - **验证产物**:`dotnet build` 只证明编译过。写最小控制台跑正文「典型工作流」的判据:`parcel.Intersection(zone).Area` 为 12.5、`back.IsValid` 为 `true`、WKT 往返坐标数一致
14
+ - 输出重定向到 `run.log` 再 `read`,或写成 xunit 用例交给 `dotnet test`。Shapefile 产物用 `Shapefile.ReadAllFeatures` 回读要素数,机上有 GDAL 时再 `ogrinfo -so out.shp` 复核。要交付的 GeoJSON 用 `present` 列给用户。
15
+ - **风险与权限**:装 SDK、加 NuGet 包、连 SQL Server/PostgreSQL 都要先问人——用 `ask_user_question` 给「只读连接/新建库/跳过」选项,生产库不直接读写。`Shapefile.WriteAllFeatures` 与 `GeoJsonWriter` 写同名文件会覆盖,先换名或备份
16
+ - EF Core 的 `EnsureCreated`、迁移、批量 `UPDATE` 都改库。`GeometryFixer.Fix` 可能返回 `MultiPolygon`,别照抄正文的 `(Polygon)` 强转
17
+ - `WKBWriter` 默认丢 Z/M,需要时设 `HandleOrdinates`。
18
+ - **常见失败**:`TopologyException` 先用 `GeometryFixer.Fix`
19
+ - `TypeInitializationException` 或程序集加载失败多为 IO 包与主库版本错配
20
+ - `GeoJsonConverterFactory` 找不到说明装的是 Newtonsoft 版 `IO.GeoJSON`,该类只在 `IO.GeoJSON4STJ`
21
+ - EF Core 类型冲突是同时引了 `Microsoft.SqlServer.Types`。
@@ -1,8 +1,21 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,没有 reference 目录;正文「核心命令」的参数表与预设组合是主要入口,「典型工作流」四条链路按场景取用,「常见问题」表先对症状。成果入库转换用 `skill` 加载 `gdal`,点云清洗用 `pdal`,三维发布用 `cesiumjs`;不要 `read` 兄弟目录的 SKILL.md。
4
- - **执行环境**:全部命令在 `ops_bash` 里跑,Windows 侧依赖 Docker Desktop,动手前确认守护进程在跑(`docker info` 能出 Server 段)。正文的 `docker run -ti` 在 DSH 里会因无 TTY 报 `the input device is not a TTY`,去掉 `-t` 只留 `-i` 或直接不加;MSYS bash 会把 `-v /datasets:/datasets` 这类参数当路径改写,挂载统一写成宿主 `-v /d/datasets:/datasets` 并在命令前加 `MSYS_NO_PATHCONV=1`,或改用 `pwsh` 调 `docker run -v d:/datasets:/datasets`。整条流水线以小时计、镜像首次拉取就上 GB,必须 `run_in_background` 起作业、`job_output`(可带 `wait`)收进度与末尾日志,跑错再 `job_kill`,不要在一条前台命令里等完。
5
- - **先探测版本**:`docker --version` 与 `docker info --format '{{.MemTotal}}'` 先看引擎与可用内存(OOM 是头号失败原因),`docker run --rm opendronemap/odm:3.6.2 --version` 确认镜像标签是正文写的 3.6.2 而不是 `latest`,第一次会先拉镜像,同样放后台。WebODM 侧 `curl -s http://localhost:8000/api/` 应返回带 version 的 JSON,起 `./webodm.sh` 前先 `curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/` 看端口有没有被占。
6
- - **验证产物**:先数输入 `ls images | wc -l` 与预计张数一致,再看退出码——137 就是 OOM,别当普通失败。产物按正文目录约定逐项核:`gdalinfo -json odm_orthophoto/odm_orthophoto.tif` 核对 CRS 与尺寸、`gdalinfo -stats odm_dem/dsm.tif` 看高程范围是否合理,`odm_report/` 里的重叠度与重投影误差才是质量判据,只出图不代表成果可信。要肉眼确认正射影像,用 OSGeo4W 的 `gdal_translate -of PNG -outsize 1024 0 odm_orthophoto.tif preview.png` 生成缩略图后 `read_image` 看一眼,纯白或被裁成一条与空文件同罪;WebODM 的成果最终由用户在 2D/3D 查看器确认,写明「打开哪个地址、应看到什么」。
7
- - **风险与权限**:`--rerun` 会就地重算并覆盖已有阶段产物、`./webodm.sh down` 删容器、`docker system prune` 清镜像层,都不可逆,执行前用 `ask_user_question` 给「换项目目录重跑/覆盖现有成果/取消」;WebODM 的 `admin` 密码与 JWT token 从环境变量传入、命令里只引用 `$TOKEN`,日志与回答里不回显。对外暴露 8000/3000 端口、上传航拍影像、把成果传给第三方之前,确认数据合规(测绘资质与隐私)。
8
- - **常见失败**:`No images found` 是缺 `images/` 子目录或 `--project-path` 传成了数据集本身;空三大量未注册先查重叠度与糊片,改参数救不回来;正射空白或被裁条先去 `--auto-boundary` 再试;没有 `dsm.tif` 是没传 `--dsm`;Windows 挂载失败基本是路径写了反斜杠或 Docker Desktop 没共享该盘符。
3
+ - **加载与引用**:单文件技能,没有 reference 目录
4
+ - 正文「核心命令」的参数表与预设组合是主要入口,「典型工作流」四条链路按场景取用,「常见问题」表先对症状。成果入库转换用 `skill` 加载 `gdal`,点云清洗用 `pdal`,三维发布用 `cesiumjs`
5
+ - 不要 `read` 兄弟目录的 SKILL.md。
6
+ - **执行环境**:全部命令在 `ops_bash` 里跑,Windows 侧依赖 Docker Desktop,动手前确认守护进程在跑(`docker info` 能出 Server 段)。正文的 `docker run -ti` 在 DSH 里会因无 TTY 报 `the input device is not a TTY`,去掉 `-t` 只留 `-i` 或直接不加
7
+ - MSYS bash 会把 `-v /datasets:/datasets` 这类参数当路径改写,挂载统一写成宿主 `-v /d/datasets:/datasets` 并在命令前加 `MSYS_NO_PATHCONV=1`,或改用 `pwsh` 调 `docker run -v d:/datasets:/datasets`。
8
+ - 整条流水线以小时计、镜像首次拉取就上 GB,必须 `run_in_background` 起作业、`job_output`(可带 `wait`)收进度与末尾日志,跑错再 `job_kill`,不要在一条前台命令里等完
9
+ - **先探测版本**:`docker --version` 与 `docker info --format '{{.MemTotal}}'` 先看引擎与可用内存(OOM 是头号失败原因),`docker run --rm opendronemap/odm:3.6.2 --version` 确认镜像标签是正文写的 3.6.2 而不是 `latest`,第一次会先拉镜像,同样放后台。
10
+ - WebODM 侧 `curl -s http://localhost:8000/api/` 应返回带 version 的 JSON,起 `./webodm.sh` 前先 `curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/` 看端口有没有被占
11
+ - **验证产物**:先数输入 `ls images | wc -l` 与预计张数一致,再看退出码——137 就是 OOM,别当普通失败。
12
+ - 产物按正文目录约定逐项核:`gdalinfo -json odm_orthophoto/odm_orthophoto.tif` 核对 CRS 与尺寸、`gdalinfo -stats odm_dem/dsm.tif` 看高程范围是否合理,`odm_report/` 里的重叠度与重投影误差才是质量判据,只出图不代表成果可信。
13
+ - 要肉眼确认正射影像,用 OSGeo4W 的 `gdal_translate -of PNG -outsize 1024 0 odm_orthophoto.tif preview.png` 生成缩略图后 `read_image` 看一眼,纯白或被裁成一条与空文件同罪
14
+ - WebODM 的成果最终由用户在 2D/3D 查看器确认,写明「打开哪个地址、应看到什么」。
15
+ - **风险与权限**:`--rerun` 会就地重算并覆盖已有阶段产物、`./webodm.sh down` 删容器、`docker system prune` 清镜像层,都不可逆,执行前用 `ask_user_question` 给「换项目目录重跑/覆盖现有成果/取消」
16
+ - WebODM 的 `admin` 密码与 JWT token 从环境变量传入、命令里只引用 `$TOKEN`,日志与回答里不回显。对外暴露 8000/3000 端口、上传航拍影像、把成果传给第三方之前,确认数据合规(测绘资质与隐私)。
17
+ - **常见失败**:`No images found` 是缺 `images/` 子目录或 `--project-path` 传成了数据集本身
18
+ - 空三大量未注册先查重叠度与糊片,改参数救不回来
19
+ - 正射空白或被裁条先去 `--auto-boundary` 再试
20
+ - 没有 `dsm.tif` 是没传 `--dsm`
21
+ - Windows 挂载失败基本是路径写了反斜杠或 Docker Desktop 没共享该盘符。
@@ -1,9 +1,20 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:本技能是索引型入口:先按四个阶段定位工具,再用 `skill` 加载子技能读细节(`gdal`、`gdal-api`、`qgis-process`、`pyqgis`、`geoserver-rest-api`、`openlayers`、`cesiumjs`、`stac-cog-titiler`),别指望本文给全参数;影像云原生链路(COG 出图、STAC 编目、TiTiler 动态切片)从 `stac-cog-titiler` 进。两份参考要分段取:`reference/data-stages.md` 先看开头 `## Contents` 定位阶段一至阶段四的小节,再按 `offset`/`limit` 读;`reference/workflow-cheatsheets.md` 只取端到端示例、内置算法速查、GDAL 命令速查几节,用 `grep` 定位比整读快。
4
- - **执行环境**:四个阶段的命令都在 `ops_bash` 里跑。Windows 没有 `apt-get`/`sudo`:GDAL 走 OSGeo4W 绝对路径或 conda-forge,QGIS 用官方安装包(`qgis_process` 随安装自带),GeoServer 用 Docker。`QT_QPA_PLATFORM=offscreen` 在 bash 写成单条命令前缀,在 `pwsh` 写 `$env:QT_QPA_PLATFORM = "offscreen"`。起服务用后台作业:`docker run -d -p 8080:8080 docker.osgeo.org/geoserver:3.0.2` 以 `run_in_background` 启动,再用 `job_output` 轮询就绪,别让一次调用阻塞;收尾 `job_kill`。`qgis_process` 参数多,先 `qgis_process help <id> --json`。
5
- - **先探测版本**:`gdalinfo --version` / `ogrinfo --version`(正文基准 GDAL 3.13.3)、`qgis_process --version`(基准 QGIS 4.2.3,LTR 3.44.15;4.x 与 3.44 的 Processing 算法 ID 和 Qt 版本不同,混用会报未知算法)、`curl -u admin:geoserver "http://localhost:8080/geoserver/rest/about/version.json"`(GeoServer 3.0.2)、`python3 -c "from osgeo import gdal; print(gdal.VersionInfo())"`。缺哪个阶段的工具就加载相邻子技能,不要硬拼整条链路。
6
- - **验证产物**:每阶段产物落工作区(GeoPackage/COG/GeoJSON),下一阶段只读产物。转换后 `ogrinfo -so -al`、`gdalinfo -json` 核对 CRS、范围与要素数;发布后 `curl` 回读 `layers/demo:roads_buffer.json`,要求 HTTP 200 且含 `"enabled": true`,或查 `GetCapabilities`;WMS 出图后用 `read_image` 看一眼贴图是否真有内容。要交付的 GeoJSON、地图包用 `present` 列出。任一步失败先修本阶段产物,别带坏数据往下走。
7
- - **风险与权限**:`gdal_edit.py` 就地改元数据、`ogr2ogr` 同名输出、GeoServer `?recurse=true` 删除都不可逆,先备份并确认路径;GeoServer 默认 `admin:geoserver` 只用于本地演示,真实凭据不进命令行与回复。装 GDAL/QGIS、拉镜像、监听端口、连生产库前用 `ask_user_question` 让用户选方案;对外暴露 8080 端口要单独确认。
3
+ - **加载与引用**:本技能是索引型入口:先按四个阶段定位工具,再用 `skill` 加载子技能读细节(`gdal`、`gdal-api`、`qgis-process`、`pyqgis`、`geoserver-rest-api`、`openlayers`、`cesiumjs`、`stac-cog-titiler`),别指望本文给全参数
4
+ - 影像云原生链路(COG 出图、STAC 编目、TiTiler 动态切片)从 `stac-cog-titiler` 进。两份参考要分段取:`reference/data-stages.md` 先看开头 `## Contents` 定位阶段一至阶段四的小节,再按 `offset`/`limit` 读
5
+ - `reference/workflow-cheatsheets.md` 只取端到端示例、内置算法速查、GDAL 命令速查几节,用 `grep` 定位比整读快。
6
+ - **执行环境**:四个阶段的命令都在 `ops_bash` 里跑。
7
+ - Windows 没有 `apt-get`/`sudo`:GDAL 走 OSGeo4W 绝对路径或 conda-forge,QGIS 用官方安装包(`qgis_process` 随安装自带),GeoServer 用 Docker。
8
+ - `QT_QPA_PLATFORM=offscreen` 在 bash 写成单条命令前缀,在 `pwsh` 写 `$env:QT_QPA_PLATFORM = "offscreen"`。
9
+ - 起服务用后台作业:`docker run -d -p 8080:8080 docker.osgeo.org/geoserver:3.0.2` 以 `run_in_background` 启动,再用 `job_output` 轮询就绪,别让一次调用阻塞
10
+ - 收尾 `job_kill`。`qgis_process` 参数多,先 `qgis_process help <id> --json`。
11
+ - **先探测版本**:`gdalinfo --version` / `ogrinfo --version`(正文基准 GDAL 3.13.3)、`qgis_process --version`(基准 QGIS 4.2.3,LTR 3.44.15;4.x 与 3.44 的 Processing 算法 ID 和 Qt 版本不同,混用会报未知算法)、`curl -u admin:geoserver "http://localhost:8080/geoserver/rest/about/version.json"`(GeoServer 3.0.2)、`python3 -c "from osgeo import gdal; print(gdal.VersionInfo())"`。
12
+ - 缺哪个阶段的工具就加载相邻子技能,不要硬拼整条链路
13
+ - **验证产物**:每阶段产物落工作区(GeoPackage/COG/GeoJSON),下一阶段只读产物。转换后 `ogrinfo -so -al`、`gdalinfo -json` 核对 CRS、范围与要素数
14
+ - 发布后 `curl` 回读 `layers/demo:roads_buffer.json`,要求 HTTP 200 且含 `"enabled": true`,或查 `GetCapabilities`
15
+ - WMS 出图后用 `read_image` 看一眼贴图是否真有内容。要交付的 GeoJSON、地图包用 `present` 列出。任一步失败先修本阶段产物,别带坏数据往下走。
16
+ - **风险与权限**:`gdal_edit.py` 就地改元数据、`ogr2ogr` 同名输出、GeoServer `?recurse=true` 删除都不可逆,先备份并确认路径
17
+ - GeoServer 默认 `admin:geoserver` 只用于本地演示,真实凭据不进命令行与回复。装 GDAL/QGIS、拉镜像、监听端口、连生产库前用 `ask_user_question` 让用户选方案
18
+ - 对外暴露 8080 端口要单独确认。
8
19
  - **常见失败**:`qgis_process` 在无显示器环境崩溃先设 `QT_QPA_PLATFORM=offscreen`;上传 Shapefile 失败先打成 ZIP 且根目录含 `.shp/.shx/.dbf/.prj`;报找不到 `gdal_calc.py` 是缺 Python 绑定,改用 `qgis_process run gdal:rastercalculator`;REST 401/403 查 Basic Auth 与用户权限;大栅格内存不足先 `gdal_translate -srcwin` 分块并调 `GDAL_CACHEMAX`、`GDAL_NUM_THREADS`。
9
20
  - **工作流**:端到端链路先 `todo_write` 拆成「取数→转换→分析→发布→回读」,阶段间以文件为契约;多数据源核对这类互不依赖的活可以 `subagent` 并行,但发布步骤必须串行等验证通过。
@@ -1,9 +1,20 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference 目录;正文的「方案配置」「内置算子」「CLI 命令」「常见问题」是查表区,按小节定位即可。正文提到的 `docs/plan-config-guide.md`、`docs/operator-reference.md` 在上游仓库里,clone 后才有、不在技能目录内,别用 `read` 硬找。需要几何语义用 `skill` 加载 `nettopologysuite`,GDAL 绑定细节加载 `opengis-utils-for-net`。
4
- - **执行环境**:`git clone --recurse-submodules` 走 `ops_bash`(漏 `--recurse-submodules` 会缺 `opengis-utils-for-net` 子模块,编译期报 GDAL 绑定类型缺失);`dotnet` 系列与 `.\build.ps1`、`demo/run-demo.ps1` 走 `pwsh`。要求 .NET SDK 10.0(`global.json` 锁 10.0.301),没有就如实报告,不要拿 .NET 8/9 硬编。克隆目录与 `plans/` 放会话工作区;长构建用后台作业加 `job_output` 收日志。
5
- - **先探测版本**:正文按 .NET SDK 10.0.301(C# 14)编写;`dotnet --version` 与 `dotnet --list-sdks` 确认 10.0.301 在列;`dotnet build OpenGisDAF.slnx --configuration Release` 成功后 `dotnet run --project src/OpenGisDAF.Cli -- help` 确认 CLI 可用。本项目无 Release tag、无 NuGet 包,别写 `dotnet add package OpenGisDAF`;SDK 低于 `global.json` 要求时会直接拒绝构建。
6
- - **验证产物**:先 `daf validate --plan plans/my.json`(只校验 21 条规则)再 `daf run --plan plans/my.json`,退出码 `0` 才算成功(失败或跳过都返回 1)。QC 方案额外生成 `{plan}.qc-report.json`,看 `totalChecked`/`failed`/`passRate` 与 issue 清单;非 QC 方案不生成该文件。输出 GeoJSON 用 `ogrinfo -so` 或 `read` 回读核对 `crs`、要素数、字段。测试必须两步:先 `dotnet build OpenGisDAF.slnx -c Release` 再 `dotnet test OpenGisDAF.slnx -c Release --no-build`,同一条命令会报「运行了零个测试」并退出码 5。
7
- - **风险与权限**:`daf plan` 写 `%APPDATA%\opengis-daf\plans`,`copy`/`export` 会覆盖同名方案;PostGIS 输出的 `encryptedPassword` 只接受当前用户生成的 DPAPI/AES-256-GCM 密文,明文直接失败且不回显密文。目标表已存在报 `Layer already exists` 是有意防误覆盖,删表或换表名都要先问用户;`buffer` 的 `distance` 单位随数据坐标系,EPSG:4326 下 800 就是 800 度。删表、覆盖方案、连生产库前用 `ask_user_question` 给选项。
3
+ - **加载与引用**:单文件技能,无 reference 目录
4
+ - 正文的「方案配置」「内置算子」「CLI 命令」「常见问题」是查表区,按小节定位即可。
5
+ - 正文提到的 `docs/plan-config-guide.md`、`docs/operator-reference.md` 在上游仓库里,clone 后才有、不在技能目录内,别用 `read` 硬找。
6
+ - 需要几何语义用 `skill` 加载 `nettopologysuite`,GDAL 绑定细节加载 `opengis-utils-for-net`
7
+ - **执行环境**:`git clone --recurse-submodules` 走 `ops_bash`(漏 `--recurse-submodules` 会缺 `opengis-utils-for-net` 子模块,编译期报 GDAL 绑定类型缺失)
8
+ - `dotnet` 系列与 `.\build.ps1`、`demo/run-demo.ps1` 走 `pwsh`。要求 .NET SDK 10.0(`global.json` 锁 10.0.301),没有就如实报告,不要拿 .NET 8/9 硬编。克隆目录与 `plans/` 放会话工作区
9
+ - 长构建用后台作业加 `job_output` 收日志。
10
+ - **先探测版本**:正文按 .NET SDK 10.0.301(C# 14)编写
11
+ - `dotnet --version` 与 `dotnet --list-sdks` 确认 10.0.301 在列
12
+ - `dotnet build OpenGisDAF.slnx --configuration Release` 成功后 `dotnet run --project src/OpenGisDAF.Cli -- help` 确认 CLI 可用。本项目无 Release tag、无 NuGet 包,别写 `dotnet add package OpenGisDAF`
13
+ - SDK 低于 `global.json` 要求时会直接拒绝构建。
14
+ - **验证产物**:先 `daf validate --plan plans/my.json`(只校验 21 条规则)再 `daf run --plan plans/my.json`,退出码 `0` 才算成功(失败或跳过都返回 1)。QC 方案额外生成 `{plan}.qc-report.json`,看 `totalChecked`/`failed`/`passRate` 与 issue 清单
15
+ - 非 QC 方案不生成该文件。输出 GeoJSON 用 `ogrinfo -so` 或 `read` 回读核对 `crs`、要素数、字段。测试必须两步:先 `dotnet build OpenGisDAF.slnx -c Release` 再 `dotnet test OpenGisDAF.slnx -c Release --no-build`,同一条命令会报「运行了零个测试」并退出码 5。
16
+ - **风险与权限**:`daf plan` 写 `%APPDATA%\opengis-daf\plans`,`copy`/`export` 会覆盖同名方案
17
+ - PostGIS 输出的 `encryptedPassword` 只接受当前用户生成的 DPAPI/AES-256-GCM 密文,明文直接失败且不回显密文。目标表已存在报 `Layer already exists` 是有意防误覆盖,删表或换表名都要先问用户
18
+ - `buffer` 的 `distance` 单位随数据坐标系,EPSG:4326 下 800 就是 800 度。删表、覆盖方案、连生产库前用 `ask_user_question` 给选项。
8
19
  - **常见失败**:`dotnet test` 报「运行了零个测试」+退出码 5 是 xunit.v3 工具链的固有行为,按上面两步走;缺子模块时编译报 GDAL 类型缺失,重新 clone 带 `--recurse-submodules`;插件算子不出现,先查是否把 `OpenGisDAF.Core.dll` 复制进插件目录(类型不同源会被静默跳过),且 `daf operator import` 只对当前进程有效,要让插件参与 `daf run` 必须用同进程宿主。
9
20
  - **交付**:方案 JSON、QC 报告、输出 GeoJSON/Shapefile 都以工作区相对路径写回复,成品用 `present` 列出;qc-report 里的 WKT 违规几何可单独抽成文件再给用户。
@@ -1,8 +1,22 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:主文件给高频入口(`OguLayerUtil`、枚举、数据模型、异常层次),完整示例在 `reference/common-tasks.md`:先 `read` 该文件开头 `## Contents`,再跳到「常用任务速查」下的读取/写出/几何运算小节,或 `grep` 搜 `readLayer`、`writeLayer`、`GeometryUtil.bufferWkt` 定位,别整份读。需要 JTS 几何语义用 `skill` 加载 `jts`,GDAL 命令行核对加载 `gdal`。
4
- - **执行环境**:`java`、`mvn` 走 `ops_bash`(MSYS bash);需要 `java.library.path` 这类带反斜杠的 Windows 属性时换 `pwsh`。本库未发布到 Maven Central,必须先 `git clone` 后 `mvn install -DskipTests` 装到本地仓库,再在业务工程里引 `com.znlgis.ogu4j:ogu4j:1.0.0`;`~/.m2` 在 Windows 实为 `%USERPROFILE%\.m2`。示例 Java 代码里的路径写 Windows 形式(`D:/work/parcels.shp`),MSYS 的 `/d/...` 传给 JVM 常找不到文件。长构建用后台作业加 `job_output` 收日志。
5
- - **先探测版本**:`java -version` 与 `mvn -version`(JDK 17+、Maven 3.8+),`mvn -v` 里显示的 JDK 才是 Maven 实际使用的,与 shell 的 `java` 不一致先改 `JAVA_HOME`。正文按 OGU4J 1.0.0、`org.gdal:gdal` 3.13.0 编写;`mvn dependency:tree -Dincludes=com.znlgis.ogu4j` 确认坐标;原生 GDAL 版本低于 3.13 时 GDAL 引擎会链不上,FileGDB 直接不可用。找不到 CI 里的 `1.0.0` 包就是没做本地 `mvn install`,不要去 Central 找。
6
- - **验证产物**:`mvn -q -DskipTests package` 只证明能编译。写最小 main 跑正文「典型工作流」:`OguLayerUtil.readLayer(DataFormatType.SHP, path, null, null, null, GisEngineType.AUTO)` 打印 `getWkid()` 与 `getFeatureCount()`,`CrsUtil.reproject(layer, 4528)` 后再 `writeLayer` 成 GeoJSON,回读的 WKID 必须是 4528、要素数与筛选结果一致;机上有 GDAL 时再 `ogrinfo -so out.geojson` 复核。`mvn -v` 的输出与测试日志重定向到 `run.log` 再 `read`。成品 GeoJSON 用 `present` 交付。
7
- - **风险与权限**:`mvn install` 写 `~/.m2` 并可能覆盖同名 SNAPSHOT;`OguLayerUtil.writeLayer` 写同名 Shapefile/GeoJSON 会整份覆盖,先换名或备份。PostGIS 连接串(`PG: host=... password=...`)的密码不要回显,连接生产库前用 `ask_user_question` 让用户选只读还是跳过。`DataStore` 与 OGR `DataSource` 要在 `finally` 释放,否则文件被占用后覆盖失败;`GisEngineType.AUTO` 在装了原生 GDAL 时优先 GDAL,要复现纯 Java 结果必须显式传 `GEOTOOLS`。
8
- - **常见失败**:`UnsatisfiedLinkError: no gdal_jni in java.library.path` 是原生 GDAL 缺失或版本不匹配,装 GDAL 3.13.x 或改 `GEOTOOLS`;`Could not resolve dependencies for org.geotools:*` 是 `pom.xml` 缺 `https://repo.osgeo.org/repository/release/`;`找不到 com.znlgis.ogu4j:ogu4j` 是没本地安装;Shapefile 字段名被截断用 `ShpUtil.formatFieldName()`。
3
+ - **加载与引用**:主文件给高频入口(`OguLayerUtil`、枚举、数据模型、异常层次),完整示例在 `reference/common-tasks.md`:先 `read` 该文件开头 `## Contents`,再跳到「常用任务速查」下的读取/写出/几何运算小节,或 `grep` 搜 `readLayer`、`writeLayer`、`GeometryUtil.bufferWkt` 定位,别整份读。
4
+ - 需要 JTS 几何语义用 `skill` 加载 `jts`,GDAL 命令行核对加载 `gdal`
5
+ - **执行环境**:`java`、`mvn` 走 `ops_bash`(MSYS bash)
6
+ - 需要 `java.library.path` 这类带反斜杠的 Windows 属性时换 `pwsh`。本库未发布到 Maven Central,必须先 `git clone` 后 `mvn install -DskipTests` 装到本地仓库,再在业务工程里引 `com.znlgis.ogu4j:ogu4j:1.0.0`
7
+ - `~/.m2` 在 Windows 实为 `%USERPROFILE%\.m2`。示例 Java 代码里的路径写 Windows 形式(`D:/work/parcels.shp`),MSYS 的 `/d/...` 传给 JVM 常找不到文件。长构建用后台作业加 `job_output` 收日志。
8
+ - **先探测版本**:`java -version` 与 `mvn -version`(JDK 17+、Maven 3.8+),`mvn -v` 里显示的 JDK 才是 Maven 实际使用的,与 shell 的 `java` 不一致先改 `JAVA_HOME`。正文按 OGU4J 1.0.0、`org.gdal:gdal` 3.13.0 编写
9
+ - `mvn dependency:tree -Dincludes=com.znlgis.ogu4j` 确认坐标
10
+ - 原生 GDAL 版本低于 3.13 时 GDAL 引擎会链不上,FileGDB 直接不可用。找不到 CI 里的 `1.0.0` 包就是没做本地 `mvn install`,不要去 Central 找。
11
+ - **验证产物**:`mvn -q -DskipTests package` 只证明能编译。
12
+ - 写最小 main 跑正文「典型工作流」:`OguLayerUtil.readLayer(DataFormatType.SHP, path, null, null, null, GisEngineType.AUTO)` 打印 `getWkid()` 与 `getFeatureCount()`,`CrsUtil.reproject(layer, 4528)` 后再 `writeLayer` 成 GeoJSON,回读的 WKID 必须是 4528、要素数与筛选结果一致
13
+ - 机上有 GDAL 时再 `ogrinfo -so out.geojson` 复核。`mvn -v` 的输出与测试日志重定向到 `run.log` 再 `read`。成品 GeoJSON 用 `present` 交付。
14
+ - **风险与权限**:`mvn install` 写 `~/.m2` 并可能覆盖同名 SNAPSHOT
15
+ - `OguLayerUtil.writeLayer` 写同名 Shapefile/GeoJSON 会整份覆盖,先换名或备份。
16
+ - PostGIS 连接串(`PG: host=... password=...`)的密码不要回显,连接生产库前用 `ask_user_question` 让用户选只读还是跳过。
17
+ - `DataStore` 与 OGR `DataSource` 要在 `finally` 释放,否则文件被占用后覆盖失败
18
+ - `GisEngineType.AUTO` 在装了原生 GDAL 时优先 GDAL,要复现纯 Java 结果必须显式传 `GEOTOOLS`。
19
+ - **常见失败**:`UnsatisfiedLinkError: no gdal_jni in java.library.path` 是原生 GDAL 缺失或版本不匹配,装 GDAL 3.13.x 或改 `GEOTOOLS`
20
+ - `Could not resolve dependencies for org.geotools:*` 是 `pom.xml` 缺 `https://repo.osgeo.org/repository/release/`
21
+ - `找不到 com.znlgis.ogu4j:ogu4j` 是没本地安装
22
+ - Shapefile 字段名被截断用 `ShpUtil.formatFieldName()`。
@@ -1,8 +1,25 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:主文件给 `OguLayerUtil` 入口、模型类与枚举;`OguLayerUtil`/`GeometryUtil`/`CrsUtil`/`ShpUtil`/`PostgisUtil`/`GtTxtUtil` 的完整签名在 `reference/util-classes.md`(开头 `## Contents` 按类分节,`read` 时带 `offset`/`limit`),从零构造图层、读写筛选的成段示例在 `reference/code-patterns.md`。主文件 480 余行,用 `grep` 搜 `ReadLayer(`、`CrsUtil.Transform`、`Geojson2Wkt` 定位行号再局部读,别整篇搬进上下文。
4
- - **执行环境**:`dotnet new/restore/build/run/test` 走 `ops_bash`;确需 `Get-Command` 或带反斜杠的 Windows 路径参数时换 `pwsh`。探测工程建在会话工作区(`dotnet new console -o work/ogu-probe`),别写进 `assets/`。正文里的 `findstr` 是 cmd 写法,MSYS 下用 `grep`:`dotnet list package --include-transitive | grep OpenGIS.Utils`。GDAL 原生运行时由 `MaxRev.Gdal.Universal` 随包分发,不要手写 `GdalConfiguration.ConfigureGdal()`。长构建放后台作业,用 `job_output` 收日志。
5
- - **先探测版本**:`dotnet --version`(库目标 .NET Standard 2.0,.NET Core 2.0+/5+ 均可引用),正文按 `OpenGIS.Utils` 1.1.2 编写;`dotnet restore` 能解析即包可用,`dotnet list package --include-transitive | grep OpenGIS.Utils` 核对实际解析到的 1.1.2。`NU1101`/`NU1102` 表示源或版本不可用,如实报告,不要自行改版本号重试。低于 1.1.2 的版本没有 `GEOPACKAGE`/`KML`/`DXF` 这些 `DataFormatType` 与 `ConvertFormat`。
6
- - **验证产物**:`dotnet build` 成功只说明编译过,GDAL 原生库是运行期才加载。写最小控制台跑正文「典型工作流」:读 Shapefile 后打印 `layer.Wkid` 与 `layer.GetFeatureCount()`,`CrsUtil.Transform` 逐要素转到 4528 并改 `layer.Wkid`,`WriteLayer` 出 GeoPackage 后回读,核对 WKID 为 4528、要素数与筛选结果一致;`dotnet run > run.log 2>&1` 再 `read` 日志确认,机上有 GDAL 时补 `ogrinfo -so data/parcels_4528.gpkg`。成品用 `present` 交付。
7
- - **风险与权限**:`WriteLayer` 写 Shapefile/GeoPackage/KML 会覆盖同名文件,先换名或备份;`ConvertFormat` 同理。PostGIS 连接串与 GDAL 配置里的密码不要回显,连生产库前用 `ask_user_question` 给「只读/新库/跳过」选项。`dotnet restore`、装 SDK、改 `NuGet.config` 前先问用户。`OgrGeometry` 实现 `IDisposable`,用完 `Dispose()`,否则大批量几何会吃满内存;`GEOTOOLS` 在 .NET 版被重定向到 GDAL,别据此以为有纯托管路径。
8
- - **常见失败**:`DllNotFoundException` / `Unable to load DLL 'gdal'` 多是 RID 与运行环境不一致,`dotnet publish -r win-x64` 后跑发布目录,别跑 `bin/Debug`;`Geojson2Wkt` 传整份 FeatureCollection 文件内容会抛 `ArgumentException`,整文件走 `OguLayerUtil.ReadLayer`;GBK Shapefile 乱码先 `Encoding.RegisterProvider(CodePagesEncodingProvider.Instance)` 再传 `Encoding.GetEncoding('GBK')`;`CrsUtil` 只有 WKT/`OgrGeometry` 重载,没有整层变换方法。
3
+ - **加载与引用**:主文件给 `OguLayerUtil` 入口、模型类与枚举
4
+ - `OguLayerUtil`/`GeometryUtil`/`CrsUtil`/`ShpUtil`/`PostgisUtil`/`GtTxtUtil` 的完整签名在 `reference/util-classes.md`(开头 `## Contents` 按类分节,`read` 时带 `offset`/`limit`),从零构造图层、读写筛选的成段示例在 `reference/code-patterns.md`。
5
+ - 主文件 480 余行,用 `grep` 搜 `ReadLayer(`、`CrsUtil.Transform`、`Geojson2Wkt` 定位行号再局部读,别整篇搬进上下文
6
+ - **执行环境**:`dotnet new/restore/build/run/test` 走 `ops_bash`
7
+ - 确需 `Get-Command` 或带反斜杠的 Windows 路径参数时换 `pwsh`。
8
+ - 探测工程建在会话工作区(`dotnet new console -o work/ogu-probe`),别写进 `assets/`。
9
+ - 正文里的 `findstr` 是 cmd 写法,MSYS 下用 `grep`:`dotnet list package --include-transitive | grep OpenGIS.Utils`。
10
+ - GDAL 原生运行时由 `MaxRev.Gdal.Universal` 随包分发,不要手写 `GdalConfiguration.ConfigureGdal()`。
11
+ - 长构建放后台作业,用 `job_output` 收日志
12
+ - **先探测版本**:`dotnet --version`(库目标 .NET Standard 2.0,.NET Core 2.0+/5+ 均可引用),正文按 `OpenGIS.Utils` 1.1.2 编写
13
+ - `dotnet restore` 能解析即包可用,`dotnet list package --include-transitive | grep OpenGIS.Utils` 核对实际解析到的 1.1.2。
14
+ - `NU1101`/`NU1102` 表示源或版本不可用,如实报告,不要自行改版本号重试。
15
+ - 低于 1.1.2 的版本没有 `GEOPACKAGE`/`KML`/`DXF` 这些 `DataFormatType` 与 `ConvertFormat`
16
+ - **验证产物**:`dotnet build` 成功只说明编译过,GDAL 原生库是运行期才加载。
17
+ - 写最小控制台跑正文「典型工作流」:读 Shapefile 后打印 `layer.Wkid` 与 `layer.GetFeatureCount()`,`CrsUtil.Transform` 逐要素转到 4528 并改 `layer.Wkid`,`WriteLayer` 出 GeoPackage 后回读,核对 WKID 为 4528、要素数与筛选结果一致
18
+ - `dotnet run > run.log 2>&1` 再 `read` 日志确认,机上有 GDAL 时补 `ogrinfo -so data/parcels_4528.gpkg`。成品用 `present` 交付。
19
+ - **风险与权限**:`WriteLayer` 写 Shapefile/GeoPackage/KML 会覆盖同名文件,先换名或备份
20
+ - `ConvertFormat` 同理。PostGIS 连接串与 GDAL 配置里的密码不要回显,连生产库前用 `ask_user_question` 给「只读/新库/跳过」选项。`dotnet restore`、装 SDK、改 `NuGet.config` 前先问用户。`OgrGeometry` 实现 `IDisposable`,用完 `Dispose()`,否则大批量几何会吃满内存
21
+ - `GEOTOOLS` 在 .NET 版被重定向到 GDAL,别据此以为有纯托管路径。
22
+ - **常见失败**:`DllNotFoundException` / `Unable to load DLL 'gdal'` 多是 RID 与运行环境不一致,`dotnet publish -r win-x64` 后跑发布目录,别跑 `bin/Debug`
23
+ - `Geojson2Wkt` 传整份 FeatureCollection 文件内容会抛 `ArgumentException`,整文件走 `OguLayerUtil.ReadLayer`
24
+ - GBK Shapefile 乱码先 `Encoding.RegisterProvider(CodePagesEncodingProvider.Instance)` 再传 `Encoding.GetEncoding('GBK')`
25
+ - `CrsUtil` 只有 WKT/`OgrGeometry` 重载,没有整层变换方法。
@@ -1,8 +1,22 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference 目录。正文的「典型工作流」是最完整、可直接跑的示例(含 `dataProjection`/`featureProjection` 与样式函数),照它起步比自己拼 `ol/...` 导入稳;有疑问时按「常见问题」表的报错原文定位小节,再 `grep` 搜对应类名。要联动服务端时用 `skill` 加载 `geoserver`,三维对照加载 `cesiumjs`,不要 `read` 兄弟目录的 `SKILL.md`。
4
- - **执行环境**:`npm install ol`、`npm run build`、`npx serve dist` 走 `ops_bash`(Windows 下 `npm` 实为 `npm.cmd`)。构建与起静态服务放后台作业(`run_in_background`),输出重定向到文件后用 `grep` 找错,收尾 `job_kill`;`python -m http.server 5173 -d dist` 同理。起 server、对外暴露端口前先用 `ask_user_question` 确认。工程建在会话工作区,别写进 `assets/`。
5
- - **先探测版本**:`npm ls ol`,未装再 `npm view ol version`;正文按 10.11.0 编写,只用 `ol/Map.js`、`ol/layer/Tile.js`、`ol/source/OSM.js` 这类 ESM 子路径。动手前用 `grep` 搜代码里的 `ol.source.`、`ol.layer.` 全量命名空间写法——10.x 里混用会在打包或运行时报错(`Failed to resolve module specifier`);低于 10 的版本 `MVT({ featureClass })`、`hitTolerance` 行为不同,按实际版本对 `--help` 与 API 文档核对。
6
- - **验证产物**:`npm run build` 通过只代表编译过;再 `curl.exe -I http://localhost:5173/` 与打包出的 `assets/*.js` 确认 200,并核验页面真能出图——底图与行政区面同现、画一个多边形后控制台输出 EPSG:4326 的 GeoJSON。有截图或渲染产物时用 `read_image` 真看一眼;交付给用户的页面与示例数据用 `present` 列出。
7
- - **风险与权限**:矢量图层不 `setStyle()` 默认不渲染,别把空白页面当成数据没加载;经纬度必须 `fromLonLat()` 转 EPSG:3857,自定义投影先 `register(proj4)`;内网 WMS 地址与凭据不要写进示例代码或回复。`npm install` 会改 `package-lock.json` 与 `node_modules`,在用户仓库里执行前先确认;起 dev server、改端口、对外暴露服务要单独确认。
8
- - **常见失败**:`Assertion failed: The view center is not defined` 是 `View` 没给 `center`;`Assertion failed: Expected a list of style instances` 是 `setStyle()` 收到非 Style 值;WMS 空白查 CORS、`LAYERS` 全名与 `SRS`/`CRS` 版本;MVT 属性丢失用 `new MVT({ featureClass: Feature })`;容器尺寸变化后调 `map.updateSize()`;模块找不到说明打包器没按 ESM 解析。
3
+ - **加载与引用**:单文件技能,无 reference 目录。正文的「典型工作流」是最完整、可直接跑的示例(含 `dataProjection`/`featureProjection` 与样式函数),照它起步比自己拼 `ol/...` 导入稳
4
+ - 有疑问时按「常见问题」表的报错原文定位小节,再 `grep` 搜对应类名。要联动服务端时用 `skill` 加载 `geoserver`,三维对照加载 `cesiumjs`,不要 `read` 兄弟目录的 `SKILL.md`。
5
+ - **执行环境**:`npm install ol`、`npm run build`、`npx serve dist` 走 `ops_bash`(Windows 下 `npm` 实为 `npm.cmd`)。构建与起静态服务放后台作业(`run_in_background`),输出重定向到文件后用 `grep` 找错,收尾 `job_kill`
6
+ - `python -m http.server 5173 -d dist` 同理。起 server、对外暴露端口前先用 `ask_user_question` 确认。工程建在会话工作区,别写进 `assets/`。
7
+ - **先探测版本**:`npm ls ol`,未装再 `npm view ol version`
8
+ - 正文按 10.11.0 编写,只用 `ol/Map.js`、`ol/layer/Tile.js`、`ol/source/OSM.js` 这类 ESM 子路径。动手前用 `grep` 搜代码里的 `ol.source.`、`ol.layer.` 全量命名空间写法——10.x 里混用会在打包或运行时报错(`Failed to resolve module specifier`)
9
+ - 低于 10 的版本 `MVT({ featureClass })`、`hitTolerance` 行为不同,按实际版本对 `--help` 与 API 文档核对。
10
+ - **验证产物**:`npm run build` 通过只代表编译过
11
+ - 再 `curl.exe -I http://localhost:5173/` 与打包出的 `assets/*.js` 确认 200,并核验页面真能出图——底图与行政区面同现、画一个多边形后控制台输出 EPSG:4326 的 GeoJSON。有截图或渲染产物时用 `read_image` 真看一眼
12
+ - 交付给用户的页面与示例数据用 `present` 列出。
13
+ - **风险与权限**:矢量图层不 `setStyle()` 默认不渲染,别把空白页面当成数据没加载
14
+ - 经纬度必须 `fromLonLat()` 转 EPSG:3857,自定义投影先 `register(proj4)`
15
+ - 内网 WMS 地址与凭据不要写进示例代码或回复。`npm install` 会改 `package-lock.json` 与 `node_modules`,在用户仓库里执行前先确认
16
+ - 起 dev server、改端口、对外暴露服务要单独确认。
17
+ - **常见失败**:`Assertion failed: The view center is not defined` 是 `View` 没给 `center`
18
+ - `Assertion failed: Expected a list of style instances` 是 `setStyle()` 收到非 Style 值
19
+ - WMS 空白查 CORS、`LAYERS` 全名与 `SRS`/`CRS` 版本
20
+ - MVT 属性丢失用 `new MVT({ featureClass: Feature })`
21
+ - 容器尺寸变化后调 `map.updateSize()`
22
+ - 模块找不到说明打包器没按 ESM 解析。
@@ -1,8 +1,28 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference 目录;参数不确定时先跑 `pdal --options filters.smrf` 或 `pdal --drivers` 取运行时定义,别凭记忆写 stage 参数——正文的算子参数表与这些命令输出以实际版本为准。管线较长时用 `write` 把 JSON 存成工作区里的 `pipeline.json`,复用和逐条改动都比命令行内联可靠;复杂管线按「读取→裁剪/重投影→过滤→写出」分段拼,出错好定位。需要 DEM 后处理时用 `skill` 加载 `gdal`。
4
- - **执行环境**:`pdal info/translate/pipeline/--drivers` 走 `ops_bash`;`Get-Command pdal` 或带反斜杠的 Windows 路径参数走 `pwsh`。本机 Windows 无 `sudo`/`apt`:PDAL 来自 conda-forge(`conda install -c conda-forge pdal python-pdal`)、OSGeo4W,或容器 `docker run --rm -v "$PWD":/data -w /data pdal/pdal pdal pipeline pipeline.json`(容器内路径写 `/data/...`,不要传宿主 `D:\...`)。整片点云处理、DEM 全量栅格化放后台作业,用 `job_output` 收日志、`job_kill` 收尾。
5
- - **先探测版本**:`pdal --version` 与 `pdal --drivers`;正文按 2.10.2 编写,`pdal ground` 自 2.6 弃用、2.7 移出默认安装、2.8 完全移除,见到旧命令一律换 `filters.smrf` 管线写法;2.10 才有的 `filters.m3c2`、`filters.radiusassign`、`writers.gdal` 的 `p<percentile>` 波段需先确认驱动列表里有;`readers.spz`/`writers.spz` 在 2.10 变成插件,标准安装的 `--drivers` 里看不到属正常,别当成损坏。低版本没有 `filters.expression` 时退回 `filters.range`(2.5 起推荐 expression、3.0 弃用 range)。Python 侧 `pip install PDAL` 依赖系统已装 PDAL 库(需 `pdal-config`),PyPI 的 `pdal` 3.5.5 与主库 2.10.2 是两套独立版本号。
6
- - **验证产物**:点云用 `pdal info --summary out.laz` 核对 `num_points`、`bounds`、`srs`(转换前后的点数差异要能解释,比如裁剪后减少、去噪后仍保留全部点仅标 Class=7);DEM 用 `gdalinfo -json dem.tif` 看波段数与范围:`writers.gdal` 默认 `output_type: "all"` 输出多波段,`p95` 这类百分位波段不计入 `all`,要单波段必须显式写 `idw`/`mean`,`binmode: true` 时只统计落在像元内的点、值域会变。`filters.georeference` 在 2.10 输出 ECEF(EPSG:4978),要经纬度必须再接 `filters.reprojection`,否则 `pdal info` 里的 srs 会是 4978。管线先 `pdal pipeline --validate` 再实跑,退出码 0 不能证明结果正确;DEM 或点云渲染图用 `read_image` 看一眼,成品用 `present` 交付。
7
- - **风险与权限**:`pdal translate` 与各 writer 按 `filename` 覆盖同名输出,先确认目标文件名、换名或备份;`filters.outlier`、`filters.smrf` 需要全局统计、不能流式,大点云先按 tile 拆分。拉取 Docker 镜像、下载大点云、安装 PDAL、写用户目录外的路径前用 `ask_user_question` 让用户选方案;从源码编译时 GDAL 必须 3.8+(`cmake/gdal.cmake` 硬校验,报 `Required at least GDAL version 3.8`),SMRF 参数改动会影响地面分类结果,交付前说明用了哪组参数。
8
- - **常见失败**:`Couldn't create <cls> stage of type '<type>'` 是 stage 名拼错或版本没有该 stage,先 `pdal --drivers` 确认;`pipeline` 解析失败用 `--validate` 定位 JSON 语法与顶层结构;`filters.reprojection` 报缺 SRS 补 `out_srs`(数据本身无坐标系时再给 `in_srs`);重投影后精度变差在 writer 设 `scale_x/y/z` 与 `offset_x/y/z: "auto"`;Python 侧 `execute()` 返回点数不是数组,数据在 `pipeline.arrays`,失败看 `pipeline.log`。
3
+ - **加载与引用**:单文件技能,无 reference 目录
4
+ - 参数不确定时先跑 `pdal --options filters.smrf` 或 `pdal --drivers` 取运行时定义,别凭记忆写 stage 参数——正文的算子参数表与这些命令输出以实际版本为准。管线较长时用 `write` 把 JSON 存成工作区里的 `pipeline.json`,复用和逐条改动都比命令行内联可靠
5
+ - 复杂管线按「读取→裁剪/重投影→过滤→写出」分段拼,出错好定位。需要 DEM 后处理时用 `skill` 加载 `gdal`。
6
+ - **执行环境**:`pdal info/translate/pipeline/--drivers` 走 `ops_bash`
7
+ - `Get-Command pdal` 或带反斜杠的 Windows 路径参数走 `pwsh`。
8
+ - 本机 Windows 无 `sudo`/`apt`:PDAL 来自 conda-forge(`conda install -c conda-forge pdal python-pdal`)、OSGeo4W,或容器 `docker run --rm -v "$PWD":/data -w /data pdal/pdal pdal pipeline pipeline.json`(容器内路径写 `/data/...`,不要传宿主 `D:\...`)。
9
+ - 整片点云处理、DEM 全量栅格化放后台作业,用 `job_output` 收日志、`job_kill` 收尾
10
+ - **先探测版本**:`pdal --version` 与 `pdal --drivers`
11
+ - 正文按 2.10.2 编写,`pdal ground` 自 2.6 弃用、2.7 移出默认安装、2.8 完全移除,见到旧命令一律换 `filters.smrf` 管线写法
12
+ - 2.10 才有的 `filters.m3c2`、`filters.radiusassign`、`writers.gdal` 的 `p<percentile>` 波段需先确认驱动列表里有
13
+ - `readers.spz`/`writers.spz` 在 2.10 变成插件,标准安装的 `--drivers` 里看不到属正常,别当成损坏。
14
+ - 低版本没有 `filters.expression` 时退回 `filters.range`(2.5 起推荐 expression、3.0 弃用 range)。
15
+ - Python 侧 `pip install PDAL` 依赖系统已装 PDAL 库(需 `pdal-config`),PyPI 的 `pdal` 3.5.5 与主库 2.10.2 是两套独立版本号
16
+ - **验证产物**:点云用 `pdal info --summary out.laz` 核对 `num_points`、`bounds`、`srs`(转换前后的点数差异要能解释,比如裁剪后减少、去噪后仍保留全部点仅标 Class=7)
17
+ - DEM 用 `gdalinfo -json dem.tif` 看波段数与范围:`writers.gdal` 默认 `output_type: "all"` 输出多波段,`p95` 这类百分位波段不计入 `all`,要单波段必须显式写 `idw`/`mean`,`binmode: true` 时只统计落在像元内的点、值域会变。
18
+ - `filters.georeference` 在 2.10 输出 ECEF(EPSG:4978),要经纬度必须再接 `filters.reprojection`,否则 `pdal info` 里的 srs 会是 4978。
19
+ - 管线先 `pdal pipeline --validate` 再实跑,退出码 0 不能证明结果正确
20
+ - DEM 或点云渲染图用 `read_image` 看一眼,成品用 `present` 交付。
21
+ - **风险与权限**:`pdal translate` 与各 writer 按 `filename` 覆盖同名输出,先确认目标文件名、换名或备份
22
+ - `filters.outlier`、`filters.smrf` 需要全局统计、不能流式,大点云先按 tile 拆分。拉取 Docker 镜像、下载大点云、安装 PDAL、写用户目录外的路径前用 `ask_user_question` 让用户选方案
23
+ - 从源码编译时 GDAL 必须 3.8+(`cmake/gdal.cmake` 硬校验,报 `Required at least GDAL version 3.8`),SMRF 参数改动会影响地面分类结果,交付前说明用了哪组参数。
24
+ - **常见失败**:`Couldn't create <cls> stage of type '<type>'` 是 stage 名拼错或版本没有该 stage,先 `pdal --drivers` 确认
25
+ - `pipeline` 解析失败用 `--validate` 定位 JSON 语法与顶层结构
26
+ - `filters.reprojection` 报缺 SRS 补 `out_srs`(数据本身无坐标系时再给 `in_srs`)
27
+ - 重投影后精度变差在 writer 设 `scale_x/y/z` 与 `offset_x/y/z: "auto"`
28
+ - Python 侧 `execute()` 返回点数不是数组,数据在 `pipeline.arrays`,失败看 `pipeline.log`。
@@ -1,8 +1,22 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference 目录;验收判据集中在「典型工作流」的输出与验收、「性能优化」、「常见问题」三节,按标题定位再读。导入/导出链路的细节用 `skill` 加载 `gdal`,发布图层加载 `geoserver`,不要在本文件重写。SQL 大段结果先落文件再 `grep` 关键行,别把整份 `EXPLAIN` 贴进上下文。
4
- - **执行环境**:`psql`、`shp2pgsql`、`raster2pgsql`、`pgsql2shp`、`ogr2ogr` 都在 `ops_bash` 里跑。导入用管道 `shp2pgsql -s 4326 -I -W UTF-8 data/poi.shp public.poi | psql -d gisdb -v ON_ERROR_STOP=1`;元命令不能进交互式会话,单条传:`psql -d gisdb -c "\d+ poi"`。Windows 上没有这些 CLI 时改走 `ogr2ogr -f PostgreSQL "PG:host=localhost dbname=gisdb user=postgres"`,或用容器 `docker exec -i pg psql -U postgres`。整库导入、`VACUUM FULL`、大表 `CREATE INDEX` 放后台作业,用 `job_output` 收日志。
5
- - **先探测版本**:连上去先 `psql -c "SELECT version(), PostGIS_Full_Version();"` 一次拿到 PostgreSQL、PostGIS、GEOS、PROJ。正文按 PostGIS 3.7.0 编写(2026-10-30 发布),要求 PostgreSQL 14–19、GEOS ≥ 3.10、PROJ ≥ 6.1;3.6 及更早还能配 PostgreSQL 12+,升级前先确认 GEOS/PROJ 满足新下限。连不上先探服务端 `psql -h 127.0.0.1 -U postgres -c "SELECT 1"`,connection refused 是服务没起而非 SQL 写错;本机无实例时用 `docker run --name pg -e POSTGRES_PASSWORD=pg -p 5432:5432 -d postgis/postgis:17-3.7`。扩展缺失查 `SELECT * FROM pg_available_extensions WHERE name LIKE 'postgis%';`。
6
- - **验证产物**:导入后别只看 `INSERT 0 n`,回读 `SELECT count(*), ST_SRID(geom), ST_IsValid(geom) FROM t GROUP BY 2,3;`;空间连接按正文判据核对已匹配数与 `unmatched` 差值、`ST_SRID(geom)` 为 4326;性能结论必须附 `EXPLAIN (ANALYZE, BUFFERS)` 输出并指出计划里出现 `poi_geom_idx` 上的 Index/Bitmap Index Scan,没计划就直说未验证。导出后再 `ogrinfo -al -so out/poi_with_district.geojson` 核对要素数与字段;出图后用 `read_image` 看一眼,成品用 `present` 交付。
7
- - **风险与权限**:`DROP TABLE/SCHEMA`、整表 `UPDATE ... SET geom=`、`UpdateGeometrySRID`、`VACUUM FULL`、重启 PostgreSQL 都不可逆,执行前必须备份并向用户确认。连生产库、建库、删表、批量改写用 `ask_user_question` 给「只读查询/新建临时库/取消」选项;密码走 `PGPASSWORD`/`.pgpass`/环境变量,不写进命令行与回复。大表 `UPDATE`/`CREATE INDEX` 放可控事务避免长时间锁表,`CREATE INDEX CONCURRENTLY` 不能包在事务块里。`shp2pgsql -d` 会先删表,`-a` 是追加,别拿错。
8
- - **常见失败**:`Operation on mixed SRID geometries` 先用 `ST_SRID(geom)` 核对两侧、`ST_Transform` 统一;`Boundary geometry is invalid` 用 `ST_IsValidReason` 定位、`ST_MakeValid` 修复;`transform: Failed to transform` 查 `spatial_ref_sys` 与 PROJ 数据(`projinfo EPSG:<code>` 能否解析);`type "geometry" does not exist` 是扩展没装或 `search_path` 不对;查询慢先确认 GiST 索引存在且几何没被函数包裹导致索引失效。
3
+ - **加载与引用**:单文件技能,无 reference 目录
4
+ - 验收判据集中在「典型工作流」的输出与验收、「性能优化」、「常见问题」三节,按标题定位再读。导入/导出链路的细节用 `skill` 加载 `gdal`,发布图层加载 `geoserver`,不要在本文件重写。SQL 大段结果先落文件再 `grep` 关键行,别把整份 `EXPLAIN` 贴进上下文。
5
+ - **执行环境**:`psql`、`shp2pgsql`、`raster2pgsql`、`pgsql2shp`、`ogr2ogr` 都在 `ops_bash` 里跑。导入用管道 `shp2pgsql -s 4326 -I -W UTF-8 data/poi.shp public.poi | psql -d gisdb -v ON_ERROR_STOP=1`
6
+ - 元命令不能进交互式会话,单条传:`psql -d gisdb -c "\d+ poi"`。
7
+ - Windows 上没有这些 CLI 时改走 `ogr2ogr -f PostgreSQL "PG:host=localhost dbname=gisdb user=postgres"`,或用容器 `docker exec -i pg psql -U postgres`。
8
+ - 整库导入、`VACUUM FULL`、大表 `CREATE INDEX` 放后台作业,用 `job_output` 收日志
9
+ - **先探测版本**:连上去先 `psql -c "SELECT version(), PostGIS_Full_Version();"` 一次拿到 PostgreSQL、PostGIS、GEOS、PROJ。正文按 PostGIS 3.7.0 编写(2026-10-30 发布),要求 PostgreSQL 14–19、GEOS ≥ 3.10、PROJ ≥ 6.1
10
+ - 3.6 及更早还能配 PostgreSQL 12+,升级前先确认 GEOS/PROJ 满足新下限。连不上先探服务端 `psql -h 127.0.0.1 -U postgres -c "SELECT 1"`,connection refused 是服务没起而非 SQL 写错
11
+ - 本机无实例时用 `docker run --name pg -e POSTGRES_PASSWORD=pg -p 5432:5432 -d postgis/postgis:17-3.7`。扩展缺失查 `SELECT * FROM pg_available_extensions WHERE name LIKE 'postgis%';`。
12
+ - **验证产物**:导入后别只看 `INSERT 0 n`,回读 `SELECT count(*), ST_SRID(geom), ST_IsValid(geom) FROM t GROUP BY 2,3;`
13
+ - 空间连接按正文判据核对已匹配数与 `unmatched` 差值、`ST_SRID(geom)` 为 4326
14
+ - 性能结论必须附 `EXPLAIN (ANALYZE, BUFFERS)` 输出并指出计划里出现 `poi_geom_idx` 上的 Index/Bitmap Index Scan,没计划就直说未验证。导出后再 `ogrinfo -al -so out/poi_with_district.geojson` 核对要素数与字段
15
+ - 出图后用 `read_image` 看一眼,成品用 `present` 交付。
16
+ - **风险与权限**:`DROP TABLE/SCHEMA`、整表 `UPDATE ... SET geom=`、`UpdateGeometrySRID`、`VACUUM FULL`、重启 PostgreSQL 都不可逆,执行前必须备份并向用户确认。连生产库、建库、删表、批量改写用 `ask_user_question` 给「只读查询/新建临时库/取消」选项
17
+ - 密码走 `PGPASSWORD`/`.pgpass`/环境变量,不写进命令行与回复。大表 `UPDATE`/`CREATE INDEX` 放可控事务避免长时间锁表,`CREATE INDEX CONCURRENTLY` 不能包在事务块里。`shp2pgsql -d` 会先删表,`-a` 是追加,别拿错。
18
+ - **常见失败**:`Operation on mixed SRID geometries` 先用 `ST_SRID(geom)` 核对两侧、`ST_Transform` 统一
19
+ - `Boundary geometry is invalid` 用 `ST_IsValidReason` 定位、`ST_MakeValid` 修复
20
+ - `transform: Failed to transform` 查 `spatial_ref_sys` 与 PROJ 数据(`projinfo EPSG:<code>` 能否解析)
21
+ - `type "geometry" does not exist` 是扩展没装或 `search_path` 不对
22
+ - 查询慢先确认 GiST 索引存在且几何没被函数包裹导致索引失效。