Dcs Edit

---
name: dcs-edit
description: Точечное редактирование схемы компоновки данных 1С (СКД). Используй когда нужно модифицировать существующую СКД — добавить поля, итоги, фильтры, параметры, изменить текст запроса
allowed-tools:
  - Bash
  - Read
  - Write
  - Glob
---

# /dcs-edit — точечное редактирование СКД (Template.xml)

## MCP routing

- Preferred path: use MCP `unica` tool `unica.apply` с операциями СКД; адрес
  цели — логический, файлового селектора у поверхности нет.
- Не зови внутренние адаптеры напрямую: они спрятаны за MCP `unica`.
- Сначала вызови `unica.apply` с `at` и `ops`: это план без записи.
  Когда пользователь поручил внести эту правку, вызови `unica.apply` только
  с `executionToken` из `data.executionToken` успешного плана.
- Словарь операций узла даёт `unica.view {at}` в секции `can`: что не названо
  там, того поверхность не пишет.

Атомарные правки существующей схемы компоновки данных: поля, итоги, фильтры,
параметры, настройки варианта, структура, текст запроса.

## Адрес и операции

Цель — узел макета-схемы: `<набор>:<Вид>.<Имя>.Template.<Макет>`. Набор данных
и вариант, когда их несколько, называются продолжением адреса.

Двадцать операций словаря: `field.add`, `field.set`, `field.remove`,
`fieldRole.set`, `calculatedField.add`, `total.add`, `parameter.add`,
`parameter.set`, `parameter.remove`, `filter.add`, `filter.clear`,
`selection.add`, `selection.clear`, `order.clear`,
`conditionalAppearance.clear`, `query.set`, `query.patch`, `variant.add`,
`structure.set`, `structure.patch`.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.apply",
    "arguments": {
      "at": "main:Report.Продажи.Template.ОсновнаяСхема",
      "ops": [
        {"op": "field.add", "args": {"items": [{"dataPath": "Номенклатура", "title": "Товар"}]}}
      ]
    }
  }
}
```

Несколько правок идут одним `ops`: план собирается целиком и применяется
атомарно — отказ любой операции отменяет весь вызов.

Применение — вызов только с `executionToken` из `data.executionToken` успешного плана:

Сначала получи план этого изменения:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.apply",
    "arguments": {
      "at": "main:Report.Продажи.Template.ОсновнаяСхема",
      "ops": [
        {
          "op": "field.add",
          "args": {
            "items": [
              {
                "dataPath": "Номенклатура",
                "title": "Товар"
              }
            ]
          }
        }
      ]
    }
  }
}
```

Для исполнения передай `data.executionToken` из этого успешного плана:

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.apply",
    "arguments": {
      "executionToken": "<data.executionToken из успешного плана>"
    }
  }
}
```

Изменившаяся схема отвечает `stale_revision` и называет обе ревизии: перечитай
превью и повтори.

## Чего словарь не пишет

Поверхность правит существующую схему двадцатью операциями выше. Остальное из
прежнего DSL канонической операции **не имеет**:

- наборы данных и их связи (`add-dataSet`, `add-dataSetLink`);
- параметры данных варианта (`add-dataParameter`, `modify-dataParameter`);
- добавление сортировки (`add-order` — есть только `order.clear`);
- добавление условного оформления (`add-conditionalAppearance` — есть только
  `conditionalAppearance.clear`);
- расшифровку ресурсов (`add-drilldown`);
- параметры вывода (`set-outputParameter`);
- переименование и перестановку параметров (`rename-parameter`,
  `reorder-parameters`);
- удаление итога, вычисляемого поля и отдельного фильтра (`remove-total`,
  `remove-calculated-field`, `remove-filter`).

Если задача требует одного из них — сообщи это как пробел контракта Unica MCP
и не подменяй его соседней операцией: `filter.clear` вместо удаления одного
фильтра сотрёт все.

## Операции

Заголовки ниже названы операциями словаря там, где операция есть; прежние имена
DSL, у которых канонической операции нет, помечены прямо в заголовке — их
значения остаются описанием формата, а не вызовом. Само значение (`values`,
`items`) в разделах описано в том же shorthand, что принимает операция.


### `field.add` — добавить поле в набор данных

Shorthand: `"Имя [Заголовок]: тип @роль #ограничение"`.

```
"Цена: decimal(15,2)"
"Организация [Орг-ция]: CatalogRef.Организации @dimension"
"Служебное: string #noFilter #noOrder"
```

Поле добавляется в набор и в selection варианта (если нет `-NoSelection`). Дубликат dataPath — предупреждение, пропуск.

### `total.add` — добавить итог

```
"Цена: Среднее"
"Стоимость: Сумма(Кол * Цена)"
```

### `calculatedField.add` — добавить вычисляемое поле

Shorthand: `"Имя [Заголовок]: тип = Выражение #noFilter #noOrder #noGroup"`.

```
"Маржа = Продажа - Закупка"
"Наценка [Наценка, %]: decimal(10,2) = Маржа / Закупка * 100"
"Служебное: string = \"\" #noFilter #noOrder #noGroup"
```

`#noFilter`, `#noOrder`, `#noGroup`, `#noField` → `<useRestriction>` (аналогично `field.add`).

Также добавляется в selection варианта.

### `parameter.add` — добавить параметр

```
"Период [Отчетный период]: StandardPeriod = LastMonth @autoDates"
"Организация: CatalogRef.Организации"
```

Shorthand: `"Имя [Заголовок]: тип = значение [availableValue=список] [@флаги]"`. `[Заголовок]` опциональный — добавляет `<title>`.

Флаги:
- `@autoDates` генерирует пару скрытых параметров `ДатаНачала`/`ДатаОкончания` для StandardPeriod-параметра — для БСП-отчётов, чтобы получить пару полей «Начало/Конец» в панели быстрых настроек.
- `@hidden` скрывает параметр от пользовательских настроек, например для параметров-констант в запросе.
- `@always` всегда подставляет параметр в запрос. Часто используется вместе с `@hidden`, но подходит и для видимых обязательных параметров.
- `@valueList` разрешает передавать список значений. При значении-списке флаг подразумевается автоматически.

Значение-список задаётся несколькими значениями через запятую; если запятая входит в само значение, оборачивай его в одинарные кавычки.

```
"Виды [Виды субконто]: ChartOfCharacteristicTypesRef.ВидыСубконтоХозрасчетные = ПланВидовХарактеристик.ВидыСубконтоХозрасчетные.Контрагенты, ПланВидовХарактеристик.ВидыСубконтоХозрасчетные.Договоры"
"ПС: CatalogRef.Контрагенты = Справочник.Контрагенты.ПустаяСсылка @hidden"
"Период: StandardPeriod = LastMonth @always"
"ПСчет: ChartOfAccountsRef.Хозрасчетный = ПланСчетов.Хозрасчетный.X @hidden @always"
"Округление: EnumRef.Округления = Окр1 availableValue=Перечисление.Округления.Окр1: руб., Перечисление.Округления.Окр1000: тыс."
```

`availableValue=` задаёт начальный список допустимых значений. Формат списка: `v1[: p1], v2[: p2], ...`; представление после `:` опционально. Если в значении или представлении встречается `,` или `:`, оборачивай элемент в одинарные кавычки:

```
"Округление: EnumRef.Округления = Окр1 availableValue=Окр1_00: 'руб., коп.', Окр1: руб."
```

### `parameter.set` — изменить существующий параметр

Shorthand: `"ИмяПараметра [Заголовок] [ключ=значение]... [@флаги]"`. Находит параметр по имени, обновляет указанные свойства.

```
"ПорядокОкругления use=Always"
"ПорядокОкругления [Округление сумм] denyIncompleteValues=true"
"ПериодОтчета [Отчетный период]"                                  # только title
"ПорядокОкругления availableValue=Перечисление.Округления.Окр1: руб., Перечисление.Округления.Окр1000: тыс."
"СчетПС value=ПланСчетов.Хозрасчетный.КассаПредприятия"
"Виды value=ПланВидовХарактеристик.ВидыСубконтоХозрасчетные.Контрагенты, ПланВидовХарактеристик.ВидыСубконтоХозрасчетные.Договоры"
"Контрагент @hidden @always"
```

`[Заголовок]` опциональный — устанавливает или заменяет `<title>`. Можно вызывать без других kv-пар, чтобы только обновить title.

`availableValue=` заменяет весь список допустимых значений; старые элементы удаляются. Формат и кавычки такие же, как в `parameter.add`.

`value=` заменяет значение параметра. Несколько значений через запятую дают список значений и заменяют все прежние значения; для запятой внутри значения используй одинарные кавычки.

Флаги `@hidden` и `@always` работают так же, как в `parameter.add`, и идемпотентны.

### rename-parameter — переименовать параметр — канонической операции нет

Shorthand: `"OldName => NewName"`. Атомарно обновляет имя параметра, ссылки `&Имя` в выражениях других параметров (только полные совпадения, `&ПериодX` не задевается), и записи в `dataParameters` всех вариантов. Текст запроса не трогает — переименование строго в области параметров.

```
"Период => ПериодОтчета"
```

### reorder-parameters — переставить параметры в указанном порядке — канонической операции нет

Shorthand: `"Имя1, Имя2, Имя3"`. Частичный список — указанные параметры идут первыми в заданном порядке, остальные сохраняют исходный порядок и идут в конце. Параметры из списка, которых нет в схеме — warning, пропуск.

```
"ПериодОтчета, НачалоПериода, КонецПериода"
```

### `filter.add` — добавить фильтр в вариант

Shorthand: `"Поле оператор значение @флаги"`. Флаги: `@off` (use=false), `@user` (userSettingID=auto), `@quickAccess`, `@normal`, `@inaccessible`.

```
"Номенклатура = _ @off @user"
"Дата >= 2024-01-01T00:00:00"
"Статус filled"
```

### add-dataParameter — добавить параметр данных в вариант — канонической операции нет

Shorthand: `"Имя [= значение] @флаги"`.

```
"Период = LastMonth @user"
"Организация @off @user"
```

### add-order — добавить сортировку — канонической операции нет

Shorthand: `"Поле [desc]"`. По умолчанию asc. `Auto` — авто-элемент.

```
"Количество desc"
"Auto"
```

### `selection.add` — добавить элемент выборки

```
"Номенклатура"
"Auto"
"Folder(Поступление: ПолеА, ПолеБ, ПолеВ)"
```

`Folder(Название: поле1, поле2)` — группа полей (SelectedItemFolder) с заголовком и `placement=Auto`.

`@group=ИмяГруппировки` — добавить в selection именованной группировки (вместо уровня варианта):

```
"Folder(Поступление: ПолеА, ПолеБ) @group=ДанныеОтчета"
```

### add-dataSetLink — добавить связь наборов данных — канонической операции нет

Shorthand: `"Источник > Приёмник on ВырИсточника = ВырПриёмника [param Имя]"`.

```
"Набор1 > Набор2 on Поле1 = Поле2"
"Набор1 > Набор2 on Поле1 = Поле2 [param Связь]"
```

### add-dataSet — добавить набор данных — канонической операции нет

Shorthand: `"Имя: ТЕКСТ_ЗАПРОСА"` или `"ТЕКСТ_ЗАПРОСА"` (авто-имя `НаборДанныхN`).

```
"Доп: ВЫБРАТЬ 1 КАК Тест"
"ВЫБРАТЬ Ссылка ИЗ Справочник.Номенклатура"
"Продажи: @queries/sales.sql"
```

`dataSource` берётся из первого существующего. Дубликат имени — предупреждение, пропуск. Не поддерживает пакетный режим (запрос может содержать `;;`).

### `variant.add` — добавить вариант настроек

Shorthand: `"Имя [Представление]"`. Представление опционально, по умолчанию = имя.

```
"Детальный"
"Детальный [Детальный отчёт]"
```

Создаёт вариант с Auto selection + detail group. Дубликат имени — предупреждение, пропуск.

### add-conditionalAppearance — добавить условное оформление — канонической операции нет

Shorthand: `"Параметр = значение [when условие] [for Поле1, Поле2]"`. Блок `when` — синтаксис `filter.add` (Поле оператор значение).

```
"ЦветТекста = web:Red when Сумма < 0"
"ЦветФона = web:LightGreen when Статус = Одобрен for Статус"
"МинимальнаяШирина = 50 for Организация"
"Формат = ЧДЦ=2 for Цена, Сумма"
```

Типы значений appearance (автодетект): `web:*`/`style:*`/`win:*` → Color, `true`/`false` → Boolean, параметр `Формат`/`Текст`/`Заголовок` → LocalStringType, иначе String.

Типы значений фильтра (автодетект): `Перечисление.*`/`Справочник.*`/`ПланСчетов.*`/`Документ.*` → DesignTimeValue, `true`/`false` → Boolean, дата → DateTime, числа → Decimal, иначе String.

OrGroup: несколько условий через ` or ` в `when` объединяются в FilterItemGroup/OrGroup:

```
"Формат = ЧЦ=15; ЧДЦ=0 when ПараметрыДанных.Округление = Перечисление.Округления.Окр1 or ПараметрыДанных.Округление = Перечисление.Округления.Окр1000"
```

**Важно**: для параметров данных используйте префикс `ПараметрыДанных.` в поле фильтра.

### add-drilldown — подключить расшифровку к ресурсам в шаблонах — канонической операции нет

Value — имена ресурсов (как в полях/вычисляемых полях СКД) через запятую.

```
"ПоступлениеИзПроизводства, ВыбытиеПрочее"
"Сумма_Дт83, Сумма_Дт99, Сумма_68, Сумма_84"
```

Подключает DrillDown по `ИмяРесурса` ко всем шаблонам, содержащим указанные ресурсы. Идемпотентно.

### `query.set` — заменить текст запроса

Не поддерживает пакетный режим. Value — полный текст запроса или `@path/to/file.sql` (ссылка на внешний файл). Путь разрешается относительно Template.xml, затем CWD.

Когда что: существенная переработка запроса (добавить поля, соединения, переписать пакет) -> получи запрос через `unica.view` on the schema node и возьми `data.dataSets[].query`; отредактируй текст и передай его в `query.set` как значение. `query` отдаёт сырой текст запроса целиком, с отступами строк продолжения `|`, поэтому передача точна, включая многопакетные запросы. Точечная замена идентификатора или подстроки не требует выгрузки: используй `query.patch`.

### `query.patch` — точечная замена в тексте запроса

Shorthand: `"старое => новое [@once]"`. По умолчанию заменяет все вхождения подстроки. Поддерживает пакетный режим и `DataSet`.

```
"СубконтоДт1) В => СубконтоКт1) В"
"ЛЕВОЕ СОЕДИНЕНИЕ => ВНУТРЕННЕЕ СОЕДИНЕНИЕ"
"КАК ВТ_СтароеИмя => КАК ВТ_НовоеИмя @once"
```

`@once` падает с ошибкой, если найдено не ровно одно вхождение. Используй его для опасных переименований, чтобы не заменить однотипные идентификаторы или комментарии.

### set-outputParameter — установить параметр вывода — канонической операции нет

```
"Заголовок = Мой отчёт"
"ВыводитьЗаголовок = true"
```

Если параметр уже существует — заменяет значение.

### `structure.set` — установить структуру варианта

Shorthand: `"Поле1 > Поле2 > details"`. `details`/`детали` — детальные записи. Заменяет всю структуру. Не поддерживает пакетный режим.

```
"Организация > Номенклатура > details"
"details"
"СчетМеждународногоУчета @name=ДанныеОтчета"
```

`@name=Имя` — присваивает имя группировке (`<dcsset:name>`). Используется для привязки шаблонов через `groupName`.

### `field.set` — изменить существующее поле

Тот же shorthand что и `field.add`. Находит по dataPath, объединяет свойства (непустые переопределяют), сохраняет позицию.

```
"Цена [Цена USD]: decimal(10,4) @dimension"
```

### modify-filter — изменить существующий фильтр — канонической операции нет

Тот же shorthand что и `filter.add`. Находит по полю, обновляет оператор/значение/флаги. См. правило для `<use>` ниже.

### modify-dataParameter — изменить параметр данных — канонической операции нет

Тот же shorthand что и `add-dataParameter`. Находит по имени, обновляет значение/флаги. См. правило для `<use>` ниже.

#### Правило `<use>` для modify-filter / modify-dataParameter

В отличие от `add-*`, в `modify-*` поле `<use>` обновляется **только если флаг задан явно**:
- `@off` — установить `<use>false</use>`
- `@on` — убрать существующий `<use>false</use>` (включить параметр)
- ни `@off`, ни `@on` не задано — `<use>` не трогается, существующее значение сохраняется (важно: это значит, что отключённый параметр останется отключённым после модификации других свойств)

### remove-* и clear-*

| Операция | Value | Действие |
|----------|-------|----------|
| `field.remove` | dataPath | Удаляет поле из набора + из selection варианта |
| remove-total | dataPath | Удаляет итог — **канонической операции нет** |
| remove-calculated-field | dataPath | Удаляет вычисляемое поле — **канонической операции нет** |
| `parameter.remove` | name | Удаляет параметр |
| remove-filter | поле | Удаляет один фильтр — **канонической операции нет**; `filter.clear` стирает все |
| `selection.clear` | `*` | Очищает все элементы selection |
| `order.clear` | `*` | Очищает все элементы order |
| `filter.clear` | `*` | Очищает все элементы filter |

## Верификация

### Валидация структуры после редактирования

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.check",
    "arguments": {
      "at": "<sourceSet>:<Kind>.<Name>.Template.<Template>"
    }
  }
}
```

### Сводка схемы

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.view",
    "arguments": {
      "cwd": "<workspace>",
      "at": "<набор>:Report.<Отчёт>.Template.<Макет>"
    }
  }
}
```