From 643211f2fb74d1a2f95b6509ccde64d9d206ec5b Mon Sep 17 00:00:00 2001 From: Nick Shirokov Date: Thu, 21 May 2026 13:50:46 +0300 Subject: [PATCH] =?UTF-8?q?docs(skd-decompile):=20=D1=87=D0=B5=D1=81=D1=82?= =?UTF-8?q?=D0=BD=D0=B0=D1=8F=20=D1=84=D0=BE=D1=80=D0=BC=D1=83=D0=BB=D0=B8?= =?UTF-8?q?=D1=80=D0=BE=D0=B2=D0=BA=D0=B0=20scope=20=D0=B2=20SKILL.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Убрал ложное обещание «структурной эквивалентности» (DSL покрывает подмножество СКД). Слил «Гарантии» и «Не поддерживается» в раздел «Что получаешь» с тремя категориями (покрытое / sentinel / fail-fast). Добавил Workflow — декомпил это начало процесса, а не финал. Co-Authored-By: Claude Opus 4.7 --- .claude/skills/skd-decompile/SKILL.md | 47 +++++++++++---------------- 1 file changed, 19 insertions(+), 28 deletions(-) diff --git a/.claude/skills/skd-decompile/SKILL.md b/.claude/skills/skd-decompile/SKILL.md index 47f55aeb..8b5e1277 100644 --- a/.claude/skills/skd-decompile/SKILL.md +++ b/.claude/skills/skd-decompile/SKILL.md @@ -10,21 +10,20 @@ allowed-tools: - Glob --- -# /skd-decompile — извлечение JSON-черновика из Template.xml СКД +# /skd-decompile — JSON-черновик из Template.xml СКД -Читает существующий `Template.xml` (DataCompositionSchema) и эмитит JSON в формате, который принимает `/skd-compile`. Получившийся JSON — **черновик**: гарантируется только структурная эквивалентность, не байтовая. +Читает Template.xml и эмитит JSON в формате `skd-compile`. **Результат — черновик**, а не обратимое представление: см. раздел «Что получаешь». ## Когда использовать -- **Scaffold нового отчёта по образцу.** Взять существующий СКД, получить JSON, поправить параметры/поля/шаблоны, скомпилировать в новый отчёт. -- **Глобальный рефакторинг.** Когда правка структурная (переписать вариант, перерисовать шаблон), а не точечная. +- **Scaffold нового отчёта по образцу** — взять существующий СКД, получить JSON, поправить и скомпилировать в новый. +- **Структурный рефакторинг** — переписать вариант, перерисовать шаблон, перебрать набор полей. ## Когда **не** использовать -- **Точечные правки готового отчёта** — добавить поле, фильтр, итог, переименовать. Для этого есть `/skd-edit`: точечно, без полной реконструкции, без риска потерь. -- **Анализ схемы** — для обзора используй `/skd-info` (overview/query/fields/variant/templates). +- **Точечные правки готового отчёта** (добавить поле, фильтр, итог, переименовать) → `/skd-edit`. Точечно, без потерь, без полной реконструкции. -## Параметры и команда +## Параметры | Параметр | Описание | |----------|----------| @@ -32,33 +31,25 @@ allowed-tools: | `OutputPath` | Путь к выходному JSON. Если не задан — JSON в stdout | ```powershell -# В файл (рядом, если есть warnings, кладётся .warnings.md) powershell.exe -NoProfile -File "${CLAUDE_SKILL_DIR}/scripts/skd-decompile.ps1" -TemplatePath "" -OutputPath "" - -# В stdout -powershell.exe -NoProfile -File "${CLAUDE_SKILL_DIR}/scripts/skd-decompile.ps1" -TemplatePath "" ``` -## Гарантии и ограничения +При наличии `-OutputPath` рядом пишется `.warnings.md`, если есть непокрытые конструкции. -- **JSON всегда валиден** — компилируется через `skd-compile` без синтаксических ошибок. -- **Покрытие — DSL `skd-compile`.** Конструкции XML вне DSL отмечаются sentinel-объектом `{"__unsupported__": {...}}` и описаны в `.warnings.md` рядом с JSON. `skd-compile` фейлится при наличии sentinel — это специально, чтобы пользователь сначала разобрался с непокрытым. -- **Не байтовая эквивалентность.** После round-trip XML структурно эквивалентен оригиналу, но порядок атрибутов/секций может отличаться. -- **Стиль ячейки** определяется по совпадению с одним из built-in (`header`/`data`/`subheader`/`total`) или user-стилей из `presets/skills/skd/skd-styles.json`. Точечный custom appearance не сворачивается → sentinel. +## Что получаешь -## Не поддерживается (fail-fast) +JSON — это **черновик, не полное обратимое представление СКД**. Декомпилятор знает только то, что умеет `skd-compile`, поэтому: -- Picture cells в шаблонах (``). -- Параметры типа ХранилищеЗначения. -- Sibling templates / templateCondition (вариативные шаблоны). -- Не-СКД корневые XML (например, spreadsheet `` — для них есть `/mxl-decompile`). +- **Покрытые конструкции** эмитятся в JSON напрямую (поля, параметры с `@autoDates`, шаблоны с rows-стилями, варианты с structure/selection/filter/order/conditionalAppearance и т.п.). +- **Непокрытые, но не критичные** (например, `orderExpression` на полях, `ChoiceParameterLinks` на параметрах, custom per-cell appearance, scope в conditionalAppearance) — заменяются на sentinel `{"__unsupported__": {"id": "W###", "kind": "...", "loc": "..."}}`. JSON остаётся валидным, но **`skd-compile` отказывается компилировать его до тех пор, пока sentinel не убраны** — это намеренно, чтобы непокрытое не уехало в финальный отчёт незамеченным. +- **Критичные конструкции** (Picture cells, ХранилищеЗначения, вариативные шаблоны, не-СКД root) — fail-fast: скрипт завершается с ненулевым кодом и пишет в stderr какой именно элемент не поддержан. -При обнаружении — скрипт пишет в stderr понятное сообщение и завершается с ненулевым кодом. +Все непокрытые места — с координатами в `.warnings.md`. -## Верификация +## Workflow -``` -/skd-compile -DefinitionFile -OutputPath — обратная компиляция -/skd-validate — валидация результата -/skd-info — визуальный осмотр -``` +1. `/skd-decompile -OutputPath draft.json` — получить черновик. +2. Открыть `draft.warnings.md`, посмотреть, что не покрылось. +3. Поправить JSON под задачу. Sentinel-объекты — заменить на ручную реализацию (через явный raw `template`, через ручное описание appearance и т.п.) либо удалить, если конструкция в новом отчёте не нужна. +4. `/skd-compile -DefinitionFile draft.json -OutputPath new-Template.xml` — собрать обратно. +5. `/skd-validate` + `/skd-info` — проверить.