Back to Details

foresttrip-vacancy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Foresttrip Vacancy

Foresttrip空位查询

What this skill does

本Skill的功能

숲나들e 공식 사이트(
https://foresttrip.go.kr/index.jsp
)에서 자연휴양림 예약 가능 객실을 날짜 기준으로 조회 자동화한다.
이 스킬은 조회 전용 자동화이다. 예약 신청, 결제, 캡차 처리, 대기열 우회, 반복 스나이핑은 범위에 포함하지 않는다.
自动在숲나들e官方网站(
https://foresttrip.go.kr/index.jsp
)上按日期查询自然休养林的可预订房间。
本Skill是仅用于查询的自动化工具。不包含预订申请、支付、验证码（Captcha）处理、插队、重复抢购等功能。

When to use

使用场景

  • "이번 주말 자연휴양림 빈 객실 있어?"
  • "숲나들e 2026년 5월 4일 예약 가능한 곳 조회해줘"
  • "자연휴양림 빈자리 전체 조회해줘"
  • "관심 휴양림 중 예약 가능한 객실만 알려줘"
  • "这周末自然休养林有空房吗？"
  • "帮我查询숲나들e 2026年5月4日的可预订场地"
  • "查询所有自然休养林的空位"
  • "只告诉我关注的休养林中可预订的房间"

When not to use

非使用场景

  • 예약 신청이나 결제까지 자동화해야 하는 경우
  • 캡차를 풀거나 대기열을 우회해야 하는 경우
  • 계정 정보를 채팅창에 직접 넣으려는 경우
  • aggressive polling, 스나이핑, 반복 예약 시도가 필요한 경우
  • 需要自动化完成预订申请或支付的情况
  • 需要破解验证码或插队的情况
  • 想要在聊天窗口直接输入账户信息的情况
  • 需要频繁轮询、抢购或重复尝试预订的情况

Prerequisites

前置条件

  • Python 3.9+
  • Playwright Chromium browser
bash
python3 -m pip install playwright
python3 -m playwright install chromium
python3 scripts/run_foresttrip_vacancy.py --check-deps
  • Python 3.9+
  • Playwright Chromium browser
bash
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
  • KSKILL_FORESTTRIP_ID
  • KSKILL_FORESTTRIP_PASSWORD
可选：
  • 无

Credential resolution order

凭证获取顺序

  1. 이미 환경변수에 있으면 그대로 사용한다.
  2. 에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면 거기서 꺼내 환경변수로 주입해도 된다.
  3. ~/.config/k-skill/secrets.env
     (기본 fallback) — plain dotenv 파일, 퍼미션 
    0600
    .
  4. 아무것도 없으면 유저에게 물어서 2 또는 3에 저장한다.
기본 경로에 저장하는 것은 fallback일 뿐, 강제가 아니다. Helper 자체는 
KSKILL_FORESTTRIP_ID
, 
KSKILL_FORESTTRIP_PASSWORD
환경변수만 읽는다. vault나 
secrets.env
를 사용하는 경우에도 실행 전에 해당 값을 환경변수로 주입한다.
  1. 已存在于环境变量中：直接使用
  2. Agent正在使用自有密钥库（1Password CLI、Bitwarden CLI、macOS Keychain等）：可从中取出并注入到环境变量
  3. ~/.config/k-skill/secrets.env
    （默认备选）——纯dotenv文件，权限设为
    0600
  4. 无任何凭证时：询问用户并保存到上述第2或第3种方式中
默认路径仅作为备选方案，并非强制要求。 Helper仅读取
KSKILL_FORESTTRIP_ID
、
KSKILL_FORESTTRIP_PASSWORD
环境变量。即使使用密钥库或
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
  • 日期：
    YYYYMMDD
    ，多个日期用逗号分隔
    YYYYMMDD,YYYYMMDD
  • 查询范围： 
    • --all
      ：查询所有自然休养林
    • --forest-id
      ：查询指定
      insttId
      的休养林
    • --forest-name
      ：按官方休养林名称模糊查询
  • 输出格式： 
    • --text
      ：面向用户的简洁总结
    • --json
      ：结构化结果
  • 可选筛选条件： 
    • --categories 01
      ：住宿
    • --categories 02
      ：露营
    • --categories 01,02
      ：住宿+露营
  • 高级执行选项： 
    • --week-range N
      ：仅在未指定
      --dates
      时，查询从今日起N周内的空位
    • --concurrency N
      ：并行查询的工作线程数，范围1-5
    • --session-cache PATH
      ：覆盖登录会话缓存路径

Workflow

工作流程

1. Ensure credentials are available

1. 确保凭证可用

KSKILL_FORESTTRIP_ID
, 
KSKILL_FORESTTRIP_PASSWORD
가 설정되어 있는지 확인한다. 없으면 credential resolution order에 따라 확보한다.
시크릿이 없다는 이유로 대체 사이트, 캡차 우회, 비공식 예약 경로를 찾지 않는다.
检查
KSKILL_FORESTTRIP_ID
、
KSKILL_FORESTTRIP_PASSWORD
是否已设置。若未设置，则按照凭证获取顺序获取。
不会因无凭证而寻找替代网站、破解验证码或使用非官方预订渠道。

2. Install runtime dependencies when missing

2. 安装缺失的运行依赖

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

3. Run a vacancy lookup

3. 执行空位查询

이 스킬의 helper를 통해 조회한다. Helper는 Playwright로 숲나들e에 로그인해 CSRF/cookie와 공식 휴양림 ID 목록을 얻은 뒤, 월별예약조회 JSON endpoint만 호출한다.
2026-04-29 확인 기준, 로그인 없이 월별예약조회 화면에 접근하면 
401 Unauthorized
가 반환되고, 조회 endpoint는 JSON 대신 안내 HTML을 반환한다. 따라서 현재 helper는 로그인 세션/CSRF 확보를 필수 전제로 둔다.
전체 자연휴양림에서 특정 날짜 조회:
bash
python3 scripts/run_foresttrip_vacancy.py --all --text --dates 20260504
JSON 출력:
bash
python3 scripts/run_foresttrip_vacancy.py --all --json --dates 20260504
캠핑/야영만 조회:
bash
python3 scripts/run_foresttrip_vacancy.py --all --text --dates 20260504 --categories 02
특정 휴양림명으로 조회:
bash
python3 scripts/run_foresttrip_vacancy.py --forest-name 유명산 --text --dates 20260504
通过本Skill的Helper执行查询。Helper使用Playwright登录숲나들e，获取CSRF/cookie以及官方休养林ID列表后，仅调用月度预订查询的JSON接口。
截至2026年4月29日验证，未登录时访问月度预订查询页面会返回
401 Unauthorized
，查询接口会返回提示HTML而非JSON。因此当前Helper必须以获取登录会话/CSRF为前提。
查询所有自然休养林在指定日期的空位：
bash
python3 scripts/run_foresttrip_vacancy.py --all --text --dates 20260504
输出JSON格式结果：
bash
python3 scripts/run_foresttrip_vacancy.py --all --json --dates 20260504
仅查询露营空位：
bash
python3 scripts/run_foresttrip_vacancy.py --all --text --dates 20260504 --categories 02
按指定休养林名称查询：
bash
python3 scripts/run_foresttrip_vacancy.py --forest-name 유명산 --text --dates 20260504

4. Summarize results conservatively

4. 保守地总结结果

응답은 아래 항목 중심으로 짧게 정리한다.
  • 조회 날짜
  • 조회 범위
  • 예약 가능한 휴양림명
  • 객실/시설명
  • 숙박/야영 구분
  • 정원 또는 수용 인원
  • fetch failure가 있으면 실패 개수
결과가 없으면 "조회 시점 기준 예약 가능 객실 없음"이라고 말한다. 실제 예약 가능 여부는 숲나들e 화면에서 재확인될 수 있음을 덧붙인다.
响应主要围绕以下内容简洁整理：
  • 查询日期
  • 查询范围
  • 可预订的休养林名称
  • 房间/设施名称
  • 住宿/露营类型
  • 定员或可容纳人数
  • 若存在获取失败的情况，需说明失败数量
若无结果，则提示“查询时点无可用预订房间”，并补充说明实际可预订情况需在숲나들e页面再次确认。

Done when

完成标志

  • 요청 날짜와 조회 범위가 명확하다.
  • read-only 월별예약조회 helper를 최소 1회 실행했다.
  • 빈 객실이 있으면 날짜/휴양림/객실을 정리했다.
  • 빈 객실이 없으면 없다고 명확히 말했다.
  • 예약/결제/대기열 우회는 시도하지 않았다.
  • 请求日期和查询范围明确
  • 至少执行一次只读的月度预订查询Helper
  • 若有空房，已整理日期/休养林/房间信息
  • 若无空房，已明确告知
  • 未尝试预订/支付/插队等操作

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 점검 필요
  • 登录失败：检查
    KSKILL_FORESTTRIP_ID
    、
    KSKILL_FORESTTRIP_PASSWORD
  • Playwright浏览器未安装：执行
    python3 -m playwright install chromium
  • 部分获取失败：同时报告结果和失败数量，必要时使用
    --refresh-session
    重新查询一次
  • 숲나들e页面变更：需检查Helper的登录/会话初始化或解析逻辑

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
같은 비민감 요약만 남기고 계정 정보, 세션 쿠키, 개인 조회 세부 내역은 공유하지 않는다.
维护者无需为审核本Skill新创建숲나들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
实际在线测试由贡献者或已有숲나들e账户的用户选择性执行。PR中仅保留
forests_scanned
、
fetch_failures
、
filter_hits
等非敏感总结信息，不得共享账户信息、会话Cookie、个人查询详情。

Safety notes

安全说明

  • 조회 전용 스킬이다.
  • 예약, 결제, 캡차 처리, 대기열 우회, 공격적인 반복 조회를 하지 않는다.
  • 계정 시크릿은 환경변수 또는 
    ~/.config/k-skill/secrets.env
    로만 다룬다.
  • 本Skill仅用于查询
  • 不执行预订、支付、验证码处理、插队、攻击性重复查询等操作
  • 账户密钥仅通过环境变量或
    ~/.config/k-skill/secrets.env
    管理