docs(wiki): web-search skill design (search_web tool + web-search skill)

.wiki/concepts/web-search-skill-design.md

@@ -0,0 +1,75 @@
+---
+title: web-search skill design
+type: concept
+status: draft
+created: 2026-08-22
+---
+
+# web-search — скилл веб-поиска через субагента на search-комбо llm-web-proxy
+
+## Проблема
+
+Основная модель агента (deepseek-flash-web) не имеет веб-поиска. «Найди актуальное про X» сейчас решается костылями: curl на поисковик (блокируется 403/captcha), CDP-скрейпинг (тысячи токенов мусора в основном контексте), или отпиской «у меня нет веб-поиска».
+
+При этом llm-web-proxy уже имеет search-комбо (`deepseek-flash-search-web` / `deepseek-pro-search-web`) — нативный веб-поиск DeepSeek с цитатами, работает из коробки, без новых аккаунтов.
+
+## Решение
+
+**Pi-расширение** с тулом `search_web` (паттерн vision-subagent) + **скилл** `web-search` с политикой «когда искать».
+
+- Поиск **включён по умолчанию**: агент сам решает, когда нужны свежие данные, и вызывает тул.
+- Юзер может явно сказать «поищи X» — явный вызов.
+- Юзер может сказать **«без поиска»** — агент перестаёт вызывать тул **до конца сессии** (конверсационный механизм, как using-interns revoke; память в контексте сессии, следующая сессия — снова поиск включён).
+
+## Тул search_web
+
+Реализация в `~/projects/pi-extensions/extensions/search-web.ts` (репо `OpeItcLoc03/pi-extensions`), по образцу `vision-subagent.ts`:
+
+```
+search_web(query: string)
+→ answer: "полный текст с [1][2]"
+  sources: ["https://...", ...]   # regex по URL из citation-блока; [] если пусто
+```
+
+- **Модель**: `lwp/deepseek-pro-search-web` по умолчанию (pro-search). Переопределение: env `PI_SEARCH_MODEL` или `~/.pi/search-model.json` `{ "model": "..." }` (как PI_VISION_MODEL).
+- **Механика**: `modelRegistry.complete()` на чистом контексте с system-промптом «ищи в вебе, отвечай с цитатами [1][2]» + `search_web` инструкция. Таймаут ~120s (как vision).
+- **sources**: regex по `https?://\S+` в тексте ответа; пусто → `[]`, НЕ ошибка (поиск может не найти цитат).
+- **Ошибки**: честный текст «search failed: …», isError: true. `/search-status` command (как `/vision-model-status`).
+- Модели уже в `~/.pi/agent/models.json` (провайдер `llm-web`, префикс `lwp/`).
+
+## Скилл web-search
+
+Файл: `~/projects/skills/skills/web-search/SKILL.md` (sovereign каталог).
+
+**When to use** (триггеры):
+- Вопрос требует свежих/внешних данных: новости, цены, версии, даты, «что сейчас актуально про X»
+- «Поищи X», «найди актуальное про Y», «проверь ссылку»
+- Подтверждение факта из недавнего времени (обучение модели могло устареть)
+
+**Когда НЕ вызывать**:
+- Дизайн/рефакторинг/интроспекция проекта (код — в репо)
+- Вопросы по уже загруженному контексту (доки, файлы сессии)
+- «Без поиска» сказано юзером в этой сессии
+
+**Правила**:
+1. Один запрос = один вызов тула (не спамить серией поисков без нужды).
+2. При `sources: []` — честно «без источников», не выдумывать URL.
+3. При ответе с [1][2] — оставлять нумерацию, ссылки из sources можно дать списком.
+4. Механизм «без поиска»: после команды юзера — не вызывать тул до конца сессии, при следующем «поищи» — вернуть (повторный грант).
+
+## Тестирование (writing-skills TDD)
+
+1. **RED**: базлайн-субагент без скила — «найди актуальное про X», зафиксировать поведение (костыли/отписка).
+2. **GREEN**: субагент со скилом — вызывает `search_web`, возвращает answer+sources.
+3. Микро-тест wording'а: триггеры срабатывают на формулировках юзера; no-guidance control.
+4. Live: реальный вызов тула в сессии pi, проверка answer+sources.
+
+## Deploy
+
+1. Правки pi-extensions (search-web.ts) → commit + push → `just install`.
+2. Скилл: `skills/web-search/SKILL.md` → lint → build → install → README provenance table → commit + push (semver bump).
+3. Обновить `~/.pi/agent/models.json` при необходимости (модель уже есть).
+
+## Открытые вопросы
+
+- Нет (дизайн одобрен юзером 2026-08-22: pro-search дефолт, answer+sources, конверсационный «без поиска»).