← Docs hub

SKIX 프레임워크 구성요소 상세 지도

공통 작업 관리와 도메인 실행의 폴더 경계

TaskManager는 AMR·Cleaning보다 넓은 공통 작업 관리 책임이다. 폴더의 물리적 부모가 아니라 모든 도메인이 사용하는 실행권·Task 상태의 공통 소유자라는 뜻이다.

Task 상태·실행 배정은 공통 실행 계층, 장치 명령·도메인 상태·정지 절차는 각 도메인에 둔다. 현재 AMR–Cleaning 직접 협력은 유지되며, 폴더 분리가 범용 도메인 조정자 구현을 의미하지 않는다. 클래스명·공개 계약·동작은 유지하고 내부 package/import와 대응 테스트 경로를 함께 옮긴다.

이 문서에서 먼저 이해할 것

이 프레임워크는 앱의 요청을 받아, 실행 가능 여부를 확인하고, 각 기능의 실행과 결과를 일관되게 관리하는 기반이다. 주행·청소·음성 같은 실제 기능을 한 서비스에 다시 모으는 작업이 아니다. 공통 규칙은 공통 서비스가 맡고, 기능별 상태와 사양은 해당 도메인이 맡으며, 실제 장치 동작은 연결된 실행 구현이 맡는다.

처음 읽을 때는 아래 순서로 본다. 상세 구조도는 없애지 않고, 각 그림이 답하는 질문을 구분했다.

상태값도 담당자가 다르다

예를 들어 LLM 서비스가 READY, AI Agent 연결이 끊김, 발화 Task는 결과 확인 중인 상황은 서로 모순이 아니다. 각각 서비스 자체, 외부 연결, 개별 작업에 대한 상태이기 때문이다. 이들을 하나의 “LLM 상태”로 합치면 재연결·취소·늦은 결과 처리에서 잘못된 판단을 하게 된다.

이 표는 책임을 설명한다. 모든 도메인의 장치 상태 연동이 이미 완료됐다는 뜻은 아니다.

AI Agent와 프레임워크가 헷갈린다면: 실행 주체·작업 관리·폴더 위치 해설을 먼저 읽는다. TTS의 실제 실행은 AI Agent가 담당하고, 프레임워크 LLM 도메인은 연동을 관리한다. TtsManagedHost는 내부 구현이며 실제 생산자 연결은 아직 이관 대상이다. 아래 기존 전체 그림은 그대로 유지한다.

연결·관측 확대: 제공자 재연결과 TTS 순서 보존. 아래 전체 지도는 유지하고, control/capability → domain/llm/completion → execution/task의 협력을 별도로 펼친다.

최신 기반 구현: 자원·기능·작업 Runtime 상세. Resource·Capability·Task를 포함한 실제 7개 서비스 조립과 장치 연결의 남은 경계를 함께 본다.

전체 모듈의 역할부터 한눈에 보기

크게 열기 · Mermaid 원본

상자마다 무슨 일을 맡는지, 무엇을 받고 무엇을 돌려주는지를 적었다. 공통 모듈은 모든 기능에 필요한 상태·판단·작업 기반이고, 제품 도메인은 자기 기능의 책임자다. 아래 Agent/provider는 실제 실행 구현이다. 이 구분은 논리 모듈이며 APK·프로세스의 개수와 다르다.

전체 연결 → 15개 도메인별 책임 → 소스 폴더와 실제 구동 위치 순서로 읽는 상세 구조도다. 기존 Atlas를 없애거나 요약 그림으로 대체하지 않고, 구성요소를 더 자세히 펼친다. 모든 그림은 확대 가능한 SVG이며 핵심 식별자 아래에 한국어 역할과 소유 폴더를 표시했다.

먼저 구분할 세 가지

파랑은 소스가 존재함, 황색 점선은 목표 연결 또는 소유 폴더 골격, 보라는 기존 구현이다. 파랑도 제품 동작 완료를 뜻하지 않는다. 특히 오른쪽 provider 열은 연결 방향이지 현재 결선 완료 목록이 아니다.

폴더 구조로 읽기 — 어느 코드를 어디에 두는가

폴더 구조 SVG 원본 크게 열기 · Mermaid 원본

왼쪽 폴더 → 가운데 포함 모듈 → 오른쪽 역할 순서로 한 행씩 읽는다. services/core 행 아래의 runtime, entrypoint, control, execution, domain, integration은 java/com/sk/airbot/frameworkservice/server/ 아래의 패키지다. 그림의 가로선은 소속 관계이며 실행 호출선이 아니다. services/core/.../runtime은 순수 Java 서비스 조립부, services/runtime/java는 Android 의존 진입부다.

루트부터 따라가는 읽기 순서

1. skix-framework/base/core/ — 사용하는 쪽의 계약. 앱이 호출하는 Manager, 공개 모델, 도메인별 Constants와 AIDL을 둔다. 여기서 모터를 직접 제어하거나 도메인 상태를 소유하지 않는다.
2. base/services/core/ — 서버의 판단과 상태. 아래 트리의 server/가 실제 Java 패키지 루트다. runtime/이 형제 폴더의 서비스를 조립하며, domain/을 자기 하위로 소유하는 구조는 아니다.
3. base/services/runtime/ — Android와 만나는 진입부. Binder 호출자를 확인하고 서버 접수 로직으로 전달한다. 위의 server/runtime/과 이름은 비슷하지만 책임과 폴더가 다르다.
4. base/adapters/, compatibility/ — 실행 연결과 기존 IPC 변환. 도메인의 판단을 Agent·MCU·HAL 같은 실행 구현에 연결한다. 연결 경계가 존재하는 것과 장치 결선 완료는 구분한다.
5. apps/ — 현재 컴파일·패키징 호스트. SDK와 서버 프로젝트가 base/ 소스를 직접 참조한다. 프레임워크 소스를 앱 아래에 다시 복제하지 않는다.

skix-framework/base/
├ core/                         공개 Manager · 모델 · Constants · AIDL
├ services/
│ ├ core/java/com/sk/airbot/frameworkservice/server/
│ │ ├ runtime/                  서비스 생성·등록·시작·중지
│ │ ├ entrypoint/               권한·요청 접수·엔드포인트 조회
│ │ ├ control/                  lifecycle · state · policy · resource · capability
│ │ ├ execution/                task · workflow · scheduler · evidence
│ │ ├ domain/                   amr · iot · llm · vision · cleaning · airquality 등
│ │ ├ integration/              실행 구현으로 연결할 서버 내부 경계
│ │ └ legacy/                   기존 구현 이행 경계
│ ├ runtime/java/               Android Binder·호출자 확인
│ ├ systemserver/               AOSP 시작 연결의 목표 경계
│ └ tests/                      서버 패키지에 대응하는 테스트
├ adapters/                     Agent·ROS 2·MCU·HAL 연결 경계
├ compatibility/                기존 IPC 호환 변환
├ data/etc/                     제품 설정·권한 배치 경계
└ api/                          공개 API 서명 검토 경계

기능을 수정할 때 찾는 폴더

TTS의 완료 처리처럼 여러 폴더가 협력하는 사례는 TTS 폴더별 책임·작업 연결 확대도에서 별도로 볼 수 있다. 전체 구조를 유지한 채 domain → task → evidence 책임을 확대하며, 기존 장치 콜백의 미연결 경계도 표시한다.

예를 들어 TTS 완료 처리를 찾는다면 공개 API 전체를 뒤지는 대신 services/core/.../server/domain/llm/completion/에서 재생 상태 해석을 먼저 본다. 결과가 어느 작업의 것인지 확인하는 부분은 execution/task/completion/, 작업 상태 변경은 execution/task/, 근거 보관은 execution/evidence/다. 한 기능이 여러 폴더를 거치는 이유는 같은 코드를 분산하기 위해서가 아니라, 각 상태의 책임자를 분리하기 위해서다. 대응 테스트는 base/services/tests/src/ 아래 같은 Java 패키지 경로에 둔다.

공개 Manager와 서버 ManagerService의 이름·개수가 반드시 1:1인 것은 아니다. 기존 공개 API 호환을 유지하면서 서버 책임을 도메인별로 나누는 중이다. 위 표는 코드 위치 안내이며, 모든 경로의 실제 기기 연결이 끝났다는 뜻은 아니다.

폴더 규칙은 어떻게 지키는가

tools/verify-skix-framework-tree.sh가 소스 위치와 빌드 참조를 검사한다. 2026-09-08에는 Java에만 적용되던 패키지·경로 검사를 base/core/aidl/에도 적용하고, SDK 호스트의 src/main/aidl/com/sk/airbot/framework/에 새 프레임워크 계약이 되돌아오는 경우를 거부하도록 보완했다. 기존 devicecontrol 등 별도 IPC 계약은 호환 이행을 위해 앱에 남겨 둔다. 즉 새 프레임워크 계약은 base, 기존 계약은 이행 대상이라는 구분이며, 기존 계약을 모두 삭제한 것은 아니다.

격리된 폴더 fixture에서 잘못된 AIDL 패키지와 앱 소유 복제본을 각각 거부하고, 정상 계약·기존 IPC는 허용하는 회귀 검사를 통과했다. 이 검사는 명시된 소스 루트의 구조 검사다. 모든 Gradle variant·사용자 정의 sourceSet을 해석하거나 AOSP 빌드·실기기 연결을 증명하지는 않는다.

호출 흐름과 폴더 소속은 다른 그림이다

폴더 SVG의 가로선은 어디에 속하는지를 보여준다. 실행 목표 흐름은 core/의 Manager → Android Binder 진입 → entrypoint/ 접수 → Task·Policy·도메인 서비스 협력 → 실행 어댑터 → Agent·장치 → 상태·근거 환류다. 명령 특성에 따라 조회 경로와 Task 실행 경로는 달라지며, 아직 전체 왕복이 결선된 상태는 아니다. 아래 전체 연결 SVG와 함께 읽으면 저장 위치와 실행 관계를 혼동하지 않을 수 있다.

모듈 역할 사전 — 이름에서 실제 소스까지

상위 지능 서비스는 상황 해석·계획 생성·수정을 맡는 외부 호출자의 역할명이다. 특정 제품명·프로토콜명이나 프레임워크의 필수 내부 모듈 이름이 아니다.

그림은 배치, 아래 표는 책임과 협력 관계를 설명한다. 담당 업무는 목표 책임을 포함한다. 경로가 있다는 이유만으로 표의 동작이 모두 구현되었다고 해석하지 않는다. 서버 경로의 공통 앞부분은 skix-framework/base/services/core/java/com/sk/airbot/frameworkservice/server/다.

공통 기반: 모든 기능이 함께 쓰는 모듈

역할 그림의 공통 9개는 Runtime을 위쪽 기반 영역에 별도로 놓은 수다. 위 표는 Runtime까지 포함한 공통 기반 10개다. 제품 도메인은 15개이며 Streaming은 별도 실행 경계다. 이는 논리 책임의 집계이지 Gradle 모듈·APK·프로세스 수가 아니다.

제품 도메인: 기능의 의미와 상태를 소유하는 15개 서비스

각 행의 서버 소스는 domain/<폴더>/<클래스>.java에 있다. 15개 모두 별도 클래스와 공통 생명주기 계약을 갖지만, 기본 Runtime에 모두 조립되거나 기존 장치 동작 전체가 이관된 상태는 아니다. 아래 협력 관계도 목표 책임 분담이다.

모듈을 연결하는 구조: API·진입부·실행 어댑터

아래 경로는 저장소 루트 기준이다. 이 구조까지 포함해야 앱에서 장치까지 전체가 보인다.

한 요청에서 역할을 따라가기: 주행 중 틸팅 조건

다음은 목표 협력 흐름이다. 현재 전체 경로가 실기기에서 연결되었다는 의미는 아니다.

1. 앱/상위 지능 서비스가 이동을 요청한다. Manager는 호출 창구이며 주행 상태의 소유자가 아니다.
2. Task가 작업의 접수와 진행을 관리한다. AMR은 주행의 의미·상태·요구 조건을 제공한다.
3. Policy가 “주행 중 틸팅 다운” 같은 필수 조건을 검사한다. Resource는 관련 구동 자원의 충돌을 조정한다.
4. 해당 도메인과 장치 실행 구현이 동작하고 관측·진행 결과를 반환한다. 전송 성공을 물리 완료로 취급하지 않는다.
5. State는 현재 상태, Task는 작업 진행 상태, Evidence는 관측·완료 근거를 제공한다.
6. 상위 지능 서비스는 이 정보를 보고 계획을 수정한다. 프레임워크는 필수 정책 위반을 이유와 함께 거부하는 실행 경계를 맡는다.

서비스 상태와 작업 상태도 다르다. 서비스의 READY는 요청을 받을 준비 상태이고, Task의 진행·종료는 개별 작업의 상태다. 서비스가 중지됐다고 장치가 안전 정지하거나 작업이 물리적으로 완료되었다고 자동 판정해서는 안 된다. 이 연결은 후속 실행·복구 계약에서 검증해야 한다.

1. 전체 프레임워크를 위에서 아래로 보기

전체 화면으로 확대 · Mermaid 원본

앱과 상위 지능 서비스는 SDK를 통해 요청한다. Android 진입부는 호출자의 신원을 확인하고, 서버 접수부는 권한과 요청 범위를 검사한다. Task는 실행 상태를 관리하고, 도메인 서비스는 자기 기능의 의미와 상태를 소유한다. 실제 동작은 기존 Agent 또는 앞으로 분리할 provider가 수행한다.

반대 방향으로는 장치 관측과 진행 상황이 들어온다. 이것을 도메인 상태, Task 결과, 실행 근거로 정리해 상위에 제공한다. Experience 상황을 해석하고 새 계획을 만드는 역할은 상위 지능 서비스에 남긴다. 프레임워크는 중요한 정책 위반을 거부하고 이유를 돌려주며, 계획 수정이 가능한 실행 계약을 제공하는 방향이다.

Runtime 내부 공통 구성요소

2. 도메인을 하나도 한 상자로 뭉치지 않고 펼쳐 보기

전체 화면으로 확대 · Mermaid 원본

AMR, IoT, LLM, MCU, Vision, Update, Pairing, EventAsset, Cleaning, AirQuality, Power, UI, System, Diagnostics, Security가 각각 별도 서비스 클래스다. ProductDomainManagerServices.createAll()에서 15개를 생성할 수 있지만 기본 Runtime 구성에 자동 등록되어 돌아가는 상태는 아니다.

Cleaning은 청정 운전, AirQuality는 공기질 관측, UI는 화면 세션을 소유한다. 팬을 사용하는 상황에서 공기질과 청정이 협력하더라도 하나의 공통 서비스에 책임을 합치지 않는다. 주행과 틸팅처럼 도메인을 가로지르는 제약은 각 도메인이 상태·요구 조건을 제공하고 공통 Policy/Resource 경계에서 조정하는 방향이다.

왼쪽은 공개 API의 역할이다. 15개 모두 새 SkixXManager 구현이 완성되었다는 뜻은 아니다. 현재 SDK에는 SkixAirCleanerManager, SkixCameraManager, SkixMapManager, SkixLcdManager 등 기존 API가 있고, 이 API를 새 도메인 책임으로 연결하는 이행 작업이 필요하다. 다수 서버 클래스도 아직 생명주기 기반 골격이다.

3. 폴더가 어디에 있고, 무엇이 빌드되며, 어디서 시작되는가

전체 화면으로 확대 · Mermaid 원본

skix-framework/base/가 소스의 소유 루트다. apps/AirbotSdkProject와 apps/SkixFrameworkService는 현재 그 소스를 참조하는 빌드 호스트이며, 프레임워크 소스를 다시 앱 폴더에 복제하지 않는다.

skix-framework/base/
├── core/java/                  공개 API·Manager·모델
├── core/aidl/                  프로세스 간 계약
├── core/tests/src/             SDK 계약 테스트
├── services/core/java/         Android 전송과 분리된 서버 로직
│   └── …/server/
│       ├── entrypoint/         접수·권한·엔드포인트 등록
│       ├── control/            생명주기·상태·정책·자원·기능
│       ├── execution/          Task·Workflow·예약·근거
│       ├── domain/             15개 제품 도메인별 소유권
│       └── runtime/            서비스 조립 지점
├── services/runtime/java/      Android Binder·호출자 어댑터
├── services/systemserver/      AOSP 시작·권한 연결 목표 경계
├── services/tests/src/         서버 계약 테스트
├── compatibility/java/         기존 IPC·Bundle 계약
├── adapters/                   장치별 실행 연결 경계
├── data/etc/                   제품 설정 목표 경계
└── api/                        공개 API 관리 목표 경계

현재와 목표를 혼동하면 안 되는 부분

• createBaseRuntime()은 현재 Runtime + State + Evidence + Policy + Resource + Capability + Task를 구성한다. 전체 도메인·장치 실행기 결선 완료는 아니다.
• SkixFrameworkService의 Manifest에는 비공개 SkixFrameworkHostService(exported=false) 선언이 있다. 내부 Runtime 시작 연결과 제품 자동 부팅·외부 Binder 공개는 다르며, 후자는 미검증이다. 현재 호스트 연결 범위.
• services/systemserver/는 README 경계이며 실제 SKIX SystemService 구현이 아니다.
• Android.bp의 filegroup은 소스 묶음이다. 제품 이미지 포함이나 자동 시작을 보장하지 않는다.
• 목표는 얇은 AOSP 시작·권한 서비스와 격리 Runtime의 하이브리드다. 제품 로직 전부를 system_server에 넣지 않는다.

코드 근거와 다음 연결 작업

소스 기준은 MR7 refactor/blueprint-foundation이다. 서버 경로 접두사는 skix-framework/base/services/core/java/com/sk/airbot/frameworkservice/server/다.

후속 구현은 시작 호스트 → 전체 서비스 조립 → 도메인별 provider 연결 → MR6 TaskManager 행동 이식 → 정책·상태·중간 수정·실제 완료의 통합 검증 순으로 이어져야 한다. 도메인 클래스 생성만으로 완료 처리하지 않는다.

공식 설계 참고

AOSP 전체 계층 구조의 API·시스템 서비스·HAL 구분과 Binder 구조의 클라이언트/서버 경계를 참고했다. 공식 그림의 복사본이 아니라 현재 SKIX 소스에 대응시킨 자체 구조도다.

Connections

• 전체 구조 Atlas
• 통합 전체 구조
• 프레임워크 Blueprint
• 리팩터링 진행 현황