Diagram: превратите объяснение в наглядную схему

Архитектуру, автомат состояний или модель данных проще обсуждать, когда человек и агент смотрят на одну схему. Diagram хранит исходное описание схемы в файле и показывает её на Canvas. Можно запросить предложение, отредактировать исходный текст, увидеть результат и пересмотреть решение, не переключая контекст.

Схема не заменяет Specification: она помогает обнаружить неоднозначность, объяснить решение или представить альтернативу. Контракт остаётся в предназначенном для него месте.

Посмотреть изображение в полном размере

Схема участвует в том же рабочем графе, что CodingAgent и Sticky Note. Её источник остаётся файлом.

Создайте или добавьте Diagram

Через интерфейс

1. Нажмите Diagram на панели инструментов Canvas или откройте панель Diagrams, сразу после Specs, и выберите New diagram.
2. Выберите формат и введите имя. По умолчанию используется Mermaid.
3. Перед созданием проверьте показанные путь и расширение. Enter подтверждает; Escape отменяет.
4. Пишите в Source или начинайте рисовать, если выбрали Excalidraw.

Можно также перетащить Diagram с панели инструментов в нужную точку Canvas. Форма откроется в панели и сохранит эту точку до подтверждения; при нажатии на панели инструментов используется видимая область.

В форме нет отдельного поля папки. Создание через панель инструментов или общее действие New diagram использует путь, настроенный в Workspace. Команда New Diagram… в меню папки использует эту папку. Перед подтверждением проверьте показанный путь. Совпадения имён и ошибки отображаются в форме, не перезаписывая файлы. draw.io отсутствует среди форматов создания, поскольку его редактор внешний.

Посмотреть изображение в полном размере

Выберите формат для создания через панель. draw.io открывается из существующего файла, поэтому в этом списке его нет.

Выберите папку для новых диаграмм

Откройте Workspace Settings → Documentation roots. Specifications и Diagrams используют общие корневые папки; отдельного списка корней для Diagrams нет.

Поле Diagrams folder задаётся относительно первой Documentation root. По умолчанию это diagrams: при корне docs получается docs/diagrams/. Можно указать вложенную папку, например architecture/diagrams, и проверить вычисленный путь перед сохранением. Используйте ., чтобы создавать прямо в первом корне, без подпапки.

Изменение поля или порядка корней влияет только на следующие создания. Существующие файлы и Nodes не перемещаются. Панель обнаруживает диаграммы внутри Documentation roots; файл за их пределами всё равно можно открыть на Canvas по явному пути. Настройка обнаружения не предоставляет новых разрешений файловой системы.

Из существующего файла

Используйте Add to Canvas в панели Diagrams или перетащите файл на Canvas. Расширение определяет формат, включая составные расширения, такие как .vl.json. Источник остаётся на месте; изменения на диске обновляют Node.

SVG нужно выбрать явно: открытие или перетаскивание .svg обычно создаёт File, а не Diagram. Когда просите CodingAgent добавить его, укажите, что нужен Diagram. Если тот же файл уже представлен как File, операция преобразует Node, сохраняя идентичность, положение, размер и Connections, без изменения файла.

Для каждого источника в Workspace может быть не более одного Node. Переименование Diagram переименовывает его исходный файл; удаление Node не удаляет файл.

Работайте с CodingAgent

Опишите, что хотите донести, а не только формат. «Покажи решение и пути отказа в этом процессе» даёт больше контекста, чем «сделай красивую диаграмму». Начинайте с небольших примеров и проверяйте, соответствует ли схема системе.

Примеры ниже — отправные точки с вымышленными данными. Вставьте запрос в ответственный CodingAgent и адаптируйте имена и пути перед отправкой. Для создания Node требуется Allow workspace editing; существующие ресурсы должны быть достижимыми, а их Guardrails продолжают действовать. Без разрешения структурных изменений просите только исходный текст или рекомендации.

Если путь не указан, CodingAgent проверяет Documentation roots и Diagrams folder Workspace и использует то же место, что интерфейс: docs/diagrams/ при стандартной настройке. Явный путь в запросе имеет приоритет. Примеры используют явные пути в docs/diagrams/; адаптируйте их, если хотите хранить файлы в другом настроенном корне и находить их через панель.

Проверяйте схему, а не только синтаксис

CodingAgent может записать исходный текст, добавить его Diagram на Canvas и запросить результат рендеринга текущего файла: rendered, failed или not_rendered. При сбое он получает ошибку движка и номер строки, если он доступен.

Внешне правильный исходный текст не доказывает успешный рендеринг. not_rendered означает отсутствие действительного наблюдения для текущего файла; откройте или покажите Diagram, чтобы он отобразился. Результаты другой редакции файла, несохранённые preview и наблюдения до перезапуска не считаются подтверждением успеха для текущего файла на диске.

Если Diagram достижим, но на прямой Connection стоит diagram_read_only, агент обязан сохранить источник без изменений и не может переименовывать или удалять Node. Не обходите ограничение запросом или инструментами файловой системы.

От запроса до схемы на Canvas

Посмотрите, как CodingAgent создаёт диаграмму сущностей CRM на Canvas (открывается в новой вкладке).

Практическая демонстрация начинается с CodingAgent и Sticky Note с контекстом. Пользователь просит простую диаграмму сущностей CRM; агент использует Excalidraw, записывает исходный файл и добавляет на Canvas соединённый с ним Diagram. Как и в примерах ниже, создание Node зависит от разрешения редактировать Workspace.

Результат включает Account, Contact, Lead, Opportunity и Activity с вымышленными полями и связями. Проверьте схему, прежде чем использовать её как модель проекта: она иллюстрирует предложение, а не анализ вашей реальной схемы данных. Демонстрация показывает создание вплоть до визуального результата; редактирование, экспорт и организация папок описаны отдельно в этом руководстве.

Запись без звука, на английском языке. Набор текста и ожидание местами ускорены; итоговый результат показан с обычной скоростью. Текст выше позволяет понять демонстрацию без просмотра видео.

Выбирайте формат по тому, что нужно объяснить

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

Посмотреть изображение в полном размере

На Canvas могут соседствовать разные форматы. Это иллюстративные примеры; форматы и ограничения подробно описаны ниже.

Mermaid — .mmd, .mermaid

Хорошая отправная точка для потоков, последовательностей и состояний. Доступны типы встроенного в Kavor движка; не предполагайте, что недавно добавленный в Mermaid синтаксис уже поддерживается здесь. Вставьте в CodingAgent, чтобы создать небольшой вымышленный процесс.

Создай docs/diagrams/checkout.mmd в Mermaid: корзина → оплата → подтверждение, с отдельным путём отказа в оплате.
Добавь как Diagram в мой граф и проверь результат рендеринга текущего файла.
Исправь сообщённые ошибки; не меняй приложение и не объявляй успех без наблюдения результата.

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

PlantUML — .puml, .plantuml

Для UML, последовательностей, диаграмм Ганта, интеллект-карт и каркасов интерфейсов. Движок JavaScript не требует установки Java. Стандартные библиотеки, включая C4, загружаются по запросу; первое использование C4 может потребовать дополнительной загрузки. Вставьте запрос в CodingAgent.

Создай docs/diagrams/checkout-context.puml с библиотекой C4: клиент, магазин и внешний платёжный провайдер.
Обозначь связи, добавь файл как Diagram и запроси результат для текущего файла.
Если не хватает библиотеки или возникает ошибка, сообщи причину, прежде чем объявлять схему готовой.

Ожидаемый результат: простой контекст C4 с явно обозначенной внешней зависимостью. Отсутствие сети или библиотеки не должно выдаваться за проверку схемы.

Graphviz — .dot, .gv

Для графов, в которых расположение вершин помогает понять зависимости. Доступны алгоритмы компоновки встроенного движка. Вставьте в CodingAgent; зависимости в примере вымышленные, а не выведенные из вашего репозитория.

Создай docs/diagrams/dependencies.dot: web зависит от api; api — от billing и catalog; оба зависят от storage.
Расположи граф слева направо, добавь как Diagram и проверь рендеринг текущего файла.
Не придумывай зависимости реального проекта; это только описанный пример.

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

D2 — .d2

Для архитектуры и связей компонентов. Kavor предлагает компоновки Dagre и ELK; TALA не поддерживается. Вставьте в CodingAgent и указывайте компоновку явно, если выбор важен.

Создай docs/diagrams/order-service.d2 с компоновкой Dagre: клиент, API, очередь и worker, показывающие путь заказа.
Добавь как Diagram и проверь рендеринг текущего файла. Используй только возможности Dagre или ELK, без TALA.
Сообщи о любых ошибках и не меняй реальную инфраструктуру.

Ожидаемый результат: понятная архитектурная схема без зависимости от TALA и без создания изображённых сервисов.

SVG — .svg

Для векторных рисунков, где нужно напрямую управлять фигурами, подписями и композицией. Отображение встроенное. Вставьте в CodingAgent и явно запросите Diagram, сохранив отличие от обычного File.

Создай docs/diagrams/review-cycle.svg: три блока — Builder, Reviewer и решение человека, соединённые в этом порядке.
Сделай самодостаточный SVG без скриптов и удалённых ресурсов и добавь явно как Diagram, не как File.
Проверь рендеринг текущего файла и сообщи результат, не меняя другие Nodes.

Ожидаемый результат: векторный рисунок в виде Diagram. Само расширение .svg не меняет тип File.

Excalidraw — .excalidraw

Для исследовательского рисунка, который вы хотите продолжить редактировать визуально. Файл содержит сцену Excalidraw; это формат с визуальным редактором в Kavor. Вставьте в CodingAgent для подготовки простой сцены.

Создай docs/diagrams/review-workshop.excalidraw с корректной сценой: идея, реализация и проверка, со стрелками и подписями.
Добавь как Diagram и проверь рендеринг. Оставь рисунок простым, чтобы я продолжил через Edit drawing.
Не заменяй существующий файл и не утверждай, что моя проверка уже выполнена.

Ожидаемый результат: сцена, которую можно открыть через Edit drawing. Генерация сцены сама по себе не гарантирует качества изображённого процесса; проверьте его, прежде чем использовать как решение.

draw.io — .drawio

Для просмотра диаграмм этого формата, включая страницы и слои. View only: в Kavor нет ни визуального редактора, ни редактирования XML в Source. Создавайте и меняйте файл внешним инструментом, в том числе через файловую систему CodingAgent, если это разрешено. Вставьте запрос агенту для создания нового примера, а не перезаписи вашего документа.

Создай docs/diagrams/order-overview.drawio как корректный файл draw.io с одной страницей: клиент → API → база данных.
Добавь существующий файл как Diagram и проверь рендеринг текущего файла.
Не используй New diagram для draw.io и не обещай визуальное редактирование внутри Kavor.

Ожидаемый результат: страница, доступная для просмотра в Node. Для последующих изменений используйте внешнее приложение или разрешённое редактирование исходного файла; Kavor отслеживает его изменения.

Vega-Lite / Vega — .vl.json, .vg.json

Для графиков данных. .vl.json выбирает Vega-Lite; .vg.json — Vega. Это разные грамматики, недостаточно сменить расширение. Для примера без сетевых зависимостей вставьте в CodingAgent запрос со встроенными данными.

Создай docs/diagrams/build-times.vl.json в Vega-Lite: столбцы для вымышленных длительностей сборки 12, 18 и 9 секунд.
Включи данные прямо в JSON, подпиши оси и не загружай внешние наборы данных.
Добавь как Diagram и проверь рендеринг текущего файла.

Ожидаемый результат: график, позволяющий сравнить значения, с понятными единицами измерения. Для Vega явно запросите эту грамматику и путь .vg.json. Удалённый набор данных всё равно требует сети, даже если движок уже в кеше.

WaveDrom — .wavedrom

Для временных диаграмм цифровых сигналов. Kavor использует корректный JSON, а не скрипт JavaScript. Вставьте запрос в CodingAgent, чтобы показать простой обмен сигналами.

Создай docs/diagrams/handshake.wavedrom в корректном JSON с clock, request и acknowledge на протяжении восьми циклов.
Явно покажи, когда acknowledge отвечает на request; не выполняй скрипты.
Добавь как Diagram и запроси результат для текущего файла, исправляя ошибки, сообщённые движком.

Ожидаемый результат: сигналы, выровненные во времени. Схема объясняет пример, но не подтверждает измерение оборудования.

nomnoml — .nomnoml, .noml

Для кратких эскизов UML. У nomnoml собственный синтаксис, не взаимозаменяемый с PlantUML. Вставьте в CodingAgent.

Создай docs/diagrams/order-model.nomnoml с Order, OrderItem и Product, показывая связи и несколько атрибутов.
Используй синтаксис nomnoml, добавь как Diagram и проверь рендеринг текущего файла.
Оставь модель вымышленной; не меняй классы или схему данных проекта.

Ожидаемый результат: эскиз сущностей для обсуждения, а не автоматическая реализация по рисунку.

Pikchr — .pikchr

Для технических композиций на языке рисования в стиле PIC. Используется грамматика Pikchr, а не произвольная программа PIC. Вставьте в CodingAgent для небольшой схемы обработки.

Создай docs/diagrams/processing.pikchr с входом, преобразованием и выходом, используя подписанные блоки и стрелки.
Используй синтаксис Pikchr, добавь как Diagram и проверь рендеринг текущего файла.
Если движок отклонит источник, исправь наблюдаемую ошибку, прежде чем сообщать результат.

Ожидаемый результат: простая векторная композиция. Внешне правдоподобный синтаксис не заменяет наблюдения результата движка.

Svgbob — .bob

Для преобразования ASCII-эскиза в векторный рисунок. Выравнивание текста — часть исходного описания. Вставьте в CodingAgent и сохраните выравнивание в файле.

Создай docs/diagrams/request-path.bob в ASCII: два блока с подписями Client и Server, соединённые стрелкой.
Сохрани выравнивание, добавь как Diagram и проверь рендеринг текущего файла.
Не ограничивайся вставкой изображения: оставь текстовый эскиз редактируемым источником.

Ожидаемый результат: рисунок из текстового эскиза. Изменение пробелов может изменить геометрию.

DBML — .dbml

Для обсуждения таблиц, столбцов и связей. Источник — DBML, а не SQL; рендеринг не создаёт таблицы и не выполняет миграцию. Вставьте в CodingAgent запрос с вымышленной моделью.

Создай docs/diagrams/shop-schema.dbml с customers, orders и order_items, обозначив ключи и связи.
Добавь как Diagram и проверь рендеринг текущего файла.
Не подключайся к реальной базе, не создавай миграции и не считай пример схемой данных моего проекта.

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

Переключайтесь между схемой и исходным текстом

• Diagram: главное — визуальный результат. Существующие файлы открываются в этом режиме.
• Source: показывает исходный текст. Для редактируемых форматов используются редактор и процесс сохранения Files.
• Split: исходный текст слева и preview справа — удобно править и сравнивать без переключения контекста.

Новые диаграммы текстовых форматов открываются в Source. В Excalidraw используйте Edit drawing для перехода в визуальный редактор и Finish editing для возврата к рисунку. Изменения используют тот же файл и процесс сохранения; отдельного второго Save для рисунка нет. Визуальное редактирование и правка исходного текста не активны одновременно.

Для draw.io Source доступен только для чтения. Используйте Open with default app для работы во внешнем редакторе.

В режиме Diagram перетаскивание правой кнопкой мыши перемещает внутреннюю область просмотра; жест сведения пальцев или Ctrl/⌘ + колесо меняет масштаб, не перемещая Canvas. Используйте управление масштабом и Fit, чтобы вписать схему. Заголовок по-прежнему служит для перемещения Node. У редактора Excalidraw свои элементы управления.

Посмотреть изображение в полном размере

Для текстовых форматов Split сближает код и результат. Excalidraw также позволяет визуально редактировать сам рисунок.

Когда preview устарел

Если правка не отрисовалась, последний успешный результат может остаться видимым с Preview out of date и ошибкой движка. Он относится к предыдущему исходному тексту, а не доказывает успех нового. Если сообщён реальный номер строки, её можно открыть в Source; для файла, который ещё ни разу не отрисовался, показываются исходный текст и ошибка.

Исправьте синтаксис, сохраните и проверьте результат текущего файла. Ошибки сохранения и конфликты отличаются от ошибок рендеринга; не отбрасывайте локальную правку только потому, что на экране ещё есть схема.

Экспортируйте для передачи другим

Действие Export предлагает SVG и PNG полной схемы, а не обрезанный снимок видимой части Node. Для draw.io экспортируется активная страница с её слоями. Если preview устарел, экспорт использует последний успешный рендеринг и сообщает об этом. Если отрисованного результата ещё нет, экспорт недоступен.

Используйте панель Diagrams, не заполняя Canvas

Панель рекурсивно находит файлы диаграмм внутри Documentation roots, учитывает .gitignore, позволяет искать по имени или пути и выбирать формат в All formats. Она не выполняет общий поиск всех файлов Workspace.

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

Specs и Diagrams показывают одни Documentation roots. Папка, созданная в одной панели, появляется в другой: это та же папка на диске, а не копия. Это не превращает Specification в диаграмму и не меняет её lifecycle.

• Preview: открывает просмотр только для чтения, без добавления Node. Наведение или выбор строки его не открывают. Одновременно открыта одна предварительная версия; Escape закрывает её и возвращает фокус к действию.
• Add to Canvas: добавляет источник; если Node уже есть, действие находит существующий.
• New diagram: создаёт через встроенную форму с форматом и именем.
• Show in File Manager: показывает файл или папку в системном файловом менеджере.

Для предварительного просмотра может потребоваться загрузить движок формата. Закрытие preview не делает запоздавший результат действительным рендерингом другого файла.

Посмотреть изображение в полном размере

Preview позволяет посмотреть схему, не создавая Node. Add to Canvas — отдельное действие.

Создавайте и организуйте папки

Откройте контекстное меню папки в дереве:

• New Diagram…: открывает встроенную форму для создания в этой папке, даже если она не выбрана по умолчанию в Diagrams folder. Выберите формат, введите имя и проверьте путь.
• New Folder…: создаёт настоящую подпапку; она может оставаться пустой, пока не понадобится диаграмма.
• Rename Folder…: меняет имя папки, не выбирая другой родительский каталог. Затронутые Diagram Nodes следуют за новым путём.
• Show in File Manager: открывает расположение в системном файловом менеджере.

Этими действиями нельзя переименовать или удалить настроенные Documentation roots. Для изменения корней обнаружения или места создания по умолчанию используйте настройки Workspace, а не удаление папки.

Переименовывайте, перемещайте и версионируйте файл

В контекстном меню диаграммы Rename Diagram… меняет имя файла с сохранением расширения, включая составные, такие как .vl.json. Чтобы переместить файл, перетащите строку в другую папку или корень дерева. Если файл уже отслеживается Git, используется git mv; неотслеживаемый файл также можно переместить.

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

В репозитории Git Commit Diagram создаёт коммит только для пути этого файла и показывает итоговый хеш. Изменения других путей, уже находящиеся в индексе, в него не входят. Действие работает и без Node на Canvas: версионируется файл, а не снимок схемы.

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

Удаляйте, различая файл и Node

Delete Diagram в меню файла после подтверждения удаляет исходный файл и его Diagram Nodes. Это не то же самое, что удалить только Node с Canvas: при этом файл сохраняется.

Delete Folder and Contents требует подтверждения и удаляет только поддерево, содержащее распознанные файлы диаграмм и настоящие каталоги. При обнаружении Specification, другого типа файла, скрытого элемента или символической ссылки панель отклоняет операцию до любых изменений и предлагает использовать Files для смешанного содержимого. Эта проверка относится только к Diagrams и не меняет правила удаления в панели Specs.

При удалении отдельной отслеживаемой диаграммы Kavor использует процесс удаления Git. Если Git отклоняет операцию, например из-за локальных изменений, разберитесь с указанным состоянием перед повторной попыткой; подтверждение не разрешает принудительно отбросить эти изменения.

Включайте источник в граф

Достижимый Diagram предоставляет исходный текст и визуальный результат для работы CodingAgent. Необязательно соединять с ним каждого агента напрямую; прямая Connection важна, когда нужно применить diagram_read_only к этой паре.

Connection Diagram + Terminal передаёт абсолютный путь исходного файла через выбранную вами переменную окружения, как File + Terminal. Значение — путь, а не отрисованный SVG или PNG. Настройте её до запуска сессии или перезапустите сессию для применения изменённого параметра. См. матрицу Connections.

Загрузки, конфиденциальность и автономная работа

Схема отрисовывается внутри Kavor, а не отправляется во внешний сервис рендеринга. Движки, шрифты и вспомогательные ресурсы загружаются по запросу, проверяются и сохраняются в кеше данных приложения. Открытие Kavor или Workspace не загружает все форматы. SVG использует встроенное отображение.

После первого использования полученные ресурсы можно использовать без сети. Редактор Excalidraw загружается только при входе в редактирование; библиотеки PlantUML, например C4, и ресурсы draw.io также могут требовать первоначальной загрузки. Обновление Kavor, заменившее эти ресурсы, может потребовать новой загрузки при следующем использовании.

При первой попытке без сети или ошибке загрузки Node показывает причину и Retry. Исходный текст редактируемых форматов остаётся доступным; повторите попытку, когда ресурсы можно будет получить.

Кеш движка не означает полного отсутствия сетевых запросов. Само содержимое может ссылаться на удалённые изображения, наборы данных и другие ресурсы. Локальные includes разрешаются относительно папки диаграммы, а их изменения могут обновлять схему. Проверяйте незнакомые источники перед открытием; для автономной работы предпочитайте самодостаточное содержимое и заранее подготовьте все необходимые ресурсы.

Область диаграммы изолирована от привилегированного интерфейса приложения. Это не делает ссылки внутри схемы доверенными источниками. Если просите CodingAgent создать или проанализировать содержимое, участие provider подчиняется условиям выбранного harness; не путайте локальный рендеринг с локальной обработкой моделью.

Что дальше

• Добавляйте содержимое на Canvas, не копируя источники без необходимости.
• Храните решения в Specification, используя схему для их объяснения.
• Проверьте поддерживаемые Connections и границы контекста CodingAgents.