runesleo/x-reader

x-reader란 무엇인가?

x-reader는 Python 기반의 Agent Skill 및 명령줄 도구로, URL 뒤에 있는 실제 콘텐츠를 가져옵니다. 검색 엔진이나 소셜 미디어 플랫폼이 보여주는 미리보기만 가져오는 것이 아닙니다. X/Twitter, YouTube, 팟캐스트, WeChat, RSS 등 다양한 온라인 소스와 함께 작동하며, AI 에이전트에게 전체 소스를 읽었는지, 일부만 읽었는지, 또는 가져오지 못했는지를 알려줍니다.

작동 방식

URL → 플랫폼별 페처(fetcher) – 지원되는 각 사이트에는 정식 소스를 검색하는 방법을 아는 작은 모듈(예: twitter.py, youtube.py)이 있습니다. 예를 들어 oEmbed를 통한 트윗 텍스트, yt-dlp를 통한 YouTube 트랜스크립트, Bilibili 자막 등입니다.
증거 계약(Evidence contract) – 가져오기 후 도구는 네 가지 상태 중 하나를 반환합니다:
- PASS – 답변에 필요한 모든 것이 읽혔습니다.
- PARTIAL – 일부 미디어 레이어(비디오, 오디오, 자막)가 누락되었습니다.
- FAIL – 페이지를 안정적으로 가져올 수 없습니다.
- UNKNOWN – 검색된 자료가 모호합니다.
CLI / JSON 출력 – x-reader <url>은 간단한 사람이 읽을 수 있는 요약을 출력합니다. --json을 추가하면 AI 에이전트가 사용할 수 있는 기계가 읽을 수 있는 페이로드를 제공합니다.
선택적 MCP 서버 – 가벼운 HTTP 서버(mcp_server.py)는 동일한 기능(read_url, detect_platform 등)을 노출하여 Claude Code와 같은 에이전트가 도구를 원격으로 호출할 수 있게 합니다.

"소스 우선"이 중요한 이유

에이전트는 종종 검색 스니펫이나 트윗 캡션을 인용하여 질문에 답변하는데, 이는 중요한 미디어(비디오, 자막, 유료 텍스트)를 누락할 수 있습니다. x-reader는 이러한 격차를 명확히 하여 환각을 방지하고 사용자가 정확히 어떤 증거를 사용할 수 있는지 알 수 있게 합니다.

주요 기능(README에 설명된 대로)

기능	설명
다중 플랫폼 지원	X/Twitter, YouTube, Bilibili, WeChat, Xiaohongshu, Telegram, RSS, 일반 웹 기사, Apple Podcasts 등
미디어 처리	첨부된 비디오, 자막을 검색하고 Groq Whisper(`whisper-large-v3`)로 오디오를 전사할 수 있습니다.
CLI	빠른 확인을 위한 `x-reader <url>`; 자체 테스트를 위한 `x-reader doctor`; 구조화된 출력을 위한 `--json`.
Agent Skill	`npx skills add runesleo/x-reader --skill x-reader`로 설치 가능; 설치 없이 스킬을 나열할 수 있습니다.
MCP 서버	원격 호출을 위한 선택적 FastMCP 호환 서버(`x-reader-mcp`).
보안 모델	가져온 모든 데이터를 신뢰할 수 없는 것으로 취급하고, 실행하지 않으며, 명시적으로 동의하지 않는 한 쿠키를 격리합니다.
확장 가능한 Python 라이브러리	프로그래밍 방식 사용을 위한 `UniversalReader` 클래스(`await reader.read(url)`).
증거 계약	각 가져오기에 대한 명시적 `PASS / PARTIAL / FAIL / UNKNOWN` 상태.

누가 사용할까요?

AI 에이전트 개발자 – 모델이 답변하기 전에 실제로 원본 소스를 참조했는지 증명할 수 있는 신뢰할 수 있는 방법이 필요한 경우.
연구자 – 어떤 미디어 레이어가 소비되었는지 추적해야 하는 검색 증강 생성 파이프라인을 구축하는 경우.
고급 사용자 – 트윗, 비디오 또는 기사의 전체 콘텐츠를 다운로드하고 확인할 수 있는 CLI를 원하는 경우.

설치 스냅샷

# 저장소에서 CLI 직접 설치
pip install "x-reader @ git+https://github.com/runesleo/x-reader.git"
# 선택적 브라우저 폴백(Playwright) 및 미디어 도구
pip install "x-reader[browser] @ git+https://github.com/runesleo/x-reader.git"
playwright install chromium

라이선스

MIT – 개인 및 상업적 사용에 무료입니다.

위의 모든 세부 사항은 저장소의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.