@danceiny/gotry 0.0.1-rc.18 → 0.0.1-rc.20

package/ts/capabilities/session-search.ts

@@ -6,7 +6,7 @@
  *  cdp(attach 日常 Chrome,Chrome 144+ 每连接弹权限框)降为显式后备
  * (`GOTRY_SESSION_TRANSPORT=cdp` opt-in,诊断/测试用);persistent 仅测试。
  *
- * 证据链(L4 增补):[会话:ctrip-flight@ts] = 用户本人会话内实时检索,非官方 API;
+ * 证据链(L4 增补):[会话:ctrip-flight@ts] / [会话:ctrip-hotel@ts] = 用户本人会话内实时检索,非官方 API;
  * 风控命中(verdict='challenged')= degraded,绝不重试、绝不绕过(合规支柱②)。
  * 节律(§3.4):同站点 ≥30s 间隔 + 单调冷却;超间隔返回 verdict='cooldown'。
  * 永不抛错;扩展车道 fail-closed(桥/扩展不可用即 verdict,零花费);测试/巡检用隔离 profile 与 stateRoot。
@@ -17,6 +17,8 @@ import { extensionCookieNames, extensionSearchJob, classifyBridgeFailure } from
 import { appendFileSync, mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
 import { buildEntryUrl, NETWORK_HINTS, parseBatchSearch, LOGIN_COOKIE_NAMES, SITE_DOMAIN, type SessionFlightOption } from './session/adapters/ctrip-flight.ts'
+import { buildHotelEntryUrl, parseCtripHotelList, HOTEL_SITE_HOST, type SessionHotelOption } from './session/adapters/ctrip-hotel.ts'
+import { buildTrainEntryUrl, parseLeftTicketQuery, TRAIN_SITE_HOST, type SessionTrainOption } from './session/adapters/rail-12306.ts'
 import { EXTENSION_STORE_URL } from './session/extension-bridge.ts'
 
 export type SessionVerdict = 'hit' | 'miss' | 'error' | 'challenged' | 'cooldown' | 'needs-login' | 'needs-attach' | 'needs-extension'
@@ -109,6 +111,326 @@ export function appendExtensionAudit(auditPath: string | undefined, entry: { kin
   } catch { /* 审计失败不阻塞检索 */ }
 }
 
+// ---------------------------------------------------------------------------
+// 酒店会话检索(2026-09-03 实装;与机票同构:节律闸/登录闸/needs-extension 映射/
+// 挑战红线/证据链。酒店页与机票页同属 ctrip.com 风控域,但通道键独立——
+// 各自 30s 预算已足够礼貌,跨通道合并预算留首个真会话风控观测后校准)
+// ---------------------------------------------------------------------------
+
+export interface SessionHotelQuery {
+  /** 目的地(中文);城市码表未收录时须带 cityId */
+  to: string
+  /** 显式城市 id(携程/trip.com 酒店 list 页 URL 的 city= 数字;覆盖码表) */
+  cityId?: number | string
+  /** YYYY-MM-DD */
+  checkIn?: string
+  /** YYYY-MM-DD(与 checkIn 成对) */
+  checkOut?: string
+  adults?: number
+  /** 隔离 profile 目录(测试必传;默认 /tmp 专用目录) */
+  profileDir?: string
+  headless?: boolean
+  /** ReadGuard 审计路径(测试传隔离 stateRoot 下) */
+  auditPath?: string
+  /** 等嗅探回包的上限,默认 30_000(酒店列表接口比机票慢) */
+  timeoutMs?: number
+  /** 允许匿名实例(默认 false);true 仅适配器链路自检,证据链标 anonymous */
+  allowAnonymous?: boolean
+}
+
+export interface SessionHotelResult {
+  ok: boolean
+  via: 'session-ctrip-hotel' | 'session-ctrip-hotel-error'
+  evidence: string
+  latencyMs: number
+  verdict: SessionVerdict
+  hotels?: SessionHotelOption[]
+  error?: string
+  /** needs-extension 时给出 Chrome Web Store URL(dsh UI 渲成可点链接) */
+  installUrl?: string
+  installAction?: 'add-to-chrome'
+}
+
+/** 酒店城市码表未收录时的人话指引(纯函数,测试锚点) */
+export function hotelCityUnresolvedHint(cities: string[]): string {
+  return `城市 ${cities.join('/')} 不在携程酒店城市码表——先 web 搜「hotels.ctrip.com ${cities[0] ?? ''} 酒店」拿到 list 页 URL 里的 city= 数字,带 cityId 重试`
+}
+
+export async function sessionHotelSearch(q: SessionHotelQuery): Promise<SessionHotelResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const site = 'ctrip-hotel'
+  const err = (verdict: SessionVerdict, error: string): SessionHotelResult => ({
+    ok: false, via: 'session-ctrip-hotel-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict, error,
+  })
+
+  // 日期对闸(与 flyai hotel 同口径):成对且 YYYY-MM-DD;过去日期不发上游
+  if ((q.checkIn ? 1 : 0) !== (q.checkOut ? 1 : 0) || (q.checkIn && !/^\d{4}-\d{2}-\d{2}$/.test(q.checkIn))) {
+    return err('error', 'checkIn/checkOut 须成对且为 YYYY-MM-DD(未定档期可不带日期)')
+  }
+  if (q.checkIn) {
+    const now = new Date()
+    const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+    if (q.checkIn < today || (q.checkOut ?? '') < q.checkIn) {
+      return err('error', `入住 ${q.checkIn}/退房 ${q.checkOut ?? ''} 不是未来合法区间(今天 ${today})——向用户确认日期后再查`)
+    }
+  }
+
+  // 节律闸:超间隔即拒,不发起导航
+  const last = lastCallAt.get(site) ?? 0
+  if (Date.now() - last < MIN_INTERVAL_MS) {
+    return err('cooldown', `rate limit: last call ${Date.now() - last}ms ago, min ${MIN_INTERVAL_MS}ms`)
+  }
+  lastCallAt.set(site, Date.now())
+
+  const entry = buildHotelEntryUrl({ to: q.to, cityId: q.cityId, checkIn: q.checkIn, checkOut: q.checkOut, adults: q.adults })
+  if (!entry.ok || !entry.url) {
+    return err('error', hotelCityUnresolvedHint(entry.unresolved ?? [q.to]))
+  }
+
+  const mode = resolveTransportMode(q.profileDir)
+
+  if (mode === 'extension') {
+    // ① 登录态快查(与机票同账号体系,票据 cookie 名一致)
+    const login = await extensionCookieNames({ site, domain: SITE_DOMAIN.replace(/^\./, ''), ticketNames: LOGIN_COOKIE_NAMES })
+    if (!login.ok) {
+      const verdict = classifyBridgeFailure(login.kind)
+      if (verdict === 'needs-extension') {
+        return { ok: false, via: 'session-ctrip-hotel-error', evidence: '[会话:ctrip-hotel-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: login.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' as const }
+      }
+      return err(verdict, login.summary)
+    }
+    if (login.tickets.length === 0 && !q.allowAnonymous) {
+      return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)')
+    }
+    // ② 检索 job:后台标签 + 被动嗅探(URL hint + 形状兜底;扩展零写行为)
+    const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs })
+    appendExtensionAudit(q.auditPath, {
+      kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+      result: r.ok ? (r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"`) : `${r.kind}:${r.summary.slice(0, 120)}`,
+    })
+    if (!r.ok) {
+      const verdict = classifyBridgeFailure(r.kind)
+      if (verdict === 'needs-extension') {
+        return { ok: false, via: 'session-ctrip-hotel-error', evidence: '[会话:ctrip-hotel-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' as const }
+      }
+      return err(verdict, r.summary)
+    }
+    const title = r.title
+    const head = r.body.slice(0, 5000)
+    if (CHALLENGE_RE.test(title + head)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    const hotels = parseCtripHotelList(r.body)
+    const verdict: SessionVerdict = hotels.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-ctrip-hotel',
+      evidence: `[会话:${site}@${ts}] ${hotels.length} hotels;transport=extension(被动嗅探,零系统弹窗;扩展零写行为=物理只读)${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+      latencyMs: Date.now() - started,
+      verdict,
+      hotels,
+    }
+  }
+
+  // cdp/persistent 车道:与机票同构——挂监听等 NETWORK hint 回包(酒店用 HOTEL hints + 形状兜底)
+  const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true })
+  if (!t.ok) {
+    return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary)
+  }
+  try {
+    const loggedIn = async (): Promise<boolean> => {
+      const cookies = await t.browser.cookies().catch(() => [])
+      return cookies.some((c) => c.domain.includes(SITE_DOMAIN.replace(/^\./, '')) && LOGIN_COOKIE_NAMES.includes(c.name))
+    }
+    if (!(await loggedIn()) && !q.allowAnonymous) {
+      return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)')
+    }
+    let settled = false
+    let body = ''
+    const heard = new Promise<void>((resolve) => {
+      t.page.on('response', async (res) => {
+        if (settled) return
+        const u = res.url()
+        const hostHit = u.includes(HOTEL_SITE_HOST)
+        if (!hostHit) return
+        try {
+          const text = await res.text()
+          if (text && (hostHit && /hotels\.ctrip\.com\/(hotels\/api|domestic\/pc\/api)|GetHotelListBySOA|GetHotelListByCity|HotelSearch|hotelsearch/i.test(u) || text.length <= 2_000_000 && /"hotelList"|"hotelMatchInfos"|"hotelName"/.test(text))) {
+            body = text
+            settled = true
+            resolve()
+          }
+        } catch { /* 流式/竞态不可读则继续等下一个 */ }
+      })
+      setTimeout(() => resolve(), q.timeoutMs ?? 30_000)
+    })
+    await t.page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 30_000 })
+    await heard
+    const title = await t.page.title().catch(() => '')
+    const headHtml = (await t.page.content().catch(() => '')).slice(0, 5000)
+    if (CHALLENGE_RE.test(title + headHtml)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    const hotels = parseCtripHotelList(body)
+    const verdict: SessionVerdict = hotels.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-ctrip-hotel',
+      evidence: `[会话:${site}@${ts}] ${hotels.length} hotels;guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}${q.allowAnonymous ? ';anonymous=自检态' : ''}`,
+      latencyMs: Date.now() - started,
+      verdict,
+      hotels,
+    }
+  } catch (e) {
+    return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e))
+  } finally {
+    await t.close()
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// 火车会话检索(2026-09-03 实装;12306 余票查询是公开面——登录只关系下单,
+// 无账号数据过手,故无登录闸;扩展照样只读被动嗅探,证据链标注「公开查询面」)
+// ---------------------------------------------------------------------------
+
+export interface SessionTrainQuery {
+  from: string
+  to: string
+  /** YYYY-MM-DD */
+  date: string
+  /** 显式城市电报码(覆盖码表;kyfw 查询页 URL fs=城市,XXX 的三位码) */
+  fromStationTelecode?: string
+  toStationTelecode?: string
+  /** 隔离 profile 目录(测试必传;默认 /tmp 专用目录) */
+  profileDir?: string
+  headless?: boolean
+  /** ReadGuard 审计路径(测试传隔离 stateRoot 下) */
+  auditPath?: string
+  /** 等嗅探回包的上限,默认 25_000 */
+  timeoutMs?: number
+}
+
+export interface SessionTrainResult {
+  ok: boolean
+  via: 'session-train-12306' | 'session-train-12306-error'
+  evidence: string
+  latencyMs: number
+  verdict: SessionVerdict
+  trains?: SessionTrainOption[]
+  error?: string
+  /** needs-extension 时给出 Chrome Web Store URL(dsh UI 渲成可点链接) */
+  installUrl?: string
+  installAction?: 'add-to-chrome'
+}
+
+/** 车站电报码表未收录时的人话指引(纯函数,测试锚点) */
+export function trainStationUnresolvedHint(cities: string[]): string {
+  return `城市 ${cities.join('/')} 不在 12306 城市电报码表——web 搜「12306 ${cities[0] ?? ''} 余票」拿到 kyfw 查询页 URL 里的 fs=城市,XXX 三位码,带 fromStationTelecode/toStationTelecode 重试`
+}
+
+export async function sessionTrainSearch(q: SessionTrainQuery): Promise<SessionTrainResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const site = 'train-12306'
+  const err = (verdict: SessionVerdict, error: string): SessionTrainResult => ({
+    ok: false, via: 'session-train-12306-error', evidence: `[会话:${site}@error@${ts}] ${error}`, latencyMs: Date.now() - started, verdict, error,
+  })
+
+  // 节律闸:超间隔即拒,不发起导航
+  const last = lastCallAt.get(site) ?? 0
+  if (Date.now() - last < MIN_INTERVAL_MS) {
+    return err('cooldown', `rate limit: last call ${Date.now() - last}ms ago, min ${MIN_INTERVAL_MS}ms`)
+  }
+  lastCallAt.set(site, Date.now())
+
+  const entry = buildTrainEntryUrl({ from: q.from, to: q.to, date: q.date, fromStationTelecode: q.fromStationTelecode, toStationTelecode: q.toStationTelecode })
+  if (!entry.ok || !entry.url) {
+    return err('error', trainStationUnresolvedHint(entry.unresolved ?? [q.from, q.to]))
+  }
+
+  const mode = resolveTransportMode(q.profileDir)
+
+  if (mode === 'extension') {
+    // 无登录闸(公开查询面):直接发起检索 job
+    const r = await extensionSearchJob({ site, url: entry.url, timeoutMs: q.timeoutMs })
+    appendExtensionAudit(q.auditPath, {
+      kind: 'extension-session-job', site, url: entry.url, jobId: 'search',
+      result: r.ok ? (r.timedOut ? 'timeout' : `body ${r.body.length}B title="${r.title.slice(0, 60)}"`) : `${r.kind}:${r.summary.slice(0, 120)}`,
+    })
+    if (!r.ok) {
+      const verdict = classifyBridgeFailure(r.kind)
+      if (verdict === 'needs-extension') {
+        return { ok: false, via: 'session-train-12306-error', evidence: '[会话:train-12306-needs-extension@ts]', latencyMs: Date.now() - started, verdict, error: r.summary, installUrl: EXTENSION_STORE_URL, installAction: 'add-to-chrome' as const }
+      }
+      return err(verdict, r.summary)
+    }
+    const title = r.title
+    const head = r.body.slice(0, 5000)
+    if (CHALLENGE_RE.test(title + head)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    const trains = parseLeftTicketQuery(r.body, entry.url)
+    const verdict: SessionVerdict = trains.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-train-12306',
+      evidence: `[会话:${site}@${ts}] ${trains.length} trains;transport=extension(公开查询面,被动嗅探,零系统弹窗;扩展零写行为=物理只读)`,
+      latencyMs: Date.now() - started,
+      verdict,
+      trains,
+    }
+  }
+
+  // cdp/persistent 车道:与机/酒同构
+  const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: mode === 'persistent' ? 'persistent' : 'cdp', newPage: true })
+  if (!t.ok) {
+    return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary)
+  }
+  try {
+    let settled = false
+    let body = ''
+    const heard = new Promise<void>((resolve) => {
+      t.page.on('response', async (res) => {
+        if (settled) return
+        const u = res.url()
+        if (!/leftTicket\/query/i.test(u)) return
+        try {
+          const text = await res.text()
+          if (text) {
+            body = text
+            settled = true
+            resolve()
+          }
+        } catch { /* 流式/竞态不可读则继续等下一个 */ }
+      })
+      setTimeout(() => resolve(), q.timeoutMs ?? 25_000)
+    })
+    await t.page.goto(entry.url, { waitUntil: 'domcontentloaded', timeout: 30_000 })
+    await heard
+    const title = await t.page.title().catch(() => '')
+    const headHtml = (await t.page.content().catch(() => '')).slice(0, 5000)
+    if (CHALLENGE_RE.test(title + headHtml)) {
+      return err('challenged', `风控/验证码命中(title=${title.slice(0, 60)});按红线不重试不绕过,交还用户`)
+    }
+    const trains = parseLeftTicketQuery(body, entry.url)
+    const verdict: SessionVerdict = trains.length > 0 ? 'hit' : 'miss'
+    return {
+      ok: true,
+      via: 'session-train-12306',
+      evidence: `[会话:${site}@${ts}] ${trains.length} trains(公开查询面);guard blocked=${t.guard.blockedCount()}/${t.guard.requestCount()}`,
+      latencyMs: Date.now() - started,
+      verdict,
+      trains,
+    }
+  } catch (e) {
+    return err('error', e instanceof Error ? e.message.slice(0, 200) : String(e))
+  } finally {
+    await t.close()
+  }
+}
+
 export async function sessionFlightSearch(q: SessionFlightQuery): Promise<SessionSearchResult> {
   const started = Date.now()
   const ts = new Date().toISOString()

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