@danceiny/gotry 0.0.1-rc.19 → 0.0.1-rc.21

package/ts/capabilities/anything.ts

@@ -3,10 +3,17 @@
  *
  * 链路(同构 hbcli.ts):
  *   gotry capabilities/anything.ts
- *     → spawn hbcli search anything [keywords...] --json <opts>
- *       → hotel-be /api/search/anything
+ *     → spawn hbcli --json search anything <kw> [opts]
+ *       → hotel-be /api/search/anything(httpdispatch 自动注册;httpdispatch 路由面)
  *         → search/service/geography.go func Anything (mixed 城市+酒店搜索)
  *
+ * wire 契约(2026-09-07 对齐上游源码;SearchItem = FuzzySearchItem + hotel):
+ *   req  { keyword, contentType?, context.destinationId?, minHotelCount? }
+ *   resp { candidates: [{ type: 'city'|'place'|'hotel',
+ *                         region?:  { id, name:{en,zh,ar}, coordinates:{centerLat,centerLng}, countryCode, … },
+ *                         place?:   { latlngCoordinator },
+ *                         matchScore?, hotel?: { id, name:{en,zh,ar}, star, latlngCoordinator:{google|gaode:{lat,lng} } } }] }
+ *
  * 三值语义:
  *   - hit:  命中候选(混合 city/hotel,maybe-coords)
  *   - miss: hbcli exit 0,但 candidates 为空(查无结果)
@@ -22,33 +29,36 @@
  */
 
 import { spawn } from 'node:child_process'
+import { hbcliBinCandidates } from './hbcli.ts'
 
 export interface AnythingQuery {
   /** 多词以空格 join,与 hbcli argument-parser 一致;前后 trim。空则报错(unless contentType 强限定) */
   keyword: string
   /** 'city' | 'hotel' | undefined(混合) */
   contentType?: 'city' | 'hotel'
-  /** 限定子区域 ID(可选) */
+  /** 限定子区域 ID(上游 SearchReq.context.destinationId) */
   parentDestinationId?: string | number
   /** 默认 12_000 ms */
   timeoutMs?: number
-  /** 显式 hbcli 路径(默认 'hbcli',从 $PATH 找) */
+  /** 显式 hbcli 路径(默认 'hbcli',从 $PATH 找;默认名自动回退 ~/.local/bin 等已知安装位) */
   hbcliBin?: string
 }
 
 export interface AnythingHit {
   type: 'city' | 'hotel' | 'place'
-  /** FuzzySearchItem name(or hotel name);fallback 为 region.Name */
+  /** i18n name 解析(zh 优先,产品中文优先;回退 en/ar) */
   name: string
-  /** score / 0..1(若返回) */
+  /** matchScore(文本相关度,越高越匹配) */
   score?: number
-  /** lat/lng(若 region 给出) */
+  /** lat/lng(region.center 或 hotel/place latlngCoordinator,若给出) */
   latitude?: number
   longitude?: number
-  /** city id(若有) */
+  /** city id(region.id;酒店候选为所属 destinationId) */
   destinationId?: string
   /** hotel id(若有) */
   hotelId?: string
+  /** 星级(酒店候选,若返回) */
+  star?: number
 }
 
 export interface AnythingResult {
@@ -63,16 +73,46 @@ export interface AnythingResult {
   error?: string
 }
 
+/** 上游 i18n.I18N {en,zh,ar};tolerant 读取(字段可能缺省,老字符串形态也兜住) */
+type I18N = { en?: string; zh?: string; ar?: string } | string | undefined
+
+function i18nText(v: I18N): string {
+  if (!v) return ''
+  if (typeof v === 'string') return v
+  return v.zh || v.en || v.ar || ''
+}
+
+/** hotel-be Latlng:{lat,lng};google/gaode 双源取先非零者 */
+function latlngOf(coord: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } } | undefined): { latitude?: number; longitude?: number } {
+  for (const src of [coord?.google, coord?.gaode]) {
+    const lat = typeof src?.lat === 'number' ? src.lat : undefined
+    const lng = typeof src?.lng === 'number' ? src.lng : undefined
+    if (lat !== undefined && lng !== undefined && (lat !== 0 || lng !== 0)) return { latitude: lat, longitude: lng }
+  }
+  return {}
+}
+
 interface RawSearchResp {
   candidates?: RawSearchItem[]
 }
+/** hotel-be SearchItem wire 形状(FuzzySearchItem + hotel,2026-09-07 对齐源码) */
 interface RawSearchItem {
   type?: string
-  name?: string
-  label?: string
-  region?: { id?: string; name?: string; latitude?: number; longitude?: number; typeScore?: number; name_en?: string; name_zh?: string }
-  hotel?: { id?: string; name?: string; latitude?: number; longitude?: number }
-  score?: number
+  matchScore?: number
+  region?: {
+    id?: string | number
+    name?: I18N
+    countryCode?: string
+    coordinates?: { centerLat?: number; centerLng?: number }
+  }
+  place?: { latlngCoordinator?: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } } }
+  hotel?: {
+    id?: string | number
+    name?: I18N
+    star?: number
+    destinationId?: string | number
+    latlngCoordinator?: { google?: { lat?: number; lng?: number }; gaode?: { lat?: number; lng?: number } }
+  }
 }
 
 function sh(cmd: string, args: string[], opts: { timeoutMs: number; env: NodeJS.ProcessEnv }) {
@@ -115,8 +155,20 @@ function sh(cmd: string, args: string[], opts: { timeoutMs: number; env: NodeJS.
   })
 }
 
-const upperFirst = (s: string): string => (s ? s[0]!.toUpperCase() + s.slice(1) : s)
-const lowerFirst = (s: string): string => (s ? s[0]!.toLowerCase() + s.slice(1) : s)
+/** --json 必须在子命令前(cli.ts 全局旗标预扫描只认子命令前位置;JSON 错误也走结构化 stderr) */
+function buildArgs(keyword: string, q: AnythingQuery): string[] {
+  const args = ['--json', 'search', 'anything', keyword]
+  if (q.contentType) args.push('--content-type', q.contentType)
+  if (q.parentDestinationId !== undefined) args.push('--destination-id', String(q.parentDestinationId))
+  return args
+}
+
+/** 旧版 CLI 无 search anything 子命令时的可行动升级指引(issue #195:裸 unknown command 读起来像工具坏了) */
+function upgradeHint(stderr: string): string | null {
+  return /unknown command/i.test(stderr)
+    ? 'hbcli 版本过旧(无 search anything 子命令)——请升级:hbcli update,或重跑 npx gotry setup'
+    : null
+}
 
 /** Anything 通用搜索 — 任何搜索失败走降级;不抛错 */
 export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult> {
@@ -131,27 +183,25 @@ export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult>
       error: 'keyword is required',
     }
   }
-  const bin = q.hbcliBin ?? 'hbcli'
-  const args = [bin, 'search', 'anything', kw]
-  if (q.contentType) args.push('--content-type', q.contentType)
-  if (q.parentDestinationId !== undefined) {
-    args.push('--parent-destination-id', String(q.parentDestinationId))
+  const args = buildArgs(kw, q)
+  // spawn 级失败(ENOENT)按已知安装位回退(hbcli.ts callHbcliJson 同款);其余失败无重试意义
+  const candidates = hbcliBinCandidates(q.hbcliBin ?? 'hbcli')
+  let r: { code: number; stdout: string; stderr: string; error?: string } = { code: -1, stdout: '', stderr: '' }
+  for (let i = 0; i < candidates.length; i++) {
+    r = await sh(candidates[i]!, args, { timeoutMs: q.timeoutMs ?? 12_000, env: process.env })
+    if (!(r.error && i < candidates.length - 1)) break
   }
-
-  const r = await sh(bin, args.slice(1), {
-    timeoutMs: q.timeoutMs ?? 12_000,
-    env: process.env,
-  })
   const latencyMs = Date.now() - started
 
   if (r.error || r.code !== 0) {
+    const raw = r.error ?? `${r.stderr.slice(0, 200)} (exit ${r.code})`
     return {
       ok: false,
       via: 'hbcli-anything-error',
-      evidence: `[实时API:hbcli-anything@error@${ts}] ${r.error ?? `exit ${r.code}`}`,
+      evidence: `[实时API:hbcli-anything@error@${ts}] ${raw}`,
       latencyMs,
       verdict: 'error',
-      error: r.error ?? `${r.stderr.slice(0, 200)} (exit ${r.code})`,
+      error: upgradeHint(r.stderr) ?? raw,
     }
   }
 
@@ -174,15 +224,19 @@ export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult>
   const hits: AnythingHit[] = rawItems.map((it) => {
     const region = it.region ?? {}
     const hotel = it.hotel ?? {}
-    const isHotel = it.type === 'hotel' || it.type === 'SupplierHotelList' || Boolean(hotel.id)
+    const isHotel = it.type === 'hotel' || Boolean(hotel.id)
+    const hotelCoords = latlngOf(hotel.latlngCoordinator)
+    const placeCoords = latlngOf(it.place?.latlngCoordinator)
+    const center = region.coordinates ?? {}
     return {
-      type: (isHotel ? 'hotel' : (it.type === 'place' || it.type === 'City' ? lowerFirst(it.type) : 'city')) as AnythingHit['type'],
-      name: it.name ?? region.name_en ?? region.name ?? hotel.name ?? '?',
-      score: it.score ?? region.typeScore,
-      latitude: hotel.latitude ?? region.latitude,
-      longitude: hotel.longitude ?? region.longitude,
-      destinationId: region.id,
-      hotelId: hotel.id,
+      type: (isHotel ? 'hotel' : (it.type === 'place' ? 'place' : 'city')) as AnythingHit['type'],
+      name: i18nText(hotel.name) || i18nText(region.name) || '?',
+      score: it.matchScore,
+      latitude: hotelCoords.latitude ?? placeCoords.latitude ?? (typeof center.centerLat === 'number' ? center.centerLat : undefined),
+      longitude: hotelCoords.longitude ?? placeCoords.longitude ?? (typeof center.centerLng === 'number' ? center.centerLng : undefined),
+      destinationId: hotel.destinationId !== undefined ? String(hotel.destinationId) : (region.id !== undefined ? String(region.id) : undefined),
+      hotelId: hotel.id !== undefined ? String(hotel.id) : undefined,
+      star: typeof hotel.star === 'number' && hotel.star > 0 ? hotel.star : undefined,
     }
   })
 
@@ -196,6 +250,3 @@ export async function anythingSearch(q: AnythingQuery): Promise<AnythingResult>
     totalCandidates: rawItems.length,
   }
 }
-
-// noop exports to keep file shape consistent with hbcli.ts
-export const _ = { upperFirst }

package/ts/capabilities/hbcli.ts

@@ -142,19 +142,66 @@ export async function callHbcliJson(
   return last!
 }
 
+/** 上游 i18n 名称容错读取(zh 优先,中文优先产品口径;回退 en/ar) */
+function i18nName(v: { zh?: string; en?: string; ar?: string } | string | undefined): string {
+  if (!v) return ''
+  if (typeof v === 'string') return v
+  return v.zh || v.en || v.ar || ''
+}
+
+/**
+ * 实时 hotelList 响应 → 模型可读紧凑行(id/名称/星级/最低价)。
+ * issue #195:render 面只透 summary,若 summary 不含数据,模型只看到
+ * 「实时返回」四个字——工具调用等于白调。id 必须在行内,hotel-rates 的入参
+ * 就来自这里。上游 wire:HotelListResp{list:[Hotel{id,name:{en,zh},star,minPrice:{amount,currency}}]}。
+ */
+function hotelLines(result: unknown, max = 8): string {
+  const list = (result as { list?: unknown } | null)?.list
+  if (!Array.isArray(list) || list.length === 0) return ''
+  const lines: string[] = []
+  for (const item of list.slice(0, max)) {
+    const h = item as {
+      id?: string | number
+      name?: { zh?: string; en?: string; ar?: string }
+      star?: number
+      minPrice?: { amount?: number; currency?: string }
+    }
+    const name = i18nName(h.name) || `hotel ${h.id ?? '?'}`
+    const star = typeof h.star === 'number' && h.star > 0 ? ` ${h.star}★` : ''
+    const price = h.minPrice && typeof h.minPrice.amount === 'number'
+      ? ` 低至 ${h.minPrice.amount}${h.minPrice.currency ? ` ${h.minPrice.currency}` : ''}`
+      : ''
+    lines.push(`- id=${h.id ?? '?'} ${name}${star}${price}`)
+  }
+  if (list.length > max) lines.push(`…(共 ${list.length} 家,仅列前 ${max})`)
+  return lines.join('\n')
+}
+
 /** 高层语义化封装:酒店列表查询(down-tier to 静态包 + 证据链标注) */
 export async function searchHotels(
   query: { destination: string; checkIn?: string; checkOut?: string; adults?: number },
   opts: HbcliCallOptions & { fallbackPath?: string } = {},
 ): Promise<HbcliCallResult & { hotels?: unknown; summary: string }> {
-  // 旗标对齐上游 CLI v0.3.0(命令树扁平化后):--destination-name + --room-occupancies;
-  // hotel-list 无日期旗标(房价按上游当前窗口),checkIn/checkOut 留给 hotel-rates 跟进
+  // 旗标对齐上游 CLI(hotelbyte-com/hotelbyte-cli):--destination-name + --room-occupancies;
+  // hotel-list 支持日期旗标(--check-in/--check-out,上游帮助文档在册)——issue #195 教训:
+  // 「日期不传上游」会让实时价退化为当前窗口价,用户要下周五的房给的是今天的价。
   const hbArgs = ['search', 'hotel-list', '--json', '--page-size', '10']
   if (query.destination) hbArgs.push('--destination-name', query.destination)
+  if (query.checkIn) hbArgs.push('--check-in', query.checkIn)
+  if (query.checkOut) hbArgs.push('--check-out', query.checkOut)
   if (query.adults) hbArgs.push('--room-occupancies', JSON.stringify([{ adultCount: query.adults, childrenAges: [] }]))
   const live = await callHbcliJson(hbArgs, opts)
   if (live.via === 'hbcli-realtime') {
-    return { ...live, hotels: live.result, summary: `${query.destination}:hbcli 实时返回${query.checkIn || query.checkOut ? '(日期不传上游 list,以当前窗口房价返回)' : ''}` }
+    // summary 即模型面(render 只透 summary):必须自带紧凑数据行 + 证据链,
+    // 否则模型只看到「实时返回」占位一句话(issue #195 实锤)。
+    const list = (live.result as { list?: unknown[] } | null)?.list
+    const n = Array.isArray(list) ? list.length : 0
+    const dateTag = query.checkIn
+      ? `入住 ${query.checkIn}${query.checkOut ? ` → 退房 ${query.checkOut}` : ''}`
+      : '未传日期(上游按当前窗口价)'
+    const lines = hotelLines(live.result)
+    const summary = `${query.destination}:hbcli 实时 ${n} 家(${dateTag})${lines ? `\n${lines}` : ''}\n${live.evidence}`
+    return { ...live, hotels: live.result, summary }
   }
   // 降级原因人话化(issue #24):hbcli 未安装时按 gotry setup 指引(npm 安装期已
   // 自动跑过官方脚本;PATH 未含 ~/.local/bin 时上方候选路径也已兜住),
@@ -176,7 +223,9 @@ export async function searchHotels(
         return {
           ...live,
           hotels: { stays: matched },
-          summary: `${query.destination}:hbcli 实时源不可用(${reason}),已降级到静态包(公开渠道估算,非实时),命中 ${matched.length} 个住宿块`,
+          // summary 即模型面:静态块内容(note/options/recommendation)直接内联,
+          // 模型不必再猜「命中 N 块」里有什么(issue #195)
+          summary: `${query.destination}:hbcli 实时源不可用(${reason}),已降级到静态包(公开渠道估算,非实时),命中 ${matched.length} 个住宿块:\n${JSON.stringify(matched).slice(0, 1600)}`,
         }
       }
       return {

package/ts/capabilities/session/health-watch.ts

@@ -155,8 +155,15 @@ export function startExtensionHealthWatch(opts: HealthWatchOptions = {}): Health
   const probe = opts.probe ?? (async () => {
     // 先确保桥存在 + keepBridge
     const bridge = await import('./extension-bridge.ts')
-    await bridge.getOrCreateSessionBridge({ keepBridge: opts.keepBridge === true })
-    return combinedProbe(opts, businessProbe)
+    const created = await bridge.getOrCreateSessionBridge({ keepBridge: opts.keepBridge === true, ports: opts.ports })
+    // The default path must keep scanning the canonical pool: another GoTry
+    // process may already own the extension-connected bridge. An explicit
+    // port override is an isolation boundary, so probe only the bridge that
+    // this process actually bound (including an ephemeral `0` request).
+    const probeOpts = created.ok && opts.ports
+      ? { ...opts, ports: [created.bridge.port] }
+      : opts
+    return combinedProbe(probeOpts, businessProbe)
   })
   const now = opts.now ?? Date.now
   const state: InternalState = { cancelled: false, readyCount: 0, resolveOutcome: null }

package/ts/dsh-runtime/vendor/README.md

@@ -0,0 +1,60 @@
+# vendored dsh runtime(`vendor/`)
+
+本目录是 [DeepSeek Harness(dsh CLI)](https://github.com/deepseek-ai/DeepSeek-Harness)
+dsh 发布家族的全量 vendored 成员,pnpm workspace 方式参与安装
+(`ts/dsh-runtime/pnpm-workspace.yaml` 声明 `vendor/*`,`linkWorkspacePackages: true`)。
+
+## 当前版本
+
+- 上游:`dsh-v0.1.2-alpha.1`(tag;alpha 面向 monorepo 内部,尚未发布到
+  npm 公共 registry——npm latest 仍为 `0.1.1-rc.2`,等上游 publish 后本目录
+  可整体换回 npm 依赖形态)。
+- 源 commit:`cd5ef814`(/tmp 构建树为浅克隆同源;发布 tag 见上游 releases)。
+- License:MIT © DeepSeek(upstream LICENSE);本仓 MIT 使用。
+
+## 为什么 vendored(而不是 npm 依赖)
+
+- 上游只挂 GitHub 预发布 tag;依赖闭包(dsh 家族 ~187 个内部包 + cordis/
+  schemastery 等 vendor 家族)里 **dsh 家族全部 0.1.2-alpha.1 均不在公共
+  npm**,外部环境不可安装。
+- `ts/dsh-runtime` 只影响 repo 工作副本与 `./gotry`;npm 公共分发面
+  (root `package.json`)仍钉 rc.2,不受影响;CI 不安装本目录。
+- workspace 成员 + `linkWorkspacePackages: true` 让成员间
+  `^0.1.2-alpha.1` 的 range 直接命中本地版本,干净克隆只依赖本仓文件 +
+  公共 registry(第三方),不依赖内部镜像。
+
+## 非 dsh 家族成员:`vendor/dsh-map-tools`
+
+`dsh-map-tools`(dshmarket 第三方宿主插件,地图/路线/POI,零 key 走
+OSM/OSRM)与 dsh 家族不同源,进本目录的原因是 **npm 依赖形态被上游
+peerDependencies 否决**:它要求 `dsh-settings`/`dsh-tools`
+`>=0.1.2-rc.1`,而 gotry 锁定的运行时家族是 `0.1.2-alpha.3`
+(semver 上 alpha < rc)——npm/npx 严格 peer 解析直接 ERESOLVE
+(optionalDependencies 也不豁免),硬依赖会弄坏 `npx @danceiny/gotry`
+主安装路径。故以 vendor 副本随 tarball 分发(root `package.json`
+`files[]` 含本目录),`bin/gotry-inner.js` 解析链 vendor 优先;
+升级 = 从 npm 拉 `dsh-map-tools@<new>` 覆盖本目录(保留来源与
+license:MIT,上游 package.json 里无 devDependencies 需清理)。
+
+## 升级/复现流程(dsh 家族,下个版本照抄)
+
+1. `git clone --depth 1 --branch <tag> https://github.com/deepseek-ai/DeepSeek-Harness.git /tmp/dsh-<tag>`
+2. `cd /tmp/dsh-<tag> && pnpm install && pnpm build:official`
+3. `pnpm release:pack --family dsh --out dist/dsh`(产出 241 个 tarball)
+4. 解包 tarball(`package/` 前缀剥掉)平铺进 `vendor/<kebab-name>/`
+5. manifest 归一处:**删除各成员的 `devDependencies`**(上游 devDeps 引用
+   未进发布家族的 experimental 私有包,npm 安装形态本就不装 devDeps;
+   唯 `@deepseek-ai/dsh-subprocess-local` 的 `postinstall` 保
+   留——恢复 node-pty spawn-helper 可执行位,终局面依赖);
+   `scripts` 里 dev 期 `bundle/watch/build` 一并丢弃。
+6. 更新 `package.json` 的 4 个直接依赖版本 + `pnpm install` 重新生成 lockfile
+7. 验证:`./gotry help` 报版本;`cd ts && npx tsc --noEmit && npx tsx scripts/smoke.ts`;
+   全量 `bash scripts/run-all-tests.sh` 全绿后才可提交。
+
+## 纪律
+
+- 本目录内容必须与上游 tag 的 tarball 逐字节一致(`devDependencies`/
+  dev 期 `scripts` 除外);不得手改 vendor 内代码——补丁面一律走 gotry 侧
+  (`cordis.gotry-patch.yml` / `bin/gotry-inner.js`)。
+- `gotry-state/`、`node_modules/` 已 gitignore;`vendor/` 与三份 manifest
+  (package.json / pnpm-lock.yaml / pnpm-workspace.yaml / .npmrc)入 git。

package/ts/dsh-runtime/vendor/dsh-map-tools/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HorusJiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ts/dsh-runtime/vendor/dsh-map-tools/README.en.md

@@ -0,0 +1,200 @@
+<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.md">中文</a> | English</p>
+
+<p align="center">Map &amp; routing tools plugin for <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>: driving/transit/walking/bicycling route planning, geocoding, reverse geocoding and POI search as <strong>native tools</strong> — the model calls them directly, no MCP server required.</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-installable-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-listed-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>
+
+---
+
+## Features
+
+- **7 native tools**: route planning (driving/transit/walking/bicycling), geocoding, reverse geocoding and POI search — called directly by the model via `map_*`.
+- **Amap (高德) data source (recommended)**: configure a free Amap Web Service key for the best China coverage (transit, POI, reliable Chinese geocoding).
+- **Zero-key fallback**: without a key, driving/walking/bicycling routes use free OSM/OSRM; Chinese address parsing degrades with clear guidance.
+- **Settings card out of the box**: Settings → Plugins → dsh-map-tools, graphical config with an "How to get an Amap key?" link; save applies instantly (no restart).
+- **China-network friendly**: clear Chinese guidance for unreachable free sources or invalid keys.
+
+## Install
+
+Two ways, pick one:
+
+### Option 1: npm install (recommended, prebuilt, no build approval)
+
+```sh
+dsh plugin --profile web add dsh-map-tools
+```
+
+### Option 2: from GitHub (source build, requires approval)
+
+```sh
+dsh plugin --profile web add github:HorusJiang/dsh-map-tools
+```
+
+> The published package ships **no** `prepare`/`postinstall` build scripts, so pnpm ≥10 installs it without prompting to allow build scripts or configuring `allowBuilds`.
+
+> **Version requirement**: from 0.5.0 on, this plugin is compatible with **DeepSeek Harness 0.1.2-rc.1 and newer** (including a source-built 0.1.3-alpha.1). Earlier Harness release lines are no longer supported because `@deepseek-ai/dsh-settings` removed its legacy API.
+
+Restart `dsh web` after install (or wait for HMR), then use the `map_*` tools in a session.
+
+> **Development mode**: `dsh plugin add <local-path>` installs via `link:`, so source edits take effect immediately — ideal for iterating on the plugin.
+
+## Quick start
+
+Configure an Amap key (~2 minutes):
+
+1. Open the [Amap console](https://console.amap.com/dev/key/app) → create an app → request a **"Web Service"** key (free for individuals).
+2. In DSH **Settings → Plugins → dsh-map-tools**, paste the key, set data source `amap`, save.
+3. Ask in a session:
+
+```
+Plan a driving route from Beijing South Station to Capital Airport T3
+Geocode "西湖区文三路478号" to coordinates
+Any gas stations within 1km of 116.397428,39.90923?
+```
+
+## Tools
+
+| Tool | What it does | Free OSM | Amap |
+|---|---|---|---|
+| `map_driving_route` | Driving route planning | ✅ | ✅ |
+| `map_transit_route` | Transit planning | — | ✅ |
+| `map_walking_route` | Walking route planning | ✅ | ✅ |
+| `map_bicycling_route` | Bicycling route planning | ✅ | ✅ |
+| `map_geocode` | Address → coordinates | CJK unreliable | ✅ |
+| `map_reverse_geocode` | Coordinates → address | CJK unreliable | ✅ |
+| `map_poi_search` | POI search | — | ✅ |
+
+Origin/destination accept either **address text** or **`"lng,lat"` coordinates** — the plugin normalizes automatically.
+
+## Configuration
+
+### Settings card (recommended)
+
+DSH **Settings → Plugins → dsh-map-tools** provides a graphical card: data-source selector, masked Amap key input, timeout, and apply link. Saving takes effect immediately.
+
+Config lives in **`~/.dsh-map-tools/config.json`** (0600), decoupled from the DSH settings document and shared across profiles:
+
+```jsonc
+// ~/.dsh-map-tools/config.json
+{
+  "provider": "amap",        // "amap" | "osm"
+  "amapKey": "your-amap-key",
+  "timeoutMs": 15000
+}
+```
+
+> Keys are only surfaced to the frontend as a boolean (`hasAmapKey`); the literal is **never echoed to the page or logs**.
+
+### cordis.yml defaults
+
+Defaults can be provided in the profile's `cordis.yml` (**config-file values win over cordis.yml**):
+
+```yaml
+- id: map-tools
+  name: dsh-map-tools
+  config:
+    provider: amap
+```
+
+## Architecture
+
+```
+┌─ Model ─────────────────────────────────────┐
+│  map_driving_route / map_geocode / ...      │  7 native tools (ctx.tools)
+└──────────────┬──────────────────────────────┘
+               │
+┌──────────────▼──────────────────────────────┐
+│  src/tools/    tool definitions (validate+render) │
+│  src/clients/  provider clients              │
+│    amap.ts      Amap Web Service API (recommended) │
+│    osrm.ts      OSRM free routing (fallback)       │
+│    photon.ts    Photon free geocoding (fallback)   │
+│    nominatim.ts Nominatim free geocoding (fallback)│
+└──────────────┬──────────────────────────────┘
+               │
+┌──────────────▼──────────────────────────────┐
+│  src/config-file.ts  ~/.dsh-map-tools/config.json (0600) │
+│  src/config-route.ts loopback route /dsh-map-tools/config │
+│  src/settings-ns.ts   settings namespace registration    │
+│  client/client.js     settings card (hand-written, zero-dep)│
+└──────────────────────────────────────────────┘
+```
+
+- **Config priority**: config file (settings card) → `cordis.yml` defaults.
+- **Instant apply**: tools rebuild on config change; no restart.
+- **No MCP**: all capabilities are native tools; no external MCP server process.
+
+## Data sources
+
+| Source | Use | Key | Notes |
+|---|---|---|---|
+| Amap (高德) | All tools (recommended) | Free | Best China coverage: transit, POI, Chinese geocoding |
+| OSRM | driving/walking/bicycling routes | none | Free public server, rate-limited |
+| Photon / Nominatim | geocoding | none | Free public; **CJK unreliable**, unreachable on some networks |
+
+> Free-source limitations (unstable CJK geocoding) are deliberate: without a key you get clear guidance; with an Amap key the experience upgrades seamlessly.
+
+## FAQ
+
+**Q: I configured an Amap key but routes still use OSM?**
+A: Check the config file's `provider` is `amap` (not `osm`) and `amapKey` is non-empty.
+
+**Q: Why do transit/POI require a key?**
+A: Free OSM sources don't provide transit or POI data; those need the Amap key.
+
+**Q: My Amap key is rejected?**
+A: Make sure it's a **"Web Service"** key (not JS API / Web key), and the services are enabled in the Amap console.
+
+**Q: Chinese geocoding reports "free source unavailable"?**
+A: Free sources (Photon/Nominatim) handle Chinese poorly and may be unreachable on some CN networks. This is by design — configure an Amap key and it resolves.
+
+## Development
+
+```sh
+pnpm install
+pnpm run build                # tsc → lib/
+pnpm test                     # vitest unit tests (mocked network)
+node scripts/smoke.mjs        # smoke: 7 tools register
+node scripts/integration.mjs  # integration: real requests (free sources)
+node scripts/amap-e2e.mjs     # Amap e2e: set AMAP_API_KEY
+node scripts/config-e2e.mjs   # config file round-trip
+```
+
+Conventions: see [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
+
+## Publishing
+
+```sh
+npm config set registry https://registry.npmjs.org/
+npm login                     # npm account (a bypass-2FA publish token is recommended)
+node scripts/publish.mjs      # one-shot: build → pack check → publish → verify
+```
+
+Versioning follows [SemVer](https://semver.org/); changes are tracked in [CHANGELOG.md](CHANGELOG.md).
+
+## Security
+
+Key storage and vulnerability reporting: see [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+Issues and PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions.
+
+## License
+
+[MIT](LICENSE) © HorusJiang