Skip to content

FAQ.md

Latest commit

 

History

History
226 lines (135 loc) · 17 KB

FAQ.md

File metadata and controls

226 lines (135 loc) · 17 KB
Raw

FAQ — rlm-tools-bsl

Сборник часто задаваемых вопросов от пользователей. Если не нашли ответа — пишите Issue на GitHub.

Регистрация проекта

Я добавил проект, но в projects.json нет поля с паролем — это нормально?

Да, руками установить пароль нельзя — он хранится в виде хэша (password_hash + password_salt в JSON). Установка пароля выполняется только через MCP-tool rlm_projects(action="add" | "update", password="...").

Если зарегистрировали проект без пароля — попросите AI задать его:

Задай пароль "МойПароль" текущему проекту через rlm-tools-bsl

Проверка кода: projects.py — функции _hash_password (PBKDF2-SHA256) и _verify_password.

AI-агент случайно записал пароль в поле description — что делать?

Бывает: агент копирует пример из доки буквально и не понимает, что пароль должен идти отдельным параметром. Решение — переформулировать промпт явно:

Удали проект X через rlm_projects, затем зарегай его заново с теми же путями и отдельным параметром password

Не правьте projects.json руками — пароль всё равно не запишется (нужен хэш и соль).

Что-то сломалось при регистрации, можно ли удалить запись через файл?

Можно — projects.json это обычный JSON. Но если удалили проект через файл — повторно зарегистрируйте через MCP, иначе пароль не получится установить корректно.

Расширения 1С (CFE)

У меня основная конфа в src/cf, расширения в src/cfe — какой путь указать в проекте?

Можно указывать либо src/cf, либо верхнеуровневый src/ — утилита сама найдёт корень основной конфы. Если в src/ лежит ровно одна MAIN-конфигурация в прямой подпапке (или ровно одна из нескольких называется cf — типичный случай vanessa-bootstrap), она берётся автоматически. Расширения в src/cfe подхватываются в обоих случаях.

D:/Repos/myproject/
├── src/           ← можно указать здесь (path="D:/Repos/myproject/src")
│   ├── cf/        ← либо сразу здесь (path="D:/Repos/myproject/src/cf")
│   └── cfe/       ← расширения подхватываются автоматически

Существующие проекты с путём до src/cf/ продолжают работать без изменений.

Если в контейнере несколько MAIN-подпапок и ни одна не называется cf — rlm_start/rlm_index вернут ошибку со списком кандидатов. В этом случае укажите путь точнее (до конкретной конфы).

А расширения тоже индексируются?

Нет. Индексируется только основная конфа. Расширения в cfe/ в индекс не входят, но при анализе они подгружаются на лету: find_ext_overrides() сканирует все расширения параллельно (~1 сек на 5 расширений). Это сделано намеренно — расширений обычно мало, индексирование их не даёт большого ускорения.

Я скачал расширение отдельно — как его подключить?

Положите рядом с основной конфой по соглашению Vanessa-bootstrap (src/cf + src/cfe). Если по структуре отличается — придётся анализировать вручную через find_ext_overrides(extension_path=...).

Индексы

Когда нужно пересобирать индекс?

Только в двух случаях:

  1. После обновления rlm-tools-bsl на новую версию с изменением builder_version в bsl_index.py. Смотрите CHANGELOG.md — если в записи о версии есть строка о повышении builder_version или о новых таблицах — пересоберите. Альтернатива: rlm-bsl-index index update — он сам определит несовпадение версий и сделает force_full_scan.

  2. После массовых изменений в исходниках (merge, rebase, выгрузка из конфигуратора). Используйте index update — он работает за секунды через git diff, если каталог в Git-репо.

Чем update отличается от build?

index build index update
Полное перестроение да (DB удаляется) нет
При version mismatch — автоматически делает force_full_scan (эквивалент build)
Время на ERP (24K модулей) ~10 мин 5–20 сек (BSL-only) или 2 мин (force_full_scan)
Когда использовать первый раз дальше всегда

Почему запросы медленные без индекса?

Без индекса каждый find_* вызов сканирует файловую систему (rglob) и парсит XML/BSL на лету. На конфигурациях 20K+ модулей это 30–60 сек на вызов. С индексом — миллисекунды (один SQL запрос).

Для слабых моделей (Minimax, Kimi, GLM-4.5 и т.п.) индекс обязателен — иначе они не справятся с многошаговыми fallback-цепочками.

Проекты в командной работе и Docker

Зачем имена проектов, если есть пути?

Имена проектов — для удобства:

  • Если сервер на Docker / удалённом хосте — пути внутри контейнера могут отличаться от хостовых. С RLM_PATH_MAP (host→container префиксы) и именами проектов вам не нужно помнить пути в контейнере.
  • Если вы тимлид команды — раздаёте коллегам только имена проектов и (опционально) пароли. Они пишут «проанализируй ЕРП», а пути уже зарегистрированы вами.
  • Промпты получаются короче и переносимы между разработчиками.

Можно ли использовать без имени проекта?

Да — передать path напрямую в rlm_start(path=...). Но если у вас несколько проектов, AI не угадает какой из них использовать без явного указания. Поэтому в промпте либо:

  • «проанализируй с помощью rlm-tools-bsl проект ЕРП» (по имени, AI вызовет rlm_start(name="ЕРП"))
  • «проанализируй с помощью rlm-tools-bsl D:/work/erp/src/cf» (по пути)

Как настроить удобный маппинг в Docker?

В .env контейнера задайте PATH-маппинг:

REPOS_ROOT=E:/git
RLM_PATH_MAP=E:/git:/repos
RLM_PORT=9000

RLM_PATH_MAP — это host_prefix:container_prefix. После этого вы регистрируете проекты с хостовыми путями (E:/git/myproject/src/cf), а внутри контейнера они автоматически транслируются в /repos/myproject/src/cf. См. server.py _resolve_path_map.

Зачем нужен пароль на проект?

Две причины:

  1. Защита от самовольных действий AI. Без пароля модель может сама удалить индекс / проект «потому что он устарел» — пароль блокирует мутирующие операции.
  2. Командная безопасность. Тимлид раздаёт команде имена проектов; коллеги не могут случайно сломать чужой индекс / удалить проект.

Пароль нужен только для remove, rename, update и для rlm_index(action="build" | "drop"). Чтение (rlm_start, анализ) пароль не требует.

Расход токенов

Сколько токенов тратит rlm-tools-bsl?

В среднем — ~200K токенов на сложный анализ (комплексный промпт по типу одного из промптов full_analysis_prompt.md). На простых вопросах («сколько процедур в модуле X», «найди вызовы Y») — 5–20K токенов.

Если у вас Claude Pro за $20 — лимиты тарифа на 5-часовую сессию могут закончиться на одной серьёзной задаче. На Claude Max / Codex Pro / GLM — комфортно.

Как посмотреть сколько токенов потратил конкретный анализ?

В логах сервера. Откройте ~/.config/rlm-tools-bsl/logs/server.log (Windows: %USERPROFILE%\.config\rlm-tools-bsl\logs\server.log). Каждая запись rlm_execute содержит out_chars=N out_tokens~M. Сумма out_tokens за сессию = расход на ответы хелперов.

У меня съело 60% токенов на маленькую задачу. Это нормально?

Зависит от:

  • Подписки. На Claude Pro лимиты низкие, так что даже 200K токенов в сессии могут «съесть» 60% бюджета на 5 часов.
  • Что именно делалось. Если AI писал код (а не только анализировал) — основной расход на генерацию, а не на rlm. Проверьте логи rlm — там видно реальный расход именно на анализ.
  • Поднят ли rlm-индекс. Без индекса каждый запрос гоняет fallback-цепочки, токенов в 3–5 раз больше.

Рекомендации: (1) обязательно постройте индекс, (2) переходите на тариф выше или используйте альтернативные модели (GLM, Qwen3-Coder и т.п.).

Несколько проектов

Если у меня 3 разные конфы — как работать?

Зарегистрируйте все три через rlm_projects(action="add", name="ИмяX", path="..."). Затем в промпте обязательно указывайте имя проекта:

Построй индекс для БП Проанализируй документ РТУ в ЕРП Найди ссылки на Контрагенты в МояКонфигурация

Без указания имени AI не угадает, в каком проекте смотреть, и либо спросит вас, либо использует первый по алфавиту, либо ошибётся.

Можно ли работать без регистрации проекта, через path?

Да — rlm_start(path="D:/work/erp/src/cf"). Но при работе с несколькими проектами это неудобно (придётся каждый раз вводить путь). Регистрация — это разовая операция, дальше используете имена.

Качество анализа и промпты

AI «не понимает» rlm-tools-bsl, делает грепы по всей папке

Возможные причины:

  1. Не подключен MCP — проверьте, что rlm-tools-bsl есть в списке MCP-серверов и rlm_start доступен в чате.
  2. AI не вызвал rlm_start — он не подцепится к индексу. Уточните в промпте: «начни с rlm_start по проекту X».
  3. Слабая модель. На GPT-4o-mini, Kimi K2 и т.п. без явных инструкций про MCP rlm может не использоваться.

Прелесть rlm в том, что ей не нужны инструкции, как ей пользоваться — стратегия и рецепты возвращаются в rlm_start ответе. Сильным моделям (Claude Sonnet/Opus, GPT-5) этого достаточно. Слабым — добавьте в rules/skills короткое: «всегда начинай анализ 1С через MCP rlm-tools-bsl, начни с rlm_start».

Где найти готовые промпты для типовых задач?

См. docs/full_analysis_prompt.md — там 10 готовых промптов для разных задач:

  • Полный анализ документа (все 63 хелпера)
  • Анализ интеграции (HTTP/SOAP/XDTO/планы обмена) — v1.4.0
  • Object Synonyms (бизнес-имена) — v1.4.1
  • Regions & Module Headers (семантический контекст кода) — v1.4.2
  • Extension Overrides (перехваты в расширениях) — v1.5.0
  • Unified Search (broad-first поиск) — v1.5.1
  • Form Analysis (формы, обработчики, команды) — v1.6.0
  • Attribute Types & Predefined Items (типы реквизитов, предопределённые) — v1.7.0
  • Where-Used Analysis (поиск ссылок на объект) — v1.9.0
  • Reverse-Index Coverage Audit (полнота reverse-index) — v1.9.0

Версии и обновление

Я обновил rlm-tools-bsl. Нужно ли что-то делать с индексами?

Откройте CHANGELOG.md и найдите описание новой версии. Если в release-notes написано «Индекс vN→vM требует rebuild» (либо упоминается «BUILDER_VERSION», «новые таблицы») — пересоберите индекс.

Альтернатива — просто запустить rlm-bsl-index index update <path>. При несовпадении builder_version сервер автоматически выполнит force_full_scan, который создаст новые таблицы и наполнит их.

rlm_start также покажет warning при подключении к старому индексу:

Index built with v11, current v12 — new helpers available after rebuild

Как узнать версию индекса?

rlm-bsl-index index info <path>

Или через AI: «покажи статистику индекса проекта X». Поле Index: v12 в выдаче — текущая версия.

Что почитать дальше

  • QUICKSTART.md — установка и первые шаги
  • HELPERS.md — полный список из 63 хелперов с примерами
  • INDEXING.md — устройство SQLite-индекса (27 таблиц + FTS5)
  • ARCHITECTURE.md — общая архитектура
  • full_analysis_prompt.md — готовые E2E-промпты для типовых задач