d3ro-voice/docs/phases/phase-6.md

Phase 6: 커스텀 명령어 + 설정 UI 고도화

목표

사용자 정의 LLM 명령어 시스템을 완전 구현하고, 설정 UI를 고도화하여 STT/LLM/TTS 모델 선택, 온보딩, 다국어(i18n)를 지원한다.

태스크

6.1 CustomInstructionService 완전 구현

• src/main/services/CustomInstructionService.ts
• electron-store에 명령어 목록 저장 (DB 아닌 설정 파일)
• CustomInstruction 타입:

  interface CustomInstruction {
    id: string;               // nanoid
    name: string;             // 표시 이름 (예: "번역 (한→영)")
    description: string;      // 설명
    prompt: string;           // 시스템 프롬프트 템플릿
    icon: string;             // MUI 아이콘 이름 또는 이모지
    isBuiltin: boolean;       // 프리셋 여부 (삭제 불가)
    hotkeyId: string | null;  // 바인딩된 핫키 ID (null이면 미설정)
    order: number;            // 표시 순서
    createdAt: number;
    updatedAt: number;
  }
  

• CRUD 메서드:
  • getAll(): CustomInstruction[]
  • getById(id: string): CustomInstruction | null
  • create(input: CreateCustomInstructionInput): CustomInstruction
  • update(id: string, data: Partial<CustomInstruction>): void
  • delete(id: string): void — isBuiltin은 삭제 불가
  • reorder(ids: string[]): void — 순서 변경
  • resetBuiltins(): void — 프리셋을 기본값으로 초기화

6.2 프리셋 명령어 5개

• 앱 최초 실행 시 자동 생성 (isBuiltin: true)

1. 번역 (translate)

   다음 텍스트를 {{targetLanguage}}로 번역해주세요.
   자연스럽고 정확한 번역만 출력하세요.
   

2. 요약 (summarize)

   다음 텍스트의 핵심 내용을 3줄 이내로 요약해주세요.
   요약문만 출력하세요.
   

3. 전문 리라이트 (formal-rewrite)

   다음 텍스트를 격식 있는 비즈니스 문체로 다시 작성해주세요.
   원래 의미를 유지하면서 전문적인 톤으로 변환하세요.
   다시 작성된 텍스트만 출력하세요.
   

4. 코드 설명 (explain-code)

   다음 코드를 한국어로 설명해주세요.
   각 부분이 무엇을 하는지 간결하게 설명하세요.
   

5. 자유 프롬프트 (free-prompt)

   {{userPrompt}}
   

   • 사용자가 매번 프롬프트를 직접 입력하는 특수 모드
   • UI에서 프롬프트 입력 필드 표시

6.3 사용자 정의 명령어 CRUD UI

• src/renderer/components/CustomCommands.tsx
• 명령어 목록: 이름, 설명, 프리셋 여부 표시
• 추가: 이름, 설명, 프롬프트 템플릿 입력 다이얼로그
  • 프롬프트 템플릿에 {{text}} 변수 자동 삽입 안내
  • 프롬프트 미리보기 (예시 텍스트로 치환 결과 표시)
• 편집: 프리셋은 프롬프트만 수정 가능, 사용자 정의는 전체 수정 가능
• 삭제: 프리셋은 삭제 불가 (리셋만 가능), 사용자 정의는 확인 후 삭제
• 드래그 앤 드롭으로 순서 변경
• IPC 채널:
  • customInstruction:getAll
  • customInstruction:create
  • customInstruction:update
  • customInstruction:delete
  • customInstruction:reorder

6.4 핫키 바인딩 (명령어별)

• 각 커스텀 명령어에 개별 핫키 설정 가능
• HotkeyService에 동적 핫키 등록/해제 연동
• 핫키 녹화 UI (Speakly HotkeyRecordModal 참조):
  • 모달에서 키 조합 누르면 감지 → 표시 → 저장
  • 시스템 예약 키 블랙리스트 (Ctrl+C, Ctrl+V, Alt+F4 등)
  • 중복 핫키 충돌 감지 + 경고
• 명령어별 핫키 → VoiceModeService에 postProcess 자동 설정
  • 핫키 감지 시: 해당 명령어의 prompt로 postProcess 설정 후 녹음 시작

6.5 설정 UI 고도화

• src/renderer/components/Settings.tsx — MUI Modal 기반
• 섹션별 탭 구성:

일반 탭:

• 테마 선택 (light/dark/system)
• 시작 시 최소화
• 닫기 시 트레이로 최소화

음성 입력(STT) 탭:

• STT 모델 선택 드롭다운 (base, small, medium, large-v3)
  • 모델별 크기, 정확도 설명 표시
  • 미다운로드 모델 표시 + 다운로드 버튼 (선택)
• 기본 언어 선택 (auto, ko, en, ja, zh 등)
• VAD 필터 토글
• 초기 프롬프트 입력
• 마이크 디바이스 선택 + 테스트 (Phase 3에서 이관)

LLM 탭:

• Ollama 서버 URL 입력 + 연결 테스트 버튼
• 기본 LLM 모델 선택 드롭다운 (Ollama에서 설치된 모델 목록 조회)
• 기본 온도, 최대 토큰 설정
• 기본 후처리 명령 선택

TTS 탭:

• TTS 활성화/비활성화 토글
• 기본 음성 선택 (설치된 음성 목록)
• 말하기 속도 슬라이더 (0.5x ~ 2.0x)
• 미리듣기 버튼

핫키 탭:

• Dictation 모드 핫키 설정
• Hands-free 모드 핫키 설정
• 커스텀 명령어별 핫키 설정 (6.4 연동)
• 핫키 녹화 모달

6.6 온보딩 플로우 (첫 실행 안내)

• 앱 최초 실행 감지: ConfigService에 onboarding.completed 플래그
• 4단계 온보딩 위저드:
  1. 환영: 앱 소개, 주요 기능 설명
  2. 마이크 설정: 디바이스 선택 + 테스트 녹음
  3. 핫키 설정: 기본 핫키 안내 + 커스텀 설정
  4. Ollama 설정: Ollama 설치 안내 + 연결 테스트, 모델 선택
• 건너뛰기 가능, 설정에서 다시 실행 가능
• Speakly FlowOnboarding 참조: 단계별 UI, 진행 표시기

6.7 i18n (한국어/영어)

• src/shared/i18n/ 디렉토리
• 리소스 파일 구조:

  i18n/
  ├── ko.json    # 한국어 (기본)
  └── en.json    # 영어
  

• 간단한 i18n 유틸리티 (라이브러리 없이 직접 구현):

  type I18nKey = string;
  function t(key: I18nKey, params?: Record<string, string>): string;
  function setLocale(locale: 'ko' | 'en'): void;
  function getLocale(): string;
  

• React 컨텍스트: I18nProvider + useI18n() 훅
• ConfigService ui.language 연동
• 번역 대상: UI 라벨, 에러 메시지, 프리셋 명령어 이름/설명, 온보딩 텍스트
• Speakly I18nService 참조: 키-값 리소스 파일, 런타임 언어 전환

6.8 IPC 채널 추가

• customInstruction:getAll, customInstruction:create, customInstruction:update, customInstruction:delete, customInstruction:reorder
• config:getSection, config:setSection, config:resetSection
• i18n:getLocale, i18n:setLocale, i18n:getTranslations
• onboarding:getStatus, onboarding:complete

Speakly RE 참조

• CustomInstructionConfigService: 명령어 CRUD, 프리셋 관리, electron-store 저장
• HotkeyConfig: 키코드 맵, 시스템 예약 단축키 블랙리스트, HotkeyRecordModal
• FlowOnboarding: 단계별 온보딩 UI, 진행 표시, 건너뛰기
• I18nService: 키-값 리소스 파일, 런타임 언어 전환, React 컨텍스트 연동
• Settings: 섹션별 탭 UI, 디바이스 선택, 모델 선택

완료 조건

• 프리셋 명령어 5개 기본 제공
• 사용자 정의 명령어 추가/편집/삭제/순서변경 가능
• 명령어별 핫키 바인딩 및 핫키로 녹음+명령어 실행 가능
• 설정에서 STT 모델, LLM 모델, TTS 음성 선택 가능
• Ollama 연결 테스트 작동
• 온보딩 위저드가 첫 실행 시 표시됨
• 한국어/영어 UI 전환 가능
• 모든 UI 텍스트가 i18n 리소스에서 로드됨