Source Traceability Matrix
이 문서는 운영 Wiki의 설명이 실제 On-device Agent 코드의 어느 지점과 연결되는지 추적하기 위한 표입니다. PDF로 출력할 때는 이 문서를 부록처럼 붙이면, 기능 설명과 코드 근거를 함께 확인할 수 있습니다.
1. E2E 처리 흐름과 코드 근거
| 단계 | 핵심 파일/함수 | 코드 위치 | 로그/증거 |
|---|---|---|---|
| STT 결과 수집 | ForegroundService.decodeSpeechToText() |
app/src/main/java/com/skmagic/ondeviceai/agent/service/ForegroundService.kt:1977 |
originalSttResult, STT token/timestamp 로그 |
| 전체 음성 명령 오케스트레이션 | ForegroundService.processVoiceCmd() |
ForegroundService.kt:1813 |
processVoiceCmd, BEFORE Processing, AFTER Processing |
| Cloud/Local 분기 | processVoiceCmd() 내부 |
ForegroundService.kt:1829 |
Continuing with Cloud LLM conversation, Processing with on-device LLM |
| 로컬 이해 실패 후 Cloud fallback | processVoiceCmd() 내부 |
ForegroundService.kt:1837 |
UNDERSTANDING ERROR TO CLOUD |
| 로컬 라우팅 | ForegroundService.processLLAMA() |
ForegroundService.kt:2051 |
LLM inference started, [DICTIONARY_MATCH], parsedLlamaResponse |
| Cloud Case 재진입 | runCloudResolvedQueryThroughLocalPipeline() |
ForegroundService.kt:2039 |
Cloud rewrite_query enters local routing pipeline |
| Cloud 호출 | ForegroundService.processCloudLLM() |
ForegroundService.kt:2274 |
Cloud LLM processing took, Cloud LLM Error |
| Cloud request 생성 | ForegroundService.callCloudLLMAPI() |
ForegroundService.kt:2420 |
REQ size, send json, Request body size |
| 기능 실행 전 검증 | ApiCallValidator.preApiCallValidate() |
app/src/main/java/com/skmagic/ondeviceai/agent/common/ApiCallValidator.kt |
ApiCallValidator(preApiCallValidate), getErrorStatus |
| 기능 실행/TTS 매핑 | FunctionCallHandler.processCall() |
app/src/main/java/com/skmagic/ondeviceai/agent/service/FunctionCallHandler.kt:220 |
FunctionCallHandler, mappingTtsTextAndDeviceApi, ttsText |
2. 딕셔너리 처리 근거
| 항목 | 파일/클래스 | 코드 위치 | 역할 |
|---|---|---|---|
| exact match | PreDefinedCommandMatcher |
app/src/main/java/com/skmagic/ondeviceai/agent/service/PreDefinedCommandMatcher.kt:16 |
mapping.json 기반 정확 발화 매칭 |
| contains token | CommandContainsMatcher |
app/src/main/java/com/skmagic/ondeviceai/agent/service/CommandContainsMatcher.kt:11 |
contains_token.json 그룹 조건 매칭 |
| 3 keyword | ThreeKeywordContainsTokenMatcher |
app/src/main/java/com/skmagic/ondeviceai/agent/service/ThreeKeywordContainsTokenMatcher.kt:16 |
기능명/대상/동작어 3축 매칭 |
| contains 치환 | CommandContainsFinder |
ForegroundService.processLLAMA() 호출부 |
contains.json 기반 입력 보정 |
| 매칭 적용 순서 | processLLAMA() |
ForegroundService.kt:2078 |
3keyword -> mapping -> contains_token -> local LLM |
운영 판단:
STT raw가 틀리면 dictionary 품질로 계산하지 않는다.
STT processed가 맞고 token이 틀릴 때 dictionary/로컬 LLM 이슈로 본다.
dictionary 수정은 positive/negative/regression을 함께 검증한다.
3. Cloud LLM 계약 근거
| 항목 | 코드 위치 | 설명 |
|---|---|---|
| Persona prompt | loadPrompt() |
LLM_PROMPT_ko.text, LLM_PROMPT_en.text 또는 외부 prompt 파일 |
| Information message | callCloudLLMAPI() |
Date, Time, DayOfWeek, TimeZone 구성 |
| Environment message | callCloudLLMAPI() |
Weather, Humidity, Temperature low/high, PM 정보 구성 |
| User message | callCloudLLMAPI() |
originalSttResult 기반 user content |
| Case 1/4 | callCloudLLMAPI() response 처리 |
Cloud response를 TTS로 출력 |
| Case 2 | callCloudLLMAPI() response 처리 |
rewrite_query를 로컬 파이프라인으로 재진입 |
| Case 2 최종 검증 | runCloudResolvedQueryThroughLocalPipeline() 이후 로그 |
기대 <sk_xx> token 재매칭까지 확인 |
| Case 3 | callCloudLLMAPI() response 처리 |
prepared question 또는 rewrite query 처리 |
Cloud 운영 기준:
Cloud가 제품 기능을 직접 수행했다고 말하면 안 된다.
제품 기능 의도는 Case 2 + rewrite_query + 온디바이스 재진입으로 검증한다.
Case 2는 Cloud 성공이 아니라 중간 단계이며, 기대 token 재매칭과 Validator/API/TTS까지 확인한다.
말레이시아 Custom RAG는 제품 기능 실행이 아니라 현지 문서 기반 답변 보강 경로다.
상세 기준:
4. Error Handler 근거
| 항목 | 코드 위치 | 설명 |
|---|---|---|
| validation map | ApiCallValidator.initializeValidationRules() |
토큰별 rule 묶음 정의 |
| LLM 실행 전 차단 | preLlmCallValidate() |
홈잠금, 프라이버시, 음소거, 음성인식, 음량, 에러코드 |
| 기능 실행 전 차단 | preApiCallValidate() |
token별 validation rule 적용 |
| 이동 기능 rule | createMovementRules() |
이동/주행/센서/위치 계열 차단 |
| Safe Care rule | createSafeCareRules() |
보안모드 관련 에러 차단 |
| 기타 rule | otherRules() |
직접 발화보다 관리/로그 분류 목적 |
운영 판단:
token이 맞는데 기능이 실행되지 않는 것은 실패가 아닐 수 있다.
현재 errorcode와 ErrorGroup이 기능 실행을 정상 차단했는지 먼저 확인한다.
5. 말레이시아 현지 운영 근거
| 영역 | 현지 기준 |
|---|---|
| 언어 | 영어 기본 검증 + 말레이시아 현지 표현 regression set |
| 지명/건물명 | 지역명/건물명은 제품 공간명과 분리 |
| Custom RAG | 현지 FAQ, 서비스, 보증, 앱 가이드, 국가별 제한 기능 |
| 기능 실행 | On-device token, Validator, Device API 기준 |
| 리포트 | STT raw, processed, token, Cloud response, API, TTS를 한 표에 기록 |
6. PDF 출력 관점
| 항목 | 기준 |
|---|---|
| SVG 크기 | PDF 본문 삽입용은 1120x760 전후의 svg/pdf-safe/ 또는 svg/day-sections/ 우선 사용 |
| 큰 구조도 | 기존 대형 architecture SVG는 원본 보존, PDF에는 pdf-safe 요약 사용 |
| 문서 순서 | index -> Day 1~5 -> source-level -> templates 순서 권장 |
| 검증 | build, lint, link check, 원격 HTML/SVG 200 확인 |