toki
b4c6550eab
- Add node store implementation for edge app - Add adapters factory for node app - Update edge and node transport layers - Update domain rules for edge and node - Add bin scripts for edge and node - Update configs and documentation - Add agent-task node_centralized_mgmt directory
54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
# node
|
|
|
|
## 목적 / 책임
|
|
|
|
디바이스당 1개 실행되는 IOP 노드 에이전트 영역이다. edge에서 들어온 실행 요청을 runtime 요청으로 변환하고, 라우팅된 어댑터를 실행하며, 실행 이벤트와 이력을 관리한다.
|
|
|
|
## 포함 경로
|
|
|
|
- `apps/node/cmd/node/` — node CLI 진입점과 서브커맨드
|
|
- `apps/node/internal/bootstrap/` — fx 의존성 주입과 adapter registry 구성
|
|
- `apps/node/internal/node/` — transport handler 구현과 실행 오케스트레이션
|
|
- `apps/node/internal/runtime/` — node 도메인 타입과 핵심 인터페이스
|
|
- `apps/node/internal/router/` — RunRequest를 ExecutionSpec으로 해석하는 라우팅
|
|
- `apps/node/internal/transport/` — edge와의 TCP/protobuf 세션 및 메시지 처리
|
|
- `apps/node/internal/adapters/` — mock/ollama/vllm/cli 실행 어댑터
|
|
- `apps/node/internal/store/` — SQLite 실행 이력 저장
|
|
|
|
## 제외 경로
|
|
|
|
- `apps/edge/` — node를 받아들이는 gateway 서버 영역
|
|
- `apps/control-plane/` — 노드 등록/정책/스케줄링 예정 영역
|
|
- `apps/worker/` — 비동기 작업 처리 예정 영역
|
|
- `packages/` — 여러 앱이 공유하는 공통 패키지
|
|
- `proto/` — 앱 간 메시지 계약
|
|
|
|
## 주요 구성 요소
|
|
|
|
- `runtime.Adapter` — 모델/CLI 실행 어댑터 계약
|
|
- `runtime.Router` — 실행 요청을 구체적인 `ExecutionSpec`으로 변환하는 계약
|
|
- `node.Node` — `transport.Handler` 구현체이자 실행 파이프라인 조정자
|
|
- `transport.Session` — edge와 연결된 node 세션 및 실행 취소 함수 관리
|
|
- `adapters.Registry` — 사용 가능한 node 어댑터 등록/조회
|
|
- `store.Store` — 실행 상태와 결과 저장
|
|
|
|
## 유지할 패턴
|
|
|
|
- `runtime` 패키지에는 도메인 타입과 인터페이스를 두고 구체 구현 의존성을 넣지 않는다.
|
|
- transport/proto 타입은 `node.Node` 경계에서 runtime 타입으로 변환한다.
|
|
- 어댑터 추가 시 `runtime.Adapter`를 구현하고 bootstrap registry에 등록한다.
|
|
- 실행 취소는 run ID 기준으로 세션에 등록하고 실행 종료 시 반드시 해제한다.
|
|
- node 내부 변경은 가능한 대상 패키지 테스트를 먼저 추가하거나 갱신한다.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **edge**: edge는 node 연결 등록과 중앙 설정 전달, 라우팅 진입을 담당한다. node는 edge가 보낸 실행 요청을 처리하고 이벤트를 돌려준다.
|
|
- **platform-common**: node는 `packages/config`, `packages/observability`, `proto/gen/iop` 등을 사용하지만 공통 타입/설정 자체의 소유자는 platform-common이다.
|
|
- **control-plane 후보**: 정책/스케줄링의 시스템 단위 결정은 control-plane에서 다루고, node는 전달받은 실행 단위 수행에 집중한다.
|
|
|
|
## 금지 사항
|
|
|
|
- node 도메인 내부에서 gRPC, WebSocket 기본 transport, actor/FSM/plugin framework를 새 기본 구조로 도입하지 않는다.
|
|
- `proto/gen/iop/*.pb.go` 생성 파일을 직접 수정하지 않는다.
|
|
- 새 어댑터 구현을 `node.Node`에 직접 분기문으로 박아 넣지 않는다.
|
|
- placeholder 상태인 control-plane/worker 책임을 node에 임시로 흡수하지 않는다.
|