SK-Intellix Framework SDK System Design
1. 범위
이 문서는 A1 기준 Android platform package와 DeviceAgent API 구조를 설명한다. 범위는 a1-packages, <qssi-vendor-overlay>, <um-vendor-overlay>, QCS6490 split build, platform vendor HAL/vendor service까지다.
범위에 포함하지 않는 것:
- 상위 판단/계획 서버 구조
- 자연어 planner 구조
- 메모리/개인화 정책
- 별도 클라우드 런타임
이 문서의 핵심 질문은 하나다.
현재 A1 제품 이미지 안에서 client app의 기능 호출이
DeviceAgent, peer agent, platform vendor HAL/vendor service, board device node까지
어떤 경계로 내려가는가?
DeviceAgent는 여기서 단순 Android app이 아니라 A1 제품 기능의 product-level SystemServer / service hub다. Android OS의 system_server를 대체한다는 뜻은 아니며, 제품 기능 제어 계층에서 system_server처럼 중앙 Binder service, domain dispatcher, peer service coordinator, HAL bridge 역할을 모아 수행한다는 뜻이다.
2. 현재 호출 구조
SKMLauncher / SKMLauncher2 / ICT / privileged package
-> DeviceControlAPIJavaLib
-> DeviceControlProxy.bindService(action=com.sk.airbot.devicecontrol.IDeviceControl)
-> DeviceAgent service
-> IDeviceControl.sendModuleCommand(Bundle)
-> MainApi / framework command / task package / domain managers
-> AMRAgent / IotAgent / UpdateAgent / PairingAgent / VisionAgent / LLMAgent
-> vendor.<platform-vendor>.hardware.device_manager@1.0
-> vendor.<platform-vendor>.hardware.soundflowservice@1.0
-> UM vendor service / MCU / SoundFlow / sysfs / DTS-backed node
3. A1 Package Runtime Composition
| 영역 | 현재 구성 | 확인 근거 |
|---|---|---|
| Client API | apps/DeviceControlAPI/java/com/sk/airbot/devicecontrol/DeviceControlProxy.java |
action com.sk.airbot.devicecontrol.IDeviceControl로 bind |
| Binder contract | apps/DeviceAgent/app/src/main/aidl/com/sk/airbot/devicecontrol/IDeviceControl.aidl |
registerCallback, sendModuleCommand(Bundle) |
| Runtime entry | apps/DeviceAgent/app/src/main/AndroidManifest.xml |
.DeviceAgent exported service. 현재 기준에는 서비스 전체 signature permission이 선언되지 않음 |
| Runtime implementation | apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/DeviceAgent.java |
IDeviceControl.Stub 구현 |
| Legacy command path | main/api/MainApi.java, framework/command/* |
기존 method string/Bundle 처리와 command handler 후보 |
| Task path | task/TaskManager.java, TaskIngressClassifier.java, TaskExecutorRegistry.java, TaskReasonContract.java |
task/workflow 계층 상세는 DeviceAgent/SoC 문서에서 관리 |
| State/policy/event | event/StateManager.java, event/EventManager.java, policy/CmdPolicyManager.java, framework/policy/PolicyEngine.java |
현재 코드에 존재하는 정책/상태 관련 구현 |
| Peer agent binding | AMRAgent, IotAgent, UpdateAgent, PairingAgent, VisionAgent, LLMAgent |
SERVICE_MAP.md |
| HAL bridge | DeviceManager HAL, SoundFlow HAL | platform vendor HIDL Java lib와 getService() 호출 |
| Native support | ethernetagent, logwriter, a1_decrypt, libserial_port.so |
MODULE_INVENTORY.md, packages.mk |
3.1 DeviceAgent as Product SystemServer
| 역할 | DeviceAgent에서 보이는 구조 | 설명 |
|---|---|---|
| Service entrypoint | .DeviceAgent service, IDeviceControl action |
client app이 제품 기능을 호출하는 중앙 Binder entry |
| Permission boundary | 일부 명령의 Binder.getCallingUid() 검사, 제품 이미지·서명·배치 정책 |
현재는 명령별 검사가 부분적으로 존재한다. 공용 API를 열기 전 서비스 권한과 공통 호출자 검증을 보강해야 함 |
| Command dispatch | sendModuleCommand(Bundle), MainApi, framework/command/* |
legacy method와 command handler를 제품 기능으로 연결 |
| Task/runtime coordination | task/TaskManager.java, TaskExecutorRegistry.java, TaskReasonContract.java |
실행 가능성, queue, reason, callback을 구조화하는 후보/현재 구현 |
| Peer service coordination | AMR/IoT/Update/Pairing/Vision/LLM agent binding | 제품 기능별 agent를 묶는 service hub |
| HAL bridge | DeviceManager/SoundFlow HIDL Java lib, getService() path |
Android system app 영역에서 vendor HAL service로 내려가는 다리 |
| State/policy/event | StateManager, EventManager, CmdPolicyManager, PolicyEngine |
제품 기능 상태와 정책 판단이 모이는 지점 |
3.2 Peer Agent Service Topology
DeviceAgent는 client API만 받는 endpoint가 아니라 기능별 service agent를 묶는 hub다. SERVICE_MAP.md와 DeviceAgent.connectServices() 기준으로 확인되는 연결은 다음과 같다.
| 연결 | 등록/action | DeviceAgent 연결 방식 | 의미 |
|---|---|---|---|
| Client apps -> DeviceAgent | com.sk.airbot.devicecontrol.IDeviceControl |
DeviceControlProxy.bindService, IDeviceControl.Stub |
외부 제품 API 진입점 |
| DeviceAgent -> AMRAgent | com.sk.airbot.amrcontrol.IAMRControl |
AMRService.connectService, IAMRControlCallback |
AMR 이동/지도/도킹/배터리 상태 수신 및 명령 |
| DeviceAgent -> IotAgent | com.sk.airbot.iotcontrol.IIotControl |
bindService, mServiceConnectionIot |
IoT 보고/제어 |
| DeviceAgent -> UpdateAgent | com.sk.airbot.updatecontrol.IUpdateControl |
bindService, mServiceConnectionUpdate |
OTA/update orchestration |
| DeviceAgent -> PairingAgent | com.sk.airbot.pairingcontrol.IPairingControl |
bindService, mServiceConnectionPairing |
pairing/BLE control |
| DeviceAgent -> VisionAgent | com.sk.airbot.visioncontrol.IVisionControl |
VisionAIManager.bindService |
vision recognition/control |
| LLMAgent | com.sk.airbot.llmcontrol.ILLMControl |
AIDL/manifest/package 존재. DeviceAgent direct bind 여부는 별도 source 확인 필요 | LLM/TTS peer package 후보 |
이 표에서 중요한 점은 Agent들이 DeviceAgent 내부 클래스로 합쳐진 구조가 아니라는 것이다. 각 Agent는 별도 package/service이고, DeviceAgent가 Binder/action/callback 경계로 연결한다.
4. Partition / Package Boundary
| Partition 관점 | 현재 구성 | 설명 |
|---|---|---|
| QSSI / system | <qssi-vendor-overlay>/vendor.mk, prebuilts/packages.mk, a1-packages/packages.mk |
system/priv-app, permissions, sysconfig, HIDL interface 정의 |
| system/priv-app | DeviceAgent, AMRAgent, IotAgent, UpdateAgent, VisionAgent, PairingAgent, launcher류 |
PRODUCT_PACKAGES와 prebuilt/source package로 포함 |
| system policy | privapp-permissions-vendor_packages.xml, vendor_whitelist.xml, package sepolicy |
privileged app 권한과 system allowlist |
| UM / vendor | <um-vendor-overlay>/vendor.mk, airbot/airbot.mk |
vendor service, vendor sepolicy, thirdparty/Kardome 포함 |
| vendor HAL service | vendor.<platform-vendor>.hardware.device_manager@1.0-service, vendor.<platform-vendor>.hardware.soundflowservice@1.0-service |
/vendor/bin/hw, init rc, VINTF fragment |
| board/kernel | kernel/msm-5.4, board DTS include, device node |
UART/MCU/fan/thermal/audio 실기기 경로 |
4.1 BSP Split Build Evidence
QCS6490 BSP 관점에서 platform vendor package는 QSSI와 UM에 나뉘어 들어간다.
| 단계 | 확인 근거 | 의미 |
|---|---|---|
| QSSI source/prebuilt overlay | <qssi-vendor-overlay>/vendor.mk, <qssi-vendor-overlay>/prebuilts/packages.mk |
system/priv-app, permission/sysconfig, HIDL interface 반영 |
| UM vendor overlay | <um-vendor-overlay>/vendor.mk, <um-vendor-overlay>/airbot/airbot.mk |
vendor HAL service, vendor sepolicy, Kardome/SoundFlow 반영 |
| 동기화 위치 | sync_vendor_overlay.sh |
QSSI/UM 각각의 vendor/<platform-vendor>로 복사 |
| split build | g13qcs6490/build_project.sh |
qssi --qssi_only, lahaina --target_only 빌드 |
| merge/release | build_image_standalone.py --image super, RELEASE/OTA, RELEASE/PKG |
merged super/OTA/PKG 산출 |
5. HAL / Vendor Boundary
| HAL | Interface 위치 | Implementation 위치 | 검증 |
|---|---|---|---|
| DeviceManager | <qssi-vendor-overlay>/airbot/hardware/interfaces/device_manager/1.0/IDeviceManager.hal |
<um-vendor-overlay>/airbot/external/device_manager/service |
service 등록, callback, MCU/fan/thermal/serial 기능 log |
| SoundFlow | <qssi-vendor-overlay>/airbot/hardware/interfaces/soundflowservice/1.0/ISoundFlowService.hal |
<um-vendor-overlay>/airbot/external/sndflow/service |
service 등록, event callback, Kardome/SoundFlow log |
6. SDK 전환의 실제 의미
현재 존재하는 API는 DeviceControlAPIJavaLib와 IDeviceControl.sendModuleCommand(Bundle)이다. 따라서 SDK 전환은 다음 순서로만 사실 기반으로 말할 수 있다.
| 단계 | 설명 | 완료 조건 |
|---|---|---|
| 현재 API 고정 | DeviceControlProxy, IDeviceControl, Bundle key/method contract를 문서화 |
source map, sample call, callback log |
| Adapter 정리 | public caller가 직접 Bundle key를 다루지 않도록 wrapper 추가 | adapter test, 기존 path parity |
| AAR 후보 | sk-intellix-sdk-core.aar 같은 별도 artifact로 분리 |
AAR build, sample app, API diff |
| Platform packaging | AOSP image에 SDK/client library 반영 | QSSI package evidence |
7. 리스크
| 리스크 | 의미 | 대응 |
|---|---|---|
Bundle/method string 의존 |
API 안정성, 타입 안정성 낮음 | 현재 contract를 먼저 고정하고 adapter로 감싼다 |
| DeviceAgent 책임 집중 | API gateway, domain manager, HAL bridge, policy/state가 한 앱에 집중 | DeviceAgent/SoC 문서에서 task/domain/source map으로 분해 |
| QSSI/UM 경계 혼동 | system app, HIDL interface, vendor service 책임이 섞여 보일 수 있음 | build partition flow와 vendor brief에서 owner 분리 |
| evidence owner 혼동 | device log를 SK-Intellix 역할처럼 표현할 수 있음 | 플랫폼 벤더 제출, release gate 검증으로 표기 |
| SDK 구현 상태 오해 | 후보 계약을 구현 완료처럼 읽을 수 있음 | SDK 문서는 candidate/contract draft로 표기 |