# 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 프로젝트 분리 |