diff --git a/docs/skd-guide.md b/docs/skd-guide.md index 661be5d1..c74c45c9 100644 --- a/docs/skd-guide.md +++ b/docs/skd-guide.md @@ -8,6 +8,7 @@ |-------|-----------|----------| | `/skd-info` | ` [-Mode] [-Name]` | Анализ структуры СКД: наборы, поля, параметры, ресурсы, варианты (11 режимов, включая full) | | `/skd-compile` | `[-DefinitionFile \| -Value ] -OutputPath ` | Генерация Template.xml из JSON DSL: наборы, поля, итоги, параметры, варианты | +| `/skd-decompile` | ` [-OutputPath ]` | Преобразование Template.xml в JSON-черновик в формате `/skd-compile` — для нового отчёта по образцу или структурной переработки существующего. Из соображений предосторожности исключён из автоматического подбора моделью — вызывается только явной командой | | `/skd-edit` | ` -Operation -Value ""` | Точечное редактирование: 26 атомарных операций (add/set/patch/modify/clear/remove) | | `/skd-validate` | ` [-MaxErrors 20]` | Валидация структурной корректности: ~30 проверок | @@ -15,15 +16,23 @@ ``` Описание отчёта (текст) → JSON DSL → /skd-compile → Template.xml → /skd-validate - ↕ /skd-edit → /skd-info + ↑ ↕ /skd-edit → /skd-info + └──── /skd-decompile ──────┘ ``` -1. Claude формирует JSON-определение СКД (shorthand-поля, параметры, итоги, варианты) +1. Claude формирует JSON-определение СКД (shorthand-поля, параметры, итоги, варианты) — либо с нуля по описанию, либо `/skd-decompile` готовит черновик по существующему Template.xml 2. `/skd-compile` генерирует Template.xml с корректными namespace, типами, группировками 3. `/skd-edit` вносит точечные изменения: добавление полей, фильтров, наборов данных, вариантов, условного оформления и т.д. 4. `/skd-validate` проверяет корректность XML 5. `/skd-info` выводит компактную сводку для визуальной проверки +### Когда `/skd-decompile`, а когда `/skd-edit` + +- **`/skd-edit`** — точечные правки готового отчёта (добавить поле, фильтр, итог, переименовать параметр). Меняет XML адресно, без полной реконструкции, не задевает непокрытые конструкции. +- **`/skd-decompile` → правка JSON → `/skd-compile`** — сценарии, где правки структурны: новый отчёт по образцу существующего, переработка варианта, перерисовка макета, перебор набора полей. Цикл переписывает Template.xml целиком. + + **Полнота не гарантируется.** Известные декомпилятору непокрытые конструкции явно отмечаются маркерами в JSON и собираются в файл предупреждений — компилятор откажется собирать такой черновик, пока маркеры не разрешены вручную или не удалены. Но возможны и **тихие потери** — мелкое оформление, редкие настройки, незнакомые декомпилятору расширения. Это даёт валидный XML без части функциональности, и Конфигуратор такой результат не отбракует. Именно поэтому навык не предназначен для точечных правок (для них есть `/skd-edit`) и исключён из автоматического подбора моделью — вызывается только явной командой пользователя. Решение использовать пересобранный Template.xml — на стороне пользователя, и сверка с оригиналом перед коммитом остаётся его ответственностью. + ## JSON DSL — компактный формат СКД описываются в JSON с двумя уровнями детализации для каждой секции: