DeviceAgent TaskManager 기준 사양서
NoneTaskManager의 전체 기준을 빠르게 이해하고, 역할에 맞는 상세 사양으로 바로 이동하기 위한 문서 허브다. 규범 내용은 주제별 상세 페이지에 나누고 이 페이지는 정의, 핵심 원칙과 읽기 경로만 제공한다.
TaskManager는 여러 요청 경로에서 들어오는 기기 동작을 Task로 접수하고, 실행 가능 여부·순서·상태·완료·취소·실패를 공통 규칙으로 관리하는 DeviceAgent 내부 실행 프레임워크다.
5분 안에 이해하기
| 핵심 원칙 | 의미 |
|---|---|
| 기능은 그대로 | 이동·청정·화면·TTS 같은 실제 기능과 안전 정책은 기존 기기 도메인이 계속 소유한다. |
| 실행은 공통 관리 | 요청 출처와 관계없이 Task와 Workflow로 접수해 queue, 우선순위와 자원 경쟁을 관리한다. |
| 접수와 완료 분리 | accepted=true는 시작일 뿐이며 실제 callback과 상태 증거가 있어야 완료된다. |
| 기존 경로와 공존 | 모든 MQTT나 앱 API를 한 번에 바꾸지 않고 관리가 필요한 요청부터 점진적으로 전환한다. |
Task와 Workflow
| 단위 | 의미 | 대표 예시 |
|---|---|---|
| Task | 독립적으로 접수·실행·취소·완료 판정할 수 있는 하나의 작업 | 지정 위치 이동, 청정 시작, 화면 전환 |
| Workflow | Task의 순서, 의존관계, 조건, 지연과 실패 정책을 가진 실행 묶음 | 이동 완료 → 청정 → 종료 확인 → 복귀 |
| Completion Evidence | 다음 단계나 최종 완료를 허용하는 실제 상태 증거 | movement.arrived, cleaning.stopped |
TaskManager가 확장하는 제품 기능
TaskManager가 새 기기 기능이나 사용자 목표를 직접 만들지는 않는다. 기존 DeviceAgent 기능을 재사용 가능한 Task로 연결하고 실행 계약을 공통화해, 앱·IoT·예약·내부 서비스와 선택적 상위 Planner가 더 복잡한 제품 시나리오를 안전하게 구성할 수 있게 한다.
| 확장 가능한 기능 | TaskManager가 제공하는 기반 | 구현·출시 조건 |
|---|---|---|
| 복합 기기 시나리오 | 이동 → 청정 → 복귀처럼 여러 Task의 순서·의존관계·실패를 하나의 Workflow로 관리한다. | 현재 기반. 각 단계의 실행기와 실제 완료 증거가 연결돼야 한다. |
| 시간·조건 기반 실행 | “30분 뒤 작은방 청정”, “이동 완료 30초 후 화면 전환”을 예약 Task와 after_step 지연으로 표현한다. |
현재 기반. 출시 형상에서 Alarm, 재부팅 복원과 실행 시점의 재검증이 필요하다. |
| 장시간 사용자 참여 작업 | Vital Sign, Security, Welcome과 앱 세션을 시작 응답이 아니라 완료·취소·시간 초과까지 추적한다. | 부분 연동. 도메인별 terminal callback과 취소 계약을 완성해야 한다. |
| 중단·실패 후 안전한 수렴 | PUI 취소, 저전력, 이동 실패를 reason code로 남기고 중지·재시도·보상 동작을 선택한다. | 부분 연동. 기능별 안전 정책과 보상 가능 범위를 검증해야 한다. |
| 채널 간 동일한 진행 관리 | PUI·앱·IoT·예약·Agent가 같은 Task ID, 상태, 취소와 결과 계약을 사용한다. | 점진 전환. 기존 direct 경로는 유지하고 관리가 필요한 명령부터 전환한다. |
| 상태 기반 동적 Workflow | 선택적 Planner가 기기 상태와 capability로 단계를 구성하고 TaskManager가 실행 가능성·순서·완료를 결정적으로 관리한다. | 목표 확장. capability catalog, 최신 context, 동의 정책과 재계획 경계를 함께 검증해야 한다. |
외부 실행 관리 구조에서 확인되는 공통 원리
장시간·복합 작업을 단순 함수 호출과 분리해 관리하는 구조는 Android, 로보틱스와 클라우드 Workflow에서도 확인된다. 아래 사례는 SKIX TaskManager와 동일한 제품이 아니라, 상태·의존관계·진행·취소·실패·복원을 별도 실행 계층이 소유하는 이유를 보여 주는 설계 참조다.
| 공식 플랫폼 | 확인되는 실행 관리 원리 | SKIX에서의 적용과 경계 |
|---|---|---|
| Android WorkManager | 제약 충족 후 영속 작업 실행, 상태 관찰과 작업 Chain을 제공한다. | 예약·의존·상태·재시도 원리를 참고한다. AndroidX WorkManager는 기기 물리 완료와 DeviceAgent 안전 정책을 대신하지 않는다. |
| ROS 2 Actions · Nav2 | 장시간 Goal의 수락·진행·취소·결과와 단계 실패 후 contextual recovery를 분리한다. | 이동·청정처럼 오래 걸리는 Task의 상태와 완료 증거, 복구 경계에 대응한다. ROS 통신 런타임을 도입한다는 의미는 아니다. |
| NVIDIA Isaac Missions | 로봇 Mission을 Task tree로 구성하고 sequence·selector·route·action 상태를 추적한다. | Workflow 단계 조합과 실패 분기에 대응한다. 현재 SKIX 범위는 단일 기기 실행이며 Fleet 배정은 포함하지 않는다. |
| AWS Step Functions | 응답, 장기 Job 대기와 callback 대기를 구분해 Workflow를 이어 간다. | ACK와 실제 완료 callback을 분리하는 원리에 대응한다. Cloud state machine이 기기 내부 실행 권한을 소유하지는 않는다. |
| Microsoft Durable Task | 상태 영속성, 자동 복구와 분산 조정을 실행 프레임워크가 관리한다. | 예약 복원과 장기 Workflow 이력의 확장 방향에 대응한다. 현재 실행 중 Workflow 전체 replay는 보강 대상이다. |
구조 예시: ROS 2 Actions와 SKIX TaskManager
ROS 2 Actions는 장시간 Goal마다 UUID와 상태를 부여하고 Action Server가 수락·거절, 진행 feedback, 취소와 최종 result를 관리한다. 이 생명주기는 SKIX의 Task ID, Admission, 진행 Event, 취소와 Completion Evidence에 직접 대응한다.
Isaac ROS Missions도 ROS 2 패키지와 Mission Client를 사용하지만, 공식 Missions 흐름은 여러 Task를 mission_tree로 묶어 VDA5050 Order로 전달하는 상위 Mission 계층이다. 따라서 아래 그림은 TaskManager Core의 직접 대응은 ROS 2 Actions, 여러 Task를 묶는 상위 활용 사례는 Isaac Missions로 구분한다.
- ROS 2의
send_goal → feedback/status → result는 SKIX의submitTask → event/status → Completion Evidence와 대응한다. - ROS 2의
cancel_goal과 Goal terminal state는 SKIX의 Task 취소와COMPLETED/FAILED/CANCELLED에 대응한다. - SKIX는 여기에 공통 Queue, Priority, Workflow, Scheduler, DeviceAgent 정책과 기존 API 호환성을 추가로 소유한다.
빠른 결론
- 기능 호출 성공은 Task 완료가 아니다.
- TaskManager는 기존 기능과 안전 정책을 대체하지 않는다.
- 복합 실행은 검증된 Task의 Workflow 조합으로 표현한다.
- 다음 단계는 선행 Task의 실제 완료 증거가 있어야 진행한다.
- Planner는 선택 연동이며 TaskManager의 결정적 실행 책임과 분리한다.
실행 구조 변화
| 구분 | 실행 구조 |
|---|---|
| AS-IS | 앱·PUI·IoT·예약·내부 서비스가 기능을 직접 호출하고, 복합 기능마다 전용 콜백과 상태 변수를 다시 작성한다. |
| TO-BE | 호출자·제품 시나리오가 사전 정의 Workflow를 제출하거나 선택적 Planner가 동적으로 구성하고, 검증된 Task를 순차·병렬·조건·대기로 조립한다. |
TaskManager는 요청 경로와 무관한 Task·Workflow 실행 계약을 제공한다. 어느 경로든 실제 실행은 같은 TaskManager 계약을 사용하며, 기존 기기 도메인이 기능과 안전 정책을 계속 소유한다.
역할별 시작점
| 독자 | 먼저 볼 페이지 | 확인할 내용 |
|---|---|---|
| 기획·리더 | 개념과 아키텍처 | 무엇이 달라지고 TaskManager가 어디까지 책임지는지 확인한다. |
| 앱·IoT 호출자 | 요청, API와 실행 정책 | 어떤 요청을 보내고 기본값과 실행 정책이 어떻게 적용되는지 확인한다. |
| DeviceAgent 개발 | 생명주기와 Workflow | Task 생명주기, Workflow, 완료 증거와 취소 계약을 확인한다. |
| QA·운영 | 운영, 보안과 검증 | 관측성, 실패, 보안, 실기기 인수 기준과 출시 판정을 확인한다. |
전체 사양 지도
| 순서 | 상세 사양 | 범위 | 기존 장 |
|---|---|---|---|
| 01 | 개념과 아키텍처 | TaskManager의 책임 경계, AOSP와 SKIX namuh 안에서의 위치, 내부 구성요소를 정의한다. | 0, 1, 2, 3장 |
| 02 | 요청, API와 실행 정책 | 요청 유입부터 공개 API, 기본값, 검증, 호출자·기기·자원 정책까지 실행 전 경계를 정의한다. | 4, 5, 6, 7장 |
| 03 | 생명주기와 Workflow | TaskRecord, 실행 모드, Workflow, 완료 증거, 취소, 실패, 이벤트와 예약 실행을 정의한다. | 8, 9, 10, 11, 12, 13, 14, 15장 |
| 04 | 도메인 기능과 기기 컨텍스트 | 기존 DeviceAgent 기능을 Task 실행기로 연결하는 방법과 계획에 제공할 기기 상태 계약을 정의한다. | 16, 17장 |
| 05 | 외부 연동과 기존 시스템 호환 | AAR, IoT/MQTT, 선택적 Planner와 기존 direct 실행 경로의 점진 전환 방식을 정의한다. | 18, 19, 20, 30장 |
| 06 | 운영, 보안과 검증 | 관측성, 영속성, 용량, 보안, 실패 UX, 인수 시험과 변경 절차를 정의한다. | 21, 22, 23, 24, 25, 26, 27, 28장 |
| 07 | Core와 Task 규범 | TaskManager Core, 관리 대상 Task, 기기 상태와 도메인별 연동의 필수 규범을 정의한다. | 29장 |
| 08 | 적합성, 용어와 설계 근거 | 요구사항 ID, 적합성 수준, 추적 사슬, 용어와 외부 실행 제어 설계 근거를 제공한다. | 31, 32, 33, 34장 |
상태 표기
| 표기 | 판정 기준 |
|---|---|
| 현재 구현 | 소스에 실행 경로가 존재한다. |
| 코드 검증 | 단위 테스트나 빌드로 확인했다. |
| 실기기 확인 | 특정 기기와 APK 조합에서 실제 증거를 확인했다. |
| 목표 사양 | 다음 단계로 합의했으며 현재 구현과 구분한다. |
기존 장 번호 바로가기
기존 URL의 #0부터 #34까지는 상세 사양의 같은 장으로 자동 연결된다. 아래 목록에서도 장을 직접 선택할 수 있다.
| 장 | 상세 사양 |
|---|---|
| 00 | 0. 문서 판독 규칙 |
| 01 | 1. TaskManager란 무엇인가 |
| 02 | 2. AOSP와 SKIX namuh 안에서의 위치 |
| 03 | 3. 전체 구성요소 |
| 04 | 4. 요청 유입과 유형 분류 |
| 05 | 5. 공개 제어 API |
| 06 | 6. 실행 허용 절차 |
| 07 | 7. 실행 정책 목록 |
| 08 | 8. TaskRecord와 생명주기 |
| 09 | 9. 실행 런타임 |
| 10 | 10. Workflow 런타임 |
| 11 | 11. 완료 증거 |
| 12 | 12. 취소와 보상 동작 |
| 13 | 13. 실패 사유 계약 |
| 14 | 14. 이벤트 계약 |
| 15 | 15. 예약 실행 |
| 16 | 16. 도메인 기능과 실행기 연결 |
| 17 | 17. 기기 계획 컨텍스트 |
| 18 | 18. TaskManagerClient AAR |
| 19 | 19. IoT/MQTT와 Task Monitor 계약 |
| 20 | 20. 선택 연동: Cloud Planner와 A2A |
| 21 | 21. 모니터링과 관측성 |
| 22 | 22. 영속성·용량·런타임 설정 |
| 23 | 23. 보안과 권한 |
| 24 | 24. 실패 처리와 사용자 UX |
| 25 | 25. 테스트 전략과 인수 기준 |
| 26 | 26. 현재 구현의 한계와 목표 확장 |
| 27 | 27. 구현 변경 절차 |
| 28 | 28. 참조 규격과 문서 색인 |
| 29 | 29. TaskManager Core, 관리 대상 Task와 기기 연동 규범 |
| 30 | 30. 기존 시스템 호환성과 점진적 전환 사양 |
| 31 | 31. 규범 요구사항과 적합성 판정 |
| 32 | 32. 용어집 |
| 33 | 33. 최종 설계 원칙 |
| 34 | 34. 관련 문서 |
전체 원문과 관련 문서
- 분할 전 전체 사양 보존본 — 전체 내용을 한 파일에서 검색해야 할 때만 사용한다.
- AS-IS / TO-BE 가이드 — 도입 전후의 차이를 먼저 이해한다.
- Source-Level Implementation Guide — 클래스와 구현 변경 지점을 확인한다.
- TaskManagerClient AAR API — 시스템 앱 호출 계약을 확인한다.
- MQTT Task Contract — IoT 요청과 callback 계약을 확인한다.