# 수동 Chrome 확장 프로그램 시나리오 {/* #manual-chrome-extension-scenarios */}

수동 기록은 **Desktop → Web Extension** Admin 캡처 작업으로 실행됩니다. 내부 환경은 `WebExtension`, 캡처 메타데이터와 공개 MCP는 `web-extension`을 사용합니다. 에이전트는 선택된 Chrome 웹 스토어 확장을 다운로드하고 해당 확장과 Reconstruct 캡처 확장을 넣은 일회용 Chromium 프로필을 엽니다. 운영자가 탐색하며 Reconstruct는 화면과 관찰된 전환을 [`reconstruct.scene.v1`](/docs/ko/data-format)으로 저장합니다.

## 작업 생성 및 실행 {/* #create-and-run-a-job */}

1. Admin → Jobs → Create에서 **Desktop → Web Extension**을 선택하세요. 확장만 필요하면 Web을 해제하세요. 모바일 환경은 Web, iOS 및 Android로 유지됩니다.
2. Environment Settings → Web Extension에 선택한 Chrome 웹 스토어 링크를 붙여넣으세요. 로컬 확장 디렉터리와 개인 브라우저 프로필은 입력이 아닙니다.
3. 작업을 큐에 넣으세요. **Desktop / Web Extension**이 할당된 활성 Capture Agent가 가져갑니다. Web과 Web Extension 워커는 서로의 작업을 가져갈 수 없습니다.
4. 에이전트는 Google 업데이트 서비스에서 서명된 CRX3를 다운로드하고 선택된 확장 ID와 게시자 서명을 검증한 후 비공개 작업 디렉터리에 풉니다. 압축 해제 상태로 로드해도 패키지의 스토어 ID는 유지됩니다. 캡처 버전 메타데이터의 `browserExtension`에는 검증된 ID, 현지화 이름, 패키지 버전 및 SHA-256이 있으며 카탈로그 표시 이름은 해당 패키지에서 가져옵니다. 사용 전에 아카이브 경로, 파일 수 및 압축 해제 크기를 검사합니다.
5. Chromium은 확장의 온보딩 탭을 엽니다. 없다면 선언된 옵션 페이지나 액션 팝업을 사용합니다. UI 진입점이 없는 확장은 실패합니다.
6. 브라우저 확장 메뉴에서 **Reconstruct Agent Browser Bridge**를 여세요. 팝업에 활성 작업 ID와 저장된 화면 수가 표시됩니다. 각 화면 후 **Capture screen**을 사용하세요. **Pause**, **Resume**, **Finish recording**도 여기에서 사용하세요.

별도 레코더 CLI나 추가 기록 MCP를 실행할 필요가 없습니다. 제어는 활성 작업과 비공개 로컬 세션 토큰에 연결됩니다. 필드 값, 임의 레이블 또는 소스 URL은 받지 않습니다. 관리자는 Admin → Jobs → job → **Live browser**에서도 작업 브라우저를 보고 제어할 수 있으며 입력은 작업이 운영자를 기다릴 때만 허용됩니다. 다른 확장이나 다른 작업은 거부됩니다. 확장이 다른 탭을 열었다면 캡처 전에 활성화하세요. 대상 전환 전에 신원을 확인합니다. 비밀번호, 지갑 생성, 동의 및 등록은 수동 작업으로 남습니다.

## 로그인 작업 및 자동 탐색 {/* #sign-in-jobs-and-automatic-exploration */}

MetaMask 지갑 생성처럼 온보딩이 필요한 확장은 반자동으로 기록할 수 있습니다. Environment Settings → Web Extension에서 **Sign-in**을 **Operator registers** 또는 **Operator signs in**으로 설정하세요.

1. 작업은 운영자를 기다립니다. Admin → Jobs → job → **Live browser** 또는 작업 브라우저에서 온보딩을 완료하세요. **Capture screen**으로 화면을 저장하세요. 비밀번호와 복구 문구 화면은 절대 저장되지 않습니다.
2. **Finish sign-in**(콘솔), **Continue**(Admin) 또는 **Finish sign-in and explore**(Reconstruct 팝업)를 선택하세요.
3. 그다음 Reconstruct가 확장의 팝업, 옵션, 사이드 패널 페이지 및 탐색 컨트롤이 연결하는 경로를 방문하며 경로마다 화면 하나를 저장합니다. 전송, 서명, 확인, 공개, 내보내기, 잠금, 삭제 또는 어떤 생성이라도 수행할 수 있는 컨트롤은 클릭하지 않습니다.
4. 확장이 잠기면 운영자가 잠금을 해제하고 **Finish sign-in**을 다시 선택할 때까지 **Signed out** 상태로 기다립니다. 남은 경로가 없거나 페이지 한도에 도달하면 기록을 마치고 검토용으로 업로드합니다.

웹 작업에도 같은 **Sign-in** 설정이 있습니다. 로그인 화면은 단계로 저장되고 크롤러는 로그아웃 링크를 피하며 세션이 끝나면 일시 중지됩니다. CAPTCHA, SMS 코드 및 약관 동의는 항상 운영자가 처리합니다. 자세한 내용은 `backend/docs/operator-sign-in.md`를 참고하세요.

## 에이전트 설정 {/* #agent-setup */}

`backend/agent-browser-extensions`에서 `yarn nx run chrome:build`로 일치하는 브라우저 어댑터를 빌드하세요. 호스트에는 Node.js 24+, Python 3 및 확장을 지원하는 Chromium 빌드가 필요합니다. 무시되는 로컬 설정이나 환경 변수로 기존 Capture Agent를 설정하세요:

```json
{
  "Agent": {
    "Id": "extension-worker",
    "ApiUrl": "https://internal-admin-api.example",
    "ChromiumPath": "/Applications/Chromium.app/Contents/MacOS/Chromium",
    "ExtensionDir": "/checkout/backend/agent-browser-extensions/chrome"
  },
  "WebExtension": {
    "RecorderDirectory": "/checkout/backend/tools/manual-recorder",
    "NodePath": "node",
    "PythonPath": "python3"
  }
}
```

기존 `ApiTokens:Agent` 자격 증명은 비밀 설정으로 제공하세요. 기존 Kestrel Web 리스너는 루프백이어야 합니다. Capture Agent 바이너리를 `extension serve`로 실행하고 Admin에서 에이전트 레코드를 **Desktop / Web Extension**에 할당하세요. 각 호스트 모드는 자체 리스너와 작업 잠금을 소유하므로 한 엔드포인트에 워커 둘을 시작하지 마세요. 원격 워커에는 관리되는 격리 브라우저 호스트와 명시적 `WebExtension:ManagedBrowserIsolated` 선언이 필요합니다. 확장은 자체 네트워크 및 백그라운드 코드를 실행하기 때문입니다. 이 플래그 자체가 격리를 만들지는 않습니다. 기존의 명시적 `Agent:AllowHttpApi` 설정은 루프백 개발 API에 적용됩니다.

워커는 할당, 하트비트, 취소 및 업로드 재시도를 관리합니다. 내부 Node 자식 프로세스는 비공개 프로세스 파이프를 사용하고 디버깅 TCP 포트는 사용하지 않습니다. 종료 시 해당 작업의 브라우저를 닫고 임시 프로필을 삭제합니다. 빈 테스트 지갑을 사용하세요. 시나리오는 자격 증명이나 사용 가능한 지갑을 보존하지 않습니다.

## 비밀 정보 및 이미지 검토 {/* #secrets-and-image-review */}

비밀번호, 복구 문구, 키 또는 코드를 입력하기 전에 일시 중지하세요. 민감한 화면을 떠난 후 재개하세요. 보호된 텍스트 화면은 안전하게 차단되며 관찰 공백이 생성됩니다. 스크린샷 전에 편집 가능한 컨트롤과 자식을 마스킹하며 필드 값은 Scene으로 읽지 않습니다. 캡처 중 보호 상태, 마스킹, 탐색 또는 문서 콘텐츠가 바뀌면 사전/사후 검사에서 캡처를 거부합니다.

Canvas와 다른 불투명 픽셀은 **비공개 검토 미디어**에 그대로 보입니다. DOM 검사로 비밀이 없음을 입증할 수는 없습니다. 검사와 마스킹은 한 번의 격리된 월드 평가에서 동기 실행됩니다. 네이티브 canvas 콘텐츠가 렌더링되도록 스크린샷 시 JavaScript는 활성 상태입니다.

**Finish recording**은 결과를 자동 패키징하고 미공개 캡처로 업로드합니다. 체크포인트마다 페이지, Scene 및 스크린샷을 소유합니다. 시나리오 인덱스는 텍스트를 복사하지 않고 페이지를 참조합니다. Admin의 **Hide personal data**에서 모든 스크린샷을 검토하고 민감한 부분을 흐리게 하거나 안전하지 않은 미디어를 삭제한 후 공개하세요. 가림 처리는 덮인 Scene 텍스트, 접근성 이름, 반복 값 및 미디어 참조도 지웁니다. 별도 저장된 원본 미디어는 따로 검토해야 합니다. 기록 컨트롤은 공개하거나 원본 이미지를 반환할 수 없습니다.

## MCP를 통한 재구현 {/* #reconstruction-through-mcp */}

검토 및 공개 후 에이전트는 일반 Capture MCP 카탈로그로 버전을 찾습니다. `get_scenario_scene`으로 Admin 가림 처리를 포함한 현재 페이지 소유 데이터에서 조합된 프레임, 프로필 및 전환을 로드하세요. 승인된 이미지에는 일반 공개 페이지 도구를 사용하세요. 필요한 모든 캡처 화면과 프로필에 대해 재구현을 검증하세요. 도구 호출 성공만으로 시각적 충실도가 입증되지는 않습니다.

## 증거 및 한계 {/* #evidence-and-limits */}

체크포인트는 정적 관찰입니다. 탐색, 메뉴, 모달 등 콘텐츠를 연 후 및 필요한 각 뷰포트에서 캡처하세요. 인접 관찰은 변경/미변경 결과를 측정하며 클릭이 자동 실행되었음을 입증하지 않습니다. 일시 중지되거나 차단된 구간은 명시적 공백입니다. 이 모드는 모든 클릭을 몰래 캡처하거나 등록을 재생하거나 OS 권한 대화상자를 캡처하거나 정지 이미지에서 애니메이션을 추론하지 않습니다. 비밀 단계는 수동이며 공개 시나리오에서 제외됩니다. 체크포인트는 작업 페이지 한도(자동 선택 기본값 200)의 제한을 받으며 Scene 노드 한도는 작업당 100,000개입니다. 작업 시간과 요소 한도도 적용됩니다.

## 요청 가용성 {/* #request-availability */}

**Admin → Requests → Job defaults → Request submissions**에서 허용 제품 형식/환경 쌍을 설정하세요. 기본값은 Desktop/Web, Desktop/Web Extension 및 Mobile/Web입니다. **Allow new requests**로 모든 새 제출을 닫거나 열 수 있으며 닫힌 상태에서 저장해도 선택된 쌍은 보존됩니다. 기존 요청과 공개 캡처는 계속 이용할 수 있습니다. 같은 저장 정책이 오래된 양식 옵션을 쓰는 클라이언트까지 플랫폼 API와 인증 MCP에 적용됩니다. 제출이 닫혀 있으면 request-options 엔드포인트는 플랫폼을 반환하지 않습니다. 카탈로그 제품 형식/환경 선택기는 해당 제품에 캡처된 환경만 보여주며 요청 가용성이 공개 카탈로그 증거를 숨기지는 않습니다.