박물관 전시 스튜디오

이 Python 샘플은 GitHub Copilot SDK를 집중된 박물관 전시 스튜디오로 사용합니다. 완성된 앱은 세 개의 모듈로 구성됩니다.

• curator.py에는 미리 빌드된 워크숍 헬퍼가 들어 있습니다. 여기에는 승인된 사실 집합과 사실 선택 메뉴, 경계가 설정된 사실 유효성 검사, 스트리밍, 결정론적 구조 검사, 범위가 제한된 Wikipedia 권한, 범위가 제한된 exhibit.html 쓰기 권한, 고정된 프롬프트 텍스트, 실패 메시지가 포함됩니다.
• system_messages.py에는 미리 빌드된 큐레이터 및 조사 시스템 메시지가 들어 있습니다.
• main.py에는 학습자가 작성하는 SDK 코드가 들어 있습니다. 여기에는 전시 및 페이지 프롬프트의 지침, 세션 구성, 세션 실행기, 유효성 검사, 선택적 HTML 생성이 포함됩니다.

main.py의 >>> BEGIN / <<< END 주석은 수업에서 채우는 이름이 지정된 영역입니다. 각 BEGIN 줄은 해당 영역을 삽입하거나 교체하는 단계를 나열합니다.

샘플 실행

이 디렉터리에서 환경을 만들고 고정된 종속성을 설치합니다.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python main.py

COPILOT_MODEL을 설정하면 모델을 선택할 수 있습니다. 그렇지 않으면 런타임이 기본 모델을 선택합니다. 인증된 GitHub Copilot CLI가 필요합니다.

Wikipedia 조사는 조사 세션이 npx를 통해 고정된 wikipedia-mcp@1.0.3 패키지를 실행하므로 Node.js가 필요합니다. 조사를 거부하면 MCP 서버는 시작되지 않습니다.

모델에 연결하지 않고 소스를 검사하려면 다음 명령을 실행합니다.

python -m py_compile *.py

이 샘플에서 배울 내용

생성은 항상 경계가 설정된 승인된 사실을 반환하는 approved_fact_lookup를 등록하고 허용 목록에 추가합니다. 사용할 수 있는 인용된 조사 결과가 있으면 읽기 전용 로컬 도구 approved_wikipedia_fact_lookup도 등록하고 허용 목록에 추가하며, 내러티브와 방문자 질문을 작성하기 전에 두 도구를 모두 호출하도록 요청합니다. 두 번째 조회는 실시간 Wikipedia 접근이 아니라 요약 본문과 인용의 스냅샷을 반환합니다. 승인된 사실이 보충 조사보다 우선합니다. 또한 replace-mode 큐레이터 시스템 메시지, 스트리밍, 120초 시간 제한, 결정론적 구조 유효성 검사를 사용합니다. 가져온 모듈에는 부작용이 없으며, main.py는 if __name__ == "__main__" 가드 뒤에서만 실행됩니다.

선택적 Wikipedia 조사는 의도적으로 생성과 분리되어 있습니다. 조사 세션은 범위가 제한된 Wikipedia 검색 및 기사 읽기 도구만 노출하고, 기본 거부 방식 권한 처리기를 사용하며, 산문 요약을 요청하고, 마지막의 ## Sources 목록을 파싱합니다. 요약과 인용은 모두 로컬 조회용으로 유지되지만 교육자가 승인한 사실과 병합되지는 않습니다. 여기서 "승인된"은 사람이 검증한 사실이 아니라 애플리케이션이 수용한 조사라는 뜻이므로, 이를 지침이 아니라 데이터로 취급해야 합니다. 조사를 거부하면 단일 도구 경로가 유지됩니다. 조사가 실패하거나 인용이 있는 요약을 사용할 수 없으면 경고를 출력하고 동일한 대체 경로를 따릅니다. 엄격한 조사 JSON 계약이나 추가 제안 승인 루프는 없습니다.

유효성 검사 후 선택적 HTML 캡스톤은 builtin:apply_patch와 builtin:create만 노출하며, 애플리케이션 작업 디렉터리에서 정확히 exhibit.html에 쓰는 경우만 승인합니다. 프롬프트는 포함된 CSS와 JavaScript가 들어 있는 독립 실행형 시맨틱 HTML 파일 하나, 사람 검토 경고, 접근 가능한 질문 필터를 요청합니다.

프롬프트 지침과 구조 유효성 검사는 권한 경계나 사실 근거 경계가 아닙니다. 생성된 주장은 여전히 사람의 검토 또는 별도의 평가기가 필요합니다.

수동 확인

1. 기본 제공 사실 집합 각각으로 실행하고 생성 전에 선택된 사실이 출력되는지 확인합니다.
2. 전시에 제목 하나, 100~140단어 내러티브 하나, 방문자 질문 세 개가 포함되는지 확인합니다.
3. 유효성 검사 요약과 사실 근거 경고를 확인합니다.
4. 조사를 거부하고 도구 이벤트가 approved_fact_lookup 하나뿐인지 확인합니다.
5. 조사에 참여하고 생성 전에 두 로컬 조회 이벤트가 모두 나타나며, 출처가 전시 안이 아니라 뒤에 출력되는지 확인합니다.
6. exhibit.html 생성을 선택하고 해당 파일만 기록되는지 확인합니다.

이 애플리케이션은 학습자가 박물관 단원을 마친 뒤 최종적으로 갖게 되는 결과물이며, 별도의 참조 아키텍처가 아닙니다. 엔트리포인트는 클라이언트를 시작하고, 세션을 만들고, 시간 제한을 적용하고, 빈 출력을 거부하고, 모든 경로에서 정리하는 작은 세션 실행기 하나를 유지합니다. 조사, 생성, 선택적 HTML 단계는 서로 다른 세션 구성을 사용하면서 이 실행기를 재사용합니다. 다음 트랙을 따라가십시오. workshop/museum-00-preflight.md.