dsh-geolibre

DeepSeek Harness (DSH) plugin — 把 GeoLibre 地图能力接入 Web GUI，并让 Agent 可以实时操作「地图」tab 里的交互地图：渲染 GeoJSON、管理图层/样式/视图、运行 GeoLibre 处理算法与 Whitebox 工具箱（浏览器内 WASM 执行）。

Render GeoJSON into an interactive GeoLibre map inside the DSH Web GUI, and let agents operate the live map in the "地图" (Map) sidebar tab — layers, styles, view, GeoLibre processing algorithms and the Whitebox toolbox (executed by WASM in the browser).

功能总览 / Features

• 宿主侧 agent 工具（Host agent tools）
  • geolibre_render_map — 渲染 GeoJSON 数据（文本 / 本地文件 / URL）为地图并同步到会话工程
  • geolibre_map_status — 查看实时地图会话：图层清单、可见性、视图、连接状态
  • geolibre_map_run — 向已就绪的实时地图发送命令并等待结果： getView / getCenter / getBounds / flyTo / fitBounds / zoomToLayer / identify / getLayerFeatures / getSelectedFeatures / getDrawnFeatures / listAlgorithms / runAlgorithm / runModelBuilder / listWhiteboxTools / runWhiteboxTool / toImage …
  • geolibre_map_update — 整体替换工程、追加 GeoJSON 图层、删除 / 改名 / 显隐 / 改样式图层、移动视图（view / data+style / layer / removeLayer / project）
• 浏览器侧（client）：注册「地图」侧边栏 tab，内嵌 GeoLibre 应用并充当 host ↔ iframe 的双向中继（geolibre:load-project / geolibre:command / state / result / event）
• 同源本地托管 GeoLibre Web App（/dsh-geolibre/app/*），无需外部 CDN

依赖要求 / Requirements

• Node.js >= 20，运行在 DSH（Web 形态，profile 内注册）
• Python 3（python 可执行文件，可配置 python），且该解释器可 import geolibre（pip install geolibre）—— geolibre Python 包同时提供图层构造辅助与其内置的 GeoLibre Web App 静态资源

安装 / Installation

在目标 DSH profile 的 package.json 中声明依赖并把本包加入 dsh.profile.bundles：

{
  "dependencies": { "dsh-geolibre": "0.1.0" },
  "dsh": { "profile": { "bundles": ["…", "dsh-geolibre"] } }
}

插件配置（在 profile 的 cordis.patch.yml 中按 entry id 覆盖）：

# 仅当 python 无法直接 import geolibre 时需要显式指定
- id: geolibre
  config:
    geolibreEnv: "D:/path/to/geolibre_env"   # 留空则自动探测（推荐）
    python: "python"                          # 默认
    # outputDir: ""                           # 地图产物目录，默认 <工作区>/.geolibre-maps
    # appRoot: ""                             # GeoLibre app 静态目录，默认 <geolibreEnv>/geolibre/static/app
    # theme: "light"

说明：geolibreEnv 留空时插件会运行 python -c "import geolibre" 自动定位其安装目录（作为 PYTHONPATH 前缀）。显式设置则跳过探测。

使用示例 / Usage examples

Agent（模型）在工作区直接调用工具即可：

用户：把北京、上海、广州、成都四个点画到地图上。
→ geolibre_render_map(data=<GeoJSON>, name="cities", center="112,32", zoom=4)

用户：对 sample-points 做 100km 缓冲。
→ geolibre_map_run(method="listAlgorithms")        # 发现 buffer 算法
→ geolibre_map_run(method="runAlgorithm", params={"id":"buffer","params":{"layer":"<图层id>","distance":100,"units":"kilometers"}})

用户：把所有省会城市显示出来。
→ geolibre_map_update(data=<34 城市 GeoJSON>, name="cities", style={...})

用户：把地图移到上海。
→ geolibre_map_update(view={center:"121.5,31.2", zoom:8})

「地图」tab 顶部的 刷新 按钮会重新挂载 iframe 并载入 host 当前工程；工程/图层状态以 host 进程内的会话工程为单一事实来源，应用侧改动（用户交互、算法结果图层）会通过 geolibre:state 回写。

架构 / Architecture

Agent 工具 (host, Node)
   │  ops 队列（id 数字键）
   ▼  同源 HTTP：/dsh-geolibre/ops · /result · /state · /project · /status
「地图」tab 控制器页 (lib/map-page.html) —— 轮询 op、回传 result/state
   │  window.postMessage（geolibre:load-project / geolibre:command / result / ready / state）
   ▼
GeoLibre Web App iframe（本地静态托管于 /dsh-geolibre/app/，含 Whitebox WASM）

• 每次渲染 / 更新会整体推送 .geolibre.json 工程对象（图层、样式、视图），与 geolibre Python 包 Map 使用的协议一致。
• runAlgorithm / runWhiteboxTool 等命令在浏览器端由应用执行（算法 / Whitebox WASM），结果经 geolibre:result 返回并在应用侧新增图层。

开发 / Development

npm install           # 安装 dev 依赖
npm test              # 冒烟测试（纯 Node 检查 + 可选 python byte-compile）
npm run prepack       # 发布前语法检查

目录：

路径	说明
lib/index.js	host 插件：工具、会话、HTTP API、静态托管
lib/map-page.html	「地图」tab 控制器页（iframe 中继）
client/client.js	浏览器侧 tab 注册（client module）
scripts/render.py	渲染 GeoJSON → 独立 HTML + project JSON（复用 geolibre Python 包）
scripts/ops.py	服务端工程编辑（create / add-layer / set-layer / remove-layer / set-view）
cordis.patch.yml	DSH bundle 层：注册插件 entry（id geolibre）
test/smoke.mjs	冒烟测试

注意：本仓库工作区内的演示工程（.geolibre-maps/）与控制器会话是运行期产物，不随包发布。

许可 / License

MIT — see LICENSE。