# Skenario ekstensi Chrome manual {/* #manual-chrome-extension-scenarios */}

Perekaman manual berjalan sebagai tugas tangkapan Admin: **Desktop → Web Extension**. Lingkungan internalnya `WebExtension`; metadata tangkapan dan MCP publik memakai `web-extension`. Agen mengunduh ekstensi Chrome Web Store terpilih dan membuka profil Chromium sekali pakai dengan ekstensi itu serta ekstensi tangkapan Reconstruct. Operator menavigasi; Reconstruct menyimpan layar dan transisi teramati sebagai [`reconstruct.scene.v1`](/docs/id/data-format).

## Buat dan jalankan tugas {/* #create-and-run-a-job */}

1. Di Admin → Jobs → Create, pilih **Desktop → Web Extension**. Batalkan pilihan Web jika hanya menginginkan ekstensi. Lingkungan mobile tetap Web, iOS, dan Android.
2. Di Environment Settings → Web Extension, tempel tautan Chrome Web Store terpilih. Direktori ekstensi lokal dan profil browser pribadi bukan masukan.
3. Antrekan tugas. Capture Agent aktif dengan penugasan **Desktop / Web Extension** mengklaimnya. Worker Web dan Web Extension tidak dapat saling mengklaim tugas.
4. Agen mengunduh CRX3 bertanda tangan melalui layanan pembaruan Google dan memverifikasi ID ekstensi terpilih serta tanda tangan penerbit sebelum mengekstraknya ke direktori tugas privat. Paket mempertahankan ID toko saat dimuat tanpa dikemas. Metadata versi tangkapan mencakup `browserExtension` dengan ID terverifikasi, nama terlokalisasi, versi paket, dan SHA-256; nama tampilan katalog berasal dari paket itu. Jalur arsip, jumlah berkas, dan ukuran hasil ekstraksi diperiksa sebelum dipakai.
5. Chromium membuka tab onboarding milik ekstensi. Jika tidak, halaman opsi atau popup tindakan yang dideklarasikan dipakai. Ekstensi tanpa pintu masuk UI akan gagal.
6. Buka **Reconstruct Agent Browser Bridge** dari menu ekstensi browser. Popup menampilkan ID tugas aktif dan jumlah layar tersimpan. Setelah tiap layar, gunakan **Capture screen**. Gunakan **Pause**, **Resume**, dan **Finish recording** di sana.

Tidak ada CLI perekam mandiri atau MCP perekaman tambahan yang harus dijalankan. Kontrol terikat pada tugas aktif dan token sesi lokal privat. Kontrol tidak menerima nilai kolom, label sembarang, atau URL sumber. Admin juga dapat melihat dan mengontrol browser tugas melalui Admin → Jobs → job → **Live browser**; input di sana diterima hanya saat tugas menunggu operator. Ekstensi lain atau tugas lain ditolak. Jika ekstensi membuka tab lain, aktifkan sebelum menangkap; identitas diperiksa sebelum target dialihkan. Kata sandi, pembuatan dompet, persetujuan, dan pendaftaran tetap tindakan manual.

## Tugas login dan eksplorasi otomatis {/* #sign-in-jobs-and-automatic-exploration */}

Ekstensi yang memerlukan onboarding (misalnya pembuatan dompet MetaMask) dapat direkam semiotomatis. Di Environment Settings → Web Extension, tetapkan **Sign-in** ke **Operator registers** (atau **Operator signs in**).

1. Tugas menunggu operator. Selesaikan onboarding melalui Admin → Jobs → job → **Live browser**, atau dalam browser tugas sendiri. Simpan layar dengan **Capture screen**; layar kata sandi dan frasa pemulihan tidak pernah disimpan.
2. Pilih **Finish sign-in** (konsol), **Continue** (Admin), atau **Finish sign-in and explore** (popup Reconstruct).
3. Reconstruct lalu mengunjungi halaman popup, opsi, dan panel samping ekstensi serta rute tujuan kontrol navigasinya, menyimpan satu layar per rute. Tidak pernah mengeklik kontrol yang dapat mengirim, menandatangani, mengonfirmasi, mengungkapkan, mengekspor, mengunci, menghapus, atau membuat apa pun.
4. Jika ekstensi mengunci diri, tugas menunggu sebagai **Signed out** sampai operator membuka kunci dan memilih **Finish sign-in** lagi. Perekaman selesai dan diunggah untuk peninjauan ketika rute habis atau batas halaman tercapai.

Tugas Web memiliki pengaturan **Sign-in** yang sama: layar login disimpan sebagai tahap, perayapan melewati tautan keluar, dan berhenti sementara jika sesi berakhir. CAPTCHA, kode SMS, dan penerimaan ketentuan selalu menjadi tugas operator. Lihat `backend/docs/operator-sign-in.md` untuk detail.

## Penyiapan agen {/* #agent-setup */}

Bangun adaptor browser yang sesuai dengan `yarn nx run chrome:build` di `backend/agent-browser-extensions`. Host memerlukan Node.js 24+, Python 3, dan Chromium yang mendukung ekstensi. Konfigurasikan Capture Agent yang ada memakai pengaturan lokal yang diabaikan atau variabel lingkungan:

```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"
  }
}
```

Berikan kredensial `ApiTokens:Agent` yang ada melalui konfigurasi rahasia. Listener Kestrel Web yang ada harus loopback. Mulai biner Capture Agent dengan `extension serve`, lalu tugaskan catatan agen ke **Desktop / Web Extension** di Admin. Setiap mode host memiliki listener dan kunci kerjanya sendiri; jangan jalankan dua worker pada satu endpoint. Worker jarak jauh memerlukan host browser terisolasi terkelola dan deklarasi eksplisit `WebExtension:ManagedBrowserIsolated`, karena ekstensi menjalankan kode jaringan dan latar sendiri. Penanda ini tidak menciptakan isolasi. Pengaturan eksplisit `Agent:AllowHttpApi` yang ada berlaku untuk API pengembangan loopback.

Worker menangani klaim, heartbeat, pembatalan, dan percobaan ulang unggah. Proses anak Node internal memakai pipa proses privat tanpa port TCP debugging. Penyelesaian menutup browser tugas dan menghapus profil sementaranya. Gunakan dompet uji kosong: skenario tidak menyimpan kredensial atau dompet yang dapat dipakai.

## Rahasia dan peninjauan gambar {/* #secrets-and-image-review */}

Jeda sebelum memasukkan kata sandi, frasa pemulihan, kunci, atau kode. Lanjutkan setelah meninggalkan layar sensitif. Layar teks terlindungi ditolak demi keamanan dan menciptakan celah pengamatan. Kontrol yang dapat diedit dan turunannya dimasker sebelum screenshot; nilai kolom tidak dibaca ke Scene. Pemeriksaan sebelum/sesudah menolak tangkapan jika status perlindungan, masking, navigasi, atau konten dokumen berubah selama penangkapan.

Canvas dan piksel opak lain tetap terlihat dalam **media tinjauan privat**. Pemeriksaan DOM tidak membuktikan bahwa piksel itu bebas rahasia. Pemeriksaan dan masking berjalan sinkron dalam satu evaluasi isolated-world; JavaScript tetap aktif untuk screenshot agar konten canvas native dapat dirender.

**Finish recording** mengemas dan mengunggah hasil otomatis sebagai tangkapan belum terbit. Setiap checkpoint memiliki halaman, Scene, dan screenshot. Indeks skenario merujuk halaman tanpa menyalin teksnya. Di Admin, periksa tiap screenshot pada **Hide personal data**, buramkan area sensitif atau hapus media tidak aman, lalu terbitkan setelah peninjauan. Penyamaran juga menghapus teks Scene, nama aksesibilitas, nilai berulang, dan referensi media yang tercakup. Media asli yang disimpan terpisah perlu tinjauan sendiri. Kontrol perekaman tidak dapat menerbitkan atau mengembalikan gambar mentah.

## Rekonstruksi melalui MCP {/* #reconstruction-through-mcp */}

Setelah ditinjau dan diterbitkan, agen menemukan versi melalui katalog Capture MCP normal. Gunakan `get_scenario_scene` untuk memuat bingkai, profil, dan transisi yang dirakit dari data halaman terkini termasuk penyamaran Admin. Gunakan alat halaman terbitan normal untuk gambar yang disetujui. Verifikasi rekonstruksi terhadap setiap layar dan profil tangkapan yang diperlukan; keberhasilan alat saja tidak membuktikan kesetiaan visual.

## Bukti dan batas {/* #evidence-and-limits */}

Checkpoint adalah pengamatan statis. Tangkap setelah navigasi, menu, modal, dan pengungkapan lain, serta pada setiap viewport yang diperlukan. Pengamatan berdekatan mengukur hasil berubah/tidak berubah; tidak membuktikan klik dijalankan otomatis. Interval jeda dan pemblokiran menciptakan celah eksplisit. Mode ini tidak diam-diam menangkap tiap klik, mengulang pendaftaran, menangkap dialog izin OS native, atau menyimpulkan animasi dari gambar diam. Langkah rahasia tetap manual dan tidak ada dalam skenario publik. Batas halaman tugas membatasi checkpoint (pilihan otomatis default 200); batas simpul Scene adalah 100.000 per tugas. Batas waktu dan elemen tugas juga berlaku.

## Ketersediaan permintaan {/* #request-availability */}

Di **Admin → Requests → Job defaults → Request submissions**, konfigurasikan pasangan jenis produk/lingkungan yang diizinkan. Default adalah Desktop/Web, Desktop/Web Extension, dan Mobile/Web. **Allow new requests** menutup atau membuka kembali semua pengajuan baru; penyimpanan mempertahankan pasangan terpilih saat pengajuan ditutup. Permintaan yang ada dan tangkapan terbitan tetap tersedia. Kebijakan tersimpan yang sama berlaku pada API platform dan MCP terautentikasi, termasuk klien dengan opsi formulir usang. Endpoint request-options tidak mengembalikan platform saat pengajuan ditutup. Pemilih jenis produk/lingkungan katalog hanya menampilkan lingkungan yang ditangkap untuk produk itu; ketersediaan permintaan tidak menyembunyikan bukti katalog terbitan.