variet-agent/.agent/references/known-issues.md

Known Issues & Lessons Learned

이 파일은 SSOT(Single Source of Truth)입니다. 디버깅이나 구현 전에 반드시 이 파일을 확인하세요. 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.

---

포맷

각 항목은 아래 형식을 따릅니다:

### [날짜] [키워드] — 한줄 요약
- **증상**: 무엇이 잘못되었는가
- **원인**: 근본 원인
- **해결**: 올바른 해결 방법
- **주의**: 재발 방지를 위한 교훈

---

공통 이슈

[2026-03-08] PowerShell curl — Invoke-WebRequest 충돌

• 증상: curl 명령이 예상과 다른 응답 형식을 반환
• 원인: PowerShell에서 curl은 Invoke-WebRequest의 별칭
• 해결: **curl.exe**를 명시적으로 사용
• 주의: HTTP 관련 모든 명령에서 curl.exe 사용 필수

[2026-03-08] PowerShell npm — 실행 정책 오류

• 증상: npm run 명령이 실행 정책 관련 오류로 실패
• 원인: PowerShell 스크립트 실행 정책이 제한적으로 설정됨
• 해결: cmd /c npm run dev 형식으로 cmd를 통해 실행
• 주의: npm 관련 명령은 항상 cmd /c 접두어 사용 권장

---

프로젝트별 이슈

아래에 프로젝트 특화 이슈를 추가하세요.

[2026-03-08] nas_scanner docstring — Unicode escape SyntaxError

• 증상: from tools.nas_scanner import NasScanner 시 SyntaxError: (unicode error) 'unicodeescape' codec can't decode \N
• 원인: docstring 내 \\NasData 경로에서 \N이 Python Unicode named escape로 해석
• 해결: docstring을 r"""...""" (raw string)으로 변경
• 주의: Windows 경로(\\, \N, \U 등)가 포함된 docstring은 반드시 r"""로 작성

[2026-03-08] title_matcher _kata_to_hira — 장음기호 깨짐

• 증상: フリーレン → ふり゜れん (ー가 ゜로 변환)
• 원인: 카타카나 범위 0x30A0~0x30FF에 기호 문자(ー U+30FC) 포함
• 해결: 범위를 0x30A1~0x30F6으로 좁혀 실제 문자만 변환
• 주의: 유니코드 범위 지정 시 기호/구두점 문자 포함 여부 확인 필수

[2026-03-08] anime_pipeline — Nyaa 검색 0건 반환

• 증상: 한자 포함 원제의 로마자 변환 결과(葬送nofuriren) + suffix 고정으로 Nyaa 검색 실패
• 원인: 단일 검색 전략, suffix(ASW HEVC) 항상 부착
• 해결: 6단계 fallback 전략 (romaji±suffix → 원제±suffix → 한글±suffix)
• 주의: 외부 API 검색 시 반드시 다중 전략 + suffix 토글 구현

[2026-03-15] _extract_episode — v2/S01E10 패턴 미인식 → 중복 다운로드

• 증상: NAS에 ep9, 10이 있는데 재다운로드. ASW - 10v2 릴리스 에피소드 추출 실패
• 원인: 정규식 [-–]\s*(\d{1,4})(?:\s|$|\.|\[)이 v2 접미사 미처리. S01E10은 하이픈 패턴이 S01의 01을 먼저 매칭
• 해결: (1) SxxExx 패턴을 최우선 체크, (2) (?:v\d)? 추가로 version suffix 허용, (3) \( 추가로 SubsPlease 포맷 지원
• 주의: 에피소드 추출 정규식 수정 시 반드시 v2/v3 릴리스 + SxxExx + 한글(N화) + false positive(29-sai) 테스트 포함

[2026-03-15] _add_torrents — 릴리스 그룹 불일치 다운로드

• 증상: NAS에 [ASW] HEVC 파일(~300MB)만 있는데 CR WEB-DL DUAL(1.4GB) 릴리스를 다운
• 원인: 스코어링이 ASW에 +100을 주지만, ASW 릴리스가 없는 에피소드에서 아무 릴리스나 선택
• 해결: NAS 기존 파일의 릴리스 그룹([ASW])을 감지하여 같은 그룹만 허용. 매칭 없으면 스킵
• 주의: Nyaa 토렌트 제목에 영어+일본어 제목이 모두 포함되어 키워드 필터만으로는 불충분

[2026-03-15] _download_subtitles — 기존 자막 덮어쓰기 위험

• 증상: 이미 수동으로 배치한 자막 파일을 Anissia 자막으로 덮어쓸 수 있음
• 원인: 기존 자막 파일 존재 여부를 확인하지 않고 전 에피소드 자막 다운로드 시도
• 해결: NAS 폴더의 기존 자막 파일을 에피소드별로 스캔, 이미 있으면 스킵
• 주의: 자막 처리 시 사용자 수동 입력 파일의 보존을 항상 고려

[2026-03-15] Wiki.js GraphQL — update mutation에 tags 누락 시 에러

• 증상: update_page() 호출 시 Cannot read properties of undefined 백엔드 에러
• 원인: Wiki.js update mutation이 tags 파라미터 생략 시 내부적으로 undefined 처리하여 crash
• 해결: update_page()에서 tags가 None이면 get_page()로 기존 tags를 먼저 조회하여 항상 전달
• 주의: Wiki.js GraphQL mutation은 optional로 보이는 필드도 생략 시 에러 가능. 항상 모든 필드를 명시적으로 전달

[2026-03-16] main.py StreamHandler — cp949 콘솔에서 한글/특수문자 UnicodeEncodeError

• 증상: 봇 기동 시 UnicodeEncodeError: 'cp949' codec can't encode character '\u2014' 로 프로세스 비정상 종료
• 원인: logging.StreamHandler(sys.stdout) 기본값이 시스템 인코딩(cp949) 사용. 로그 메시지의 em-dash(—) 등 유니코드 문자가 인코딩 불가
• 해결: io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")로 StreamHandler를 UTF-8 고정
• 주의: Windows 한글 환경에서 모든 콘솔 출력에 cp949 인코딩 문제 발생 가능. subprocess.run도 encoding="utf-8", errors="replace" 명시 필수

[2026-03-16] workspaces.json — 다른 PC 사용자 경로로 봇 기동 실패

• 증상: [WinError 267] 디렉터리 이름이 올바르지 않습니다 — Gemini agent 호출 시 cwd 오류
• 원인: workspaces.json의 path가 다른 PC의 사용자 경로(c:\Users\Certes\...)로 하드코딩
• 해결: 현재 머신의 사용자 경로(c:\Users\Variet-Worker\...)로 수정
• 주의: 멀티 환경 배포 시 workspaces.json의 절대 경로가 환경별로 다를 수 있음. 상대 경로 또는 환경변수 사용 고려

[2026-03-18] config.py — .env 값의 따옴표가 값에 포함됨

• 증상: .env에 KEY="val,ue" 형식으로 쓰면 비밀번호에 " 따옴표가 포함되어 인증 실패
• 원인: config.py의 수동 .env 파서가 value.strip()만 하고 따옴표를 제거하지 않음
• 해결: 양쪽 따옴표("..." 또는 '...') 감지 후 제거하는 로직 추가
• 주의: .env에 특수문자(,, &, # 등) 포함 비밀번호는 반드시 따옴표로 감싸야 함

[2026-03-18] Mailcow IMAP — 앱 비밀번호 LOGIN 커맨드 거부

• 증상: imaplib.login() 호출 시 AUTHENTICATIONFAILED — 비밀번호 맞는데도 실패
• 원인: Mailcow 앱 비밀번호는 IMAP LOGIN 커맨드를 거부하고 PLAIN 인증만 지원
• 해결: conn.authenticate("PLAIN", lambda x: ("\0" + user + "\0" + pw).encode()) 사용
• 주의: 일반 계정 비밀번호는 LOGIN도 가능하지만, 앱 비밀번호는 반드시 PLAIN auth 필요