dsh-map-tools

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

<p align="center">

<img src="assets/banner.svg" width="100%" alt="dsh-map-tools — Map & routing tools for DeepSeek Harness" />

</p>

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> 的<strong>地图与路径规划原生工具</strong>：驾车 / 公交 / 步行 / 骑行路线、地理编码、逆地理编码、POI 搜索。模型直接调用，<strong>不需要 MCP</strong>；算出来的路线会画成<strong>真地图卡片</strong>，出现在最终回答的下方。</p>

<p align="center">

<a href="https://www.npmjs.com/package/dsh-map-tools"><img src="https://img.shields.io/npm/v/dsh-map-tools?style=flat-square&label=npm&color=cb3837" alt="npm"></a>

<a href="https://www.npmjs.com/package/dsh-map-tools"><img src="https://img.shields.io/npm/dw/dsh-map-tools?style=flat-square&label=downloads&color=cb3837" alt="npm downloads"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>

<a href="https://github.com/HorusJiang/dsh-map-tools/actions/workflows/ci.yml"><img src="https://github.com/HorusJiang/dsh-map-tools/actions/workflows/ci.yml/badge.svg?style=flat-square" alt="CI"></a>

<a href="https://github.com/HorusJiang/dsh-map-tools/releases"><img src="https://img.shields.io/github/v/release/HorusJiang/dsh-map-tools?style=flat-square&label=release" alt="Release"></a>

<a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/dsh--plugin-%E5%8F%AF%E5%AE%89%E8%A3%85-2A6BE8?style=flat-square" alt="dsh-plugin"></a>

<a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://img.shields.io/badge/dshmarket-%E6%94%B6%E5%BD%95-22C55E?style=flat-square&logo=shopify&logoColor=white" alt="dshmarket"></a>

<img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js >= 20">

</p>

---

目录

• [这是什么](#这是什么)
• [效果长什么样](#效果长什么样)
• [安装](#安装)
• [快速开始](#快速开始)
• [工具参考](#工具参考)
• [配置](#配置)
• [数据源与降级](#数据源与降级)
• [已知限制](#已知限制)
• [架构](#架构)
• [FAQ](#faq)
• [开发](#开发)
• [发布](#发布)
• [安全](#安全)
• [贡献](#贡献)
• [许可](#许可)

这是什么

一句话：把「路怎么走」变成模型能直接调用的 7 个工具，并把结果画成看得见的地图。

• 7 个原生工具（map_*）：路线规划（驾车 / 公交 / 步行 / 骑行）、地理编码、逆地理编码、POI 搜索。走 DSH 的 ctx.tools 注册，不是 MCP，没有额外进程。
• 路线画在真地图上：每轮回答的收尾正文之后会出现一张真地图——高德底图 + 高德绘制的路线折线 + 起终标注，配距离、耗时、步数与「在高德打开」深链。一轮里算了几条就画几条（每条标注「第 k/N 条」），不会再出现「正文讲 A、地图画 B」。
• 零 key 也能用：不配置 key 时，驾车 / 步行 / 骑行走免费 OSM/OSRM；中文地址解析不可靠时给出明确引导；配置高德 key 后无缝升级到全能力。
• key 不出服务端：静态地图由宿主携带 key 去取，浏览器只加载一张本地图片；key 永不回显到页面或日志。
• 卡片数据不占 token：路线几何等卡片专用数据不进模型上下文。
• 开箱即用的配置卡片：侧边栏「插件」页 → dsh-map-tools，bundle 详情页里就是配置区——选数据源、填 key（脱敏）、改超时，保存即生效，无需重启。（更老的宿主没有这个座位，卡片仍出现在 设置 → 插件 → dsh-map-tools。）
• 与模型 / 提供方无关：插件只提供工具与卡片，不读模型名、不分模型版本，换任何 DSH 支持的模型/提供方行为一致。

效果长什么样

<p align="center">

<img src="assets/card-turn-tail.png" width="100%" alt="回合尾部的路线地图卡：高德真地图 + 路线折线 + 起终点标注 + 距离/耗时/步数 + 「在高德打开」深链" />

</p>

<p align="center">_{实机截图：收尾正文下方的路线地图卡（驾车 10.8 公里 / 约 20 分钟 / 共 12 步，蓝色折线是高德绘制的真实路线）。}</p>

一次路线问答里，界面会出现三处内容：

位置 · 内容 · 说明

过程区（「思考」块） · 紧凑摘要 + 可折叠路书 · 不渲染地图——过程区会随思考反复重绘，地图只在最终结果处出现一次（也省掉一次取图）

收尾正文 · 距离、耗时、分段指引、「在高德打开 ↗」 · 模型可见文本，模型据此作答

收尾正文之后（回合尾部） · 路线地图卡：真地图 + 起终点 + 距离/耗时/步数 + 深链 · 本轮每条路线一张，多条时标注「第 k/N 条」；超过 3 条只显示前 3 条并注明总数

卡片的四种形态（都不会「空白」）：

• 运行中：显示「规划中…」。
• 成功 + 有几何：真地图（高德静态图）。
• 成功但取不到真地图（未配 key / 配额超限 / 宿主没有该路由）：自动退回自绘 SVG 示意图——不请求外部网络、不需要前端 key，路线走向、起终点、距离耗时照常显示。
• 失败：显示错误文本，不会被吞掉。

回合尾部是 DSH 客户端的单选席位：本轮有路线时地图卡占用这一行，官方的「本轮产出文件」行本轮不渲染——卡片里会注明「本轮另有 N 个产出文件（地图卡占用此行，文件见过程区）」。

卡片上的署名接在「在高德打开 ↗」同一行的后面（本卡片由 DeepSeek Harness 插件 dsh-map-tools 生成 · GitHub ↗；整卡只出现一次，挂在最后一条路线上）：地图卡经常被截图转发，而那张图里没有 README、也没有包页——这行字是图里唯一能说明"它是谁画的"的信息。它由浏览器半边直接渲染，不进模型上下文、不占 token。

安装

方式一：桌面版插件页安装（DeepSeek Harness Desktop，推荐）

桌面版的插件管理界面可以直接按包名安装，不必碰命令行：

1. 侧边栏打开 「插件」页 → 右上角 「添加插件」。

2. 在 「包名或地址」 里填 dsh-map-tools；右侧 「安装源」 用默认即可（国内网络可切 「中国大陆镜像源」）。

3. 界面会去该 npm 源查询这个包并显示名称与版本，确认无误后点 「安装」；结束时可以点 「立即启用」，否则按提示 「更改将在下次启动生效」。

4. 重启 DeepSeek Harness Desktop，在会话里即可使用 map_* 工具。

它装到哪个 profile：桌面版写进 desktop profile（~/.dsh/profiles/desktop），依赖会写成 dsh-map-tools ^0.7.1 这样的 caret 区间——0.x 下 caret 不会升到 0.8.x，升级时在同一个输入框里填目标版本（形如 dsh-map-tools@^0.8.0，0.8 换成你要升到的那条 minor）重新安装即可。

同一个输入框也接受 GitHub 地址（https://github.com/HorusJiang/dsh-map-tools）与 本机插件目录的绝对路径，源码安装 / 本地开发都能走这个界面。

方式二：从 npm 安装（命令行，预构建）

dsh plugin --profile web add dsh-map-tools        # Web / CLI 版
dsh plugin --profile desktop add dsh-map-tools    # 桌面版（profile 名 desktop）

方式三：从 GitHub 安装（源码构建）

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

发布包不含 prepare / postinstall 构建脚本，pnpm ≥10 安装时无需放行构建脚本，也不必配置 allowBuilds。

版本要求

• DeepSeek Harness ≥ 0.1.2-rc.1（peer 依赖：@deepseek-ai/dsh-settings、@deepseek-ai/dsh-tools、@deepseek-ai/cordis ^4.0.2）。更早的发布线因 @deepseek-ai/dsh-settings 移除旧 API 而不再支持。
• 已在 DSH 0.1.6-alpha.2 / 0.1.6-alpha.1 + Node v24 实测全部功能；已兼容版本记录在 package.json 的 dsh.compatibility.dshReleases。
• 桌面版同样可用：DeepSeek Harness Desktop（DSH 0.1.7-rc.2） 上，插件页安装（desktop profile）与回合尾部的地图卡片都正常工作——该版本的 conversation.chat.turnTail 仍声明为 list，与插件注册的形状一致。
• 插件不写死宿主版本号：客户端卡片按槽位实际声明适配。conversation.chat.turnTail 在 0.1.6-alpha.2 由链式（chain，要 select）改成列表式（list，要 id），插件运行时读 slots.spec() 决定注册形状，因此同一份构建在两条发布线上都能让回合尾部的路线卡片正常出现（详见 [docs/dsh-map-tools-0.1.6兼容性说明.md](docs/dsh-map-tools-0.1.6兼容性说明.md)）。
• Node ≥ 20。
• 路线地图卡与配置页需要 Web 客户端（dsh.client.platform: web：dsh web 与 DeepSeek Harness Desktop 都属于这一类）。TUI / headless 下 7 个工具照常可用，只是没有图形卡片。

安装后重启客户端：命令行版重启 dsh web（或在启动器里按 R），桌面版重启 DeepSeek Harness Desktop。之后在会话中即可使用 map_* 工具。

升级 / 卸载 / 查看

dsh plugin --profile web list                        # 查看已装版本
dsh plugin --profile web add dsh-map-tools@^0.7.0    # 升级
dsh plugin --profile web remove dsh-map

…(truncated)