vegavisuals

vegavisuals — это переиспользуемая фабрика визуализаций на основе Vega-Lite и чистого Vega. Она включает один центральный реестр тем, один контракт манифеста/блокировки проекта, адаптер stdio FastMCP и один Docker-рендерер на базе vl-convert-python==1.9.0.post1. Потребительским проектам не нужны Node, Chromium или установленный на хосте Vega.

Хостовый CLI требует Python 3.10 или новее и Linux, поскольку публикация использует дескриптор-относительный ввод-вывод, flock и операции renameat2 с отказом при закрытии. Для рендеринга также требуется Docker. Linux x86_64 — это хост, протестированный для релизов; установки из исходников на других архитектурах Linux требуют совместимых wheels для каждой закреплённой зависимости.

Профиль совместимости по умолчанию — vl-convert-1.9.0: Vega 6.2.0, Vega-Lite 6.4 по умолчанию, вывод SVG/PNG/PDF, детерминированная нормализация PDF с помощью qpdf и явно установленное семейство шрифтов DejaVu. Базовый образ закреплён по дайджесту реестра. Полный набор поддерживаемых версий Vega-Lite и политика выполнения раскрываются командой vegavisuals compatibility-status; исходные данные находятся в src/vegavisuals/assets/compat/vl-convert-1.9.0.json.

Quick Start

git clone https://github.com/dosquartsdedocs/vegavisuals.git
cd vegavisuals
python3 -m pip install '.[mcp]'
vegavisuals build-renderer

vegavisuals --project /path/to/consumer validate charts/summary.vl.json
vegavisuals --project /path/to/consumer render \
  charts/summary.vl.json public/summary.svg
vegavisuals --project /path/to/consumer render-all
vegavisuals --project /path/to/consumer check

Первая сборка рендерера требует доступа к репозиториям Debian и PyPI. Сами контейнеры рендеринга работают без доступа к сети и никогда не загружают образы. Готовый образ рендерера не публикуется; каждая установка собирает свой локальный образ из лицензированного исходного пакета и закреплённого профиля совместимости.

Два примера в репозитории охватывают столбчатую диаграмму Vega-Lite с локальным CSV проекта и чистую диаграмму Vega:

vegavisuals render examples/vega-lite/bar.vl.json dist/examples/bar.svg
vegavisuals render examples/vega/raw.vg.json dist/examples/raw-vega.svg

Related MCP server: nyyon-figures

Rendering Boundary

Каждый рендер использует фиксированную точку входа рабочего процесса в образе. Хостовый реестр:

• Разбирает JSON самостоятельно и отклоняет дублирующиеся ключи и неконечные числа.

• Ограничивает пути исходников, данных, входных данных, манифеста, кэша, блокировки и вывода корнем потребителя.

• Публикует файлы кэша, блокировки и вывода через дескриптор-относительные операции Linux без следования символьным ссылкам.

• Сериализует финальные коммиты с помощью файловой блокировки проекта, условно обменивает точные снимки файлов с помощью renameat2 и откатывает вывод, если публикация блокировки не удалась.

• Атомарно перемещает каждый выведенный из эксплуатации inode публикации в каталог .cache/vegavisuals/replaced/ с режимом 0700, так что поздние записи через уже открытый дескриптор остаются восстанавливаемыми до явной очистки кэша.

• Отклоняет зависимости HTTP/HTTPS для данных, изображений, гиперссылок и динамических URL.

• Разрешает локальные данные относительно исходного файла и снимает отпечаток (fingerprint) каждой зависимости.

• Никогда не монтирует потребительский проект в рендерер.

• Монтирует только подготовленную спецификацию и промежуточный вывод в изолированную временную директорию хоста по пути /output:rw.

• Запускает Docker с --network none, --read-only, всеми отброшенными capabilities, no-new-privileges, не-root UID/GID, ограничениями CPU/памяти/PID/файлов и ограниченной tmpfs. Корневые вызывающие используют 65534:65534.

• Проверяет чанки PNG и CRC, нормализованную структуру PDF, рекурсивную безопасность SVG и размер вывода.

• Копирует проверенный артефакт во временный соседний файл и атомарно заменяет целевой файл с хоста.

Контейнер не может публиковать напрямую в потребительский проект. Неудачные рендеры оставляют существующий целевой файл нетронутым.

Архивы восстановления — это сгенерированные данные кэша, которые никогда не удаляются автоматически. Проверяйте их после сообщённого конфликта публикации; make clean или ручное удаление кэша — это явный момент, когда они отбрасываются. Блокировка проекта, управляемые выходные файлы и .cache/vegavisuals/replaced/ должны находиться в одной файловой системе, чтобы публикация и восстановление оставались атомарными.

Source And Data Policy

Автоматический выбор движка сначала использует точные суффиксы .vl.json и .vg.json, затем распознанный $schema и, наконец, структуру mark Vega-Lite или marks чистого Vega. Явный --engine vega-lite или --engine vega также работает для JSON-источников; распознанный суффикс не может противоречить явному движку.

Файловые источники могут использовать статический data.url относительно проекта. Он разрешается из каталога исходного файла, должен указывать на обычный UTF-8 файл внутри проекта и подготавливается как необработанные встроенные values с объявленным или выведенным форматом CSV, TSV или JSON. Это позволяет избежать неоднозначности загрузчика file:, сохраняя собственный парсер форматов Vega. Символьные ссылки и выходы через .. отклоняются. HTTP, HTTPS, протокол-относительные, file:, data: и динамические URL данных отклоняются. Каналы URL изображений и гиперссылок также отклоняются, чтобы опубликованный SVG оставался автономным.

render-text применяет ту же политику зависимостей: каждый ключ url или href зависимости отклоняется, поэтому принимаются только встроенные значения. Входной текст ограничен 1 МиБ. Его ключ кэша включает источник, движок, формат, профиль и тему.

Project Manifest

.vegavisuals.yml — это версионируемый явный контракт проекта:

version: 1
profile: vl-convert-1.9.0
family: benizar
visualizations:
  - name: quarterly-bars
    source: charts/quarterly.vl.json
    output: public/quarterly.svg
    engine: vega-lite
    format: svg
    inputs:
      - charts/data/quarterly.csv
  - name: raw-overview
    source: charts/overview.vg.json
    output: public/overview.pdf

engine, format и inputs необязательны. Входные данные дополняют файлы данных, обнаруженные из спецификации, и участвуют в отпечатке (fingerprint).

.vegavisuals.lock.json использует версию блокировки 2. Каждая запись строго фиксирует источник, вывод, движок, выбранную версию Vega-Lite, формат, профиль, семейство, полный отпечаток рендера, SHA-256 вывода, входные данные и неизменяемое происхождение образа рендерера. status сообщает о следующих состояниях:

Переносимый отпечаток использует контракт рендерера, а не локальный ID образа Docker: чистые сборки могут иметь разные ID метаданных образа при использовании идентичных закреплённых входных данных. Наблюдаемый ID образа остаётся записанным как происхождение, и образ должен нести соответствующую метку контракта рендерера, прежде чем сможет выполнять рендеринг.

Свежие выводы пропускаются, если не передан --force. Существующие неуправляемые и изменённые выводы никогда не заменяются, если также не передан --replace. То же правило публикации применяется к прямым рендерам файлов и явным выводам из render-text.

Недействительный манифест или блокировка прерывает выполнение status и check вместо создания состояния invalid для каждой визуализации.

CLI

Операционные команды, возвращающие JSON, возвращают структурированный JSON. Их ошибки также возвращают JSON и ненулевой статус. Справка и --version используют обычный текст CLI, а mcp serve использует транспорт MCP stdio, а не вывод JSON команд.

vegavisuals [--project ROOT] version
vegavisuals [--project ROOT] profile-inventory
vegavisuals [--project ROOT] theme-inventory [--family FAMILY]
vegavisuals [--project ROOT] compatibility-status [--profile PROFILE]
vegavisuals [--project ROOT] factory-check
vegavisuals [--project ROOT] validate SOURCE [--engine auto|vega-lite|vega] [--input PATH]
vegavisuals [--project ROOT] render SOURCE OUTPUT [--format svg|png|pdf] [--name NAME]
vegavisuals [--project ROOT] render-text [--text JSON] [--output PATH]
vegavisuals [--project ROOT] status [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] check [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] render-all [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] factory-manifest
vegavisuals [--project ROOT] build-renderer [--profile PROFILE]
vegavisuals [--project ROOT] ensure-renderer [--profile PROFILE]
vegavisuals [--project ROOT] mcp serve
vegavisuals [--project ROOT] mcp client-config
vegavisuals [--project ROOT] mcp list-tools

Команды, учитывающие контракт, также принимают документированные опции --profile, --family, входные данные, манифест и политику публикации. Выполните vegavisuals COMMAND --help для полного описания.

render, render-text и render-all принимают --include-data, --replace, --force и --dry-run. Встроенные данные артефактов по умолчанию опускаются. По запросу SVG возвращается как artifact.svg; PNG и PDF возвращаются как artifact.data_base64. Профиль совместимости ограничивает размеры артефактов и ответов.

validate выполняет строгие проверки JSON, глубины, чисел, версии схемы, политики URL и базовой структуры Vega/Vega-Lite. Он не претендует на полную проверку JSON Schema или компилятора; закреплённый рабочий процесс остаётся авторитетным для полной семантики рендерера.

Python API

Публичный пакет экспортирует Registry, __version__ и типизированную иерархию исключений. Один экземпляр Registry фиксирует корень потребителя:

from vegavisuals import Registry

registry = Registry("/path/to/consumer")
registry.validate_visualization("charts/chart.vl.json")
registry.render_visualization("charts/chart.vl.json", "public/chart.svg")
registry.render_visualization_text(spec_json, output_format="png")
registry.visualization_status()
registry.visualization_check()
registry.render_visualizations()
registry.theme_inventory()
registry.compatibility_status()
registry.factory_manifest()

Методы жизненного цикла рендерера: build_renderer() и ensure_renderer(). Вспомогательные методы инвентаризации: profile_inventory(), factory_check() и version_status().

MCP

Корень потребителя разрешается один раз перед запуском сервера FastMCP и не является аргументом инструмента MCP:

vegavisuals --project /path/to/consumer mcp serve

Инструменты:

validate_visualization
render_visualization
render_visualization_text
visualization_status
visualization_check
render_visualizations
theme_inventory
compatibility_status
factory_manifest

Ресурсы:

vegavisuals://agent-guide
vegavisuals://themes
vegavisuals://compatibility
vegavisuals://project/status
vegavisuals://project/check
vegavisuals://factory-manifest

Инструменты MCP сохраняют документированный контракт результатов в виде словаря. Ожидаемые ошибки политики, проверки и рендеринга являются типизированными результатами приложения с ok: false, а не ошибками транспорта MCP; клиенты должны проверять ok.

Сгенерируйте шаблон конфигурации клиента с помощью:

vegavisuals mcp client-config --workspace-placeholder '${workspaceFolder}'

Заполнитель по умолчанию — это литерал для клиентов, которые разворачивают ${workspaceFolder}. Замените его абсолютным путём потребителя, если клиент не выполняет такое разворачивание. Используйте --command /absolute/path/to/vegavisuals, если исполняемый файл не находится в PATH клиента, и --format vscode-workspace для формы рабочей области VS Code.

Verification

python3 -m pip install -e '.[mcp,dev]'
make check
make tests
make tests-install
make docker-smoke
make mcp-smoke

make tests оставляет Docker в режиме mock. make docker-smoke рендерит все форматы для обоих движков и проверяет повторяемость байтов PDF с задержкой. make mcp-smoke вызывает оба движка рендеринга через stdio. Проверка wheel устанавливает пакет без редактирования, разрешает ресурсы из site-packages и вызывает оба реальных движка рендеринга через исполняемый файл MCP установленного wheel.

См. CONTRIBUTING.md для проверок вклада и SECURITY.md для поддерживаемых версий и частного сообщения об уязвимостях.

License

vegavisuals лицензируется только под GNU General Public License v3.0 (GPL-3.0-only). Vega, Vega-Lite, vl-convert и другие зависимости времени выполнения сохраняют свои исходные лицензии; см. THIRD_PARTY_NOTICES.md. Copyright (C) 2026 dosquartsdedocs.

Вызов автономного CLI, Docker-рендерера или MCP-сервера сам по себе не меняет лицензию потребительского проекта или созданных артефактов SVG, PNG и PDF. Приложения, которые копируют, изменяют, связывают или напрямую распространяют Python-пакет, должны соблюдать условия GPLv3.