# task-590.1 완료 보고서: 멀티모델 봇 토론 기능 + Gemini SDK 전환

## SCQA

**S**: `/home/jay/workspace/services/multimodel-bot/` 의 3개 텔레그램 봇(잼민이/코덱스/클로디)이 각각 독립 프로세스로 운영 중이며, Gemini 봇은 CLI subprocess 호출(매 요청 13초)을 사용한다.

**C**: CLI 호출의 Node.js 런타임 오버헤드(13초/건)로 응답 지연이 심각하고, 봇 간 상호작용(토론) 기능이 없어 사용자가 여러 AI의 의견을 동시에 비교할 수 없다.

**Q**: Gemini를 Python SDK로 전환하여 응답 시간을 단축하고, 봇 간 라운드 로빈 토론 기능을 추가할 수 있는가?

**A**: Google Code Assist REST API(`cloudcode-pa.googleapis.com`) 직접 호출로 전환하여 응답 시간 13초 → 0.9초 달성(14.4배 개선). DiscussionManager를 통한 라운드 로빈 토론, 5분 idle 정지, 시간 한정 모드를 구현. pytest 80건 전체 통과, pyright 에러 0건.

## 생성/수정 파일

- `engine.py` — call_gemini() CLI→REST API 전환 (aiohttp + OAuth 자동 refresh)
- `bot_utils.py` — should_respond() 자기 봇만 무시, 타봇 메시지 허용
- `discussion_manager.py` (신규) — DiscussionManager, parse_duration, DiscussionState
- `main_bot.py` (신규) — 3봇 통합 프로세스, trigger_next_bot_response
- `gemini_bot.py` — handle_message에 dm 파라미터 추가, 토론 턴 트리거
- `codex_bot.py` — 동일 패턴 수정
- `claude_bot.py` — 동일 패턴 수정
- `tests/test_engine.py` — call_gemini SDK 기반 10개 테스트
- `tests/test_discussion_manager.py` (신규) — parse_duration 11개 + DiscussionManager 15개 + should_respond 3개 = 29개 테스트
- `tests/test_bot_logic.py` — 타봇 응답 허용 테스트 수정 + 자기봇 무시 테스트 추가
- `tests/test_config.py` — CLAUDE_BOT_TOKEN 환경변수 누락 버그 수정

## 테스트 결과

- pytest: **80 passed** in 0.40s (기존 47 → 80, +33개 추가)
- pyright: **0 errors** (프로젝트 디렉토리 기준)
- black/isort: 전체 통과
- 실제 SDK 호출: 0.9초 응답 확인 (Project ID 캐시 시)

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **OAuth 스코프 불일치** — `google.generativeai` SDK는 `generativelanguage.googleapis.com` 스코프 요구하나, Gemini CLI OAuth는 `cloud-platform` 스코프 사용. Code Assist API(`cloudcode-pa.googleapis.com/v1internal`) 직접 호출로 해결.
   - 수정: engine.py 전체 재작성 (aiohttp REST 호출)
2. **모델명 오류** — 팀원이 `gemini-3.1-pro-preview`로 설정했으나 작업 지시는 `gemini-2.5-flash`. 수정 완료.
   - 수정: engine.py:21
3. **test_config.py CLAUDE_BOT_TOKEN 누락** — config.py에 CLAUDE_BOT_TOKEN이 추가된 이후 테스트에서 해당 환경변수 미설정하여 .env.keys 없이 실행 시 실패.
   - 수정: tests/test_config.py 전체 테스트에 CLAUDE_BOT_TOKEN monkeypatch 추가

### 범위 외 미해결 (1건)
1. **pyright reportMissingImports** — run_pyright.sh 스크립트가 프로젝트 cwd가 아닌 다른 디렉토리에서 실행될 때 sibling import를 resolve하지 못함. pyrightconfig.json의 `extraPaths` 설정은 프로젝트 디렉토리 기준으로만 동작. QC 인프라 수정 필요(범위 외).

## 실행 방법

### 통합 프로세스 (권장)
```bash
source /home/jay/workspace/.env.keys
cd /home/jay/workspace/services/multimodel-bot
python3 main_bot.py
```

### 단독 실행 (기존 방식, 토론 기능 없음)
```bash
python3 gemini_bot.py  # 잼민이만
python3 codex_bot.py   # 코덱스만
python3 claude_bot.py  # 클로디만
```

## QC 결과

- **Gate**: PASS
- **Summary**: 5 PASS, 3 SKIP, 2 WARN
- pytest: 80 passed in 0.40s
- pyright: 0 errors (프로젝트 디렉토리 기준)
- black: 통과
- isort: WARN (QC 인프라가 프로젝트 외부에서 실행 시 경로 문제, 프로젝트 내 실행 시 통과)
- pyright (QC): WARN (동일 경로 문제)

## 완료 정보

- **소요 시간**: 24분 29초
- **완료 시각**: 2026-03-15T15:54:58