# 🦞 OpenClaw DeepReader

> **OpenClaw 에이전트의 기본 웹 콘텐츠 게이트웨이.** X (Twitter), Reddit, YouTube 및 모든 웹페이지 읽기 — 제로 설정, 제로 API 키.

DeepReader는 [OpenClaw](https://github.com/anthropics/openclaw) 에이전트 프레임워크의 내장 콘텐츠 리더입니다. 대화에 URL을 붙여넣으면 DeepReader가 자동으로 가져오고, 파싱하고, 고품질 Markdown을 에이전트의 장기 메모리에 저장합니다. 소셜 미디어와 현대 웹을 위해 설계되었습니다.

🌍 **번역**: [English](README.md) · [中文](README_zh.md) · [Español](README_es.md) · [日本語](README_ja.md) · [العربية](README_ar.md) · [Français](README_fr.md)

---

## ⚡ 설치

```bash
npx clawhub@latest install deepreader
```

또는 수동 설치:

```bash
git clone https://github.com/astonysh/OpenClaw-DeepReeder.git
cd OpenClaw-DeepReeder
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
```

---

## 🎯 사용 시나리오

- **트윗, 스레드 또는 X 아티클**을 읽어서 OpenClaw 메모리에 추가해야 할 때
- **Reddit 게시물**을 인기 댓글과 토론 컨텍스트와 함께 수집해야 할 때
- **YouTube 자막**을 나중에 참조하거나 분석하기 위해 저장하고 싶을 때
- **블로그, 기사 또는 문서 페이지**를 깔끔한 Markdown으로 클리핑하고 싶을 때
- 에이전트에 **기본 웹 리더**가 필요할 때 — API 키 없이, 설정 없이 바로 작동

---

## ✨ 지원 소스

| 파서 | 소스 | 방법 | API 키? |
|------|------|------|---------|
| 🐦 **Twitter / X** | 트윗, 스레드, X 아티클 | [FxTwitter API](https://github.com/FxEmbed/FxEmbed) + Nitter 대체 | ❌ 없음 |
| 🟠 **Reddit** | 게시물 + 댓글 스레드 | Reddit `.json` API | ❌ 없음 |
| 🎬 **YouTube** | 동영상 자막 | [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api) | ❌ 없음 |
| 🌐 **모든 URL** | 블로그, 기사, 문서 | [Trafilatura](https://trafilatura.readthedocs.io/) + BeautifulSoup | ❌ 없음 |

**API 키 제로. 로그인 제로. 속도 제한 제로. 붙여넣기만 하면 읽기.**

---

## 🐦 Twitter / X — 심층 통합

[FxTwitter](https://github.com/FxEmbed/FxEmbed) API 기반. [x-tweet-fetcher](https://github.com/ythx-101/x-tweet-fetcher)에서 영감을 받았습니다.

| 콘텐츠 유형 | 지원 |
|------------|------|
| 일반 트윗 | ✅ 전체 텍스트 + 참여 통계 |
| 긴 트윗 (Twitter Blue) | ✅ 전체 텍스트 |
| X 아티클 (장문) | ✅ 전체 기사 + 단어 수 |
| 인용 트윗 | ✅ 중첩 콘텐츠 포함 |
| 미디어 (이미지, 동영상, GIF) | ✅ URL 추출 |
| 답글 스레드 | ✅ Nitter 대체를 통해 (처음 5개) |
| 참여 통계 | ✅ ❤️ 좋아요, 🔁 리트윗, 👁️ 조회, 🔖 북마크 |

## 🟠 Reddit — 네이티브 JSON 통합

Reddit의 내장 `.json` URL 접미사 사용 — **API 키 불필요, OAuth 불필요, 등록 불필요**.

| 콘텐츠 유형 | 지원 |
|------------|------|
| 셀프 포스트 (텍스트) | ✅ 전체 Markdown 본문 |
| 링크 포스트 | ✅ URL + 메타데이터 |
| 인기 댓글 (점수순 정렬) | ✅ 최대 15개 댓글 |
| 중첩 답글 스레드 | ✅ 최대 3단계 깊이 |
| 미디어 (이미지, 갤러리, 동영상) | ✅ URL 추출 |
| 게시물 통계 | ✅ ⬆️ 점수, 💬 댓글 수, 추천 비율 |
| Flair 태그 | ✅ 포함 |

---

## 🚀 빠른 시작

```python
from deepreader_skill import run

# 트윗 읽기 → 에이전트 메모리에 저장
result = run("이 트윗을 확인하세요: https://x.com/elonmusk/status/123456")

# Reddit 토론 읽기 → 게시물 + 인기 댓글 캡처
result = run("좋은 토론: https://www.reddit.com/r/python/comments/abc123/my_post/")

# YouTube 비디오 읽기 → 전체 자막 저장
result = run("이것을 보세요: https://youtube.com/watch?v=dQw4w9WgXcQ")

# 모든 기사 읽기 → 깨끗한 콘텐츠 추출
result = run("흥미로운 글: https://example.com/blog/ai-agents-2026")

# 여러 URL 일괄 처리
result = run("""
  여기 몇 가지 링크가 있습니다:
  https://x.com/user/status/123456
  https://www.reddit.com/r/MachineLearning/comments/xyz789/new_paper/
  https://youtube.com/watch?v=dQw4w9WgXcQ
  https://example.com/article
""")
```

---

## 📓 NotebookLM & 오디오 통합

이제 DeepReader는 **Google NotebookLM**과 완벽하게 통합됩니다. 

메시지에 `notebooklm`, `audio` 또는 `podcast`와 같은 키워드가 포함 된 경우 DeepReader는 자동으로 다음을 수행합니다:
1. 요청된 URL을 Markdown으로 파싱합니다.
2. Google NotebookLM 계정에 새 노트를 만듭니다.
3. 깔끔한 Markdown 콘텐츠를 소스로 업로드합니다.
4. **(선택 사항)** 매력적인 오디오 개요(팟캐스트 형식)를 생성하고 에이전트의 메모리 폴더에 직접 다운로드합니다.

**지원되는 NotebookLM 아티팩트 생성:**
오디오 개요와 함께 이 통합을 쉽게 확장하여 다음을 자동으로 생성하고 저장할 수 있습니다:
- **🎙️ Audio Overview** (오디오 팟캐스트)
- **🎥 Video Overview** (비디오 개요)
- **🧠 Mind Map** (마인드맵)
- **📄 Reports** (보고서)
- **📇 Flashcards** (플래시카드)
- **❓ Quiz** (퀴즈)
- **📊 Infographic** (인포그래픽)
- **🖥️ Slide Deck** (슬라이드 덱)
- **📈 Data Table** (데이터 테이블)

> **⚠️ 참고: 인증 필요**
> NotebookLM 통합을 사용하기 전에 터미널에서 인증해야 합니다(이 작업은 한 번만 수행하면 됩니다):
> ```bash
> notebooklm login
> ```

---

## 🏗️ 아키텍처

```
deepreader_skill/
├── __init__.py          # 진입점 — run() 함수
├── manifest.json        # 스킬 메타데이터 및 트리거 설정
├── SKILL.md             # ClawHub 스킬 설명
├── requirements.txt     # 의존성 목록
├── core/
│   ├── router.py        # URL → 파서 라우팅 로직
│   ├── storage.py       # Markdown 파일 생성 및 저장
│   └── utils.py         # URL 추출 및 유틸리티 함수
└── parsers/
    ├── base.py          # 추상 기본 파서 및 ParseResult 모델
    ├── generic.py       # 범용 기사/블로그 파서
    ├── twitter.py       # Twitter/X 파서 (FxTwitter + Nitter)
    ├── reddit.py        # Reddit 파서 (.json API)
    └── youtube.py       # YouTube 자막 파서
```

---

## 🔧 설정

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `DEEPREEDER_MEMORY_PATH` | `../../memory/inbox/` | 콘텐츠 저장 경로 |
| `DEEPREEDER_LOG_LEVEL` | `INFO` | 로깅 상세 수준 |
| `FIRECRAWL_API_KEY` | `""` | 선택 사항. 설정 시 차단/유료 콘텐츠를 우회 스크래핑하는 Firecrawl의 폴백으로 사용됩니다. |

---

## 💡 왜 DeepReader인가?

| 기능 | DeepReader | 수동 스크래핑 | 브라우저 도구 |
|------|-----------|-------------|-------------|
| **트리거** | URL 자동 트리거 | 코드 작성 필요 | 수동 작업 |
| **Twitter/X** | ✅ 완전 지원 | ❌ 차단됨 | ⚠️ 부분적 |
| **Reddit 스레드** | ✅ + 댓글 | ⚠️ 복잡 | ⚠️ 느림 |
| **YouTube 자막** | ✅ 내장 | ❌ 별도 도구 | ❌ 불가 |
| **API 키** | ❌ 불필요 | ✅ 자주 필요 | ✅ 때때로 |
| **출력 형식** | 깔끔한 Markdown | 원시 HTML | 스크린샷 |
| **메모리 통합** | ✅ 자동 저장 | ❌ 수동 | ❌ 수동 |

---

## 🙏 크레딧

- **[FxTwitter / FixTweet](https://github.com/FxEmbed/FxEmbed)** — Twitter/X 콘텐츠 가져오기용 공개 API
- **[x-tweet-fetcher](https://github.com/ythx-101/x-tweet-fetcher)** — FxTwitter 통합 접근 방식에 영감
- **[Trafilatura](https://trafilatura.readthedocs.io/)** — 강력한 웹 콘텐츠 추출
- **[youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)** — YouTube 자막 가져오기

---

## 🤝 기여

기여를 환영합니다!

1. 저장소를 Fork 합니다
2. 기능 브랜치를 생성합니다 (`git checkout -b feature/amazing-parser`)
3. 변경 사항을 커밋합니다 (`git commit -m '놀라운 파서 추가'`)
4. 브랜치를 푸시합니다 (`git push origin feature/amazing-parser`)
5. Pull Request를 엽니다

---

## 📄 라이선스

이 프로젝트는 **MIT 라이선스**에 따라 라이선스가 부여됩니다 — 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

---

<p align="center">
  <a href="https://github.com/astonysh">OpenClaw</a>에서 🦞 로 만들었습니다
</p>