Variet/variet-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Debate Room 설계서 v4 — 파일 기반 구조, 자동 진행, Wiki 동기화 확정

Browse Source
This commit is contained in:
authentik Default Admin
2026-03-20 06:15:10 +09:00
parent 541764dbae
commit 0508d7be8c
1 changed files with 110 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

270
docs/design/debate-room-v2.md
View File

@@ -1,187 +1,137 @@
# AI Debate Room (회의실) — 설계서 v3
# AI Debate Room — 설계서 v4
## 개요
두 AI (AG + Claude Code)가 **사회자(Gemini Flash)**의 중재 하에 주제를 토론하고, 정교한 문서를 생산하는 시스템.
- **목적**: 구현 전 설계 문서의 품질을 극대화 (교차 검증 + 반론)
- **결과물**: Wiki.js에 축적되는 설계 명세서
- **원칙**: 코드 없음. 문서만 생산. 검증도 문서 수준.
---
> 확정 구조: 파일 기반 토론 + Wiki 동기화
## 아키텍처
```
사용자 (관전/개입/방향지시)
↕ Discord #variet-debate (펜딩 시에만 질문)
사회자 (Gemini CLI Flash)
├→ AG 로컬 폴더에서 response.md 읽기
├→ 상대 AG 로컬 폴더에 input.md 쓰기
├→ 양쪽 wiki/ 폴더 동기화
├→ Wiki.js에 합의 기록
├→ 합의 감지 → Wiki 기록 + 사용자에게 검토 요청
└→ 펜딩 감지 → 사용자에게 질문
↕ ↕
AG(Gemini) AG(Claude/Opus)
debate_gemini/ debate_opus/
```
## 각 AG 로컬 폴더 구조
```
debate_gemini/ debate_opus/
GEMINI.md (참여자 프롬프트) GEMINI.md (참여자 프롬프트)
response.md ← AG가 Output response.md
input.md ← 사회자가 Input input.md
wiki/ ← Wiki 미러링 wiki/
agenda.md agenda.md
working_document.md working_document.md
... ...
```
| 파일 | 작성자 | 소비자 | 용도 |
|------|--------|--------|------|
| `response.md` | AG | 사회자 | AG의 전문 답변 (길이 무제한) |
| `input.md` | 사회자 | AG | 상대 의견 + 사회자 해설 + 방향 지시 |
| `wiki/` | 사회자 | AG | Wiki.js 페이지 미러 (현재 합의 상태) |
| `GEMINI.md` | 사전 세팅 | AG | 참여자 역할 + 행동 규칙 |
## 턴 흐름 (자동 반복)
```mermaid
graph TD
User[사용자 — Discord] -->|자연어 대화| Bot[variet-agent Bot]
Bot -->|턴 관리 + 판단| Mod[사회자 — Gemini Flash via gemini_caller.py]
Mod -->|Discord 경로| AG["AG — Gemini 3.1 Pro High (Antigravity IDE)"]
Mod -->|subprocess| CL["Claude Code CLI (claude -p --resume)"]
AG -->|Discord 응답| Mod
CL -->|stdout JSON| Mod
Mod -->|전문 게시| DC[Discord Thread]
Mod -->|승인 질문| User
Mod -->|wiki_helper.py| Wiki[Wiki.js]
flowchart TD
S[!debate-start 주제] --> M1[사회자: 첫 발언자 선택]
M1 --> W1[input.md 작성 + wiki/ 동기화]
W1 --> D1[Discord 시그널 전송]
D1 --> AG1[AG 발언: response.md 작성]
AG1 --> M2[사회자: response.md 읽기]
M2 --> WIKI[Wiki.js 업데이트]
WIKI --> CHECK{합의 판정}
CHECK -->|대립 중| W2[상대 input.md 작성 + wiki/ 동기화]
W2 --> D2[Discord 시그널]
D2 --> AG2[상대 AG 발언]
AG2 --> M2
CHECK -->|합의| DONE[Wiki 최종 기록 + 사용자 검토 요청]
CHECK -->|펜딩| ASK[사용자에게 질문]
ASK --> USER[사용자 응답]
USER --> W2
```
### 계층별 역할
## 사용자 개입 시점
| 계층 | 모델 | 과금 | 연결 방식 |
|------|------|------|-----------|
| **사회자** | Gemini Flash | 무료 (1000req/일) 또는 `gemini_caller.py` 기존 래핑 | subprocess |
| **토론자 A** | AG (Gemini 3.1 Pro High) | Google AI Pro/Ultra 구독 | Antigravity → Hub WS → Discord Bot (기존 경로) |
| **토론자 B** | Claude Code | Anthropic Pro/Max 구독 | `claude -p --resume --output-format json` (subprocess) |
| **승인자** | 사용자 | - | Discord 메시지/버튼 |
| 상황 | 트리거 | 사회자 행동 |
|------|--------|-----------|
| **합의 완료** | 양쪽 agree 2+ 연속 | Wiki 최종 기록 → Discord에 "검토 요청" |
| **의견 필요** | 양쪽 모두 user_input 요구 | Discord에 질문 → 응답 대기 |
| **중간 업데이트** | N 라운드마다 | Wiki Working-Document 업데이트 + Discord 요약 |
| **사용자 임의 개입** | `!debate-inject 의견` | 다음 턴 input.md에 반영 |
| **방향 전환** | 주제 이탈 감지 | 사회자가 redirect 지시 |
> ⚠️ **과금 핵심**: API 직접 호출 = 토큰 과금. CLI/IDE 사용 = **구독 쿼터**. 양쪽 다 구독 내에서 처리.
## 합의 판정 기준
---
## 연결 상세
### AG (Gemini 3.1 Pro High)
기존 인프라 그대로 사용:
```
variet-agent Bot → Discord 메시지 → AG 수신 → 작업 → Discord 응답
사회자(Flash)가 매 턴 후 판정:
```json
{
"decision": "continue | ask_user | conclude",
"agreement_level": "disagree | partial | agree",
"reason": "판정 근거",
"wiki_update": true/false
}
```
- **도구**: AG 내장 (run_command, view_file, write_to_file, browser 등)
- **MCP**: 불필요 — AG 자체 도구 시스템으로 대체
- **Wiki.js**: ⚠️ **신규 개발 필요** — AG는 Gitea Wiki만 지원. Wiki.js 읽기/쓰기 도구 추가 필요
- 방안 1: AG가 `run_command`로 `wiki_helper.py` 호출
- 방안 2: 사회자가 AG 응답의 `wiki_action` JSON을 받아서 대신 실행
- **세션**: AG는 대화별로 세션 관리됨 (Antigravity IDE 내장)
- `continue`: 자동 다음 턴
- `ask_user`: Discord에 질문 → 응답 올 때까지 대기
- `conclude`: 합의 완료 → Wiki 최종 기록
### Claude Code CLI
```bash
# 기본 호출
claude -p "프롬프트" --output-format json
# 세션 이어가기 (토론 맥락 유지 — 핵심!)
claude --resume SESSION_ID -p "프롬프트" --output-format json
# 시스템 프롬프트 (토론 참여자 역할)
claude -p "프롬프트" --system-prompt "당신은 토론 참여자입니다..."
# 모델 선택
claude -p "프롬프트" --model opus
```
- **과금**: Anthropic Pro/Max 구독 쿼터
- **세션 유지**: `--resume` 플래그로 이전 대화 맥락 자동 유지
- 첫 턴 → 세션 ID 생성
- 이후 턴 → `--resume {session_id}`로 맥락 이어감
- **Wiki.js**: 사회자가 대신 실행 (Claude 응답 JSON의 `wiki_action` 파싱)
- **별도 프로세스**: 사회자(Flash)와 분리 — subprocess로 호출
---
## 핵심 설계 원칙
### 1. 사회자는 전문 전달 (요약 ❌)
사회자는 AI 응답을 **그대로** 상대에게 전달 + 다음을 **추가**:
- 사용자의 어떤 답변에 기반한 의견인지 맥락
- "오류 확인 + 개선점 지적" 지시
- 대화 싱크 불일치 시 방향성 가이드
### 2. 턴 순서 랜덤
매 라운드 발언자 랜덤 선택. 예외:
- 한쪽이 질문 → 상대에게 우선권
- 싱크 불일치 → 사회자가 방향 명시
### 3. 커맨드 없음 — 사회자 자동 판단
`/debate` 같은 커맨드 없음. 자연어 대화에서:
1. 사회자가 "이 주제는 토론이 필요하다" 판단
2. 사용자에게 "회의실을 열까요?" 확인
3. 승인 시 세션 시작
### 4. 검증은 문서 수준만
소스 코드 작성 없음. 설계 가능 여부를 문서 논리로 검증.
---
## 턴 프로토콜
## Wiki.js 구조
```
Phase 0: 준비
사회자 → Wiki.js에 Agenda 페이지 생성 (wiki_helper.py)
사회자 → Discord 쓰레드 생성
사회자 → 첫 발언자 랜덤 선택
사회자 → Claude 세션 초기화 (claude -p --system-prompt)
Phase 1: 발언
사회자 → 선택된 AI에게 주제 + 맥락 + 지시 전달
AG: Discord 메시지로 전달
Claude: claude --resume {sid} -p "..." --output-format json
AI → 응답 전문 + wiki_action (선택)
Phase 2: 사회자 판단
① 응답 전문 → Discord 쓰레드에 게시
AG 응답 = 🟢 초록 Embed
Claude 응답 = 🔵 파랑 Embed
② wiki_action 있으면 → wiki_helper.py 실행 → "📝 Wiki 수정됨" 보고
③ 판단:
자동 진행 → 상대 AI에게 전문 + 방향 지시
사용자 필요 → 승인 요청 (버튼)
주제 이탈 → 리다이렉트
합의 도달 → 결론 정리
Phase 3: 반복 → 종료
합의 / 최대 라운드 / 사용자 중단
→ 사회자가 Wiki.js Conclusion 페이지 정리
/Debates/{주제}/
Agenda ← 토론 의제 + 범위
Working-Document ← 진행 중 합의 사항 (라이브)
Round-Log ← 라운드별 요약 기록
Conclusion ← 최종 합의 (종료 후)
```
---
- 사회자만 Wiki 쓰기 권한
- 매 라운드 후 Working-Document 업데이트
- AG는 로컬 `wiki/` 폴더에서 읽기만
## Wiki.js 문서 구조
## Discord 채널 역할
```
/Debates/{주제명}/
Agenda ← 사회자 생성
Working-Document ← 양쪽 AI 공동 편집 (사회자 경유)
Round-Log ← 전체 턴 기록 (자동 축적)
Conclusion ← 최종 합의
```
| 채널 | 용도 |
|------|------|
| `#variet-debate` | 사용자 커맨드 + 요약 게시 + 승인 요청 |
| `#ag-debate_gemini` | AG(Gemini)에게 시그널 전송 |
| `#ag-debate_opus` | AG(Opus)에게 시그널 전송 |
Wiki 수정 흐름:
```
AI 응답 JSON: { "opinion": "...", "wiki_action": { "page": "...", "content": "..." } }
→ 사회자가 wiki_action 파싱
→ wiki_helper.py update "페이지" "내용"
→ Discord에 변경 보고
```
Discord 메시지는 **시그널 용도**만. 전문은 모두 로컬 파일로 전달.
> ⚠️ Wiki 수정 권한은 사회자가 통제. AI가 직접 수정하지 않음.
## 과금 구조 (변경 없음)
---
| 역할 | 모델 | 과금 |
|------|------|------|
| 사회자 | Gemini Flash (CLI) | 무료/구독 쿼터 |
| 토론자 A | AG (Gemini 3.1 Pro) | 구독 쿼터 |
| 토론자 B | AG (Claude Opus) | 구독 쿼터 |
## 신규 개발 필요 항목
## 구현 파일
| 모듈 | 역할 | 우선순위 |
|------|------|---------|
| `handlers/debate_handler.py` | 세션 관리, 턴 라우팅, 상태 머신 | 필수 |
| `tools/claude_caller.py` | `claude -p --resume` subprocess 래핑 | 필수 |
| `prompts/debate_moderator.md` | 사회자 프롬프트 (판단 기준, 전달 형식) | 필수 |
| `prompts/debate_participant.md` | 참여자 프롬프트 (응답 JSON 형식, wiki_action 가이드) | 필수 |
| AG Wiki.js 도구 | AG가 Wiki.js 읽기/쓰기 | 선택 (사회자 경유 가능) |
---
| 파일 | 역할 |
|------|------|
| `handlers/debate_handler.py` | 세션 관리, 파일 읽기/쓰기, 턴 관리 |
| `prompts/debate/participant_base.md` | AG 참여자 프롬프트 (→ GEMINI.md로 복사) |
| `prompts/debate/moderator.md` | 사회자 프롬프트 |
| `api/discord_bot.py` | 커맨드 + AG 메시지 감지 |
| `tools/wiki_helper.py` | Wiki.js 연동 |
## 미결 사항
- [ ] AG 응답 트리거 방식 구체화 — AG에게 Discord 메시지를 보내면 어떤 채널에서 응답이 오는지
- [ ] Claude `--resume` 세션 ID 관리 — 세션 파일 저장 위치 + 만료 정책
- [ ] 토론 히스토리 컨텍스트 윈도우 — 장기 토론 시 AG/Claude 컨텍스트 초과 대응
- [ ] 사회자의 "토론 필요" 감지 프롬프트 설계 — unified.md에 debate 모드 추가
- [ ] Wiki Working-Document 동시 편집 충돌 방지 — 한 턴에 한 AI만 수정
1. AG가 `response.md`에 쓰라는 지시를 **확실히 따르는지** 검증 필요
2. UTF-8 인코딩 — `debate_handler.py`에서 파일 읽기/쓰기 시 명시
3. Wiki.js 페이지 → 로컬 폴더 동기화 함수 구현 (`wiki_helper.py`)
4. 합의 판정 Flash 프롬프트 정교화
5. 컨텍스트 창 관리 — 토론이 길어질 때 히스토리 압축 전략