dsh-geolibre

Readme

# dsh-geolibre

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin — 把 [GeoLibre](https://geolibre.app/) 地图能力接入 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`：

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

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

```yaml
# 仅当 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（模型）在工作区直接调用工具即可：

```text
用户：把北京、上海、广州、成都四个点画到地图上。
→ 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

```bash
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](./LICENSE)。