# Веб-поиск и исследование

Этот skill содержит инструкции по использованию инструмента `web_search` для поиска актуальной правовой информации.

**Ключевое отличие от других навыков:** этот навык НЕ использует `sandbox_bash`. Инструмент `web_search` вызывается напрямую.

**Режимы ограничений:**
- **Поиск (query)** — без ограничений по доменам, поиск по всему интернету
- **Загрузка по URL (url)** — только с разрешённых доменов (см. БЛОК 2)

---

## Workflow

```
1. read_skill(skill_id="web_search_ru")   → получаешь стратегии поиска
2. web_search(query="...", ...)            → выполняешь поиск напрямую
```

❌ НЕПРАВИЛЬНО: вызывать web_search из Python-кода через sandbox_bash — web_search это инструмент, не библиотека!
✅ ПРАВИЛЬНО: `web_search(query="ст 395 ГК РФ проценты")` — вызов инструмента напрямую

---

## Два режима работы

### Режим 1: Поиск (query)

Поиск по правовым базам и сайтам госорганов:

```
web_search(
    query="ст 395 ГК РФ проценты за пользование чужими денежными средствами",
    max_results=5,
    fetch_full_text=true,
    time_range="any",
    format="full"
)
```

### Режим 2: Загрузка страницы (url)

Загрузка конкретной страницы по известному URL:

```
web_search(
    url="https://www.consultant.ru/document/cons_doc_LAW_5142/",
    format="full"
)
```

⚠️ `query` и `url` — взаимоисключающие. Нельзя указать оба одновременно.

---

# БЛОК 1: Параметры инструмента web_search

## Параметр: query (строка, 3–500 символов)

Текстовый поисковый запрос. Поддерживает естественный язык и юридические термины.

**Автоматические улучшения запроса:**
- Аббревиатуры юридических кодексов разворачиваются автоматически (ГК РФ → Гражданский кодекс РФ)
- Короткие типовые запросы расширяются до полной формулировки
- Запросы с датами (месяц+год) при пустом результате автоматически упрощаются

**Примеры хороших запросов:**
- `"неустойка по договору поставки арбитражная практика 2024"`
- `"ст 395 ГК РФ проценты за пользование"`
- `"изменения в закон о банкротстве 2025"`
- `"ключевая ставка ЦБ РФ текущая"`
- `"форма декларации по НДС 2025"`

**Примеры плохих запросов:**
- `"закон"` — слишком общий
- `"ГК"` — слишком короткий (минимум 3 символа)
- `"что такое договор"` — RAG/контекст достаточен, web_search не нужен

## Параметр: url (строка, 10–2000 символов)

Прямой URL для загрузки содержимого. Домен должен быть в списке разрешённых (см. БЛОК 2).

**Когда использовать:**
- URL уже найден в результатах поиска и нужна полная версия
- Пользователь предоставил конкретную ссылку
- Нужно загрузить конкретный нормативный документ

## Параметр: max_results (число, 1–20, по умолчанию 5)

Количество результатов поиска.

| Сценарий | Рекомендация |
|----------|-------------|
| Быстрая проверка факта | 3 |
| Стандартный поиск | 5 (по умолчанию) |
| Обзор судебной практики | 10–15 |
| Комплексное исследование | 15–20 |

## Параметр: fetch_full_text (bool, по умолчанию true)

Загружать ли полный текст страниц. При `true` — медленнее, но подробнее.

| Сценарий | Рекомендация |
|----------|-------------|
| Нужен полный текст статьи/закона | `true` |
| Достаточно заголовков и сниппетов | `false` |
| Много результатов (>10) | `false` (для скорости) |
| Единичный документ | `true` |

## Параметр: time_range (фильтр по времени)

| Значение | Период | Когда использовать |
|----------|--------|-------------------|
| `any` | Без ограничений (по умолчанию) | Базовые нормы, кодексы, устоявшаяся практика |
| `hour` | Последний час | Экстренные новости, только что опубликованное |
| `day` | Последние сутки | Новости дня, свежие публикации |
| `week` | Последняя неделя | Свежая практика, недавние разъяснения |
| `month` | Последний месяц | Новые законы, изменения за месяц |

**Триггеры для time_range в запросе пользователя:**
- «на этой неделе», «за последнюю неделю» → `week`
- «свежая практика», «новые», «последние изменения» → `week` или `month`
- «сегодня», «вчера» → `day`
- «только что», «прямо сейчас» → `hour`

## Параметр: format (формат содержимого)

| Значение | Лимит | Когда использовать |
|----------|-------|-------------------|
| `full` | 100 КБ (по умолчанию) | Полный текст закона, детальный анализ |
| `summary` | 15 КБ | Обзор нескольких источников |
| `snippet` | 3 КБ | Быстрая проверка, много результатов |

---

# БЛОК 2: Разрешённые домены (только для загрузки по URL)

Ограничения по доменам действуют **только для режима загрузки по URL** (`url=`).
Поиск по запросу (`query=`) работает по всему интернету без ограничений.

## Правовые базы данных

| Домен | Описание |
|-------|----------|
| `consultant.ru` | КонсультантПлюс — законодательство, комментарии |
| `garant.ru` | Гарант — правовая информация |

## Судебная практика

| Домен | Описание |
|-------|----------|
| `sudact.ru` | Судебные акты РФ |
| `arbitr.ru` | Арбитражные суды |
| `vsrf.ru` | Верховный Суд РФ |
| `kad.arbitr.ru` | Картотека арбитражных дел |

## Государственные органы

| Домен | Описание |
|-------|----------|
| `pravo.gov.ru` | Официальный интернет-портал правовой информации |
| `nalog.gov.ru` | ФНС России |
| `cbr.ru` | Банк России |
| `minfin.gov.ru` | Минфин России |
| `fas.gov.ru` | ФАС России |
| `mintrud.gov.ru` | Минтруд России |
| `economy.gov.ru` | Минэкономразвития России |
| `rostrud.gov.ru` | Роструд |
| `rosreestr.gov.ru` | Росреестр |
| `rosminzdrav.ru` | Минздрав России |
| `fssprus.ru` | ФССП России |
| `zakupki.gov.ru` | Единая информационная система в сфере закупок |
| `rg.ru` | Российская газета |

## Реестры и базы

| Домен | Описание |
|-------|----------|
| `egrul.nalog.ru` | ЕГРЮЛ/ЕГРИП |
| `bo.nalog.ru` | Бухгалтерская отчётность |
| `fedresurs.ru` | Федресурс |
| `rusprofile.ru` | Rusprofile |
| `spark-interfax.ru` | СПАРК-Интерфакс |

## СМИ и аналитика

| Домен | Описание |
|-------|----------|
| `tass.ru` | ТАСС |
| `ria.ru` | РИА Новости |
| `kommersant.ru` | Коммерсантъ |
| `vedomosti.ru` | Ведомости |
| `interfax.ru` | Интерфакс |
| `banki.ru` | Banki.ru — финансовый портал |
| `law.ru` | Право.ru |
| `zakon.ru` | Закон.ру |
| `advgazeta.ru` | Адвокатская газета |

⚠️ Загрузка по URL с доменов вне списка будет отклонена с ошибкой `BLOCKED`.
Для поиска (query) ограничений нет — результаты возвращаются с любых сайтов.

---

# БЛОК 3: Стратегии поиска

## Стратегия: Поиск нормы закона

Когда нужно найти конкретную статью или норму:

```
web_search(
    query="ст 333 ГК РФ уменьшение неустойки текст статьи",
    max_results=3,
    fetch_full_text=true,
    format="full"
)
```

**Рекомендации:**
- Указывай номер статьи и кодекс
- Добавляй «текст статьи» или «действующая редакция»
- max_results=3 достаточно для конкретной нормы
- fetch_full_text=true для получения полного текста

## Стратегия: Обзор судебной практики

Когда нужна практика по конкретному вопросу:

```
web_search(
    query="неустойка по договору подряда снижение по ст 333 арбитражная практика",
    max_results=10,
    fetch_full_text=false,
    time_range="any",
    format="summary"
)
```

Затем загрузка релевантных решений по URL:

```
web_search(
    url="https://sudact.ru/arbitral/doc/...",
    format="full"
)
```

**Рекомендации:**
- Сначала поиск с fetch_full_text=false для обзора
- Затем загрузка конкретных решений по URL
- format="summary" для обзорного поиска, "full" для загрузки конкретного акта

## Стратегия: Актуальные изменения

Когда пользователь спрашивает о недавних изменениях в законодательстве:

```
web_search(
    query="изменения в закон о банкротстве 2025",
    max_results=10,
    fetch_full_text=true,
    time_range="month",
    format="summary"
)
```

**Рекомендации:**
- Используй time_range="month" или "week" для свежих изменений
- Добавляй год в запрос для точности
- max_results=10 для полноты картины
- Если пусто — убери time_range и попробуй снова

## Стратегия: Проверка контрагента

Когда нужно проверить юридическое лицо:

```
web_search(
    query="ООО Ромашка ИНН 7707123456",
    max_results=5,
    fetch_full_text=true,
    format="full"
)
```

**Рекомендации:**
- Указывай ИНН или ОГРН для точного поиска
- Результаты придут из rusprofile.ru, spark-interfax.ru, egrul.nalog.ru
- fetch_full_text=true для получения полных данных

## Стратегия: Ключевая ставка и экономические данные

Когда нужны актуальные данные ЦБ РФ:

```
web_search(
    query="ключевая ставка ЦБ РФ текущая",
    max_results=3,
    fetch_full_text=true,
    time_range="week",
    format="full"
)
```

**Рекомендации:**
- time_range="week" для актуальных данных
- cbr.ru — основной источник
- Для исторических данных — time_range="any"

## Стратегия: Налоговые формы и отчётность

Когда нужны формы отчётности или разъяснения ФНС:

```
web_search(
    query="форма 6-НДФЛ 2025 порядок заполнения",
    max_results=5,
    fetch_full_text=true,
    format="full"
)
```

**Рекомендации:**
- Указывай название формы и год
- nalog.gov.ru и consultant.ru — основные источники
- Добавляй «порядок заполнения» или «инструкция» для практических результатов

## Стратегия: Комплексное исследование (многошаговый)

Когда тема требует глубокого анализа:

**Шаг 1: Обзорный поиск**
```
web_search(
    query="защита прав дольщиков при банкротстве застройщика",
    max_results=15,
    fetch_full_text=false,
    format="snippet"
)
```

**Шаг 2: Загрузка ключевых источников**
```
web_search(
    url="https://consultant.ru/document/...",
    format="full"
)
```

**Шаг 3: Поиск свежей практики**
```
web_search(
    query="банкротство застройщика передача квартир дольщикам практика",
    max_results=10,
    fetch_full_text=true,
    time_range="month",
    format="summary"
)
```

---

# БЛОК 4: Когда использовать web_search

## Используй web_search, когда:

- Пользователь спрашивает об **актуальных данных** (ставки, курсы, новые законы)
- Нужна **свежая судебная практика** (после даты среза знаний)
- Запрос содержит слова: «свежий», «новый», «последние изменения», «текущий»
- RAG-контекст **не содержит** нужной информации (проверь сначала)
- Нужен **полный текст** конкретного нормативного акта
- Требуется **проверка контрагента** (ИНН, ОГРН, ЕГРЮЛ)

## НЕ используй web_search, когда:

- Информация **уже есть** в загруженных документах → используй `query_documents`
- Вопрос по **базовым нормам** ГК/ТК, которые ты знаешь → отвечай из знаний
- Нужен **анализ договора** пользователя → используй соответствующий юридический навык
- Запрос **не связан** с правовой информацией
- Нужна загрузка по URL с домена **не в списке** разрешённых

## Приоритет источников информации:

```
1. Загруженные документы пользователя (query_documents)
2. Навыки/скиллы (read_skill) — для устоявшихся норм
3. Базовые знания модели
4. Веб-поиск (web_search) — для актуальных данных и свежей практики
```

---

# БЛОК 5: Обработка результатов

## Формат ответа при поиске

Результат web_search содержит:

```json
{
    "query": "исходный запрос",
    "total_found": 5,
    "results": [
        {
            "title": "Заголовок страницы",
            "url": "https://consultant.ru/...",
            "snippet": "Краткое описание...",
            "content": "Полный текст (если fetch_full_text=true)..."
        }
    ],
    "cached": false,
    "format": "full"
}
```

## Формат ответа при загрузке URL

```json
{
    "url": "https://consultant.ru/...",
    "title": "Заголовок страницы",
    "content": "Полный текст в markdown...",
    "content_length": 45000,
    "truncated": false,
    "cached": false,
    "format": "full"
}
```

## Рекомендации по обработке

1. **Цитируй источники** — всегда указывай URL и название источника
2. **Проверяй релевантность** — snippet может не совпадать с запросом
3. **Обрабатывай пустые результаты** — предложи переформулировать запрос или убрать time_range
4. **Используй кэш** — повторный запрос в течение часа вернёт кэш (cached=true)
5. **Следи за truncated** — если `truncated=true`, важная информация может быть обрезана

## Обработка ошибок

| Код ошибки | Причина | Действие |
|-----------|---------|---------|
| `TIMEOUT` | Превышено время ожидания | Повторить с меньшим max_results или fetch_full_text=false |
| `BLOCKED` | Домен не в списке разрешённых | Использовать разрешённый домен или отказать |
| `RATE_LIMITED` | Превышен лимит запросов | Подождать и повторить |
| `NETWORK_ERROR` | Ошибка сети | Повторить позже |
| `SERVICE_UNAVAILABLE` | Сервис недоступен | Сообщить пользователю, использовать альтернативный источник |

---

# БЛОК 6: Формирование запросов — лучшие практики

## Общие правила

1. **Конкретность** — «ст 395 ГК РФ проценты» лучше, чем «проценты по закону»
2. **Юридические термины** — используй точные термины из кодексов и законов
3. **Номера статей** — «ст 333 ГК РФ» точнее, чем «уменьшение неустойки»
4. **Номера законов** — «127-ФЗ о банкротстве» точнее, чем «закон о банкротстве»
5. **Год** — добавляй год для актуальных вопросов: «налоговые изменения 2025»
6. **Контекст** — добавляй «арбитражная практика», «разъяснения ФНС» для целевых результатов

## Типовые шаблоны запросов

### Поиск нормы
```
"ст {номер} {кодекс} {ключевые слова} действующая редакция"
```

### Судебная практика
```
"{тема спора} арбитражная практика {год}"
"{тема спора} постановление пленума ВС РФ"
"{тема спора} обзор судебной практики"
```

### Изменения законодательства
```
"изменения {закон/кодекс} {год} новая редакция"
"федеральный закон от {дата} № {номер}-ФЗ"
```

### Разъяснения госорганов
```
"письмо {орган} от {год} {тема} разъяснения"
"приказ {орган} {тема} {год}"
```

### Проверка контрагента
```
"{название организации} ИНН {инн}"
"ОГРН {огрн} выписка ЕГРЮЛ"
```

---

*Skill-файл содержит инструкции по использованию инструмента web_search для поиска актуальной правовой информации. Вызывай web_search напрямую как инструмент — НЕ через sandbox_bash.*