Telegram Youtube Fetch

전제 조건

1. Telethon 설치: pip install 'telethon>=1.42,<2.0'
2. Telegram API 키: .env에 TELEGRAM_API_ID, TELEGRAM_API_HASH 설정
3. 첫 인증: python3 scripts/fetch_telegram_urls.py --limit 1 수동 실행하여 .session 생성
4. NotebookLM 인증: notebooklm login 완료 상태

Workflow

Step 0: 옵션 파싱

$ARGUMENTS에서 옵션을 파싱한다.

파싱 규칙:

• -l N 또는 --limit N: LIMIT (기본 50)
• -d N 또는 --days N: DAYS (선택)
• -n N 또는 --count N: COUNT (기본 5)
• -f FORMAT 또는 --format FORMAT: FORMAT (기본 blog)
• -t TOPIC 또는 --topic TOPIC: TOPIC (선택)
• --fetch-only: FETCH_ONLY=true
• --process-only: PROCESS_ONLY=true
• --stats: STATS_ONLY=true
• --retry: RETRY=true

Step 1: 분기 처리

--stats인 경우:

python3 scripts/db_manager.py stats

통계를 사용자에게 표시하고 종료.

--retry인 경우:

python3 scripts/db_manager.py retry

리셋 결과를 사용자에게 표시하고 종료.

Step 2: Telegram에서 URL 수집 (--process-only가 아닌 경우)

# .env 파일에서 환경변수 로드
source .env 2>/dev/null || true

# URL 수집 + DB 삽입 (파이프라인)
python3 scripts/fetch_telegram_urls.py --limit {LIMIT} [--days {DAYS}] | python3 scripts/db_manager.py insert

에러 처리:

• fetch_telegram_urls.py가 stderr에 JSON 에러 출력 시 → 사용자에게 에러 내용 표시
• 인증 에러 → "첫 인증이 필요합니다" 안내 + 수동 실행 방법 안내
• FloodWaitError → 대기 시간 안내

수집 결과(inserted/skipped)를 사용자에게 표시.

--fetch-only인 경우: 여기서 pending 목록 표시 후 종료.

python3 scripts/db_manager.py pending --limit 20

Step 3: 미처리 URL 조회

python3 scripts/db_manager.py pending --limit {COUNT}

pending 항목이 없으면 "처리할 URL이 없습니다" 표시 후 종료.

Step 4: youtube-summary 반복 호출

pending URL 목록을 순회하며 각 URL에 대해:

# 4-1. processing 상태로 변경
python3 scripts/db_manager.py processing --video-id {video_id}

4-2. /youtube-summary 스킬을 호출한다:

/youtube-summary {clean_url} [-f {FORMAT}] [-t {TOPIC}]

주의: youtube-summary 스킬을 Skill 도구로 호출한다. 인수로 clean_url과 옵션을 전달.

4-3. 처리 결과에 따라 DB 업데이트:

성공 시:

python3 scripts/db_manager.py done --video-id {video_id} --title "{영상 제목}"

실패 시:

python3 scripts/db_manager.py error --video-id {video_id} --message "{에러 메시지}"

다음 URL로 계속 진행 (fail-forward).

Step 4.5: Wiki Ingest (자동)

각 YouTube 요약 처리 성공 후, .omc/wiki/youtube-insights.md에 핵심 인사이트 1줄을 append한다.

형식:

- YYYY-MM-DD [{주제폴더}]: {영상 제목} — {핵심 인사이트 1줄}

실행 방법: Edit 도구로 youtube-insights.md의 ## 최근 인사이트 섹션 마지막에 append

규칙:

• 20개 초과 시 가장 오래된 항목 삭제 (롤링)
• 기술/업무 관련 인사이트만 기록 (투자/개인 영상은 skip)
• youtube-insights.md가 없으면 자동 생성 (category: pattern, tags: [youtube, insight, learning])

Step 5: 완료 보고

처리 결과를 요약하여 사용자에게 표시:

📊 Telegram YouTube 파이프라인 결과:
- 수집: {inserted}건 새로 추가, {skipped}건 중복
- 처리: {success}건 성공, {failed}건 실패
- DB 현황: (stats 출력)

Step 5.5: Wiki Ingest — youtube-insights.md append (v4 신설)

Step 4에서 youtube-summary 호출이 성공해 13.YouTube에 새 파일을 저장한 직후, 각 파일마다 다음을 수행:

python3 .claude/skills/telegram-youtube-fetch/scripts/append_insight.py \
    "<newly-saved .md path>"

역할:

1. 저장된 파일 frontmatter에서 summary, area, domain, title, created 추출
2. .omc/wiki/youtube-insights.md "## 최근 인사이트" 섹션 상단에 1줄 append:

   - {created} [{area}/{domain}]: [[{basename}]] — {summary 80자 압축}
   

3. Rolling buffer 20개 유지 (초과 시 오래된 항목 제거)
4. area == "Technology" 이면 .omc/wiki/instinct-patterns.md의 "## YouTube 학습" 섹션에도 append (최대 10개 rolling)

실패 처리: append 실패해도 파이프라인 전체를 중단하지 않음 (non-blocking). 오류는 stderr로만 출력.

처리 건수 집계: Step 5 보고 시 insights_added: N 필드 추가.

Step 6: Git 커밋

youtube-summary 스킬이 각 영상마다 커밋하므로 별도 커밋 불필요. 수집만 한 경우(--fetch-only)에는 커밋하지 않음. 주의: Step 5.5 가 수정한 .omc/wiki/ 파일들은 .gitignore 에 포함되어 있으므로 자동 커밋 대상 아님 (의도된 동작).

주의사항

• Telethon 첫 인증: 터미널에서 수동 1회 실행 필요 (전화번호 + 인증코드 입력)
• .session 파일: ~/.config/telegram/reader/에 저장됨, iCloud 동기화 대상 아님
• NotebookLM rate limit: --count 5 기본값은 rate limit 대응
• fail-forward: 한 URL 실패해도 나머지 계속 처리
• 중복 안전: video_id PK로 같은 영상 재수집해도 중복 없음