mirror of
https://github.com/NomaDamas/k-skill.git
synced 2026-06-24 02:04:11 +00:00
68abad3de0* Enable public local-election candidate lookups Add an NEC integrated-search skill and helper package so agents can answer 지방선거 후보자 lookup requests without credentials or proxy routes. Constraint: Issue #256 requested TDD, Ralph completion, branch feature/#256, and PR targeting dev. Rejected: k-skill-proxy route | NEC integrated candidate search is public and requires no API key. Confidence: high Scope-risk: moderate Directive: Keep the helper read-only and do not automate NEC login, CAPTCHA, filing, or privileged election workflows. Tested: git diff --check; node --test packages/local-election-candidate-search/test/index.test.js; npm run lint --workspace local-election-candidate-search; npm run test --workspace local-election-candidate-search; npm pack --workspace local-election-candidate-search --dry-run; node packages/local-election-candidate-search/src/cli.js 오세훈 --election 시도지사 --region 서울 --limit 1; PATH=/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin:/Users/jeffrey/.codex/tmp/arg0/codex-arg0a6JueA:/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: Exhaustive NEC markup variants for every historical election type. Co-authored-by: OmX <omx@oh-my-codex.dev> * Enforce fail-closed candidate identity parsing Constraint: PR #266 review required exact candidate-name matching and CLI help regression coverage.\nRejected: fallback-to-query-name on missing upstream markup | it can mislabel unrelated candidates as exact matches.\nConfidence: high\nScope-risk: narrow\nDirective: Keep NEC parser changes fail-closed when candidate identity cannot be parsed.\nTested: git diff --check; node --test packages/local-election-candidate-search/test/index.test.js; npm run lint --workspace local-election-candidate-search; npm run test --workspace local-election-candidate-search; npm pack --workspace local-election-candidate-search --dry-run; live CLI smoke for 오세훈; CLI --help smoke.\nNot-tested: repo-wide npm run ci remains blocked by pre-existing missing SKILL.md: ohou-today-deal. * Preserve unique candidate lookup results Deduplicate parsed NEC candidate/election rows before applying user limits, and make expected CLI validation failures concise by default while keeping an explicit debug stack escape hatch. Constraint: PR #266 round-2 follow-up requested TDD fixes for duplicate NEC rows and CLI validation UX.\nRejected: Deduplicating after limit | would still allow duplicates to crowd out unique rows.\nRejected: Always printing stack traces | exposes local paths for normal user-input failures.\nConfidence: high\nScope-risk: narrow\nDirective: Keep dedupe keys stable enough to avoid collapsing legitimately distinct historical election rows.\nTested: git diff --check; node --test packages/local-election-candidate-search/test/index.test.js; npm run lint --workspace local-election-candidate-search; npm run test --workspace local-election-candidate-search; npm pack --workspace local-election-candidate-search --dry-run; live 오세훈 smoke; live 김동연 duplicate repro; CLI no-args/help.\nNot-tested: Full npm run ci remains blocked by pre-existing missing SKILL.md: ohou-today-deal. * Prevent filtered NEC lookup false negatives Fix the candidate parser so documented education-superintendent and filtered local-election lookups return bounded, evidence-backed results instead of silently dropping valid rows. Constraint: PR #266 round-3 review required TDD, Ralph verification, and branch update for issue #256. Rejected: Full NEC pagination in this follow-up | broader than the approved change; bounded 100-row fetch now avoids user-limit false negatives and warns when capped. Confidence: high Scope-risk: narrow Directive: Preserve exact-name fail-closed parsing and count raw parsed upstream rows before cap-warning decisions. Tested: git diff --check; node --test packages/local-election-candidate-search/test/index.test.js; npm run lint --workspace local-election-candidate-search; npm run test --workspace local-election-candidate-search; npm pack --workspace local-election-candidate-search --dry-run; live CLI smokes for 오세훈, 조희연, 김동연; CLI help/no-args checks; architect verification CLEAR. Not-tested: Full npm run ci remains blocked by pre-existing repo-wide missing SKILL.md: ohou-today-deal. --------- Co-authored-by: OmX <omx@oh-my-codex.dev>
9.7 KiB
9.7 KiB
공통 설정 가이드
k-skill 전체 스킬을 설치한 뒤, 인증 정보가 필요한 기능(SRT 예매, KTX 예매, 자연휴양림 빈 객실 조회, KOSIS bigdata/--direct 조회용 KSKILL_KOSIS_API_KEY (https://kosis.kr/openapi/ 에서 무료 발급), 한국 법령 검색의 로컬 CLI/MCP 경로용 LAW_OC, 한국 특허 정보 검색의 KIPRIS Plus 경로용 KIPRIS_PLUS_API_KEY, self-host 프록시 운영용 서울 지하철/한국 날씨/미세먼지/한강홍수통제소/식약처/KOSIS/Kakao upstream key, 또는 배포 확인이 끝난 proxy URL 공유)이 있으면 이 절차를 진행하면 된다. 미세먼지, 한강 수위, 주유소 가격, 부동산 실거래가, 한국 주식 정보 조회, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회, 의약품 안전 체크, 식품 안전 체크는 기본 hosted proxy를 쓰므로 사용자 쪽 키가 불필요하다. KOSIS 일반 조회와 Kakao Local geocoding도 기본 hosted proxy를 쓰므로 사용자 쪽 키가 불필요하다(단, hosted 프록시 운영 측에서 DATA_GO_KR_API_KEY·KEDU_INFO_KEY·DATA4LIBRARY_AUTH_KEY·FOODSAFETYKOREA_API_KEY·KOSIS_API_KEY·KAKAO_REST_API_KEY 등은 서버에 설정되어 있어야 한다).
Credential resolution order
모든 credential-bearing 스킬은 아래 우선순위를 따른다.
- 이미 환경변수에 있으면 그대로 사용한다.
- 에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면 거기서 꺼내 환경변수로 주입해도 된다.
~/.config/k-skill/secrets.env(기본 fallback) — plain dotenv 파일, 퍼미션0600.- 아무것도 없으면 유저에게 물어서 2 또는 3에 저장한다.
에이전트가 자체 vault를 사용 중이라면 기본 경로 설정을 건너뛰어도 된다.
기본 경로로 설정하기
에이전트가 별도 vault를 쓰지 않는 경우, 기본 fallback 파일을 만든다.
mkdir -p ~/.config/k-skill
cat > ~/.config/k-skill/secrets.env <<'EOF'
KSKILL_SRT_ID=replace-me
KSKILL_SRT_PASSWORD=replace-me
KSKILL_KTX_ID=replace-me
KSKILL_KTX_PASSWORD=replace-me
KSKILL_FORESTTRIP_ID=replace-me
KSKILL_FORESTTRIP_PASSWORD=replace-me
# KOSIS 일반 조회는 hosted proxy 사용. bigdata/--direct 때만 채운다.
KSKILL_KOSIS_API_KEY=replace-me
# 창업진흥원 K-Startup 일반 조회는 hosted proxy 사용. --direct 때만 채운다.
KSKILL_KSTARTUP_API_KEY=replace-me
LAW_OC=replace-me
KIPRIS_PLUS_API_KEY=replace-me
AIR_KOREA_OPEN_API_KEY=replace-me
# Kakao Local geocoding은 hosted proxy 사용. self-host proxy 운영 때만 채운다.
KAKAO_REST_API_KEY=replace-me
KSKILL_PROXY_BASE_URL=
EOF
chmod 0600 ~/.config/k-skill/secrets.env
실제 값을 채운다.
서울 지하철 도착정보, 한국 날씨, 미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회, 의약품 안전 체크, 식품 안전 체크는 KSKILL_PROXY_BASE_URL 을 비워 두면 기본 hosted path(k-skill-proxy.nomadamas.org)를 그대로 쓴다. KOSIS 일반 조회와 Kakao Local geocoding도 같은 기본 hosted path를 쓴다. 별도 self-host proxy를 쓸 때만 KSKILL_PROXY_BASE_URL 을 채운다.
한국 법령 검색의 로컬 CLI/MCP 경로용 LAW_OC 는 korean-law-mcp 로컬 실행에 쓴다. 로컬 CLI/MCP 경로는 LAW_OC 를 채운 뒤 npm install -g korean-law-mcp 와 korean-law list 로 설치 상태를 확인한다.
remote MCP endpoint는 사용자 LAW_OC 없이 url만으로 연결한다. 다만 기존 korean-law-mcp 경로가 서비스 장애로 막히면 법망(https://api.beopmang.org) MCP/REST를 fallback으로 사용할 수 있다.
한국 부동산 실거래가 조회는 기본 hosted proxy(k-skill-proxy.nomadamas.org)를 경유하므로 사용자 쪽 DATA_GO_KR_API_KEY 가 불필요하다.
한국 주식 정보 조회는 기본 hosted proxy(k-skill-proxy.nomadamas.org)를 경유하므로 사용자 쪽 KRX_API_KEY 가 불필요하다. self-host proxy 운영자만 서버 환경변수 KRX_API_KEY 를 사용한다.
도서관 도서 조회는 기본 hosted proxy(k-skill-proxy.nomadamas.org)를 경유하므로 사용자 쪽 DATA4LIBRARY_AUTH_KEY 가 불필요하다. self-host proxy 운영자만 서버 환경변수 DATA4LIBRARY_AUTH_KEY 를 사용한다.
근처 가장 싼 주유소 찾기는 기본 hosted proxy(k-skill-proxy.nomadamas.org)를 경유하므로 사용자 쪽 OPINET_API_KEY 가 불필요하다.
한국 특허 정보 검색의 KIPRIS Plus 경로용 KIPRIS_PLUS_API_KEY 는 helper가 읽는 표준 변수명이다. 실제 HTTP 요청에서는 같은 값을 ServiceKey 쿼리 파라미터로 보낸다. 공공데이터포털에서 복사한 percent-encoded key도 helper가 한 번 정규화해서 그대로 쓸 수 있다.
확인
bash scripts/check-setup.sh
시크릿이 없을 때의 기본 응답
인증이 필요한 스킬에서 값이 비어 있으면 credential resolution order에 따라 확보한다.
- 어떤 값이 필요한지 정확한 변수 이름으로 알려주기
- resolution order에 따라 유저에게 확보 방법 안내하기
기능별로 필요한 값
| 기능 | 필요한 값 |
|---|---|
| SRT 예매 | KSKILL_SRT_ID, KSKILL_SRT_PASSWORD |
| KTX 예매 | KSKILL_KTX_ID, KSKILL_KTX_PASSWORD |
| 고속버스 예매 | 사용자 시크릿 불필요 (조회·좌석 단계는 공식 KOBUS HTTP 흐름 사용, 결제는 공식 페이지에서 수동 진행) |
| 시외버스 예매 | 사용자 시크릿 불필요 (조회·좌석 단계는 공식 티머니 HTTP 흐름 사용, 결제는 공식 페이지에서 수동 진행) |
| 자연휴양림 빈 객실 조회 | KSKILL_FORESTTRIP_ID, KSKILL_FORESTTRIP_PASSWORD |
| 한국 법령 검색 (로컬 CLI/MCP) | LAW_OC |
| 한국 법령 검색 (remote MCP endpoint) | 사용자 시크릿 불필요 (url만 등록, 장애 시 법망 fallback 가능) |
| 한국 부동산 실거래가 조회 | 사용자 시크릿 불필요 (기본 hosted proxy 사용) |
| 한국 특허 정보 검색 | KIPRIS_PLUS_API_KEY |
| 하이패스 영수증 발급 | 사용자 시크릿 불필요 (로그인된 브라우저 세션 필요) |
| 한국 주식 정보 조회 | 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 KRX_API_KEY) |
| 근처 가장 싼 주유소 찾기 | 사용자 시크릿 불필요 (기본 hosted proxy 사용) |
| 서울 지하철 도착정보 조회 | 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 SEOUL_OPEN_API_KEY) |
| 서울 실시간 혼잡도 조회 | 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 SEOUL_OPEN_API_KEY) |
| 한국 날씨 조회 | 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 KMA_OPEN_API_KEY) |
| 사용자 위치 미세먼지 조회 | KSKILL_PROXY_BASE_URL 또는 AIR_KOREA_OPEN_API_KEY |
| 한강 수위 정보 조회 | 사용자 시크릿 불필요 (기본 hosted proxy 사용) |
| 생활쓰레기 배출정보 조회 | 사용자 시크릿 불필요 (프록시에 DATA_GO_KR_API_KEY가 설정된 hosted/self-host; API 호출 시 pageNo=1, numOfRows=100 필수) |
| 학교 급식 식단 조회 | 사용자 시크릿 불필요 (프록시에 KEDU_INFO_KEY가 설정된 hosted/self-host 사용) |
| 도서관 도서 조회 | 사용자 시크릿 불필요 (프록시에 DATA4LIBRARY_AUTH_KEY가 설정된 hosted/self-host 사용) |
| 의약품 안전 체크 | 사용자 시크릿 불필요 (프록시에 DATA_GO_KR_API_KEY가 설정된 hosted/self-host 사용) |
| 식품 안전 체크 | 사용자 시크릿 불필요 (프록시에 DATA_GO_KR_API_KEY와 선택적 FOODSAFETYKOREA_API_KEY가 설정된 hosted/self-host 사용) |
| 창업진흥원 K-Startup 조회 | 사용자 시크릿 불필요 (프록시에 DATA_GO_KR_API_KEY가 설정된 hosted/self-host 사용; --direct 호출 때만 KSKILL_KSTARTUP_API_KEY) |
다음에 볼 문서
- SRT 예매 가이드
- KTX 예매 가이드
- 고속버스 예매 가이드
- 시외버스 예매 가이드
- 자연휴양림 빈 객실 조회 가이드
- 서울 지하철 도착정보 가이드
- 서울 실시간 혼잡도 가이드
- 한국 날씨 조회 가이드
- 사용자 위치 미세먼지 조회 가이드
- 한강 수위 정보 가이드
- 한국 법령 검색 가이드
- 한국 부동산 실거래가 조회 가이드
- 한국 특허 정보 검색 가이드
- 하이패스 영수증 발급 가이드
- 한국 주식 정보 조회 가이드
- 근처 가장 싼 주유소 찾기 가이드
- 근처 공중화장실 찾기 가이드
- 생활쓰레기 배출정보 조회 가이드
- 학교 급식 식단 조회 가이드
- 도서관 도서 조회 가이드
- 의약품 안전 체크 가이드
- 식품 안전 체크 가이드
- 창업진흥원 K-Startup 조회 가이드
- 지방선거 후보자 조회 가이드
- 보안/시크릿 정책
설치 기본 흐름은 "전체 스킬 설치 → 개별 기능 사용" 이다.