korea-air-quality

# korea-air-quality 대한민국 지역의 대기질을 OpenClaw에서 자연어로 조회하고, 브리핑/감시 흐름으로 연결한다. ## Quick start 우선 `references/api-and-product-plan.md` 를 읽고 데이터 소스/범위를 확인한다. 그 다음 아래 흐름으로 처리한다. 1. 사용자가 원하는 것이 무엇인지 분류한다. - 지금/오늘 대기질 조회 - 현재 위치 기반 조회 - 기본 지역 저장/변경 - 나쁨 이상 알림 - 아침 브리핑 - 여러 지역 비교 2. 지역 결정을 시도한다. - 1순위: 사용자가 방금 공유한 위치 좌표 - 2순위: 저장된 기본 지역 - 3순위: 메시지에 포함된 지역명 3. 지역이 확정되면 측정소/행정구역 후보를 해석한다. 4. 실시간 대기질과 예보를 조합해 짧고 실용적으로 요약한다. 5. 반복 요청이면 alert/cron 흐름으로 바꾼다. ## Core capabilities ### 1. 현재 대기질 조회 다음 같은 요청을 처리한다. - `지금 우리 동네 미세먼지 어때?` - `오늘 서울 공기질 알려줘` - `성동구 초미세먼지 어때?` - `분당 공기 어때?` 반드시 포함한다. - 기준 지역 또는 측정소 - 측정 시각 - PM10 / PM2.5 / O3 가능 범위 - 등급(좋음/보통/나쁨/매우나쁨) - 한 줄 행동 가이드 ### 2. 현재 위치 기반 조회 사용자가 위치를 직접 보내거나 좌표가 있으면 가장 우선한다. 좌표가 있으면 가장 가까운 측정소를 찾는 방식으로 해석한다. 좌표가 없으면 저장된 기본 지역을 사용하고, 그것도 없으면 지역명을 다시 물어본다. ### 3. 기본 지역 저장 다음 요청을 처리한다. - `내 기본 지역을 성동구로 저장해줘` - `앞으로는 분당 기준으로 알려줘` - `기본 지역 삭제해줘` - `내 현재 위치를 기본 위치로 저장해줘` 저장 위치는 `data/user-preferences.json` 같은 로컬 파일을 우선 고려한다. 사용자별 식별자가 필요하면 채널 사용자 id를 키로 쓴다. 현재 버전은 지역명 저장과 좌표 저장(`save-location`) 모두 지원한다. ### 4. 알림 / 감시 다음 요청을 처리한다. - `초미세먼지 나쁨 이상이면 알려줘` - `서울 오존 나쁘면 알려줘` - `출근 시간에 공기 안 좋으면 알려줘` 현재 버전은 `alert-add`, `alert-list`, `alert-check` 명령으로 로컬 규칙 저장/점검이 가능하다. `alert-check` 는 기본적으로 중복 hit를 다시 알리지 않도록 상태를 저장한다. 반복 감시는 watch 성격의 로컬 규칙 + OpenClaw cron 조합으로 설계한다. ### 5. 아침 브리핑 다음 요청을 처리한다. - `매일 아침 7시에 오늘 공기질 알려줘` - `날씨랑 같이 대기질 브리핑해줘` 현재 버전은 `morning-brief` 명령으로 날씨 + 대기질 결합 브리핑을 생성할 수 있다. 브리핑은 모바일에서 읽기 좋게 짧게 쓰고, 아래 순서를 권장한다. - 지역 - 현재/예상 등급 - 핵심 수치 - 외출/환기/마스크 한 줄 팁 ## Location resolution policy 항상 아래 우선순위를 사용한다. 1. 사용자가 방금 보낸 위치 좌표 2. 저장된 기본 지역 3. 메시지에 적힌 지역명 4. 아무 정보가 없으면 지역을 짧게 재질문 `우리 동네`, `내 위치`, `지금 있는 곳` 같은 표현은 좌표 또는 기본 지역 해석을 먼저 시도한다. ## Output style 출력은 한국어로, 짧고 실용적으로 쓴다. 권장 형식: - `성동구 인근 측정소 기준` - `초미세먼지: 38㎍/㎥ · 나쁨` - `미세먼지: 54㎍/㎥ · 보통` - `한줄 요약: 오늘은 초미세먼지가 다소 높은 편이라 장시간 야외활동은 줄이는 게 좋겠어.` - `행동 팁: 창문 환기는 짧게, 외출 시 마스크 권장` 여러 지역 비교일 때는 지역별 1~2줄 요약으로 정리한다. ## Resources ### references/api-and-product-plan.md 데이터 소스 후보, 권장 MVP 범위, 위치 반영 전략, 알림 설계를 정리한 문서다. 이 스킬을 확장하거나 실제 API를 연결할 때 먼저 읽는다. ### scripts/air_quality.py 실행 가능한 CLI다. 현재 버전은 Open-Meteo 기반으로 한국 지역 대기질 조회가 가능하며, 지역명 해석, 기본 지역/기본 좌표 저장, 여러 지역 비교, 알림 점검, 중복 알림 방지, 아침 브리핑, OpenClaw cron 초안 생성을 지원한다. `--provider airkorea` 레이어와 `setup-provider` 설정 흐름도 준비돼 있어 국내 API 연결 시 이 파일을 중심으로 확장한다.