foresttrip-vacancy

SKILL.md

Foresttrip Vacancy

What this skill does

숲나들e 공식 사이트(https://foresttrip.go.kr/index.jsp)에서 자연휴양림 예약 가능 객실을 날짜 기준으로 조회 자동화한다.

이 스킬은 조회 전용 자동화이다. 예약 신청, 결제, 캡차 처리, 대기열 우회, 반복 스나이핑은 범위에 포함하지 않는다.

When to use

"이번 주말 자연휴양림 빈 객실 있어?"

"숲나들e 2026년 5월 4일 예약 가능한 곳 조회해줘"

"자연휴양림 빈자리 전체 조회해줘"

"관심 휴양림 중 예약 가능한 객실만 알려줘"

When not to use

예약 신청이나 결제까지 자동화해야 하는 경우

캡차를 풀거나 대기열을 우회해야 하는 경우

계정 정보를 채팅창에 직접 넣으려는 경우

aggressive polling, 스나이핑, 반복 예약 시도가 필요한 경우

Prerequisites

Python 3.9+

Playwright Chromium browser

python3 -m pip install playwright
python3 -m playwright install chromium
python3 scripts/run_foresttrip_vacancy.py --check-deps

Required environment variables

KSKILL_FORESTTRIP_ID

KSKILL_FORESTTRIP_PASSWORD

Optional:

none

Credential resolution order

이미 환경변수에 있으면 그대로 사용한다.

에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면 거기서 꺼내 환경변수로 주입해도 된다.

~/.config/k-skill/secrets.env (기본 fallback) — plain dotenv 파일, 퍼미션 0600.

아무것도 없으면 유저에게 물어서 2 또는 3에 저장한다.

기본 경로에 저장하는 것은 fallback일 뿐, 강제가 아니다.
Helper 자체는 KSKILL_FORESTTRIP_ID, KSKILL_FORESTTRIP_PASSWORD 환경변수만 읽는다. vault나 secrets.env 를 사용하는 경우에도 실행 전에 해당 값을 환경변수로 주입한다.

Inputs

날짜: YYYYMMDD, 여러 날짜면 comma-separated YYYYMMDD,YYYYMMDD

조회 범위:

--all: 전체 자연휴양림 조회

--forest-id: 특정 insttId 조회

--forest-name: 공식 휴양림명 부분 일치 조회

출력 형식:

--text: 사람용 요약

--json: 구조화 결과

선택 필터:

--categories 01: 숙박

--categories 02: 야영/캠핑

--categories 01,02: 숙박 + 야영/캠핑

고급 실행 옵션:

--week-range N: --dates 를 생략했을 때만 오늘부터 N주 범위를 조회

--concurrency N: 병렬 조회 worker 수, 1-5 범위

--session-cache PATH: 로그인 세션 캐시 경로 override

Workflow

1. Ensure credentials are available

KSKILL_FORESTTRIP_ID, KSKILL_FORESTTRIP_PASSWORD 가 설정되어 있는지 확인한다. 없으면 credential resolution order에 따라 확보한다.

시크릿이 없다는 이유로 대체 사이트, 캡차 우회, 비공식 예약 경로를 찾지 않는다.

2. Install runtime dependencies when missing

python3 -m pip install playwright
python3 -m playwright install chromium

3. Run a vacancy lookup

이 스킬의 helper를 통해 조회한다. Helper는 Playwright로 숲나들e에 로그인해 CSRF/cookie와 공식 휴양림 ID 목록을 얻은 뒤, 월별예약조회 JSON endpoint만 호출한다.

2026-04-29 확인 기준, 로그인 없이 월별예약조회 화면에 접근하면 401 Unauthorized가 반환되고, 조회 endpoint는 JSON 대신 안내 HTML을 반환한다. 따라서 현재 helper는 로그인 세션/CSRF 확보를 필수 전제로 둔다.

전체 자연휴양림에서 특정 날짜 조회:

python3 scripts/run_foresttrip_vacancy.py --all --text --dates 20260504

JSON 출력:

python3 scripts/run_foresttrip_vacancy.py --all --json --dates 20260504

캠핑/야영만 조회:

python3 scripts/run_foresttrip_vacancy.py --all --text --dates 20260504 --categories 02

특정 휴양림명으로 조회:

python3 scripts/run_foresttrip_vacancy.py --forest-name 유명산 --text --dates 20260504

4. Summarize results conservatively

응답은 아래 항목 중심으로 짧게 정리한다.

조회 날짜

조회 범위

예약 가능한 휴양림명

객실/시설명

숙박/야영 구분

정원 또는 수용 인원

fetch failure가 있으면 실패 개수

결과가 없으면 "조회 시점 기준 예약 가능 객실 없음"이라고 말한다. 실제 예약 가능 여부는 숲나들e 화면에서 재확인될 수 있음을 덧붙인다.

Done when

요청 날짜와 조회 범위가 명확하다.

read-only 월별예약조회 helper를 최소 1회 실행했다.

빈 객실이 있으면 날짜/휴양림/객실을 정리했다.

빈 객실이 없으면 없다고 명확히 말했다.

예약/결제/대기열 우회는 시도하지 않았다.

Failure modes

로그인 실패: KSKILL_FORESTTRIP_ID, KSKILL_FORESTTRIP_PASSWORD 확인

Playwright browser 미설치: python3 -m playwright install chromium

fetch failure 일부 발생: 결과와 실패 개수를 함께 보고하고, 필요하면 --refresh-session 으로 1회 재조회

숲나들e 표면 변경: helper의 login/session bootstrap 또는 parser 점검 필요

Maintainer review notes

메인테이너가 이 스킬을 검토하기 위해 숲나들e 계정을 새로 만들 필요는 없다.

계정 없이 가능한 검증:

./scripts/validate-skills.sh

python3 -m py_compile foresttrip-vacancy/scripts/run_foresttrip_vacancy.py

python3 foresttrip-vacancy/scripts/run_foresttrip_vacancy.py --help

python3 foresttrip-vacancy/scripts/run_foresttrip_vacancy.py --check-deps

npm run ci

실제 live smoke는 기여자 또는 이미 숲나들e 계정을 가진 사용자가 선택적으로 수행한다. PR에는 forests_scanned, fetch_failures, filter_hits 같은 비민감 요약만 남기고 계정 정보, 세션 쿠키, 개인 조회 세부 내역은 공유하지 않는다.

Safety notes

조회 전용 스킬이다.

예약, 결제, 캡차 처리, 대기열 우회, 공격적인 반복 조회를 하지 않는다.

계정 시크릿은 환경변수 또는 ~/.config/k-skill/secrets.env 로만 다룬다.