# 새 플랫폼 추가하기

새 채팅 웹사이트를 추가하는 작업은 두 개의 층으로 나뉩니다.

1. **사이트 어댑터** `catalog/sites/<site>/site.json`: Voyager에게 웹사이트를 인식하는 방법과 사용자 턴, 어시스턴트 턴, 입력창, 사이드바, 테마 표식을 찾는 방법을 알려 줍니다.
2. **플러그인** `catalog/sites/<site>/plugins/<id>/`: 그 웹사이트에서 사용자가 겪는 문제 하나를 해결합니다. 읽기 너비나 렌더링 수정 같은 것입니다.

`site.json`에는 `id`(디렉터리 이름과 같아야 합니다), `label`, `matches`, `selectors`, `theme`, `brandColor`, `capabilities`가 들어가며, 선택 항목으로 `conversationIdPattern`과 `turnKeyAttributes`를 둘 수 있습니다. `turnKeyAttributes`는 페이지가 사용자 메시지를 다시 렌더링할 때도 그 메시지의 정체성을 유지하는 속성 이름입니다. 메시지 전송 추적(폴더 Activity와 타임라인 타임스탬프에서 사용)은 이 속성이 설정된 사이트에서만, 그리고 `composer`, `userTurn`, `conversationIdPattern`과 함께 실행됩니다. `src/features/plugins/sites/siteAdapterData.ts`의 `validateSiteAdapterData`가 이를 검증하며, `bun run catalog:build`는 게시 전에 모든 사이트와 플러그인을 검증합니다.

`site.json`은 사이트 어댑터 자체를 데이터로 적은 것입니다. 현재 플러그인 플랫폼은 ChatGPT, Claude, DeepSeek, Kimi입니다. Gemini와 AI Studio는 Voyager의 네이티브 화면이며 각자 `site.json`(`catalog/sites/gemini/`, `catalog/sites/aistudio/`)을 갖지만, 이 파일은 확장 프로그램에 포함되어 배포될 뿐 원격 카탈로그에는 게시되지 않습니다. `sites/adapters/gemini.ts`, `aistudio.ts`, `claude.ts`, `chatgpt.ts`, `deepseek.ts`는 모두 `site.json`을 감싼 한 줄짜리 껍데기입니다. TypeScript가 아니라 JSON을 수정하세요. 게시되는 호스트별 카탈로그가 사이트 데이터도 함께 싣기 때문에, 선택자 수정은 확장 프로그램을 새로 배포하지 않아도 사용자에게 전달됩니다. 다만 완전히 새로운 사이트는 여전히 확장 프로그램 배포가 필요합니다. 호스트 권한과 콘텐츠 스크립트 등록도 패키지에 포함되어 배포되어야 하기 때문입니다.

DeepSeek 같은 새 플랫폼을 추가할 때는 어댑터 작업을 플랫폼 계약에 집중하세요. `site.json`, 필요한 선택자 테스트, 지원 내용을 설명하는 최소한의 문서를 하나의 완결된 변경으로 묶으세요. 사이트 레지스트리는 파일 자체에서 새 어댑터를 찾으므로 등록 목록을 수정할 필요가 없습니다. 플러그인마다 새 사이트를 추가하지는 마세요.

어댑터가 승인된 뒤에는 후속 플러그인을 별도의 집중된 변경으로 제출할 수 있습니다. 여러 변경이 서로 의존한다면 스택 PR 체인이 유용합니다. 각 후속 브랜치는 이전 브랜치를 기반으로 하고, 각 PR은 자신의 점진적 기능만 보여 줍니다. 이 체인도 같은 범위 원칙을 따라야 합니다. PR마다 명확한 사용자 목표 하나와 필요한 테스트 및 정리 작업을 담으세요.

사이트 지원에는 모델 API 연동이 필요하지 않습니다. 새 플랫폼을 위해 정적 콘텐츠 스크립트나 필수 호스트 권한을 추가하지 마세요. 플러그인만 제공하는 사이트는 기존의 선택적 권한과 동적 등록 흐름을 사용하면 됩니다.

선택적 권한과 동적 등록 경로는 브라우저 버전에 따라 다릅니다. Chrome과 Edge는 확장 프로그램이 사용하는 흐름을 지원합니다. Firefox는 선택적 호스트 권한에 128 이상이 필요하고, Safari는 동적 콘텐츠 스크립트 등록에 16.4 이상이 필요합니다. 더 오래된 지원 브라우저에서는 필요한 API가 지속적인 허용을 제공할 수 없으므로, 팝업이 사용자 지정 사이트의 플러그인 활성화를 올바르게 거부할 수 있습니다. 이를 피하려고 관리자 승인 없이 넓은 정적 호스트 권한을 추가하지 마세요.