41 lines
5.5 KiB
Markdown
41 lines
5.5 KiB
Markdown
# Пользовательская конфигурация
|
||
|
||
## Контракт автора
|
||
|
||
Шаблон содержит config.schema.json, config.defaults.json и необязательную ui.schema.json. JSON Schema описывает данные, UI Schema — только представление. Собственные параметры harness и plugins располагаются в пространствах имён harness и plugins.<packageId>; схема template объединяет их без конфликтов имён
|
||
|
||
Базовый диалект — JSON Schema Draft 2020-12. MVP renderer поддерживает object, string, number, integer, boolean, array, enum, required, additionalProperties, minimum/maximum, minLength/maxLength, minItems/maxItems и локальные $ref/$defs. oneOf и условные секции включаются только после проверки renderer и валидатора. Неизвестные UI-компоненты и неподдерживаемые keywords отвергаются при публикации, а не игнорируются. Удалённые $ref запрещены. Ограничиваются размер, вложенность и сложность схемы. На старте запрещены пользовательские regex pattern, пока не реализованы лимиты их выполнения
|
||
|
||
## Применение значений
|
||
|
||
1. Загрузить схему и defaults, закреплённые по digest
|
||
2. Создать конфигурацию из defaults и явных значений пользователя: objects объединяются по ключам, arrays заменяются целиком; null допустим только по схеме и не означает удаление
|
||
3. Проверить итоговую конфигурацию одним согласованным набором правил
|
||
4. Проверить права на подключения и ограничения организации
|
||
5. Сохранить полный результат как новую AgentRevision с schemaDigest
|
||
|
||
JSON Schema default — аннотация, а не команда валидатору. defaults-файл при публикации обязан соответствовать схеме после объединения с обязательными вводимыми полями; отсутствующие обязательные поля пользователь заполняет до сохранения. Сервер не доверяет клиентской валидации
|
||
|
||
## UI
|
||
|
||
Web UI: TypeScript, React, JSON Forms; серверный валидатор — совместимая Go-библиотека Draft 2020-12, точная реализация выбирается по общему корпусу контрактных примеров. UI schema использует только встроенные контролы и layout, без JavaScript, HTML и внешних скриптов. Описания отображаются как безопасный текст
|
||
|
||
Поля для подключения к сервису отображают selector ConnectionRef. Секретные значения не входят в JSON конфигурации, defaults, пример или URL. readOnly, writeOnly и скрытие поля в UI не заменяют server-side permission checks. Пользователь не может через config повысить лимит ресурсов, изменить tenantId или разрешить новые сетевые доступы
|
||
|
||
## Версии и изменения
|
||
|
||
PUT конфигурации требует If-Match. При конфликте ревизии сервер возвращает 412. UI показывает различия, пользователь повторно сохраняет результат. Запуск фиксирует agentRevisionId, schemaDigest и effectiveConfig; последующие изменения агента не влияют на Run
|
||
|
||
Новая версия шаблона сначала проверяется на копии конфигурации. При несовместимости показываются JSON Pointer путей и сообщения ошибок. Старая ревизия остаётся рабочей до явного обновления. В MVP автоматических исполняемых миграций нет
|
||
|
||
## Источники и пример
|
||
|
||
- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12)
|
||
- [Аннотации и default](https://json-schema.org/understanding-json-schema/reference/annotations)
|
||
- [JSON Forms UI Schema](https://jsonforms.io/docs/uischema/)
|
||
- [Пример схемы](contracts/examples/config.schema.json)
|
||
- [Начальные значения](contracts/examples/config.defaults.json)
|
||
- [Представление формы](contracts/examples/ui.schema.json)
|
||
|
||
Ограниченный набор JSON Schema keywords относится к пользовательским формам config/input. Служебные схемы протокола могут использовать allOf/if/then и не передаются renderer. Версия профиля валидатора закрепляется вместе с шаблоном; несовместимая схема отвергается при публикации
|