mirrors/k-skill
2
0
Fork 0
mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00
Code Issues Projects Releases Packages Wiki Activity
k-skill/seoul-bike/SKILL.md
Jeffrey (Dongkyu) Kim 5e406eb32b Add Seoul Bike live station lookup 
Expose narrow Seoul Open Data proxy surfaces for realtime bike availability, station master pages, and coordinate-based nearby lookups while keeping the upstream key server-side. Add a single Python skill entrypoint plus docs so agents can answer last-mile bike and dock availability questions.

Constraint: Issue #274 requires , TDD, three proxy routes, branch feature/#274, and PR to dev.
Rejected: Client-side Seoul OpenAPI key handling | would leak upstream credentials and violate existing proxy patterns.
Confidence: high
Scope-risk: moderate
Directive: Keep these routes read-only; do not add rental/booking mutations or user-key requirements.
Tested: node --test packages/k-skill-proxy/test/server.test.js --test-name-pattern 'seoul bike'; PYTHONPATH=.:scripts python3 -m unittest scripts.test_seoul_bike; local fake-proxy smoke run; PATH="/Users/jeffrey/.pyenv/versions/3.11.9/bin:/Users/jeffrey/.codex/tmp/arg0/codex-arg08RBix6:/opt/homebrew/lib/node_modules/@openai/codex/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin/path:/Users/jeffrey/.cmuxterm/omo-bin:/opt/homebrew/share/android-commandlinetools/platform-tools:/opt/homebrew/share/android-commandlinetools/emulator:/opt/homebrew/share/android-commandlinetools/cmdline-tools/latest/bin:/Users/jeffrey/.local/bin:/Users/jeffrey/.bun/bin:/opt/homebrew/opt/node@22/bin:/opt/homebrew/opt/openjdk@21/bin:/opt/homebrew/opt/postgresql@18/bin:/Users/jeffrey/.jenv/shims:/Users/jeffrey/.jenv/bin:/opt/homebrew/opt/imagemagick/bin:/opt/homebrew/Cellar/pyenv-virtualenv/1.4.0/shims:/Users/jeffrey/.pyenv/shims:/opt/homebrew/opt/openssl@3/bin:/Users/jeffrey/.rbenv/shims:/Users/jeffrey/.rbenv/bin:/Users/jeffrey/google-cloud-sdk/bin:/Applications/cmux.app/Contents/Resources/bin:/Users/jeffrey/Library/pnpm:/Users/jeffrey/.nvm/versions/node/v24.13.0/bin:/Users/jeffrey/.cops/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/opt/pmk/env/global/bin:/Library/Apple/usr/bin:/Library/TeX/texbin:/Users/jeffrey/.cargo/bin:/Users/jeffrey/Library/Application Support/JetBrains/Toolbox/scripts:/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home/bin:/Users/jeffrey/xcode-projects/marshroom/cli" npm run ci.
Not-tested: Live hosted Seoul Open Data request with production SEOUL_OPEN_API_KEY.
2026-05-21 15:27:29 +09:00

3.2 KiB
Raw Blame History

name description license metadata
seoul-bike 서울 따릉이 실시간 대여소의 대여 가능 자전거와 빈 거치대를 좌표 주변 또는 대여소 이름으로 조회한다. MIT
category locale phase
transit ko-KR v1

Seoul Bike (따릉이)

What this skill does

서울 열린데이터 광장의 따릉이 실시간 대여정보를 k-skill-proxy 경유로 조회해 대여 가능 자전거 수와 빈 거치대 수를 요약한다.

When to use

  • "지금 여기서 따릉이 빌릴 수 있어?"
  • "광화문 근처 빈 거치대 있어?"
  • "강남역 따릉이 대여소에 자전거 몇 대 남았어?"

Prerequisites

  • Python 3 표준 라이브러리만 사용한다.
  • optional: KSKILL_PROXY_BASE_URL (self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.)

Required environment variables

없음. 사용자가 개인 서울 열린데이터 광장 OpenAPI key를 직접 발급할 필요는 없다. /v1/seoul-bike/* routes는 기본 hosted proxy에서 호출하고, upstream key는 proxy 서버 쪽에만 보관한다.

Single entrypoint

python3 "$SKILL_DIR/scripts/seoul_bike.py" <subcommand> [args]

첫 사용 시 Bash(python3 *seoul_bike.py:*) 패턴 한 번만 승인하면 이후 호출은 모두 자동 허용된다.

Subcommands

명령 설명
nearby --lat LAT --lon LON [--radius-m 500] [--limit 10] [--json] 좌표 주변 실시간 대여소 조회
search <키워드> [--limit 10] [--json] 대여소 이름에 키워드가 포함된 실시간 상태 검색
realtime [--start-index 1 --end-index 1000] 실시간 대여정보 원문 JSON 페이지 조회

Workflow

1. 현재 위치 주변 대여소 조회

python3 "$SKILL_DIR/scripts/seoul_bike.py" nearby --lat 37.5717 --lon 126.9763 --radius-m 500

요약 항목:

  • 대여소명
  • 대여 가능 자전거 수 (parkingBikeTotCnt)
  • 빈 거치대 수 (rackTotCnt - parkingBikeTotCnt)
  • 거리(m)
  • 조회 시각(proxy.requested_at)

2. 대여소 이름 검색

python3 "$SKILL_DIR/scripts/seoul_bike.py" search "광화문" --limit 5

3. Proxy endpoints

  • GET /v1/seoul-bike/realtime?startIndex=1&endIndex=1000 → 서울 bikeList 실시간 대여정보
  • GET /v1/seoul-bike/stations?startIndex=1&endIndex=1000 → 서울 tbCycleStationInfo 대여소 마스터 정보
  • GET /v1/seoul-bike/nearby?lat=37.5717&lon=126.9763&radius_m=500&limit=10 → proxy-side 주변 대여소 필터링

Done when

  • 대여 가능 자전거 수와 빈 거치대 수가 정리되어 있다.
  • live data 기준 조회 시각이 명시되어 있다.
  • upstream key가 클라이언트에 노출되지 않았다.

Failure modes

  • proxy upstream key 미설정 (SEOUL_OPEN_API_KEY 없음)
  • 서울 열린데이터 광장 quota 초과
  • 실시간 API가 빈 행 또는 일시 오류를 반환
  • 좌표가 없거나 반경 안에 대여소가 없음

Notes

  • 실시간 데이터는 계속 변하므로 답변에 조회 시각을 함께 적는다.
  • 예약/대여 자동화는 하지 않는다. 조회 전용 스킬이다.
  • proxy 운영/환경변수 설정은 docs/features/k-skill-proxy.md 를 참고한다.