@seafteam/seaf-archtool-core-plugin-suite 2026.31.0 → 2026.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -66,6 +66,55 @@ tags:
66
66
  - name: HealthInfo
67
67
  description: "API для получения расширенной служебной информации о состоянии портала. ⚠️ Данный метод доступен только при работе SEAF.ArchTool в кластерном режиме."
68
68
  paths:
69
+ /seaf-core/api/core/storage/jsonata/{query}:
70
+ get:
71
+ tags:
72
+ - DataLake
73
+ summary: Выполняет произвольный запрос JSONata к данным архитектуры
74
+ description: >
75
+ Устаревший GET-контракт (до ERA-2872). Сохранён для обратной совместимости.
76
+ Предпочтительный способ — POST /seaf-core/api/core/storage/jsonata.
77
+ parameters:
78
+ - in: path
79
+ name: query
80
+ description: JSONata запрос в скобках "([запрос])" или идентификатор DataSet без скобок
81
+ required: true
82
+ schema:
83
+ $ref: '#/components/schemas/JSONataQuery'
84
+ example: >
85
+ ({"id": $params.id, "limit": $params.limit, "type": $self.type, "template": $self.template})
86
+ - in: query
87
+ name: params
88
+ description: >
89
+ JSON структура с параметрами передающаяся в запрос.
90
+ Будет доступна в переменной $params.
91
+ required: false
92
+ schema:
93
+ type: string
94
+ example: '{"id":"sber.rdwsoft","limit":8}'
95
+ - in: query
96
+ name: subject
97
+ description: >
98
+ JSON структура с профилем объекта, который выполняет запрос.
99
+ Будет доступна в переменной $self.
100
+ required: false
101
+ schema:
102
+ type: string
103
+ example: '{"type":"markdown","template":"template.md"}'
104
+ - in: query
105
+ name: envelope
106
+ description: Если "true", ответ упаковывается в envelope-формат
107
+ required: false
108
+ schema:
109
+ type: string
110
+ enum: ["true", "false"]
111
+ responses:
112
+ "200":
113
+ description: "Результат выполнения запроса"
114
+ content:
115
+ application/json:
116
+ schema:
117
+ $ref: '#/components/schemas/JSONataResult'
69
118
  /seaf-core/api/core/storage/jsonata:
70
119
  post:
71
120
  tags:
@@ -26,6 +26,37 @@
26
26
  - false
27
27
  - Прочие приводимые значения
28
28
 
29
+ # Markdown в текстовых ячейках
30
+
31
+ Текстовую колонку можно показывать как Markdown, не меняя сохраняемое значение.
32
+ Возможность включается только для заголовка с `type: text`:
33
+
34
+ ```yaml
35
+ headers:
36
+ - value: evidence
37
+ text: Обоснование
38
+ type: text
39
+ render: markdown
40
+ editable: true
41
+ ```
42
+
43
+ Без `render: markdown` Markdown-синтаксис отображается как обычный текст. Поддерживаются
44
+ обычное форматирование и ссылки, таблицы, изображения, а также fenced-блоки `mermaid`
45
+ и `plantuml`. Произвольный HTML не исполняется.
46
+
47
+ Markdown хранится в ячейке как обычная строка и сохраняется тем же способом, что и
48
+ обычный `text`; проверенный save payload сохраняет и соседнее поле строки. Относительные пути изображений вычисляются от файла презентации
49
+ editable-table; они не зависят от `save.path` конкретной колонки. Mermaid строится в
50
+ браузере, а PlantUML требует настроенный сервер или обработчик IDEA-плагина.
51
+
52
+ Режим исходного текста открывается кнопкой редактирования, двойным кликом, `Enter` или
53
+ `F2` на выбранной ячейке. `Escape`, `Ctrl/Cmd+Enter` или переход фокуса завершают
54
+ редактирование и возвращают предпросмотр.
55
+
56
+ SVG, в которых подписи находятся внутри `foreignObject` (например, экспортированные из
57
+ draw.io или Excalidraw), браузер может показать без текста: такие изображения выводятся
58
+ в `<img>`.
59
+
29
60
  # link
30
61
 
31
62
  ## Описание
@@ -161,6 +192,8 @@ headers:
161
192
  # type - Тип вывода ячеек для указанной колонки
162
193
  # Дефолтное значение: text
163
194
  # Допустимые значения: text / select / multiple-select / checkbox / link / fn
195
+ # render - дополнительный режим отображения текстовой ячейки
196
+ # Допустимое значение: markdown (только вместе с type: text)
164
197
 
165
198
  - value: name
166
199
  text: Имя
@@ -1,5 +1,5 @@
1
1
  docs:
2
2
  archtool.plugins.gigachat.agents.aigena.menu:
3
- location: SEAF.ArchTool/Руководство/Документы/GigaChat/2. Агенты/3. AiGenA
3
+ location: SEAF.ArchTool/Руководство/Документы/GigaChat/2. Агенты/2. AiGenA
4
4
  type: markdown
5
5
  source: template.md
@@ -1,5 +1,4 @@
1
1
  imports:
2
2
  - menu.yaml
3
3
  - simple/root.yaml
4
- - react/root.yaml
5
4
  - aigena/root.yaml
@@ -51,11 +51,6 @@ archtool.plugins.gigachat.example:
51
51
  Взаимодействует c API GigaChat.
52
52
  Позволяет описать промпт и добавить в него результат выполнения JSONata-выражения в качестве контекста.
53
53
 
54
- ## [`react`](/entities/docs/blank?dh-doc-id=archtool.plugins.gigachat.agents.react.menu)
55
-
56
- Взаимодействует c API GigaChat.
57
- Позволяет использовать тулы (function-calling инструменты) для предоставления ответа.
58
-
59
54
  ## [`aigena`](/entities/docs/blank?dh-doc-id=archtool.plugins.gigachat.agents.aigena.menu)
60
55
 
61
56
  Взаимодействует с API AiGenA.
@@ -23,7 +23,7 @@ archtool.plugins.gigachat.example:
23
23
  # описание агента, с ними мы познакомимся позже
24
24
  scenarios_id_2:
25
25
  title: Сценарий 2
26
- type: react
26
+ type: gigachat
27
27
  # ...
28
28
  ```
29
29
 
@@ -1,78 +1,5 @@
1
1
  flix.office.hq_page: []
2
2
  flix.dc.01_page:
3
- - id: flix.network.dc.ngfw.cntxt2
4
- diff:
5
- geometry_attr_key:
6
- x:
7
- new: "275"
8
- old: "130"
9
- y:
10
- new: "170"
11
- old: "90"
12
- - id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.01_flix.lan.dc.dmz.vpn
13
- diff:
14
- geometry_attr_key:
15
- pointsArray:
16
- - - "820"
17
- - "450"
18
- - - "820"
19
- - "1110"
20
- - id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.02_flix.lan.dc.dmz.prod
21
- diff:
22
- geometry_attr_key:
23
- pointsArray:
24
- - - "790"
25
- - "380"
26
- - - "790"
27
- - "810"
28
- - id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.02_flix.lan.dc.dmz.vpn
29
- diff:
30
- geometry_attr_key:
31
- pointsArray:
32
- - - "810"
33
- - "380"
34
- - - "810"
35
- - "1110"
36
- - id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.03_flix.lan.dc.dmz.vpn
37
- diff:
38
- geometry_attr_key:
39
- pointsArray:
40
- - - "755"
41
- - "1120"
42
- - id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.04_flix.lan.dc.dmz.prod
43
- diff:
44
- geometry_attr_key:
45
- pointsArray:
46
- - - "880"
47
- - "820"
48
- - - "880"
49
- - "820"
50
- - id: link_id:Sber Cloud DC:generic:flix.network.dc.fw.04_flix.lan.dc.dmz.vpn
51
- diff:
52
- geometry_attr_key:
53
- pointsArray:
54
- - - "755"
55
- - "850"
56
- - - "850"
57
- - "850"
58
- - id: link_id:Sber Cloud
59
- DC:generic:flix.network.dc.ngfw.cntxt1_flix.lan.dc.dmz.prod
60
- diff:
61
- geometry_attr_key:
62
- pointsArray:
63
- - - "985"
64
- - "670"
65
- - - "935"
66
- - "670"
67
- - id: link_id:Sber Cloud
68
- DC:generic:flix.network.dc.ngfw.cntxt2_flix.lan.dc.int.prod
69
- diff:
70
- geometry_attr_key:
71
- pointsArray:
72
- - - "1630"
73
- - "257"
74
- - - "1630"
75
- - "257"
76
3
  - id: link_id:Sber Cloud DC:generic:flix.kb.fpsu_1_flix.lan.dc.dmz.vpn
77
4
  diff:
78
5
  geometry_attr_key:
@@ -83,35 +10,12 @@ flix.dc.01_page:
83
10
  - "420"
84
11
  - - "830"
85
12
  - "1100"
86
- - id: link_id:Sber Cloud DC:generic:flix.kb.4_flix.lan.dc.int.prod
87
- diff:
88
- label:
89
- new: s
90
- old: FW
91
- geometry_attr_key:
92
- pointsArray:
93
- - - "1235"
94
- - "960"
95
- - - "1510"
96
- - "960"
97
- - - "1510"
98
- - "230"
99
- - - "1580"
100
- - "230"
101
13
  - id: link_id:Sber Cloud DC:generic:flix.kb.5_flix.lan.dc.int.security
102
14
  diff:
103
15
  geometry_attr_key:
104
16
  pointsArray:
105
17
  - - "1795"
106
18
  - "510"
107
- - id: link_id:Sber Cloud DC:generic:flix.cluster.vdi_flix.lan.dc.dmz.vdi
108
- diff:
109
- geometry_attr_key:
110
- pointsArray:
111
- - - "1040"
112
- - "1204"
113
- - - "1040"
114
- - "510"
115
19
  - id: link_id:Sber Cloud
116
20
  DC:generic:flix.backup.cyberbackup_flix.lan.dc.int.it.services
117
21
  diff:
@@ -25,18 +25,89 @@
25
25
  - **dataset** Обязательный, содержит описание объектов архитектуры.
26
26
  - **templates** Необязательный, содержит пользовательские шаблоны для объектов или переопределения встроенных шаблонов.
27
27
  - **diff** Необязательный, содержит трансформации для отображаемой диаграммы.
28
+ - **diff_path** Необязательный, содержит путь к файлу `.yaml` или `.json` с трансформациями. При наличии имеет приоритет над `diff`.
28
29
  - **layout_settings** Необязательный, содержит настройки алгоритмов компоновки и отрисовки связей. Может задаваться на уровне YAML-профиля документа или возвращаться из `source`; настройки из `source` переопределяют одноимённые поля профиля.
29
30
 
30
31
  Параметры iframe Draw.io для seaf2drawio настраиваются так же, как у документа `drawio`:
31
32
  переменные `VUE_APP_DOCHUB_PLUGIN_DRAWIO_SERVER_URI` / `VUE_APP_DOCHUB_PLUGIN_DRAWIO_URL_PARAMS`
32
33
  и поле профиля `drawio_url_params` (см. [документацию drawio](/docs/archtool.plugins.drawio)).
33
34
 
35
+ ### Автоматическая компоновка технической архитектуры
36
+
37
+ На общей и детальных схемах `Internet` и `Транспортная сеть` отображаются как самостоятельные контейнеры. Провайдеры и явно отнесённые к ним объекты остаются внутри соответствующего контейнера. На страницах офиса и ЦОД внутренние зоны располагаются слева направо: `INET-EDGE` (под ним `EXT-WAN-EDGE`), `DMZ` (под ним `INT-WAN-EDGE`), `INT-NET`, затем `INT-SECURITY-NET`.
38
+
39
+ Размеры зон и групп рассчитываются по фактическому содержимому. При добавлении сетей, устройств или сервисов контейнеры расширяются, а соседние зоны сдвигаются с безопасным интервалом. Поэтому итоговый размер и координаты схемы могут отличаться от исходного шаблона: генератор отдаёт приоритет отсутствию наложений и читаемости подписей. Сохранённые пользователем geometry diff имеют приоритет над автоматическим stacking; для остальных объектов применяется адаптивная компоновка.
40
+
41
+ На детальных страницах сервисы и пользовательские устройства без явно заданного `segment`, чьи `network_connection` относятся только к `INTERNET` или `TRANSPORT-WAN`, выводятся слева от `Internet` в визуальном контейнере **«Внешние сервисы»**. Внутренние группы при этом сохраняют штатные слои сервисов КБ и технических сервисов. Это только визуальная компоновка: связи и принадлежность объектов в архитектурной модели не изменяются. Явно заданный `segment`, смешанные внутренние и внешние подключения либо неразрешённая ссылка имеют приоритет и не переносятся в этот контейнер автоматически.
42
+
43
+ Компоненты сети с `is_part_of` отображаются в составе единого `network_service`; для размещения такого агрегата требуется разрешимый `segment` самого сервиса, его участников или связанной через `network_connection` сети.
44
+
45
+ ### Перестроение схемы с ИИ (бета)
46
+
47
+ Для документа можно явно включить экспериментальный диалог перестроения схемы по текстовому запросу. По умолчанию функция выключена. При включении пользователь видит кнопку **Перестроить с ИИ** и предупреждение о передаче запроса и выбранного контекста в настроенный в ArchTool GigaChat через общий `chatService`.
48
+
49
+ ```yaml
50
+ docs:
51
+ something.seaf2drawio_ai_r41:
52
+ type: seaf2drawio
53
+ ai_assistant:
54
+ enabled: true
55
+ max_attempts: 3
56
+ context_mode: compact
57
+ response_mode: selection
58
+ scenario:
59
+ type: gigachat
60
+ temperature: 0.1
61
+ ```
62
+
63
+ Параметры `ai_assistant`:
64
+
65
+ - **enabled** включает функцию только для данного документа. При отсутствии `enabled: true` интерфейс и генерация схемы работают как раньше; флаг берётся из профиля документа.
66
+ - **max_attempts** задаёт ограничение числа обращений к LLM, включая первичную попытку. Продуктовый предел — три попытки.
67
+ - **context_mode: compact** передаёт модели ограниченный срез исходного датасета, выбранный по запросу, вместо полного содержимого хранилища.
68
+ - **response_mode: selection** требует от модели только существующие OID, после чего связный датасет детерминированно собирается из исходных объектов.
69
+ - **scenario** задаёт сценарий LLM через общий `chatService` ArchTool; `system_prompt` внутри сценария позволяет заменить системную инструкцию, а `history: false` отключает сохранение истории сессии.
70
+
71
+ Параметры, возвращённые `source`, дополняют настройки профиля документа; флаг `enabled` принимается только из профиля.
72
+
73
+ Если `context_mode` и `response_mode` не заданы, используются безопасные значения `compact` и `selection`. Другие значения не подменяются значениями по умолчанию: диалог показывает ошибку конфигурации и не отправляет запрос в LLM. В `compact` передаётся ограниченный срез датасета; в `selection` модель возвращает только существующие OID, а итоговый датасет собирается Core. Для одного запроса действует предел 200 объектов вместе с зависимостями.
74
+
75
+ Перед отправкой запроса диалог сообщает пользователю, что текст запроса и отобранный контекст архитектурных данных передаются в настроенный GigaChat через общий `chatService`. В запрос нельзя включать секреты, персональные или иные данные, не разрешённые к обработке выбранным сервисом.
76
+
77
+ Ответ модели проходит синтаксическую, структурную, ссылочную и Draw.io-проверку. При ошибке модель получает ограниченную диагностику и может исправить ответ в пределах `max_attempts`. Успешный результат показывается только как предпросмотр. Кнопка **Использовать в этой сессии** не записывает файлы и не изменяет исходный архитектурный датасет. После применения в текущей сессии используется компактный AI-датасет, поэтому экспорт и сохранение заблокированы до успешного обновления исходных данных.
78
+
79
+ В AI-предпросмотре технологии КБ без специализированного шаблона, например IdM, IdP, PAM, DLP, политики Kubernetes и Registry, рисуются общим значком и могут визуально отличаться от обычной R41-схемы; обычный рендер R41 не меняется.
80
+
81
+ #### Поддерживаемые формулировки
82
+
83
+ Запрос можно писать обычным языком. Распознаются команды `покажи`, `нарисуй`, `отрисуй`, `отобрази`, `выведи`, `визуализируй`, `сформируй` и `оставь`, а также вежливые формы: `можешь показать`, `покажи, пожалуйста`, `давай отобразим`, `хочу увидеть` и `мне нужны`.
84
+
85
+ Нормализатор понимает категории, которые рисуют текущие шаблоны SEAF2DrawIO: регионы и зоны доступности, ЦОД и офисы, сетевые сегменты, сети, сетевые и пользовательские устройства, вычислительные сервисы, кластеры виртуализации, Kubernetes, резервное копирование, мониторинг, средства КБ и logical links. Для часто используемых категорий поддерживаются варианты `monitoring`/`мониторинг`/`маниторинг`, `Kubernetes`/`K8s`/`кубернетес`, `КБ`/`УКБ`/`ЭКБ`/`ИБ`/`кибербезопасность`, `backup`/`бекап`/`бэкап`/`резервное копирование`. Конкретный объект можно указать точным `title` или OID, например `ELK`, `Zabbix` или `jupiter.monitoring.elk`.
86
+
87
+ Примеры:
88
+
89
+ | Запрос | Результат |
90
+ |---|---|
91
+ | `Покажи мониторинг` | Все существующие сервисы мониторинга и зависимости их размещения |
92
+ | `Нарисуй ELK и Zabbix` | Только названные сервисы и существующие связи между ними |
93
+ | `Покажи мониторинг и все связи` | Все сервисы мониторинга, все смежные logical links и их конечные объекты |
94
+ | `Покажи исходящие связи ELK` | ELK, его исходящие logical links с учётом `direction` и все конечные объекты этих связей |
95
+ | `Покажи ELK и Zabbix без связей` | Названные сервисы без logical links |
96
+ | `Покажи monitoring, K8s и средства ИБ` | Все объекты трёх категорий и необходимые зависимости размещения |
97
+ | `Покажи внешние подключения` | WAN/INTERNET/INET-EDGE/EXT-WAN-EDGE/TRANSPORT-WAN, подключённые сетевые устройства и сети |
98
+
99
+ Если пользователь перечислил только объекты, Core добавляет существующие logical links между выбранными объектами. Формы `все связи`, `со связями`, `входящие связи` и `исходящие связи` расширяют выборку смежными связями и вторыми концами. Форма `без связей` полностью исключает logical links. Связь с `topology: star` или `topology: chain` сохраняется как единая сущность вместе со всеми её конечными объектами.
100
+
101
+ Однозначно распознанные категории и явно названные объекты добавляются детерминированно в режиме `compact` + `selection`: результат не зависит от того, перечислила ли модель каждый обязательный OID. Служебные объекты, которые сами не рисуются, используются только как зависимости. Каждый новый запрос строится от исходного датасета документа и выполняется в новой AI-сессии; применённый ранее предпросмотр не ограничивает следующую выборку.
102
+
103
+ Нормализатор не является универсальным морфологическим анализатором. Для неизвестного синонима или неоднозначного названия следует использовать термин из списка выше, точный `title` либо OID. Выборка вместе с зависимостями ограничена 200 объектами; при превышении лимита интерфейс попросит сузить запрос.
104
+
34
105
  ### Вычисляемые logical links
35
106
  По умолчанию logical links рисуются напрямую по полям `source`, `target` и `topology`. Чтобы включить поиск сетевого маршрута, нужно одновременно включить режим в документе и пометить конкретную logical link.
36
107
 
37
108
  ``` yaml
38
109
  docs:
39
- seaf.ta.docs.schema_r41:
110
+ something.seaf2drawio_schema_r41:
40
111
  description: Схема Р41 (seaf2drawio, raw TA dataset)
41
112
  type: seaf2drawio
42
113
  source: seaf.company.ds.ta.schema_r41
@@ -115,7 +186,7 @@ datasets:
115
186
  <mxGeometry x="{{x_pos}}" y="{{y_pos}}" width="{{width}}" height="{{height}}" as="geometry" />
116
187
  </mxCell>
117
188
  </object>
118
- schema: seaf.ta.components.network
189
+ schema: seaf.company.ta.components.networks
119
190
  parent_id: segment
120
191
  type: type:Маршрутизатор
121
192
  algo: Y+
@@ -133,7 +204,7 @@ datasets:
133
204
  <mxGeometry x="{{x_pos}}" y="{{y_pos}}" width="{{height}}" height="{{width}}" as="geometry" />
134
205
  </mxCell>
135
206
  </object>
136
- schema: seaf.ta.services.network
207
+ schema: seaf.company.ta.services.networks
137
208
  parent_id: segment
138
209
  type: type:LAN
139
210
  algo: Y+
@@ -145,14 +216,61 @@ datasets:
145
216
  h: 220
146
217
  ```
147
218
  ## Трансформации
148
- Изменения, которые пользователь внёс на построенную диаграмму можно сохранить в виде набора трансформаций. Для этого в правом верхнем углу экрана расположена кнопка Export Transformations сохраняющая внесённые на диаграмму изменения в yaml-формате.
219
+ Изменения, которые пользователь внёс на построенную диаграмму, можно сохранить в виде набора трансформаций. Без `diff_path` кнопка **Export transformations** скачивает YAML. С `diff_path` она называется **Save transformations** и записывает файл проекта.
149
220
 
150
221
  Трансформации предназначены для сохранения визуальных изменений (положение объектов, положение стрелок, и т.п.) и не предназначены для изменений иерархии или архитектурных данных (перенос сервисов в другие подсети, изменения описаний и т.п.).
151
222
 
152
- После сохранения файла трансформаций его следует приложить к архитектурным данным, сформировать датасет и записать в параметр diff документа seaf2drawio.
223
+ Чтобы сохранять трансформации сразу в файл проекта, укажите `diff_path` в результате
224
+ `source`. При открытии документа `seaf2drawio` загрузит файл `.yaml` или `.json`, а кнопка
225
+ `Save transformations` запишет его через механизм хранения ArchTool. Путь задаётся
226
+ относительно YAML документа; разрешены сегменты `..`, в том числе для перехода в другую
227
+ папку проекта. В Portal лишние `..` нормализуются к корню репозитория. В IDE путь
228
+ нормализуется к каталогу корневого манифеста; если он расположен не в корне репозитория,
229
+ получившийся путь может отличаться от Portal.
153
230
 
154
- Пример объявления документа:
155
- ``` yaml
231
+ Поддерживаются файлы `.yaml` и `.json`. В Portal сохранение доступно только для
232
+ репозитория, подключённого к манифесту, и каждое успешное сохранение создаёт коммит через
233
+ механизм хранения ArchTool. Перед записью файл перечитывается: трансформации элементов,
234
+ которых нет на текущей схеме, сохраняются из свежего содержимого файла. Для элементов
235
+ текущей схемы побеждает последнее сохранение. Между чтением и записью остаётся окно для
236
+ конкурентного изменения; в IntelliJ запись `pushFile` выполняется с задержкой, поэтому
237
+ быстрое повторное сохранение может прочитать прежнее содержимое. Если файл не удалось
238
+ прочитать, схема откроется без его трансформаций, но сохранение останется заблокированным
239
+ до обновления документа.
240
+
241
+ Трансформации отсутствующих элементов не удаляются автоматически и могут сохраняться в
242
+ файле бессрочно. Если элемент удалён из архитектуры окончательно, удалите его запись из
243
+ файла трансформаций вручную; иначе она будет переноситься при последующих сохранениях.
244
+ Пример `examples/diff.yaml` содержит только записи, которые соответствуют текущей
245
+ схеме.
246
+
247
+ Если `diff_path` не задан, кнопка продолжит скачивать `diff*.yaml` в браузере (или
248
+ предложит выбрать файл в IDE-плагине). При отсутствии файла создание возможно только
249
+ когда среда возвращает явный ответ 404; в VS Code и Portal с
250
+ `VUE_APP_SEAF_ENVELOPED_REQUESTS=true` файл
251
+ нужно создать заранее, иначе документ покажет ошибку чтения и заблокирует сохранение.
252
+
253
+ Пример документа с сохранением трансформаций на диск:
254
+
255
+ ```yaml
256
+ docs:
257
+ archtool.plugins.example.seaf2drawio.save_transformations:
258
+ type: seaf2drawio
259
+ location: SEAF.ArchTool/Руководство/Документы/SEAF2Draw.io/Примеры/Трансформации
260
+ origin:
261
+ dataset: archtool.plugins.example.seaf2drawio.data
262
+ source: >
263
+ ({
264
+ "title": "Применение трансформаций",
265
+ "dataset": dataset,
266
+ "diff_path": "./diff.yaml"
267
+ })
268
+ ```
269
+
270
+ Для совместимости трансформации по-прежнему можно передать готовым объектом в
271
+ параметре `diff`. В этом варианте сохранённый файл следует подключить как датасет:
272
+
273
+ ```yaml
156
274
  docs:
157
275
  archtool.plugins.example.seaf2drawio.transformations:
158
276
  type: seaf2drawio
@@ -4,8 +4,7 @@
4
4
  Мы будем стараться сохранять совместимость при его развитии, но следует учитывать эту информацию
5
5
  при принятии решения об его использовании.
6
6
 
7
- **ВНИМАНИЕ:** Плагины в настоящий момент поддерживаются только при развертывании SEAF.ArchTool в режиме портала. В плагинах IDE
8
- данный функционал пока не поддерживается. Но обязательно будет.
7
+ Плагины, включённые в сборку, доступны в портале и в IDE. В IDE они всегда подключаются сразу, без lazy loading.
9
8
 
10
9
  ## Введение
11
10
 
@@ -166,18 +165,64 @@ DocHub.documents.register('html', doc);
166
165
 
167
166
  ## Сборка
168
167
 
169
- Плагин должен собираться в контексте проекта SEAF.ArchTool. Для этого, необходимо в файле ./plugins.json указать ссылку на его проект.
168
+ Плагин собирается в контексте проекта SEAF.ArchTool. В `plugins.json` задаётся массив descriptors:
170
169
 
171
170
  ```json
171
+ [
172
172
  {
173
- "inbuilt": [
174
- "plugins/html"
175
- ]
173
+ "id": "html",
174
+ "documents": ["html"],
175
+ "source": {
176
+ "type": "local",
177
+ "location": "plugins/html"
178
+ }
176
179
  }
180
+ ]
177
181
  ```
178
182
 
179
- Обратите внимание, что путь указывается **к папке** с проектом плагина. Сама папка должна располагаться **внутри** проекта SEAF.ArchTool.
180
- Рекомендуется использовать для этого папку ./plugins.
183
+ ### Поля descriptor
184
+
185
+ | Поле | Обязательное | Описание |
186
+ |---|---|---|
187
+ | `id` | Да | Уникальный ID плагина: строчные латинские буквы, цифры и дефисы; первый символ — буква или цифра (`^[a-z0-9][a-z0-9-]*$`). |
188
+ | `documents` | Да | Непустой массив типов, точно соответствующих `DocHub.documents.register(...)`. Каждый тип имеет одного владельца; повторы внутри массива тоже запрещены. |
189
+ | `source.type` | Да | `local` — каталог внутри core; `package` — установленный npm-пакет. |
190
+ | `source.location` | Да | Для `local` — путь к каталогу с `package.json` относительно корня core. Путь нормализуется; абсолютные пути и выход за корень запрещены. Для `package` — имя установленного пакета, не путь к `.tgz`. |
191
+ | `lazy` | Нет | Boolean override режима загрузки: `true` — lazy, `false` — eager. Без поля наследуется общий env-флаг. В IDE всегда eager. |
192
+
193
+ Entry определяется через `package.json.main`, по умолчанию — `index.js`. Для источника `package` файл `package.json` должен быть доступен через `require.resolve('<имя-пакета>/package.json')`; если пакет использует `exports`, он должен разрешать этот путь.
194
+
195
+ При стандартном каталоге сборки JS-артефакт package-плагина располагается в `dist/plugins/packages/<id>.js`. Для local используется `dist/plugins/<нормализованный location>.js`, например `dist/plugins/plugins/html.js`. Пути JS/CSS lazy-плагинов записываются в `lazy-plugins.json`.
196
+
197
+ ### Миграция со старого формата
198
+
199
+ Объект `{ "inbuilt": ["plugins/html", ...] }` больше не поддерживается и приводит к ошибке сборки. Для каждого пути создайте элемент массива по примеру выше: задайте уникальный `id`, перечислите фактически регистрируемые `documents`, укажите `source.type: "local"` и перенесите путь в `source.location`. Поле `lazy` можно не задавать — сохранится общий режим загрузки.
200
+
201
+ Старое поле `external` и загрузка JS из `manifest.json.plugins` больше не поддерживаются. Внешний плагин нужно установить как package и включить в `plugins.json` перед сборкой. Источник `remote` пока не реализован. Сам PWA-файл `manifest.json` продолжает генерироваться.
202
+
203
+ В IDE package-плагины также включаются в сборку. Legacy-ответ `fetchPlugins` / `pluginList` содержит только пути local-плагинов и не управляет их загрузкой.
204
+
205
+ ### Lazy loading
206
+
207
+ Без lazy loading все включённые в сборку плагины загружаются при запуске ArchTool, даже если пользователь ими не пользуется.
208
+
209
+ Lazy loading позволяет отложить загрузку плагина до первого открытия документа соответствующего типа. Это уменьшает объём ресурсов, необходимых для запуска приложения. При повторном открытии документа уже загруженный плагин используется снова.
210
+
211
+ Текущая реализация меняет только момент загрузки: плагин по-прежнему должен быть указан до сборки ArchTool.
212
+
213
+ `VUE_APP_DOCHUB_PLUGINS_LAZY_LOADING` задаёт режим по умолчанию при сборке: `Y` — lazy, `N` или отсутствие настройки — eager. Необязательное поле `lazy` в descriptor переопределяет этот режим для конкретного плагина:
214
+
215
+ | Поле `lazy` | Поведение |
216
+ |---|---|
217
+ | Отсутствует | Наследует общий env-флаг |
218
+ | `true` | Загружается при открытии документа своего типа, даже при общем `N` |
219
+ | `false` | Подключается через HTML при запуске, даже при общем `Y` |
220
+
221
+ Например, чтобы всегда подключать HTML-плагин сразу, добавьте `"lazy": false` рядом с `id`, `documents` и `source`. Допустимы только boolean-значения, не строки `"Y"`/`"N"` и не `null`.
222
+
223
+ Настройка одинакова для источников `local` и `package` и применяется ко всем типам из `documents` одного плагина. Все плагины включаются в сборку; режим меняет только момент загрузки JS/CSS браузером. В `lazy-plugins.json` попадают только lazy-плагины; если их нет, файл не создаётся и frontend его не запрашивает.
224
+
225
+ В IDE (`VUE_APP_DOCHUB_MODE=plugin`) все плагины остаются eager независимо от env и `lazy` в descriptor. Изменение режима требует пересборки приложения.
181
226
 
182
227
  Теперь можно собрать проект SEAF.ArchTool в нескольких режимах:
183
228