variet-agent/docs/design/debate-room-v2.md

AI Debate Room — 설계서 v5

확정 구조: Wiki.js 기반 분산 토론 (로컬 파일 I/O 제거)

아키텍처

사용자 (관전/개입/방향지시)
  ↕ Discord #variet-debate
사회자 (variet-agent Bot 내 debate_handler.py + Gemini Flash)
  ├→ Wiki.js에 input-{speaker} 작성 (해설 + 상대 전문)
  ├→ Wiki.js에서 response-{speaker} 읽기
  ├→ Wiki.js working-document 통합 편집 (Flash)
  ├→ Wiki.js round-log append
  ├→ Discord에 발언권 시그널 전송
  ├→ Discord에서 "step XX 종료" 완료 감지
  └→ 합의 판정 → conclude / ask_user / continue
  ↕                    ↕
AG(Gemini)           AG(Opus)
debate-gemini/       debate-opus/

통신 채널

채널	역할
Wiki.js	유일한 콘텐츠 전달 경로 (input, response, WD, round-log)
Discord	양방향 시그널만 (발언권 시작 + "step XX 종료" 감지)

Wiki.js 페이지 구조

/debates/{topic-slug}/
├── control               ← 턴 상태 JSON
├── input-gemini          ← 사회자 → Gemini (해설 + 상대 전문)
├── response-gemini       ← Gemini → 사회자 (AG 답변)
├── input-opus            ← 사회자 → Opus
├── response-opus         ← Opus → 사회자
├── working-document      ← 사회자만 편집 (AG 열람 가능)
├── round-log             ← 전문 기록 append (AG 열람 가능)
└── conclusion            ← 최종 합의

페이지 접근 매트릭스

페이지	사회자 (Bot)	AG-Gemini	AG-Opus
input-{자기}	✍️ Write	👁️ Read	👁️ Read
response-{자기}	👁️ Read	✍️ Write	✍️ Write
working-document	✍️ Write	👁️ Read	👁️ Read
round-log	✍️ Write	👁️ Read	👁️ Read

접근 권한은 GEMINI.md 지시문으로 제어 (Wiki.js 레벨 ACL 아님)

턴 흐름

① response-{speaker} 초기화 (이전 답변 누적 방지)
② Flash: input-{speaker} 생성 (해설 + 상대 전문)
③ Discord 발언권 시그널 전송 ("📥 Round N — input 확인")
④ Discord "step XX 종료" 대기
⑤ Wiki.js에서 response-{speaker} 읽기
⑥ Flash: Working Document 통합 편집
⑦ Round Log append
⑧ 합의 판정 (continue / ask_user / conclude)

프로젝트 구조

소스 관리 (variet-agent 리포)

variet-agent/
├── handlers/debate_handler.py     ← 사회자 (Wiki.js API 사용)
├── tools/wiki_client.py           ← singleByPath 쿼리 지원
└── debate-agent/                  ← AG 프로젝트 소스 관리
    ├── debate-gemini/
    │   ├── GEMINI.md              ← 참여자 행동 규칙
    │   ├── .agent/workflows/start.md ← /start 워크플로우
    │   └── tools/wiki_debate.py   ← Wiki.js 읽기/쓰기 CLI
    └── debate-opus/
        ├── GEMINI.md
        ├── .agent/workflows/start.md
        └── tools/wiki_debate.py

배포 위치

C:\Users\Variet-Worker\Desktop\debate-agent\
├── debate-gemini/     ← AG(Gemini)가 이 폴더를 프로젝트로 열기
│   ├── GEMINI.md
│   ├── .agent/workflows/start.md
│   ├── .env           ← Wiki.js API 키
│   └── tools/wiki_debate.py
└── debate-opus/
    ├── GEMINI.md
    ├── .agent/workflows/start.md
    ├── .env
    └── tools/wiki_debate.py

AG 도구

wiki_debate.py CLI:

python tools/wiki_debate.py read  <page-path>
python tools/wiki_debate.py write <page-path> <content>
python tools/wiki_debate.py write-file <page-path> <file>

주요 변경 이력

버전	날짜	변경 내용
v4.1	2026-03-20	로컬 파일 기반 자동 토론 + Wiki.js 동기화
v5	2026-03-21	Wiki.js 기반 분산 토론 — 로컬 파일 I/O 전면 제거, AG 프로젝트 분리