Naver Search

# Naver Search Skill 명세서

이 문서는 OpenClaw 에이전트가 네이버 검색 스킬을 가장 효율적으로 호출하고 결과를 분석할 수 있도록 돕는 지침서입니다.

## 🎯 스킬 목적
네이버의 실시간 뉴스, 쇼핑 데이터, 영상 및 장소 정보를 정교한 파라미터 제어를 통해 확보합니다.

## 🛠️ 호출 명세 (Command Reference)

### 1. 통합 어그리게이터 (추천)
에이전트가 여러 카테고리의 정보를 한꺼번에 파악해야 할 때 사용합니다.
```bash
python3 scripts/naver_search.py "<검색어>"
```
- **반환 데이터**: 최신 뉴스(3건), 쇼핑 트렌드(3건), 이미지 썸네일, 비디오 요약, 상위 웹 결과.

### 2. 고성능 뉴스 엔진
```bash
python3 scripts/naver_news.py "<검색어>" --sort <sort> --time <time>
```
- `--sort`: `0`(관련도순), `1`(최신순-추천), `2`(오래된순)
- `--time`: `all`, `1h`(1시간), `1d`(1일), `1w`(1주), `1m`(1개월)
- **팁**: 실시간 이슈 분석 시 `--sort 1 --time 1d` 조합이 가장 유용합니다.

### 3. 쇼핑/이미지/비디오 전문 엔진
| 기능 | 스크립트 | 특수 옵션 |
| :--- | :--- | :--- |
| **쇼핑** | `naver_shopping.py` | 가격, 판매처 정보 포함 |
| **이미지** | `naver_images.py` | `--num [n]` (결과 개수 제어) |
| **비디오** | `naver_video.py` | 출처 및 재생 시간 정보 포함 |

### 4. 예약 및 장소 엔진
장소의 물리적 위치나 예약 링크가 필요할 때 호출합니다.
```bash
python3 scripts/naver_booking.py "<맛집/장소명>"
```
- **반환 데이터**: 업체명, 주소, 카테고리, 네이버 예약 상품 정보 및 링크.

## 📊 출력 포맷 제어
모든 명령어 뒤에 `--format` 옵션을 추가하여 데이터 구조를 선택할 수 있습니다.
- `compact` (기본): 에이전트가 읽기 좋은 핵심 요약 텍스트.
- `json`: 코드 레벨에서 정밀 분석이 필요한 경우 유용한 JSON raw 데이터.

## 🔐 보안 및 환경 변수
- 본 스킬은 **`SERPAPI_API_KEY`** 환경 변수가 필수입니다. 
- 환경 변수가 설정되어 있지 않다면 스킬 루트 폴더의 `.env` 파일에 키를 기입하세요.

---
**유의사항**: 네이버 엔진 특성상 검색어 뒤에 '뉴스', '예약' 등의 단어를 직접 포함하면 더 정확한 결과를 얻을 수 있습니다. (`naver_news.py`, `naver_booking.py` 내부에 이미 일부 자동 보강 로직이 포함되어 있습니다.)

# Naver Search Skill for OpenClaw

OpenClaw 에이전트가 네이버의 방대한 데이터를 카테고리별(웹, 뉴스, 쇼핑, 이미지, 비디오, 예약)로 정밀하게 활용할 수 있도록 설계된 스킬입니다. 모든 엔진은 SerpAPI를 기반으로 하며, 독립적인 스크립트 구조를 가져 안정적입니다.

## 🏗️ 전체 구조 (Architecture)

```text
naver-search/
├── .env                  # API 키 (SERPAPI_API_KEY)
├── SKILL.md              # [Agent 전용] 사용 가이드 및 명령어 명세
├── README.md             # [User 전용] 설치 및 정보 요약
├── requirements.txt      # 의존성 패키지 (serpapi)
├── lib/
│   └── naver_base.py     # 공용 통신 및 데이터 정제 엔진
└── scripts/
    ├── naver_search.py   # [Main] 모든 결과를 요약 취합하는 통합 어그리게이터
    ├── naver_web.py      # 웹/지식iN/블로그 검색
    ├── naver_news.py     # 뉴스 (최신순/기간 필터 완벽 지원)
    ├── naver_shopping.py # 쇼핑 (최저가/판매처 상세 정보)
    ├── naver_images.py   # 이미지 (썸네일 및 출처 정보)
    ├── naver_video.py    # 비디오 (YouTube/TikTok 플랫폼 연동)
    └── naver_booking.py  # 예약/장소 (지도 위치 및 예약 상품 정보)
```

## 🚀 빠른 시작 (Quick Start)

가장 권장되는 사용법은 **통합 검색**을 통해 전체적인 흐름을 파악하는 것입니다.

```bash
# 한 번의 실행으로 뉴스, 쇼핑, 이미지, 비디오 요약 결과를 통합 조회
python3 scripts/naver_search.py "검색어"
```

## 🛠️ 기능별 상세 명령어 (Detailed Usage)

에이전트는 필요에 따라 아래의 전문 엔진을 직접 호출하여 더 깊은 데이터를 확보할 수 있습니다.

| 엔진명 (-e) | 전문 스크립트 | 주요 특징 및 옵션 |
| :--- | :--- | :--- |
| **통합** | `naver_search.py` | 모든 카테고리 톱 결과를 한 뷰에 요약 출력 |
| **뉴스** | `naver_news.py` | `--sort 1`(최신순), `--time 1d`(1일 이내) 옵션으로 정확한 속보 확인 |
| **쇼핑** | `naver_shopping.py` | 가격(`price`), 평점, 판매처 링크 등 이커머스 최적화 데이터 |
| **이미지** | `naver_images.py` | `--num [개수]` 옵션으로 다량의 썸네일 및 출처 확보 |
| **비디오** | `naver_video.py` | 영상 플랫폼(유튜브 등) 링크 및 재생 시간 정보 확인 |
| **예약** | `naver_booking.py` | 업체...