cc-1c-skills/docs/db-guide.md

Базы данных 1С

Навыки группы /db-* позволяют управлять информационными базами 1С из Claude Code: создавать базы, загружать и выгружать конфигурации, обновлять БД, запускать предприятие, загружать изменения из Git.

Навыки

Навык	Скрипт	Описание
/db-list	—	Управление реестром баз (.v8-project.json)
/db-create	—	Создание информационной базы
/db-dump-cf	—	Выгрузка конфигурации в CF-файл
/db-load-cf	—	Загрузка конфигурации из CF-файла
/db-dump-xml	.ps1	Выгрузка конфигурации в XML-файлы (полная/инкрементальная/частичная)
/db-load-xml	.ps1	Загрузка конфигурации из XML-файлов (полная/частичная)
/db-update	—	Обновление конфигурации БД
/db-run	—	Запуск 1С:Предприятие
/db-load-git	.ps1	Загрузка изменений из Git в базу
/db-repo	.ps1	Хранилище конфигурации: захват, помещение, получение изменений
/db-cfe-admin	.ps1	Расширения в базе: список и состояние, проверка применимости и модулей, свойства подключения, удаление

Рабочий цикл

.v8-project.json → /db-create → /db-load-cf или /db-load-xml → /db-update → /db-run
                                                                    ↑
                                 /db-dump-xml ←→ правки в исходниках → /db-load-git → /db-update

Типичный цикл разработки

1. Настройка — /db-list add зарегистрировать базу в .v8-project.json
2. Создание — /db-create создать базу (если нет)
3. Загрузка — /db-load-xml или /db-load-cf загрузить конфигурацию
4. Обновление — /db-update применить к БД
5. Работа — редактирование XML-исходников
6. Синхронизация — /db-load-git загрузить изменения из Git
7. Обновление — /db-update применить
8. Запуск — /db-run открыть предприятие

Работа с хранилищем конфигурации

База, подключённая к хранилищу, живёт по другим правилам, и это меняет весь цикл:

• полная загрузка XML в неё невозможна — платформа отвечает «текущая конфигурация помещена в хранилище». Работает только -Mode Partial;
• частичная загрузка проходит только по захваченным объектам, иначе отказ с именем объекта;
• новый объект требует захвата корня конфигурации — без него частичная загрузка не пройдёт;
• любой команде конфигуратора нужны реквизиты хранилища. Их берут из repository записи базы (см. справочник .v8-project.json), передавать в каждом вызове не нужно.

Цикл разработки под хранилищем:

/db-repo update  →  /db-repo lock  →  /db-dump-xml -Mode Partial  →  правки
                                                                        ↓
              /db-repo commit  ←  /db-load-xml -Mode Partial -UpdateDB

Выгрузка после захвата обязательна: захват и обновление молча подтягивают из хранилища свежие версии объектов, и загрузка исходников, снятых раньше, откатит чужие изменения без единой ошибки. /db-repo печатает список полученных объектов и готовую команду выгрузки.

Подробности — в SKILL.md навыка /db-repo.

Формат .v8-project.json

Полное описание формата — в справочнике .v8-project.json.

Разрешение базы

Все навыки db-* (а также epf-build, epf-dump, erf-build, erf-dump) используют единый алгоритм:

1. Если пользователь указал параметры подключения (путь, сервер) — используй напрямую
2. Если указал базу по имени — ищи: id → aliases (с учётом морфологии) → name (нечёткое)
3. Если не указал — сопоставь текущую ветку Git с branches (точно или по glob-паттерну)
4. Fallback на default
5. Если не найдено — спроси пользователя
6. После выполнения: если использованная база не зарегистрирована — предложи добавить через /db-list add

Сценарии использования

Создать базу и загрузить конфигурацию

> Создай файловую базу C:\Bases\Test и загрузи в неё конфигурацию из C:\WS\cfsrc

Claude вызовет /db-create → /db-load-xml -Mode Full → предложит /db-update.

Загрузить изменения из Git

> Загрузи мои последние правки в базу разработки

Claude вызовет /db-load-git dev -Source All → предложит /db-update.

Выгрузить конфигурацию

> Выгрузи конфигурацию из тестовой базы в C:\WS\cfsrc

Claude вызовет /db-dump-xml test C:\WS\cfsrc -Mode Full.

Работа с расширениями

> Выгрузи расширение МоёРасширение из базы dev в C:\WS\ext_src

Claude вызовет /db-dump-xml dev C:\WS\ext_src -Extension МоёРасширение.

> Загрузи расширение обратно в базу

Claude вызовет /db-load-xml C:\WS\ext_src dev -Extension МоёРасширение → предложит /db-update -Extension МоёРасширение.

Запустить предприятие

> Запусти базу разработки

Claude вызовет /db-run dev.

Движок: 1cv8 или ibcmd

По умолчанию навыки группы работают через конфигуратор (1cv8.exe; путь к нему определяется автоматически по каталогу v8path) — менять это не нужно. При желании ту же операцию можно выполнить через автономный сервер ibcmd. Для этого навыку нужно передать путь к самому файлу ibcmd.exe (каталог bin всегда трактуется как 1cv8.exe; отдельного поля-переключателя в .v8-project.json нет). Путь указывают одним из двух способов:

• разово, в самой задаче — назвать полный путь к ibcmd.exe:

  > Собери обработку, платформа C:\Program Files\1cv8\8.3.24.1691\bin\ibcmd.exe
  

• в файле настроек — прописать в v8path не каталог bin, а сам файл ...\bin\ibcmd.exe (тогда через ibcmd пойдут все операции).

Через ibcmd работают: db-create, db-load-xml/db-dump-xml (в том числе по отдельным объектам и со всеми расширениями), db-load-cf/db-dump-cf, db-load-dt/db-dump-dt, db-update, db-load-git, epf-build/epf-dump, erf-build/erf-dump.

При выгрузке конфигурации выбор движка на результат не влияет: выгрузка одной и той же базы конфигуратором и ibcmd совпадает побайтно (проверено на полной выгрузке типовой конфигурации — 91807 файлов из 91807). Дампы конфигурации, снятые разными движками, сравнимы напрямую.

Это НЕ распространяется на разбор внешних обработок и отчётов (epf-dump/erf-dump): там результат определяется базой, в которой идёт разбор, а движок начинает влиять, когда база не та.

Замер на реквизите типа CatalogRef.Валюты (платформа 8.3.24):

База разбора	Движок	Что попадает в исходники
с подходящей конфигурацией	1cv8 и ibcmd одинаково	<v8:Type>cfg:CatalogRef.Валюты</v8:Type>
без нужного объекта	ibcmd	<v8:TypeId>602d2ea9-…</v8:TypeId> — идентификатор типа
без нужного объекта	1cv8	<v8:Type>xs:string</v8:Type> + StringQualifiers Length=10

Годится только первая строка, и вот почему. Имя типа резолвится по имени: такие исходники собираются в любой конфигурации, где есть одноимённый объект. Идентификатор же привязан к той конфигурации, из которой получен: сборка в чужой базе проходит без ошибки, но uuid остаётся висячим и ни к чему не привязывается — работать с такими исходниками нельзя. Вариант с xs:string хуже всех: ссылка подменена строкой, и по XML не видно, что там вообще была ссылка.

Оба деградированных варианта молчаливы — ни при разборе, ни при последующей сборке ошибок нет. Поэтому разбирать EPF/ERF нужно в базе с подходящей конфигурацией; «разберу в пустой, потом поправлю» не работает.

Ограничения:

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

Дополнительные аргументы платформы

Набор аргументов, который скрипт формирует сам, закрыт: подключение, пакетная операция, /Out. Общие ключи платформы, которых нет среди параметров навыка (/UseHwLicenses+, /L, /ClearCache, /DebuggerURL, …), передаются через escape hatch — по одному параметру на движок:

Движок	Параметр	Ключ в .v8-project.json
1cv8.exe	-AdditionalV8Arguments	v8args
ibcmd	-AdditionalIbcmdArguments	ibcmdargs

# разово; несколько аргументов — через запятую, как у -Objects/-Files
powershell.exe -NoProfile -File "…/epf-build.ps1" -SourceFile "src/Обработка.xml" `
    -OutputFile "build/Обработка.epf" -AdditionalV8Arguments "/UseHwLicenses+,/L,ru"

Список пишется одной строкой через запятую: при запуске скрипта через -File PowerShell не умеет собирать массив из отдельных токенов. Значение, содержащее запятую, не поддерживается.

Проектные аргументы применяются первыми, параметр — после них. Аргументы уходят во все запуски платформы, которые делает навык: epf-build без указания базы прогоняет CREATEINFOBASE, /LoadConfigFromFiles, /UpdateDBCfg и саму сборку — ключ получит каждый.

Что отклоняется до запуска, с указанием штатного параметра:

• аргумент, которым управляет сам скрипт: режим (DESIGNER, ENTERPRISE, CREATEINFOBASE), подключение (/F, /S, /N, /P), /Out, пакетная операция (/Load*, /Dump*, /UpdateDBCfg, …). Платформа допускает лишь одну пакетную операцию, а дубль ключа подключения даёт невнятную ошибку 1С;
• для ibcmd — позиционный токен: команда (infobase create, config import) принадлежит навыку, поэтому значения передаются только в форме --ключ=значение;
• параметр «не своего» движка (-AdditionalV8Arguments при выбранном ibcmd). Ключи из .v8-project.json в этом случае просто не применяются — реестр проекта может описывать оба движка.

Что печатает навык

Порядок один и тот же в обоих портах и на обоих движках:

1. Running: … — командная строка запуска (секреты замаскированы, см. ниже);
2. результат операции одной строкой;
3. --- Log --- … --- End --- — журнал платформы из /Out (у ibcmd его нет);
4. --- Вывод платформы --- … --- End --- — то, что платформа написала в консоль.

Четвёртый блок появляется, только если платформа что-то написала. В пакетном режиме 1cv8 пишет в /Out и молчит в консоли, поэтому обычно блока нет; он всплывает при аварийном завершении, когда сообщение проходит мимо /Out. ibcmd, наоборот, весь свой вывод ([INFO] …) шлёт именно туда.

Кодировка определяется по факту: UTF-8, при неудаче — cp866. Гадать нельзя — ibcmd пишет UTF-8, а аварийный текст 1cv8 приходит в OEM.

Путевые параметры прощают обрамляющие кавычки, пробелы по краям и хвостовой разделитель. Навыки, работающие с готовой базой, проверяют её наличие до запуска и говорят «information base not found at X» вместо платформенного «Неверные или отсутствующие параметры соединения».

В строке Running: … значения секрето-опасных ключей (/P, /UC, --password, --token) заменяются на ***. Ограничения разбора, о которых стоит знать:

• слитое значение, начинающееся с буквы (/Psecret вместо /P"secret"), неотличимо от более длинного ключа — такой аргумент не будет ни распознан как конфликт, ни замаскирован;
• содержимое файла параметров /@ не разбирается — за его состав отвечает вызывающий.

Спецификации

• build-spec.md — пакетный режим конфигуратора 1С (CREATEINFOBASE, DESIGNER, ENTERPRISE, параметры, коды возврата)