dsh-map-tools

<p align="center"><a href="README.en.md">English</a> | 中文</p> <p align="center">地图与路径规划工具插件，为 <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> 提供驾车/公交/步行/骑行路线规划、地理编码、逆地理编码和 POI 搜索等<strong>原生工具</strong>——模型可直接调用，无需 MCP 服务器。</p>

---

特性

• 7 个原生工具：路线规划（驾车/公交/步行/骑行）、地理编码、逆地理编码、POI 搜索——模型通过 map_* 直接调用，无需 MCP。
• 高德数据源（推荐）：配置免费的高德 Web 服务 key 后，使用国内最全的地图数据（含公交换乘、POI、稳定的中文地理编码）。
• 零 key 兜底：不配置 key 时，驾车/步行/骑行路线自动走免费的 OSM/OSRM；中文地址解析不可靠时给出清晰引导。
• 开箱即用的配置卡片：设置 → 插件 → dsh-map-tools，图形化配置，内置"如何获取高德 Key？"申请链接，保存即生效（无需重启）。
• 面向国内网络：免费源不可达、key 无效等场景均有清晰的中文提示与补救路径。

安装

支持两种安装方式，二选一：

方式一：npm 安装（推荐，预构建免授权）

dsh plugin --profile web add dsh-map-tools

方式二：从 GitHub 安装（源码构建，需授权）

dsh plugin --profile web add github:HorusJiang/dsh-map-tools

pnpm ≥10 会要求你显式允许该包的构建脚本（prepare），按提示把包 key 加入该 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试即可。

安装后重启 dsh web（或等待 HMR 热加载），在会话中即可使用 map_* 工具。

开发模式：在本地 clone 后使用 dsh plugin add <本地路径> 会以 link: 方式安装——改动源码即生效，适合插件迭代。

快速开始

配置高德 key（约 2 分钟）：

1. 打开 高德开放平台 → 创建应用 → 申请 "Web 服务" 类型 key（个人开发者免费）。
2. 在 DSH 的 设置 → 插件 → dsh-map-tools 填入 key，选择数据源 amap，保存。
3. 在会话中直接提问：

从北京南站到首都机场T3，规划驾车路线
把"西湖区文三路478号"转成经纬度
116.397428,39.90923 附近 1 公里内有什么加油站？

工具

工具	功能	免费 OSM	高德
map_driving_route	驾车路线规划	✅	✅
map_transit_route	公交/地铁换乘	—	✅
map_walking_route	步行路线规划	✅	✅
map_bicycling_route	骑行路线规划	✅	✅
map_geocode	地址 → 经纬度	中文不可靠	✅
map_reverse_geocode	经纬度 → 地址	中文不可靠	✅
map_poi_search	兴趣点搜索	—	✅

起点/终点统一接受 地址文本 或 "lng,lat" 坐标 两种形式，插件自动归一化。

配置

设置页配置卡片（推荐）

DSH 的 设置 → 插件 → dsh-map-tools 提供图形化卡片：数据源选择、高德 key 输入（脱敏显示）、超时设置、申请链接。保存后立即生效。

配置实际存储于 ~/.dsh-map-tools/config.json（用户目录，权限 0600），与 DSH 设置文档解耦，跨 profile 共享：

// ~/.dsh-map-tools/config.json
{
  "provider": "amap",        // "amap" | "osm"
  "amapKey": "你的高德Web服务key",
  "timeoutMs": 15000
}

key 只以布尔标记（hasAmapKey）呈现给前端，永远不会回显到页面或日志。

cordis.yml 默认值

也可以在 profile 的 cordis.yml 中提供默认值（配置文件中的值优先于 cordis.yml）：

- id: map-tools
  name: dsh-map-tools
  config:
    provider: amap

架构

┌─ 模型 ──────────────────────────────────────┐
│  map_driving_route / map_geocode / ...       │  7 个原生工具（ctx.tools）
└──────────────┬───────────────────────────────┘
               │
┌──────────────▼───────────────────────────────┐
│  src/tools/    工具定义（参数校验/输出渲染）     │
│  src/clients/  数据源客户端                    │
│    amap.ts      高德 Web 服务 API（推荐）      │
│    osrm.ts      OSRM 免费路线（兜底）           │
│    photon.ts    Photon 免费地理编码（兜底）     │
│    nominatim.ts Nominatim 免费地理编码（兜底）   │
└──────────────┬───────────────────────────────┘
               │
┌──────────────▼───────────────────────────────┐
│  src/config-file.ts  ~/.dsh-map-tools/config.json（0600） │
│  src/config-route.ts 回环路由 /dsh-map-tools/config     │
│  src/settings-ns.ts   设置页 namespace 注册              │
│  client/client.js     设置页配置卡片（前端，手写零依赖）    │
└──────────────────────────────────────────────┘

• 配置优先级：配置文件（设置卡片写入）→ cordis.yml 默认值。
• 保存即生效：配置变更后工具自动重建，无需重启。
• 无 MCP：全部能力为原生工具，不依赖外部 MCP 服务器进程。

数据源

…