위키 문서 관리 안내

Wiki home › 한국어 문서 · 영어 원문 · v3 문서 안내

프로젝트 공통 문서와 v3 구현 문서의 기준 위치는 이 위키입니다. 이 위키 안에서 프로젝트 공통 개념과 v3 구현 계약의 페이지별 책임을 구분합니다.

저장소별 책임

저장소	관리할 내용
kpl-v3.wiki	프로젝트 개념, 연구·출판, 운영·개발 안내, 스키마·수식, 탐색 메뉴와 문서 이미지
kpl-v3	소스 코드, 배포 파일, 실행 예제, 테스트, 기계가 읽는 검증 입력과 위키로 연결하는 README

위키 안에서는 **“구현체가 바뀌어도 이 설명이 유지되는가?”**로 페이지를 구분합니다. 공통 설계 의도는 프로젝트 페이지, 소프트웨어 리비전에 따라 달라지는 동작은 v3 페이지에 둡니다. 같은 계약을 복제하지 않고 연결합니다.

주제	프로젝트 공통 페이지	v3 구현 페이지
목적과 기능	연구 목적과 설계 원칙	현재 지원 기능, 준비 사항과 제한
아키텍처	제어·분산 실행·관측의 개념적 관계	프로세스, 서비스, 네트워크, 권한, 영속화, 장애 경계와 소스 연결
용량과 배치	목표 규모·허용 용량·관측된 준비 상태의 구분	CLI 기본값, Agent별 예외, 스케줄링 알고리즘, 적용 확인, 예약과 정리
실험 생명주기	설계·증거 수집·비교와 복구 이력 보고	YAML 동작, 타이밍, run/batch 상태, 정지·이어하기·재시도
측정	모집단, 불확실성, 단위와 공정한 보고 원칙	정확한 수식, 정의 버전, 이벤트·필드, 집계와 알려진 누락
운영과 접근	선택한 구현체로 연결	배포, 계정·인증, 로그, SSE, 문제 진단, 백업과 보존
분석과 그림	해석과 비교 가능성의 기준	분석 작업, 그림 조작, 내보내기 형식과 저장 파일
이력과 출판	프로젝트 발전, 논문 목록과 인용	해당 버전의 호환성 매핑, 마이그레이션, 소스 목록, 벤치마크와 검증 근거

v3의 v2 호환성 표는 v3 호환성 페이지에, v2 논문은 출판 페이지에 둡니다. 성능 근거에는 구현 범위·입력·환경·한계를 함께 기록합니다.

프로젝트 페이지

프로젝트 목적·개념·연구·출판은 아래 위키 페이지에서 직접 관리합니다.

문서	책임
프로젝트 개요	짧은 프로젝트 소개, 읽는 순서, 저장소 경계와 버전 발전
CONCEPTS	설계 원칙, 논리 아키텍처, 용량과 워크로드 개념
RESEARCH	연구 질문, 실험 주기, 보고 원칙과 측정 배경
PUBLICATIONS	플랫폼 논문, 활용 연구와 인용 지침
이 문서	통합 위키에 적용하는 책임·분할·탐색·유지보수 기준

운영 예제와 현재 지원 기능은 v3 페이지에 둡니다. kpl-v3 README는 이 위키로 연결하는 짧은 진입점입니다. 연구 방법과 출판 목록은 독자와 변경 이유가 다르므로 별도 페이지로 유지합니다.

구현체 구조

v3 문서 안내는 구현 문서를 독자의 작업별로 묶습니다.

독자의 작업	v3 기준 문서
플랫폼 시작과 운영	Swarm-Deployment, Agent-Capacity, Monitoring
실험 준비·실행·정지·복구	Scenario-Library, Experiments; 실행 예제는 Churn-Publish-Example
실시간 네트워크 확인	Dashboard, Topology
증거 보존·분석·내보내기	Results, Visualization
정확한 계약 조회	Scenario-Reference, Protocol-Options, API, Experiment-Metrics, Bandwidth
구현 이해와 변경	Architecture, Development, Churn-Performance
이전 구현과 비교	V2-Reproduction, V2-Analysis-Coverage

Monitoring은 Prometheus/Grafana·접근 로그·연결 진단, Results는 저장 파일과 내보내기·백업 경계, Experiments는 실행·복구를 담당합니다. API는 HTTP 본문·상태 코드·SSE 형식·캐시 계약, 지표·대역폭 페이지는 수식, Visualization은 그림 조작의 기준입니다.

문서를 나누는 기준

독자의 작업이나 내용의 책임이 달라질 때 분리합니다. 단순히 길다는 이유로 나누거나 버그 수정마다 새 문서를 만들지 않습니다.

• 절차의 준비 사항, 단계, 결과와 실패 대응은 함께 둡니다.
• 절차와 전체 스키마·수식은 분리하고 해당 참조 절로 연결합니다.
• 실시간 관측, 원본 저장 결과, 계산한 분석, 모니터링 이력은 보존 기간이 다르므로 구분합니다.
• 비교하며 읽어야 하는 프로토콜 옵션과 지표 정의는 관련 항목을 함께 둡니다.
• 최적화 측정과 과거 검증 근거는 날짜·입력·한계와 함께 개발·호환성 자료에 둡니다. 이후 checkout의 검증으로 표현하지 않습니다.

탐색과 유지보수

영어 문서를 기준으로 합니다. Home.md가 기본 진입점이며 기본 사이드바·목차·Footer는 영어로 구성합니다. _Sidebar.md의 한국어 문서는 기본적으로 접힌 하위 섹션이고, Home-KO.md는 한국어 번역을 모아 보는 진입점입니다. 영어 페이지 하단에는 한국어 번역 링크를, 한국어 페이지 상단에는 한국어 문서 섹션과 해당 영어 원문 링크를 둡니다.

Agent-Capacity.md와 Agent-Capacity-KO.md처럼 평탄하고 안정적인 ASCII 페이지 이름을 사용합니다. 한국어 하위 섹션은 탐색 구조로 구성하여 기존 페이지 URL을 유지합니다. 영어 원문을 먼저 갱신하고 한국어의 절 범위·예제·대상을 맞춥니다. 한국어 안내에서도 실제 영어 UI 레이블을 유지합니다.

Markdown 링크는 .md 없는 전체 위키 URL을 사용합니다. 예: [Agent 용량](https://github.com/k-p2p-lab/kpl-v3/wiki/Agent-Capacity-KO). 편집 시 절 앵커를 보존합니다. 소스·디렉터리·예제 링크는 kpl-v3 저장소의 blob/tree URL을 사용합니다. 로컬 ../internal 경로는 위키 저장소를 기준으로 해석되어 v3 소스를 가리킬 수 없습니다. 위키 이미지는 images/에 두고 raw 위키 URL로 연결합니다.

코드 동작이 바뀌면 해당 위키 페이지와 한국어 쌍을 관련 소스 리비전에 맞춰 갱신합니다. 페이지를 추가·변경할 때 Home·목차·Sidebar를 함께 맞춥니다. kpl-v3 README는 짧은 진입점입니다. 문서와 이미지는 위키에 두고 v3에 docs 디렉터리를 다시 만들지 않습니다.

로컬 편집과 검증

로컬에서 작업할 때 위키를 별도로 clone합니다.

git clone https://github.com/k-p2p-lab/kpl-v3.wiki.git
cd kpl-v3.wiki

이곳에서는 Markdown 페이지를 수정합니다. 애플리케이션·Swarm·개발 명령은 kpl-v3 소스 저장소에서 실행합니다. 위키는 문서 저장소이며 애플리케이션 checkout이 아닙니다. 위키와 v3의 commit 이력은 독립적이므로 벤치마크·검증 근거를 남길 때 소스 commit을 기록합니다.

게시 전에 페이지·앵커, 같은 언어 연결, 소스 파일·이미지, Sidebar·목차에서의 접근, 표·코드 펜스·구조화 예제를 검사합니다. 문서 검사는 실행 동작을 검증하지 않으며 과거 테스트를 이후 리비전에서 수행한 것으로 표시하지 않습니다.

GitHub 공식 문서의 위키 링크·이미지, Sidebar·Footer 파일, 접을 수 있는 섹션, 위키 Git 편집·게시를 참고하십시오.

이식 기록

저장소 소개와 v3 목차를 포함한 Markdown 56개(영문·국문 28쌍)를 이식했습니다. 이식 목록은 원본 경로·내용 hash·위키 대상·소스 리비전을 기록합니다. 아래는 이식 기준이며 현재 애플리케이션 리비전을 뜻하지 않습니다.

원본	이식 기준
이전 프로젝트 저장소	b399b16f3a520692aa64ec282eb21f86c2cb1538
v3	c20624ac6d21

이전 Hub 저장소는 폐지 대상으로 두며 문서·로고·도식은 이 위키에서 관리합니다. v3의 docs는 이동 안내와 아키텍처 이미지를 포함해 제거했습니다. 이식 목록의 이전 경로·리비전은 출처 식별자이며 이전 저장소에 접근할 필요가 없습니다. 이후 문서 변경은 위키 Git 이력으로 관리합니다. v2 감사 manifest는 감사 스크립트가 읽는 입력이므로 v3의 scripts/data/v2-analysis-coverage.json으로 옮겨 코드와 함께 버전 관리합니다. 설명용 분석 범위 페이지는 위키에 있습니다.

이식 목록의 wikiAssets는 로고·아키텍처 PNG의 원본 경로, 위키 경로와 SHA-256을 기록합니다. 개념·실험 주기·구현 도식의 Mermaid 원본도 해당 위키 페이지에 보존합니다.