# task-587.1 완료 보고서: 멀티모델 텔레그램 봇 서버 구축

## SCQA

**S**: 기존 Claude 봇(cokacdir)이 텔레그램에서 단독 AI 모델로 운영 중이며, 그룹챗에서 다양한 AI 모델 간 논의를 위해 Gemini와 Codex CLI 기반 봇 서버가 필요하다.

**C**: Gemini CLI(v0.31.0, OAuth 완료)와 Codex CLI(v0.106.0, 미로그인) 두 개의 이기종 CLI를 텔레그램 봇으로 래핑해야 하며, 그룹챗에서 봇 간 무한 루프 방지, 메시지 분할, 타임아웃 처리 등 다양한 엣지 케이스를 안전하게 처리해야 한다.

**Q**: 두 CLI를 각각 독립 텔레그램 봇으로 래핑하여, 그룹챗에서 안전하고 안정적인 멀티모델 논의 환경을 구축할 수 있는가?

**A**: `python-telegram-bot` v22.6 기반으로 Gemini/Codex 봇 서버 2개를 구축 완료. engine.py에서 CLI 래핑(shell=True 금지, 인젝션 방지), bot_utils.py에서 공통 로직(should_respond, split_message, send_response) 분리, 그룹챗 루프 방지(is_bot 체크), 타임아웃 처리(120초), 메시지 분할(4096자), Codex 미로그인 graceful 처리 구현. pytest 47건 전체 통과, pyright 에러 0건.

## 생성/수정 파일 목록

- `/home/jay/workspace/services/multimodel-bot/config.py` — 환경변수 로드, 상수 정의
- `/home/jay/workspace/services/multimodel-bot/engine.py` — CLI 래핑 (call_gemini, call_codex)
- `/home/jay/workspace/services/multimodel-bot/bot_utils.py` — 공통 봇 유틸리티 (should_respond, split_message, send_response)
- `/home/jay/workspace/services/multimodel-bot/gemini_bot.py` — Gemini 텔레그램 봇
- `/home/jay/workspace/services/multimodel-bot/codex_bot.py` — Codex 텔레그램 봇
- `/home/jay/workspace/services/multimodel-bot/requirements.txt` — 의존성 목록
- `/home/jay/workspace/services/multimodel-bot/start.sh` — 동시 실행 스크립트
- `/home/jay/workspace/services/multimodel-bot/gemini-bot.service` — systemd 서비스 파일
- `/home/jay/workspace/services/multimodel-bot/codex-bot.service` — systemd 서비스 파일
- `/home/jay/workspace/services/multimodel-bot/pyrightconfig.json` — pyright 설정
- `/home/jay/workspace/services/multimodel-bot/README.md` — 사용법 문서
- `/home/jay/workspace/services/multimodel-bot/tests/__init__.py` — 테스트 패키지
- `/home/jay/workspace/services/multimodel-bot/tests/test_config.py` — config 테스트 (9건)
- `/home/jay/workspace/services/multimodel-bot/tests/test_engine.py` — engine 테스트 (16건)
- `/home/jay/workspace/services/multimodel-bot/tests/test_bot_logic.py` — 봇 로직 테스트 (22건)

## 테스트 결과

- **pytest**: 47건 전체 PASS (0.13초)
  - test_config: 9 PASSED (토큰 로드, 기본값, 누락 시 KeyError)
  - test_engine: 16 PASSED (call_gemini 7건, call_codex 9건)
  - test_bot_logic: 22 PASSED (응답 조건 9건, 메시지 분할 10건, send_response 3건)
- **pyright**: 에러 0건, 경고 0건
- **black + isort**: 포매팅 적용 완료

## 발견 이슈 및 해결

### 자체 해결 (4건)

1. **pyright: update.message Optional 접근** — bot_utils.py의 send_response에서 `update.message`가 None일 수 있는 문제. None 체크 가드 추가로 해결 (`bot_utils.py:112-113`)
2. **pyright: update.effective_chat Optional 접근** — gemini_bot.py, codex_bot.py에서 `update.effective_chat.id`가 None 가능. 변수 추출 + None 체크로 해결 (`gemini_bot.py:43-47`, `codex_bot.py:43-47`)
3. **pyright: config 모듈 import symbol 미인식** — pyright가 workspace 루트에서 실행되어 `config.py` 모듈을 찾지 못하는 문제. `pyrightconfig.json`에 `extraPaths: ["."]` 추가 및 config.py에 타입 어노테이션 + `__all__` 추가로 해결
4. **python-telegram-bot 미설치** — pip3 시스템 패키지 제한으로 `--break-system-packages` 플래그 필요. 설치 완료 (v22.6)

### 범위 외 미해결 (1건)

1. **Codex CLI 미로그인 상태** — `codex login` 필요. 봇에서 미로그인 시 안내 메시지를 반환하도록 구현 완료. 실제 로그인은 수동 작업 필요. 범위 외 사유: 사용자 인증 절차로 자동화 불가.

## QC 자동 검증 결과

- **overall**: WARN (PASS 기준 충족, .done 생성됨)
- file_check: PASS (9/9 파일 존재)
- data_integrity: PASS
- test_runner: PASS (47 passed in 0.11s)
- tdd_check: PASS (테스트 3개, 구현 5개)
- pyright_check: WARN (QC 스크립트가 workspace 루트에서 실행하여 로컬 relative import 해석 불가. 로컬에서 `cd multimodel-bot && pyright` 실행 시 에러 0건 확인)
- style_check: WARN (QC의 isort 설정과 로컬 isort 설정 차이. 로컬에서 black+isort 적용 완료)
- critical_gap: PASS

## 비고

- systemd 서비스 파일은 `/home/jay/workspace/services/multimodel-bot/` 에 생성. 실제 배포 시 `sudo cp *.service /etc/systemd/system/` 필요
- 토큰은 환경변수(`/home/jay/workspace/.env.keys`)에서만 로드. 하드코딩 없음
- subprocess 호출 시 shell=True 금지, 리스트 전달로 명령어 인젝션 방지
- Gemini CLI: `--yolo --approval-mode yolo` 옵션으로 비대화식 모드 보장