clawmate 1.4.0 → 1.4.2

package/main/ai-bridge.js

@@ -1,14 +1,14 @@
 /**
- * AI ↔ ClawMate 브릿지
+ * AI <-> ClawMate Bridge
  *
- * AI 에이전트가 ClawMate의 뇌 역할을 한다.
- * - AI → ClawMate: 행동 명령, 말풍선, 감정, 이동
- * - ClawMate → AI: 사용자 이벤트 (클릭, 드래그, 커서, 파일 변화)
+ * AI agent serves as ClawMate's brain.
+ * - AI -> ClawMate: Action commands, speech bubbles, emotions, movement
+ * - ClawMate -> AI: User events (click, drag, cursor, file changes)
  *
- * 통신: WebSocket (로컬 ws://localhost:9320)
- * 프로토콜: JSON 메시지
+ * Communication: WebSocket (local ws://localhost:9320)
+ * Protocol: JSON messages
  *
- * AI 연결 안 됐을 때 → 자율 모드 (기존 FSM) 로 폴백
+ * When AI is not connected -> falls back to autonomous mode (existing FSM)
  */
 const WebSocket = require('ws');
 const EventEmitter = require('events');
@@ -17,7 +17,7 @@ class AIBridge extends EventEmitter {
   constructor() {
     super();
     this.wss = null;
-    this.client = null;           // 연결된 AI 에이전트
+    this.client = null;           // Connected AI agent
     this.connected = false;
     this.port = 9320;
     this.heartbeatInterval = null;
@@ -33,19 +33,19 @@ class AIBridge extends EventEmitter {
   }
 
   /**
-   * WebSocket 서버 시작 — AI 에이전트가 여기에 접속
+   * Start WebSocket server -- AI agent connects here
    */
   start() {
     this.wss = new WebSocket.Server({ port: this.port, host: '127.0.0.1' });
 
     this.wss.on('connection', (ws) => {
-      console.log('[AI Bridge] AI 연결됨');
+      console.log('[AI Bridge] AI connected');
       this.client = ws;
       this.connected = true;
       this.reconnectAttempts = 0;
       this.emit('connected');
 
-      // AI에 현재 상태 전송
+      // Send current state to AI
       this.send('sync', this.petState);
 
       ws.on('message', (data) => {
@@ -53,22 +53,22 @@ class AIBridge extends EventEmitter {
           const msg = JSON.parse(data.toString());
           this._handleCommand(msg);
         } catch (err) {
-          console.error('[AI Bridge] 메시지 파싱 실패:', err);
+          console.error('[AI Bridge] Message parsing failed:', err);
         }
       });
 
       ws.on('close', () => {
-        console.log('[AI Bridge] AI 연결 해제');
+        console.log('[AI Bridge] AI disconnected');
         this.client = null;
         this.connected = false;
         this.emit('disconnected');
       });
 
       ws.on('error', (err) => {
-        console.error('[AI Bridge] WebSocket 오류:', err.message);
+        console.error('[AI Bridge] WebSocket error:', err.message);
       });
 
-      // 하트비트
+      // Heartbeat
       this.heartbeatInterval = setInterval(() => {
         if (this.connected) {
           this.send('heartbeat', { timestamp: Date.now() });
@@ -77,54 +77,54 @@ class AIBridge extends EventEmitter {
     });
 
     this.wss.on('error', (err) => {
-      console.error('[AI Bridge] 서버 오류:', err.message);
+      console.error('[AI Bridge] Server error:', err.message);
     });
 
-    console.log(`[AI Bridge] ws://127.0.0.1:${this.port} 에서 대기 중`);
+    console.log(`[AI Bridge] Listening on ws://127.0.0.1:${this.port}`);
   }
 
   /**
-   * AI에서 온 명령 처리
+   * Handle commands from AI
    */
   _handleCommand(msg) {
     const { type, payload } = msg;
 
     switch (type) {
-      // === 행동 제어 ===
+      // === Behavior Control ===
       case 'action':
-        // AI가 펫의 행동을 직접 지시
+        // AI directly commands pet behavior
         // payload: { state: 'walking'|'excited'|..., duration?: ms }
         this.emit('action', payload);
         break;
 
       case 'move':
-        // 특정 위치로 이동
+        // Move to specific position
         // payload: { x, y, speed? }
         this.emit('move', payload);
         break;
 
       case 'emote':
-        // 감정 표현
+        // Express emotion
         // payload: { emotion: 'happy'|'curious'|'sleepy'|... }
         this.emit('emote', payload);
         break;
 
-      // === 말하기 ===
+      // === Speech ===
       case 'speak':
-        // AI가 펫을 통해 사용자에게 말함
+        // AI speaks to user through the pet
         // payload: { text: string, style?: 'normal'|'thought'|'shout' }
         this.emit('speak', payload);
         break;
 
       case 'think':
-        // 생각 말풍선 (... 형태)
+        // Thought bubble (... form)
         // payload: { text: string }
         this.emit('think', payload);
         break;
 
-      // === 파일 작업 ===
+      // === File Operations ===
       case 'carry_file':
-        // 특정 파일을 집어들도록 지시
+        // Command to pick up specific file
         // payload: { fileName: string, targetX?: number }
         this.emit('carry_file', payload);
         break;
@@ -134,134 +134,134 @@ class AIBridge extends EventEmitter {
         break;
 
       case 'smart_file_op':
-        // 스마트 파일 조작 (텔레그램 또는 AI에서 트리거)
+        // Smart file operation (triggered by Telegram or AI)
         // payload: { phase: 'pick_up'|'drop'|'complete', fileName?, targetName?, ... }
         this.emit('smart_file_op', payload);
         break;
 
-      // === 외형 변화 ===
+      // === Appearance Changes ===
       case 'evolve':
-        // 진화 트리거
+        // Evolution trigger
         // payload: { stage: number }
         this.emit('evolve', payload);
         break;
 
       case 'set_mode':
-        // 모드 전환
+        // Mode switching
         // payload: { mode: 'pet'|'incarnation' }
         this.emit('set_mode', payload);
         break;
 
       case 'accessorize':
-        // 임시 악세사리 추가
+        // Add temporary accessory
         // payload: { type: string, duration?: ms }
         this.emit('accessorize', payload);
         break;
 
-      // === 공간 이동 명령 ===
+      // === Spatial Movement Commands ===
       case 'jump_to':
-        // 특정 위치로 점프
+        // Jump to specific position
         // payload: { x, y }
         this.emit('jump_to', payload);
         break;
 
       case 'rappel':
-        // 레펠 (천장/벽에서 실 타고 내려가기)
+        // Rappel (descend from ceiling/wall on thread)
         // payload: {}
         this.emit('rappel', payload);
         break;
 
       case 'release_thread':
-        // 레펠 실 해제 (낙하)
+        // Release rappel thread (fall)
         // payload: {}
         this.emit('release_thread', payload);
         break;
 
       case 'move_to_center':
-        // 화면 중앙으로 이동
+        // Move to screen center
         // payload: {}
         this.emit('move_to_center', payload);
         break;
 
       case 'walk_on_window':
-        // 특정 윈도우 타이틀바 위로 이동
+        // Move onto specific window title bar
         // payload: { windowId, x, y }
         this.emit('walk_on_window', payload);
         break;
 
       case 'query_windows':
-        // 윈도우 위치 정보 요청 → main process에서 처리
+        // Window position info request -> handled by main process
         this.emit('query_windows', payload);
         break;
 
-      // === 커스텀 이동 패턴 ===
+      // === Custom Movement Patterns ===
       case 'register_movement':
-        // AI가 커스텀 이동 패턴 등록
+        // AI registers custom movement pattern
         // payload: { name: string, definition: { type: 'waypoints'|'formula'|'sequence', ... } }
         this.emit('register_movement', payload);
         break;
 
       case 'custom_move':
-        // 등록된 커스텀 이동 패턴 실행
+        // Execute registered custom movement pattern
         // payload: { name: string, params?: object }
         this.emit('custom_move', payload);
         break;
 
       case 'stop_custom_move':
-        // 현재 커스텀 이동 강제 중지
+        // Force stop current custom movement
         // payload: {}
         this.emit('stop_custom_move', payload);
         break;
 
       case 'list_movements':
-        // 등록된 이동 패턴 목록 요청 → 응답은 renderer에서 reportToAI로 전송
+        // Request registered movement pattern list -> response sent via renderer's reportToAI
         // payload: {}
         this.emit('list_movements', payload);
         break;
 
-      // === 캐릭터 커스터마이징 ===
+      // === Character Customization ===
       case 'set_character':
-        // AI가 생성한 캐릭터 데이터 적용
+        // Apply AI-generated character data
         // payload: { colorMap?: {...}, frames?: {...} }
         this.emit('set_character', payload);
         break;
 
       case 'reset_character':
-        // 원래 캐릭터로 리셋
+        // Reset to default character
         this.emit('reset_character', payload);
         break;
 
       case 'set_persona':
-        // 봇 인격체 전환 (Incarnation 모드)
+        // Bot persona switching (Incarnation mode)
         // payload: { name, personality, speakingStyle, color?, ... }
         this.emit('set_persona', payload);
         break;
 
-      // === 컨텍스트 질의 ===
+      // === Context Queries ===
       case 'query_state':
-        // 현재 펫 상태 요청
+        // Request current pet state
         this.send('state_response', this.petState);
         break;
 
       case 'query_screen':
-        // 화면 정보 요청
+        // Request screen info
         this.emit('query_screen', payload);
         break;
 
-      // === AI 의사결정 결과 ===
+      // === AI Decision Result ===
       case 'ai_decision':
-        // AI의 종합적 의사결정
+        // AI's comprehensive decision
         // payload: { action, speech?, emotion?, reasoning? }
         this.emit('ai_decision', payload);
         break;
 
       default:
-        console.log(`[AI Bridge] 알 수 없는 명령: ${type}`);
+        console.log(`[AI Bridge] Unknown command: ${type}`);
     }
   }
 
   /**
-   * AI에 이벤트 전송
+   * Send event to AI
    */
   send(type, payload) {
     if (!this.client || this.client.readyState !== WebSocket.OPEN) return false;
@@ -273,7 +273,7 @@ class AIBridge extends EventEmitter {
     }
   }
 
-  // === 사용자 이벤트 리포트 (ClawMate → AI) ===
+  // === User Event Reports (ClawMate -> AI) ===
 
   reportUserClick(position) {
     this.send('user_event', {
@@ -335,8 +335,8 @@ class AIBridge extends EventEmitter {
   }
 
   /**
-   * 메트릭 데이터를 AI에 전송
-   * 렌더러에서 수집한 펫 동작 품질 메트릭을 AI에 전달
+   * Send metrics data to AI
+   * Forwards pet behavior quality metrics collected by renderer to AI
    */
   reportMetrics(summary) {
     this.send('metrics_report', {
@@ -345,7 +345,7 @@ class AIBridge extends EventEmitter {
     });
   }
 
-  // === 상태 업데이트 ===
+  // === State Updates ===
 
   updatePetState(updates) {
     Object.assign(this.petState, updates);

package/main/ai-connector.js

@@ -1,15 +1,15 @@
 /**
- * AI 에이전트 측 커넥터
+ * AI Agent-side Connector
  *
- * AI가 ClawMate에 접속해서 펫을 조종하는 클라이언트.
- * ClawMate 플러그인(index.js)에서 사용됨.
+ * Client for AI to connect to ClawMate and control the pet.
+ * Used in the ClawMate plugin (index.js).
  *
- * 사용 예:
+ * Usage:
  *   const connector = new ClawMateConnector();
  *   await connector.connect();
- *   connector.speak('안녕! 오늘 뭐 할 거야?');
+ *   connector.speak('Hello! What are you doing today?');
  *   connector.action('excited');
- *   connector.onUserEvent((event) => { ... AI가 반응 결정 ... });
+ *   connector.onUserEvent((event) => { ... AI decides reaction ... });
  */
 const WebSocket = require('ws');
 const EventEmitter = require('events');
@@ -27,7 +27,7 @@ class ClawMateConnector extends EventEmitter {
   }
 
   /**
-   * ClawMate에 접속
+   * Connect to ClawMate
    */
   connect() {
     return new Promise((resolve, reject) => {
@@ -73,7 +73,7 @@ class ClawMateConnector extends EventEmitter {
       case 'pet_state_update':
         this.petState = payload;
         this.emit('state_update', payload);
-        // queryState() Promise 해소
+        // Resolve queryState() Promise
         if (type === 'state_response' && this._stateResolvers.length > 0) {
           const resolver = this._stateResolvers.shift();
           resolver(payload);
@@ -81,22 +81,22 @@ class ClawMateConnector extends EventEmitter {
         break;
 
       case 'user_event':
-        // 사용자 이벤트 → AI가 반응 결정
+        // User event -> AI decides reaction
         this.emit('user_event', payload);
         break;
 
       case 'screen_capture':
-        // 화면 캡처 응답 → AI가 분석
+        // Screen capture response -> AI analyzes
         this.emit('screen_capture', payload);
         break;
 
       case 'window_positions':
-        // 윈도우 위치 정보 응답 → 탐험 시스템에서 사용
+        // Window position info response -> used by exploration system
         this.emit('window_positions', payload);
         break;
 
       case 'metrics_report':
-        // 메트릭 데이터 수신 → AI가 분석
+        // Metrics data received -> AI analyzes
         this.emit('metrics_report', payload);
         break;
 
@@ -115,109 +115,109 @@ class ClawMateConnector extends EventEmitter {
     }
   }
 
-  // === AI → ClawMate 명령 API ===
+  // === AI -> ClawMate Command API ===
 
-  /** 펫이 말하게 함 */
+  /** Make the pet speak */
   speak(text, style = 'normal') {
     return this._send('speak', { text, style });
   }
 
-  /** 펫이 생각하게 함 (말풍선에 ...) */
+  /** Make the pet think (shows ... in speech bubble) */
   think(text) {
     return this._send('think', { text });
   }
 
-  /** 펫 행동 변경 */
+  /** Change pet behavior */
   action(state, duration) {
     return this._send('action', { state, duration });
   }
 
-  /** 특정 위치로 이동 */
+  /** Move to specific position */
   moveTo(x, y, speed) {
     return this._send('move', { x, y, speed });
   }
 
-  /** 감정 표현 */
+  /** Express emotion */
   emote(emotion) {
     return this._send('emote', { emotion });
   }
 
-  /** 파일 집어들기 */
+  /** Pick up file */
   carryFile(fileName, targetX) {
     return this._send('carry_file', { fileName, targetX });
   }
 
-  /** 파일 내려놓기 */
+  /** Drop file */
   dropFile() {
     return this._send('drop_file', {});
   }
 
-  /** 모드 전환 */
+  /** Switch mode */
   setMode(mode) {
     return this._send('set_mode', { mode });
   }
 
-  /** 진화 트리거 */
+  /** Trigger evolution */
   evolve(stage) {
     return this._send('evolve', { stage });
   }
 
   /**
-   * AI 종합 의사결정 전송
-   * AI가 상황을 분석하고 내린 결정을 한번에 전송
+   * Send comprehensive AI decision
+   * Sends the AI's analyzed decision in a single message
    */
   decide(decision) {
     return this._send('ai_decision', decision);
   }
 
-  // === 공간 이동 API (펫이 컴퓨터를 "집"처럼 돌아다님) ===
+  // === Spatial Movement API (pet roams the computer like its "home") ===
 
-  /** 특정 위치로 점프 */
+  /** Jump to specific position */
   jumpTo(x, y) {
     return this._send('jump_to', { x, y });
   }
 
-  /** 레펠 시작 (천장/벽에서 실 타고 내려감) */
+  /** Start rappelling (descend from ceiling/wall on thread) */
   rappel() {
     return this._send('rappel', {});
   }
 
-  /** 레펠 실 해제 (낙하) */
+  /** Release rappel thread (fall) */
   releaseThread() {
     return this._send('release_thread', {});
   }
 
-  /** 화면 중앙으로 이동 */
+  /** Move to screen center */
   moveToCenter() {
     return this._send('move_to_center', {});
   }
 
-  /** 특정 윈도우 위로 점프 */
+  /** Jump onto specific window */
   walkOnWindow(windowId, x, y) {
     return this._send('walk_on_window', { windowId, x, y });
   }
 
-  /** 열린 윈도우 목록 요청 */
+  /** Request list of open windows */
   queryWindows() {
     return this._send('query_windows', {});
   }
 
-  // === 커스텀 이동 패턴 API ===
+  // === Custom Movement Pattern API ===
 
   /**
-   * 커스텀 이동 패턴 등록
-   * ClawMate에 새로운 이동 패턴을 동적으로 추가
+   * Register custom movement pattern
+   * Dynamically add new movement patterns to ClawMate
    *
-   * @param {string} name - 패턴 이름 (예: 'figure8', 'spiral')
-   * @param {object} definition - 패턴 정의
+   * @param {string} name - Pattern name (e.g., 'figure8', 'spiral')
+   * @param {object} definition - Pattern definition
    *   type: 'waypoints' | 'formula' | 'sequence'
-   *   waypoints?: [{x, y, pause?}]      — 웨이포인트 순차 이동
-   *   formula?: { xAmp, yAmp, xFreq, yFreq, xPhase, yPhase }  — 수학 궤도
-   *   sequence?: ['zigzag', 'shake']     — 기존 패턴 순차 실행
-   *   duration?: number                  — 지속 시간 (ms, formula 타입)
-   *   speed?: number                     — 이동 속도
+   *   waypoints?: [{x, y, pause?}]      -- Sequential waypoint movement
+   *   formula?: { xAmp, yAmp, xFreq, yFreq, xPhase, yPhase }  -- Mathematical orbit
+   *   sequence?: ['zigzag', 'shake']     -- Execute existing patterns sequentially
+   *   duration?: number                  -- Duration (ms, for formula type)
+   *   speed?: number                     -- Movement speed
    *
-   * 사용 예:
+   * Usage:
    *   connector.registerMovement('figure8', {
    *     type: 'formula',
    *     formula: { xAmp: 80, yAmp: 40, xFreq: 1, yFreq: 2 },
@@ -229,14 +229,14 @@ class ClawMateConnector extends EventEmitter {
   }
 
   /**
-   * 등록된 커스텀 이동 패턴 실행
+   * Execute registered custom movement pattern
    *
-   * @param {string} name - 실행할 패턴 이름
-   *   사전 등록 패턴: 'zigzag', 'patrol', 'circle', 'shake', 'dance'
-   *   또는 registerMovement()로 등록한 커스텀 패턴
-   * @param {object} params - 실행 파라미터 (패턴별로 다름)
+   * @param {string} name - Pattern name to execute
+   *   Built-in patterns: 'zigzag', 'patrol', 'circle', 'shake', 'dance'
+   *   Or custom patterns registered via registerMovement()
+   * @param {object} params - Execution parameters (varies by pattern)
    *
-   * 사용 예:
+   * Usage:
    *   connector.customMove('zigzag', { distance: 200, amplitude: 30 });
    *   connector.customMove('patrol', { pointAX: 100, pointBX: 500, laps: 5 });
    *   connector.customMove('shake', { intensity: 6, duration: 1000 });
@@ -245,39 +245,39 @@ class ClawMateConnector extends EventEmitter {
     return this._send('custom_move', { name, params });
   }
 
-  /** 현재 실행 중인 커스텀 이동 강제 중지 */
+  /** Force stop currently running custom movement */
   stopCustomMove() {
     return this._send('stop_custom_move', {});
   }
 
-  /** 등록된 이동 패턴 목록 요청 (응답은 user_event로 수신) */
+  /** Request list of registered movement patterns (response via user_event) */
   listMovements() {
     return this._send('list_movements', {});
   }
 
-  /** 스마트 파일 조작 명령 전송 */
+  /** Send smart file operation command */
   smartFileOp(payload) {
     return this._send('smart_file_op', payload);
   }
 
-  /** 캐릭터 데이터 전송 (AI 생성 캐릭터 적용) */
+  /** Send character data (apply AI-generated character) */
   setCharacter(data) {
     return this._send('set_character', data);
   }
 
-  /** 원래 캐릭터로 리셋 */
+  /** Reset to default character */
   resetCharacter() {
     return this._send('reset_character', {});
   }
 
-  /** 인격체 전환 (Incarnation 모드에서 봇 인격 반영) */
+  /** Switch persona (reflect bot personality in Incarnation mode) */
   setPersona(data) {
     return this._send('set_persona', data);
   }
 
   /**
-   * 현재 펫 상태 요청 (Promise 반환)
-   * 서버에서 state_response가 오면 resolve, 타임아웃 시 캐시된 상태 반환
+   * Request current pet state (returns Promise)
+   * Resolves when state_response arrives from server, returns cached state on timeout
    */
   queryState(timeout = 2000) {
     return new Promise((resolve) => {
@@ -297,22 +297,22 @@ class ClawMateConnector extends EventEmitter {
     });
   }
 
-  /** 화면 캡처 요청 (ClawMate에서 스크린샷 촬영 후 응답) */
+  /** Request screen capture (ClawMate takes screenshot and responds) */
   requestScreenCapture() {
     return this._send('query_screen', {});
   }
 
-  /** 화면 캡처 응답 리스너 등록 */
+  /** Register screen capture response listener */
   onScreenCapture(callback) {
     this.on('screen_capture', callback);
   }
 
-  /** 사용자 이벤트 리스너 등록 */
+  /** Register user event listener */
   onUserEvent(callback) {
     this.on('user_event', callback);
   }
 
-  /** 메트릭 리포트 리스너 등록 */
+  /** Register metrics report listener */
   onMetrics(callback) {
     this.on('metrics_report', callback);
   }