@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.27

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/tools/routes.js

@@ -0,0 +1,267 @@
+/** Route planning tools: driving / transit / walking / bicycling. */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { AmapQuotaError } from '../clients/amap.js';
+import { parseLngLat } from '../types.js';
+import { simplifyGeometry, shortPlaceName } from '../geo.js';
+/**
+ * 把工具返回值投影成卡片元数据（纯函数，可单测）。
+ *
+ * 上游数据不可信（重放的是历史日志），所以每个字段都做窄化；
+ * 几何不足两个点时**省略** `line` 而不是报错——客户端会因此退回文本卡片。
+ * @param value - 已通过 schema 校验的工具返回值。
+ * @returns 卡片元数据。
+ */
+export function routeCardMeta(value) {
+    const line = simplifyGeometry(Array.isArray(value.geometry) ? value.geometry : []);
+    return {
+        v: 1,
+        kind: 'route',
+        provider: value.provider === 'osrm' ? 'osrm' : 'amap',
+        distanceM: Number.isFinite(value.distanceM) ? value.distanceM : 0,
+        durationS: Number.isFinite(value.durationS) ? value.durationS : 0,
+        stepCount: Array.isArray(value.steps) ? value.steps.length : 0,
+        alternatives: Array.isArray(value.alternatives) ? value.alternatives.length : 0,
+        ...(line.length >= 2 ? { line } : {}),
+        ...(typeof value.fromName === 'string' && value.fromName !== '' ? { fromName: value.fromName } : {}),
+        ...(typeof value.toName === 'string' && value.toName !== '' ? { toName: value.toName } : {}),
+    };
+}
+/** 统一拼装工具返回值：三个返回点（高德/降级 OSRM/纯 OSRM）共用一份。 */
+function routeValue(result, names = {}) {
+    return {
+        provider: result.provider,
+        distanceM: result.distanceM,
+        durationS: result.durationS,
+        polyline: result.polyline,
+        geometry: result.geometry,
+        steps: result.steps,
+        ...(names.fromName !== undefined ? { fromName: names.fromName } : {}),
+        ...(names.toName !== undefined ? { toName: names.toName } : {}),
+    };
+}
+/**
+ * 给一个端点算"给卡片看的名字"。
+ *
+ * 参数本身是地名时直接用它（不打任何请求）；参数是坐标时反查一次，
+ * 把"北京市丰台区北京南站"裁成"北京南站"。反查是**尽力而为**：没有
+ * 高德 key、配额超限、或任何异常都退回坐标原文，绝不让卡片因此失败。
+ *
+ * @param text - 用户/模型传入的原始参数。
+ * @param coord - 已解析出的坐标（起终点几何的首尾）。
+ * @param clients - 运行时客户端集合。
+ * @param signal - 取消信号。
+ * @returns 可读名称。
+ */
+async function placeLabel(text, coord, clients, signal) {
+    if (parseLngLat(text) === null)
+        return text;
+    if (!clients.amap)
+        return text;
+    try {
+        const r = await clients.amap.reverseGeocode(coord, signal);
+        // **省也要剥**：高德 `formatted_address` 是"省市区街道+具体位置"连写，
+        // 第一个前缀就是"湖南省"，列表里没有它，后面几个前缀就一个也匹配不上
+        // （startsWith 从整串开头比），整串会原样留下——卡片抬头就会变成
+        // "湖南省长沙市雨花区东山街道长沙南站"。街道（township）同理，
+        // 不剥会得到"右安门街道北京南站"这种半成品。
+        const short = shortPlaceName(r.formatted, [r.province, r.city, r.district, r.township]);
+        return short === '' ? text : short;
+    }
+    catch {
+        return text;
+    }
+}
+function routeTool(name, description, mode, clients) {
+    const osrmProfile = mode === 'walking' ? 'walking' : mode === 'bicycling' ? 'cycling' : 'driving';
+    return defineTool({
+        name,
+        // 卡片语义是模型必须知道的：Web 界面里"最终答案下方的地图卡"**只镜像本回合**
+        // 的路线调用。实测踩坑：模型为补全主路线被截断的分段，在回答回合里顺手算了
+        // 一段"别的路口 → 终点"的核对路线，结果卡片画的是那段核对、正文讲的却是主
+        // 路线。这里把规则说清楚，模型要么在本回合重算主路线，要么至少知道自己刚才
+        // 那次调用会占掉卡片。
+        description: `${description} 注意：Web 卡片的路线图只镜像**本回合**的路线调用（本回合算几条就画几条，含为核对细节而算的分段）；回答如果引用更早回合的路线，请在本回合用相同起终点再调用一次。`,
+        parameters: {
+            origin: { type: 'string', required: true, description: 'Start point: an address, or "lng,lat" coordinates.' },
+            destination: { type: 'string', required: true, description: 'End point: an address, or "lng,lat" coordinates.' },
+            waypoints: { type: 'string', description: 'Optional waypoints as "lng,lat;lng,lat" (Amap driving only).' },
+            alternatives: { type: 'boolean', description: 'Request alternative routes (default false).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    provider: { type: 'string' },
+                    distanceM: { type: 'number' },
+                    durationS: { type: 'number' },
+                    polyline: { type: 'string' },
+                    geometry: {
+                        type: 'array',
+                        items: { type: 'array', items: { type: 'number' } },
+                    },
+                    fromName: { type: 'string' },
+                    toName: { type: 'string' },
+                    steps: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                instruction: { type: 'string' },
+                                distanceM: { type: 'number' },
+                                durationS: { type: 'number' },
+                            },
+                        },
+                    },
+                    alternatives: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                provider: { type: 'string' },
+                                distanceM: { type: 'number' },
+                                durationS: { type: 'number' },
+                                steps: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        properties: {
+                                            instruction: { type: 'string' },
+                                            distanceM: { type: 'number' },
+                                            durationS: { type: 'number' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (args, value) => {
+                const v = value;
+                const mins = (s) => Math.round(s / 60);
+                const providerName = v.provider === 'amap' ? '高德' : 'OSRM';
+                const distanceText = v.distanceM >= 1000 ? `${(v.distanceM / 1000).toFixed(1)} 公里` : `${v.distanceM} 米`;
+                // Amap v5 transit returns no duration field — report it as unknown.
+                const durationText = v.durationS > 0 ? `，约 ${mins(v.durationS)} 分钟` : '';
+                const lines = [
+                    `${providerName} 路线：${distanceText}${durationText}`,
+                ];
+                // 回显解析后的起终点名称。坐标入参时这两个名字是**我们按坐标反查出来的**，
+                // 模型自己看不到（它的参数里只有一串数字）——实测踩坑：模型为补全分段
+                // 指引而地理编码了别的路口，却拿它当了起点，于是"算出来的路线"和它想讲
+                // 的完全不是一条。把真名回显出来，模型和读过程区的人都能立刻发现传错。
+                if (v.fromName || v.toName) {
+                    const reversed = parseLngLat(args.origin) !== null || parseLngLat(args.destination) !== null;
+                    lines.push(`起终点：${v.fromName || '?'} → ${v.toName || '?'}${reversed ? '（坐标反查）' : ''}`);
+                }
+                // 分段指引：以前固定只给前 12 步、再加一句"共 N 步"。实测这条截断**就是**
+                // 一连串问题的起因——模型想回答"最后几步怎么进景区大门"，手里却只有前 12 步，
+                // 于是自己去地理编码路口、再算一条分段路线来反推；那条探测路线把卡片占掉，
+                // 用户看到的地图就变成了另一条路线（正文讲主路线、地图画探测）。
+                // 现在给足：≤24 步全给；更长则给前 16 步 + 省略提示 + **最后 6 步**
+                // （到达段永远在，模型没有理由再去补算）。
+                const STEP_MAX = 24;
+                const STEP_HEAD = 16;
+                const STEP_TAIL = 6;
+                if (v.steps.length <= STEP_MAX) {
+                    for (const s of v.steps)
+                        lines.push(`- ${s.instruction}`);
+                }
+                else {
+                    for (const s of v.steps.slice(0, STEP_HEAD))
+                        lines.push(`- ${s.instruction}`);
+                    lines.push(`- …（中间省略 ${v.steps.length - STEP_HEAD - STEP_TAIL} 步，共 ${v.steps.length} 步）`);
+                    for (const s of v.steps.slice(v.steps.length - STEP_TAIL))
+                        lines.push(`- ${s.instruction}`);
+                }
+                if (v.alternatives?.length) {
+                    lines.push(`另有 ${v.alternatives.length} 条备选路线：`);
+                    for (const a of v.alternatives) {
+                        const aName = a.provider === 'amap' ? '高德' : 'OSRM';
+                        lines.push(`  - ${aName}：${(a.distanceM / 1000).toFixed(1)} 公里 / ${mins(a.durationS)} 分钟`);
+                    }
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+            // 卡片数据：抽稀后的几何 + 距离/耗时/分段数，随会话日志持久化，
+            // 由客户端 client/client.js 注册的同名 toolview 读取（内置 Web 客户端
+            // 不消费 presentCall/presentResult，UI 走 tool.call.toolview 槽位）。
+            presentationMeta: (_args, value) => routeCardMeta(value),
+        },
+        async execute(args, exec) {
+            let origin;
+            let destination;
+            try {
+                origin = parseLngLat(args.origin) ?? (await clients.resolve(args.origin, exec.signal));
+                destination = parseLngLat(args.destination) ?? (await clients.resolve(args.destination, exec.signal));
+            }
+            catch (err) {
+                // 地址解析阶段的高德配额超限：没有坐标就无法降级，转成可操作提示。
+                if (err instanceof AmapQuotaError) {
+                    throw new Error(`地址解析暂时不可用（${err.message}）。请稍后重试，或直接提供 "lng,lat" 坐标。`);
+                }
+                throw err;
+            }
+            // 起终点名称：模型常常先用 map_geocode 把地名换成坐标再调路线工具，
+            // 那样参数里就只剩坐标。坐标入参时反查一次，卡片才显示得出地名。
+            // （地名入参不打任何额外请求；反查失败退回原文。）
+            const [fromName, toName] = await Promise.all([
+                placeLabel(args.origin, origin, clients, exec.signal),
+                placeLabel(args.destination, destination, clients, exec.signal),
+            ]);
+            const names = { fromName, toName };
+            // Provider priority: Amap → OSRM free fallback.
+            if (clients.amap) {
+                try {
+                    let city1;
+                    let city2;
+                    try {
+                        city1 = mode === 'transit' ? await clients.resolveCity(args.origin, exec.signal) : undefined;
+                        city2 = mode === 'transit' ? await clients.resolveCity(args.destination, exec.signal) : undefined;
+                    }
+                    catch (err) {
+                        // 城市解析也受高德配额影响；公交没有 city 无法请求，但非公交不受影响。
+                        if (err instanceof AmapQuotaError && mode === 'transit') {
+                            throw new Error(`公交路线需要城市解析，但高德暂不可用（${err.message}）。请稍后重试，或改用驾车/步行/骑行路线（自动降级 OSRM 免费源）。`);
+                        }
+                        throw err;
+                    }
+                    const result = await clients.amap.route(origin, destination, mode, { city1, city2 }, exec.signal);
+                    const out = routeValue(result, names);
+                    if (args.waypoints && mode === 'driving') {
+                        out.waypoints = args.waypoints.split(';').map((w) => w.trim()).filter(Boolean).join(';');
+                    }
+                    return out;
+                }
+                catch (err) {
+                    // 高德配额超限（QPS/日配额）：非公交模式自动降级 OSRM 兜底，
+                    // 公交无免费兜底源，给用户可操作的提示。
+                    if (err instanceof AmapQuotaError) {
+                        if (mode === 'transit') {
+                            throw new Error(`高德公交路线暂不可用（${err.message}）。请稍后重试，或改用驾车/步行/骑行路线（自动降级 OSRM 免费源）。`);
+                        }
+                        const result = await clients.osrm.route(origin, destination, osrmProfile, exec.signal);
+                        return routeValue(result, names);
+                    }
+                    throw err;
+                }
+            }
+            // Fallback: OSRM (driving/walking/cycling only; no transit).
+            if (mode === 'transit') {
+                throw new Error('公交路线需要高德 key。请在插件配置中设置 amapKey（https://console.amap.com/dev/key/app）。');
+            }
+            const result = await clients.osrm.route(origin, destination, osrmProfile, exec.signal);
+            return routeValue(result, names);
+        },
+    });
+}
+export function registerRouteTools(ctx, clients, disposers = []) {
+    disposers.push(ctx.tools.register(routeTool('map_driving_route', '规划驾车路线，返回距离、预计耗时和分段指引。起点/终点支持地址或 "lng,lat" 坐标。', 'driving', clients)));
+    disposers.push(ctx.tools.register(routeTool('map_transit_route', '规划公交/地铁换乘路线（需配置高德 amapKey），返回距离、耗时和多段换乘指引。', 'transit', clients)));
+    disposers.push(ctx.tools.register(routeTool('map_walking_route', '规划步行路线，返回距离、预计耗时和分段指引。', 'walking', clients)));
+    disposers.push(ctx.tools.register(routeTool('map_bicycling_route', '规划骑行路线，返回距离、预计耗时和分段指引。', 'bicycling', clients)));
+}

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/clients/amap.d.ts

@@ -0,0 +1,90 @@
+/** Amap (高德) Web Service API client. */
+import type { GeocodeResult, LngLat, PoiResult, RouteResult } from '../types.js';
+/** 配额类错误（QPS 或日配额超限）。retryable=true 时短期内重试可能成功
+ *  （QPS 超限），false 表示重试无意义（日配额已用尽）。 */
+export declare class AmapQuotaError extends Error {
+    readonly infocode: string;
+    readonly retryable: boolean;
+    constructor(infocode: string, message: string, retryable: boolean);
+}
+export interface AmapClientOptions {
+    key: string;
+    timeoutMs: number;
+    /** 每秒最大高德请求数（默认 2，低于高德常见 3 QPS 上限，留余量防 10021）。 */
+    maxQps?: number;
+}
+export declare class AmapClient {
+    private readonly opts;
+    private readonly limiter;
+    private readonly geoCache;
+    private readonly routeCache;
+    private readonly poiCache;
+    /** 静态地图字节缓存：同一张图不重复计费。 */
+    private readonly mapCache;
+    constructor(opts: AmapClientOptions);
+    /**
+     * 带配额保护的统一请求入口：限速排队 → 缓存命中 → 请求 → 可重试错误退避
+     * 重试 → 写入缓存。
+     */
+    private request;
+    /** 裸 GET：拼 URL、带 key、超时 + abort、错误分类。 */
+    private rawGet;
+    /**
+     * 把高德返回的错误码翻译成面向用户的异常（key / 配额 / 其它）。
+     * @param infocode - 高德 `infocode`。
+     * @param info - 高德 `info` 文案。
+     */
+    private throwAmapError;
+    /**
+     * 裸 GET，返回二进制（静态地图）。高德出错时返回 JSON 而不是图片，
+     * 所以响应不是 image/* 就按错误体解析。
+     */
+    private rawGetBytes;
+    /**
+     * 静态地图：一张**真地图** PNG，路线折线与起终点标注由高德绘制。
+     *
+     * 取景框**交给高德自己适配**——不传 `location`，不传 `zoom`。这里踩过
+     * 一个很贵的坑：高德静态地图的 `zoom` 与标准 Web Mercator 差一级
+     * （它的 12 级才等于 256px 瓦片的 13 级），于是按 Mercator 公式"算准了
+     * 装得下"的 zoom 实际被放大一倍，路线溢出画布；而高德**不报错**，只是
+     * 静默把整条 `paths` 丢掉——现象正是"有底图、没路线"。
+     *
+     * 只给 `paths`（+`markers`）时高德按外包框自适应取景，实测 0.8km 步行、
+     * 20.9km 驾车、1205km 跨省、公交链各种尺度都完整居中、不裁切。
+     *
+     * 结果按参数缓存，同一张图不会被反复计费。
+     *
+     * @param line - 路线几何（GCJ-02，与高德出图坐标系一致）。
+     * @param opts - 画布尺寸与是否画起终点标注。
+     * @param signal - 取消信号。
+     * @returns PNG 字节。
+     */
+    staticMap(line: readonly LngLat[], opts: {
+        width: number;
+        height: number;
+        markers?: boolean;
+    }, signal: AbortSignal): Promise<Uint8Array>;
+    /**
+     * Plan a route. `mode` maps to the Amap endpoint.
+     * Transit requires city1/city2 (origin/destination city names).
+     */
+    route(origin: LngLat, destination: LngLat, mode: 'driving' | 'transit' | 'walking' | 'bicycling', opts: {
+        city1?: string;
+        city2?: string;
+    } | undefined, signal: AbortSignal): Promise<RouteResult>;
+    private transitRoute;
+    /** Forward geocode: address → coordinates. */
+    geocode(address: string, signal: AbortSignal): Promise<GeocodeResult>;
+    /** Reverse geocode: coordinates → address. */
+    reverseGeocode(location: LngLat, signal: AbortSignal): Promise<GeocodeResult>;
+    /** POI text search. */
+    poiSearch(keywords: string, opts: {
+        region?: string;
+        cityLimit?: boolean;
+    }, signal: AbortSignal): Promise<PoiResult[]>;
+    /** POI around search (nearest first by default). */
+    poiAround(location: LngLat, keywords: string, opts: {
+        radiusM?: number;
+        types?: string;
+    }, signal: AbortSignal): Promise<PoiResult[]>;
+}

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/clients/nominatim.d.ts

@@ -0,0 +1,17 @@
+/** Nominatim (OpenStreetMap) geocoding client — free fallback, 1 QPS policy. */
+import type { GeocodeResult, LngLat } from '../types.js';
+export interface NominatimClientOptions {
+    timeoutMs: number;
+    baseUrl?: string;
+    /** User-Agent identifying the client (required by Nominatim usage policy). */
+    userAgent: string;
+}
+export declare class NominatimClient {
+    private readonly opts;
+    constructor(opts: NominatimClientOptions);
+    private get;
+    /** Forward geocode. */
+    geocode(query: string, signal: AbortSignal): Promise<GeocodeResult>;
+    /** Reverse geocode. */
+    reverseGeocode(location: LngLat, signal: AbortSignal): Promise<GeocodeResult>;
+}

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/clients/osrm.d.ts

@@ -0,0 +1,15 @@
+/** OSRM public server client — free route fallback (no API key). */
+import type { LngLat, RouteResult } from '../types.js';
+export interface OsrmClientOptions {
+    timeoutMs: number;
+    baseUrl?: string;
+}
+export declare class OsrmClient {
+    private readonly opts;
+    constructor(opts: OsrmClientOptions);
+    /**
+     * Plan a route. `profile` maps to OSRM profiles: driving | walking | cycling.
+     * OSRM has no transit profile — callers must not request transit here.
+     */
+    route(origin: LngLat, destination: LngLat, profile: 'driving' | 'walking' | 'cycling', signal: AbortSignal): Promise<RouteResult>;
+}

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/clients/photon.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Photon (photon.komoot.io) geocoding client — free, keyless, reachable on CN
+ * networks (unlike nominatim.openstreetmap.org). Backed by OpenStreetMap data.
+ *
+ * Usage policy: free public service; be reasonable with request rate. Add a
+ * `lang` parameter (default zh) for localized results.
+ */
+import type { GeocodeResult, LngLat } from '../types.js';
+export interface PhotonClientOptions {
+    timeoutMs: number;
+    baseUrl?: string;
+    lang?: 'zh' | 'en';
+}
+export declare class PhotonClient {
+    private readonly opts;
+    constructor(opts: PhotonClientOptions);
+    private get;
+    /** Forward geocode. */
+    geocode(query: string, signal: AbortSignal): Promise<GeocodeResult>;
+    /** Reverse geocode. */
+    reverseGeocode(location: LngLat, signal: AbortSignal): Promise<GeocodeResult>;
+}

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/config-file.d.ts

@@ -0,0 +1,33 @@
+/**
+ * dsh-map-tools persisted config file (~/.dsh-map-tools/config.json).
+ *
+ * Follows the modlens pattern: the plugin's API keys and provider choice live
+ * in its own file (shared across profiles, never in the DSH settings
+ * document), and the settings card reads/writes it through a loopback route.
+ */
+/** The file the plugin's settings card reads and writes. Overridable for tests. */
+export declare function configPath(): string;
+/** What the plugin persists and serves to the settings card. */
+export interface MapToolsFileConfig {
+    provider?: 'amap' | 'osm';
+    amapKey?: string;
+    timeoutMs?: number;
+    maxQps?: number;
+}
+/**
+ * Read the shared config, or a thrown error. Only a missing file reads as
+ * empty: an existing-but-unparsable file is somebody's configuration, and a
+ * card that treated it as empty would overwrite it on the next save.
+ */
+export declare function readConfig(): MapToolsFileConfig;
+/** Persist a patch onto the config file, then return the new whole. */
+export declare function applyConfig(patch: Partial<MapToolsFileConfig>): MapToolsFileConfig;
+/** Whether the config file exists (the card can offer "open config file"). */
+export declare function configFileExists(): boolean;
+/** Non-secret summary served to the settings card (keys are never echoed). */
+export declare function configSummary(): {
+    provider: MapToolsFileConfig['provider'];
+    timeoutMs?: number;
+    maxQps?: number;
+    hasAmapKey: boolean;
+};

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/config-route.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Loopback settings-card route for dsh-map-tools.
+ *
+ * GET  /dsh-map-tools/config            → non-secret summary (has-amap-key, …)
+ * GET  /dsh-map-tools/config?open=true  → open the config file in the editor
+ * POST /dsh-map-tools/config            → apply a provider/key/timeout patch
+ *
+ * Same-origin loopback only (mirrors dsh's own /api fence and the modlens
+ * pattern); the two halves of the card read/write a real file.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { IncomingMessage } from 'node:http';
+/** Refuse cross-origin and non-loopback requests (the route answers same-origin loopback only). */
+export declare function isTrustedRequest(req: IncomingMessage): boolean;
+/**
+ * Register the settings-card route under the web server, when one exists.
+ *
+ * @param ctx - plugin context.
+ * @param reload - rebuild the tools after the card saves (the file write alone
+ *   never reaches the registered tool instances; without this the new provider
+ *   or key only takes effect on the next plugin reload).
+ */
+export declare function installConfigRoute(ctx: Context, reload?: () => void): void;

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/config.d.ts

@@ -0,0 +1,23 @@
+/** Plugin configuration schema. */
+import Schema from '@deepseek-ai/schemastery';
+export interface Config {
+    /**
+     * Provider selection:
+     * - 'amap': 高德地图（Web 服务 API key，免费申请，推荐）
+     * - 'osm': 免费 OSM/OSRM 兜底（无 key，能力有限）
+     */
+    provider: 'amap' | 'osm';
+    /** Amap (高德) Web Service API key. */
+    amapKey?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs: number;
+    /** Amap requests per second cap (高德个人 key QPS 上限低，默认 2 留余量). */
+    maxQps: number;
+    /** Default route mode when a generic route is requested. */
+    defaultMode: 'driving' | 'transit' | 'walking' | 'bicycling';
+    /** Language hint for providers that support it. */
+    language: 'zh' | 'en';
+}
+/** Amap apply URL (shown as a clickable link in the settings card). */
+export declare const AMAP_APPLY_URL = "https://console.amap.com/dev/key/app";
+export declare const Config: Schema<Config>;

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/geo.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 路线几何的纯函数工具：解码、抽稀、取整。
+ *
+ * 这些函数是 UI 卡片的输入准备层——它们决定"会话日志里到底存了多少个点"。
+ * 全是纯函数（无 I/O、无时钟、无随机），便于单元测试。
+ */
+import type { LngLat } from './types.js';
+/** 会话日志里一条路线最多保留的几何点数（卡片是示意图，不需要原始精度）。 */
+export declare const MAX_GEOMETRY_POINTS = 200;
+/**
+ * 解码高德的紧凑折线串 `"lng,lat;lng,lat;…"`。
+ * 非法片段被跳过（上游数据不可信，宁可少画一点也不抛错）。
+ * @param text - 高德 `polyline` 字段原文。
+ * @returns 解析出的坐标序列（可能为空）。
+ */
+export declare function decodeAmapPolyline(text: string | undefined): LngLat[];
+/** 去掉相邻重复点（按取整后的坐标比较），并丢弃非法点。 */
+export declare function dedupeGeometry(points: readonly LngLat[]): LngLat[];
+/**
+ * 抽稀一条路线几何，使其点数不超过 `maxPoints`。
+ *
+ * 阈值从包围盒对角线推导（自适应：长途粗、短途细——40 公里路线约 40 米，
+ * 200 米步行路线约 0.2 米），逐步放宽直到达标；若 Douglas–Peucker 仍不达标
+ * （例如密集的锯齿路径），再做等间隔兜底。首尾点始终保留，坐标统一取整到
+ * 5 位小数。
+ *
+ * 注意：即使点数没超上限也会跑一遍抽稀——直线上的冗余点同样要丢掉，
+ * 因为产物要写进会话日志。
+ *
+ * @param points - 原始几何点（可为空、可含重复/非法点）。
+ * @param maxPoints - 点数上限，默认 {@link MAX_GEOMETRY_POINTS}。
+ * @returns 抽稀并取整后的几何（点数 ≤ `maxPoints`）。
+ */
+export declare function simplifyGeometry(points: readonly LngLat[], maxPoints?: number): LngLat[];
+/**
+ * 把几何压成高德风格的紧凑串 `"lng,lat;lng,lat"`（日志体积的一档压缩）。
+ * @param points - 已取整的几何点。
+ * @returns 紧凑串；空序列返回空串。
+ */
+export declare function encodeGeometry(points: readonly LngLat[]): string;
+/**
+ * 把高德的长地址裁成可读的短地名。
+ *
+ * 高德反查返回的 `formatted_address` 是"省市区街道 + 具体位置"连写（如
+ * "北京市丰台区右安门街道北京南站"）。把已知的省/市/区/街道前缀依次剥掉、
+ * 再去掉尾部括号补充，剩下的就是用户认得的那个名字。
+ * 剥完为空则原样返回（宁可长，也不要空）。
+ *
+ * @param formatted - 高德 `formatted_address`。
+ * @param strip - 要剥掉的前缀（省 / 市 / 区 / 街道）。
+ * @returns 短地名。
+ */
+export declare function shortPlaceName(formatted: string, strip: readonly (string | undefined)[]): string;
+/**
+ * 抽稀到最多 `maxPoints` 个点，再编成紧凑串（用于塞进 URL query）。
+ * 静态地图不需要 200 个点，太长会把 URL 撑爆。
+ * @param points - 路线几何。
+ * @param maxPoints - 点数上限。
+ * @returns `"lng,lat;…"`。
+ */
+export declare function compactLine(points: readonly LngLat[], maxPoints?: number): string;

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * dsh-map-tools — map & routing tools for DeepSeek Harness.
+ *
+ * Registers 7 native tools:
+ *   map_driving_route / map_transit_route / map_walking_route / map_bicycling_route
+ *   map_geocode / map_reverse_geocode / map_poi_search
+ *
+ * Data sources: OSM/OSRM/Nominatim free fallback by default (zero-key); when
+ * amapKey is configured (or provider='amap'), Amap (高德) is used for best
+ * CN data quality (transit + POI require Amap).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.js';
+import type { Config as ConfigType } from './config.js';
+export declare const name = "dsh-map-tools";
+export declare const inject: string[];
+export { Config };
+export declare function apply(ctx: Context, config: ConfigType): void;

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/settings-ns.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config as ConfigType } from './config.js';
+/** Namespace the settings page keys this plugin's card to (plain string since DSH 0.1.2-rc.1). */
+export declare const MAP_TOOLS_NS = "dsh-map-tools";
+/**
+ * Wire the settings section so the card renders. The values live in the
+ * config file; the section carries only the composition entry as its base so
+ * the page has something to dispatch on.
+ *
+ * @param ctx - plugin context.
+ * @param entry - the composition entry config (schema defaults).
+ * @param reload - rebuild tools after a settings change.
+ */
+export declare function installSettingsNamespace(ctx: Context, entry: ConfigType, reload: () => void): void;

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/staticmap-route.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Loopback route serving the route-card's static map image.
+ *
+ * GET /dsh-map-tools/staticmap?w=640&h=260&line=lng,lat;lng,lat;…
+ *
+ * 为什么走回环路由而不是把图片塞进工具结果：
+ *   1. **key 不出宿主**——浏览器只拿到一张本地图片 URL，高德 key 始终在服务端；
+ *   2. **不进模型上下文**——工具结果里放 image block 会被适配器跳过/或消耗
+ *      视觉额度，而卡片要的只是一张示意图；
+ *   3. **懒加载 + 可缓存**——只有卡片真正渲染时才取图，且服务端按参数缓存。
+ *
+ * 拿不到图（没 key / 配额超限 / 网络问题）时返回错误状态码，客户端卡片会
+ * 自动降级为自绘示意图（client/client.js 里的 svg 兜底）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AmapClient } from './clients/amap.js';
+import { type LngLat } from './types.js';
+/** 解析 `line=lng,lat;lng,lat;…`；非法片段跳过，超过上限则等间隔截断。 */
+export declare function parseLineParam(raw: string | null): LngLat[];
+/** 把尺寸参数钳制到合法范围（默认 640×260）。 */
+export declare function parseSizeParam(w: string | null, h: string | null): {
+    width: number;
+    height: number;
+};
+/**
+ * Register the static-map route under the web server, when one exists.
+ *
+ * @param ctx - plugin context.
+ * @param getAmap - reads the current Amap client (rebuilt on every config save).
+ */
+export declare function installStaticMapRoute(ctx: Context, getAmap: () => AmapClient | undefined): void;

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/tools/geocode.d.ts

@@ -0,0 +1,11 @@
+/** Geocoding tools: address → coordinates, and reverse. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AmapClient } from '../clients/amap.js';
+import type { NominatimClient } from '../clients/nominatim.js';
+import type { PhotonClient } from '../clients/photon.js';
+export interface GeocodeClients {
+    amap?: AmapClient;
+    nominatim?: NominatimClient;
+    photon?: PhotonClient;
+}
+export declare function registerGeocodeTools(ctx: Context, clients: GeocodeClients, disposers?: Array<() => void>): void;

package/ts/dsh-runtime/vendor/dsh-map-tools/lib/types/tools/poi.d.ts

@@ -0,0 +1,9 @@
+/** POI search tool. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AmapClient } from '../clients/amap.js';
+export interface PoiClients {
+    amap?: AmapClient;
+    /** Resolve an address (or `lng,lat`) to coordinates; throws with a helpful message. */
+    resolve: (text: string, signal: AbortSignal) => Promise<[number, number]>;
+}
+export declare function registerPoiTool(ctx: Context, clients: PoiClients, disposers?: Array<() => void>): void;