search-skill

# 인터넷 검색 및 JSON 정리 스킬

웹에서 정보를 검색하고, 이미지 URL을 검증하며, 결과를 JSON 파일로 정리합니다.

---

# ⛔⛔⛔ CRITICAL: UNSPLASH 절대 사용 금지 ⛔⛔⛔

```
╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║   🚨🚨🚨 UNSPLASH.COM 이미지 사용 절대 금지 🚨🚨🚨                           ║
║                                                                              ║
║   이 규칙을 위반하면 다음과 같은 치명적인 문제가 발생합니다:                 ║
║                                                                              ║
║   ❌ 이미지가 전혀 표시되지 않음 (핫링크 완전 차단)                          ║
║   ❌ 완전히 다른 엉뚱한 이미지가 표시됨 (랜덤 리다이렉트)                    ║
║   ❌ 사용자에게 거짓 정보 전달 → 서비스 신뢰도 완전 붕괴                     ║
║   ❌ 법적 문제 발생 가능 (잘못된 정보 제공)                                  ║
║                                                                              ║
║   🔴 이 규칙은 절대로, 어떤 상황에서도, 예외 없이 준수해야 합니다! 🔴        ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

## 🚫 절대 금지 URL 패턴 - 발견 즉시 삭제/교체 필수

| 금지 URL 패턴 | 문제점 | 즉시 조치 |
|--------------|--------|----------|
| `images.unsplash.com/*` | 핫링크 차단, 이미지 미표시 | **즉시 삭제** |
| `unsplash.com/photos/*` | 404 에러 다발 | **즉시 삭제** |
| `source.unsplash.com/*` | 랜덤 이미지로 리다이렉트, 콘텐츠 불일치 | **즉시 삭제** |
| `plus.unsplash.com/*` | 유료 이미지, 접근 불가 | **즉시 삭제** |

### ⚠️ Unsplash 사용 시 발생하는 실제 피해

1. **사용자가 "마리나 베이 샌즈" 정보를 보는데 전혀 다른 사진이 표시됨**
2. **앱/서비스에서 이미지가 아예 로드되지 않음**
3. **사용자 신뢰 완전 상실 - "이 서비스는 거짓 정보를 제공한다"**
4. **개발자가 직접 수정해야 하는 추가 작업 발생**

---

## ✅ 반드시 사용해야 하는 이미지 소스 (우선순위 순)

### 1. Wikimedia Commons (최우선 권장) ⭐⭐⭐

- **URL 패턴**: `https://upload.wikimedia.org/wikipedia/commons/...`
- **장점**:
  - 안정적이고 영구적인 URL
  - 고품질 이미지
  - 상업적 사용 가능
  - 핫링크 허용
  - 이미지가 콘텐츠와 정확히 일치

### 2. Wikipedia API

```bash
# 이미지 URL 직접 획득 - 가장 신뢰할 수 있는 방법
TITLE="Marina_Bay_Sands"
curl -s "https://en.wikipedia.org/w/api.php?action=query&titles=${TITLE}&prop=pageimages&format=json&pithumbsize=1280" | jq -r '.query.pages | to_entries[0].value.thumbnail.source'
```

### 3. 공식 관광청/정부 사이트 이미지

- 예: Visit Singapore, 공식 명소 웹사이트

---

## 📋 이미지 검증 필수 체크리스트 (모든 항목 통과 필수!)

검색된 **모든 이미지**에 대해 반드시 확인:

- [ ] **1단계**: URL에 `unsplash` 문자열이 포함되어 있지 않은가? → 포함 시 **즉시 삭제**
- [ ] **2단계**: `curl -I` 명령으로 HTTP 200 응답 확인
- [ ] **3단계**: Content-Type이 `image/*` 인가?
- [ ] **4단계**: 실제 이미지가 검색한 콘텐츠와 일치하는가?

```bash
# 이미지 URL 검증 명령어
curl -s -I -m 10 "IMAGE_URL" 2>/dev/null | grep -E "^HTTP|content-type"
```

**⚠️ Unsplash URL을 발견하면 즉시 Wikipedia/Wikimedia로 교체하세요!**
**⚠️ 코드에 Unsplash URL이 하나라도 있으면 전체 작업 실패로 간주합니다!**

---

## 사용자 옵션 (필수 확인)

**⚠️ 검색 시작 전 반드시 사용자에게 다음 파라미터를 확인하세요:**

| 파라미터 | 설명 | 옵션 | 기본값 |
|---------|------|------|--------|
| `search_query` | 검색할 내용 상세 설명 | (사용자 입력) | **필수** |
| `include_image` | 이미지 포함 여부 | `true` / `false` | `true` |
| `description_format` | 설명 형식 | `markdown` / `plain` | `markdown` |
| `summary_sentences` | 요약 문장 수 | 1~20 | `2` |

### 사용자에게 질문할 내용

```
1. 무엇을 검색할까요? (상세하게 설명해주세요)
2. 이미지를 포함할까요? (예/아니오)
3. 설명 형식은 어떻게 할까요? (마크다운/일반 텍스트)
```

### 사용 예시

```
사용자: "싱가포르 여행 명소 검색해줘"
Claude: "다음 정보를 확인해주세요:
  1. 검색 내용: 싱가포르 여행 명소 (맞나요?)
  2. 이미지 포함: 예/아니오?
  3. 설명 형식: 마크다운/일반 텍스트?"
```

### description_format에 따른 출력

| 형식 | 예시 |
|------|------|
| `markdown` | `"🌟 **주요 특징**: 설명. 📍 **위치**: 정보."` |
| `plain` | `"주요 특징: 설명. 위치: 정보."` |

---

## 핵심 워크플로우

```
검색 → 수집 → 이미지 검증 → JSON 저장 → 크로스체크
```

### Step 1: 웹 검색

```
WebSearch 쿼리 예시:
- "{주제} wikimedia commons"
- "{주제} wikipedia image"
- "{주제} pixabay free image"
```

### Step 2: 데이터 수집

WebFetch로 URL 콘텐츠 수집 후 필요한 정보 추출.

### Step 3: 이미지 URL 검증

**스크립트 사용 (권장):**

```bash
# 단일 이미지 검증
bash scripts/verify_image.sh "IMAGE_URL"

# 여러 이미지 일괄 검증
bash scripts/verify_image_batch.sh urls.txt
```

**직접 curl 사용:**

```bash
# HTTP 상태 + Content-Type 확인
curl -s -I -m 10 "IMAGE_URL" 2>/dev/null | grep -E "^HTTP|content-type"
```

**유효한 응답:**
- HTTP 200 + `content-type: image/jpeg|png|webp|gif`

**무효한 응답 (교체 필요):**
- HTTP 404/403
- `content-type: text/html`
- 타임아웃

### Step 4: JSON 파일 저장

```json
{
  "meta": {
    "query": "검색어",
    "date": "2025-01-27",
    "total_results": 10,
    "params": {
      "include_image": true,
      "description_format": "markdown",
      "summary_sentences": 2
    }
  },
  "summary": "전체 검색 결과 요약",
  "results": [
    {
      "title": "제목",
      "emoji": "🏛️",
      "url": "https://...",
      "image": {
        "url": "https://upload.wikimedia.org/...",
        "verified": true,
        "http_code": "200",
        "content_type": "image/jpeg"
      },
      "description": "🌟 **주요 특징**: 마크다운 + 이모지 형식으로 작성.",
      "details": {
        "location": "123 Main Street, Singapore",
        "opening_hours": "09:00",
        "closing_hours": "22:00",
        "price_range": "$50-$100",
        "reservation": "required"
      }
    }
  ]
}
```

**필드 설명:**
| 필드 | 설명 |
|------|------|
| `emoji` | 항목을 대표하는 이모지 (UI 디자인용) |
| `description` | **마크다운 + 이모지** 형식으로 작성 |
| `details` | 추가 속성 객체 (유동적) |

**details 속성 예시 (콘텐츠에 따라 선택):**
- 기본: `location`, `contact`, `website`
- 영업: `opening_hours`, `closing_hours`, `holidays`
- 가격: `price_range`, `admission_fee`
- 예약: `reservation`, `booking_url`, `delivery`
- 제한: `dress_code`, `age_limit`, `accessibility`
- 평점: `rating`, `review_count`

> 상세 속성 목록은 [output-formats.md](references/output-formats.md) 참조

### Step 5: 이미지 크로스체크 (필수!)

**⚠️ JSON 저장 후 반드시 모든 이미지 URL을 재검증합니다.**

```bash
# JSON에서 이미지 URL 추출 후 일괄 검증
jq -r '.results[].image.url' output.json | bash scripts/verify_image_batch.sh -
```

**크로스체크 기준:**
| 상태 | 조치 |
|------|------|
| 모든 이미지 valid: true | 완료 |
| 일부 valid: false | 해당 이미지 재검색 및 교체 |
| 검증 불가 | Wikipedia API로 대체 이미지 검색 |

---

## Wikipedia API로 이미지 검색

검증 실패 시 Wikipedia API로 정확한 이미지 획득:

```bash
# 제목으로 이미지 검색
TITLE="Marina_Bay_Sands"
curl -s "https://en.wikipedia.org/w/api.php?action=query&titles=${TITLE}&prop=pageimages&format=json&pithumbsize=1280" | jq -r '.query.pages | to_entries[0].value.thumbnail.source'
```

**검색 제목 예시:**

| 한글명 | Wikipedia 제목 |
|--------|---------------|
| 마리나 베이 샌즈 | `Marina_Bay_Sands` |
| 머라이언 파크 | `Merlion` |
| 가든스 바이 더 베이 | `Gardens_by_the_Bay` |

---

## 사용 도구

| 도구 | 용도 |
|------|------|
| `WebSearch` | 인터넷에서 정보 검색 |
| `WebFetch` | URL에서 콘텐츠 수집 |
| `Bash (curl)` | 이미지 URL 검증 |
| `scripts/verify_image.sh` | 단일 이미지 검증 |
| `scripts/verify_image_batch.sh` | 일괄 이미지 검증 |

---

## 참조 문서

상세 정보는 다음 문서를 참조하세요:

- **[이미지 소스 가이드](references/image-sources.md)**: 권장 이미지 소스, URL 패턴, Wikipedia API 상세
- **[출력 형식 템플릿](references/output-formats.md)**: JSON/Markdown 출력 템플릿, 보고서 형식
- **[Bash 명령어 참조](references/bash-commands.md)**: curl, jq, grep 등 자주 사용하는 명령어

---

## 성공 기준

1. ✅ 모든 이미지 URL이 HTTP 200 반환
2. ✅ Content-Type이 `image/*`
3. ✅ 이미지가 콘텐츠와 관련성 있음
4. ✅ JSON 파일이 올바른 형식
5. ✅ 크로스체크 완료