SoC TaskManager Framework
이 항목은 DeviceAgent 쪽에서 진행한 TaskManager 작업을 SoC 업체가 보고 같은 방향으로 구현할 수 있도록 정리한 큰 묶음이다.
목표는 단순히 TaskManager.java 설명을 남기는 것이 아니다. 나중에 이 구조를 SoC 실행 프레임워크로 리팩터링할 수 있도록, 배경, 구조, 실제 작업내역, 업체 구현 범위, 검증 기준을 한 흐름으로 제공한다.
중요한 전제:
DeviceAgent TaskManager는 Cloud LLM 전용 모듈이 아니다.
Cloud LLM, 온디바이스 음성 브릿지, MQTT 명령 서버, 앱/리모트 제어 등 여러 ingress가 공통으로 사용하는 SoC 실행 관문이어야 한다.
먼저 선택할 진입로
| 목적 | 시작 문서 | 읽는 방식 |
|---|---|---|
| 업체에게 설명/회의 진행 | Vendor Briefing Path | 10분 요약 -> 30분 구조 설명 -> 구현 질의응답 순서 |
| 기존/변경 Layer 시각화 | DeviceAgent Layer Transition | 기존 DeviceAgent layer와 TaskManager 추가 후 layer 차이를 SVG로 확인 |
| MainApi 삽입점 확인 | MainApi TaskManager Insertion | 기존 명령이 MainApi에 모이는 위치와 TaskManager hook이 동작하는 위치 확인 |
| 소스 파일 매핑 | DeviceAgent TaskManager Layer Source Map | 각 layer가 실제 어떤 Java 파일과 연결되는지 확인 |
| 실행 lifecycle 상세 | DeviceAgent Task Lifecycle Detail | submitTask, submitWorkflow, event, executor fallback의 runtime 흐름 확인 |
| 구조 변화 이해 | Before/After Change Model | 기존 DeviceAgent 구조와 TaskManager layer 추가 후 차이 확인 |
| 실제 구현 착수 | Source-Level Implementation Guide | MainApi, TaskManager, policy, validator, executor, event 순서로 작업 |
| 제출물/검증 기준 확인 | Vendor Implementation Workbook | API sample, event sample, reason, evidence checklist 확인 |
| 장기 프레임워크화 논의 | Framework Refactor Roadmap | DeviceAgent 내부 package에서 SoC 실행 framework로 분리하는 방향 확인 |
전체 읽는 순서
| 순서 | 챕터 | 목적 |
|---|---|---|
| 1 | Vendor Briefing Path | 업체 설명을 어떤 흐름으로 진행할지 확인 |
| 2 | DeviceAgent Layer Transition | 기존 Layer와 변경 Layer를 먼저 시각적으로 이해 |
| 3 | MainApi TaskManager Insertion | 기존 명령 집결 지점과 TaskManager 삽입 지점을 코드 흐름으로 이해 |
| 4 | DeviceAgent TaskManager Layer Source Map | layer별 실제 소스 파일과 업체 작업 범위 확인 |
| 5 | DeviceAgent Task Lifecycle Detail | submitTask/submitWorkflow가 runtime에서 지나가는 세부 단계 확인 |
| 6 | Background | 왜 TaskManager가 필요한지, Cloud/MQTT/App/On-device/DeviceAgent 경계를 이해 |
| 7 | Before/After Change Model | 기존 DeviceAgent 구조와 TaskManager layer 추가 후 변화, 이점, 업체 설명 포인트 이해 |
| 8 | Source-Level Implementation Guide | 실제 코드 기준으로 어디에 어떤 layer를 붙이고 어떤 method를 구현해야 하는지 확인 |
| 9 | Architecture | 현재 소스 기준 컴포넌트와 실행 흐름 이해 |
| 10 | Implementation Worklog | 실제 추가/정리된 클래스와 역할 확인 |
| 11 | Vendor Implementation Workbook | 업체가 구현해야 할 API, event, test evidence 확인 |
| 12 | Framework Refactor Roadmap | 나중에 SoC 실행 프레임워크로 리팩터링하는 방향 |
기준 소스
/home/silogood/work/1.A1_SoC_new/SoC/a1-packages/apps/DeviceAgent
핵심 파일:
app/src/main/java/com/sk/airbot/deviceagent/task/TaskManager.java
app/src/main/java/com/sk/airbot/deviceagent/task/TaskEventListener.java
app/src/main/java/com/sk/airbot/deviceagent/task/TaskReasonContract.java
app/src/main/java/com/sk/airbot/deviceagent/task/DevicePlanningContextProvider.java
app/src/main/java/com/sk/airbot/deviceagent/task/TaskIngressClassifier.java
app/src/main/java/com/sk/airbot/deviceagent/task/TaskBundleValidator.java
app/src/main/java/com/sk/airbot/deviceagent/task/TaskExecutorRegistry.java
app/src/main/java/com/sk/airbot/deviceagent/task/TaskExecutorBootstrap.java
현재 구현 핵심
| 축 | 현재 상태 |
|---|---|
| API entry | TaskManager.handleControlMethod(...)가 submitTask, submitWorkflow, getTaskStatus, cancelTask, getDevicePlanningContext 등을 처리 |
| workflow | submitWorkflow가 subTasks 순차 실행과 parallelGroup 실행을 지원 |
| event | notifyTaskEvent(...)가 onTaskEvent bundle을 listener와 AppCmd.INSTANCE.sendModuleCallback_main(...)으로 전달 |
| reason | TaskReasonContract가 실패를 upstream이 공통 해석 가능한 reason_code, recoverability, suggested_action으로 정규화 |
| planning context | DevicePlanningContextProvider가 battery/map/location/cleaning/movement/task_manager/capabilities snapshot 생성 |
| executor binding | TaskExecutorRegistry와 TaskExecutorBootstrap이 movement/cleaning/LLM/TTS/IoT/update executor를 method와 연결 |
기존 구조 대비 변화
| 구분 | 기존 DeviceAgent 중심 구조 | TaskManager layer 추가 후 |
|---|---|---|
| 명령 진입 | DeviceAgent, MainApi.executeMethod(...), 개별 command handler로 직접 분기 |
submitTask, submitWorkflow로 먼저 admission/validation/policy를 통과 |
| 복합명령 | 호출자가 순서와 상태를 직접 관리해야 함 | TaskManager가 workflow/subTask/currentStepIndex를 관리 |
| 실패 처리 | callback 또는 자연어/토스트성 이유가 분산될 수 있음 | reason_code, reason_params, recoverability, requires_cloud_decision으로 구조화 |
| 이벤트 | 기능별 callback이 흩어짐 | onTaskEvent terminal/progress event를 공통 contract로 제공 |
| 외부 유입원 | Cloud, MQTT, App, 예약 source별로 경로가 갈라질 위험 | source trace만 다르고 같은 TaskManager API를 사용 |
| 프레임워크화 | 기능 함수 묶음에 가까움 | admission, queue, workflow, executor registry, event bus 성격의 SoC 실행 layer |
상세 비교와 업체 설명용 구조도는 Before/After Change Model을 기준으로 한다.
MainApi 안에서 실제로 TaskManager가 어느 위치에 삽입되는지는 MainApi TaskManager Insertion을 기준으로 설명한다.
업체 전달 핵심 문장
DeviceAgent TaskManager = task/workflow admission + queue + executor binding + event callback + reason contract + planning context provider
SoC 쪽의 목표는 “명령 함수 묶음”이 아니라 “기기 실행 오케스트레이션 프레임워크”다.
Ingress 관점
| 유입원 | TaskManager 사용 방식 | 반환/이벤트 처리 |
|---|---|---|
| Cloud A2A / LLM | 발화 기반 plan을 submitTask/submitWorkflow로 전달 |
requires_cloud_decision=true인 실패만 replan 후보 |
| On-device Bridge | Cloud 또는 로컬 음성 결과를 DeviceAgent Bundle로 변환 | 정상 진행/완료는 로컬 처리, 필요 시 상위로 relay |
| MQTT Command Server | 서버에서 내려온 원격 명령을 같은 task/workflow API로 등록 | LLM replan이 아니라 command ack/status/report 중심 |
| App / Remote Control | 앱 버튼, 예약, 자동화 요청을 task로 등록 | UI state와 server state에 event 반영 |
| Internal Policy / Schedule | 기기 내부 정책, 예약, 자동 실행을 task로 등록 | DeviceAgent 내부 상태와 event log로 관리 |
따라서 문서에서 Cloud라고 적힌 부분은 대부분 “현재 우리가 먼저 붙이고 있는 upstream”을 의미한다.
SoC 프레임워크 관점의 실제 목표는 source가 무엇이든 동일한 admission, validation, queue, executor, event, reason contract를 태우는 것이다.