브라우저에서 자연어로 XGEN AI 플랫폼을 제어하는 Chrome Extension.
| 문서 | 내용 |
|---|---|
| 문서 인덱스 | 전체 문서 안내 및 지원 범위 |
| 로드맵 | 현재 작업 순서, 품질 gate 및 완료 기준 |
| 개발 환경 | 로컬 설치, 빌드 및 Chrome 로딩 |
| 아키텍처 | 확장 컨텍스트와 API 캡처 흐름 |
| 메시지 프로토콜 | Side Panel, Service Worker, Content Script 계약 |
| 검증 가이드 | Playwright 자동화와 실제 환경 검증 계층 |
| GraphQL Introspection 가져오기 | schema JSON과 endpoint 기반 GraphQL tool 등록 |
| Postman 가져오기 | Collection v2.0/v2.1의 schema-only import |
| 수동 Tool Contract | endpoint와 schema로 단일 API 도구 등록 |
| XGEN 연동 | endpoint, 인증 및 Collection 등록 |
| 고객사 환경 | 내부망, VPN, CA, SSO 및 acceptance |
| 보안 | 권한, 민감정보 및 로그 정책 |
| 문제 해결 | 설치, 캡처 및 통합 오류 진단 |
AI가 여러 페이지를 연속으로 이동하며 작업을 수행합니다.
- "도구 관리 페이지 열어줘" → 사용자 관리 클릭 → 도구 관리 클릭 (자동 경로 탐색)
- 매 스텝마다 실제 DOM 상태를 AI에게 피드백하여 정확한 다음 액션 결정
- 최대 15스텝 연속 실행 가능
접힌 사이드바 메뉴를 자동으로 스캔하여 AI에게 전체 네비게이션 구조를 제공합니다.
[메뉴 구조]
워크플로우 > [워크플로우 소개, 워크플로우 캔버스, 워크플로우 관리, 실행도구, ...]
지식관리 > [지식컬렉션]
채팅하기 > [채팅 소개, 새 채팅, 현재 채팅, 기존 채팅 불러오기]
- XGEN CSS 모듈 패턴(
sidebarToggle/navItem) 자동 인식 aria-expanded기반 표준 메뉴도 지원nav > ul > li범용 패턴 폴백
기존 fire-and-forget 방식을 양방향 결과 피드백으로 교체했습니다.
Before: AI → "클릭 성공" (거짓) → AI 눈 감고 진행
After: AI → SSE page_command → 프론트엔드 실행 → DOM 재스캔 → POST /command-result → AI가 실제 결과 확인
PageCommandBridge: asyncio 기반 요청-응답 브릿지POST /api/ai-chat/command-result/{requestId}: 콜백 엔드포인트- AI가 실패를 감지하고 대안을 제시 가능
고정 300ms 대기 → MutationObserver 기반 DOM 안정화 감지로 교체.
- DOM 변경이 300ms간 없으면 안정 판단
- 최대 5초 타임아웃 (애니메이션 페이지 대응)
- SPA 네비게이션, AJAX 로딩 등에 자동 적응
viewportExpansion: 0 → 3으로 변경하여 화면 밖 요소도 AI가 인식합니다.
- 뷰포트 ±3배 범위의 DOM 요소 포함
- 스크롤 없이도 아래쪽 목록 항목 클릭 가능
LangGraph create_react_agent를 수동 ReAct 루프로 교체하여 전체 제어권 확보.
- LLM 스트리밍 → tool_calls 감지 → 도구별 분기 처리
- page_command: SSE emit → 프론트엔드 결과 대기 → ToolMessage에 새 DOM 포함
- canvas_command: fire-and-forget (기존 유지)
- gateway tools: 로컬 실행 + tool_start/tool_end SSE
- API 검색/호출: "워크플로우 목록 보여줘", "LLM 상태 확인"
- 캔버스 노드 관리: "RAG 노드 추가해줘", "두 노드 연결해줘"
- 문서 인덱싱: 컬렉션 생성, 파일 업로드, 인덱싱 실행
매 대화마다 LLM 토큰 사용량을 실시간 표시합니다.
- 입력 토큰 / 출력 토큰 / 합계
- 각 AI 응답 하단에 표시
- 멀티 인스턴스 지원: origin별 JWT 토큰 관리 (xgen.x2bee.com / jeju-xgen.x2bee.com 동시 사용)
- 컨텍스트 연속성: 대화 요약 자동 생성 + DOM 재스캔 + canvas state 캐싱
- 실시간 스트리밍: SSE 기반 LLM 응답 + 마크다운 렌더링
- 다크/라이트 모드: 시스템 설정 연동
- 브라우저 fetch/XHR 캡처와 개인정보 보호형 HAR import
- OpenAPI/Swagger URL 또는 JSON/YAML 파일 import
- GraphQL introspection JSON과 실행 endpoint import
- Postman Collection v2.0/v2.1 schema-only import
- endpoint, parameter, request/response JSON Schema 기반 수동 Tool Contract
- 모든 입력은 XGEN API Collection preview와 readiness 검사를 거쳐 등록
사이드패널 메뉴의 MCP 도구 연결에서 XGEN MCP Station의 실행 중인 세션을 기존 API Collection에 추가할 수 있습니다.
- 대상 API Collection을 선택합니다.
- 현재 사용자가 접근할 수 있는 실행 중 MCP 세션을 선택합니다.
미리보기로 도구 수, 이름 충돌, ingest 준비 상태를 확인합니다.등록 / 갱신으로 canonical MCP tool contract와 실행 binding을 저장합니다.
등록된 MCP 도구는 OpenAPI 도구와 같은 graph/search/PlanRunner 경로를
사용하지만, 실행은 XGEN MCP Station의 tools/call로 전달됩니다. 컬렉션은
사용자 ID 원문을 저장하지 않으며, 실행할 때 현재 XGEN 사용자와 역할 권한을
Station에서 다시 확인합니다.
┌─────────────────────────────────────────────────────────────┐
│ Chrome Browser │
│ │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ XGEN 웹 페이지 │ │ Extension Side Panel │ │
│ │ │ │ (React 채팅 UI) │ │
│ │ Content Script: │ │ │ │
│ │ - PageAgent │←→│ 토큰 사용량 표시 │ │
│ │ - GenericHandler │ │ 도구 호출 뱃지 │ │
│ │ - 메뉴 사전탐색 │ │ 마크다운 렌더링 │ │
│ └──────────┬──────────┘ └──────────────┬──────────────┘ │
│ │ │ │
│ ┌──────────┴──────────────────────────────┴──────────────┐ │
│ │ Background Service Worker │ │
│ │ - SSE 스트리밍 관리 │ │
│ │ - PAGE_COMMAND_RESULT → POST /command-result (결과 피드백)│
│ │ - 멀티 인스턴스 토큰 관리 │ │
│ └────────────────────────┬───────────────────────────────┘ │
└───────────────────────────┼──────────────────────────────────┘
│ HTTPS (SSE)
┌─────────────┴─────────────┐
│ xgen-workflow (백엔드) │
│ 수동 ReAct 루프 │
│ PageCommandBridge │
│ POST /command-result │
└───────────────────────────┘
1. 사용자 입력 → Side Panel
2. Background SW → Content Script에서 page_context + menuMap 수집
3. Background SW → POST /api/ai-chat/stream (SSE)
4. 백엔드 ReAct 루프:
┌─ LLM 호출 → tool_calls 감지
│ ├─ page_command → SSE emit → 프론트엔드 실행 → POST /command-result → 결과 대기
│ ├─ canvas_command → SSE emit (fire-and-forget)
│ └─ gateway tool → 로컬 실행 → tool_start/tool_end SSE
└─ tool_calls 없으면 → 최종 응답 + token_usage SSE → done
5. Side Panel: 토큰 스트리밍 + 도구 호출 표시 + 토큰 사용량
| 영역 | 기술 |
|---|---|
| Extension | Manifest V3, TypeScript, React, Vite, Tailwind CSS |
| DOM 조작 | @page-agent/page-controller (alibaba/page-agent) |
| 백엔드 | Python, FastAPI, LangChain, LangGraph |
| API 엔진 | graph-tool-call (OpenAPI → LLM 도구 자동 생성) |
| 통신 | SSE (서버→클라이언트), HTTP POST (결과 콜백) |
- Releases에서 zip 다운로드
- 압축 해제
- Chrome →
chrome://extensions→ 개발자 모드 → "압축해제된 확장 프로그램을 로드합니다" → 폴더 선택
git clone https://github.com/PlateerLab/xgen-chrome-extension.git
cd xgen-chrome-extension
npm ci
npx playwright install --with-deps chromium
npm run build
# chrome://extensions → 압축해제된 확장 프로그램 로드 → dist/개발 중 자동 빌드는 npm run dev를 사용한다. 자세한 절차는 개발 환경 문서를 참고한다.
npm run verify:pathfinder이 명령은 production build, trace contract 검증, 실제 Chromium extension runtime 검증을 순서대로 실행한다. mock runtime 통과는 실제 XGEN이나 고객사 내부망 통합 성공을 의미하지 않는다. 환경별 검증 기준은 검증 가이드에 정리되어 있다.
Extension 사이드 패널에서 설정:
- LLM Provider: Anthropic / OpenAI / Google / Bedrock / vLLM
- Model: claude-sonnet-4-20250514, gpt-4o, gemini-2.0-flash 등
인증 토큰은 XGEN 웹 페이지 로그인 시 자동 추출됩니다.
| 프로젝트 | 역할 |
|---|---|
| xgen-workflow | AI 챗봇 백엔드 (ReAct 루프, PageCommandBridge) |
| xgen-frontend | XGEN 웹 UI (canvas_command 핸들러) |
| graph-tool-call | API 검색/실행 엔진 |
MIT