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

13 KiB
Raw Blame History

test_env last_rule_updated_at
dev-corp 2026-07-13

dev-corp 테스트 규칙

현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다. dev-corp 테스트 환경은 public iop.ai.kr Edge와 내부 provider nodes를 기준으로 하며, mac-mini는 source/build/provider SSH runner로만 사용한다. local/dev stack과 공존하도록 host publish 포트와 runtime profile을 분리한다.

공통 규칙

  • dev-corp 테스트/검증은 이 파일을 기준으로 판단한다.
  • 작업 완료 검증은 변경 범위 기준으로 선택한다.
  • 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
  • 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
  • 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다.
  • token/secret/API key 원문은 원격 환경에서 주입하고, shell stdout/stderr와 최종 보고에 출력하지 않는다.
  • private IP와 SSH user는 테스트 접속에 필요한 환경값으로 기록할 수 있으나, token/secret 원문은 기록하지 않는다.
  • 테스트용 Docker 환경을 작성/수정할 때는 Docker Compose networks, IPAM subnet, static IPv4, extra_hosts, host publish 문서 어디에도 회사 LAN/VPN과 충돌하는 대역을 사용하지 않는다.

기본 배포 통로

  • dev-corp Edge의 기본 배포/검증 통로는 iop.ai.kr이다. artifact/bootstrap, Edge OpenAI-compatible, Edge-Node TCP는 같은 host의 dev-corp 포트 18085/18086/18087을 사용한다.
  • mac-mini는 source sync/build/provider 점검 경유지로만 사용한다. dev-corp Edge 주소, Node edge_addr, OpenAI-compatible smoke 대상, bootstrap 기본 URL은 public domain 값으로만 둔다.
  • mac-mini local endpoint로 Edge를 배포/검증하지 않는다. 사용자가 “mac-mini local Edge로 검증” 또는 같은 의미의 명시 요청을 한 경우에만 별도 local-runner 비교로 진행한다.
  • provider direct 확인은 mac-mini에서 Spark01 Ornith 192.168.2.2:8003, Spark02 Ornith 192.168.2.4:8005, Mac Studio Gemma4 192.168.2.3:8004를 확인한다.

기본 환경

  • host: Edge public runtime은 iop.ai.kr(115.21.224.82)이다.
  • remote runner: ssh fe@172.24.63.178 mac-mini는 source sync/build/provider SSH runner다.
  • repo root: 목표 checkout은 /Users/fe/agent-work/iop-dev-corp이다. 2026-07-02 기준 해당 checkout과 build/dev-corp-runtime runtime이 배포되어 있으며, /Users/fe/iop-field는 unrelated legacy field state로 본다.
  • sync 기준: dev-corp 배포 전 mac-mini checkout은 배포 기준 ref로 clean sync하고 dirty 변경은 보존 대상으로 보지 않는다.
  • env file: compose stack을 만들면 .env.dev-corp.example로 분리한다. 파일 생성 전에는 native/provider-pool profile만 기준으로 삼는다.
  • compose identity: COMPOSE_PROJECT_NAME=iop-dev-corp-agent, IOP_COMPOSE_NETWORK=iop-dev-corp-agent-net, IOP_COMPOSE_SUBNET=10.89.2.0/24.
  • port: web/dev preview 13002, Control Plane HTTP 18002, Client WS 19004, CP-Edge wire 19005, compose Edge-Node TCP 19006, native Edge-Node TCP 후보 18087, Edge admin 후보 19094, Control Plane metrics 19104, Prometheus 19112, Grafana 19122.
  • operator notice: 기존 dev-corp 사용자-facing 접속점(13002, 18002, Edge OpenAI-compatible 후보 18086, native Edge 후보 18087)은 변경하지 않는다. 현재 세션에서는 dev-corp 원격 접근이 불가하므로 compose/port 문서 정의만 갱신하고 실제 세팅은 수행하지 않는다.
  • optional field ports: artifact/bootstrap HTTP 18085, Edge OpenAI-compatible HTTP 18086, Edge metrics 19102.
  • runtime: Go quick check는 local toolchain을 우선한다. Docker/Flutter/client/field/bootstrap/provider-pool evidence는 mac-mini와 내부 provider nodes를 사용한다.
  • package manager: Go modules / Makefile / Flutter pub
  • docker: 현재 작업 컨테이너에서는 Docker-in-Docker를 사용하지 않는다. Docker compose 검증은 mac-mini checkout에서 수행한다.
  • external service: dev-corp Edge 후보는 http://iop.ai.kr:18085, http://digitalplatform.iop.ai.kr:18086/v1, iop.ai.kr:18087이다. Control Plane/Client public 후보는 해당 public host 포트가 실제로 열려 있을 때만 검증 대상으로 삼는다.
  • model endpoint: Edge 배포 후 기본 외부 후보 http://digitalplatform.iop.ai.kr:18086/v1; 직접 provider 확인은 agent-test/dev-corp/inventory.yaml의 provider endpoint를 따른다.
  • credential: secret/token/API key 원문은 문서에 기록하지 않는다.

포트 매핑

용도 local/test dev dev-corp
Web preview 13000 13001 13002
Control Plane HTTP 18000 18001 18002
CP Client WS 19080 19001 19004
CP-Edge wire 19081 19002 19005
Edge-Node TCP 19090 19003 19006
Edge artifact/bootstrap 18080 18082 18085
Edge OpenAI-compatible 18081 18083 18086
Edge metrics 19092 19101 19102
Control Plane metrics 19100 19103 19104
Prometheus UI/API 19110 19111 19112
Grafana UI 19120 19121 19122
PostgreSQL host publish 15400 15401 15402
Redis host publish 16300 16301 16302

dev-corp native/provider-pool profile은 compose Edge-Node TCP 19006이 아니라 public native Edge listen 후보 iop.ai.kr:18087을 사용한다. DGX Spark 01/02와 Mac Studio Node도 기본적으로 이 public Edge addr에 직접 붙는다. mac-mini reverse SSH tunnel은 dev-corp Edge 기준으로 사용하지 않는다. 세부 provider endpoint와 Node 접속 기준은 agent-test/dev-corp/inventory.yaml, agent-test/dev-corp/edge-smoke.md, agent-test/dev-corp/node-smoke.md를 따른다.

런타임 프로필

  • local quick check: 현재 checkout에서 Go quick check를 우선 실행한다.
  • remote runner: source sync/build/provider SSH 조작은 ssh fe@172.24.63.178의 /Users/fe/agent-work/iop-dev-corp 기준으로 수행할 수 있다.
  • public Edge evidence: Edge runtime evidence와 OpenAI-compatible smoke는 public iop.ai.kr 경로로 판정한다.
  • compose dev-corp stack: .env.dev-corp.example, COMPOSE_PROJECT_NAME=iop-dev-corp-agent, IOP_COMPOSE_NETWORK=iop-dev-corp-agent-net, IOP_COMPOSE_SUBNET=10.89.2.0/24, Edge-Node TCP 19006, Control Plane metrics 19104, Prometheus 19112, Grafana 19122를 사용한다.
  • compose observability: dev-corp Control Plane 관측 그룹 정의는 문서 기준으로만 유지한다. 접근 가능한 mac-mini runner에서 별도 요청이 있을 때 실제 compose 세팅/검증을 수행한다.
  • Edge direct dev-corp profile: artifact/bootstrap 18085, OpenAI-compatible 18086, metrics 19102, admin 19094를 사용한다.
  • dev-corp provider pool: 기본 public Edge-Node TCP iop.ai.kr:18087을 기준으로 한다. /Users/fe/agent-work/iop-dev-corp/build/dev-corp-runtime/edge.yaml은 mac-mini runner의 보조 산출물일 뿐 dev-corp Edge source of truth로 판정하지 않는다. retired reverse tunnel route는 Edge addr로 사용하지 않는다. 3-node/provider 세부는 agent-test/dev-corp/edge-smoke.md와 agent-test/dev-corp/node-smoke.md를 따른다.
  • current native Control Plane: 2026-07-02 기준 provider-pool runtime에서 build/dev-corp-runtime/bin/control-plane이 18002/19004/19005를 listen하고, Edge id dev-corp-edge가 127.0.0.1:19005로 연결된다. provider snapshot status 기준은 http://127.0.0.1:18002/edges/dev-corp-edge/status다.
  • external provider field: DGX Spark 01/02와 Mac Studio는 mac-mini에서 내부 SSH로 접속한다. 직접 접속 경로와 provider endpoint는 agent-test/dev-corp/inventory.yaml을 따른다.

프리플라이트

  • plan 작성 시 필수 검증이 현재 checkout을 벗어나 mac-mini runner, field/bootstrap, 외부 provider, Docker/code-server, emulator/device, 공유 장기 runtime을 사용하면 먼저 테스트 환경 프리플라이트를 계획에 기록한다.
  • 테스트 환경 프리플라이트에는 runner, repo root/workdir, branch/HEAD/dirty 상태, local 변경과 원격 source 동기화 여부, binary/artifact 경로와 필요한 help/version 출력, config path, runtime identity, port/process 상태, 외부 host, OS/arch 가정을 포함한다.
  • mac-mini에 /Users/fe/agent-work/iop-dev-corp checkout이 없으면 배포/검증을 시작하지 말고 checkout 생성과 source sync를 setup blocker로 보고한다.
  • provider pool 검증 전 mac-mini에서 내부 provider endpoint 192.168.2.2:8003, 192.168.2.4:8005, 192.168.2.3:8004의 /health와 /v1/models를 먼저 확인하고, 각 Node의 edge_addr가 iop.ai.kr:18087인지 확인한다.
  • 현재 dev-corp model/provider mapping은 gemma4:26b -> Mac Studio capacity 5, ornith:35b -> Spark01/02 합산 capacity 8이다. 새 배포에서 Edge config 반영과 model-specific capacity smoke가 통과하기 전에는 새 결과를 확정값으로 보고하지 않는다.
  • 프리플라이트에서 dirty/divergent checkout 또는 stale artifact가 확인되면 dev-corp 배포에서는 먼저 원격 checkout을 clean sync하고 dev-corp runtime 바이너리를 rebuild한다. 잘못된 identity, missing command, closed port, host OS 불일치, source 미동기화가 확인되면 plan은 setup/sync/rebuild 단계를 만들거나 blocker로 보고한다.

노드/Provider 인벤토리 위치

  • dev-corp provider pool machine-readable 기준: agent-test/dev-corp/inventory.yaml
  • dev-corp provider pool과 Edge/OpenAI-compatible 입력 표면 상세 기준: agent-test/dev-corp/edge-smoke.md
  • dev-corp Node 접속과 bootstrap 상세 기준: agent-test/dev-corp/node-smoke.md
  • 공통 provider config 계약 기준: agent-test/dev-corp/platform-common-smoke.md
  • compose stack 기준: agent-test/dev-corp/control-plane-smoke.md, agent-test/dev-corp/client-smoke.md, agent-test/dev-corp/testing-smoke.md

Field/bootstrap 반복 테스트 기준

  • field/bootstrap 검증은 mac-mini runner의 /Users/fe/agent-work/iop-dev-corp checkout과 dev-corp runtime artifact를 기준으로 수행한다.
  • compose dev-corp stack은 Edge-Node TCP 19006을 사용하고, dev-corp provider pool은 native Edge listen 18087을 사용한다. 두 프로필을 섞어서 판정하지 않는다.
  • Node bootstrap은 Edge의 node register가 출력한 OS별 완성 명령을 그대로 사용한다. 사용자에게 안내하는 명령에는 임의 placeholder, 수동 token 치환, IOP_*= named environment parameter를 넣지 않는다.
  • token, API key, private credential 원문은 tracked docs, roadmap, 테스트 규칙에 기록하지 않는다. 실행 증거에는 token을 마스킹하거나 명령 생성 사실만 남긴다.
  • Linux/macOS Node는 생성된 curl | bash 계열 명령을 사용한다. Windows Node는 dev-corp provider pool의 기본 대상이 아니다.
  • dev-corp runtime 배포는 clean sync 후 build/dev-corp-runtime/bin/control-plane, build/dev-corp-runtime/bin/iop-edge, mac node, Linux ARM64 node binary를 같은 source 기준으로 rebuild한다.
  • provider capacity, model/provider mapping은 config check와 config refresh --mode dry-run을 통과한 뒤 config refresh --mode apply로 반영한다. refresh subcommand 또는 19094 admin port가 없으면 바이너리 rebuild 누락으로 보고 먼저 rebuild한다.
  • Edge process restart 또는 일시 단절 후에는 Node reconnect 정책을 검증한다. retry 한계를 넘겨 Node process가 종료된 경우에만 해당 Node host에서 새 bootstrap 실행이 필요하다.

라우팅

  • node / smoke / node 실행 파이프라인 baseline: agent-test/dev-corp/node-smoke.md
  • edge / smoke / edge 실행 그룹과 입력 표면 baseline: agent-test/dev-corp/edge-smoke.md
  • dev-corp provider pool, 3-node 연결, DGX Spark vLLM, Mac Studio vLLM-MLX 점검: agent-test/dev-corp/edge-smoke.md, agent-test/dev-corp/node-smoke.md
  • control-plane / smoke / control-plane health와 wire baseline: agent-test/dev-corp/control-plane-smoke.md
  • client / smoke / Flutter client와 IOP console package baseline: agent-test/dev-corp/client-smoke.md
  • platform-common / smoke / 공통 설정과 protobuf 계약 baseline: agent-test/dev-corp/platform-common-smoke.md
  • testing / smoke / 테스트 도구와 full-cycle 검증 baseline: agent-test/dev-corp/testing-smoke.md

라우팅 규칙

  • 여러 항목이 맞으면 모두 읽는다.
  • 도메인 매핑이나 domain rule이 있으면 각 도메인의 <domain>-smoke 문서를 기본 baseline으로 둔다.
  • 도메인이 아직 없을 때만 project-smoke를 fallback baseline으로 둔다.
  • 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.