Autonomous Portfolio Assistant: Multi-LLM & RAG Agent

컨텍스트 인식 터미널 챗봇 및 MCP 통합

LIVE DEMO • [GITHUB: Private Source]

개요

• 역할: 풀스택 엔지니어링 (아키텍처, 백엔드 API, 상태 관리, UI/UX, 오디오 통합을 포함하여 전체 시스템을 처음부터 구축)
• 스택: React, Next.js, TypeScript, Tailwind CSS, Framer Motion, next-intl, MCP
• 핵심 결과: 사이버펑크 포트폴리오의 중앙 대화형 노드 역할을 하는 몰입형 컨텍스트 인식 V2 챗봇
• 요약: 포트폴리오: 사이버펑크를 위해 깊이 통합된 V2 챗봇 시스템으로, 원래의 V1 챗봇(포트폴리오: 글래스)에서 대대적으로 발전했습니다. 실시간 더빙, ToolBadge 표시기를 통한 동적 MCP 도구 실행, 시스템 명령, 활성 컨텍스트 한계 관리를 특징으로 하는 "Oz"라는 AI 터미널을 시뮬레이션합니다. 프란츠를 대표하는 완전한 자율 에이전트 역할을 합니다.

문제

• 과제: 사이버펑크 포트폴리오는 단순한 위젯이 아니라 내장형 터미널이나 AI 비서처럼 느껴지는 챗봇이 필요했습니다. 표준 대화형 인터페이스였던 V1 글래스 챗봇과 달리, 이 V2 반복 버전은 여러 시스템 수준의 명령을 처리하고, LLM 도구 호출(예: 탐색 또는 음악 재생)을 시각적으로 렌더링하며, 오디오 겹침 없이 동기화된 AI 더빙을 재생하고, 컨텍스트 창을 효율적으로 처리해야 했습니다.
• 대상: 포트폴리오를 탐색하는 기술 채용 담당자, 개발자 및 방문자.
• 제약 사항: 사운드 재생, UI 레이아웃 변경, 사용자 타이핑, 비동기 도구 호출 렌더링, API 제약(토큰 제한 처리)을 포함하는 복잡한 상태 관리를 60fps 애니메이션 손상 없이 신중한 아키텍처 계획을 통해 해결해야 했습니다.

접근 방식 및 결정

• 아키텍처: 구성 요소를 모듈식 기능으로 분리했습니다: ChatHeader, ChatInput, ChatMessage, ChatHistory, DubPopup, ToolBadge. 스팸을 피하고 소리를 안전하게 오케스트레이션하기 위해 useChatbotAudio를 활용했습니다.
• 주요 결정 사항:
  • 도구 실행 (ToolBadge): AI의 작업을 시각적이고 투명하게 만들기 위해 ToolBadge 구성 요소를 구축했습니다. AI가 MCP 도구(예: 음악 전환, 이력서 다운로드, 테마 변경, 사이트 번역)를 실행할 때 애니메이션 효과가 적용된 세련된 터미널 배지가 채팅 흐름에 표시되어 작업을 자세히 설명합니다. 이는 기본적으로 시스템 작업과 일반 텍스트를 분리합니다.
  • 아이덴티티 및 자율적 행동: AI는 전문 AI 비서 역할을 하는 "Oz"라는 페르소나로 작동합니다. 가격 문의(숨겨진 내부 가격표 표시) 및 문의 양식 라우팅(Oz가 사용자를 위해 이메일을 초안 작성하지만 엄격한 검토 및 승인 UI 루프를 거치도록 강제함)과 같은 복잡한 워크플로를 동적으로 처리합니다.
  • LLM 엔진 및 대체 아키텍처: 탄력적인 백엔드 대체 체인을 구축했습니다. 긴 컨텍스트 유지를 지원하기 위해 하이브리드 어텐션 아키텍처로 최대 100만 개의 컨텍스트 토큰을 기본적으로 처리합니다. 속도 제한이나 일시적인 중단이 발생할 경우 쿼리는 빠른 기본 모델에서 강력한 보조 네트워크로 유연하게 이어집니다.
  • RAG 및 컨텍스트 관리: 사용자가 깊은 기술적인 질문을 할 때 전체 MDX 사례 연구를 가져오기 위해 RAG(query_portfolio_data)를 활용합니다. 적응형 슬라이딩 창은 컨텍스트 용량의 90-98%에 도달하면 가장 오래된 메시지를 삭제합니다.
  • 모더레이션 잠금: Oz가 남용적인 언어나 스팸으로 인해 사용자를 일시적으로 차단(짧은, 중간 또는 긴 타임아웃)할 수 있는 자동화된 lockdown 시스템을 구현했으며 서버 측 쿠키와 완전히 동기화됩니다.
• 절충점: 복잡한 상태에 Redux를 사용하는 대신 지역화된 상태 관리를 위해 React Context 및 useSyncExternalStore에 의존했습니다. 이는 번들 크기를 최적화했지만 불필요한 재렌더링을 방지하기 위해 정확한 훅(hook) 설계가 필요했습니다.

핵심 결과 및 영향

• 결과: 진정한 유틸리티(예: 질문 답변, 음악 제어, 기술 쇼케이스)를 제공하면서 사이버펑크 내러티브를 강화하는 인상적이고 매우 기능적인 비서입니다.
• 영향: 고급 Next.js 패턴, MCP를 통한 시스템 통합, 맞춤형 훅 및 정확한 시청각 조정을 보여줍니다.

기술적 딥 다이브

• 주목할 만한 세부 사항:
  • 실시간 진단(왕복 시간, 활성 모델, 토큰)을 UI에서 직접 추적합니다.
  • 도구 호출 요소: ToolBadge.tsx 구성 요소는 AI가 단순한 텍스트가 아닌 action 객체를 반환할 때마다 트리거됩니다. 도구의 매개변수(예: { type: "toggle_theme", theme: "dark" })를 분석하고 채팅 피드 내에서 실행된 작업을 요약하는 미래 지향적인 빛나는 배지를 렌더링합니다.
  • 해커와 같은 타자기 효과로 마크다운을 안전하게 렌더링하기 위한 맞춤형 TypewriterMarkdown.
  • DubPopup 시각화 도구는 API 작업을 기반으로 "AI가 말하는 중" 상태를 비동기적으로 반영합니다.
• 검증: 남용적인 사용이나 속도 제한을 유연하게 처리하기 위한 강력한 제한(잠금 상태, 스팸 보호)을 구축하여 서버 구성을 UI에 직접 반영했습니다.
• 코드 품질: ToolDetail, ChatSession에 대한 TypeScript 인터페이스의 광범위한 사용 및 참조 및 시각적 레이아웃 상호작용에 대한 엄격한 null 검사.

회고

• 아쉬운 점: 모바일 장치에서 긴 오디오 파일을 디코딩할 때 주 스레드 끊김 현상을 완전히 제거하기 위해 오디오 플레이어 엔진을 일반 워커로 분리할 수도 있었습니다.
• 성공: useMusicPlayer 컨텍스트를 AI 명령과 원활하게 연결하여 비서가 채팅과 사이트 탐색 사이의 경계를 넘어 웹사이트 내에서 진정으로 "작동"할 수 있도록 했습니다.
• 교훈: "멋진" 사이버펑크 효과(타자기, 결함 있는 도구)와 접근성의 균형을 맞추려면 지속적인 테스트가 필요합니다. 고정된 위치 지정 및 스크롤 잠금 기능이 있는 모바일 친화적인 플로팅 채팅 창을 디자인하는 것은 브라우저의 특징에 크게 좌우됩니다.

나의 기여

• 시스템 아키텍처: 채팅 상태 엔진, 실시간 진단을 위한 폴링 논리 및 세션 스토리지 기록을 설계했습니다.
• 오디오 엔지니어링: 시퀀스 기반 더빙 및 음향 효과 훅(useChatbotAudio)을 프로그래밍했습니다.
• UI/UX: 진정한 터미널 모양을 위해 Tailwind 및 Framer Motion을 사용하여 구성 요소(ChatSettings, ChatInput)의 스타일을 지정했습니다.
• 통합: AI 출력을 광범위한 앱에 영향을 미치는 실행 가능한 도구(ToolBadge)에 매핑했습니다(예: 언어 변경, 이력서 다운로드, 테마 전환).

프로젝트 아키텍처

components/chatbot/ 디렉토리는 비서 논리를 오케스트레이션합니다:

• 코어 엔진: Chatbot.tsx는 주 컨트롤러 역할을 합니다.
• UI 구성 요소: ChatMessage.tsx, ChatInput.tsx, ChatHistory.tsx.
• 특수 기능: 시각적 효과를 위한 TypewriterMarkdown.tsx, 오디오 존재감을 위한 DubPopup.tsx, 도구 실행 요약을 위한 ToolBadge.tsx.
• 통합: 글로벌 프로바이더(useMusicPlayer, useTheme, useLocale)와 통합됩니다.

라이브 프리뷰

• 라이브 데모 링크: 라이브 포트폴리오 사이트 franzdomingo.dev에서 챗봇을 직접 체험해 보세요.
• 시도해 볼 기능: /help를 입력하여 명령어를 확인하거나 "Play music"을 요청하여 글로벌 뮤직 플레이어가 작동하는지 확인하세요.