From 55f444ca2b8ec2057721402a82ce3b6be0b86819 Mon Sep 17 00:00:00 2001 From: toki Date: Fri, 29 May 2026 05:41:30 +0900 Subject: [PATCH] =?UTF-8?q?docs(readme):=20README=EB=A5=BC=20=ED=95=9C?= =?UTF-8?q?=EA=B5=AD=EC=96=B4=EB=A1=9C=20=EC=A0=95=EB=A6=AC=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 83a4bc2..ef5eec2 100644 --- a/README.md +++ b/README.md @@ -10,17 +10,17 @@ IOP는 NomadCode 전용 Agent Shell이 아니라, NomadCode와 외부 agent, 운 현재 프로젝트는 완성된 운영 시스템이 아니라 스켈레톤 단계다. 이 README는 현재 구현의 세부 사용법보다, 프로젝트가 향하는 구조와 경계를 명확히 설명한다. -## Overview +## 개요 IOP의 실행 대상은 크게 두 가지다. -- **Model Serving** - - OpenAI-compatible model calls +- **모델 서빙** + - OpenAI-compatible model 호출 - Ollama - vLLM - MLX - 그 외 로컬/원격 모델 런타임 -- **Agent / Automation Execution** +- **Agent / Automation 실행** - CLI Agent - Shell - Git @@ -31,7 +31,7 @@ IOP의 실행 대상은 크게 두 가지다. IOP는 model serving만 담당하는 시스템이 아니다. CLI Agent 실행과 node maintenance도 adapter 기반 실행으로 보고, Edge와 Node를 통해 실행 요청, 스트림, 상태, 결과를 관리하는 방향으로 설계한다. 다만 모든 실행자를 `iop-node` 하위 프로세스로 흡수하지는 않는다. OTO처럼 자체 도메인과 배포 단위를 가진 자동화 도구는 Edge에 직접 붙는 specialized domain agent로 다룰 수 있다. -## Core Concept +## 핵심 개념 IOP의 중심 개념은 `adapter + target` 기반 실행이다. @@ -57,7 +57,7 @@ target = codex-local 외부 OpenAI API 호환 계층에서는 호환성을 위해 `model` 필드가 남을 수 있다. 그러나 내부 실행 개념에서는 모델 이름만으로 전체 실행을 설명하지 않고, `adapter`, `target`, `execution`, `node adapter`, `adapter execution` 같은 용어를 우선한다. -## Architecture +## 아키텍처 IOP는 Control Plane이 Edge를 통해 시스템을 제어하고, Edge가 자신의 로컬 실행 그룹을 운영하는 구조를 지향한다. @@ -78,7 +78,7 @@ Control Plane은 Node에 직접 연결하지 않는다. 전체 시스템 제어 > Control Plane은 Edge를 통해 시스템을 제어하고, Edge는 자신의 로컬 런타임 상태를 소유하고 운영한다. -### Control Plane +### 제어면(Control Plane) Control Plane은 자체 서버와 프론트 페이지를 가진 중앙 관리 계층이다. @@ -136,7 +136,7 @@ Node는 모델 런타임, CLI Agent, 도구 실행을 담당한다. Node는 Cont Node는 가능한 한 단순한 실행 단위로 유지한다. 정책, 전체 시스템 조정, 다중 Edge 운영 판단을 Node에 밀어 넣지 않고, 전달받은 실행을 안정적으로 수행하는 데 집중한다. -### Domain Agent +### 도메인 에이전트(Domain Agent) Domain agent는 특정 자동화 도메인을 자체 바이너리와 자체 실행 모델로 가진 Edge 연결 실행자다. @@ -144,7 +144,7 @@ OTO는 build/deploy domain agent의 대표 후보로 둔다. `oto-agent`는 `iop 이 경계에서 `iop-node`는 generic execution agent이고, OTO는 specialized build/deploy agent다. -### Worker Structure +### Worker 구조 Edge, Node, Control Plane은 별도 `iop-worker` 앱으로 분리하지 않고, 각 Go 서비스 내부의 공통 Worker 모듈을 사용한다. 공통 처리 모델은 `Job Queue`, `Worker Pool`, `Job Status`, `Retry`, `Timeout`, `Cancel`이며, Worker가 담당하는 역할은 서비스별 책임에 맞춰 분리한다. @@ -158,9 +158,9 @@ Edge, Node, Control Plane은 별도 `iop-worker` 앱으로 분리하지 않고, - 운영/관리/스케줄 기반 작업을 담당한다. - node health 수집, model registry 동기화, policy/config 배포, drain/reload 명령, benchmark/job 실행, 운영 리포트와 cleanup 작업을 처리한다. -## Execution Model +## 실행 모델 -### Adapter and Target +### 어댑터와 대상(Adapter / Target) IOP 내부 실행은 model 중심이 아니라 adapter 중심으로 정리한다. @@ -172,7 +172,7 @@ IOP 내부 실행은 model 중심이 아니라 adapter 중심으로 정리한다 현재 코드에는 `RunRequest`, `ExecutionSpec`, `RuntimeEvent`, `NodeCommandRequest`, `EdgeNodeEvent`처럼 이 방향을 담기 위한 타입들이 있다. `RunEvent`는 adapter execution stream에, `EdgeNodeEvent`는 node 연결/해제 같은 edge-node lifecycle과 이후 제어/상태성 이벤트에 사용한다. 세부 계약과 schema는 작업을 진행하면서 점진적으로 정리한다. -### Runtime Domain +### 런타임 도메인(Runtime Domain) Runtime Domain은 모델 서빙 중심 실행 영역이다. @@ -188,7 +188,7 @@ Runtime Domain은 모델 서빙 중심 실행 영역이다. 이 영역에서도 내부적으로는 `adapter + target` 개념을 사용한다. 예를 들어 OpenAI 호환 요청의 `model` 값은 내부에서 특정 adapter와 target으로 해석될 수 있다. RAG, context 구성/압축, web search, MCP 정책, tool policy, output validation, retry/fallback은 이 기본 serving/load routing 기반이 정리된 뒤 Runtime 최적화 계층으로 확장한다. -### Automation Domain +### 자동화 도메인(Automation Domain) Automation Domain은 CLI Agent와 도구 실행 중심 영역이다. @@ -208,7 +208,7 @@ NomadCode └─ IOP Automation Domain을 활용하는 개발 업무 자동화 도메인 ``` -## Current Status +## 현재 상태 현재 iop는 스켈레톤 단계다. @@ -238,7 +238,7 @@ NomadCode Client의 장기 UI 기준은 Flutter 앱이며, 필요한 웹 표면은 Flutter Web 산출물로 제공한다. `apps/control-plane`은 Go 기반 운영 제어 서버다. 주요 통신은 edge-node에서 사용 중인 proto-socket을 IOP Wire Protocol 기준으로 Client-Control Plane, Control Plane-Edge, Edge-Node 방향으로 확장한다. Client-Control Plane은 앱/브라우저 경계를 고려해 proto-socket WebSocket/WSS를 우선하고, `net/http`는 health/readiness/bootstrap 같은 보조 endpoint 용도로 유지한다. -## Guide +## 가이드 사람이 읽는 최신 실행 가이드는 [Edge-local Dev Guide](docs/edge-local-dev-guide.md) 하나로 유지한다. @@ -249,7 +249,7 @@ Client의 장기 UI 기준은 Flutter 앱이며, 필요한 웹 표면은 Flutter 로드맵의 큰 축은 Edge-Node 실행 기반, Edge input surface, CLI Automation runtime, remote terminal bridge, agent bootstrap/OTO enrollment, 모델 서빙과 부하 라우팅, RAG/web search/MCP/tool policy/검증 최적화, Control Plane/Client, policy/history/audit, multi-edge operations로 관리한다. -## Development Notes +## 개발 메모 - 기존 구조를 우선하며, 세부 구현은 각 작업의 domain rule과 현재 코드 경계를 먼저 확인한 뒤 진행한다. - Edge-Node 내부 통신은 TCP/protobuf 기반 소켓 흐름을 우선한다. @@ -261,7 +261,7 @@ Client의 장기 UI 기준은 Flutter 앱이며, 필요한 웹 표면은 Flutter - Remote terminal bridge는 Edge/Node 운영 제어 기능으로 분류하며, OpenAI-compatible API가 아니라 IOP native protocol과 정책/audit 계층에서 다룬다. - 앱별 README에는 현재 수동 테스트나 구현 세부가 더 많이 남아 있을 수 있다. 루트 README는 전체 방향과 경계를 설명하는 문서로 유지한다. -## Non-Goals for Current Stage +## 현재 단계에서 다루지 않는 것 이번 단계에서는 다음 내용을 루트 README에서 상세 설계로 확정하지 않는다.