配置

bundle 配置页（推荐）

DSH 的侧边栏「插件」页 → dsh-map-tools 打开 bundle 详情页，描述与行列表之间就是本插件的配置区：顶部一行状态（数据源 · key 状态）、数据源选择、高德 key 输入（脱敏，留空表示保持不变）、请求超时，并内置「如何获取高德 Key？」申请链接和「打开配置文件」。保存后插件重建工具实例，立即生效。

这一区渲染在宿主的 plugins.bundle.config 座位上（key = 包名 dsh-map-tools），页面骨架（标题、包名、描述、开关、卸载）由宿主自己画，插件只画内容。更老的宿主（DSH ≤ 0.1.5，没有这个座位）自动回落到 设置 → 插件 → dsh-map-tools，卡片内容完全一样。

配置区的行为约定与官方配置页一致：改动先暂存、点保存才落盘（屏幕上看到的就是保存会写下的），离开页面即丢弃（所以没有「取消」按钮），非法超时会拦住保存而不是被悄悄改写成默认值，保存后以宿主返回的值重新播种（key 输入框随之为空）。

配置文件

配置实际存储在 ~/.dsh-map-tools/config.json（权限 0600），与 DSH 设置文档解耦、跨 profile 共享。路径可用 DSH_MAP_TOOLS_CONFIG 环境变量覆盖。

// ~/.dsh-map-tools/config.json
{
  "provider": "amap",     // "amap" | "osm"
  "amapKey": "……",        // 高德「Web 服务」key（secret，永不回显）
  "timeoutMs": 15000,
  "maxQps": 2,            // 高德每秒请求上限
  "defaultMode": "driving",
  "language": "zh"
}

键	默认	配置页可改	说明
`provider`	`amap`	✅	`amap` = 高德（推荐，国内数据最全）；`osm` = 免费 OSM 兜底（无需 key，能力有限）
`amapKey`	—	✅	高德 Web 服务类型 key，免费申请
`timeoutMs`	`15000`	✅	单次请求超时（毫秒）
`maxQps`	`2`	手改 JSON	高德每秒最大请求数（默认 2 低于常见上限 3，防触发 `10021` 配额错误）
`defaultMode`	`driving`	手改 JSON	默认路线模式（`driving` / `transit` / `walking` / `bicycling`）
`language`	`zh`	手改 JSON	返回语言（`zh` / `en`）

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

cordis.yml 默认值

也可以在 profile 的 cordis.yml 里给默认值：

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

优先级：配置文件（配置页写入）> cordis.yml 默认值。

回环路由（进阶）

配置卡片走插件的同源回环路由，不直接写 DSH 设置：

路由	用途
`GET /dsh-map-tools/config`	返回非敏感摘要（`provider`、`hasAmapKey`、`timeoutMs` …）
`GET /dsh-map-tools/config?open=true`	在编辑器中打开配置文件
`POST /dsh-map-tools/config`	应用 `provider` / `amapKey` / `timeoutMs` 补丁并重建工具
`GET /dsh-map-tools/staticmap?w=&h=&line=`	取静态地图 PNG（同源校验、按参数缓存、连接关闭即取消上游请求）

静态地图由宿主取回，浏览器只拿到一张本地图片——这也是不把图片塞进工具结果的原因：既不进模型上下文，也不必往附件仓库写字节。

bundle 配置页（推荐）

配置文件

配置实际存储在 ~/.dsh-map-tools/config.json（权限 0600），与 DSH 设置文档解耦、跨 profile 共享。路径可用 DSH_MAP_TOOLS_CONFIG 环境变量覆盖。

// ~/.dsh-map-tools/config.json
{
  "provider": "amap",     // "amap" | "osm"
  "amapKey": "……",        // 高德「Web 服务」key（secret，永不回显）
  "timeoutMs": 15000,
  "maxQps": 2,            // 高德每秒请求上限
  "defaultMode": "driving",
  "language": "zh"
}

键	默认	配置页可改	说明
`provider`	`amap`	✅	`amap` = 高德（推荐，国内数据最全）；`osm` = 免费 OSM 兜底（无需 key，能力有限）
`amapKey`	—	✅	高德 Web 服务类型 key，免费申请
`timeoutMs`	`15000`	✅	单次请求超时（毫秒）
`maxQps`	`2`	手改 JSON	高德每秒最大请求数（默认 2 低于常见上限 3，防触发 `10021` 配额错误）
`defaultMode`	`driving`	手改 JSON	默认路线模式（`driving` / `transit` / `walking` / `bicycling`）
`language`	`zh`	手改 JSON	返回语言（`zh` / `en`）

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

dsh-map-tools

安裝

說明文件

配置

bundle 配置页（推荐）

配置文件

cordis.yml 默认值

回环路由（进阶）

bundle 配置页（推荐）

配置文件