feat: add LocationTool — geographic search with Amap/Google Maps

Add a new LocationTool supporting geocoding, POI search, directions,
and trip planning. Automatically selects Amap (China) or Google Maps
(international) based on region detection.

Co-Authored-By: Claude Big Pickle <noreply@anthropic.com>

docs/tools/overview.md

@@ -202,6 +202,7 @@ LLM 请求工具调用
 | `SkillToolProgress` | 技能执行进度 | SkillTool |
 | `TaskOutputProgress` | 后台任务输出进度 | TaskOutputTool |
 | `WebSearchProgress` | 网络搜索进度 | WebSearchTool |
+| `LocationToolProgress` | 地理位置搜索进度 | LocationTool |
 | `REPLToolProgress` | REPL 工具进度 | REPLTool |
 | `HookProgress` | 钩子执行进度 | Hooks |
 
@@ -267,3 +268,61 @@ WebSearchTool 支持两个搜索后端：
 - `/home/yuki/Code/Agent/VersperClaw/src/tools.ts` — 工具注册与过滤
 - `/home/yuki/Code/Agent/VersperClaw/src/services/tools/toolExecution.ts` — 执行引擎
 - `/home/yuki/Code/Agent/VersperClaw/src/services/tools/toolHooks.ts` — 工具钩子
+
+---
+
+### LocationTool
+
+地理位置与地图搜索工具。根据地区自动选择地图服务商：
+
+| 地区 | 服务商 | 环境变量 |
+|------|--------|----------|
+| 中国大陆 | 高德地图 (Amap) | `AMAP_API_KEY` |
+| 海外 | Google Maps | `GOOGLE_MAPS_API_KEY` |
+
+**支持的操作：**
+
+| 动作 | 功能 | Amap API | Google API |
+|------|------|----------|------------|
+| `locate` | IP 地理定位 (无需 location 参数) | — | — |
+| `geocode` | 地址→坐标 | 地理编码 | Geocoding |
+| `search_places` | 周边/关键词搜索 POI | POI 周边搜索 | Places / Nearby Search |
+| `get_directions` | 两点间路线规划 | 驾车/公交路径规划 | Directions |
+| `plan_trip` | 多途经点行程规划 | 分段路径拼接 | 多航点 Directions |
+
+**地区自动检测：** 含中文字符或已知中国城市名 → Amap，否则 → Google。支持 `region` 参数强制指定。
+
+**配合搜索工具：** Prompt 层面指导模型在获取地点后，可调用 WebSearchTool 查攻略/评价，或用 WebFetchTool 获取详情页内容。
+
+**输入参数：** `action` (必填), `location` (必填), `destination`, `query`, `radius` (默认 5000m), `mode` (driving/walking/transit/bicycling), `waypoints`, `type` (Amap POI 类型过滤), `region` (强制指定), `language`
+
+相关文件：
+- `/home/yuki/Code/Agent/VersperClaw/src/tools/LocationTool/LocationTool.ts` — 主工具逻辑
+- `/home/yuki/Code/Agent/VersperClaw/src/tools/LocationTool/prompt.ts` — 提示词
+- `/home/yuki/Code/Agent/VersperClaw/src/tools/LocationTool/UI.tsx` — 渲染组件
+
+#### API Key 申请指南
+
+**高德地图 API Key（中国大陆用）**
+
+1. **注册账号** — 打开 [高德开放平台](https://lbs.amap.com/)，点击右上角「注册」
+2. **创建应用** — 登录后进入控制台 → 「应用管理」→ 「创建新应用」
+3. **添加 Key** — 在创建的应用中点击「添加 Key」→ 服务平台选择 **「Web 服务」**
+4. **获取 Key** — 创建成功后复制 Key，设为环境变量：
+   ```bash
+   export AMAP_API_KEY=你的高德Key
+   ```
+
+**Google Maps API Key（海外用）**
+
+1. **创建项目** — 打开 [Google Cloud Console](https://console.cloud.google.com/)，创建新项目
+2. **启用 API** — 进入「API 和服务」→「库」，搜索并启用以下 API：
+   - **Geocoding API**（地址 → 坐标）
+   - **Places API**（地点搜索）
+   - **Directions API**（路线规划）
+3. **创建凭据** — 「API 和服务」→「凭据」→「创建凭据」→「API 密钥」
+4. **限制密钥**（强烈建议）— 在凭据页面设置 API 限制，仅允许上面启用的三个 API，避免滥用
+5. 设为环境变量：
+   ```bash
+   export GOOGLE_MAPS_API_KEY=你的GoogleKey
+   ```

docs/tools/tool-reference.md

@@ -35,6 +35,7 @@
 |----------|------|----------|----------|
 | **WebSearch** (WebSearchTool) | 搜索 | 执行网络搜索。支持 Tavily API 和本地 SearXNG 两种后端（优先本地 SearXNG） | `query` (必填, 最少 2 字符) |
 | **WebFetch** (WebFetchTool) | 搜索 | 抓取指定 URL 的内容，并对内容执行 prompt 处理（提取、总结等） | `url` (必填), `prompt` (必填) |
+| **LocationTool** (LocationTool) | 搜索 | 地理位置与地图搜索。中国大陆使用高德地图，海外使用 Google Maps。支持地理编码、POI 搜索、路线规划、行程规划 | `action` (必填), `location` (必填), `destination`, `query`, `radius`, `mode`, `waypoints`, `type`, `region`, `language` |
 | **ToolSearch** (ToolSearchTool) | 搜索 | 搜索延迟加载的工具。当 ToolSearch 启用时，部分工具的 schema 不会随初始提示发送，需通过此工具查询后再调用 | `query` (必填, 支持 "select:name" 精确选择), `max_results` (默认 5) |
 
 ---

src/constants/tools.ts

@@ -8,6 +8,7 @@ import { ASK_USER_QUESTION_TOOL_NAME } from '../tools/AskUserQuestionTool/prompt
 import { TASK_STOP_TOOL_NAME } from '../tools/TaskStopTool/prompt.js'
 import { FILE_READ_TOOL_NAME } from '../tools/FileReadTool/prompt.js'
 import { WEB_SEARCH_TOOL_NAME } from '../tools/WebSearchTool/prompt.js'
+import { LOCATION_TOOL_NAME } from '../tools/LocationTool/prompt.js'
 import { TODO_WRITE_TOOL_NAME } from '../tools/TodoWriteTool/constants.js'
 import { GREP_TOOL_NAME } from '../tools/GrepTool/prompt.js'
 import { WEB_FETCH_TOOL_NAME } from '../tools/WebFetchTool/prompt.js'
@@ -55,6 +56,7 @@ export const CUSTOM_AGENT_DISALLOWED_TOOLS = new Set([
 export const ASYNC_AGENT_ALLOWED_TOOLS = new Set([
   FILE_READ_TOOL_NAME,
   WEB_SEARCH_TOOL_NAME,
+  LOCATION_TOOL_NAME,
   TODO_WRITE_TOOL_NAME,
   GREP_TOOL_NAME,
   WEB_FETCH_TOOL_NAME,

src/tools.ts

@@ -80,6 +80,7 @@ import { ReadMcpResourceTool } from './tools/ReadMcpResourceTool/ReadMcpResource
 import { ToolSearchTool } from './tools/ToolSearchTool/ToolSearchTool.js'
 import { DebugSessionTool } from './tools/DebugSessionTool.js'
 import { FriendEmotionTool } from './tools/FriendEmotionTool.js'
+import { LocationTool } from './tools/LocationTool/LocationTool.js'
 // Friend ScreenObserve removed — voice + emotion only
 import { EnterPlanModeTool } from './tools/EnterPlanModeTool/EnterPlanModeTool.js'
 import { EnterWorktreeTool } from './tools/EnterWorktreeTool/EnterWorktreeTool.js'
@@ -252,6 +253,8 @@ export function getAllBaseTools(): Tools {
     DebugSessionTool,
     // Friend VRM desktop pet tools — enabled when the plugin is active
     FriendEmotionTool,
+    // Location & mapping tool — uses Amap (China) or Google Maps (international)
+    LocationTool,
     ListMcpResourcesTool,
     ReadMcpResourceTool,
     // Include ToolSearchTool when tool search might be enabled (optimistic check)

src/tools/LocationTool/LocationTool.ts

@@ -0,0 +1,1083 @@
+import { z } from 'zod/v4'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { logError } from '../../utils/log.js'
+import { LOCATION_TOOL_NAME, PROMPT } from './prompt.js'
+import {
+  getToolUseSummary,
+  renderToolResultMessage,
+  renderToolUseMessage,
+  renderToolUseProgressMessage,
+} from './UI.js'
+
+// ── Region detection ────────────────────────────────────────────────────────
+
+/** Chinese cities known to be in mainland China */
+const CHINA_CITIES = new Set([
+  '北京', '上海', '广州', '深圳', '成都', '杭州', '武汉', '西安', '重庆',
+  '南京', '天津', '苏州', '长沙', '郑州', '东莞', '青岛', '沈阳', '宁波',
+  '昆明', '大连', '厦门', '合肥', '佛山', '福州', '哈尔滨', '济南', '温州',
+  '长春', '石家庄', '常州', '泉州', '南宁', '贵阳', '南昌', '太原', '烟台',
+  '嘉兴', '南通', '金华', '珠海', '惠州', '徐州', '海口', '乌鲁木齐', '绍兴',
+  '中山', '台州', '兰州', 'beijing', 'shanghai', 'guangzhou', 'shenzhen',
+  'chengdu', 'hangzhou', 'wuhan', 'xi\'an', 'chongqing', 'nanjing',
+  'tianjin', 'suzhou', 'changsha', 'zhengzhou', 'qingdao', 'shenyang',
+  'kunming', 'dalian', 'xiamen', 'hefei', 'foshan', 'fuzhou', 'harbin',
+  'jinan', 'changchun', 'shijiazhuang', 'nanning', 'guiyang', 'nanchang',
+  'taiyuan', 'haikou', 'urumqi', 'lanzhou', 'macau', 'macao', 'hong kong',
+  'xianggang',
+])
+
+const NON_CHINA_COUNTRIES = new Set([
+  'japan', 'korea', 'south korea', 'usa', 'united states', 'uk', 'united kingdom',
+  'france', 'germany', 'italy', 'spain', 'australia', 'canada', 'brazil',
+  'india', 'thailand', 'vietnam', 'singapore', 'malaysia', 'indonesia',
+  'philippines', 'russia', 'mexico', 'turkey', 'egypt', 'switzerland',
+  'sweden', 'norway', 'finland', 'denmark', 'netherlands', 'belgium',
+  'portugal', 'greece', 'ireland', 'new zealand', 'argentina', 'chile',
+  'peru', 'colombia', 'south africa', 'nigeria', 'kenya', 'morocco',
+  '美国', '日本', '韩国', '英国', '法国', '德国', '意大利', '西班牙',
+  '澳大利亚', '加拿大', '巴西', '印度', '泰国', '越南', '新加坡',
+  '马来西亚', '俄罗斯', '土耳其', '埃及', '瑞士', '荷兰', '新西兰',
+])
+
+function isChinaMainland(location: string): boolean {
+  // Normalize curly/smart quotes to straight quotes for matching
+  const normalized = location.replace(/[\u2018\u2019]/g, "'")
+
+  // Contains Chinese characters → likely China
+  if (/[\u4e00-\u9fff]/.test(normalized)) {
+    // Check for non-China country names in Chinese
+    const lower = normalized.toLowerCase()
+    for (const country of NON_CHINA_COUNTRIES) {
+      if (lower.includes(country)) return false
+    }
+    return true
+  }
+
+  const lower = normalized.toLowerCase().trim()
+
+  // Check Chinese city names
+  for (const city of CHINA_CITIES) {
+    if (lower.startsWith(city) || lower.includes(` ${city}`) || lower.includes(`, ${city}`)) {
+      return true
+    }
+  }
+
+  // If it looks like a country name, check against known non-China list
+  if (NON_CHINA_COUNTRIES.has(lower)) return false
+
+  // Default: if location is purely alphabetic/pinyin, assume non-China
+  return false
+}
+
+/** Parse "lat,lng" coordinate string (e.g. "34.2583,108.9286") */
+function parseCoords(input: string): { lat: number; lng: number } | null {
+  const trimmed = input.trim()
+  const match = trimmed.match(/^(-?\d+\.?\d*)\s*[,，]\s*(-?\d+\.?\d*)$/)
+  if (!match) return null
+  const lat = parseFloat(match[1])
+  const lng = parseFloat(match[2])
+  if (isNaN(lat) || isNaN(lng)) return null
+  if (lat < -90 || lat > 90 || lng < -180 || lng > 180) return null
+  return { lat, lng }
+}
+
+/** Detect China mainland from coordinates (rough bounding box) */
+function isChinaCoords(lat: number, lng: number): boolean {
+  return lat >= 18 && lat <= 54 && lng >= 73 && lng <= 135
+}
+
+/** Build a LocationResult from parsed coordinates */
+function coordsToLocation(lat: number, lng: number): LocationResult {
+  return {
+    lat,
+    lng,
+    formattedAddress: `${lat.toFixed(6)}, ${lng.toFixed(6)}`,
+    displayName: `${lat.toFixed(6)}, ${lng.toFixed(6)}`,
+  }
+}
+
+/** IP geolocation result for the locate action */
+type IpGeoInfo = {
+  ip: string
+  city: string
+  region: string
+  country: string
+  lat?: number
+  lng?: number
+}
+
+/** Scan nearby WiFi access points via nmcli */
+async function scanWiFi(): Promise<{ macAddress: string; signalStrength: number }[]> {
+  try {
+    const cmd = new Deno.Command('nmcli', {
+      args: ['-t', '-f', 'BSSID,SIGNAL', 'device', 'wifi', 'list'],
+      stdout: 'piped',
+      stderr: 'null',
+    })
+    const { stdout } = await cmd.output()
+    const text = new TextDecoder().decode(stdout)
+    return text.trim().split('\n')
+      .filter(Boolean)
+      .map(line => {
+        // nmcli -t escapes colons inside values as \:, split on unescaped :
+        const fields = line.split(/(?<!\\):/)
+        if (fields.length < 2) return null
+        const bssid = fields[0].replace(/\\([\da-fA-F]{2})/g, (_, h) => String.fromCharCode(parseInt(h, 16)))
+        const signal = parseInt(fields[1], 10)
+        if (isNaN(signal)) return null
+        return { macAddress: bssid, signalStrength: signal }
+      })
+      .filter((a): a is NonNullable<typeof a> => a !== null)
+  } catch {
+    return []
+  }
+}
+
+/** Google Geolocation API — uses WiFi AP data for precise positioning */
+// Amap Wi‑Fi 基站定位（国内）— 使用 apilocate.amap.com/position（GET）
+async function amapWiFiGeolocateAPI(wifiAPs: { macAddress: string; signalStrength: number }[]): Promise<{ lat: number; lng: number; accuracy: number } | null> {
+  const key = process.env.AMAP_API_KEY
+  if (!key) return null
+  try {
+    if (wifiAPs.length < 2) return null // Amap 要求至少 2 个 AP
+
+    // 构造 macs 参数：mac1,signal1,ssid1|mac2,signal2,ssid2|...
+    // signal 为负 dBm（nmcli 返回 0‑100，取负作为近似值）
+    const macs = wifiAPs.slice(0, 30).map(ap =>
+      `${ap.macAddress},${-ap.signalStrength},`
+    ).join('|')
+
+    const params = new URLSearchParams({
+      key,
+      accesstype: '1',
+      cdma: '0',
+      macs,
+      output: 'json',
+    })
+
+    const res = await fetch(`https://apilocate.amap.com/position?${params}`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(10000),
+    })
+    if (!res.ok) return null
+    const data = await res.json() as any
+    // Amap 返回 { status: "1", info: "OK", result: { location: "lng,lat", radius: number, ... } }
+    if (data.status === '1' && data.result?.location) {
+      const [lng, lat] = data.result.location.split(',').map(Number)
+      if (!isNaN(lat) && !isNaN(lng)) {
+        return {
+          lat,
+          lng,
+          accuracy: data.result.radius || 0,
+        }
+      }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+// Google Geolocation API（海外）
+async function googleGeolocateAPI(wifiAPs: { macAddress: string; signalStrength: number }[]): Promise<{ lat: number; lng: number; accuracy: number } | null> {
+  const key = process.env.GOOGLE_MAPS_API_KEY
+  if (!key) return null
+  try {
+    const body: any = {}
+    if (wifiAPs.length > 0) {
+      body.wifiAccessPoints = wifiAPs.slice(0, 20)
+      body.considerIp = false
+    } else {
+      body.considerIp = true
+    }
+    const res = await fetch('https://www.googleapis.com/geolocation/v1/geolocate?key=' + key, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(10000),
+    })
+    if (!res.ok) return null
+    const data = await res.json() as any
+    if (data.location?.lat && data.location?.lng) {
+      return {
+        lat: data.location.lat,
+        lng: data.location.lng,
+        accuracy: data.accuracy || 0,
+      }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Detect user location via IP (3 fallback services).
+ * Only used by the explicit `locate` action.
+ */
+async function ipGeolocate(): Promise<IpGeoInfo> {
+  const services = [
+    'https://ipinfo.io/json',
+    'https://ipapi.co/json/',
+    'http://ip-api.com/json/',
+  ]
+  for (const url of services) {
+    try {
+      const res = await fetch(url, {
+        headers: { 'Accept': 'application/json' },
+        signal: AbortSignal.timeout(5000),
+      })
+      if (!res.ok) continue
+      const data = await res.json() as any
+
+      // ipinfo.io
+      if (data.city) {
+        const loc = data.loc?.split(',').map(Number) as [number, number] | undefined
+        return {
+          ip: data.ip || 'unknown',
+          city: data.city,
+          region: data.region || '',
+          country: data.country || '',
+          lat: loc?.[0],
+          lng: loc?.[1],
+        }
+      }
+      // ipapi.co
+      if (data.city) {
+        return {
+          ip: data.ip || 'unknown',
+          city: data.city,
+          region: data.region || '',
+          country: data.country_name || data.country || '',
+          lat: data.latitude,
+          lng: data.longitude,
+        }
+      }
+      // ip-api.com
+      if (data.city) {
+        return {
+          ip: data.query || 'unknown',
+          city: data.city,
+          region: data.regionName || data.region || '',
+          country: data.country || '',
+          lat: data.lat,
+          lng: data.lon,
+        }
+      }
+    } catch {
+      continue
+    }
+  }
+  throw new Error('Could not determine location via IP (all geolocation services failed)')
+}
+
+// ── Input / Output schemas ───────────────────────────────────────────────────
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    action: z.enum(['geocode', 'search_places', 'get_directions', 'plan_trip', 'locate'])
+      .describe('The action to perform'),
+    location: z.any().optional().default('').describe('The location name, address, or origin for directions (optional for locate; defaults to empty string)'),
+    destination: z.string().optional()
+      .describe('Destination location (required for get_directions and plan_trip)'),
+    query: z.string().optional()
+      .describe('Search query for places (e.g., restaurants, attractions, hotels). Required for search_places'),
+    radius: z.number().min(1).max(50000).optional().default(5000)
+      .describe('Search radius in meters (default: 5000, max: 50000)'),
+    mode: z.enum(['driving', 'walking', 'transit', 'bicycling']).optional().default('driving')
+      .describe('Transport mode for directions (default: driving)'),
+    waypoints: z.array(z.string()).max(10).optional()
+      .describe('Intermediate stops for multi-city trip planning (max 10)'),
+    type: z.string().optional()
+      .describe('POI type filter for Amap (e.g., 餐饮, 酒店, 景点, 购物). Only applies to China locations'),
+    region: z.enum(['china', 'international']).optional()
+      .describe('Force region. Auto-detected if not specified'),
+    language: z.string().optional().default('zh-CN')
+      .describe('Response language (default: zh-CN)'),
+  }),
+)
+
+type Input = z.infer<ReturnType<typeof inputSchema>>
+
+type LocationResult = {
+  lat: number
+  lng: number
+  formattedAddress: string
+  displayName: string
+}
+
+type PlaceResult = {
+  name: string
+  address: string
+  lat: number
+  lng: number
+  rating?: number
+  types?: string[]
+  phone?: string
+  website?: string
+  openingHours?: string
+  photos?: string[]
+  /** Amap-specific fields */
+  distance?: string
+  businessArea?: string
+  cost?: string
+  recommendation?: string
+  tag?: string
+}
+
+type DirectionStep = {
+  instruction: string
+  distance: string
+  duration: string
+  mode?: string
+  polyline?: string
+}
+
+type DirectionLeg = {
+  steps: DirectionStep[]
+  distance: string
+  duration: string
+  startAddress: string
+  endAddress: string
+}
+
+type DirectionsResult = {
+  origin: string
+  destination: string
+  mode: string
+  legs: DirectionLeg[]
+  totalDistance: string
+  totalDuration: string
+  polyline?: string
+  transitInfo?: string
+  tolls?: string
+  trafficRestriction?: string
+}
+
+type Output = {
+  action: string
+  region: 'china' | 'international'
+  geocoding?: LocationResult
+  places?: PlaceResult[]
+  directions?: DirectionsResult
+  error?: string
+  rawData?: unknown
+  ipGeo?: IpGeoInfo
+}
+
+// ── Amap API helpers ─────────────────────────────────────────────────────────
+
+function getAmapKey(): string {
+  const key = process.env.AMAP_API_KEY
+  if (!key) throw new Error('AMAP_API_KEY environment variable is not set')
+  return key
+}
+
+async function amapGeocode(location: string, city?: string): Promise<LocationResult> {
+  const key = getAmapKey()
+  const params = new URLSearchParams({ key, address: location })
+  if (city) params.set('city', city)
+
+  const res = await fetch(`https://restapi.amap.com/v3/geocode/geo?${params}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(10000),
+  })
+  if (!res.ok) throw new Error(`Amap geocode HTTP ${res.status}`)
+
+  const data = await res.json() as any
+  if (data.status !== '1' || !data.geocodes?.length) {
+    throw new Error(`Amap geocode failed: ${data.info || 'no results'}`)
+  }
+
+  const [lng, lat] = data.geocodes[0].location.split(',').map(Number)
+  return {
+    lat,
+    lng,
+    formattedAddress: data.geocodes[0].formatted_address || location,
+    displayName: data.geocodes[0].formatted_address || location,
+  }
+}
+
+async function amapSearchPlaces(
+  location: string,
+  query?: string,
+  type?: string,
+  radius?: number,
+  /** Pre-resolved coordinates (skip geocoding) */
+  geo?: LocationResult,
+): Promise<PlaceResult[]> {
+  const key = getAmapKey()
+
+  // Use pre-resolved coordinates if available, otherwise geocode
+  const resolved = geo ?? await amapGeocode(location)
+
+  const params = new URLSearchParams({
+    key,
+    location: `${resolved.lng},${resolved.lat}`,
+    radius: String(radius || 5000),
+    offset: '25',
+    page: '1',
+    extensions: 'all',
+  })
+  if (query) params.set('keywords', query)
+  if (type) params.set('types', type)
+
+  const res = await fetch(`https://restapi.amap.com/v3/place/around?${params}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15000),
+  })
+
+  if (!res.ok) throw new Error(`Amap around search HTTP ${res.status}`)
+  const data = await res.json() as any
+
+  if (data.status !== '1') {
+    throw new Error(`Amap search failed: ${data.info}`)
+  }
+
+  return (data.pois || []).map((poi: any) => ({
+    name: poi.name,
+    address: poi.address || '',
+    lat: parseFloat(poi.location?.split(',')[1] || '0'),
+    lng: parseFloat(poi.location?.split(',')[0] || '0'),
+    distance: poi.distance,
+    businessArea: poi.business_area,
+    cost: poi.cost,
+    type: poi.type,
+    tag: (poi.type || '').split(';').filter(Boolean).join(', '),
+    photos: (poi.photos || []).map((p: any) => p.url).filter(Boolean),
+    openingHours: poi.opentime || poi.biz_ext?.opentime,
+    recommendation: poi.recommend || poi.biz_ext?.rating,
+  }))
+}
+
+async function amapDirections(
+  origin: string,
+  destination: string,
+  mode: string,
+  /** Pre-resolved origin coordinates (skip geocoding) */
+  origGeo?: LocationResult,
+  /** Pre-resolved destination coordinates (skip geocoding) */
+  destGeo?: LocationResult,
+): Promise<DirectionsResult> {
+  const key = getAmapKey()
+  const originGeo = origGeo ?? await amapGeocode(origin)
+  const destinationGeo = destGeo ?? await amapGeocode(destination)
+
+  // Map our mode to Amap mode
+  const amapMode = mode === 'transit' ? 'transit' : 'driving'
+  const apiUrl = amapMode === 'transit'
+    ? 'https://restapi.amap.com/v3/direction/transit/integrated'
+    : 'https://restapi.amap.com/v3/direction/driving'
+
+  const params = new URLSearchParams({
+    key,
+    origin: `${originGeo.lng},${originGeo.lat}`,
+    destination: `${destinationGeo.lng},${destinationGeo.lat}`,
+    extensions: 'all',
+    strategy: '0',
+  })
+
+  if (amapMode === 'transit') {
+    params.set('city', '')
+    params.set('cityd', '')
+  }
+
+  const res = await fetch(`${apiUrl}?${params}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15000),
+  })
+
+  if (!res.ok) throw new Error(`Amap directions HTTP ${res.status}`)
+  const data = await res.json() as any
+
+  if (data.status !== '1' || !data.route) {
+    throw new Error(`Amap directions failed: ${data.info || 'no route'}`)
+  }
+
+  const route = data.route
+  const path = route.paths?.[0] || route.transits?.[0]
+  if (!path) throw new Error('No route found')
+
+  const legs: DirectionLeg[] = [{
+    steps: (path.steps || []).map((s: any) => ({
+      instruction: s.instruction || '',
+      distance: `${(parseFloat(s.distance) / 1000).toFixed(1)} km`,
+      duration: `${Math.round(parseFloat(s.duration) / 60)} min`,
+      polyline: s.polyline,
+    })),
+    distance: `${(parseFloat(path.distance) / 1000).toFixed(1)} km`,
+    duration: `${Math.round(parseFloat(path.duration) / 60)} min`,
+    startAddress: origin,
+    endAddress: destination,
+  }]
+
+  const result: DirectionsResult = {
+    origin,
+    destination,
+    mode,
+    legs,
+    totalDistance: legs[0].distance,
+    totalDuration: legs[0].duration,
+  }
+
+  if (amapMode === 'transit') {
+    result.transitInfo = `Transit: ${path.transit_mode || 'public transport'}`
+    result.tolls = path.tolls ? `¥${path.tolls}` : undefined
+  }
+
+  return result
+}
+
+// ── Google Maps API helpers ───────────────────────────────────────────────────
+
+function getGoogleKey(): string {
+  const key = process.env.GOOGLE_MAPS_API_KEY
+  if (!key) throw new Error('GOOGLE_MAPS_API_KEY environment variable is not set')
+  return key
+}
+
+async function googleGeocode(location: string, language?: string): Promise<LocationResult> {
+  const key = getGoogleKey()
+  const params = new URLSearchParams({ address: location, key })
+  if (language) params.set('language', language)
+
+  const res = await fetch(`https://maps.googleapis.com/maps/api/geocode/json?${params}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(10000),
+  })
+
+  if (!res.ok) throw new Error(`Google geocode HTTP ${res.status}`)
+  const data = await res.json() as any
+
+  if (data.status !== 'OK' || !data.results?.length) {
+    throw new Error(`Google geocode failed: ${data.status} — ${data.error_message || 'no results'}`)
+  }
+
+  const result = data.results[0]
+  return {
+    lat: result.geometry.location.lat,
+    lng: result.geometry.location.lng,
+    formattedAddress: result.formatted_address,
+    displayName: result.formatted_address,
+  }
+}
+
+async function googleSearchPlaces(
+  location: string,
+  query?: string,
+  radius?: number,
+  language?: string,
+  /** Pre-resolved coordinates (skip geocoding) */
+  geo?: LocationResult,
+): Promise<PlaceResult[]> {
+  const key = getGoogleKey()
+  const resolved = geo ?? await googleGeocode(location, language)
+
+  const params = new URLSearchParams({
+    key,
+    language: language || 'zh-CN',
+  })
+
+  if (query) {
+    // Text search for specific queries
+    params.set('query', `${query} in ${location}`)
+    const res = await fetch(`https://maps.googleapis.com/maps/api/place/textsearch/json?${params}`, {
+      headers: { 'Accept': 'application/json' },
+      signal: AbortSignal.timeout(15000),
+    })
+
+    if (!res.ok) throw new Error(`Google places search HTTP ${res.status}`)
+    const data = await res.json() as any
+    if (data.status !== 'OK') {
+      throw new Error(`Google places search failed: ${data.status} — ${data.error_message || ''}`)
+    }
+
+    return parseGooglePlacesResults(data.results, resolved)
+  }
+
+  // Nearby search
+  params.set('location', `${resolved.lat},${resolved.lng}`)
+  params.set('radius', String(radius || 5000))
+
+  const res = await fetch(`https://maps.googleapis.com/maps/api/place/nearbysearch/json?${params}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15000),
+  })
+
+  if (!res.ok) throw new Error(`Google nearby search HTTP ${res.status}`)
+  const data = await res.json() as any
+  if (data.status !== 'OK') {
+    throw new Error(`Google nearby search failed: ${data.status} — ${data.error_message || ''}`)
+  }
+
+  return parseGooglePlacesResults(data.results, resolved)
+}
+
+function parseGooglePlacesResults(results: any[], geo: LocationResult): PlaceResult[] {
+  return (results || []).slice(0, 20).map((place: any) => ({
+    name: place.name,
+    address: place.formatted_address || place.vicinity || '',
+    lat: place.geometry?.location?.lat || geo.lat,
+    lng: place.geometry?.location?.lng || geo.lng,
+    rating: place.rating,
+    types: place.types,
+    phone: place.formatted_phone_number,
+    website: place.website,
+    openingHours: place.opening_hours?.open_now ? 'Open now' : undefined,
+    photos: (place.photos || []).slice(0, 3).map((p: any) =>
+      `https://maps.googleapis.com/maps/api/place/photo?maxwidth=800&photoreference=${p.photo_reference}&key=${getGoogleKey()}`
+    ),
+    cost: place.price_level ? '💰'.repeat(place.price_level) : undefined,
+  }))
+}
+
+async function googleDirections(
+  origin: string,
+  destination: string,
+  mode: string,
+  language?: string,
+): Promise<DirectionsResult> {
+  const key = getGoogleKey()
+  const params = new URLSearchParams({
+    origin,
+    destination,
+    mode,
+    key,
+    language: language || 'zh-CN',
+    alternatives: 'true',
+  })
+
+  const res = await fetch(`https://maps.googleapis.com/maps/api/directions/json?${params}`, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(15000),
+  })
+
+  if (!res.ok) throw new Error(`Google directions HTTP ${res.status}`)
+  const data = await res.json() as any
+
+  if (data.status !== 'OK' || !data.routes?.length) {
+    throw new Error(`Google directions failed: ${data.status} — ${data.error_message || 'no route'}`)
+  }
+
+  const route = data.routes[0]
+  const legs: DirectionLeg[] = (route.legs || []).map((leg: any) => ({
+    steps: (leg.steps || []).map((s: any) => ({
+      instruction: s.html_instructions?.replace(/<[^>]+>/g, '') || '',
+      distance: s.distance?.text || '',
+      duration: s.duration?.text || '',
+      mode: s.travel_mode,
+    })),
+    distance: leg.distance?.text || '',
+    duration: leg.duration?.text || '',
+    startAddress: leg.start_address || origin,
+    endAddress: leg.end_address || destination,
+  }))
+
+  return {
+    origin,
+    destination,
+    mode,
+    legs,
+    totalDistance: legs[0]?.distance || '',
+    totalDuration: legs[0]?.duration || '',
+    polyline: route.overview_polyline?.points,
+  }
+}
+
+// ── Main call logic ───────────────────────────────────────────────────────────
+
+async function handleGeocode(
+  location: string,
+  region: 'china' | 'international',
+  language?: string,
+  /** Pre-resolved coordinates (skip geocoding) */
+  coords?: LocationResult,
+): Promise<LocationResult> {
+  if (coords) return coords
+  if (region === 'china') {
+    return await amapGeocode(location)
+  }
+  return await googleGeocode(location, language)
+}
+
+async function handleSearchPlaces(
+  location: string,
+  query: string | undefined,
+  type: string | undefined,
+  radius: number | undefined,
+  region: 'china' | 'international',
+  language?: string,
+  /** Pre-resolved coordinates (skip geocoding) */
+  coords?: LocationResult,
+): Promise<PlaceResult[]> {
+  if (region === 'china') {
+    return await amapSearchPlaces(location, query, type, radius, coords)
+  }
+  return await googleSearchPlaces(location, query, radius, language, coords)
+}
+
+async function handleDirections(
+  origin: string,
+  destination: string,
+  mode: string,
+  region: 'china' | 'international',
+  language?: string,
+  /** Pre-resolved origin coordinates */
+  origCoords?: LocationResult,
+  /** Pre-resolved destination coordinates */
+  destCoords?: LocationResult,
+): Promise<DirectionsResult> {
+  if (region === 'china') {
+    return await amapDirections(origin, destination, mode, origCoords, destCoords)
+  }
+  return await googleDirections(origin, destination, mode, language)
+}
+
+async function handlePlanTrip(
+  origin: string,
+  destination: string,
+  waypoints: string[] | undefined,
+  mode: string,
+  region: 'china' | 'international',
+  language?: string,
+  /** Pre-resolved origin coordinates */
+  origCoords?: LocationResult,
+  /** Pre-resolved destination coordinates */
+  destCoords?: LocationResult,
+) {
+  // Multi-stop: combine waypoints into a single route
+  if (waypoints && waypoints.length > 0) {
+    // We run directions sequentially for each leg to get complete info
+    const legs: DirectionLeg[] = []
+    let currentOrigin = origin
+    let currentCoords = origCoords
+
+    for (const wp of waypoints) {
+      const leg = await handleDirections(currentOrigin, wp, mode, region, language, currentCoords)
+      legs.push(...leg.legs)
+      currentOrigin = wp
+      currentCoords = undefined // waypoints are strings, not coordinates
+    }
+    // Final leg
+    const finalLeg = await handleDirections(currentOrigin, destination, mode, region, language, undefined, destCoords)
+    legs.push(...finalLeg.legs)
+
+    const totalDist = legs.reduce((sum, l) => sum + parseFloat(l.distance) || 0, 0)
+    const totalDur = legs.reduce((sum, l) => sum + parseFloat(l.duration) || 0, 0)
+
+    return {
+      origin,
+      destination,
+      mode,
+      legs,
+      totalDistance: `${totalDist.toFixed(1)} km`,
+      totalDuration: `${Math.round(totalDur)} min`,
+      waypoints: [origin, ...waypoints, destination],
+    }
+  }
+
+  // Simple point-to-point
+  return await handleDirections(origin, destination, mode, region, language)
+}
+
+// ── Tool export ───────────────────────────────────────────────────────────────
+
+type LocationToolProgress = {
+  type: 'query_update' | 'results_received'
+  action?: string
+  location?: string
+}
+
+export const LocationTool = buildTool({
+  name: LOCATION_TOOL_NAME,
+  searchHint: 'geographic search, POI, maps, directions, travel planning',
+  shouldDefer: true,
+
+  getToolUseSummary,
+  getActivityDescription(input) {
+    const loc = input?.location || ''
+    const action = input?.action || 'query'
+    return `${action} for "${loc}"`
+  },
+
+  isEnabled() {
+    return true
+  },
+
+  get inputSchema() {
+    return inputSchema()
+  },
+
+  isConcurrencySafe() {
+    return true
+  },
+
+  isReadOnly() {
+    return true
+  },
+
+  toAutoClassifierInput(input) {
+    return input?.action
+      ? `${input.action}: ${input?.location || '(IP auto-detect)'}`
+      : ''
+  },
+
+  async checkPermissions() {
+    return { behavior: 'allow' }
+  },
+
+  async prompt() {
+    return PROMPT
+  },
+
+  renderToolUseMessage,
+  renderToolUseProgressMessage,
+  renderToolResultMessage,
+
+  extractSearchText(output) {
+    if (!output) return ''
+    const parts: string[] = []
+    if (output.geocoding) parts.push(`geocode: ${output.geocoding.formattedAddress}`)
+    if (output.places?.length) parts.push(`places: ${output.places.length} results`)
+    if (output.directions) parts.push(`route: ${output.directions.origin} → ${output.directions.destination}`)
+    return parts.join('; ')
+  },
+
+  async validateInput(input) {
+    if (input?.action !== 'locate' && (!input?.location || input?.location.length === 0)) {
+      return { result: false, message: 'Missing location parameter', errorCode: 1 }
+    }
+    if (input.action === 'get_directions' || input.action === 'plan_trip') {
+      if (!input.destination) {
+        return { result: false, message: 'Missing destination parameter for directions/trip', errorCode: 1 }
+      }
+    }
+    if (input.action === 'search_places' && !input.query && !input.type) {
+      return { result: false, message: 'Missing query or type parameter for place search', errorCode: 1 }
+    }
+    return { result: true }
+  },
+
+  async call(input, _context, _canUseTool, _parentMessage, onProgress) {
+    const { action, location, destination, query, radius, mode, waypoints, type, region: forcedRegion, language } = input
+
+    // Detect coordinate input (e.g. "34.2583,108.9286")
+    const originCoords = typeof location === 'string' ? parseCoords(location) : undefined
+    const destCoords = destination ? parseCoords(destination) : undefined
+
+    // Region: coordinates override text-based detection
+    let region = forcedRegion
+    if (!region && originCoords) {
+      region = isChinaCoords(originCoords.lat, originCoords.lng) ? 'china' : 'international'
+    }
+    if (!region && location) {
+      region = isChinaMainland(location) ? 'china' : 'international'
+    }
+    if (!region) {
+      region = 'international'
+    }
+
+    // Build pre-resolved origin LocationResult from coordinates
+    const originLocationResult = originCoords ? coordsToLocation(originCoords.lat, originCoords.lng) : undefined
+    const destLocationResult = destCoords ? coordsToLocation(destCoords.lat, destCoords.lng) : undefined
+
+    if (onProgress) {
+      onProgress({
+        toolUseID: 'location-start',
+        data: { type: 'query_update', action, location: location || '(locate)' },
+      })
+    }
+
+    try {
+      let ipGeo: IpGeoInfo | undefined
+      let geocoding: LocationResult | undefined
+      let places: PlaceResult[] | undefined
+      let directions: DirectionsResult | undefined
+
+      switch (action) {
+        case 'geocode':
+          geocoding = await handleGeocode(location, region, language, originLocationResult)
+          break
+
+        case 'search_places':
+          places = await handleSearchPlaces(location, query, type, radius ?? 5000, region, language, originLocationResult)
+          break
+
+        case 'get_directions':
+          if (!destination) throw new Error('Destination is required for directions')
+          directions = await handleDirections(location, destination, mode ?? 'driving', region, language, originLocationResult, destLocationResult)
+          break
+
+        case 'plan_trip':
+          if (!destination) throw new Error('Destination is required for trip planning')
+          const planResult = await handlePlanTrip(location, destination, waypoints, mode ?? 'driving', region, language, originLocationResult, destLocationResult)
+          directions = planResult as DirectionsResult
+          break
+
+        case 'locate': {
+          // 1. 首先尝试国内 Amap Wi‑Fi 定位（若在中国大陆）
+          const wifiAPs = await scanWiFi()
+          const amapLoc = await amapWiFiGeolocateAPI(wifiAPs)
+          if (amapLoc) {
+            region = isChinaCoords(amapLoc.lat, amapLoc.lng) ? 'china' : 'international'
+            geocoding = coordsToLocation(amapLoc.lat, amapLoc.lng)
+            ipGeo = {
+              ip: 'amap-wifi',
+              city: `${amapLoc.lat.toFixed(4)},${amapLoc.lng.toFixed(4)}`,
+              region: `accuracy: ${amapLoc.accuracy}m`,
+              country: region === 'china' ? 'CN' : 'unknown',
+              lat: amapLoc.lat,
+              lng: amapLoc.lng,
+            }
+            break
+          }
+
+          // 2. 若 Amap 未返回或不在中国大陆，尝试国外 Google Geolocation API
+          const googleLoc = await googleGeolocateAPI(wifiAPs)
+          if (googleLoc) {
+            region = 'international'
+            geocoding = coordsToLocation(googleLoc.lat, googleLoc.lng)
+            ipGeo = {
+              ip: 'google-geolocation',
+              city: `${googleLoc.lat.toFixed(4)},${googleLoc.lng.toFixed(4)}`,
+              region: `accuracy: ${googleLoc.accuracy}m`,
+              country: 'unknown',
+              lat: googleLoc.lat,
+              lng: googleLoc.lng,
+            }
+            break
+          }
+
+          // 3. 最后回退到 IP 定位（城市级）
+          ipGeo = await ipGeolocate()
+          const detectRegion = ipGeo.country === 'CN' ? 'china' : 'international'
+          const detectCoords = ipGeo.lat && ipGeo.lng
+            ? coordsToLocation(ipGeo.lat, ipGeo.lng)
+            : undefined
+          if (detectCoords) {
+            geocoding = detectCoords
+          } else {
+            geocoding = await handleGeocode(ipGeo.city, detectRegion, language)
+          }
+          region = detectRegion
+          break
+        }
+      }
+
+      if (onProgress) {
+        onProgress({
+          toolUseID: 'location-results',
+          data: {
+            type: 'results_received',
+            action,
+            location: action === 'locate' ? ipGeo?.city : location,
+            ...(places && { count: places.length }),
+          } as any,
+        })
+      }
+
+      return {
+        data: {
+          action,
+          region,
+          geocoding,
+          places,
+          directions,
+          ipGeo,
+        } satisfies Output,
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      logError('LocationTool error', error)
+
+      return {
+        data: {
+          action,
+          region,
+          error: errorMessage,
+          ipGeo,
+        } satisfies Output,
+      }
+    }
+  },
+
+  mapToolResultToToolResultBlockParam(output: Output, toolUseID: string) {
+    const lines: string[] = []
+    lines.push(`📍 Location Result [${output.action}]`)
+    lines.push(`Region: ${output.region === 'china' ? '中国大陆' : '海外'}`)
+    if (output.ipGeo) {
+      const g = output.ipGeo
+      lines.push(`IP: ${g.ip} — ${g.city}, ${g.region} (${g.country})`)
+      if (g.lat && g.lng) lines.push(`Coords: ${g.lat}, ${g.lng}`)
+    }
+    lines.push('')
+
+    if (output.error) {
+      lines.push(`Error: ${output.error}`)
+    }
+
+    if (output.geocoding) {
+      const g = output.geocoding
+      lines.push(`┌─ 地理编码结果`)
+      lines.push(`│ 地址: ${g.formattedAddress}`)
+      lines.push(`│ 坐标: ${g.lat}, ${g.lng}`)
+      lines.push(`│ 地图: https://${output.region === 'china' ? 'uri.amap.com/marker?position=' : 'www.google.com/maps?q='}${g.lat},${g.lng}`)
+      lines.push(`└────\n`)
+    }
+
+    if (output.places && output.places.length > 0) {
+      lines.push(`┌─ 搜索结果 (${output.places.length} 条)`)
+      output.places.forEach((p, i) => {
+        lines.push(`│`)
+        lines.push(`│ [${i + 1}] ${p.name}`)
+        if (p.address) lines.push(`│     地址: ${p.address}`)
+        if (p.distance) lines.push(`│     距离: ${p.distance}米`)
+        if (p.tag) lines.push(`│     类别: ${p.tag}`)
+        if (p.rating) lines.push(`│     评分: ${'⭐'.repeat(Math.round(p.rating))} (${p.rating})`)
+        if (p.cost) lines.push(`│     消费: ${p.cost}`)
+        if (p.openingHours) lines.push(`│     营业: ${p.openingHours}`)
+        if (p.phone) lines.push(`│     电话: ${p.phone}`)
+        if (p.photos?.length) {
+          lines.push(`│     照片: ${p.photos.map((ph, idx) => `[图${idx + 1}](${ph})`).join(' ')}`)
+        }
+      })
+      lines.push(`└────\n`)
+    }
+
+    if (output.directions) {
+      const d = output.directions
+      lines.push(`┌─ 路线规划`)
+      lines.push(`│ 起点: ${d.origin}`)
+      lines.push(`│ 终点: ${d.destination}`)
+      lines.push(`│ 交通方式: ${d.mode}`)
+      lines.push(`│ 总距离: ${d.totalDistance}`)
+      lines.push(`│ 预计耗时: ${d.totalDuration}`)
+      if (d.transitInfo) lines.push(`│ 公共交通: ${d.transitInfo}`)
+      if (d.tolls) lines.push(`│ 通行费: ${d.tolls}`)
+
+      if (d.legs.length > 0) {
+        lines.push(`│`)
+        d.legs.forEach((leg, li) => {
+          if (d.legs.length > 1) lines.push(`│ 路段 ${li + 1}: ${leg.startAddress} → ${leg.endAddress}`)
+          lines.push(`│   距离: ${leg.distance} | 时间: ${leg.duration}`)
+          leg.steps.slice(0, 10).forEach(s => {
+            const instr = s.instruction.length > 80 ? s.instruction.slice(0, 80) + '…' : s.instruction
+            lines.push(`│   → ${instr} (${s.distance}, ${s.duration})`)
+          })
+          if (leg.steps.length > 10) {
+            lines.push(`│   … 还有 ${leg.steps.length - 10} 个步骤`)
+          }
+        })
+      }
+      lines.push(`└────`)
+    }
+
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: lines.join('\n'),
+    }
+  },
+}) satisfies ToolDef<ReturnType<typeof inputSchema>, Output, LocationToolProgress>

src/tools/LocationTool/UI.tsx

@@ -0,0 +1,93 @@
+import React from 'react'
+import { MessageResponse } from '../../components/MessageResponse.js'
+import { TOOL_SUMMARY_MAX_LENGTH } from '../../constants/toolLimits.js'
+import { Box, Text } from '../../ink.js'
+import { truncate } from '../../utils/format.js'
+
+export function renderToolUseMessage(
+  input: Partial<{
+    action: string
+    location: string
+    destination: string
+    query: string
+  }>,
+  { verbose }: { verbose: boolean },
+): React.ReactNode {
+  const { action, location, destination, query } = input
+  if (!action || !location) {
+    return null
+  }
+
+  const actionLabel: Record<string, string> = {
+    geocode: '地理编码',
+    search_places: '搜索地点',
+    get_directions: '路线规划',
+    plan_trip: '行程规划',
+  }
+
+  let msg = `${actionLabel[action] || action}: ${location}`
+  if (destination) msg += ` → ${destination}`
+  if (query && verbose) msg += ` (${query})`
+
+  return msg
+}
+
+export function renderToolUseProgressMessage(): React.ReactNode {
+  return null
+}
+
+export function renderToolResultMessage(output: {
+  action: string
+  region?: string
+  geocoding?: { formattedAddress: string; lat: number; lng: number }
+  places?: unknown[]
+  directions?: { origin: string; destination: string; totalDistance: string; totalDuration: string }
+  error?: string
+}): React.ReactNode {
+  if (!output) return null
+
+  if (output.error) {
+    return (
+      <MessageResponse>
+        <Text color="red">Location error: {output.error}</Text>
+      </MessageResponse>
+    )
+  }
+
+  const parts: string[] = []
+  const regionLabel = output.region === 'china' ? '中国大陆' : '海外'
+
+  if (output.geocoding) {
+    const g = output.geocoding
+    parts.push(`坐标: ${g.lat}, ${g.lng}`)
+  }
+  if (output.places?.length) {
+    parts.push(`找到 ${output.places.length} 个地点`)
+  }
+  if (output.directions) {
+    const d = output.directions
+    parts.push(`${d.origin} → ${d.destination}: ${d.totalDistance}, ${d.totalDuration}`)
+  }
+
+  return (
+    <MessageResponse>
+      <Text>
+        [{regionLabel}] {parts.join(' | ')}
+      </Text>
+    </MessageResponse>
+  )
+}
+
+export function getToolUseSummary(
+  input: Partial<{
+    action: string
+    location: string
+    destination: string
+    query: string
+  }> | undefined,
+): string | null {
+  if (!input?.action || !input?.location) return null
+  let summary = `${input.action}: ${input.location}`
+  if (input.destination) summary += ` → ${input.destination}`
+  return truncate(summary, TOOL_SUMMARY_MAX_LENGTH)
+}

src/tools/LocationTool/prompt.ts

@@ -0,0 +1,45 @@
+export const LOCATION_TOOL_NAME = 'LocationTool'
+
+export const PROMPT = `
+LocationTool — Search geographic information, points of interest, and plan routes/travel.
+
+This tool provides location-based services using two map providers:
+- **高德地图 (Amap)**: Used for China mainland locations (cities, POIs, routes within China)
+- **Google Maps**: Used for non-China mainland locations (international cities, cross-country routes)
+
+**Capabilities:**
+1. **Locate** — Detect the user's current location using Wi‑Fi fingerprinting (Amap for China, Google for abroad). If Wi‑Fi data unavailable, falls back to IP geolocation. Use \`action: "locate"\` without \`location\`.
+2. **Geocoding** — Convert a place name to coordinates (latitude/longitude)
+3. **Search Places** — Find nearby or in-city points of interest (restaurants, attractions, hotels, shopping, transportation, etc.)
+4. **Get Directions** — Get routes between two locations with multiple transport modes (driving, walking, transit, bicycling)
+5. **Plan Trip** — Multi-stop travel planning between cities/countries
+
+**When to use this tool:**
+- User asks "where am I?" → use the \`locate\` action
+- User asks about places, POIs, or things to do in a specific city/area
+- User needs directions or route information between locations
+- User wants to plan travel between cities or countries
+- User asks about geographic coordinates of a place
+
+**Combining with other tools:**
+- After getting place/POI results from LocationTool, you can use **WebSearchTool** to search for travel guides, reviews, or additional information about specific places
+- Use **WebFetchTool** to fetch detailed information from URLs found in search results (e.g., attraction pages, hotel booking sites, travel blog posts)
+- Example: Search places → WebSearch for reviews → WebFetch for detailed info
+
+**Transport modes for directions:**
+- For China (Amap): "driving", "walking", "transit" (公交/地铁)
+- For international (Google): "driving", "walking", "transit", "bicycling"
+
+**API Keys:**
+- \`AMAP_API_KEY\` env var — required for China mainland queries
+- \`GOOGLE_MAPS_API_KEY\` env var — required for non-China queries
+
+**Coordinate input:**
+- You can pass \`location\` as "lat,lng" coordinates (e.g. \`"34.2583,108.9286"\`) to search/directions directly by coordinates, bypassing geocoding
+- Region is auto-detected from coordinates using China's bounding box
+
+**Region auto-detection:**
+- Locations containing Chinese characters or recognized Chinese city names → uses Amap
+- Other locations → uses Google Maps
+- You can also explicitly specify the \`region\` parameter
+`