📘 Gemini CLI DevTools

Gemini CLI DevTools는 Google Gemini API를 사용하는 애플리케이션의 실시간 디버깅, 로그 모니터링, 그리고 프롬프트 형상 관리를 위한 오버레이 위젯입니다.

📦 설치 및 사용 방법 (NPM Package)

설치

npm install xo-gemini-cli-devtools
# or
yarn add xo-gemini-cli-devtools

적용

React 프로젝트의 최상위 컴포넌트(예: App.tsx 또는 main.tsx)에 위젯을 추가하고 스타일을 import 하세요.

import React from 'react';
import { DevToolsWidget } from 'xo-gemini-cli-devtools';
import 'xo-gemini-cli-devtools/style.css'; // 스타일 import 필수

function App() {
  return (
    <div>
      {/* 기존 앱 내용 */}
      <MyApplicationContent />
      
      {/* DevTools 위젯 추가 */}
      <DevToolsWidget />
    </div>
  );
}

### 환경 설정 (Environment Configuration)

이 위젯은 기본적으로 **개발 환경(Development Environment)**에서만 렌더링되도록 설계되었습니다.
`process.env.NODE_ENV !== 'production'`일 때만 화면에 표시됩니다.

만약 프로덕션 환경(Staging 등)에서 강제로 활성화하고 싶다면 `enabled` 속성을 사용하세요.

```tsx
// 항상 활성화 (주의: 실제 서비스 사용자에게 노출될 수 있음)
<DevToolsWidget enabled={true} />

// 특정 조건에서만 활성화 (예: 관리자)
<DevToolsWidget enabled={isAdminUser} />

🛠 배포 스크립트

이 패키지는 NPM 배포를 위해 미리 설정되어 있습니다.

# 의존성 설치
npm install

# 라이브러리 빌드 (dist 폴더 생성)
npm run build

# NPM 배포 (로그인 필요)
npm publish

1. 시작하기

위젯 실행

애플리케이션이 실행되면 화면 우측 하단에 커맨드(Command) 아이콘 버튼이 나타납니다. 이 버튼을 클릭하여 DevTools 패널을 열거나 닫을 수 있습니다.

언어 설정 (Localization)

위젯 상단의 KO/EN 버튼을 클릭하여 한국어와 영어 모드를 실시간으로 전환할 수 있습니다.

API 키 설정

• 실제 동작 모드: .env 파일에 API_KEY가 설정되어 있으면 실제 Gemini API를 호출합니다.
• 시뮬레이션 모드: 키가 없으면 시뮬레이션 모드로 동작하며, 가상의 응답을 반환하여 UI/UX를 테스트할 수 있습니다. (상단에 🟡 노란색 열쇠 아이콘으로 표시됨)

2. 주요 기능

💬 채팅 및 커맨드 관리 (Chat & Command Library)

단순한 1회성 테스트를 넘어, 대화형 인터페이스와 자주 쓰는 프롬프트를 저장/관리하는 기능입니다.

1. 채팅 (Chat Interface)

   • 화면 하단의 입력창에 메시지를 입력하고 Enter 또는 전송(Send) 버튼을 누르면 Gemini와 대화할 수 있습니다.
   • 이전 대화 내역이 스크롤 가능한 형태로 유지됩니다.
   • 모델 선택: 상단 드롭다운 메뉴에서 gemini-2.5-flash, gemini-3-pro 등 모델을 변경하며 테스트할 수 있습니다.

2. 커맨드 저장 (형상 관리)

   • 입력창에 텍스트를 입력하면 입력창 우측 하단에 저장(💾) 아이콘이 나타납니다.
   • 아이콘을 클릭하고 **커맨드 이름(예: 코드 리뷰 템플릿)**을 입력한 뒤 + 버튼을 누르면 라이브러리에 저장됩니다.

3. 커맨드 불러오기 및 관리

   • 좌측의 책(📖) 아이콘 사이드바에 저장된 커맨드 목록이 표시됩니다.
   • 저장된 항목을 클릭하면 입력창에 해당 프롬프트가 즉시 반영됩니다.
   • 불필요한 커맨드는 항목 우측의 휴지통 아이콘을 눌러 삭제할 수 있습니다.

📟 콘솔 (Console)

애플리케이션과 Gemini API 간의 모든 로그를 실시간으로 확인합니다.

• 필터링: 상단의 검색바를 통해 로그 메시지를 검색하거나, INFO, ERROR 등의 레벨 버튼으로 필터링할 수 있습니다.
• 메타데이터 확인: 로그 항목을 클릭하면 전송된 프롬프트 내용, 토큰 수, 에러 상세 내용 등 숨겨진 JSON 데이터를 펼쳐볼 수 있습니다.
• 자동 스크롤: 새로운 로그가 들어오면 자동으로 최하단으로 스크롤됩니다.

📊 지표 (Metrics)

API 호출 성능과 비용 관련 데이터를 시각화합니다.

• Latency Chart: API 응답 속도(ms) 추이를 꺾은선 그래프로 확인합니다.
• Token Usage: 요청별 토큰 사용량을 막대그래프로 확인합니다.
• 요약 정보: 총 요청 수, 평균 지연 시간, 총 사용 토큰 수 등을 한눈에 볼 수 있습니다.

⚙️ 상태 (State)

CLI 및 위젯의 내부 상태(State)를 JSON 형태로 날것 그대로 확인합니다. 디버깅 시 현재 상태 값이 꼬였는지 확인할 때 유용합니다.

3. 단축키 및 팁

• 전송: 입력창에서 Enter
• 줄바꿈: 입력창에서 Shift + Enter
• 로그 비우기: 콘솔 탭 상단의 휴지통 아이콘
• 창 최소화: 위젯 상단의 - 아이콘 (작은 바로 축소되어 모니터링 방해를 최소화함)