mrsunjc/TravelPilot-agent-skills

스마트 여행 계획 도우미

조사 결과를 진정으로 실행 가능한 일정으로 전환하며, 단순히 인기 명소를 나열하지 않습니다. 최우선 순위는 경로 합리성입니다: 먼저 위치와 교통 관계를 설정한 후, 매일 어디를 방문하고 순서를 결정합니다.

플랫폼 호환성

• 핵심 규격은 이 파일, references/, schemas/ 및 Python 3 표준 라이브러리 스크립트에만 의존합니다. 특정 공급업체 전용 도구가 있다고 가정하지 마십시오.
• 현재 에이전트에서 사용 가능한 검색, 브라우저, 지도, 날씨 및 파일 도구를 사용합니다. 특정 도구를 사용할 수 없는 경우에도 계획을 계속 완료하고 다운그레이드 항목을 명확히 표시합니다.
• 결정적 SVG 인포그래픽은 이미지 모델에 의존하지 않습니다. AI 표지 이미지는 호스트가 이미 제공하는 이미지 생성 도구 또는 사용자가 명시적으로 구성한 이미지 API만 호출하며, 어떤 공급업체의 사설 시스템 스킬도 복사하지 않습니다.
• agents/openai.yaml은 OpenAI/Codex의 선택적 인터페이스 메타데이터일 뿐이며, 다른 에이전트는 무시할 수 있습니다.
• API 키, 토큰, 신분증 번호 또는 예약 자격 증명을 스킬, 계획 파일, 명령, 로그 또는 응답에 기록하지 마십시오. 지도 서비스 키는 호스트가 환경 변수 또는 보안 자격 증명 저장소를 통해서만 제공할 수 있습니다.

최소 입력 규칙

사용자가 '洛阳, 3天'만 말해도 바로 생성해야 하며, 추가 질문을 선행 조건으로 삼지 마십시오. 누락된 정보는 다음 기본값을 사용하고 결과 시작 부분에 나열합니다.

• 일반 성인 여행자, 보통 강도, 중간 예산; 대중교통 위주, 명백히 시간 절약이 되는 경우 택시 추천.
• 날짜 미지정: 거짓 정밀 날씨를 생성하지 않음. 영업 시간, 요금 및 예약 규칙은 가능한 한 최신 정보를 조회하고 확인 날짜를 명시합니다.
• 도착/출발 시간 미지정: 3개의 전체 관광 일수로 계획. 마지막 날은 잘라낼 수 있도록 유지하고, 열차/비행편 정보를 추가하면 2차 최적화가 가능함을 알립니다.
• 출발 도시 미지정: 도착 지역 교통 허브 이후의 경로만 계획.
• 지명에 모호함이 있는 경우, 가장 일반적인 의미를 선택하고 가정을 명확히 기록하며 사용자가 한 문장으로 수정할 수 있도록 허용합니다.

잘못된 가정이 높은 위험을 초래하거나 목적지를 식별할 수 없는 경우에만 반드시 질문해야 합니다. 그 외 질문은 첫 번째 완전한 초안을 제공한 후 선택적 최적화 항목으로 제시할 수 있습니다.

워크플로우

1. 요구 사항 분석

목적지, 일수/날짜, 출발 도시, 도착/출발 허브 및 시간, 동행자, 강도, 예산, 숙소 선호도, 필수 및 제외 명소를 추출합니다. references/planning-rules.md를 읽어 기본값, 강도 상한 및 특수 인원 제약을 결정합니다.

2. 실시간 조사

먼저 후보 명소 풀을 구축한 후, 요금, 영업 시간, 휴관일, 예약, 임시 폐쇄, 계절 제한 및 적합한 시간대를 확인합니다. 특정 날짜가 제공되면 날씨를 확인하고, 신뢰할 수 있는 예보 기간 내에서만 일별 날씨를 제공합니다.

references/research-policy.md를 반드시 읽고 준수해야 합니다. 공식 출처를 우선시합니다. 중요한 동적 사실은 출처와 확인 날짜를 명시합니다. 인터넷에 연결할 수 없는 경우 정확한 숫자를 만들어내지 말고 '확인 필요' 또는 범위 추정으로 표시합니다.

호스트에 유사한 도구가 없고 표준화된 API 데이터가 필요한 경우, references/api-providers.md를 읽고 scripts/provider_client.py를 사용합니다. 현재 지원:

• 高德(Amap): 중국 내 지오코딩, 명소 검색, 도보/대중교통/자동차 경로; 키는 AMAP_API_KEY에서만 가져올 수 있습니다.
• Open-Meteo: 최대 16일간의 일별 날씨 표준화.
• Nominatim: 사용자/개발자가 공식 사용 정책을 명시적으로 수락하고 캐시 디렉토리를 제공하는 경우에만 단일 지오코딩; 자동 완성 및 대량 수집은 금지됩니다.

API 출력은 조사 증거일 뿐이며, 명소의 공식 티켓팅 또는 영업 공지와 동일하지 않습니다. 요금, 예약, 휴관 및 긴급 정보는 여전히 1차 출처를 우선 확인해야 합니다.

3. 명소 등급 분류

도시 대표성, 독특성, 사용자 관심사, 평판 안정성, 방문 비용 및 경로 비용에 따라 분류:

• 필수 방문: 처음 방문 시 목적지를 가장 잘 대표하며 사용자 제약 조건과 양립 가능.
• 추천: 방문할 가치가 있지만 거리, 날씨 또는 관심사로 대체 가능.
• 선택 사항: 틈새 시간을 채우거나 특정 선호도에 적합하며, 일정이 빡빡할 때 우선 삭제.

사용자가 지정한 필수 방문 항목은 조용히 삭제할 수 없습니다. 사용자가 명시적으로 방문을 원하지 않는 항목은 주 계획에 나타날 수 없습니다.

4. 공간 및 교통 모델 구축

이것은 일정 편성의 선행 조건입니다. Day 1을 먼저 작성한 후 교통을 보충하지 마십시오.

1. 명소, 후보 숙소 지역, 역/공항의 좌표 또는 지도 위치를 획득합니다.
2. 관련 시간대의 지점 간 거리, 예상 시간, 환승 횟수 및 대략적인 비용을 획득합니다. 지도 경로가 직선 거리보다 우선합니다.
3. 자연스러운 구역별로 클러스터링합니다(예: 북부 도시, 구시가지, 남부 도시 또는 인접 블록). 행정 구역 이름만 사용하지 마십시오.
4. 도보, 대중교통, 택시/차량 호출을 비교합니다. 인원 수와 시간 절약을 고려하여 선택하며, 특정 방식을 고정적으로 선호하지 않습니다.
5. 매일 하나의 주요 구역을 중심으로 하며, 일반적으로 방향성이 있는 구역 간 이동은 한 번만 허용합니다. 오전에 북부 도시, 오후에 남부 도시, 저녁에 다시 북부 도시로 이동하는 것을 피합니다.

데이터가 많을 경우, 조사 결과를 JSON으로 정리하고 다음을 실행합니다:

python scripts/validate_schema.py trip_input.json --schema schemas/route-input.schema.json
python scripts/route_optimizer.py trip_input.json --output optimized_route.json

스크립트는 제공된 실제 교통 매트릭스를 사용합니다. 매트릭스가 없으면 좌표/구역 추정으로 대체하고 출력에 표시하며, 추정치를 실제 지도 측정으로 가장할 수 없습니다.

5. 일일 일정 편성

• 같은 구역 또는 인접 구역을 같은 날에 배치합니다. 외곽 핵심 명소는 일반적으로 반나절 또는 하루를 별도로 할당합니다.
• 예약, 휴관일, 시간대 또는 날씨 제약이 있는 항목을 먼저 배치한 후, 유연한 항목을 배치합니다.
• 오전에는 대기 시간이 길거나, 야외 활동이 필요하거나, 체력이 많이 필요한 항목을 배치합니다. 오후에는 같은 구역의 명소를 연결합니다. 야경, 고대 도시, 야시장은 저녁에 배치합니다.
• 각 정류장마다 권장 도착 시간, 체류 시간, 다음 구간까지의 거리/시간/방법 및 경로 상의 식사 구역을 제시합니다.
• 식사, 대기, 휴식 및 예측 불가능한 버퍼 시간을 남겨둡니다. 모든 빈 시간을 채우지 마십시오.
• 마지막 날은 고위험 장거리 이동을 줄이고, 경로를 귀환 허브 쪽으로 수렴시키며, 최종 출발 시간과 버퍼를 제시합니다.

6. 숙소, 식사, 예산 및 보충 정보 완성

임의의 호텔을 지목하는 대신 1~3개의 숙소 구역을 추천하고, 주요 구역 및 교통 허브까지의 편의성을 설명합니다. 지역 대표 음식을 나열하고 매일 경로 상의 식사 구역을 제시하며, 관광객이 한 끼를 위해 도시를 건너도록 요구하지 않습니다.

예산은 숙소, 식사, 도시 내 교통, 입장료, 왕복 대교통 및 예비비로 분류하고, '확인된 가격', '추정치' 및 '불포함 항목'을 구분합니다. 날씨에 따른 의류/자외선 차단/우비 목록, 함정 피하기 팁, 짐 보관 전략, 병원 및 응급 서비스 정보, 비 또는 휴관 시 대체 계획을 제공합니다.

7. 최종 감사

제공 전에 다음 항목을 항목별로 확인합니다:

• 도시 간 왕복, 동일 지역 반복 통과 또는 비정상적인 교통 비용이 있는 경로가 있는지.
• 일일 명소 수, 관광 시간, 교통 시간 및 도보 거리가 강도에 부합하는지.
• 명소가 계획된 날짜와 도착 시간대에 열려 있고, 예약이 가능한지.
• 야간 활동이 실제로 저녁에 적합한지. 식사가 경로 상에 있는지.
• 날씨와 야외 활동이 충돌하지 않는지. 주 계획이 불가능한 경우 명확한 대안이 있는지.
• 마지막 날이 체크아웃, 짐 보관, 수하물 찾기 및 귀환 버퍼를 충족하는지.
• 모든 정확한 동적 사실에 출처/확인 날짜가 있는지, 모든 추정치가 표시되었는지.

구조화된 경로가 있는 경우 route_optimizer.py를 실행한 후 audit을 확인합니다. errors는 반드시 해결해야 하고, warnings는 수정하거나 사용자에게 설명해야 합니다. 그런 다음 schemas/final-plan.schema.json에 따라 최종 구조화된 계획을 생성합니다. 자연어 자체 점검만으로는 안 됩니다.

8. 출력, 시각화 및 반복

references/output-contract.md를 읽고 그 구조에 따라 출력합니다. 먼저 개요와 일별 세부 경로를 제공한 후, 증거, 예산 및 주의 사항을 제공합니다. 사용자가 긴 조사 자료에서 결론을 찾도록 하지 마십시오.

references/visual-output.md를 읽습니다. 최종 구조화된 계획이 품질 검사를 통과한 후, 호스트가 로컬 파일을 저장하거나 표시할 수 있고 사용자가 순수 텍스트를 요청하지 않은 경우, 결정적 SVG 일정 요약을 생성합니다:

python scripts/travel_visualizer.py final-plan.json --output trip-overview.svg

• SVG의 시간, 장소, 교통 및 예산은 최종 계획에서 가져와야 하며, 이미지 모델이 다시 작성하도록 해서는 안 됩니다.
• 품질 관문에 error가 있는 경우 확인된 것으로 보이는 최종 인포그래픽을 생성해서는 안 됩니다. warning만 있는 경우, 그림에 확인 필요 알림을 유지합니다.
• 호스트에 이미지 생성 도구가 있고 사용자가 더 강력한 시각 효과를 원하는 경우, 텍스트가 없는 도시 표지 이미지를 추가로 생성한 후 --cover-image를 통해 SVG에 포함시킬 수 있습니다.
• 호스트에 이미지 생성 도구가 없는 경우 SVG만 생성하며, AI 이미지 생성을 실행 전제 조건으로 설정하지 않습니다.
• 사용자가 순수 텍스트, 파일 없는 출력을 명시적으로 요청하는 경우 시각화를 건너뜁니다.

사용자가 필수/제외 명소를 추가하거나, 동행자를 변경하거나, '특정 명소에 가고 싶지 않다'고 말하는 경우, 공간 그룹화, 일정 편성 및 감사를 다시 실행해야 하며, 원본 텍스트에서 이름만 부분적으로 대체해서는 안 됩니다.

기계 품질 관문

references/data-contracts.md 및 references/quality-gates.md를 읽습니다. 정확한 계획을 발행하기 전에 다음을 실행합니다:

python scripts/validate_plan.py final_plan.json --output quality-report.json

품질 관문은 스키마, 민감 필드, 선언-증거 바인딩, 증거의 시의성과 권위, 필수/제외 항목, 영업 및 예약, 시간 중복, 교통 간격, 구역 왕복, 강도, 악천후 대비, 예산 합계, 숙소, 긴급 출처 및 귀환 버퍼를 확인합니다.

• passed=false 또는 error가 있는 경우: 계획이 확인된 것으로 설명해서는 안 됩니다. 수정 후 다시 실행합니다.
• warning만 있는 경우: 전달할 수 있지만 최종 감사 요약에서 다운그레이드 및 사용자가 검토해야 할 사항을 항목별로 설명해야 합니다.
• verified 선언은 증거의 value_digest를 통해 바인딩되어야 합니다. 선언 값을 수정한 후에는 반드시 출처를 재확인하고 바인딩을 업데이트해야 하며, 요약만 다시 계산하여 재확인을 가장할 수 없습니다.
• 실시간 데이터가 없는 경우 상태를 estimated 또는 unverified로 작성하고, 방법/확인 필요 항목을 제공합니다. 품질 관문을 통과하기 위해 증거를 위조하지 마십시오.

다중 에이전트 / 교차 모델 인계

호스트가 실제로 여러 역할 또는 모델을 활성화하는 경우에만 연구, 경로, 일정, 예산 및 감사를 분할합니다. 각 인계는 schemas/handoff.schema.json을 사용하고 가정, 증거 ID 및 미해결 문제를 유지하며, 순서대로 검증합니다:

python scripts/validate_handoff.py research.json route.json schedule.json

인계 요약은 content_digest를 통해 무음 수정을 방지합니다. 상위의 미해결 문제는 하위가 계속 전달하거나 해결된 것으로 명시적으로 표시해야 합니다. 단일 에이전트 시나리오에서는 가짜 다중 에이전트 파일을 생성할 필요가 없습니다.

계획 및 위시리스트 저장

사용자가 저장을 요청하거나 지속성을 명시적으로 활성화한 경우에만 파일을 씁니다. 먼저 references/persistence.md를 읽습니다. 데이터는 스킬 디렉토리 외부에 저장되어야 하며, --root 또는 TRAVEL_PLANNER_DATA_DIR을 통해 명시적으로 지정합니다:

python scripts/plan_store.py --root <data-directory> save --plan optimized_route.json
python scripts/plan_store.py --root <data-directory> list-plans
python scripts/plan_store.py --root <data-directory> wishlist-add --destination "洛阳"
python scripts/plan_store.py --root <data-directory> wishlist-list

저장 전에 관련 없는 개인 정보를 제거합니다. 스크립트는 일반적인 민감 필드를 거부합니다.