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

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

@@ -0,0 +1,126 @@
+/**
+ * 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 { spawn } from 'node:child_process';
+import { configSummary, applyConfig, configPath, configFileExists } from './config-file.js';
+/** localhost, ::1, or anything in 127/8 — matching dsh's own /api fence. */
+function isLoopbackHost(hostname) {
+    return hostname === 'localhost' || hostname === '::1' || hostname === '127.0.0.1' || /^127\.\d+\.\d+\.\d+$/.test(hostname);
+}
+/** Refuse cross-origin and non-loopback requests (the route answers same-origin loopback only). */
+function isTrustedRequest(req) {
+    const host = req.headers?.host;
+    if (typeof host !== 'string' || host === '')
+        return false;
+    let hostUrl;
+    try {
+        hostUrl = new URL(`http://${host}`);
+    }
+    catch {
+        return false;
+    }
+    if (!isLoopbackHost(hostUrl.hostname))
+        return false;
+    if (req.headers?.['sec-fetch-site'] === 'cross-site')
+        return false;
+    const origin = req.headers?.origin;
+    if (origin === undefined)
+        return true;
+    try {
+        return new URL(origin).host === hostUrl.host;
+    }
+    catch {
+        return false;
+    }
+}
+/** Open the config file in the OS default editor. */
+function openConfigFile() {
+    const file = configPath();
+    const [command, args] = process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', file]]
+        : process.platform === 'darwin'
+            ? ['open', [file]]
+            : ['xdg-open', [file]];
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.unref();
+}
+/**
+ * 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 function installConfigRoute(ctx, reload = () => { }) {
+    const fn = ctx.inject;
+    fn(['webServer'], (scope) => {
+        scope.webServer.register({
+            kind: 'exact',
+            path: '/dsh-map-tools/config',
+            handler: async (req, res) => {
+                const send = (status, body) => {
+                    res.writeHead(status, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify(body));
+                };
+                if (!isTrustedRequest(req)) {
+                    send(403, { error: 'request refused: this route answers same-origin loopback only' });
+                    return;
+                }
+                if (req.method === 'GET') {
+                    try {
+                        const summary = configSummary();
+                        const wantsOpen = new URL(req.url ?? '/', 'http://localhost').searchParams.has('open');
+                        if (wantsOpen && !configFileExists()) {
+                            applyConfig({});
+                        }
+                        if (wantsOpen)
+                            openConfigFile();
+                        send(200, { ...summary, configPath: configPath() });
+                    }
+                    catch (error) {
+                        send(409, { error: String(error?.message ?? error) });
+                    }
+                    return;
+                }
+                if (req.method !== 'POST') {
+                    res.writeHead(405).end();
+                    return;
+                }
+                try {
+                    const chunks = [];
+                    let total = 0;
+                    for await (const chunk of req) {
+                        total += chunk.length;
+                        if (total > 64 * 1024) {
+                            send(413, { error: 'config payload too large' });
+                            req.destroy();
+                            return;
+                        }
+                        chunks.push(chunk);
+                    }
+                    const patch = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                    applyConfig({
+                        provider: patch.provider,
+                        amapKey: patch.amapKey,
+                        timeoutMs: typeof patch.timeoutMs === 'number' ? patch.timeoutMs : undefined,
+                    });
+                    send(200, configSummary());
+                    // Rebuild the tool instances so the saved provider/key/timeout is
+                    // live immediately (the card tells the user "工具已重建").
+                    reload();
+                }
+                catch (error) {
+                    send(400, { error: String(error?.message ?? error) });
+                }
+            },
+        });
+    });
+}

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

@@ -0,0 +1,16 @@
+/** Plugin configuration schema. */
+import Schema from '@deepseek-ai/schemastery';
+/** Amap apply URL (shown as a clickable link in the settings card). */
+export const AMAP_APPLY_URL = 'https://console.amap.com/dev/key/app';
+export const Config = Schema.object({
+    provider: Schema.union(['amap', 'osm'])
+        .default('amap')
+        .description('数据源：amap=高德地图（推荐，国内数据最全）；osm=免费 OSM 兜底（无需 key，能力有限）'),
+    amapKey: Schema.string()
+        .role('secret')
+        .description(`高德 Web 服务 key。申请：${AMAP_APPLY_URL}（创建应用后选择"Web 服务"类型）`),
+    timeoutMs: Schema.number().default(15000).description('单次请求超时（毫秒）'),
+    maxQps: Schema.number().default(2).description('高德 API 每秒最大请求数（QPS 上限，默认 2 低于高德常见上限 3，防触发 10021 配额错误）'),
+    defaultMode: Schema.union(['driving', 'transit', 'walking', 'bicycling']).default('driving').description('默认路线模式'),
+    language: Schema.union(['zh', 'en']).default('zh').description('返回语言'),
+});

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

@@ -0,0 +1,109 @@
+import { AmapClient } from './clients/amap.js';
+import { OsrmClient } from './clients/osrm.js';
+import { NominatimClient } from './clients/nominatim.js';
+import { PhotonClient } from './clients/photon.js';
+import { registerRouteTools } from './tools/routes.js';
+import { registerGeocodeTools } from './tools/geocode.js';
+import { registerPoiTool } from './tools/poi.js';
+import { parseLngLat } from './types.js';
+import { Config } from './config.js';
+import { readConfig } from './config-file.js';
+import { installConfigRoute } from './config-route.js';
+import { installSettingsNamespace } from './settings-ns.js';
+export const name = 'dsh-map-tools';
+export const inject = ['tools'];
+export { Config };
+/** Build (or rebuild) the provider clients. Priority: config-file (settings
+ * card) → schema defaults. */
+function buildClients(config) {
+    // The settings card writes ~/.dsh-map-tools/config.json; when it holds
+    // values, they win over the composition-entry schema defaults.
+    let fileConfig = {};
+    try {
+        fileConfig = readConfig();
+    }
+    catch (error) {
+        console.error(`[dsh-map-tools] config read failed, using schema defaults: ${error}`);
+    }
+    const provider = fileConfig.provider ?? config.provider;
+    const amapKey = fileConfig.amapKey ?? config.amapKey;
+    const timeoutMs = fileConfig.timeoutMs ?? config.timeoutMs;
+    const maxQps = fileConfig.maxQps ?? config.maxQps;
+    // Provider selection: exactly one primary source per provider.
+    const amap = provider === 'amap' && amapKey
+        ? new AmapClient({ key: amapKey, timeoutMs, maxQps })
+        : undefined;
+    const osrm = new OsrmClient({ timeoutMs });
+    const nominatim = new NominatimClient({
+        timeoutMs,
+        userAgent: 'dsh-map-tools/0.1.0 (DeepSeek Harness plugin; contact: https://github.com/HorusJiang/dsh-map-tools)',
+    });
+    const photon = new PhotonClient({ timeoutMs, lang: config.language });
+    /** Resolve an address (or `lng,lat`) to coordinates, using the active provider. */
+    async function resolve(text, signal) {
+        const coord = parseLngLat(text);
+        if (coord)
+            return coord;
+        if (amap) {
+            const r = await amap.geocode(text, signal);
+            return r.location;
+        }
+        // Free sources cannot reliably geocode Chinese addresses (Nominatim is
+        // blocked on many CN networks, Photon returns 400 for CJK queries) — give
+        // an actionable prompt instead of a raw provider error.
+        throw new Error(`免费数据源无法可靠解析中文地址："${text}"。请直接提供 "lng,lat" 坐标，或在插件配置中设置高德 amapKey（https://console.amap.com/dev/key/app）。`);
+    }
+    /** Resolve the city code for a point (transit queries need city1/city2).
+     *  Amap v5 transit accepts only an adcode (e.g. "110000" / "110101") or a
+     *  citycode (e.g. "010") — bare city names like "北京" are rejected with
+     *  INVALID_PARAMS. Prefer the adcode from geocoding; fall back to the city
+     *  name as a last resort. */
+    async function resolveCity(text, signal) {
+        const coord = parseLngLat(text);
+        if (amap) {
+            const r = coord ? await amap.reverseGeocode(coord, signal) : await amap.geocode(text, signal);
+            if (r.adcode)
+                return r.adcode;
+            const city = r.city ?? '';
+            return city.replace(/市$/, '');
+        }
+        return '';
+    }
+    return { amap, osrm, nominatim, photon, resolve, resolveCity };
+}
+/** Register every tool under the current clients; returns a disposer. */
+function registerAll(ctx, clients) {
+    const disposers = [];
+    const routeClients = {
+        amap: clients.amap,
+        osrm: clients.osrm,
+        resolve: clients.resolve,
+        resolveCity: clients.resolveCity,
+        defaultMode: 'driving',
+    };
+    registerRouteTools(ctx, routeClients, disposers);
+    registerGeocodeTools(ctx, { amap: clients.amap, nominatim: clients.nominatim, photon: clients.photon }, disposers);
+    registerPoiTool(ctx, { amap: clients.amap, resolve: clients.resolve }, disposers);
+    return () => {
+        for (const d of disposers)
+            d();
+    };
+}
+export function apply(ctx, config) {
+    // Register tools under an effect: Cordis runs the returned disposer both on
+    // explicit reload (we call it) and on plugin unload (fiber disposal).
+    let disposeTools = () => { };
+    ctx.effect(() => {
+        disposeTools = registerAll(ctx, buildClients(config));
+        return () => disposeTools();
+    });
+    const reload = () => {
+        disposeTools();
+        disposeTools = registerAll(ctx, buildClients(config));
+    };
+    // The settings card route + namespace (modlens pattern): the card reads and
+    // writes ~/.dsh-map-tools/config.json through the loopback route, and the
+    // tools rebuild on a save (route POST → reload).
+    installConfigRoute(ctx, reload);
+    installSettingsNamespace(ctx, config, reload);
+}

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

@@ -0,0 +1,27 @@
+import { Config as ConfigSchema } from './config.js';
+/** Namespace the settings page keys this plugin's card to (plain string since DSH 0.1.2-rc.1). */
+export 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 function installSettingsNamespace(ctx, entry, reload) {
+    ctx.inject(['settings'], (scope) => {
+        scope.settings.installSection(ctx, MAP_TOOLS_NS, ConfigSchema, entry, {
+            setSource: (current) => {
+                // The tools read ~/.dsh-map-tools/config.json then the composition
+                // entry; the section's own value is a dispatch key for the card and
+                // is never a tool configuration source.
+                void current;
+            },
+            onChange: () => {
+                reload();
+            },
+        });
+    });
+}

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

@@ -0,0 +1,127 @@
+/** Geocoding tools: address → coordinates, and reverse. */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { parseLngLat } from '../types.js';
+export function registerGeocodeTools(ctx, clients, disposers = []) {
+    disposers.push(ctx.tools.register(defineTool({
+        name: 'map_geocode',
+        description: '把地址文本转换为经纬度坐标。支持中文地址、模糊地址。',
+        parameters: {
+            address: { type: 'string', required: true, description: '地址文本，如 "北京市朝阳区建国路88号"。' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    provider: { type: 'string' },
+                    formatted: { type: 'string' },
+                    location: {
+                        type: 'array',
+                        items: { type: 'number' },
+                    },
+                    city: { type: 'string' },
+                    district: { type: 'string' },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                const name = v.provider === 'amap' ? '高德' : v.provider === 'nominatim' ? 'Nominatim(OSM)' : v.provider === 'photon' ? 'Photon(OSM)' : 'inline';
+                const area = v.city ? `（${v.city}${v.district ? ` ${v.district}` : ''}）` : '';
+                return [{
+                        type: 'text',
+                        text: `${name} 解析 "${v.formatted}" → 经纬度 ${v.location[0]}, ${v.location[1]}${area}`,
+                    }];
+            },
+        },
+        async execute(args, exec) {
+            const coord = parseLngLat(args.address);
+            if (coord) {
+                // Input already looks like coordinates — return as-is.
+                return { provider: 'inline', formatted: args.address, location: coord };
+            }
+            if (clients.amap) {
+                const r = await clients.amap.geocode(args.address, exec.signal);
+                return { provider: r.provider, formatted: r.formatted, location: r.location, city: r.city, district: r.district };
+            }
+            // Free sources (Photon/Nominatim) are unreliable for Chinese addresses.
+            // Try them, but convert any failure into an actionable prompt.
+            let lastError = '免费地理编码服务不可用';
+            if (clients.photon) {
+                try {
+                    const r = await clients.photon.geocode(args.address, exec.signal);
+                    return { provider: r.provider, formatted: r.formatted, location: r.location, city: r.city, district: r.district };
+                }
+                catch (err) {
+                    lastError = err instanceof Error ? err.message : String(err);
+                }
+            }
+            if (clients.nominatim) {
+                try {
+                    const r = await clients.nominatim.geocode(args.address, exec.signal);
+                    return { provider: r.provider, formatted: r.formatted, location: r.location, city: r.city, district: r.district };
+                }
+                catch (err) {
+                    lastError = err instanceof Error ? err.message : String(err);
+                }
+            }
+            throw new Error(`免费数据源无法可靠解析中文地址："${args.address}"（${lastError}）。请直接提供 "lng,lat" 坐标，或在插件配置中设置高德 amapKey（https://console.amap.com/dev/key/app）。`);
+        },
+    })));
+    disposers.push(ctx.tools.register(defineTool({
+        name: 'map_reverse_geocode',
+        description: '把经纬度坐标转换为结构化地址（含城市、区县）。',
+        parameters: {
+            location: { type: 'string', required: true, description: '经纬度，格式 "lng,lat"，如 "116.397428,39.90923"。' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    provider: { type: 'string' },
+                    formatted: { type: 'string' },
+                    location: {
+                        type: 'array',
+                        items: { type: 'number' },
+                    },
+                    city: { type: 'string' },
+                    district: { type: 'string' },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                const name = v.provider === 'amap' ? '高德' : v.provider === 'nominatim' ? 'Nominatim(OSM)' : v.provider === 'photon' ? 'Photon(OSM)' : '未知';
+                return [{ type: 'text', text: `${name}：${v.formatted}` }];
+            },
+        },
+        async execute(args, exec) {
+            const coord = parseLngLat(args.location);
+            if (!coord)
+                throw new Error(`无效的经纬度格式：${args.location}（应为 "lng,lat"）`);
+            if (clients.amap) {
+                const r = await clients.amap.reverseGeocode(coord, exec.signal);
+                return { provider: r.provider, formatted: r.formatted, location: r.location, city: r.city, district: r.district };
+            }
+            let lastError = '免费地理编码服务不可用';
+            if (clients.photon) {
+                try {
+                    const r = await clients.photon.reverseGeocode(coord, exec.signal);
+                    return { provider: r.provider, formatted: r.formatted, location: r.location, city: r.city, district: r.district };
+                }
+                catch (err) {
+                    lastError = err instanceof Error ? err.message : String(err);
+                }
+            }
+            if (clients.nominatim) {
+                try {
+                    const r = await clients.nominatim.reverseGeocode(coord, exec.signal);
+                    return { provider: r.provider, formatted: r.formatted, location: r.location, city: r.city, district: r.district };
+                }
+                catch (err) {
+                    lastError = err instanceof Error ? err.message : String(err);
+                }
+            }
+            throw new Error(`免费逆地理编码服务不可用（${lastError}）。请配置高德 amapKey（https://console.amap.com/dev/key/app）以获得稳定结果。`);
+        },
+    })));
+}

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

@@ -0,0 +1,84 @@
+/** POI search tool. */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { parseLngLat } from '../types.js';
+export function registerPoiTool(ctx, clients, disposers = []) {
+    disposers.push(ctx.tools.register(defineTool({
+        name: 'map_poi_search',
+        description: '搜索兴趣点（POI）：餐厅、加油站、酒店、医院等。支持按关键词搜索或按位置周边搜索。',
+        parameters: {
+            keywords: { type: 'string', required: true, description: '搜索关键词，如 "加油站"、"咖啡"、"北京南站"。' },
+            location: {
+                type: 'string',
+                description: '中心点："lng,lat" 坐标或地址文本。提供后按周边搜索（默认半径 1000 米）。',
+            },
+            radiusM: { type: 'number', description: '周边搜索半径（米），默认 1000，最大 50000。' },
+            region: { type: 'string', description: '限定城市（文本搜索时），如 "北京"。' },
+            types: { type: 'string', description: 'POI 类型编码，如 "060000"（餐饮）。' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    count: { type: 'number' },
+                    results: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                name: { type: 'string' },
+                                location: {
+                                    type: 'array',
+                                    items: { type: 'number' },
+                                },
+                                type: { type: 'string' },
+                                address: { type: 'string' },
+                                tel: { type: 'string' },
+                                distanceM: { type: 'number' },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                const lines = [`找到 ${v.count} 个结果：`];
+                for (const r of v.results.slice(0, 10)) {
+                    const d = r.distanceM !== undefined ? `（距中心 ${Math.round(r.distanceM)} 米）` : '';
+                    const tel = r.tel ? ` 电话：${r.tel}` : '';
+                    lines.push(`- ${r.name}${d}${r.type ? ` [${r.type}]` : ''}${r.address ? ` ${r.address}` : ''}${tel}`);
+                }
+                if (v.results.length > 10)
+                    lines.push(`- …（还有 ${v.results.length - 10} 个）`);
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(args, exec) {
+            if (!clients.amap)
+                throw new Error('POI 搜索需要配置高德 amapKey。申请：https://console.amap.com/dev/key/app');
+            let results;
+            if (args.location) {
+                const center = parseLngLat(args.location) ?? (await clients.resolve(args.location, exec.signal));
+                results = await clients.amap.poiAround(center, args.keywords, {
+                    radiusM: args.radiusM ?? 1000,
+                    types: args.types,
+                }, exec.signal);
+            }
+            else {
+                results = await clients.amap.poiSearch(args.keywords, { region: args.region, cityLimit: !!args.region }, exec.signal);
+            }
+            return {
+                count: results.length,
+                results: results.map((r) => ({
+                    name: r.name,
+                    location: r.location,
+                    type: r.type,
+                    address: r.address,
+                    tel: r.tel,
+                    distanceM: r.distanceM,
+                })),
+            };
+        },
+    })));
+}

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

@@ -0,0 +1,170 @@
+/** 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';
+function routeTool(name, description, mode, clients) {
+    const osrmProfile = mode === 'walking' ? 'walking' : mode === 'bicycling' ? 'cycling' : 'driving';
+    return defineTool({
+        name,
+        description,
+        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' },
+                    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}`,
+                ];
+                for (const s of v.steps.slice(0, 12)) {
+                    lines.push(`- ${s.instruction}`);
+                }
+                if (v.steps.length > 12)
+                    lines.push(`- …（共 ${v.steps.length} 步）`);
+                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') }];
+            },
+        },
+        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;
+            }
+            // 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 = {
+                        provider: result.provider,
+                        distanceM: result.distanceM,
+                        durationS: result.durationS,
+                        polyline: result.polyline,
+                        steps: result.steps,
+                    };
+                    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 {
+                            provider: result.provider,
+                            distanceM: result.distanceM,
+                            durationS: result.durationS,
+                            polyline: result.polyline,
+                            steps: result.steps,
+                        };
+                    }
+                    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 {
+                provider: result.provider,
+                distanceM: result.distanceM,
+                durationS: result.durationS,
+                polyline: result.polyline,
+                steps: result.steps,
+            };
+        },
+    });
+}
+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)));
+}