18 августа 2026, 01:30

В технических статьях схема иногда объясняет больше, чем несколько экранов текста. Но есть неприятная крайность: либо рисовать каждый материал вручную в графическом редакторе, либо получать одинаковые безликие блоки, которые плохо читаются и не совпадают со стилем сайта.

Сегодня я добавил в рабочий контур HomeLab навык Diagram Design. Это открытый плагин для Claude Code, Codex и других совместимых агентов, который создаёт редакционные технические диаграммы в виде самостоятельных HTML, SVG и PNG-файлов.

Репозиторий проекта: cathrynlavery/diagram-design.

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

  • не менять существующий Markdown-пайплайн;
  • не добавлять тяжёлый JavaScript;
  • не зависеть от внешнего сервиса при открытии статьи;
  • сохранить единый стиль HomeLab;
  • не раскрывать реальные IP-адреса и чувствительную топологию;
  • получать схемы, которые можно редактировать и использовать повторно.

Что такое Diagram Design

Diagram Design — это не отдельный SaaS и не очередной визуальный конструктор. Это набор правил, шаблонов и проверок, которыми пользуется AI-агент при создании диаграммы.

В версии 2.4 доступно 27 визуальных типов, среди которых:

  • Architecture;
  • Flowchart;
  • Sequence;
  • State machine;
  • Timeline;
  • Tree и Nested;
  • Layer stack;
  • Process и Swimlane;
  • Data flow;
  • Gantt;
  • ER-модель;
  • IT current-state;
  • High-level infrastructure;
  • Loop и другие редакционные форматы.

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

Главный принцип проекта мне особенно близок:

Хорошая схема заканчивается не тогда, когда в неё всё добавили, а когда из неё больше нечего удалить.

Для HomeLab это важно. Полную внутреннюю топологию можно превратить в нечитаемую карту из десятков хостов, VM и связей. Для статьи читателю чаще нужна не инвентаризация, а одна конкретная мысль.

Первая схема: HomeLab как единый контур

Первой стала обзорная архитектурная схема моей инфраструктуры.

Архитектура HomeLab: дом, участок, WireGuard, Proxmox и мониторинг

На ней намеренно оставлены только основные роли:

  • внешний контур и независимый heartbeat;
  • домашний шлюз;
  • кластер Proxmox;
  • Zabbix и NOC;
  • WireGuard как backbone между площадками;
  • шлюз и edge-узлы участка.

Я не показываю адреса, названия физических узлов, открытые порты и детали административного доступа. Такая схема остаётся технически полезной, но не превращается в готовую карту для атаки.

Как выбирать формат схемы

Не каждый фрагмент статьи нужно превращать в SVG. Иногда таблица или короткая ASCII-схема будет лучше.

Как выбрать формат визуализации для технической статьи

Практическое правило получилось таким:

  • короткая линейная связь — ASCII;
  • схема, которую читатель должен копировать и менять, — Mermaid;
  • архитектура, процесс или материал с несколькими смысловыми уровнями — Diagram Design;
  • атмосферная обложка без точной технической семантики — генератор изображений;
  • список характеристик — таблица, а не картинка.

Это защищает статьи от визуального шума. Диаграмма должна помогать понять систему, а не просто занимать место между абзацами.

Как установлен плагин

Проект подключается в Codex через marketplace:

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

В моём окружении marketplace загрузился, но текущая версия CLI не увидела корневой пакет в его индексе. Поэтому я использовал совместимый и обратимый вариант: подключил каталог skills/diagram-design как локальный Codex skill.

ln -s \
  ~/.codex/.tmp/marketplaces/diagram-design/skills/diagram-design \
  ~/.codex/skills/diagram-design

Это не меняет проект сайта и не добавляет runtime-зависимостей. Навык используется только во время подготовки материалов.

Рабочий процесс создания диаграммы

Diagram Design заставляет сначала определить смысл, а уже потом рисовать. Это полезное ограничение: агент не начинает с выбора красивых цветов и случайных иконок.

Процесс создания и проверки диаграммы

Наш рабочий процесс состоит из шести этапов:

  1. Изучить исходный текст и фактическую инфраструктуру.
  2. Сформулировать одну мысль, которую должна объяснить схема.
  3. Выбрать семантический паттерн и подходящий визуальный тип.
  4. Удалить лишние узлы и обезличить чувствительные данные.
  5. Создать SVG и проверить геометрию, контраст и подписи.
  6. Проверить изображение на десктопе и мобильном экране.

Акцентный цвет используется максимум для одного-двух элементов. В обзорной схеме HomeLab это WireGuard и NOC: backbone связности и центр наблюдаемости.

Интеграция в существующий сайт

Самое важное — ради диаграмм не пришлось переделывать сайт.

Поток публикации Markdown и SVG на сайте HomeLab

Исходные материалы остаются простыми:

posts/article.md
assets/diagrams/article-architecture.svg
assets/diagrams/article-workflow.svg

В Markdown изображение подключается обычной ссылкой:

![Описание схемы](/assets/diagrams/article-architecture.svg)

Дальше работает существующий pipeline:

Markdown + SVG
    -> Python renderer
    -> HTML статьи
    -> индексы, поиск, RSS и sitemap
    -> Astro entrypoints
    -> Git
    -> nginx + homelab-app

SVG отдаётся как обычный статический файл. В нём нет скриптов и обращений к внешним API, поэтому статья не зависит от доступности генератора после публикации.

Почему SVG подходит техническим статьям

У формата есть несколько практических преимуществ.

Чёткость

Линии и текст не размываются на Retina, 2K и 4K-экранах. Один файл подходит для страницы, презентации и Telegram-превью после экспорта в PNG.

Небольшой размер

Первая схема HomeLab занимает всего несколько килобайт. Это заметно легче реалистичной обложки, сгенерированной в высоком разрешении.

Редактируемость

SVG остаётся текстовым документом. Можно заменить подпись, изменить цвет или переставить узел без повторной генерации всего изображения.

Доступность

В файл добавляются title, desc, role="img" и aria-labelledby. Читатель, который использует assistive technology, получает не просто безымянную картинку.

Независимость

После публикации схема работает локально на сервере. Не нужны Figma embed, Mermaid runtime, CDN со шрифтами или JavaScript-библиотека.

Где будем применять диаграммы в HomeLab

Инструмент особенно полезен для наших материалов про:

  • Proxmox: ноды, VM, ZFS, репликацию и миграции;
  • WireGuard: площадки, маршруты и trust boundaries;
  • Zabbix и NOC: метрики, внешний heartbeat и Telegram-алерты;
  • n8n: входные события, согласование и публикацию;
  • Hermes, Codex, OpenCode и Buzz: роли агентов и границы полномочий;
  • Home Assistant: USB passthrough, Zigbee coordinator и датчики;
  • публикацию сайта: Markdown, рендереры, Git и деплой;
  • аварийные сценарии: обнаружение, диагностику, откат и пост-проверку.

Для одной статьи можно использовать несколько типов, но у каждой схемы должна быть отдельная задача. Обзорная Architecture показывает компоненты. Flowchart помогает принять решение. Process объясняет последовательность действий. Data flow показывает, кто и какой артефакт передаёт дальше.

Что нельзя отдавать генератору без проверки

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

Факты

Каждый хост, сервис и канал должен подтверждаться кодом, инвентарём или текущей документацией. Если данных нет, узел не добавляется «для красоты».

Безопасность

Публичная схема не должна содержать:

  • реальные внутренние и внешние IP-адреса;
  • логины, токены и ключи;
  • точные правила firewall;
  • административные URL;
  • детали, позволяющие обойти защитный контур.

Геометрия

Стрелки не должны проходить через карточки, делить одну точку подключения или пересекаться без необходимости. Подпись не должна лежать поверх линии.

Мобильная версия

Большая архитектурная схема неизбежно уменьшается на телефоне. Поэтому рядом остаётся текстовое объяснение, а сам SVG можно открыть отдельно и увеличить. Для особенно сложной топологии правильнее создать отдельную вертикальную мобильную версию.

Правило для следующих статей

Теперь перед публикацией технического материала я буду задавать четыре вопроса:

1. Есть ли в статье связь, процесс или иерархия?
2. Поможет ли схема понять материал быстрее текста?
3. Можно ли показать это без чувствительных данных?
4. Читается ли результат на мобильном устройстве?

Если все ответы положительные, статья получает диаграмму. Если нет — остаются текст, таблица или компактный ASCII-блок.

Итог

Diagram Design стал не украшением сайта, а ещё одним инструментом документации HomeLab.

Мы получили:

  • повторяемый способ создавать технические схемы;
  • единый визуальный язык;
  • статические и лёгкие SVG-файлы;
  • доступность и редактируемость;
  • безопасное обезличивание инфраструктуры;
  • интеграцию без изменения работающего pipeline.

Первая обзорная карта уже показывает HomeLab как систему: две площадки, защищённый backbone, кластер виртуализации и независимый мониторинг. Следующий шаг — постепенно заменить самые сложные ASCII-схемы в старых статьях на редакционные диаграммы, не удаляя текстовые версии и проверяя каждый материал отдельно.