AI Agent - Chrome Extension & Vue.js Portal Integration

Vue.js 포탈과 통합되는 React 기반 AI Agent Chrome Extension 예시 프로젝트입니다.

📁 프로젝트 구조

이 레포지토리는 두 개의 독립적인 프로젝트로 구성되어 있습니다:

react-addon/
├── chrome-extension/     # React 기반 Chrome Extension
│   ├── popup/           # Extension 팝업 UI
│   ├── content.js       # 콘텐츠 스크립트
│   ├── background.js    # 백그라운드 워커
│   └── manifest.json    # Extension 설정
│
└── vue-portal/          # Vue.js 포탈 예시
    ├── src/
    │   ├── views/       # 페이지 컴포넌트
    │   ├── stores/      # Pinia 상태 관리
    │   └── router/      # Vue Router
    └── index.html

🎯 프로젝트 개요

Chrome Extension

React 18 + Vite로 구축된 Chrome Extension으로, Vue.js 포탈과 통합되어 AI Agent 기능을 제공합니다.

주요 기능:

• 📱 React 기반 팝업 UI
• 🔗 Vue.js 포탈 자동 감지
• 💬 실시간 양방향 통신
• 📊 포탈 데이터 추출 (DOM, 사용자 정보, 네비게이션)
• 🤖 AI 쿼리 처리

Vue Portal

Vue 3 + Pinia + Vue Router로 구축된 예시 포탈로, Chrome Extension과의 통합을 테스트할 수 있습니다.

주요 기능:

• 🏠 홈, 대시보드, 프로필 페이지
• 📡 Extension과 실시간 통신
• 🧪 Extension 테스트 기능
• 📦 Pinia 상태 관리

🚀 빠른 시작

1. Chrome Extension 설정 및 설치

# Extension 폴더로 이동
cd chrome-extension

# 의존성 설치
npm install

# 빌드
npm run build

Chrome에서 Extension 설치:

1. chrome://extensions/ 접속
2. "개발자 모드" 활성화
3. "압축해제된 확장 프로그램을 로드합니다" 클릭
4. chrome-extension/dist/ 폴더 선택

2. Vue Portal 실행

# 포탈 폴더로 이동
cd vue-portal

# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

포탈이 http://localhost:3000에서 실행됩니다.

3. 통합 테스트

1. 브라우저에서 http://localhost:3000 접속
2. Chrome Extension 아이콘 클릭하여 팝업 열기
3. 연결 상태 확인: "포탈 연결됨" 표시 확인
4. 팝업에서 AI 쿼리 입력 및 전송
5. 브라우저 콘솔(F12)에서 메시지 로그 확인

📡 통신 아키텍처

┌─────────────────┐
│   Vue Portal    │
│ (localhost:3000)│
└────────┬────────┘
         │ postMessage
         ↕
┌────────┴────────┐
│ Content Script  │  ←─── Extension의 포탈 통합 레이어
└────────┬────────┘
         │ Chrome API
         ↕
┌────────┴────────────┐
│ Background Worker   │  ←─── AI 처리 및 메시지 중계
└────────┬────────────┘
         │ Chrome API
         ↕
┌────────┴────────┐
│  Popup (React)  │  ←─── 사용자 인터페이스
└─────────────────┘

📋 메시지 프로토콜

Extension → Portal

타입	설명	데이터
ADDON_READY	Extension 준비 완료	{ source: 'react-addon' }
AI_QUERY	AI 쿼리 전송	{ message, timestamp }
GET_DOM_DATA	DOM 데이터 요청	-

Portal → Extension

타입	설명	데이터
PORTAL_READY	포탈 준비 완료	{ appVersion, capabilities }
PORTAL_RESPONSE	AI 쿼리 응답	{ text, timestamp }
DOM_DATA	DOM 데이터 전송	{ url, title, userInfo, ... }

🛠️ 개발 가이드

Chrome Extension 개발

cd chrome-extension

# 개발 모드 (hot reload 없음, 수동 reload 필요)
npm run dev

# 프로덕션 빌드
npm run build

디버깅:

• 팝업: 팝업 우클릭 → 검사
• Content Script: 포탈 페이지에서 F12 → Console
• Background: chrome://extensions/ → "서비스 워커" 클릭

Vue Portal 개발

cd vue-portal

# 개발 서버 (hot reload 지원)
npm run dev

# 프로덕션 빌드
npm run build

디버깅:

• 브라우저 콘솔(F12)에서 Extension 메시지 로그 확인
• Vue Devtools 사용 권장

새로운 메시지 타입 추가

1. Extension에서 (chrome-extension/popup/App.jsx)

const sendNewMessageType = async () => {
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true })

  chrome.tabs.sendMessage(tab.id, {
    type: 'NEW_MESSAGE_TYPE',
    data: { ... }
  })
}

2. Portal에서 (vue-portal/src/main.js)

window.addEventListener('message', (event) => {
  if (event.data.source === 'react-addon') {
    switch (event.data.type) {
      case 'NEW_MESSAGE_TYPE':
        // 처리 로직
        break
    }
  }
})

📦 배포

Chrome Extension 배포

1. 빌드:

   cd chrome-extension
   npm run build

2. ZIP 파일 생성:

   cd dist
   zip -r ../extension.zip *

3. Chrome Web Store 업로드:

   • Chrome Web Store Developer Dashboard 접속
   • 새 항목 업로드
   • extension.zip 파일 선택

Vue Portal 배포

1. 빌드:

   cd vue-portal
   npm run build

2. 배포:

   • dist/ 폴더를 웹 서버에 배포
   • Netlify, Vercel, AWS S3 등 사용 가능

3. Extension manifest 업데이트:

   "content_scripts": [
     {
       "matches": ["https://your-actual-domain.com/*"],
       ...
     }
   ]

🔧 커스터마이징

AI 처리 로직 추가

chrome-extension/background.js 파일에서:

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'PROCESS_AI') {
    // 실제 AI API 호출
    const response = await fetch('https://your-ai-api.com', {
      method: 'POST',
      body: JSON.stringify(message.data)
    })

    const result = await response.json()

    chrome.runtime.sendMessage({
      type: 'PORTAL_RESPONSE',
      data: { text: result.answer }
    })
  }
})

포탈 URL 변경

chrome-extension/manifest.json에서:

"content_scripts": [
  {
    "matches": ["https://your-portal.com/*"],  // 실제 URL로 변경
    "js": ["content.js"]
  }
]

새로운 포탈 페이지 추가

cd vue-portal

# 1. 새 컴포넌트 생성
touch src/views/NewPage.vue

# 2. 라우터에 추가 (src/router/index.js)

🐛 문제 해결

Extension이 포탈을 감지하지 못함

• ✅ manifest.json의 matches URL 확인
• ✅ Extension이 활성화되어 있는지 확인
• ✅ 페이지 새로고침 (F5)
• ✅ Extension 재로드 (chrome://extensions/)

메시지가 전송/수신되지 않음

• ✅ 브라우저 콘솔에서 에러 확인
• ✅ event.data.source 값 확인
• ✅ Content Script가 로드되었는지 확인
• ✅ 메시지 리스너가 등록되었는지 확인

빌드 오류

• ✅ Node.js 버전 확인 (v16 이상 권장)
• ✅ node_modules 삭제 후 재설치
• ✅ 캐시 클리어: npm cache clean --force

📚 기술 스택

Chrome Extension

• ⚛️ React 18.2
• ⚡ Vite 5.0
• 🎨 CSS3
• 🔧 Chrome Extension Manifest V3

Vue Portal

• 💚 Vue 3.3
• 🍍 Pinia 2.1 (상태 관리)
• 🛣️ Vue Router 4.2
• ⚡ Vite 5.0

📖 참고 문서

• Chrome Extension 개발 가이드
• Vue Portal 개발 가이드
• Chrome Extension API 문서
• Vue.js 공식 문서
• React 공식 문서

🤝 기여하기

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 라이선스

MIT License

💡 사용 사례

이 프로젝트는 다음과 같은 시나리오에 활용할 수 있습니다:

• 🤖 웹 포탈에 AI 어시스턴트 추가
• 📊 포탈 데이터 분석 및 인사이트 제공
• 🔄 레거시 시스템에 현대적인 UI/UX 추가
• 🎯 사용자 행동 추적 및 개선 제안
• 📝 컨텍스트 기반 도움말 시스템

👥 연락처

문의사항이나 제안이 있으시면 Issue를 생성해주세요!

---

Made with ❤️ using React, Vue, and Chrome Extension API