soia-pkm-clip-x

soia-pkm-clip-x은(는) 무엇을 하나요?

X의 가치 있는 콘텐츠를 Obsidian Vault에 담아 검색 가능한 지식 자산으로 구축합니다.

개요

X의 기본 UI는 장기적인 검토에 적합하지 않습니다. 스레드는 타임라인에 흩어지고, Article은 레이아웃이 깨지고, 링크는 쉽게 사라지며, 검색 기능도 부족합니다. 이 스킬은 X의 고품질 긴 콘텐츠를 한 번에 Obsidian에 담아냅니다:

• 스레드 전체 unroll
• X Article의 전체 content.blocks 확보
• 메타데이터 완벽 (작성자, 메트릭스, 미디어 직접 링크, created_at)
• frontmatter 주제 양방향 링크로 MOC 집계 용이
• 다국어 인식 (한국어 / 영어 / 일본어 / 중국어)

사전 요구사항

• Obsidian vault (모든 구조 가능)

• Python 3, 순수 stdlib만 사용 (서드파티 종속성 없음, 단일 트윗 보관용)

• 선택 사항: pip install telethon (MTProto 동기화 전용)

• 환경 변수 설정:

  export OBSIDIAN_VAULT=~/Documents/MyVault
  # 선택 사항: 보관 하위 디렉토리 (기본값 "Articles")
  export OBSIDIAN_ARTICLES="Articles"
  # 선택 사항: 섹션 제목 언어, 기본값 ko (한국어), en 설정 시 영어 제목 사용
  export X_ARCHIVE_LANG=ko
  

핵심 API: fxtwitter

X URL의 x.com을 api.fxtwitter.com으로 바꾸고 GET 요청으로 JSON을 직접 가져옵니다. X API 키, 로그인, 비용이 전혀 들지 않습니다.

주요 필드	용도
tweet.text / tweet.raw_text.text	트윗 본문
tweet.article.title	X Article 제목
tweet.article.content.blocks[]	Article 본문 blocks
tweet.replying_to_status	이전 트윗 (스레드 역추적)
tweet.quote	인용 트윗
tweet.media[]	미디어 (이미지/비디오 직접 링크)
tweet.created_timestamp	UNIX 타임스탬프
tweet.views / likes / bookmarks / retweets	메트릭스

폴백: fxtwitter 실패 → cdn.syndication.twimg.com 공개 엔드포인트.

트리거 명령어

사용자 명령	호출
"이 X 보관: URL" / "archive this: URL"	archive_x.py <URL>, 비중국어 콘텐츠는 아래 워크플로 4단계에 따라 자동으로 한국어 요약 추가 (별도로 "번역"을 말할 필요 없음)
"이 스레드 정리: URL"	위와 동일, 강제 스레드 역추적
"내 텔레그램 저장 메시지 동기화" + JSON 경로 제공	sync_telegram_export.py <path> --dry-run 으로 미리 보고 확인 후 실제 실행
"API로 텔레그램 동기화" (이미 자격 증명 있음)	sync_telegram_saved.py

워크플로 (기본 보관)

1. URL 파싱 → handle + status_id
2. 스크립트 archive_x.py <URL> 호출
3. 스크립트가 vault에 이미 보관되었는지 확인 (frontmatter url: 필드 기준)
   • 이미 존재함 → SKIP 출력, 종료
   • 그렇지 않음 → fxtwitter 가져오기, vault에 쓰기
4. AI가 이후에 추가:
   • 1문장 한국어 ## 요약
   • 1-3개의 topics 위키링크 + people 위키링크
   • 비한국어 콘텐츠 (language가 ko가 아닌 경우): ## 한국어 요약 섹션을 완전한 요약으로 자동 추가, 사용자가 별도로 "번역"을 요청할 필요 없음. 의역(paraphrasing) 방식으로 직역하지 않음——기계 번역 느낌이 아닌, 사람이 쓴 듯한 자연스러운 한국어가 되도록 함; 고유명사, 제품명, 코드/명령어/API 파라미터는 영문 원본을 유지하고, 서술적인 문장과 설명만 번역
5. "내 생각" 섹션은 항상 사용자가 직접 작성하도록 비워 둠

Telegram 동기화 두 가지 방법

A. JSON 내보내기 (권장, 위험 없음)

Telegram Desktop
  → 설정 → 고급 → Telegram 데이터 내보내기
  → "비공개 채팅" 체크 + JSON 형식 선택
  → result.json 파일 획득

python3 sync_telegram_export.py <result.json> --dry-run   # 목록 확인
python3 sync_telegram_export.py <result.json>             # 실제 실행

URL 기준으로 자동 중복 제거, 이미 보관된 건 자동 건너뜀. 월 1회 내보내기로 증분 동기화 가능.

B. MTProto API (고급, 중국 사용자는 주의)

필요 사항:

• https://my.telegram.org/auth에서 api_id / api_hash 신청
• generate_telegram_session.py 실행하여 session_string 획득
• 주거용 IP (중국 본토 사용자는 반드시 홍콩/일본의 주거용 IP 대역 사용, 데이터센터 IP는 ERROR 발생)

⚠️ 중국 사용자는 우선적으로 방법 A 사용. my.telegram.org에서 앱을 생성하는 것은 중국 본토에서 거의 확실히 IP 차단을 유발하며, 반복 시도 시 계정 수준의 24-72시간 동결이 발생할 수 있습니다.

파일명

<YYYY-MM-DD>-X-<handle>-<제목 앞 50자>.md

예시:

• 2026-05-24-X-cyrilXBT-How-to-Organize-Your-Obsidian-Vault.md
• 2026-05-29-X-ObsidianOtaku-保存版AIエージェントのためのObsidian活用術.md

같은 날 같은 작성자 여러 개 → 끝에 -<status_id 뒤 6자리> 추가.

출력 frontmatter

---
tags: [글발췌]
source: X
url: https://x.com/<handle>/status/<id>
author: <표시이름>
handle: "@<handle>"
published_at: YYYY-MM-DD HH:mm
captured_at: YYYY-MM-DD HH:mm
language: ko / en / ja / zh
type: tweet / thread / article
topics: ["[[xxx]]", ...]   # AI 작성
people: ["[[xxx]]", ...]   # AI 작성
media: [...] / 0
content_complete: true
metrics:
  views: N
  likes: N
  bookmarks: N
---

경계 및 예외 처리

상황	처리
fxtwitter가 404 반환	트윗 삭제/비공개, archive.org 확인 권장
fxtwitter 5xx	1회 재시도, 실패 시 syndication 엔드포인트로 폴백
URL이 x.com / twitter.com 아님	거부, Web Clipper 사용 권장
트윗 텍스트가 비어 있고 article도 media도 없음	경고: "순수 리트윗/순수 답글, 독립 콘텐츠 없을 수 있음"
같은 날 같은 작성자 파일명 중복	끝에 -<status_id 뒤 6자리> 추가
비디오 미디어	frontmatter media[]에 mp4 직접 링크 기록, 내장하지 않음

명령줄 참조

# 단일 트윗 보관
python3 archive_x.py <URL>
python3 archive_x.py <URL> --force                  # 이미 보관된 항목 덮어쓰기
python3 archive_x.py <URL> --vault /path/to/vault   # 환경 변수 덮어쓰기

# Telegram JSON 내보내기 동기화
python3 sync_telegram_export.py <result.json>
python3 sync_telegram_export.py <result.json> --dry-run
python3 sync_telegram_export.py <result.json> --since 2026-06-01
python3 sync_telegram_export.py <result.json> --limit 30

# MTProto 동기화 (먼저 설정 필요)
python3 generate_telegram_session.py    # 일회성
python3 sync_telegram_saved.py --dry-run
python3 sync_telegram_saved.py --days 30
python3 sync_telegram_saved.py --all