Модуль `index` — индекс документов (RAG)

🟢 Модуль строит локальный индекс документов для персоналки/организации и отдаёт его агенту двумя путями: авто-контекстом через хук rag и явным поиском через инструмент index_tool. Источники — папки на сервере и облачные диски (Яндекс.Диск). Модуль dual-transport: один код работает как linked-крейт и как нативная DLL (lean).

Движок поиска — битовые сигнатуры n-грамм (char+word 3-граммы): быстрый recall по popcount, затем точный ре-ранк по тексту. Модели/эмбеддинги не нужны.

Что поставляет

Что	Идентификатор	Описание
Инструмент	`kind: index_tool`	`sources`, `search`, `open`, `status`, `sync`, `add_folder`, `remove`, `enable/disable`, `connect`
Хук	`kind: rag` (опция `index_db`)	README-хук читает индекс и впрыскивает фрагменты в каждый запрос
Агент	`index-demo`	демо-агент + лендинг `/ext/index-demo/`
Хранилище	DuckDB	`data/plugins/index.db` (plugin data_dir)

Модуль включён по умолчанию (id index): он собирается как DLL, кладётся в plugins/ и грузится через config/plugins.yaml (см. «Сборка и деплой»).

Источники

Папка на сервере (`type: local`)

Абсолютный путь на сервере, обязательно внутри security.index.allowed_roots (пусто = разрешены любые пути, ограничение — sandbox agent_os.Fs). Корневые пути (/, C:\) запрещены.

kind: index_tool
name: index
yandex_tool: yandex_disk_idx   # какой yandex_tool использовать в connect

Добавление: index {operation:"add_folder", path:"D:/docs", source:"docs"}.

Яндекс.Диск

Вход по OAuth (см. «Яндекс.Диск»), затем index {operation:"connect", ...} и sync. Файлы Диска скачиваются и извлекается текст (текст — инлайн, бинарь — через внешний конвертер), затем строятся сигнатуры.

Операции `index_tool`

Операция	Аргументы	Что делает
`sources`	—	список источников и состояние (`вкл`/`выкл`) + `allowed_roots`
`add_folder`	`path`, `source`	зарегистрировать серверную папку
`remove`	`source`	удалить источник со всеми документами
`enable` / `disable`	`source`	приостановить/возобновить без удаления
`connect`	`source`, `code?`	OAuth Яндекс.Диска (см. ниже)
`sync` / `build`	`source`	запустить индексацию (в фоне)
`status`	—	`Документов: N; единиц: M` + `allowed_roots`
`search`	`query`, `limit?`	двухступенчатый поиск (владелец = пользователь)
`open`	`uri`	полный текст документа/единицы

Хук `rag` по индексу

kind: rag
name: docs_rag
index_db: data/plugins/index.db   # читать индекс, а не архив
top_k: 5
notice: "Найдено {{count}} фрагментов из базы документов."

Если index_db задан, хук делает двухступенчатый поиск по индексу и строго ограничивает выборку владельцем (user:<ctx.user_id>). Без index_db — прежний режим по BM25-архиву.

Яндекс.Диск: вход

Создайте OAuth-приложение на https://oauth.yandex.ru (права Yandex.Disk REST API: cloud_api:disk.read/write/info), положите в .env YANDEX_OAUTH_CLIENT_ID и YANDEX_OAUTH_CLIENT_SECRET.
Зарегистрируйте Redirect URI (https; для локали принимается http://127.0.0.1:3000/v1/yandex/callback), задайте тот же в oauth.redirect_uri инструмента.
index {operation:"connect", source:"my_disk", tool:"yandex_disk_idx"} — вернётся ссылка; подтвердите — сервер сам обменяет код на токен (GET /v1/yandex/callback, без копирования кода).
index {operation:"sync", source:"my_disk"} → status.

Пер-пользовательский токен: oauth.token_file поддерживает {user} — подставляется санитизированный user_id, у каждого пользователя свой refresh-токен и своя сессия. Пример: data/yandex-oauth/{user}/disk_token.json.

Конфиг

Расположение источника — либо правка server.yaml, либо динамически через add_folder/connect (хранится в БД). Серверный allow-list:

# server.yaml
security:
  index:
    allowed_roots: []     # абсолютные префиксы; пусто = как разрешит Fs sandbox

Сборка и деплой

Lean-DLL: scripts/build-module-dlls.ps1 (или .sh) → target/modules/<profile>/.
Загрузка: строка в config/plugins.yaml (plugins: [ … agent_os_index.dll ]).
Дистрибутив: scripts/build_distrib.* собирает и кладёт DLL в plugins/; config-starter/plugins.yaml её подхватывает.
Модуль в списке dual-transport (30-dll-ready-modules.md).

Демо-агент

index-demo (config/agents/index-demo/) — index_tool + yandex_disk_idx + хук docs_rag + лендинг /ext/index-demo/. Инструкции агента ведут онбординг: сначала спросить, что индексировать, затем подключить источник и синхронизировать.

Модуль index — индекс документов (RAG)