rlm-tools-bsl

MCP-сервер для токен-эффективного анализа кодовых баз 1С (BSL).

Адаптация open-source проекта rlm-tools под специфику платформы 1С:Предприятие — большие кодовые базы, форматы исходников (CF/EDT), структура метаданных, кириллический код, XML-описания объектов.

📖 Публикация на Инфостарте: «rlm-tools-bsl — мастерская для AI-агентов, работающих с 1С»

Установка

Windows — установка + служба одной командой (PowerShell от имени администратора):

irm https://raw.githubusercontent.com/Dach-Coin/rlm-tools-bsl/master/simple-install-from-pip.ps1 -OutFile simple-install-from-pip.ps1
PowerShell -ExecutionPolicy Bypass -File .\simple-install-from-pip.ps1

Скрипт установит пакет из PyPI, зарегистрирует Windows-службу, запустит сервер и проверит health. Повторный запуск — обновление до последней версии.

Если служба не запускается (ошибка 1053 и т.п.) — см. Диагностика Windows-службы.

Linux — установка + systemd-служба одной командой:

curl -LO https://raw.githubusercontent.com/Dach-Coin/rlm-tools-bsl/master/simple-install-from-pip.sh
chmod +x simple-install-from-pip.sh && ./simple-install-from-pip.sh

Docker

cp docker-compose.example.yml docker-compose.yml
# Отредактируйте REPOS_ROOT и другие переменные
docker compose up -d

Контейнер сам автоматически обновляет пакет из PyPI (если версия в PyPI выше, чем текущая в контейнере) при каждом старте (индексы зарегистрированных проектов при старте по умолчанию не пересчитываются; включается это RLM_UPDATE_INDEX_ON_START=1). Для запуска из локальных исходников: uv build перед docker compose up -d --build. Подробности: docs/INSTALL.md

Windows + Docker Desktop: не рекомендуется — I/O через WSL2/Virtiofs в 5-10x медленнее нативного. Индексирование и работа хелперов будут значительно тормозить. Используйте установку на хост (pip/служба). Docker оптимален для Linux.

Из исходников (для разработки)

Требования: Python 3.10+, uv (пакетный менеджер). LLM-ключи опциональны — без них работает базовый функционал.

Windows (PowerShell от имени администратора)

git clone https://github.com/Dach-Coin/rlm-tools-bsl.git
cd rlm-tools-bsl
PowerShell -ExecutionPolicy Bypass -File .\simple-install.ps1

Скрипт идемпотентен: повторный запуск после git pull останавливает службу, очищает stale-артефакты, пересобирает пакет и перезапускает сервер.

Linux

git clone https://github.com/Dach-Coin/rlm-tools-bsl.git
cd rlm-tools-bsl
chmod +x simple-install.sh && ./simple-install.sh

Скрипты установят пакет, зарегистрируют службу, запустят сервер и проверят доступность endpoint'а.

Конфиг для AI-клиента

После установки добавьте в .claude.json / mcp.json:

{
  "mcpServers": {
    "rlm-tools-bsl": {
      "type": "http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}

"type": "http" обязателен для большинства клиентов (Claude Code, Kilo Code, Roo Code, Cursor). Подключение по stdio тоже работает, но HTTP рекомендуется.

Основная философия и предназначение продукта

Получить для AI-ассистента поиск по кодовой базе BSL, сопоставимый по качеству с RAG, но при этом без самого RAG (и его временных затрат на предварительную векторизацию) и при масштабной экономии токенов и контекста на анализ

RAG и RLM — что это

RAG (Retrieval-Augmented Generation) — подход, при котором перед генерацией ответа LLM сначала ищет релевантные фрагменты из заранее проиндексированной базы знаний (эмбеддинги, граф зависимостей, полнотекстовый поиск). Требует предварительной индексации, инфраструктуры и обслуживания.

RLM (Repository-Level Machine-coding) — подход, при котором AI-агент исследует репозиторий напрямую: выполняет поисковые запросы, читает файлы, анализирует структуру — всё в реальном времени, без предварительной векторной индексации.

Зачем нужен RLM поверх встроенных готовых инструментов AI-ассистентов

AI-ассистенты (Claude Code, Cursor, Windsurf и др.) уже умеют читать файлы и искать по коду через встроенные grep/read/glob. Но каждый вызов возвращает сырые данные целиком прямо в контекстное окно агента: полные файлы, длинные списки совпадений, деревья каталогов. На больших конфигурациях 1С (20 000+ файлов) контекст забивается за несколько запросов.

rlm-tools-bsl решает эту проблему: агент отправляет Python-скрипт на сервер (хост, где открыт проект), скрипт выполняется в песочнице, а в контекст возвращается только print() — компактный отфильтрованный результат вместо сырых данных.

Пример: вместо того чтобы прочитать файл на 2000 строк целиком (2000 строк в контекст), агент вызывает extract_procedures(path) и получает список из 15 сигнатур. Затем read_procedure(path, "ОбработкаПроведения") — и получает тело одной нужной процедуры. Типичная экономия — 25-95% контекста.

RLM — не замена RAG, а дополнение

RLM не конкурирует с RAG. Это разные инструменты для разных ситуаций.

RAG — это ткацкий станок на фабрике: мощный, производительный, выдаёт ткани и одежду промышленного качества. Но требует помещения, настройки, обслуживания и времени на запуск.

RLM — это домашняя швейная машинка: компактная, всегда под рукой, можно взять с собой. Не заменит фабрику, но и не требует её. Подшить, перекроить, разобраться в выкройке — быстро и без подготовки.

Или, если ближе автомобильная аналогия:

RAG — огромный дилерский центр: склад на тысячи квадратных метров, штат мастеров в одинаковой форме, любая запчасть найдётся. Но пока запишут, пока примут, пока проведут регламентную диагностику — день ушёл. И счёт в конце за работы впечатляет.

RLM — специализированный автосервис у дома: заехал без записи, мастер сразу под капот, разобрался именно с вашей проблемой и отпустил. Без редких запчастей с другого континента — но для повседневных задач быстрее, дешевле и точнее.

Используйте оба подхода там, где каждый сильнее.

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

Кейс 1: «Разберись в новой конфигурации»

Дали новое расширение или конфигурацию 1С и задали вопрос: «Разберись, как работает вот эта подсистема» или «Что нужно доработать, чтобы добавить новый документ». Поднимать RAG ради разовой задачи нецелесообразно — индексация займёт часы, а ответ нужен сейчас. С rlm-tools-bsl: указал путь к каталогу исходников — и агент уже работает.

Кейс 2: «Оцени внедрение»

Прислали целевую конфигурацию и список бизнес-требований, просят быстро подготовить оценку: какие объекты затронуты, что потребует доработки, где готовая функциональность. Разворачивать инфраструктуру для одной оценки — избыточно. RLM позволяет агенту пройтись по исходникам, найти нужные модули и метаданные, и сформировать оценку за один сеанс.

Кейс 3: «Проверяй код команды каждый день»

Ты — тимлид проекта разработки через хранилище 1С. Много коммитов в хранилище каждый день (синхронизируемое с Git через gitsync). RAG переиндексируется по расписанию раз-два в неделю — ждать долго, а проверять код команды нужно ежедневно. RLM работает по актуальным файлам на диске: синхронизировал хранилище (выгрузил в исходники) → агент сразу видит свежий код.

Кейс 4: «Много активных баз — некогда индексировать»

Ты — разработчик, у которого три и более крупных баз 1С в активной разработке. Пользователи и аналитики постоянно приходят с вопросами, а поднимать и обслуживать RAG-индекс для каждой базы — дорого и долго. Просто указываешь llm + rlm-tools-bsl на каталог с исходниками нужной базы — и отвечаешь на вопросы без какой-либо предварительной подготовки.

Кейс 5: «Запилил фичи — теперь нужна документация»

Ты — разработчик, который долго делал доработки, но не писал документацию и описания «как это работает». Теперь тимлид или архитектор требует описания, а RAG-индекса на твой код ещё нет. Просто указываешь rlm-tools-bsl на исходники своей дев-базы и просишь LLM написать технические описания прямо по коду.

Кейс 6: «Аналитик на новом проекте без RAG»

Ты — аналитик, которому дали чужую базу и несколько подшефных пользователей с постоянными вопросами «а как в программе сделать то, а как это». RAG на проекте нет. Просто указываешь llm + rlm-tools-bsl на исходники базы — и получаешь готовые ответы пользователям, не листая код вручную и не донимая разработчиков.

Ещё подходит, если:

• Нужно проанализировать конкретную подсистему, механизм или блок кастомных доработок
• Работаешь с любым форматом исходников: CF (выгрузка из Конфигуратора), EDT (1C:EDT), MDO
• Конфигурация большая (20K+ файлов) и нельзя скормить всё в контекст одной сессии
• Раньше ты собирал и готовил контекст (модули, граф/стек вызовов, требования) руками и хочешь хотя бы немного облегчить себе жизнь
• Ты планируешь искать по кодовой базе с детерминированными вопросами ("расскажи как работает проведение документа АвансовыйОтчет", "найди http-сервис ОбменСКорпоративнымиСегментами, опиши его методы" и т.д.)

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

• Нужен полный граф зависимостей всех объектов конфигурации — для этого нужен RAG/графовый MCP с предварительной индексацией. Но для точечного анализа конкретного объекта хелпер find_callers_context строит граф BSL-вызовов на лету, а хелпер find_references_to_object (аналог команды в конфигураторе «Найти ссылки → В свойствах») мгновенно показывает все ссылки на объект метаданных из 18 разных источников (реквизиты, подсистемы, планы обмена, функциональные опции, владельцы, ОпределяемыеТипы, роли, команды и т.д.). Хелпер find_defined_types раскрывает ОпределяемыйТип в список реальных типов
• Нужен семантический поиск по описаниям объектов — rlm-tools-bsl ищет по файлам и именам, не по эмбеддингам
• Нечёткие недетерминированные вопросы ("как работает бюджетирование в ЕРП", "как работают ячеистые склады в УТ") — для этого нужен полноценный RAG (либо анализировать с помощью SOTA-моделей, так как они сами смогут преобразовать нечеткую семантику в строгие полнотекстовые запросы к кодовой базе 1С через rlm-tools-bsl)

Фактическое (e2e) сравнение с RAG/графовым подходом

Сравнительное тестирование (апрель 2026) 6 MCP-серверов на конфигурации 1С:Документооборот КОРП 3.0 — 10 бизнес-задач × 6 серверов = 60 агентских запусков. Методология, промпты и результаты: perform_comparison_1c_rag_mcp.

Выводы:

• Три сервера набрали максимум 10/10: rlm-tools-bsl, code-metadata 08.04 и 1c-mcp-metacode — при этом rlm-tools-bsl потребил минимум токенов (117K) и не требует инфраструктуры (docker + lm-studio).
• Версия code-metadata 08.04 поднялась с 7/10 до 10/10 в том числе после добавления механизмов полнотекстового поиска, заимствованных из rlm-tools-bsl.

Предварительное индексирование (опционально, но желательно)

Для ускорения работы на больших конфигурациях можно предварительно построить SQLite-индекс методов и графа вызовов — см. docs/INDEXING.md. На ПК с медленными дисками (HDD, сетевые ресурсы) индексирование фактически обязательно: без индекса файловые операции на конфигурациях размера ERP (20K+ BSL-файлов) приводят к таймаутам (60-90с на каждый вызов glob_files/tree/find_files). Помимо ускорения, предварительно созданные индексы помогают слабым моделям (Minimax, Gemini Flash и др.) выполнять качественный анализ на больших кодовых базах — мгновенные ответы хелперов вместо таймаутов устраняют основную причину ошибок. Поиски по ссылкам для объектов метаданных 1С, связи, типы реквизитов и т.д. - без предварительно построенных индексов ответы на такие запросы будут неточными и шумными.

Наличие каталога .git в исходниках 1С (и установленного Git на хосте с rlm) существенно прокачивает поиск. Если каталог исходников под git - автоматически активируется киллер-фича git_search — полнотекстовый движок git grep по всем файлам конфигурации. Это мощные возможности именно для «непредметного» поиска: любые термины, GUID/номера, сообщения пользователю, куски запросов, строковые литералы, XML-атрибуты форм/прав/СКД, произвольные технические маркеры — всё то, что не выражается как «найди объект МД», «найди процедуру», «найди реквизит». Ищет в том числе по «сырым» .xml/.mdo и текстам, недоступным обычным хелперам и rlm-индексу; включается нативно, без перестройки rlm-индекса. Подробнее — docs/INDEXING.md.

Реестр проектов

Вместо запоминания абсолютных путей к исходникам можно зарегистрировать проекты по именам:

rlm_projects(action="add", name="My Config", path="/path/to/1c-sources", password="МойПароль")
rlm_start(project="My Config", query="find module...")

Пароль обязателен при регистрации проекта. Он потребуется при управлении индексами через mcp-tool rlm_index(build/update/drop) и при любых мутирующих операциях с реестром (remove/update/rename — параметр password). Модель запросит пароль у пользователя. Это требуется, чтобы ai-ассистент не выполнял операции без команды и подтверждения со стороны человека. CLI-интерфейс rlm-bsl-index не требует пароля.

Реестр хранится в projects.json рядом с service.json. Подробнее -- docs/PROJECT_REGISTRY.md

Как работает (под капотом)

Шесть MCP-инструментов (rlm_projects, rlm_index, rlm_start → rlm_help → rlm_execute → rlm_end), песочница с 62 хелперами (52 BSL-специфичных + 8 стандартных + 2 LLM), сессионные кэши, таймауты, безопасность, пример построения графа вызовов на крупной конфигурации (23K+ файлов) — docs/ARCHITECTURE.md

Полный список хелперов — docs/HELPERS.md | Совместное использование с RAG — docs/ARCHITECTURE.md

Карта модулей и зависимостей — docs/MODULE_MAP.md | Внутренние чеклисты разработчика — docs/DEVELOPER_GUIDE.md

Совместимость с оригинальным rlm-tools

Весь функционал оригинального rlm-tools сохранён. BSL-функционал добавлен поверх, не ломая исходную механику. Подробнее — docs/HELPERS.md

Настройка llm_query (опционально)

В песочнице есть хелперы llm_query(prompt, context) и llm_query_batched(prompts, context) — они вызывают «маленькую» LLM прямо из rlm_execute, не возвращаясь в основной контекст агента. Это позволяет классифицировать, фильтровать и суммировать данные на стороне сервера, экономя расход контекста основной модели.

Поддерживаются OpenAI-совместимые endpoint'ы (OpenRouter, Ollama, vLLM) и Anthropic API. Без настройки LLM все остальные хелперы работают нормально.

Подробная настройка, механика, квоты и примеры — docs/LLM_QUERY.md | Все переменные окружения — docs/ENV_REFERENCE.md

Режимы старта сессии анализа: slim (по умолчанию) или full

rlm_start по умолчанию запускает slim-стратегию — компактную маршрутную карту по инструментарию песочницы. Детальные рецепты и описания хелперов агент дозагружает (при необходимости) по запросу через MCP-tool rlm_help(...). Это экономит токены контекста на старте сессии: full-стратегия — ~20К символов inline-справки, slim — в 3.5–4 раза меньше.

Если заметили, что качество анализа низкое и агент путается в выборе хелперов (особенно для слабых моделей вроде Haiku или мелких OSS) — попробуйте перезапустить сервер с RLM_STRATEGY_MODE=full: формат стратегии целиком inline (все рецепты и описания сразу при старте), а тул rlm_help вообще исчезнет из mcp-манифеста сервера. Подробности — docs/ENV_REFERENCE.md (раздел «Стратегия rlm_start»).

Подробная инструкция (конфигурация сервиса, .env, stdio, разработка): docs/INSTALL.md

Все сценарии развёртывания и пример настройки с нуля: docs/QUICKSTART.md

Часто задаваемые вопросы (расширения CFE, пароли, Docker, расход токенов, несколько проектов): docs/FAQ.md

Инструкция для агента-анализатора (усилитель качества отчётов)

Готовый блок правил, который стоит вставить в инструкции вашего AI-ассистента (AGENTS.md, CLAUDE.md, .cursorrules, системный промпт и т.п.) — docs/AGENT_INSTRUCTIONS.md. Он задаёт агенту дисциплину работы с rlm-tools-bsl: загрузить рецепты rlm_help перед работой, плотно батчить вызовы, проверять индекс, брать факты только из прочитанных данных (а не из имени объекта), считать состав программно, добирать недостающее полнотекстом и выполнять финальную сверку. На практике это заметно повышает полноту и точность отчётов и снижает расход токенов — особенно у моделей послабее.

Тестирование на реальных данных

Перед каждым новым релизом выполняется на:

• BSL-кодовой базе доработанной ERP 2.5 (формат выгрузки - конфигуратор).
• BSL-кодовой базе доработанной ERP 2.4 (формат выгрузки - EDT).
• BSL-кодовой базе доработанного ДО 3 (формат выгрузки - конфигуратор).
• BSL-выгрузках расширений в обоих форматах.

Готовые промпты для комплексных E2E-тестов BSL-хелперов: docs/full_analysis_prompt.md

Лицензия

MIT (наследуется от rlm-tools)

Changelog

История изменений: CHANGELOG.md