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

title, type, status, created

title	type	status	created
web-search skill design	concept	draft	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, конверсационный «без поиска»).