mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00

Jeffrey (Dongkyu) Kim dc9a765e2a

* Align proxy defaults for hosted Korean routes

Constraint: Issue #205 requires unset or empty KSKILL_PROXY_BASE_URL to use the hosted proxy consistently while preserving explicit proxy overrides and server-side upstream keys.\nRejected: Keeping Seoul subway and Korea weather as self-host-only routes | it preserves the documented inconsistency and blocks zero-config usage.\nConfidence: high\nScope-risk: narrow\nDirective: Keep client docs pointing to hosted proxy defaults unless a route is intentionally removed from hosted service.\nTested: node --test scripts/skill-docs.test.js; npm run ci; hosted smoke curls for /v1/seoul-subway/arrival and /v1/korea-weather/forecast; architect verification approved.\nNot-tested: Private self-host proxy deployment.

* Preserve hosted proxy fallback in setup guidance

Make self-host proxy examples inactive by default so client setup no longer blocks the hosted proxy resolver contract for Seoul subway and Korea weather skills.

Constraint: PR #210 review required unset and empty KSKILL_PROXY_BASE_URL to fall back to https://k-skill-proxy.nomadamas.org while preserving explicit self-host overrides.\nRejected: Keep active https://your-proxy.example.com placeholder | It creates a non-empty override and prevents hosted fallback for users copying the default secrets file.\nConfidence: high\nScope-risk: narrow\nDirective: Keep upstream API keys documented as proxy-operator/server-side only; do not reintroduce active client-side proxy placeholders for hosted-default flows.\nTested: node --test scripts/skill-docs.test.js; npm run ci; hosted smoke checks for /v1/seoul-subway/arrival?stationName=강남 and /v1/korea-weather/forecast?lat=37.5665&lon=126.9780; resolver smoke for unset, empty, and custom KSKILL_PROXY_BASE_URL; git diff --check; Ralph architect verification CLEAR.\nNot-tested: none

* Clarify proxy guide override boundary

Document the hosted-client default in the proxy guide while keeping the self-host placeholder as an explicitly scoped override, so users do not mistake it for required setup.

Constraint: Issue #205 review round 2 left a WATCH concern on docs/features/k-skill-proxy.md client env-var wording.

Rejected: Leave the proxy guide unchanged | It preserved ambiguity between hosted-client defaults and self-host/operator overrides.

Rejected: Sentence-exact regression assertions | They were too brittle after code review; semantic assertions preserve wording flexibility while locking the policy.

Confidence: high

Scope-risk: narrow

Directive: Keep KSKILL_PROXY_BASE_URL examples inactive or clearly scoped unless documenting a self-host/alternate-proxy override.

Tested: node --test scripts/skill-docs.test.js; npm run ci; resolver smoke for unset empty and custom KSKILL_PROXY_BASE_URL; hosted Seoul subway and Korea weather smokes; git diff --check; code-reviewer APPROVE; architect CLEAR

Not-tested: none

* Keep proxy guide examples on the hosted-default path

Constraint: PR #210 issue #205 follow-up requires KSKILL_PROXY_BASE_URL unset/empty to resolve to hosted while preserving explicit self-host overrides.\nRejected: Labeling the existing 127.0.0.1 examples as operator-only | it would leave the general usage section less aligned with the hosted-client default.\nConfidence: high\nScope-risk: narrow\nDirective: Keep Seoul subway and Korea weather user-facing examples on the resolver pattern unless the section is explicitly scoped to local operator smoke tests.\nTested: node --test scripts/skill-docs.test.js; npm run ci; resolver smoke for unset empty custom KSKILL_PROXY_BASE_URL; hosted Seoul subway and Korea weather smoke; architect verification CLEAR.\nNot-tested: None.

2026-05-06 16:56:40 +09:00

2.6 KiB

Raw Permalink Blame History

서울 지하철 도착정보 가이드

이 기능으로 할 수 있는 일

역 기준 실시간 도착 예정 열차 조회
상/하행 또는 외/내선 정보 확인
첫 번째/두 번째 도착 메시지 확인
개인 OpenAPI key 없이 k-skill-proxy 경유 조회

먼저 필요한 것

공통 설정 가이드 완료
보안/시크릿 정책 확인
optional: KSKILL_PROXY_BASE_URL (self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용)

필요한 환경변수

없음. KSKILL_PROXY_BASE_URL 은 선택 사항이며, 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.

사용자가 서울 열린데이터 광장 OpenAPI key를 직접 발급할 필요는 없다. /v1/seoul-subway/arrival route는 기본 hosted proxy에서 호출하고, upstream key는 proxy 서버에서만 관리한다. 별도 proxy를 쓰는 경우에만 KSKILL_PROXY_BASE_URL 을 설정한다.

Proxy resolution order

KSKILL_PROXY_BASE_URL 이 있으면 그 값을 사용합니다.
없거나 빈 값이면 기본 hosted proxy https://k-skill-proxy.nomadamas.org 를 사용합니다.
직접 proxy를 운영하는 경우에만 proxy 서버 upstream key를 서버 쪽에만 설정합니다.

입력값

역명
선택 사항: 가져올 건수

기본 흐름

KSKILL_PROXY_BASE_URL 이 있으면 그 값을 사용하고, 없거나 비어 있으면 기본 hosted proxy https://k-skill-proxy.nomadamas.org 를 사용합니다.
/v1/seoul-subway/arrival?stationName=... 로 역명 기준 실시간 도착정보를 조회합니다.
호선, 진행 방향, 도착 메시지, 조회 시점을 함께 요약합니다.

예시

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/seoul-subway/arrival" \
  --data-urlencode 'stationName=강남'

범위를 줄이거나 늘리고 싶으면:

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/seoul-subway/arrival" \
  --data-urlencode 'stationName=서울역' \
  --data-urlencode 'startIndex=0' \
  --data-urlencode 'endIndex=4'

주의할 점

실시간 데이터라 몇 초 단위로 바뀔 수 있습니다.
역명 표기가 다르면 결과가 비어 있을 수 있습니다.
일일 호출 제한이나 quota 초과 가능성이 있습니다.
self-host proxy 설정은 k-skill 프록시 서버 가이드를 봅니다.

2.6 KiB Raw Permalink Blame History