TripCheat · AI 行程规划专家（trip-cheat-sheet）은(는) 무엇을 하나요?
사용자가 제공하는 항공편, 호텔, 회의 일정, 티켓, 가이드 스크린샷 및 대화 기록을 하나의 휴대용 웹페이지로 정리합니다: 일정 타임라인 (오늘 몇 시에 어디로), 체크리스트 (놓치지 말아야 할 것), 핸드북 (이동 방법/결제 방법/문제 발생 시 연락처). 모바일에서 바로 사용 가능하며, 이중 시간대, 다크 테마, 글꼴 크기 조절, 지도 딥 링크, QR 코드 티켓을 지원하고 모든 정적 호스팅에 배포할 수 있습니다.
이 페이지는 이 스킬에 포함된 생성기가 trip.json 파일을 기반으로 빌드합니다. 데이터 계약은 references/trip-schema.md, 작성 규칙은 references/content-guide.md, 배포는 references/deploy.md를 참조하세요.
사용 시기
트리거 상황
- 「여행 일정 만들어 줘」「항공편, 호텔, 회의 일정 한 페이지로 정리해 줘」「출장/회의 준비」
- 「여행 가이드」「휴대용 페이지」「여행 핸드북」「출발 체크리스트」「매일 몇 시에 뭐 하는지」
- 사용자가 여러 스크린샷 / PDF / 이메일 / 링크 / 대화 기록을 제공하며 구조화 + 추가 조사 + 휴대용 페이지로 만들기를 원할 때
- 이미
trip.json이 있는 경우: 페이지 재생성, 테마 변경, 비밀번호 게이트 추가, 배포 또는 티켓 페이지 공유
적용 불가
- 특정 관광지 소개, 날씨, 티켓 예매만 필요한 경우: 직접 검색/답변, 페이지 생성 불필요
- 실시간 재고, 주문, 결제, 체크인이 필요한 경우: 이 스킬은 예약 API를 호출하지 않으며 정보와 링크만 정리
- 순수 경로 안내: 지도 도구 사용, 여행 페이지 불필요
산출물
| 모드 | 명령어 | 결과물 |
|---|---|---|
| 단일 파일 (기본) | node scripts/build.mjs trip.json --out dist | dist/index.html (CSS/JS/데이터/PWA manifest 모두 인라인) + 필요 시 복사된 티켓 이미지 |
| 다중 파일 사이트 | node scripts/build.mjs trip.json --multi --out dist | dist/index.html, dist/ticket-<id>.html, dist/assets/style.css, dist/assets/app.js, dist/manifest.json, 복사된 티켓 리소스 |
페이지 기능: 일정 타임라인 / 체크리스트 / 핸드북 세 가지 보기, 「현재/다음 일정」 하이라이트, 이중 시간대 시계 및 시간 변환, 테마 (paper/slate/night) 및 글꼴 크기 전환, Google/Amap/Apple 지도 딥 링크 (Google 경로 링크는 이동 수단 매개변수 포함), 체크리스트 체크 (로컬 localStorage), 티켓 QR 코드 페이지, 선택적 비밀번호 게이트 (프론트엔드 SHA-256 검증), 홈 화면 추가 (PWA, --no-pwa로 비활성화).
워크플로우 (6단계)
1단계: 자료 수집 (설문 + 파일/스크린샷/링크)
먼저 최대 6개 질문을 한 번에 묻고, 연속 질문은 피하세요. 사용자가 답변하지 않은 항목은 기본값으로 가정하고 명시적으로 「가정」이라고 표시하세요.
- 누가, 몇 명, 관계 (동행자 중 노약자/어린이/장애인 편의 필요 여부)
- 출발지, 날짜 (날짜 변경/심야 포함), 목적지 (여러 도시/경유 여부)
- 예약 완료 항목과 예약 필요 항목 (항공편, 호텔, 회의 등록, 티켓, 레스토랑)
- 회의/활동의 중요 시간 (등록, 개막, 개인 발표/포스터 시간, 만찬)
- 선호도 및 제한 사항 (예산, 식이 제한/알레르기, 일정 강도, 포기할 의향이 있는 것)
- 개인정보 보호 요구사항 (공개 공유 여부, 비밀번호 게이트 필요 여부, 온라인에 올리면 안 되는 정보)
자료 수집: 스크린샷, PDF, 이메일, 대화 기록, 링크 모두 가능. JSON을 작성하기 전에 먼저 사실 목록으로 정리하고, 수집과 동시에 추측하지 마세요.
2단계: 심층 조사 (온라인, 「확인됨」과 「확인 필요」 구분)
우선순위에 따라 조사하고, 출처 링크와 확인 날짜를 기록하세요:
| 우선순위 | 조사 내용 |
|---|---|
| P0 | 비자/여권 유효 기간, 항공편/열차, 숙소, 회의 등록/티켓, 보험 |
| P1 | 공항 ↔ 시내 교통 (막차, 터미널), 시내 교통카드, 티켓 시간대 예약, 레스토랑 예약 |
| P2 | 관광지, 쇼핑, 대체 옵션, 날씨 |
- 공식 출처 우선: 항공사/공항/철도, 호텔, 회의 공식 웹사이트, 박물관/관광지 공식 사이트, 대사관, 교통 운영사.
- 각 중요 정보는 네 가지 표현으로 구분: 확인됨 / 확인 필요 / 미정 / 예시 (규칙은
references/content-guide.md§6 참조). - 가격, 운행 시간, 영업 시간, 예약 상태를 임의로 생성하지 마세요. 찾을 수 없으면 「확인 필요」라고 쓰고 「공식 확인 필수」라는 안전 장치를 제공하세요.
- 일반적인 함정 (공항 교통, 티켓 예약, Wi-Fi, 결제, 긴급 전화, 시간대/일광 절약 시간)을 항목별로 확인하고 핸드북 또는 이벤트 설명에 포함하세요.
3단계: trip.json 작성
references/trip-schema.md를 엄격히 따르세요. 예제 examples/tokyo-conference/trip.json을 직접 참조할 수 있습니다.
meta: 제목, 부제목, 상주 지역 (home), 시작 및 종료 날짜, 테마, 지도 공급업체, 바닥글 (데이터 마감 날짜 작성).destinations: 각 목적지마다id+ IANA 시간대 (예:Asia/Tokyo).days[].events: 각 이벤트에 최소time/title/short/detail/kind작성. 장소가 있으면location+map작성. 공식 링크가 있으면links작성. 체크리스트와 연결 가능하면checkId작성.checklists: 단계별로 그룹화 (출발 전 / 도착 후 / 여행 중 / 귀국 전),id는 전역적으로 고유.handbook: 교통, 네트워크, 결제, 안전/비상, 회의 참석, 식사, 짐 싸기 등 장 (병합/추가 가능, 주제 누락 금지).tickets: 각 인원당 하나,qr은 플레이스홀더 이미지 또는 사용자 제공 이미지 (실제 티켓 코드는 제출 금지).
이중 시간대 규칙 (가장 실수하기 쉬움)
time/endTime은 이벤트 현지 시간입니다.tz를 지정하지 않으면 당일 목적지의 시간대를 상속합니다.- 항공편이 시간대를 넘을 때
tz는 출발지 시간대를 나타내며,endTime도 해당tz기준으로 해석됩니다. 하나의 항공편으로 병합할 때endTime은 「도착 시간을 출발지 시간대로 변환한 값」이어야 하며,detail에 「도착 현지 시간 HH:MM」을 명확히 작성하세요. 더 간단한 방법은 출발과 도착을 두 개의 이벤트로 분할하고 각각 자체 현지 시간대를 사용하는 것입니다. - 익일 도착은 다음 날
days[]에 넣고detail에 「+1일」/「다음 날」이라고 작성하세요. 자정을 넘는 이벤트의endTime이time보다 작으면 다음 날로 처리되지만, 텍스트로 설명하는 것이 좋습니다. - 시간 지정이 없는 하루 종일 일정은
skipTimezone: true를 사용하세요. 시간대는 항상 IANA 이름으로 작성하고,UTC+9,JST등으로 쓰지 마세요. - 페이지는 자동으로 시간을 상주 지역 시간으로 변환하므로, 본문에서 직접 변환 값을 반복해서 작성하지 마세요. 단, 「체크인 오픈/원격 회의」와 같이 출발 전에 상주 지역 시간 기준으로 행동해야 하는 경우는 예외입니다.
4단계: 빌드
스킬 루트 디렉토리 (scripts/, templates/ 디렉토리를 포함하는)에서 실행하세요. 스크립트는 현재 작업 디렉토리를 기준으로 경로를 해석하며, 임의의 디렉토리에서 전체 경로로 실행할 수도 있습니다.
node scripts/build.mjs <trip.json> --out dist
주요 매개변수:
# 다중 파일 사이트 (개별 공유 가능한 ticket-<id>.html 생성)
node scripts/build.mjs trip.json --multi --out dist
# 테마 덮어쓰기 / 비밀번호 게이트 추가 / PWA 비활성화 / 비어 있지 않은 출력 디렉토리 덮어쓰기 / 조용한 모드
node scripts/build.mjs trip.json --theme night --gate-password "your-password" --out dist
node scripts/build.mjs trip.json --no-pwa --out dist
node scripts/build.mjs trip.json --force --quiet --out dist
- 기본 출력은
dist/index.html입니다.--out기본값은dist입니다. build는 내부에서 먼저 동일한 데이터 검증을 실행하며, 오류가 있으면 종료 코드 1을 반환하고 불완전한 산출물을 생성하지 않습니다. 경고는 출력되지만 빌드를 차단하지 않습니다.- 출력 디렉토리가 이미 존재하고 비어 있지 않으면
--force를 추가해야 합니다 (먼저 디렉토리를 비웁니다). --help로 모든 매개변수를 확인하세요.
5단계: 검증
node scripts/verify.mjs <trip.json> # 기본: errors 실패 (종료 코드 1), warnings만 표시
node scripts/verify.mjs <trip.json> --strict # warnings도 실패로 간주 (배포 전 권장)
node scripts/verify.mjs <trip.json> --quiet # 오류 요약만 출력
검증 범위: meta 필수 및 유효한 시간대/날짜, destinations 참조, days/events 시간 형식 및 tz 유효성, 링크 프로토콜, handbook HTML 허용 목록, tickets.qr 파일 존재 여부, 그리고 개인정보 스캔 (의심되는 전화번호/긴 숫자 코드에 경고). 경고는 수정하거나 설명할 수 있어야 합니다.
6단계: 미리보기 및 배포
- 로컬 미리보기: 브라우저에서 직접
dist/index.html열기 (단일 파일은 더블 클릭 가능). 다중 파일의 경우 로컬 서버를 시작하는 것이 좋습니다:npx serve dist # 또는 python -m http.server --directory dist - 배포:
references/deploy.md참조 (GitHub Pages / Cloudflare Pages / 모든 정적 호스팅). - 티켓 페이지 공유: 다중 파일 모드의
ticket-<id>.html을 해당 인원에게 개별적으로 보낼 수 있습니다. 단일 파일 모드에서는#ticket-<id>앵커를 사용하지만, 동일 페이지에 모든 사람의 내용이 포함됩니다. - 개인정보 주의: 공개 사이트 = 누구나 볼 수 있습니다. 실제 QR 코드, 티켓 코드, 신분증 번호, 전화번호는 공개 페이지에 넣지 마세요. 비밀번호 게이트는 프론트엔드 검증일 뿐입니다 (자세한 내용은
deploy.md참조).
호출 예시
예시 1: 도쿄 학술 회의 (예제 데이터와 동일)
사용자: 11월 20–24일에 도쿄에서 학술 회의가 있어요. 두 명(A/B)이고, 항공편과 호텔 스크린샷, 의제 링크입니다.
등록, 개막, 포스터, 만찬을 모두 일정에 넣고, 핸드폰에서 바로 볼 수 있는 페이지로 만들어 주세요.
Agent:
1. 자료 수집 → 3가지 질문: 호텔 예약에 조식 포함 여부, A/B 각각의 참가증 종류, 귀국 체크인 시간
2. 조사 → 하네다→시내 교통 수단과 막차, 회의장과 호텔 위치 관계, 도착 후 입국 소요 시간
3. trip.json 작성 → examples/tokyo-conference/trip.json 참조 (예제는 항공편을 하나로 병합, endTime을 출발지 시간대로 변환)
4. 빌드 → node scripts/build.mjs trips/tokyo-2026/trip.json --multi --out dist
5. 검증 → node scripts/verify.mjs trips/tokyo-2026/trip.json --strict
6. 미리보기 → dist/index.html 열기; GitHub Pages에 배포하거나 ticket-badge-a.html을 A에게 보내기 제안
예시 2: 가족 해외 여행 (다중 목적지 + 이중 시간대 + 보험 정보)
사용자: 여름방학에 부모님과 스페인 10일 여행, 마드리드 입국 바르셀로나 출국입니다. 일정을 만들어 주세요. 지하철과 긴급 전화번호를 확인할 수 있으면 좋겠어요.
Agent:
- destinations에 두 개 작성 (Madrid / Barcelona, 시간대 Europe/Madrid 및 출발지와 비교)
- handbook에 중점: 공항↔시내, 지하철 티켓, 결제 및 팁, 긴급 전화 및 대사관, 식사 (노인 식이 제한)
- 이벤트에 「이유」와 「포기 항목」 명시 (예: 「오늘은 레티로 공원 안 가고, 왕궁을 위해 체력 비축」)
- build 후 verify 실행, dist를 GitHub Pages에 배포하고 가족에게 링크 전송
예시 3: 기존 데이터 업데이트 + 특정인의 티켓 페이지만 공유
사용자: 일정이 변경되었습니다. 만찬이 23일에서 24일 19:30으로 변경되었고, 아내의 참가증 페이지만 따로 보내 주세요.
Agent:
1. trip.json에서 해당 이벤트의 time/detail 수정 (「확인됨」 표현과 출처 유지)
2. node scripts/build.mjs trip.json --multi --out dist --force
3. node scripts/verify.mjs trip.json
4. dist/ticket-badge-b.html을 개별 공유; 주의: 공개 링크는 QR 코드를 노출하므로 본인에게만 보내거나 접근 제어를 추가할 것을 권장
품질 기준
- 임의 생성 금지: 가격, 운행 시간, 영업 시간, 예약 상태, 전화번호는 출처가 있어야 합니다. 없으면 「확인 필요」 + 「공식 확인 필수」라고 작성하세요.
- 확인됨 vs 확인 필요: 사용자 확인서/공식 페이지 = 확인됨; 제3자 플랫폼/오래된 스크린샷/가이드 = 확인 필요. 고정 표현은
content-guide.md§6 참조, 「据说」「应该」 같은 표현 사용 금지. - 이중 시간대:
time은 이벤트 현지 시간으로 작성. 항공편 병합 시endTime은 이벤트tz(출발지 시간대) 기준으로 변환하고detail에 도착 현지 시간 작성. 날짜 변경은 다음 날로 분할. 시간대는 IANA 이름만 사용. - 개인정보 및 티켓 코드: 실제 QR 코드, 티켓 코드, PNR, 신분증 번호, 전화번호, 주소를 공개할 페이지에 작성 금지.
copy는 플레이스홀더 사용. 예제 데이터는 반드시 가상 및 비식별화. 저장소에는 플레이스홀더 QR 코드만 보관. - 기능 미약속: 실시간 재고/예약/체크인을 약속하지 않음. 주문, 결제, 변경/취소 등 되돌릴 수 없는 작업은 사용자에게 맡기고 대신 수행하지 않음.
- 인도 전 반드시 검증 실행:
verify.mjs --strict에서 오류 0으로 인도. 배포 전에 민감한 정보가 없는지 다시 확인. - 경계 설명: 비밀번호 게이트는 지인 공유 수준의 보호이며, 암호화가 아님. 진정한 보안이 필요하면 비공개 호스팅/접근 제어 사용.
단일 파일 vs 다중 파일 선택
| 요구사항 | 단일 파일 선택 (기본) | 다중 파일 선택 (--multi) |
|---|---|---|
| 가족/동료에게 전송, 위챗/이메일, 오프라인 더블 클릭 | ✅ HTML 하나가 가장 간편 | 권장하지 않음 (전체 디렉토리 필요) |
| 사이트로 배포, 장기 사용, 수시 업데이트 | 가능 (매번 파일 하나 재전송) | ✅ 캐시 친화적, 구조 명확 |
| 인원별로 티켓 페이지 개별 공유 | ❌ 앵커는 같은 페이지의 다른 사람 티켓 노출 | ✅ ticket-<id>.html 독립 페이지 |
| 완전히 하나의 파일 (QR 코드 포함) | tickets[].qr을 data: URI 또는 외부 링크 URL로 변경 | — |
| 비밀번호 게이트 필요 | ✅ 지원 (메인 페이지와 페이지 내 티켓 보기 모두 팝업) | ✅ 메인 페이지와 ticket-<id>.html 모두 비밀번호 상자 팝업 (동일 비밀번호, 동일 브라우저에서 한 번 잠금 해제) |
참고: 단일 파일 모드는
qr이 가리키는 로컬 이미지를 자동으로data:URI로 인라인하여 결과물이 진정한 하나의 HTML 파일이 됩니다. 이미data:/http(s)인 QR은 그대로 유지됩니다.
파일 맵
skills/trip-cheat-sheet/
├── SKILL.md # 본 파일: 사용 시기, 사용 방법, 기준
├── references/
│ ├── trip-schema.md # 유일한 데이터 계약 (필드/시간대/빌드 명령어)
│ ├── content-guide.md # 콘텐츠 작성 규칙 (6대 요소/이중 시간대/핸드북 장/표시 규칙)
│ └── deploy.md # 배포 및 공유 (Pages/Cloudflare/단일 다중 파일/비밀번호 게이트)
├── scripts/
│ ├── build.mjs # trip.json → 웹페이지
│ └── verify.mjs # trip.json 검증기 (build 내부에서 재사용)
├── templates/ # style.css / app.js / index.html / ticket.html
└── examples/tokyo-conference/ # 실행 가능 예제 (플레이스홀더 QR 코드 포함)
├── trip.json
└── assets/qr-a.svg, qr-b.svg
자주 묻는 질문
| 현상 | 처리 |
|---|---|
❌ 출력 디렉토리가 비어 있지 않음 | --force 추가 또는 --out 디렉토리 변경 |
| 페이지가 비어 있음/스타일 누락 | 다중 파일 모드는 전체 dist/ (assets/ 포함)를 함께 업로드해야 함. index.html과 assets/가 같은 레벨인지 확인 |
| 시간 표시가 잘못됨 | tz 철자 확인 (IANA 이름). 병합된 항공편의 endTime이 출발지 시간대로 변환되었는지 확인 |
verify에서 경고 발생 | 수정하거나 수용 가능함을 확인 후 인도. --strict는 실패 |
| 비밀번호 게이트 암호 분실 | 다시 빌드: node scripts/build.mjs trip.json --gate-password "새 비밀번호" |
| 배포 후 404 오류 | Pages 분기/디렉토리 설정, Actions 완료 여부, 파일명 대소문자 확인 |
| Node 버전 오류 | Node.js ≥ 18 사용 (완전한 Intl 시간대 데이터 및 ESM 필요) |
English quick reference
- What: generate a mobile-first travel cheat-sheet web page from one
trip.json— itinerary timeline, checklists, destination handbook, dual-timezone display, map deep links, QR ticket pages, optional password gate, PWA. - Build:
node scripts/build.mjs <trip.json> --out dist(single file, default) or--multi(static site withticket-<id>.html). Flags:--theme paper|slate|night,--gate-password,--no-pwa,--force,--quiet. - Verify:
node scripts/verify.mjs <trip.json> [--strict] [--quiet]. - Contract:
references/trip-schema.md; writing rules:references/content-guide.md; deployment:references/deploy.md. - Never: fabricate prices/schedules, mix up timezones, or commit real ticket codes, QR images, IDs or phone numbers. Mark verified vs unverified content explicitly.