naver-map-route

Naver Map Route（네이버 지도 길찾기 MVP）

⚠️ 当前无法使用（2026-05-25）：NCP Maps 运营方密钥尚未配置到代理服务器，因此 live 模式无法运行。目前只能使用 mock fallback。NCP 付款方式注册完成后，配置密钥即可移除此说明。

此技能的功能

用户通过 /route 或 /이동루트 命令直接输入出发地和目的地后，经由 k-skill-proxy 查询 NAVER Cloud Platform Maps Directions 5 的结果，并汇总距离、所需时间、通行费和燃油费。

• 运营方仅在代理服务器端保管 NCP Maps key，用户无需单独准备 key。
• 默认模式为 mock。只有明确启用（ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true + ROUTE_PLANNER_PROVIDER=naver）时，才会调用 live proxy。
• 缺少密钥或认证失败时，会通过 graceful fallback 提供 mock 结果。

Issue #268 的 MVP 验收标准：

• /route 手动输入后正常响应
• /이동루트 手动输入后正常响应
• 在默认 mock 模式下稳定运行
• 明确启用 live 且密钥存在时选择 naver provider
• 缺少密钥或调用失败时返回 fallback 响应
• 不暴露 secret/token/.env 原文

适用场景

• 像 "/route 从江南站到市厅站" 这样的单行手动输入
• "/이동루트 出发：<地址> / 到达：<地址>"
• "从江南站到市厅开车要多久？"（转换为手动坐标/地址输入后查询路线）
• 查询汽车路线摘要、距离、所需时间、通行费和燃油费

不适用场景

• 步行、自行车或公共交通路线（公共交通请使用现有的 korean-transit-route 技能；步行和自行车请使用其他技能）
• 按分钟追踪实时交通变化的任务（proxy 有缓存）
• 自动识别当前位置或关联日历（不在 MVP 范围内）

前置条件

• 仅使用 Python 3 标准库（urllib、argparse、json）。
• 可选：KSKILL_PROXY_BASE_URL（仅在使用自托管或独立代理时设置。不设置时默认使用托管服务 https://k-skill-proxy.nomadamas.org）。
• 可选：ROUTE_PLANNER_PROVIDER=naver（只有值为 naver 时才会将其作为 live provider 候选）。
• 可选：ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true（明确允许 live 调用）。

必需的环境变量

用户机器上无需设置。 运营方需在代理服务器端配置以下变量：

• NAVER_MAP_CLIENT_ID — NCP Maps 子账户 client id
• NAVER_MAP_CLIENT_SECRET — NCP Maps 子账户 client secret

如果代理服务器在未配置这些密钥的情况下运行，/v1/naver-map/* 路由会返回 503 upstream_not_configured。客户端会将其作为 mock fallback 信号。

决策流程

provider 결정
├── ROUTE_PLANNER_ENABLE_LIVE_PROVIDER != "true"
│     → mock 결과 반환
├── ROUTE_PLANNER_PROVIDER != "naver"
│     → mock 결과 반환
└── live 시도
      ├── proxy /v1/naver-map/directions 호출
      ├── 503 / 502 / 네트워크 실패
      │     → mock fallback + warning 메모
      └── 정상 응답
            → 요약 + provider="naver"

Proxy 路由

endpoint	upstream	主要输入
GET /v1/naver-map/directions	NCP Maps Directions 5（/map-direction/v1/driving）	start=lng,lat、goal=lng,lat、waypoints（最多 5 个）、option=trafast|tracomfort|traoptimal|traavoidtoll|traavoidcaronly、lang=ko
GET /v1/naver-map/geocode	NCP Maps Geocoding（/map-geocode/v2/geocode）	q、coordinate、filter、language、page、count
GET /v1/naver-map/reverse-geocode	NCP Maps Reverse Geocoding（/map-reversegeocode/v2/gc）	coords=lng,lat、orders=roadaddr,addr,legalcode,admcode、output=json

工作流

1. 整理用户输入

• 接收 /route <start>, <goal> 或 /이동루트 出发：<start> 到达：<goal> 格式。
• 坐标（126.9706,37.5559）和地址（江南站 1 号出口）均可接受。地址需通过 geocode 步骤转换为坐标。

2. mock 模式（默认）

如果 ROUTE_PLANNER_ENABLE_LIVE_PROVIDER 未设置或值不为 true，则立即生成 mock 结果：

{
  "provider": "mock",
  "start": { "label": "강남역", "lng": null, "lat": null },
  "goal": { "label": "시청역", "lng": null, "lat": null },
  "summary": {
    "distance_km": null,
    "duration_minutes": null,
    "toll_won": null,
    "fuel_won": null
  },
  "note": "live provider is disabled. Set ROUTE_PLANNER_PROVIDER=naver and ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true to call the proxy."
}

3. live 模式

ROUTE_PLANNER_PROVIDER=naver + ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true：

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/naver-map/directions" \
  --data-urlencode 'start=126.9706,37.5559' \
  --data-urlencode 'goal=127.0276,37.4979' \
  --data-urlencode 'option=trafast'

从响应中读取默认 option=trafast 对应的 route.trafast[0].summary；如果指定了其他 option，则将 route[option][0].summary 映射如下：

• distance（米）→ distance_km = distance / 1000
• duration（毫秒）→ duration_minutes = duration / 60000
• tollFare → toll_won
• fuelPrice → fuel_won

4. 地址 → 坐标转换（仅在需要时）

用户不知道坐标、只提供地址时：

curl -fsS --get "${BASE}/v1/naver-map/geocode" \
  --data-urlencode 'q=강남역 1번 출구' \
  --data-urlencode 'count=1'

使用响应中的 addresses[0].x（lng）和 addresses[0].y（lat）。

5. 输出格式

[mock 모드]
경로 요약 (mock): 강남역 → 시청역
- 거리/소요시간/통행료 정보 없음
- live 활성화 방법: ROUTE_PLANNER_PROVIDER=naver, ROUTE_PLANNER_ENABLE_LIVE_PROVIDER=true

[live 모드]
경로 요약 (naver): 강남역(126.9706,37.5559) → 시청역(127.0276,37.4979)
- 거리: 12.3km
- 예상 소요시간: 25분
- 통행료: 1,200원
- 연료비: 1,500원
- 옵션: trafast
- 조회 시각: 2026-05-23T14:00:00.000Z

故障情况

• 未配置 proxy upstream key（缺少 NAVER_MAP_CLIENT_ID/SECRET）→ 503 upstream_not_configured → mock fallback
• NCP Maps 认证失败（401/403）→ proxy 转换为 503 → mock fallback
• NCP Maps quota/rate-limit（429）→ proxy 保留 429 upstream_error → mock fallback + 提示重试间隔
• 未找到路线（code != 0）→ 502 upstream_semantic_error → 附带消息说明情况
• 坐标格式错误 → 400 bad_request
• 网络失败 → 502 upstream_error → mock fallback

完成标准

• 用户通过 /route 或 /이동루트 提供出发地和目的地后，明确返回 mock 或 live 结果之一。
• live 响应中会整理距离、时间、通行费、燃油费和查询时间。
• 响应中绝不暴露 secret/token/.env 原文。
• live 失败时会启用 mock fallback，并明确告知用户这是 fallback。

Notes

• 본 MVP는 자동차 경로에 한정한다. 도보·자전거·대중교통은 별도 스킬을 사용한다.
• waypoints 는 최대 5개 (NCP Maps 정책).
• option=trafast(빠른 경로) 가 기본. 정확한 정의는 NCP Maps Directions 5 공식 문서를 참고.
• proxy 운영/환경변수 설정은 docs/features/k-skill-proxy.md 를 참고한다.
• 현재 위치 자동 인식·캘린더 읽기는 의도적으로 범위에서 제외된다(이슈 #268 OUT).