TaskManager 사양 1 · 개념과 아키텍처
NoneTaskManager의 책임 경계, AOSP와 SKIX namuh 안에서의 위치, 내부 구성요소를 정의한다.
이 장의 결론: TaskManager는 기존 기기 기능을 대체하지 않고, DeviceAgent 안에서 실행 순서와 상태를 공통으로 관리한다.
0. 문서 판독 규칙
0.1 상태 표기
| 표기 | 의미 | 문서에서의 사용 기준 |
|---|---|---|
| 현재 구현 | MR6 소스에 실행 경로가 존재함 | 클래스, 메서드, 필드와 런타임 경로를 확인함 |
| 코드 검증 | JVM·단위 테스트·빌드 수준에서 확인됨 | 테스트 통과가 실기기 동작을 의미하지는 않음 |
| 실기기 확인 | 특정 기기와 APK 조합에서 실제 증거를 확인함 | 기기, APK 해시나 설정이 바뀌면 재검증 필요 |
| 목표 사양 | 구조적으로 합의한 다음 단계 | 현재 코드에 일부 또는 전부 없을 수 있음 |
| 운영 확장 | Cloud, A2A, 모니터와 상위 서비스 연동 규격 | TaskManager Core의 필수 계약과 분리함 |
| 미검증 | 코드가 있어도 출시 인수 시험이 끝나지 않음 | 제품 완료로 표현하지 않음 |
0.2 가장 중요한 경계
0.3 구현 기준 구성요소
| 범위 | 기준 위치 |
|---|---|
| TaskManager Core | apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskManager.java |
| 메서드 정책 | TaskPolicyRegistry.java, TaskPolicy.java |
| 입력 검증/실행 허용 | TaskBundleValidator.java, TaskCallerPolicy.java, TaskDomainResourcePolicy.java, TaskResourcePolicy.java |
| 제품 상태/동작 제한 | StateManager.java, CmdPolicyManager.java, 도메인별 manager/controller |
| LLM/음성 세션 상태 | LlmManager.java, LlmPipelineObservationBridge.java, MainApi.setLlmStatus 경로 |
| 실행기 | TaskExecutorRegistry.java, TaskExecutorBootstrap.java, 도메인별 *TaskExecutor.java |
| 완료 판정 | TaskCompletionStateStore.java, TaskCompletionWatcher.java, AppSessionCompletionBridge.java, LlmTaskCompletionBridge.java |
| 실패 사유 | TaskReasonContract.java |
| 계획 컨텍스트 | DevicePlanningContextProvider.java |
| 요청 분류 | TaskIngressClassifier.java, TaskIngressClassification.java |
| 모니터링 | TaskMonitorReporter.java, TaskMonitorCommandPoller.java, TaskMonitorCommandBridge.java, TaskMonitorHttpAuth.java |
| 제품 시스템 앱 API | apps/TaskManagerClient/taskmanagerclient/ |
| 외부 계약 | apps/TaskManagerClient/API_SPEC.md |
0.4 규범 키워드
이 문서의 규칙은 중요도에 따라 다음처럼 읽는다.
| 키워드 | 쉬운 설명 | 위반 시 처리 |
|---|---|---|
| MUST / 필수 | 지키지 않으면 TaskManager 계약을 만족하지 못하는 조건 | 출시 차단 또는 명시적 예외 승인 필요 |
| MUST NOT / 금지 | 안전, 중복 실행 또는 호환성 문제 때문에 허용하지 않는 동작 | 구현 수정 전 출시 불가 |
| SHOULD / 권장 | 특별한 이유가 없다면 지켜야 하는 기본 설계 | 예외 이유와 대체 검증을 기록 |
| MAY / 선택 | 제품이나 기능 특성에 따라 적용 가능한 확장 | 적용 여부를 기능 계약에 명시 |
본문의 설명 문장도 31장의 요구사항 ID와 연결되면 규범 효력을 갖는다. 소스에 클래스나 메서드가 있다는 사실만으로 MUST 충족을 선언하지 않는다.
0.5 독자별 권장 읽기 순서
| 독자 | 먼저 읽을 장 | 얻어야 하는 답 |
|---|---|---|
| 기획/리더 | 1, 2, 24, 29, 30 | 무엇이 달라지고 기존 시스템을 어떻게 보호하는가 |
| 제품 시스템 앱 개발자 | 5, 18, 30 | 어떤 요청을 보내고 어떤 응답·콜백을 받아야 하는가 |
| DeviceAgent/기기 도메인 개발자 | 6~13, 16, 29 | 기능을 Task로 연결할 때 무엇을 구현해야 하는가 |
| Planner/Cloud 개발자 | 17, 20, 29 | 어떤 기기 사실과 capability를 사용하고 언제 재계획하는가 |
| QA/SQE | 11~15, 21, 25, 30, 31 | 실제 완료와 호환성을 어떤 증거로 판정하는가 |
| 운영/릴리스 | 19, 21~23, 25, 30 | 배포, 감시, 보안과 원복을 어떻게 수행하는가 |
0.6 사양과 구현의 우선순위
- 제품 안전 정책과 승인된 요구사항이 최우선이다.
- 이 사양서는 공개 계약과 인수 기준의 기준점이다.
- DeviceAgent 구현은 이 사양의 적합성을 코드와 시험 증거로 입증해야 한다.
- 사양과 구현이 다르면 차이를 요구사항 또는 결함으로 관리하고, 승인 없이 구현 동작을 사양으로 간주하지 않는다.
1. TaskManager란 무엇인가
TaskManager는 기기 기능을 호출하는 또 하나의 API 래퍼가 아니다. 여러 경로에서 들어온 기기 작업을 동일한 실행 단위와 상태 모델로 관리하는 DeviceAgent 내부 실행 제어 계층이다.
기존 구조에서는 호출자가 기능별 API를 직접 호출하고, 다음 작업의 시작 시점, 실패 대응, 실제 취소 여부와 완료 판정 콜백을 각각 구현해야 했다. 단일 명령에는 단순하지만 기능과 요청 경로가 늘수록 같은 제어 코드가 여러 앱과 서비스에 흩어진다.
TaskManager 도입 후 호출자는 다음을 구조화해 제출한다.
| 실행 계약이 답해야 하는 질문 | 대표 필드 |
|---|---|
| 무엇을 실행하는가? | taskMethod |
| 어디에서 온 요청인가? | source |
| 어느 실행 대기열을 사용하는가? | queue |
| 얼마나 우선하는가? | priority |
| 어떻게 결과를 반환하는가? | executionMode |
| 언제 실제 완료로 판단하는가? | completionTarget |
| 취소할 때 무엇을 실행하는가? | cancelMethod |
| 실패 후 무엇을 복구하는가? | compensationMethod |
| 여러 단계는 어떤 관계를 가지는가? | subTasks, trigger, conditions, parallelGroup |
TaskManager는 이 정보를 TaskRecord로 관리한다. 실제 실행은 기존 기기 도메인 실행기에 위임하고, 콜백과 상태 증거를 이용해 최종 상태를 확정한다.
1.1 한 문장 정의
TaskManager는 기존 DeviceAgent 기능을 Task와 Workflow로 표준화해 실행 순서, 상태, 자원 경쟁, 취소, 실패와 완료 증거를 공통으로 관리하는 SKIX namuh 제품 실행 프레임워크다.
1.2 무엇이 달라지는가
| 항목 | 도입 전 | 도입 후 |
|---|---|---|
| 기능 호출 | 호출자가 기기 도메인 API를 직접 호출 | submitTask 또는 submitWorkflow로 제출 |
| 순차 실행 | 호출자 코드에서 콜백을 직접 연결 | subTasks 순서와 단계 상태로 관리 |
| 병렬 실행 | 호출자가 스레드 생성과 결과 취합을 직접 구현 | parallelGroup과 실패 정책으로 표현 |
| 상태 | 기능별 상태값 또는 콜백 | TaskRecord의 공통 생명주기로 관리 |
| 경쟁 | 앱마다 별도 차단 로직 구현 | 대기열, 우선순위와 도메인 자원 정책으로 실행 허용 판정 |
| 취소 | 기능별 중지 API를 직접 찾아 호출 | Task 취소와 cancelMethod 연결 |
| 완료 | 메서드 반환을 실제 성공으로 오해하기 쉬움 | completionTarget에 해당하는 실제 완료 증거 대기 |
| 실패 | 자연어 메시지 또는 모듈별 오류 | 실패 사유, 복구 가능성과 권장 조치로 구조화 |
| 예약 | 예약 등록과 실제 실행이 섞이기 쉬움 | 예약 등록과 실행 시점의 허용 판정을 분리 |
| 관찰 | 여러 로그를 수동으로 조합 | Task, 대기열, Workflow와 단계 이벤트를 하나의 실행으로 연결 |
1.3 TaskManager가 하지 않는 일
- 자연어 원문, UI 선택과 시스템 이벤트를 분류하거나 제품 목표로 해석하지 않는다.
- 등록되지 않은 기능을 임의로 만들어 실행하지 않는다.
- 이동 경로, 청정 알고리즘, 보안 순찰 알고리즘을 대체하지 않는다.
- 센서 원시 데이터의 의미를 자체 추론하지 않는다.
- 모든 실패를 Cloud에 보내지 않는다.
- 제품의 반복 생활 스케줄 DB를 TaskManager 단기 지연 실행과 동일하게 취급하지 않는다.
- Android 플랫폼 공개 SDK인 것처럼 외부 일반 앱에 무제한 노출하지 않는다.
2. AOSP와 SKIX namuh 안에서의 위치
2.1 패키징 위치와 아키텍처 역할
DeviceAgent는 Android 빌드 관점에서 /system/priv-app에 배치되는 애플리케이션 패키지다. platform 인증서로 서명되고 android.uid.system을 사용하며, persistent 애플리케이션의 바운드 서비스로 실행된다. 따라서 일반 사용자 앱과 같은 제품 기능 화면이 아니라, 시스템 권한으로 여러 기기 기능을 연결하는 상시 실행 서비스다.
패키징 위치와 아키텍처 역할은 서로 다른 축이다. DeviceAgent는 앱 프로세스에 배치되지만, TaskManager와 공개 계약은 여러 제품 앱이 공통으로 사용하는 실행 기반을 제공한다. 이 역할을 SKIX namuh Product Framework Layer로 정의한다.
| 구분 | 실제 위치와 역할 |
|---|---|
| Android 패키징 | /system/priv-app의 com.sk.airbot.deviceagent 애플리케이션 |
| 권한과 생명주기 | platform 서명, android.uid.system, persistent 서비스, signature 권한 |
| 프로세스 | DeviceAgent 전용 앱 프로세스. system_server 내부가 아님 |
| 제품 아키텍처 | 제품 앱과 기기 도메인 사이의 SKIX namuh Product Framework Layer |
| 공개 진입점 | TaskManagerClient AAR, IDeviceControl Binder 계약과 MainApi |
| 실행 책임 | TaskManager Core, 실행기, 기존 기기 도메인과 완료 증거 연결 |
2.2 SKIX namuh Product Framework Layer
이 계층은 특정 화면이나 하나의 제품 기능을 구현하지 않는다. 제품 앱, IoT, PUI, 예약과 내부 서비스가 같은 기기 기능을 호출할 때 공통으로 필요한 권한, 실행 순서, 상태, 취소, 실패와 완료 계약을 제공한다.
| 계층 | 담당 범위 |
|---|---|
| SKIX 제품·시스템 앱 | 사용자 경험, 제품 시나리오와 실행 요청 생성 |
| TaskManagerClient AAR | 타입 기반 요청 생성, Binder 연결, 조회·취소와 콜백 API |
| DeviceAgent 공개 진입점 | 권한 확인, 기존 API 호환과 관리 경로 선택 |
| TaskManager Core | 실행 허용, 대기열, Workflow, 예약, 생명주기와 결과 관리 |
| 기기 도메인·완료 어댑터 | 기존 기능 호출과 실제 완료·실패 증거 연결 |
이 구조에서 DeviceAgent는 구현 형태로는 시스템 특권 앱 서비스이고, 제품 구조에서는 공통 실행 프레임워크다. 두 설명은 서로 다른 관점의 위치를 나타낸다.
2.3 AOSP Framework와의 경계
| 표현 | 이 사양에서의 의미 |
|---|---|
| Android Application Framework | frameworks/base, system_server, Android 공개·비공개 API와 시스템 서비스 |
| SKIX namuh Product Framework Layer | AOSP 메커니즘 위에서 여러 제품 앱과 기기 기능이 공유하는 제품 전용 실행 계층 |
| TaskManager Core | DeviceAgent 프로세스 내부의 실행 관리 런타임 |
| TaskManagerClient AAR | 제품 시스템 앱에 제공하는 타입 기반 Java 진입점 |
TaskManager는 AOSP SystemService가 아니다. frameworks/base나 system_server에 등록되지 않으며, AOSP의 Binder, 서비스 생명주기와 시스템 API를 사용해 DeviceAgent 프로세스 안에서 동작하는 SKIX namuh 제품 실행 프레임워크다. 따라서 Android 공개 SDK와 같은 범용 플랫폼 API가 아니라, 플랫폼 서명과 제품 권한 경계 안에서 사용하는 내부 프레임워크로 구분한다.
2.4 AOSP 구성요소 활용
| AOSP 구성요소 | TaskManager 사용 목적 |
|---|---|
| Binder/AIDL | 제품 시스템 앱과 DeviceAgent 사이 IPC |
| Bundle | 요청, 결과와 콜백을 전달하는 타입 기반 묶음 |
| 서비스 생명주기 | DeviceAgent 런타임 생명주기 |
Executor/Future |
대기열 실행, 시간 제한과 취소 |
AlarmManager/PendingIntent |
예약 Task의 실행 시점 진입 보조 |
BroadcastReceiver |
예약된 실행 허용 절차 재진입 |
SystemProperties |
런타임 활성화, 영속성과 모니터 설정 |
| 파일 I/O·JSON | Task·예약 상태 스냅숏 저장 |
3. 전체 구성요소
3.1 구성요소와 책임
| 구성요소 | 책임 | 대표 소스 |
|---|---|---|
| 공개 진입점 | 제어 메서드 처리와 기존 시스템 호환 경로 선택 | MainApi, TaskManager.handleControlMethod() |
| 별칭 변환기 | Cloud·기존 메서드 별칭을 표준 메서드로 변환 | TaskMethodAliasResolver |
| 입력 검증기 | 메서드별 입력 구조 검증 | TaskBundleValidator |
| 호출자 정책 | 요청 출처에 허용된 우선순위인지 확인 | TaskCallerPolicy |
| 상태 정책 | 현재 주 상태와 차단 상태 확인 | TaskManager.checkStateCondition() |
| 도메인 자원 정책 | 카메라, 이동 기반부와 전면 앱 세션의 충돌 차단 | TaskDomainResourcePolicy |
| 시스템 자원 정책 | CPU, RAM과 발열 상태를 바탕으로 실행 허용 판정 | TaskResourcePolicy |
| 기기 도메인 정책 | LLM, 배터리, AMR, 개인정보 보호, 오류와 현재 동작을 바탕으로 최종 실행 판정 | CmdPolicyManager, StateManager, 도메인별 manager |
| 실행 정책 목록 | 실행 방식, 대기열, 우선순위, 시간 제한, 재시도, 취소와 보상 동작 결정 | TaskPolicyRegistry |
| 런타임 Core | 실행 기록, 대기열, Workflow, 예약, 조회와 제어 | TaskManager |
| 실행기 등록부 | taskMethod를 실행 어댑터에 연결 |
TaskExecutorRegistry, TaskExecutorBootstrap |
| 도메인 어댑터 | 표준 요청을 기존 도메인 호출 구조로 변환 | MovementTaskExecutor 등 |
| 완료 상태 저장소 | 도메인 콜백을 공통 완료 조건에 맞게 저장 | TaskCompletionStateStore |
| 완료 감시기 | 대상·공간·시점·안정화 조건이 충족될 때까지 대기 | TaskCompletionWatcher |
| 실패 사유 계약 | 하위 오류를 구조화된 실패 사유로 정규화 | TaskReasonContract |
| 컨텍스트 제공자 | Planner와 운영 도구에 기기 상태 스냅숏 제공 | DevicePlanningContextProvider |
| 이벤트·모니터 | Task 이벤트 전달, 연결 상태 보고와 명령 조회 | TaskMonitorReporter, TaskMonitorCommandPoller |
| Client AAR | 타입 기반 요청 생성기, 조회, 취소와 콜백 API 제공 | TaskManagerClient |
3.1.1 처음 보는 사람을 위한 구성요소 지도
| 역할 묶음 | 구성요소 | 쉬운 한 줄 설명 |
|---|---|---|
| 접수 | 공개 진입점 | PUI, 앱, IoT, Cloud 요청을 받아 기존 실행과 Task 실행 중 어느 경로로 보낼지 결정한다. |
| 형식 변환 | 별칭 변환기, 도메인 어댑터 | 서로 다른 기능 이름과 입력값을 표준 Task 형식과 기존 도메인 형식 사이에서 변환한다. |
| 실행 전 심사 | 입력 검증기, 호출자·상태·자원 정책 | 요청이 올바르고 현재 기기에서 안전하게 시작할 수 있는지 확인한다. |
| 실행 조정 | 실행 정책 목록, 런타임 Core | 여러 작업의 순서, 우선순위, 대기열, 시간 제한과 병렬 실행을 관리한다. |
| 작업 배정 | 실행기 등록부 | taskMethod에 맞는 DeviceAgent 기능 담당자를 찾아 연결한다. |
| 완료 확인 | 완료 상태 저장소, 완료 감시기 | 함수 호출이 아니라 실제 이동·청정·재생·세션 종료를 확인한다. |
| 실패 기록 | 실패 사유 계약 | 실패 원인을 공통 코드와 설명으로 바꿔 안내와 복구 판단에 사용한다. |
| 상태 제공 | 컨텍스트 제공자, 이벤트·모니터 | 현재 기기 상태와 Task 진행 상황을 상위 서비스와 운영 화면에 제공한다. |
| 외부 사용 창구 | Client AAR | 다른 제품 시스템 앱이 내부 구현을 몰라도 표준 Task API를 호출하게 한다. |
이 구조에서 TaskManager는 실제 기기 기능을 수행하지 않는다. 요청 접수, 실행 순서, 상태와 완료를 관리하는 실행 조정자다. 이동과 청정 같은 실제 작업은 기존 기기 도메인이 계속 수행한다.
3.2 소유권 경계
책임 경계는 0.2 가장 중요한 경계의 구조도를 따른다. Planner는 목표와 계획, TaskManager는 실행 생명주기, 기기 도메인은 실제 동작과 물리 상태를 소유한다. Monitor는 이 상태를 표시하고 허용된 제어를 전달하지만, Task의 최종 상태를 임의로 확정하지 않는다.
3.3 스레드와 대기열의 기본 모델
- 대기열별 실행기는 같은 대기열 안의 작업 순서를 관리한다.
- 우선순위가 높은 작업을 먼저 실행하고, 우선순위가 같으면 제출 순서를 유지한다.
- 상위 Workflow는
workflow대기열에서 전체 흐름을 관리한다. - 병렬 하위 단계는 각 도메인 대기열에서 실행하며, 상위 Workflow가 결과를 취합한다.
runningManagedTask스레드 로컬 보호 장치는 TaskManager가 기존MainApi를 다시 호출할 때 대기열에 재귀 진입하는 것을 막는다.- 기본 대기열 용량은
64, 실행 기록 보존 상한은100이다.
제2부 · 요청 계약과 실행 허용 — 4~7장은 요청이 들어오는 경로, 공개 API, 실행 허용 판정과 정책을 설명한다.