mirror of
https://github.com/NomaDamas/k-skill.git
synced 2026-06-24 02:04:11 +00:00
Apply review fixes to korean-transit-route skill
- Add Done when and Failure modes sections to align with SKILL.md template - Fix Python geocode example to use with-statement for urlopen - Add korean-transit-route to README.md skill table and feature list - Add docs/features/korean-transit-route.md guide
This commit is contained in:
Jeffrey (Dongkyu) Kim
parent
11a9d25281
commit
656a60fba3
3 changed files with 98 additions and 3 deletions
|
|
@ -25,6 +25,7 @@ Claude Code, Codex, OpenCode, OpenClaw/ClawHub 등 각종 코딩 에이전트
|
|||
| 자연휴양림 빈 객실 조회 | `foresttrip-vacancy` | 공식 숲나들e 자연휴양림 예약 가능 객실 조회 자동화 (예약/결제 제외) | 필요 | [자연휴양림 빈 객실 조회 가이드](docs/features/foresttrip-vacancy.md) |
|
||||
| 카카오톡 Mac CLI | `kakaotalk-mac` | macOS에서 카카오톡 대화 조회, 검색, 메시지 전송 | 불필요 | [카카오톡 Mac CLI 가이드](docs/features/kakaotalk-mac.md) |
|
||||
| 서울 지하철 도착정보 조회 | `seoul-subway-arrival` | 서울 지하철 역 기준 실시간 도착 예정 열차 확인 | 불필요 | [서울 지하철 도착정보 가이드](docs/features/seoul-subway-arrival.md) |
|
||||
| 한국 대중교통 길찾기 | `korean-transit-route` | ODsay LIVE API + Kakao geocoding 기반 출발지→도착지 지하철+버스+도보 경로 및 환승 정보 조회 | 필요 | [한국 대중교통 길찾기 가이드](docs/features/korean-transit-route.md) |
|
||||
| 지하철 분실물 조회 | `subway-lost-property` | 지하철 역/물품명 기준 공식 LOST112 분실물 검색 조건과 유실물센터 진입점 안내 | 불필요 | [지하철 분실물 조회 가이드](docs/features/subway-lost-property.md) |
|
||||
| 긱뉴스 조회 | `geeknews-search` | GeekNews 공개 RSS/Atom 피드 기반 최신 글 목록, 검색, 상세 확인 | 불필요 | [긱뉴스 조회 가이드](docs/features/geeknews-search.md) |
|
||||
| 한국 날씨 조회 | `korea-weather` | 기상청 단기예보 기반 한국 날씨 조회 | 불필요 | [한국 날씨 조회 가이드](docs/features/korea-weather.md) |
|
||||
|
|
@ -116,6 +117,7 @@ Claude Code, Codex, OpenCode, OpenClaw/ClawHub 등 각종 코딩 에이전트
|
|||
- [자연휴양림 빈 객실 조회](docs/features/foresttrip-vacancy.md)
|
||||
- [카카오톡 Mac CLI](docs/features/kakaotalk-mac.md)
|
||||
- [서울 지하철 도착정보 조회](docs/features/seoul-subway-arrival.md)
|
||||
- [한국 대중교통 길찾기 가이드](docs/features/korean-transit-route.md)
|
||||
- [지하철 분실물 조회 가이드](docs/features/subway-lost-property.md)
|
||||
- [긱뉴스 조회 가이드](docs/features/geeknews-search.md)
|
||||
- [한국 날씨 조회 가이드](docs/features/korea-weather.md)
|
||||
|
|
|
|||
75
docs/features/korean-transit-route.md
Normal file
75
docs/features/korean-transit-route.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# 한국 대중교통 길찾기 가이드
|
||||
|
||||
## 이 기능으로 할 수 있는 일
|
||||
|
||||
- 출발지→도착지 도어투도어 대중교통 경로 조회 (지하철 + 버스 + 도보)
|
||||
- ODsay LIVE API 기반 환승 정보, 소요시간, 요금 확인
|
||||
- Kakao Local geocoding으로 주소·장소명→좌표 변환
|
||||
- 추천순 / 최소시간 / 최소환승 옵션 선택
|
||||
|
||||
## 먼저 필요한 것
|
||||
|
||||
- [공통 설정 가이드](../setup.md) 완료
|
||||
- [보안/시크릿 정책](../security-and-secrets.md) 확인
|
||||
- ODsay Server API Key 발급 및 호출 IP 화이트리스트 등록: https://lab.odsay.com
|
||||
- Kakao REST API Key 발급 (지도/로컬 서비스 활성화): https://developers.kakao.com
|
||||
|
||||
## 필요한 환경변수
|
||||
|
||||
- `ODSAY_API_KEY` — ODsay LIVE API Server 키
|
||||
- `KAKAO_REST_API_KEY` — Kakao Local REST API 키
|
||||
|
||||
두 값 모두 `~/.config/k-skill/secrets.env` 에 저장하거나 환경변수로 주입한다.
|
||||
|
||||
## 입력값
|
||||
|
||||
- 출발지 (주소, 장소명, 또는 좌표)
|
||||
- 도착지 (주소, 장소명, 또는 좌표)
|
||||
- 선택 사항: 경로 옵션 (`OPT=0` 추천순, `4` 최소시간, `5` 최소환승), `SearchPathType` (`0` 지하철+버스, `1` 지하철만, `2` 버스만)
|
||||
|
||||
## 기본 흐름
|
||||
|
||||
1. 출발지/도착지를 Kakao Local API(`address.json` → `keyword.json`)로 geocoding하여 좌표를 확보한다.
|
||||
2. ODsay `searchPubTransPathT`에 출발/도착 좌표와 옵션을 전달한다.
|
||||
3. 응답의 `result.path[]`를 3개 이내로 정리한다.
|
||||
4. 각 경로의 `subPath[]`를 `trafficType`별로 표시하며, 첫/끝 도보 구간을 반드시 포함한다.
|
||||
|
||||
## 예시
|
||||
|
||||
### 좌표 직접 입력
|
||||
|
||||
```bash
|
||||
set -a; . ~/.config/k-skill/secrets.env; set +a
|
||||
KEY=$(python3 -c "import os,urllib.parse;print(urllib.parse.quote(os.environ['ODSAY_API_KEY'],safe=''))")
|
||||
curl -s "https://api.odsay.com/v1/api/searchPubTransPathT?apiKey=${KEY}&SX=126.9706&SY=37.5559&EX=127.0276&EY=37.4979&OPT=0&SearchPathType=0"
|
||||
```
|
||||
|
||||
### 주소→좌표→경로 (Python)
|
||||
|
||||
```python
|
||||
import os, urllib.parse, urllib.request, json
|
||||
|
||||
H = {'Authorization': 'KakaoAK ' + os.environ['KAKAO_REST_API_KEY']}
|
||||
|
||||
def geocode(q):
|
||||
for ep, name in [('address', 'address_name'), ('keyword', 'place_name')]:
|
||||
url = f'https://dapi.kakao.com/v2/local/search/{ep}.json?query=' + urllib.parse.quote(q)
|
||||
req = urllib.request.Request(url, headers=H)
|
||||
with urllib.request.urlopen(req, timeout=10) as resp:
|
||||
d = json.loads(resp.read())
|
||||
if d.get('documents'):
|
||||
doc = d['documents'][0]
|
||||
return float(doc['x']), float(doc['y']), doc.get(name) or doc['address_name']
|
||||
return None
|
||||
|
||||
sx, sy, s_name = geocode('서울역')
|
||||
ex, ey, e_name = geocode('강남역')
|
||||
# 이후 ODsay searchPubTransPathT 호출
|
||||
```
|
||||
|
||||
## 주의할 점
|
||||
|
||||
- ODsay Server 키는 **호출 IP 화이트리스트 등록이 필수**이다. 등록되지 않은 IP에서는 `error` 응답이 반환된다.
|
||||
- 묣료 일일 한도는 5,000건이다. `searchPubTransPathT`와 `searchStation` 호출이 합산된다.
|
||||
- 한국 외 좌표는 지원하지 않는다.
|
||||
- 카카오맵/네이버지도 directions API는 대중교통 라우팅을 공개하지 않으므로 사용하지 말 것.
|
||||
|
|
@ -42,9 +42,12 @@ H={'Authorization':'KakaoAK '+os.environ['KAKAO_REST_API_KEY']}
|
|||
def geocode(q):
|
||||
for ep,name in [('address','address_name'),('keyword','place_name')]:
|
||||
url=f'https://dapi.kakao.com/v2/local/search/{ep}.json?query='+urllib.parse.quote(q)
|
||||
d=json.loads(urllib.request.urlopen(urllib.request.Request(url,headers=H),timeout=10).read())
|
||||
req=urllib.request.Request(url,headers=H)
|
||||
with urllib.request.urlopen(req,timeout=10) as resp:
|
||||
d=json.loads(resp.read())
|
||||
if d.get('documents'):
|
||||
x=d['documents'][0]; return float(x['x']), float(x['y']), x.get(name) or x['address_name']
|
||||
doc=d['documents'][0]
|
||||
return float(doc['x']), float(doc['y']), doc.get(name) or doc['address_name']
|
||||
return None
|
||||
```
|
||||
|
||||
|
|
@ -86,6 +89,14 @@ Parameters:
|
|||
|
||||
3개 이내 경로 비교 권장. `OPT=4`(최소시간) / `OPT=5`(최소환승) 옵션을 사용자가 선호 표시하면 그쪽으로 호출.
|
||||
|
||||
## Done when
|
||||
|
||||
- 출발지와 도착지가 geocoding 되었거나, 좌표/역명이 명확히 확인되었다.
|
||||
- ODsay 응답에서 1개 이상 경로가 정리되었다.
|
||||
- 각 경로의 총 소요시간, 요금, 환승 횟수, 총 도보 거리가 포함되었다.
|
||||
- 첫/끝 도보 구간이 포함된 door-to-door 요약을 보여줬다.
|
||||
- upstream API 키가 응답에 노출되지 않았다.
|
||||
|
||||
## Helpers
|
||||
|
||||
좌표 모르고 역명만 아는 경우 — `searchStation` 으로 변환:
|
||||
|
|
@ -98,10 +109,17 @@ curl -s "https://api.odsay.com/v1/api/searchStation?apiKey=${KEY}&stationName=
|
|||
|
||||
## Limits
|
||||
|
||||
- 무료 일 5,000건. `searchPubTransPathT` + `searchStation` 호출이 합산되니 한 질문당 호출 최소화.
|
||||
- 묣료 일 5,000건. `searchPubTransPathT` + `searchStation` 호출이 합산되니 한 질문당 호출 최소화.
|
||||
- 응답에 `error` 키 있으면 즉시 사용자에게 표시(ApiKey/IP 문제 진단에 유용).
|
||||
- 한국 외 좌표는 지원 안 함.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- ODsay `error` 응답: `msg` 필드를 그대로 사용자에게 표시하고, ApiKey 미등록 또는 IP 화이트리스트 누락 가능성을 안내한다.
|
||||
- Kakao geocoding 결과 없음: 주소/장소명을 다시 확인하거나 더 구체적인 표현을 요청한다.
|
||||
- 좌표는 있으나 ODsay 경로 없음: 대중교통 미개통 지역, 도보 가능 거리, 또는 해상/공항 구간일 수 있다. 사용자에게 확인한다.
|
||||
- quota 초과: 일일 5,000건 한도 도달 시 추가 호출을 중단하고 사용자에게 알린다.
|
||||
|
||||
## Don'ts
|
||||
|
||||
- 카카오맵/네이버지도 directions API로 대중교통 라우팅 시도하지 말 것 (둘 다 운전·도보만 공개).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue