# v8help

MCP-инструмент и CLI для чтения, индексации и поиска по файлам справки
1С:Предприятие (`.hbk`).

Извлекает HTML-страницы из V8-контейнера справки, конвертирует их в Markdown,
строит полнотекстовый индекс (SQLite FTS5) и отдаёт поиск через MCP-сервер
(stdio или streamable-http) или командную строку.

## Возможности

- Самодостаточная пересборка корпуса из `.hbk` одной командой `build`
  (распаковка → консолидация → индексация).
- Чтение контейнеров `Format15` с корректным парсингом TOC (включая свободные
  блоки, которые ломают штатный `onec_dtools.read_entries`).
- Единый конвертер HTML → Markdown: заголовки по `V8SH_pagetitle` (синтакс-
  помощник), имена по пути архива (язык запросов и др.), переписывание ссылок
  `v8help://...` в относительные `.md`.
- Полнотекстовый поиск FTS5 с лексическим расширением (разбиение
  PascalCase-идентификаторов, например `СтрНайтиПоРегулярномуВыражению`).
- Ранжирование FTS с весами полей `title`/`description`/`body` (9/3/1): совпадение
  в заголовке или в секции «Описание» метода весомее совпадения в теле.
- Чанкование длинных статей (настраиваемые `chunk_size`/`chunk_overlap`) с
  метаданными чанка (родитель, соседние чанки) — единицы поиска и чтения.
- Векторный и гибридный поиск (FTS + эмбеддинги, RRF-фьюжн) через
  OpenAI-совместимый API эмбеддингов (LM Studio, Ollama, Hugging Face).
- Асинхронная сборка через MCP: `build` возвращает `job_id` сразу, прогресс —
  через `build_status`; поиск при этом не блокируется (атомарная подмена БД).
- Автодискавери: каталог `bin` платформы (реестр Uninstall/ФС) и доступные
  эмбеддеры на localhost-портах; настройка через MCP (`config_get`/`config_set`).

## Требования

- Python 3.11+
- Установленная платформа 1С:Предприятие (каталог `bin` с `.hbk`-файлами) — нужна
  только для пересборки индекса; для поиска достаточно готовой БД (см.
  [«Готовые индексы»](docs/configuration.md#готовые-индексы-без-установленной-платформы)).
- (опционально) эмбеддер для векторного поиска — LM Studio, Ollama или Hugging Face.

## Установка

### Локальная установка

```bash
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -e .
```

Установка регистрирует два консольных скрипта: `v8help` (CLI) и
`v8help-mcp` (MCP-сервер).

### Установка в Docker

Готовый контейнер с HTTP-интерфейсом (streamable-http), БД на volume и
опциональной авто-загрузкой индекса — см. [Запуск в Docker](docs/docker.md).

## Быстрый старт

```bash
copy v8help.example.toml v8help.toml    # Windows (Linux/macOS: cp)
# укажите bin_dir своей платформы в v8help.toml
v8help build                            # собрать индекс (несколько минут)
v8help search "регулярному"             # поиск
```

Для векторного/гибридного поиска настройте эмбеддер (см.
[Эмбеддинги](docs/embedding.md)).

## Документация

- [Использование: CLI и MCP](docs/usage.md) — все команды, параметры и инструменты.
- [Конфигурация](docs/configuration.md) — `v8help.toml`, ключи, неймспейсы.
- [Эмбеддинги и гибридный поиск](docs/embedding.md) — LM Studio / Ollama / HF.
- [Запуск в Docker](docs/docker.md) — контейнер, volume, env, инициализация БД.
- [Разработка](docs/development.md) — сборка, тесты, структура кода.

## Лицензия

MIT — см. [LICENSE](LICENSE).

## Благодарности

Конвертер HTML → Markdown портирован из
[hbk-to-md](https://github.com/pzayash/hbk-to-md).