Skip to content
BranchesTags

Repository files navigation

🌐 DeepDOM Agent (OmniBrowse AI)

Autonomous AI Browser Copilot Extension with Human-like DOM Navigation, Multi-Model Gemini Intelligence, and Voice Mic Dictation.

Manifest V3 Google Gemini DeepSeek Harness Shadcn Dark Voice Mic TypeScript Vitest

📖 Ringkasan Proyek

DeepDOM Agent adalah ekstensi browser Google Chrome (Manifest V3) revolusioner yang dirancang untuk mengemudikan peramban web secara otonom sesuai instruksi teks maupun dikte suara pengguna. Berbeda dengan automasi browser konvensional yang kaku dan mudah terdeteksi anti-bot, DeepDOM Agent menggabungkan kinematika kursor manusiawi (kurva Bézier & jitter natural), ritme ketikan keyboard Gaussian, Set-of-Marks visual indexing 2 arah, dan Multi-Model Gemini Fallback Cascade.

Ekstensi ini dibangun secara Serverless / Client-Side First — seluruh ReAct loop, sanitasi DOM, dan message broker berjalan langsung di dalam Chrome Service Worker dan SidePanel tanpa memerlukan server backend terpisah.

🌟 Fitur Unggulan

1. ⚡ Multi-Action Batching Chain (AI-Decided)

Agen dapat memutuskan secara mandiri apakah suatu rangkaian aksi dapat dieksekusi sekaligus dalam satu putaran (batching) tanpa perlu observasi ulang (misal: ketik Username ➔ ketik Password ➔ klik Login), memangkas waktu eksekusi task hingga 70%.

2. 🖐️ Humanized Interaction Kinematics

  • Natural Mouse Movement: Kursor bergerak menggunakan kurva Bézier kubik parametrik dengan interpolasi kecepatan manusiawi dan random perturbation.
  • Gaussian Typing Cadence: Pengetikan karakter dengan variasi jeda per karakter (bukan element.value = ... instan), memicu event keyboard standar (keydown, keypress, keyup, input).
  • Inertial Page Scrolling: Scroll halaman menggunakan dinamika easing halus untuk memuat lazy-load konten.

3. 🧠 Multi-Model Gemini Intelligence & Dynamic Cascade

Mendukung gemini-2.5-flash, gemini-2.0-flash, gemini-1.5-pro, dan model kustom dengan sistem automatic fallback cascade apabila terjadi limit kuota atau rate-limit. Dilengkapi fitur Crosscheck API untuk menguji latensi dan kesiapan model secara realtime.

4. 🎙️ Voice Mic Dictation (Zero-TTS Policy)

Interaksi suara cepat ala Google Voice Search berbasis Web Speech API dan visualizer gelombang audio reaktif (Web Audio API Analyser). Berpegang pada prinsip Zero-TTS — AI merespons secara visual lewat navigasi browser dan ringkasan teks terstruktur tanpa kebisingan suara sintesis.

5. 🤖 Dynamic Interactive Widgets (HITL) & Autonomy Modes

Ketika membutuhkan konfirmasi atau data sensitif, agen menampilkan widget interaktif langsung di chat:

  • 🔘 Choice Widget: Pilihan opsi radio adaptif dengan input kustom.
  • 📝 Form Widget: Input formulir kredensial/data terstruktur yang aman.
  • 🛡️ Confirm & Manual Takeover: Minta persetujuan aksi penting atau jeda saat pengguna ingin berinteraksi manual.
  • 3 Mode Keputusan (Autonomy Policy):
    • 🤖 Agent Decide: AI otomatis dan adaptif menentukan kapan butuh review.
    • ⚡ Always Proceed: Eksekusi mandiri tanpa henti (Full Autonomy).
    • 🛡️ Request Review: Selalu konfirmasi sebelum mengeksekusi aksi penting (Semi-Auto).

6. 📑 Multi-Tab Auto-Tracker & Tab Awareness

Ekstensi secara otomatis mendeteksi perpindahan fokus tab, pembukaan tab baru (target="_blank" atau popup window), dan langsung menginjeksi kontrol agen ke tab target tanpa kehilangan konteks tugas.

7. 🔌 Real-Time Backend Connection & Health Monitor

SidePanel dilengkapi status monitor koneksi realtime:

  • 🟢 Online: Service Worker aktif, Internet terhubung, dan Gemini API siap.
  • 🟡 Reconnect: Sedang memulihkan koneksi atau retry request API.
  • 🔴 Offline: Koneksi internet terputus (navigator.onLine === false).
  • ⚪ Disconnect: Service Worker mati atau Gemini API Key belum terpasang.
  • Termasuk tombol "Tes Ping & Reconnect" dengan pengukuran latensi milidetik (ms).

8. 🛡️ Two-Way DOM Filtering & Set-of-Marks Indexing

Sanitasi pohon DOM cerdas yang membuang elemen redundan (SVG tersembunyi, skrip, tag non-interaktif) menjadi ringkasan semantik kompak (< 1,500 token) dengan visual badge penomoran [1]..[N] pada halaman web.

🏛️ Arsitektur Sistem

flowchart TB
    subgraph Browser ["🌐 Google Chrome Browser"]
        SP["💻 SidePanel UI (Shadcn Dark)<br/>• Chat Stream & Thought Accordion<br/>• Voice Mic Waveform Visualizer<br/>• Execution Config Popover<br/>• Backend Status Monitor"]
        SW["⚙️ Background Service Worker<br/>• Master Message Broker<br/>• Multi-Tab Auto-Tracker<br/>• Tab Awareness Coordinator"]
        CS["📄 Content Script (Active Web Page)<br/>• Two-Way DOM Tree Pruner<br/>• Set-of-Marks Badge Overlay<br/>• Bézier & Gaussian Humanizer<br/>• In-Page Floating HUD"]
    end

    subgraph AI ["🧠 Google Gemini Cloud Engine"]
        API["⚡ generativelanguage.googleapis.com<br/>• Gemini 2.5 Flash / 2.0 Flash / 1.5 Pro<br/>• Multi-Action Batch Reasoning<br/>• Multimodal Screenshot Analysis"]
    end

    SP <-->|Chrome Runtime Message Bus| SW
    SW <-->|DOM Snapshots & Action Dispatch| CS
    SW <-->|JSON Prompts & Actions Payload| API
Loading

🚀 Panduan Memulai (Quickstart)

1. Prasyarat

  • Google Chrome (Versi 116 ke atas dengan dukungan Chrome SidePanel).
  • Node.js (Versi 18+ disarankan).
  • Google Gemini API Key (Dapatkan gratis di Google AI Studio).

2. Instalasi Dependensi

Clone repository dan pasang paket yang diperlukan:

git clone https://github.com/Fadhlijeu/DeepDOM-Agent.git
cd DeepDOM-Agent
npm install

3. Konfigurasi Lingkungan (.env)

Salin template konfigurasi dan masukkan API Key Gemini Anda:

cp .env.example .env

Isi file .env:

VITE_GEMINI_API_KEY=AIzaSyYourGeminiApiKeyHere

(Catatan: Anda juga dapat memasukkan atau mengganti API Key langsung dari menu Settings di SidePanel ekstensi).

🛠️ Menjalankan & Membangun Proyek

Mode Development (Auto-Watch Rebuild)

Untuk memantau perubahan file kode secara realtime:

npm run dev

Mode Production Build

Untuk mengompilasi bundel produksi ke direktori dist/:

npm run build

Menjalankan Unit Tests (Vitest)

npm test

🧩 Cara Memuat Ekstensi ke Google Chrome

  1. Buka browser Google Chrome dan navigasikan ke alamat: 
    chrome://extensions/
  2. Aktifkan sakelar "Developer mode" di pojok kanan atas.
  3. Klik tombol "Load unpacked" (Muat yang belum dibongkar) di pojok kiri atas.
  4. Pilih folder dist/ di direktori proyek ini: 
    D:\PROJECT\DeepDOM-Agent\dist
  5. Buka tab web apa pun (misal: https://www.google.com).
  6. Klik ikon puzzle ekstensi pada toolbar Chrome, lalu pilih DeepDOM Agent atau buka SidePanel.
  7. Buka menu Konfigurasi di atas input chat untuk memilih Model AI dan Mode Keputusan, lalu mulai beri instruksi!

📁 Struktur Direktori

DeepDOM-Agent/
├── public/
│   ├── manifest.json              # Chrome Extension Manifest V3
│   └── icons/                     # Logo & icon ekstensi (16, 48, 128)
├── src/
│   ├── agent/
│   │   ├── agent_loop.ts          # Master ReAct execution loop & lifecycle
│   │   ├── gemini_client.ts       # Gemini API client & prompt engineering
│   │   ├── model_manager.ts       # Multi-model CRUD & API cross-checking
│   │   ├── session_manager.ts     # Multi-session chat history storage
│   │   └── verifier.ts            # Action schema & parameter validation
│   ├── background/
│   │   └── service_worker.ts      # Extension broker & Multi-Tab tracker
│   ├── content/
│   │   ├── bezier.ts              # Kinematika kursor Bézier manusiawi
│   │   ├── captcha_detector.ts    # Deteksi anti-bot & CAPTCHA
│   │   ├── dom_indexer.ts         # Set-of-Marks visual badge indexing
│   │   ├── humanizer.ts           # Gaussian typing cadence & smooth scroll
│   │   ├── in_page_hud.ts         # Floating control bar di atas halaman
│   │   ├── tag_overlay.ts         # Visual marker renderer [1]..[N]
│   │   ├── tree_pruner.ts         # DOM filtering & token reduction (<1.5k tokens)
│   │   └── content.ts             # Content script bootstrap & message dispatcher
│   ├── sidepanel/
│   │   ├── index.html             # UI SidePanel (Shadcn Dark Mode)
│   │   ├── main.ts                # SidePanel UI controller & status monitor
│   │   └── style.css              # Tailwind CSS & custom design tokens
│   ├── types/
│   │   ├── agent.ts               # Action schemas, messages & session types
│   │   └── dom.ts                 # DOM snapshot & mutation types
│   └── voice/
│       └── voice_controller.ts    # Web Speech API & audio waveform analyser
├── tests/                         # Vitest unit test suite
├── workflows/                     # 12 Dokumen spesifikasi arsitektur mendalam
├── progress.md                    # Memori kerja progres sesi & milestone
├── package.json
├── tsconfig.json
├── tailwind.config.js
└── vite.config.ts

📚 Peta Dokumentasi Lengkap (workflows/)

Seluruh desain sistem dan spesifikasi teknis mendalam didokumentasikan di folder workflows/:

File Topik / Spesifikasi
00_overview.md Visi utama, nilai diferensiasi produk, dan prinsip dasar.
01_requirements.md Kebutuhan fungsional, non-fungsional, dan batasan teknis.
02_architecture.md Arsitektur Manifest V3, IPC message bus, dan state synchronization.
03_agent_pipeline_deepseek_harness.md Loop ReAct, schema aksi, validasi verifier, dan refleksi kesalahan.
04_dom_filtering_indexing.md Algoritma sanitasi DOM 2 arah & Set-of-Marks visual overlay.
05_humanized_execution_engine.md Kinematika Bézier, ritme Gaussian keyboard, dan inersial scroll.
06_ai_model_strategy_gemini.md Strategi multi-model, prompt engineering, dan cascading fallback.
07_voice_mic_subsystem.md Web Speech API dictation, visualizer gelombang, dan kebijakan Zero-TTS.
08_ui_ux_design_system.md Desain antarmuka SidePanel bergaya Shadcn Dark & floating HUD.
09_captcha_edge_cases.md Penanganan anti-bot, Cloudflare Turnstile, dan graceful human fallback.
10_milestones_roadmap.md Roadmap tahapan pengembangan Phase 0 hingga Phase 6.
11_open_questions_and_recommendations.md Catatan arsitektur masa depan dan rekomendasi optimasi.

⌨️ Shortcut & Tips Penggunaan

  • Enter: Mengirim instruksi tugas dari textarea.
  • Shift + Enter: Membuat baris baru di textarea tanpa langsung mengirim.
  • Alt + M (opsional): Trigger mikrofon untuk dikte suara instan.
  • Tombol Konfigurasi: Mengubah model AI atau mengganti mode otonomi (Agent Decide / Always Proceed / Request Review) dengan cepat.
  • Backend Status Pill: Klik status di header untuk melihat latensi ping realtime dan status Service Worker.

📄 Lisensi

Proyek ini dirilis di bawah lisensi MIT License. Bebas digunakan, dimodifikasi, dan dikembangkan untuk keperluan riset maupun komersial.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages