diff --git a/docs/design/debate-room-v2.md b/docs/design/debate-room-v2.md index 69cbec8..1011c3c 100644 --- a/docs/design/debate-room-v2.md +++ b/docs/design/debate-room-v2.md @@ -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. 컨텍스트 창 관리 — 토론이 길어질 때 히스토리 압축 전략