forgeplan search

Умный поиск по артефактам. Начиная с версии v0.18.0, Forgeplan поставляется с производственным BM25 (через крейт bm25 v2.3.2) с русским Snowball stemmer, удалением шума шаблонов и расширением графа на 1 переход. Семантические векторы используются для усиления ранжирования, когда включен флаг функции semantic-search.

Когда использовать

• Вы помните концепцию, но не ID
• Онбординг - “что у нас есть по аутентификации?”
• Создание черновика нового артефакта - поиск связанных предыдущих решений для связывания
• AI-агенты, выполняющие рассуждения с дополненным поиском

Когда не использовать

• Вы знаете точный ID → используйте forgeplan get
• Вы хотите структурное представление → используйте forgeplan tree или forgeplan graph
• Вы хотите искать личные воспоминания, а не артефакты → используйте forgeplan recall

Использование

forgeplan search [OPTIONS] <QUERY>

Аргументы

  <QUERY>  Поисковый запрос

Опции

  -t, --type <TYPE>      Фильтр по типу (prd, rfc, adr, note, ...)
  -s, --status <STATUS>  Фильтр по статусу (draft, active, superseded, deprecated, stale)
      --depth <DEPTH>    Фильтр по глубине (tactical, standard, deep, critical)
      --with-evidence    Только артефакты со связанными доказательствами (R_eff > 0)
      --no-evidence      Только артефакты БЕЗ доказательств (слепые пятна)
      --since <SINCE>    Только артефакты, созданные после этой даты (YYYY-MM-DD)
      --no-expand        Отключить расширение графа (соседи на 1 переход в результатах)
      --keyword          Принудительный поиск только по ключевым словам (grep по подстроке)
      --semantic         Принудительный поиск только по семантике (векторное сходство)
  -n, --limit <LIMIT>    Максимальное количество результатов (по умолчанию: 20) [по умолчанию: 20]
      --json             Вывод в формате JSON для машинной обработки
  -h, --help             Вывести справку
  -V, --version          Вывести версию

Примеры

Умный по умолчанию - BM25 + семантический + расширение графа:

forgeplan search "authentication flow"

Сузить до активных PRD, топ-5 результатов:

forgeplan search "auth" --type prd --status active --limit 5

Найти решения, не имеющие подтверждающих доказательств (вариант слепого пятна):

forgeplan search "rate limit" --no-evidence

Интерпретация вывода

Вывод по умолчанию - это ранжированный список:

PRD-001  [active ]  score=8.42  Auth system (BM25 + semantic)
RFC-002  [active ]  score=6.71  Token refresh flow      (graph-expanded from PRD-001)
ADR-004  [active ]  score=5.30  JWT vs session cookies

Столбцы: ID, STATUS, SCORE, TITLE, плюс маркер (graph-expanded), когда совпадение было получено как сосед на 1 переход, а не как прямое совпадение термина. Оценки не сопоставимы между запросами - они ранжируются только в рамках одного вызова.

Русские запросы работают так же - “авторизация” будет соответствовать “авторизации”, “авторизованный” и т.д., благодаря Snowball stemmer.

Как это вписывается

search - это основная поверхность для обнаружения:

search → get → link (during artifact authoring)
search → get → reason (during AI planning)

Полную информацию о конвейере (индексирование, стемминг, параметры BM25, расширение графа) см. в руководстве по Search v2.

См. также

• Руководство по Search v2 - архитектура и настройка
• forgeplan get - прочитать совпадение полностью
• forgeplan recall - поиск воспоминаний (не артефактов)
• forgeplan reindex - перестроить индекс BM25