EZmap 기술 문서

개요 #

EZmap은 '내비/어시스턴트'가 아니라 Personal Agent Runtime — 폰이 모든 앱·기기 위의 사용자-소유 실행 레이어가 되어, 디지털 세계를 조작하고 검증하며 그 폰에 지속 역량을 누적합니다. 어시스턴트는 답하지만, 런타임은 툴을 만들고·검증하고·고칩니다.

아키텍처 #

음성 입력에서 응답까지의 전체 파이프라인. 모든 단계가 단일 패키지 com.example.ez_capstone 안에서 동작합니다.

실행 단계

1. SystemPrompt.build(context)   // GPS·시간·프로필·경로 상태 주입
2. GeminiApiClient.generateContent()  // Gemini 2.5 Flash
3. if (functionCall) ToolExecutor.execute() → 결과 재주입
4. functionCall 없을 때까지 반복  (MAX_ITERATIONS = 14)
5. 최종 파싱 → AgentResponse { replyText, ttsText, uiAction, uiData }

빌드 & 실행 #

Kotlin 2.0.21 · AGP 8.12.3 · Min SDK 26 · Target/Compile SDK 36.

# 디버그 빌드 / 설치
cd android
JAVA_HOME="…/Android Studio/jbr" ./gradlew assembleDebug
JAVA_HOME="…/Android Studio/jbr" ./gradlew installDebug

# 유닛 테스트
./gradlew test --tests "com.example.ez_capstone.agent.*"

필수 키 (local.properties, git-ignored)

Agent Loop #

agent/GeminiAgentEngine.kt · doChatLoop() — Gemini REST API를 직접 호출하는 Function Calling 루프. functionCall이 사라질 때까지 반복하며, 매 iteration마다 응답에 도구 호출이 있으면 ToolExecutor.execute() 결과를 다시 Gemini에 주입합니다.

1 · 동적 도구 라우팅

62개 도구를 매번 전부 보내면 토큰이 폭증하고 Gemini가 혼란스러워집니다. EZmap은 발화를 먼저 IntentDetector로 분류한 뒤, 해당 intent에 매핑된 도구만 추려 전달합니다.

2 · 자율 컴파운드 보장

open_app이 검색·작업을 만나면 task_pending을 반환하고, 다음 iteration이 강제 tool 모드(ANY)로 전환됩니다 (GeminiAgentEngine.kt:797). 이로써 에이전트가 도구 대신 텍스트로 "열었어요"라며 멈추는 루프를 근절하고, open_app → control_app(action=search) 체이닝을 결정적으로 완주시킵니다.

도구 실행이 실패하면 다음 iteration에 reflection hint가 주입되어(GeminiAgentEngine.kt:761) Gemini가 오류를 인지하고 자기 교정합니다.

3 · 지연 시간 계측

매 실행은 4개 구간을 측정해 로그로 남깁니다 — STT 완료부터 첫 토큰·도구 완료·TTS 시작까지.

Tool Catalog #

Gemini Function Calling에 등록되는 내장 도구 — 정확히 62개 (agent/ToolDeclarations.kt · allTools()). 각 도구는 tool(name, description, params) 헬퍼로 정의되며, 아래 설명은 코드의 실제 description 필드에서 추출했습니다.

이동 · 경로 8

주유 · 충전 · 주차 5

교통 · 도로안전 8

날씨 · 환경 3

생활 · 지식 6

프로필 · 메모 · 학습 9

일정 · 연락 · 커뮤니케이션 11

미디어 6

앱 조작 · 기기 · 확장 6

합계 8+5+8+3+6+9+11+6+6 = 62. call_desktop은 Desktop Bridge 키가 설정된 경우에만 활성화됩니다(ALWAYS_INCLUDED 제외).

컨텍스트 주입 #

agent/SystemPrompt.kt가 매 호출마다 실시간 컨텍스트를 시스템 프롬프트에 합성합니다.

① 가르치기 모드 (PbD) #

Programming by Demonstration — 사용자가 직접 시연하면 에이전트가 그 동작을 증류해 재사용 가능한 스킬로 저장합니다.

"이거 가르쳐줄게" 발화
  ↓ 접근성 ON 체크 → OFF면 즉시 안내 + abort
  ↓ DemonstrationRecorder.capture()   // 의미 단위 DemoStep[] (좌표 아님)
  ↓ SkillSynthesizer.distillFromDemo() → Gemini → JS
  ↓ SkillLearner.promoteFromScript(reason="distill")
  ↓ LearnedSkill 저장 (confidence = 0.80)
  ↓ 0.80 > SAFE(0.75) → 즉시 자율 실행 가능

② 외부 앱 조작 (control_app) #

접근성(Accessibility) 기반으로 모든 앱을 자율 조작하는 super-tool. 매 액션 후 화면을 다시 read해 Gemini 컨텍스트를 갱신하며 read → tap → type → submit → verify 컴파운드를 결정적으로 수렴시킵니다.

지원 액션 — 20종 (ToolExecutor.executeControlApp() when 분기 검증)

핵심 파일: accessibility/EZmapAccessibilityService.kt · agent/ToolExecutor.executeControlApp() · agent/ControlActionGuard.kt

③ AgentLink (Desktop Bridge) #

폰에서 PC의 Claude Code · Codex · bash를 원격 실행합니다. URL과 Token이 설정된 경우에만 call_desktop 도구가 활성화됩니다.

"PC에서 프로젝트 빌드해줘" 발화
  ↓ call_desktop(type="claude" | "codex" | "bash")
  │ bash 위험명령 하드 게이트 (10종 차단)
  │ rm -rf · mkfs · dd if= · fork bomb · curl|sh · shutdown …
  ↓ HTTP POST /run → ezmap-desktop-bridge.js (Node.js)
  │ token 검증 → spawn(claude --print / codex / sh -c)
  ↓ stdout/stderr → JSON (readTimeout 130s)
  ↓ output → Gemini 컨텍스트 → 사용자 응답

④ 자기확장 & 자동 학습 #

능력 갭을 감지하면 JS 스킬을 생성·실행·자기수리하고, 반복 패턴을 자동으로 스킬로 승격합니다. "스킬 추가보다 스킬 복구가 10배 중요"가 설계 철학입니다.

매 대화 후 — skillLearner.observeUtterance()
  ↓ observeCount++ → 5회마다 GeneralUtteranceLearner
  │ 동일 패턴 3회+ → LearnedSkill 자동 생성

능력 갭 감지 시:
  ↓ SkillSynthesizer.synthesizeRunPersist()
  │ JS 생성 → Rhino 실행 → 실패 시 자기수리 (MAX_REPAIRS = 2)
  │ 최대 3회 시도 (1 생성 + 2 수리)
  ↓ promoteFromScript(confidence = 0.60) → 스킬 누적

신뢰도 상태 머신 (검증)

Rhino 샌드박스 보안

데이터 계층 #

db/EZMapDatabase.kt — Room @Database version 16 · 15 Entity · SQLCipher AES-256 전체 암호화(di/DatabaseModule.kt SupportFactory).

안전 · 거버넌스 #

"안전 정책 > LLM 창의성" — 모든 actuate는 게이트를 통과해야 실행됩니다. 각 게이트는 소스코드로 검증되었습니다.

API Key 관리 #

config/ApiKeyProvider.kt — EncryptedSharedPreferences(AES-256-GCM)에 저장. 키는 사용자 디바이스를 벗어나지 않습니다.

시스템 구성 #

단일 패키지 com.example.ez_capstone · 모든 파일 개수는 파일시스템 직접 카운트.

MCP 서버 #

인앱 MCP(Model Context Protocol) 서버가 Gemini 에이전트에 도구를 등록하고, Cloudflare Quick Tunnel로 원격 노출합니다.

EZmapMcpHttpServer가 네트워크 너머로 MCP를 서빙하고, AgentLinkExporter가 call_desktop 도구를 노출합니다. SELinux 차단 시 USB fallback을 안내합니다.

음성 파이프라인 #

웨이크워드 "이지야" → STT → 에이전트 → TTS. 온디바이스(Vosk)와 클라우드(Google) STT를 SttRoutingPolicy로 라우팅합니다.

Voice State: IDLE → LISTENING → PROCESSING → SPEAKING → IDLE. NaturalVoiceEngine은 "300m 앞 맥도날드 보이면 우회전" 같은 자연어 안내로 변환합니다.

내비게이션 엔진 #

턴바이턴 안내부터 그림자 재탐색, AI 주행 조언까지 16개 엔진으로 구성됩니다.

기술 스택 #

팀 & 연락처 #

지도교수 진동섭 · IT융합학부 · 2026학년도 1학기 캡스톤디자인