Навык поиска в локальной базе знаний (kb-retriever)

Описание каталога базы знаний

• База знаний хранится в одном корневом каталоге и содержит файлы различных типов (например, .md/.txt、.pdf、.xlsx и т. д.) и, как правило, разбита на многоуровневые подкаталоги по типу или бизнес-назначению.
• Используется иерархическая структура каталогов для индексации файлов:
  • В корневом каталоге находится файл data_structure.md, в котором описаны основные «тематические каталоги» и их назначение.
  • В каждом тематическом каталоге может находиться собственный data_structure.md, в котором указано, какие подкаталоги/файлы находятся в данном каталоге, а также их назначение.
  • В подкаталогах более глубокого уровня также могут быть data_structure.md, образуя многоуровневое дерево индексации.
• Соглашение о корневом каталоге базы знаний:
  • по умолчанию предполагается, что база знаний находится в каталоге knowledge/ .
  • Если пользователь явно указал другой путь в диалоговом окне (например, «Моя база знаний находится в /data/kb» или «Использовать каталог ./docs в качестве базы знаний»), то в качестве корневого каталога используется указанный пользователем путь.
  • Если путь по умолчанию knowledge/ не существует или доступ к нему невозможен, необходимо подтвердить у пользователя фактическое расположение корневого каталога базы знаний, а не делать произвольные предположения.
• Отдельные рабочие файлы могут быть очень большими:
  • не следует считывать весь файл напрямую с помощью Read
  • для PDF и Excel используйте соответствующие навыки (Skill) для структурирования данных, а затем выполняйте точный поиск с помощью grep или частичного чтения

Определение knowledge корневого каталога

• В корневом каталоге приоритет отдается указаниям пользователя: если пользователь указал путь (например, ./docs、./knowledge-personal), используется непосредственно указанный пользователем путь.
• Корневой каталог по умолчанию: в противном случае в качестве корневого каталога принимается каталог текущего проекта knowledge/。
  • Явно проверять наличие каталога с помощью оболочки: отдавать предпочтение использованию test -d knowledge, или, в крайнем случае, ls -d knowledge。
  • Внимание: запрещается использовать Glob "knowledge" in . таких шаблонов для определения наличия каталога,Glob поскольку возвращается только путь к файлу, а не сам каталог; пустой результат не позволяет различить «каталог не существует» и «каталог существует, но пуст».
• Только после того, как корневой каталог будет подтвержден test -d или иным способом, следует использовать Glob для поиска содержимого в этом каталоге и использовать каталог в качестве path, например:
  • файл индекса:pattern="**/data_structure.md", path="knowledge"
  • Все файлы Markdown:pattern="**/*.md", path="knowledge"
• Если по умолчанию knowledge/ не существует (test -d ошибка): не следует предполагать наличие других каталогов; необходимо четко сообщить пользователю, что корневой каталог по умолчанию не найден, и предложить ему указать фактический путь к базе знаний.

Ключевой принцип: сначала изучить, потом обрабатывать

Обязательный контрольный список при работе с файлами PDF или Excel:

• ✅ Изучено соответствующее руководство по обработке файлов в разделе «references»
• ✅ Поняты рекомендуемые инструменты и команды
• ✅ Обработка файла (извлечение/преобразование) завершена
• ⏭️ Теперь можно приступать к поиску

Запрещенные действия:

• ❌ Прямая попытка обработки PDF-файла без предварительного ознакомления с файлом pdf_reading.md
• ❌ Прямая попытка обработки Excel-файлов без предварительного ознакомления с файлом excel_reading.md
• ❌ Пропуск этапа обработки файлов и непосредственный поиск по исходным файлам PDF/Excel

Общий процесс

1. Понимание потребностей пользователя

   • Прочитать вопрос пользователя и извлечь:
     • ключевые слова по теме/области (например, «отчеты по продажам», «архитектура системы», «документация по интерфейсам»)
     • Временные рамки или ограничения (например, «1-й квартал 2023 г.», «последняя версия»)
     • Требуемый тип результата (объяснение, резюме, конкретные значения полей и т. д.)
   • Определение корневого каталога базы знаний:
     • В первую очередь проверьте, указал ли пользователь в вопросе путь к базе знаний.
     • В противном случае используйте корневой каталог по умолчанию knowledge/。
     • Если корневой каталог по умолчанию отсутствует или структура каталогов неверна, следует запросить подтверждение у пользователя, а не делать собственные предположения.

2. Просмотр индекса каталогов по уровням data_structure.md

   • Используйте концепцию «текущего рабочего каталога»:
     • по умолчанию начинать с корневого каталога базы знаний, указанного пользователем; если пользователь его не указал, использовать текущий каталог.
   • Если в текущем рабочем каталоге существует data_structure.md：
     • с помощью Read считываются первые несколько строк этого файла (например, limit=300), при необходимости чтение продолжается по частям.
     • Цель:
       • узнать, какие подкаталоги и файлы находятся в текущем каталоге
       • Понять описание назначения каждого подкаталога/файла
     • На основе задачи пользователя отобрать несколько наиболее релевантных подкаталогов или файлов, сформировав набор кандидатов.
   • Для подкаталогов из набора кандидатов:
     • рекурсивно перейти в этот подкаталог, сделать его новым «текущим рабочим каталогом» и продолжить поиск в нём data_structure.md и повторяем вышеописанный процесс.
     • В процессе рекурсии избегайте одновременного прохождения всех ветвей, отдавая приоритет продвижению по пути, наиболее релевантному задаче.
   • Для файлов-кандидатов (md/текстовые файлы, PDF, Excel и т. д.):
     • после завершения необходимого обзора иерархии каталогов соберите эти файлы в окончательный список целей поиска.
   • При сортировке по приоритету:
     • отдавайте предпочтение каталогам и файлам, описание назначения которых в значительной степени соответствует теме задачи
     • во-вторых, учитывайте ограничения по времени/версии и т. д. (если они отражены в индексе)
     • Документы общего описательного характера (например, README.md, документы общего проектирования) помещаются в конец списка по приоритету

3. Изучите методы обработки файлов (обязательно применяйте при работе с PDF и Excel)

   • Перед обработкой PDF-файлов:
     • обязательно ознакомьтесь с файлом references/pdf_reading.md (обратите внимание, что этот файл находится в каталоге Skills, а не в каталоге Knowledge) Изучите методы извлечения данных
     • Особое внимание следует уделить: команде pdftotext, использованию pdfplumber, методам извлечения данных из таблиц
   • Перед обработкой файлов Excel:
     • обязательно ознакомьтесь с файлом references/excel_reading.md, чтобы изучить методы чтения
     • Обязательно ознакомьтесь с файлом references/excel_analysis.md, чтобы изучить методы анализа
     • Особое внимание следует уделить: чтению данных с помощью pandas, фильтрации столбцов и фильтрации данных
   • Цель: обеспечить использование правильных инструментов и методов, избежать бессистемного поиска

4. Выполнять обработку и извлечение данных в зависимости от типа файла

   • Обработайте файлы с помощью только что изученных методов (извлечение, преобразование, структурирование)
   • Для каждой категории потенциальных файлов действовать в соответствии со стратегиями, приведёнными ниже: «Markdown/текст», «PDF», «Excel»
   • Общий принцип:
     • начинать с наиболее релевантных и точных файлов
     • Внутри каждого файла выполняйте постепенный локальный поиск, избегая загрузки всего содержимого за один раз
     • Если текущий файл не содержит удовлетворительной информации, переходите к следующему кандидату

5. Итеративный поиск

   • Для всех типов документов используется единый «механизм многораундового итеративного поиска» (см. вышеуказанные общие принципы поиска)

6. Организация ответа и указание источников

   • Обобщаем контекст, полученный в результате многораундового поиска, и даем комплексный ответ на вопрос пользователя.
   • По возможности:
     • давать четкие и прямые ответы
     • указывать названия использованных документов (при необходимости с указанием приблизительного местоположения, например, раздела или примерного номера строки/страницы)
   • Если ответ основан на предположениях или информация неполна:
     • четко обозначить допущения и неопределенности
     • Предложите пользователю уточнить диапазон документов или ключевые слова

Принципы общего поиска

Стратегия выбора ключевых слов

• Извлечение 3–8 ключевых слов из запроса пользователя (включая возможные английские аббревиатуры, синонимы, родительские и дочерние термины)
• Возможные словосочетания (например, «отчет о продажах», «таймаут API-интерфейса»)
• При необходимости включать бизнес-термины, технические термины, распространённые аббревиатуры (например, «uv», «pv», «GMV»)

Основные принципы поиска с помощью grep

• Всегда указывайте как можно более точные параметры include и path, чтобы избежать поиска по всему каталогу
• В поле pattern сначала пробуйте использовать ключевые существительные и термины из вопроса, а затем — синонимы
• Для каждого совпадения считывайте только локальный участок вблизи совпадения (несколько строк выше и ниже)
• Сохраняйте «имя файла + информацию о местоположении + фрагмент текста»

Механизм многораундового итеративного поиска (не более 5 раз)

Для всех типов файлов используется единая стратегия итераций:

1. Управление итерациями
   • Ведение счётчика «количества попыток поиска», максимум 5 раз
   • Счетчик увеличивается после каждого поиска
2. Процесс каждого цикла итерации
   1. на основе запроса генерируются/обновляются ключевые слова для поиска (могут включать синонимы и расширенные термины)
   2. Выбор файлов или частей файлов, которые ещё не были полностью просканированы
   3. Выполнение поиска (grep/локальное чтение/вызов специального навыка)
   4. Анализ полученных фрагментов контекста
   5. Оценка достаточности информации для ответа на вопрос
3. Условия прекращения
   • найден контекст, достаточный для обоснования ответа; или
   • достигнуто 5 попыток, но подходящая информация так и не найдена
4. Действия при недостатке информации
   • Четко сообщить пользователю об отсутствии информации или о том, что она, возможно, отсутствует в текущей базе знаний
   • предоставить найденную наиболее близкую информацию с указанием степени неопределённости
   • подсказать пользователю, как можно сузить круг поиска (более конкретное название документа, ключевые слова, временной диапазон и т. д.)

Важные моменты

• Запрещается с самого начала напрямую вызывать:Glob "knowledge" in . или любые попытки определить наличие каталога с помощью Glob; наличие каталога следует проверять с помощью команд оболочки (например, test -d).
• При использовании данного Skill для поиска в базе знаний запрещается использовать другие инструменты, такие как поиск в Интернете, для получения информации

Конкретные правила для различных типов файлов

1. Файлы в формате Markdown / текстовые файлы (.md, .txt, .log и т. д.)

1. Выбор файлов-кандидатов

   • На основе data_structure.md имени файла и пути определяется релевантность
   • Приоритет отдается файлам с заголовками и оглавлениями (например, сводные документы, обзор проекта)

2. Поиск с помощью grep и локальное чтение

   • Использование инструмента grep для указанных кандидатов в файлы, с ограничением по конкретному расширению с помощью include (например, «*.md»)
   • Для файлов, в которых найдены совпадения, с помощью Read считывать только локальный фрагмент вблизи места совпадения:
     • Управление чтением с помощью смещения по номеру строки и параметра `limit` (например, чтение нескольких десятков строк вперед и назад от строки, содержащей совпадение)
     • Избегайте чтения всего файла

3. Особые случаи

   • если содержимое представляет собой только оглавление/заголовки, продолжить поиск по ссылкам или названиям подразделов для перехода к более подробному содержанию
   • Применяйте «механизм многораундового итеративного поиска» (см. выше «Общие принципы поиска»)

2. Стратегия поиска в PDF-файлах

Рабочий процесс:

1. Сначала: ознакомьтесь с руководством по методам обработки

   • Перед обработкой любого PDF-файла необходимо ознакомиться с файлом references/pdf_reading.md (обратите внимание, что этот файл находится в каталоге Skills, а не в каталоге Knowledge)
   • Особое внимание следует уделить: команде pdftotext, использованию pdfplumber, методам извлечения таблиц и таблице быстрого принятия решений

2. Выбор подходящих PDF-файлов

   • В соответствии с data_structure.md описанию выберите 1–3 наиболее релевантных файла
   • Если пользователь указал конкретный PDF-файл, то предпочтение отдается именно ему

3. Примените изученные методы для извлечения текста

   • Используйте инструменты, рекомендованные в файле pdf_reading.md (предпочтительно pdftotext или pdfplumber)
   • Важно: используйте pdftotext input.pdf output.txt сохраняйте извлечённый текст в файл, а не выводите напрямую в stdout (чтобы избежать использования большого количества токенов)
   • Для извлечения таблиц используйте функцию извлечения таблиц в pdfplumber

4. Выполните поиск по результатам извлечения

   • Используйте grep для поиска ключевых слов в извлечённом тексте
   • Для каждого совпадения извлекайте контекст в пределах определенного диапазона вокруг него (несколько десятков строк вверх и вниз или несколько соседних страниц)
   • Сохраните «имя файла + номер страницы/приблизительное местоположение + фрагмент текста»
   • Примените «механизм многораундового итеративного поиска» (см. вышеприведенные общие принципы поиска)

3. Стратегия поиска в файлах Excel

Рабочий процесс:

1. Сначала: ознакомьтесь с руководством по методам обработки

   • Перед обработкой любого файла Excel необходимо ознакомиться с:
     • references/excel_reading.md — изучить, как считывать рабочие листы (обратите внимание, что этот файл находится в каталоге «Skills», а не в каталоге «Knowledge»)
     • references/excel_analysis.md — изучите, как анализировать данные (обратите внимание, что этот файл находится в каталоге Skills, а не в каталоге Knowledge)
   • Особое внимание следует уделить: методам чтения данных с помощью pandas, фильтрации столбцов, фильтрации данных и операциям агрегирования

2. Выбор подходящего файла Excel

   • Исходя из data_structure.md и названиям файлов/рабочих листов выберите наиболее подходящие таблицы
   • Отдавайте предпочтение рабочим книгам/рабочим листам, содержащим такие ключевые слова, как «отчет», «статистика», «журнал», «конфигурация», «сопоставление» и т. д.
   • если пользователь указал конкретный файл Excel, отдавайте предпочтение этому файлу

3. Примените изученные методы для анализа структуры

   • Используйте pandas для чтения первых 10–50 строк (с учетом nrows ограничения по параметрам)
   • Основное внимание уделить: названиям столбцов/полей, типам данных (числовые значения, даты, текст), ключевым полям
   • Сравнить названия столбцов с задачей пользователя, чтобы выявить потенциальные ключевые поля (например, «доход», «объем продаж», «error_code» и т. д.)

4. Выполните поиск и анализ данных

   • Используйте изученные методы pandas для фильтрации и агрегирования (например, df[df['column'] == value]）
   • считывайте данные только вблизи соответствующих строк, чтобы избежать считывания всей таблицы за один раз
   • если в вопросе указан временной диапазон, добавьте фильтр по времени при поиске
   • Применять «механизм многораундового итеративного поиска» (см. вышеуказанные общие принципы поиска)

Взаимодействие с другими инструментами

Обработка PDF

• Перед обработкой PDF необходимо сначала ознакомиться с файлом references/pdf_reading.md, чтобы изучить методы обработки
• Используйте pdfplumber/pypdf для извлечения текста, таблиц и чтения метаданных
• Для быстрого извлечения текста предпочтительно использовать инструмент командной строки pdftotext

Обработка Excel

• Перед обработкой файлов Excel необходимо ознакомиться с:
  • references/excel_reading.md — ознакомьтесь с методами чтения
  • references/excel_analysis.md — изучите методы анализа
• Используйте pandas для исследования, предварительного просмотра, фильтрации и анализа данных

Принципы использования инструментов

• Grep: используется для поиска номеров строк и совпадающих фрагментов по ключевым словам в указанном файле; всегда указывайте как можно более точные параметры include и path
• Read: используется только для частичного чтения файла; всегда устанавливайте разумное значение limit (например, 200–500 строк) и подходящее смещение
• Для любых файлов, которые могут быть очень большими:
  • запрещается считывать файл напрямую от начала до конца
  • Всегда сначала сужайте область поиска с помощью индексов, каталогов, ключевых слов и т. д., а уже потом приступайте к чтению

Стиль ответов и обработка ошибок

• Стиль ответов
  • По возможности отвечайте на языке, на котором сформулирован вопрос пользователя (китайский/английский).
  • Сначала приведите вывод, а затем кратко обоснуйте его.
  • При необходимости в конце можно указать ссылки на документы и примерное местоположение, например:
    • Источник: design/api_gateway.md, около 100-й строки
    • Источник: репорты/2023_Q1_sales.xlsx, лист «Summary»
• В случае отсутствия или неопределённости информации
  • четко укажите, что в текущей базе знаний не найдено полностью соответствующей информации или можно дать только частичный ответ.
  • Не выдумывайте факты.
  • Подскажите пользователю, как он может помочь сузить круг поиска:
    • указать более конкретный каталог/файл
    • указать более точные ключевые слова или названия полей
    • Указать диапазон дат/версий