toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-ops/rules/project/rules.md

9.5 KiB
Raw Blame History

iop 프로젝트 규칙

응답 언어

  • 기본 응답은 한국어로 한다.
  • 코드, 명령어, 에러 메시지, 식별자는 원문을 유지한다.

프로젝트 개요

  • IOP(Inference Operations Platform)는 Control Plane - Edge - Node 계층 구조를 기반으로 모델 서빙과 CLI Agent/Automation 실행을 함께 다루는 실행 오케스트레이션 모노레포이다. 핵심 서비스는 Go이고 운영 client는 Flutter/Dart이다.
  • 내부 실행 개념은 model 중심이 아니라 adapter + target 중심으로 정리한다. 외부 OpenAI-compatible 경계나 외부 CLI 인자에서는 호환성을 위해 model 표현이 남을 수 있다.
  • 현재 구현 중심은 apps/node와 apps/edge의 Edge-Node 실행 경로, apps/control-plane의 Control Plane-Edge/Client wire baseline, apps/client의 Flutter 운영 UI, iop-edge command 중심의 local/field 운영 UX, OpenAI-compatible/A2A 입력 표면, CLI adapter logical session/runtime이다.
  • apps/control-plane은 health/readiness HTTP, Client proto-socket WebSocket, Edge proto-socket TCP 연결 baseline을 가진 중앙 제어면이다.
  • apps/worker는 CLI placeholder 수준이므로 본격 구현 전 별도 domain rule을 만들거나 갱신한다.

주요 구조

  • apps/node/ — Edge에 연결되는 실행자. 런타임 라우팅, adapter execution, CLI/model runtime 실행, 현재 단계의 로컬 실행 이력 저장을 담당한다.
  • apps/edge/ — 여러 Node를 묶는 백엔드 실행 그룹 컨트롤러. token 기반 등록, node registry, node 설정 전달, routing, stream relay, ops console, OpenAI-compatible/A2A 입력 표면을 담당한다.
  • apps/control-plane/ — 여러 Edge를 연결하고 상태 조회/설정 변경/명령 전달/이벤트 수신/운영 제어 API 제공을 담당할 Go 기반 중앙 관리 서버이다.
  • apps/client/ — Control Plane을 통해 Edge/Node 운영 상태를 보여주는 Flutter client이다.
  • apps/worker/ — 비동기 작업 처리 예정 영역이다. 현재 placeholder이다.
  • packages/go/ — 설정, 인증, 이벤트 helper, host setup, 정책, 메타데이터, 작업, 관측성, 버전 등 Go 공통 패키지이다.
  • packages/flutter/ — Flutter 재사용 패키지 root이다. 현재 packages/flutter/iop_console이 IOP-owned console package이다.
  • proto/iop/ — IOP 메시지 계약 원본이다.
  • proto/gen/iop/ — protobuf 생성물이다.
  • configs/ — 앱별 YAML 설정 예시이다.
  • scripts/dev/ — repo 내부 개발 진단 helper 위치이다. field 사용자 기본 경로로 안내하지 않는다.
  • build/bin/ — 로컬 바이너리 산출 위치이다.
  • build/artifacts/ — Node bootstrap artifact 산출 위치이다.
  • build/packages/ — Edge host에 전달할 압축 배포 archive 산출 위치이다. archive는 iop-edge와 artifacts/를 포함하고, Edge host에서 config 확정 후 Node bootstrap을 제공하는 흐름을 기준으로 한다.
  • scripts/ — 보조 E2E smoke와 입력 표면 검증 스크립트이다.
  • Makefile — 빌드와 테스트 진입점을 정의한다.
  • docs/ — 사람용 최신 가이드만 둔다. local 테스트 환경값은 agent-test/local/rules.md에 둔다.

기술 스택

  • 언어/모듈: Go 1.24, module iop
  • CLI: github.com/spf13/cobra
  • 설정: github.com/spf13/viper, YAML
  • DI: go.uber.org/fx
  • 로깅: go.uber.org/zap
  • 메트릭/헬스: Prometheus HTTP handler
  • 저장소: modernc.org/sqlite
  • 메시지 계약: google.golang.org/protobuf, proto/iop/*.proto
  • 내부 소켓: git.toki-labs.com/toki/proto-socket/go
  • Client: Flutter/Dart, proto_socket Dart client, Dart protobuf 생성물

프로젝트 특화 컨벤션

  • 기존 hexagonal 구조를 유지한다. 특히 apps/node/internal/runtime 인터페이스를 중심에 두고 transport/adapters/store는 바깥쪽 구현으로 둔다.
  • 새 node 어댑터는 runtime.Adapter를 구현하고 apps/node/internal/bootstrap/module.go에서 registry에 등록한다.
  • 내부 실행 요청과 상태 저장에서는 adapter, target, execution 용어를 우선한다. model은 외부 API 호환이나 legacy placeholder일 때만 허용한다.
  • Control Plane은 Node를 직접 연결/스케줄링하지 않고 Edge를 통해 시스템을 제어한다. Edge는 자신의 로컬 런타임 상태와 Node registry를 소유한다.
  • 사용자 실행, 로컬/dev 배포, field 테스트, 임시 Control Plane 대체 흐름은 사용법을 scripts/dev/, 보조 smoke script, 별도 dev deploy 바이너리, 모델용 skill로 흩뜨리지 않고 iop-edge와 iop-node command 표면에 모은다. helper script가 필요해도 공식 사용자 경로가 되면 안 된다.
  • Control Plane이 없는 테스트/개발 배포 단계에서는 edge.yaml을 테스트용 Control Plane source of truth로 본다. Node별 id/alias/token/adapter/runtime 설정은 Edge config의 nodes[]에서 관리한다.
  • Node 사용자 UX는 bootstrap 명령 하나로 끝나야 한다. 사용자가 node.yaml을 만들거나 편집하거나 iop-node serve --config ...를 직접 실행하는 흐름을 기본 경로로 두지 않는다. bootstrap 내부에서 임시 상태나 설정 파일을 만들 수 있더라도 이는 구현 세부이며 사용자 가이드와 기본 운영 UX에 노출하지 않는다.
  • 바이너리 배포 UX는 repo checkout 위치에 묶이지 않아야 한다. iop-edge/iop-node는 아무 작업 디렉터리에서 실행 가능해야 하며, 로컬/dev bundle에서는 Edge 설정을 바이너리와 같은 디렉터리의 edge.yaml 같은 구조화된 config에 모으는 방향을 우선한다. Node 쪽은 별도 사용자 config 파일이 아니라 Edge가 제공하는 bootstrap으로 연결한다.
  • Edge-Node 내부 통신은 TCP 기반 protobuf 메시지 흐름을 우선한다. 브라우저/앱 표면이 필요한 경계는 proto-socket WebSocket/WSS를 사용할 수 있다. gRPC 도입, Edge-Node 기본 transport의 WebSocket 전환, actor/FSM/plugin framework 도입은 금지한다.
  • protobuf 계약 변경 시 proto/iop/*.proto를 먼저 수정하고 make proto로 proto/gen/iop/*.pb.go를 갱신한다. 생성 파일은 직접 수정하지 않는다.
  • Edge/Node 앱 설정 구조 변경 시 packages/go/config의 struct/default와 configs/*.yaml 예시를 함께 확인한다. Control Plane 로컬 설정 구조 변경 시 apps/control-plane의 config loader와 configs/control-plane.yaml 예시를 함께 확인한다.
  • 테스트는 변경 범위에 맞춰 go test ./... 또는 대상 패키지 테스트를 실행한다.
  • 사용자 실행 파이프라인에 닿는 작업을 한 경우, 작업 완료 후 agent-ops/rules/project/domain/testing/rules.md의 검증 기준을 따른다.
  • field/bootstrap 작업은 testing domain rule을 따르고, 실제 local 환경값이 필요하면 agent-test/local/rules.md를 따른다.
  • Node, OTO, specialized agent, Control Plane enrollment 등 사용자가 대상 host에서 실행하는 bootstrap/install command 작업은 agent-ops/rules/project/domain/testing/rules.md의 one-line bootstrap UX 기준을 따른다.
  • 상세 DB schema, event schema, permission/policy/audit model, federation, mTLS 구현 세부는 각 작업에서 별도로 결정한다.

도메인 룰 로딩

  • 아래 도메인 매핑에 해당하는 작업에서 해당 domain 최초 진입 시 domain rule을 1회 읽는다.
  • 이미 읽은 domain rule은 같은 세션에서 반복해서 읽지 않는다.
  • 사용자 실행 파이프라인에 닿는 작업의 검증 단계에서는 testing domain rule을 1회 읽는다.

도메인 매핑

경로 패턴 도메인 rules.md
apps/node/** node agent-ops/rules/project/domain/node/rules.md
apps/edge/** edge agent-ops/rules/project/domain/edge/rules.md
apps/control-plane/** control-plane agent-ops/rules/project/domain/control-plane/rules.md
apps/client/** client agent-ops/rules/project/domain/client/rules.md
packages/flutter/** client agent-ops/rules/project/domain/client/rules.md
packages/go/** platform-common agent-ops/rules/project/domain/platform-common/rules.md
proto/** platform-common agent-ops/rules/project/domain/platform-common/rules.md
configs/** platform-common agent-ops/rules/project/domain/platform-common/rules.md
scripts/dev/** testing agent-ops/rules/project/domain/testing/rules.md
scripts/e2e-*.sh testing agent-ops/rules/project/domain/testing/rules.md
Makefile testing agent-ops/rules/project/domain/testing/rules.md
docker-compose.yml testing agent-ops/rules/project/domain/testing/rules.md

도메인 후보

  • worker: apps/worker/**가 placeholder를 넘어 작업 큐 소비/재시도/결과 저장을 구현하기 시작할 때 생성한다.

스킬 라우팅

  • 사용자 실행 파이프라인 검증, repo 내부 edge-node 진단, 메시지 2회 왕복, edge command 응답, 보조 E2E smoke, full-cycle 실제 구동, scripts/dev/edge.sh/scripts/dev/node.sh 진단 테스트: agent-ops/skills/project/e2e-smoke/SKILL.md
  • field 테스트 포트, artifact/bootstrap HTTP, 외부 테스트 환경: agent-test/local/rules.md를 따른다.
  • bootstrap/install UX, Agent Bootstrap, OTO 등록, Control Plane enrollment: testing domain rule과 agent-test/local/rules.md를 따른다.
  • 반복 작업이 확인되면 agent-ops/skills/project/<skill-name>/SKILL.md를 생성하고 이 표에 등록한다.