Главная/Документация/Справочник агента/Справочник синтаксиса диаграмм Mermaid
Справочник агента

Справочник синтаксиса диаграмм Mermaid

Craft Agent отображает диаграммы Mermaid как тематические SVG. Здесь описан синтаксис для создания диаграмм.

Необязательный YAML Frontmatter

Блоки кода Mermaid могут начинаться с YAML frontmatter. Craft Agent принимает frontmatter для совместимости и отображает синтаксис диаграммы, который следует за ним. Для видимых заголовков диаграмм предпочитайте синтаксис заголовка на уровне диаграммы (например, title "Monthly Revenue" в xychart-beta).

terminalbash
---
title: Example Diagram
---
graph LR
    A --> B

Диаграммы потоков

Заголовок: graph LR (слева направо, предпочтительно) или graph TD (сверху вниз)
Направления: LR (предпочтительно), RL, TD, TB, BT

Формы узлов

СинтаксисФорма
A[text]Прямоугольник
A(text)Прямоугольник со скруглёнными углами
A{text}Ромб (решение)
A([text])Стадион
A((text))Круг
A[[text]]Подпрограмма
A[(text)]Цилиндр (база данных)
A{{text}}Шестиугольник
A>text]Асимметричный флаг
A[/text\]Трапеция
A[\text/]Трапеция (альт.)
A(((text)))Двойной круг

Типы стрелок

СинтаксисСтиль
-->Сплошная стрелка
---Сплошная линия (без стрелки)
-.->Пунктирная стрелка
-.-Пунктирная линия
==>Толстая стрелка
===Толстая линия
<-->Двусторонняя сплошная
<-.->Двусторонняя пунктирная
<==>Двусторонняя толстая

Подписи рёбер

terminalbash
graph LR
    A -->|label text| B
    C -- label text --> D

Подграфы

terminalbash
graph LR
    subgraph Backend
        API --> DB
    end
    subgraph Frontend
        UI --> API
    end
    Client --> UI

Подграф с ID

terminalbash
graph TD
    subgraph backend-services [Backend Services]
        direction LR
        API --> Cache
        API --> DB
    end

Стилизация

terminalbash
graph LR
    A[Start]:::highlight --> B[End]
    classDef highlight fill:#f9f,stroke:#333
    style B fill:#bbf,stroke:#333

Цепочки рёбер

terminalbash
graph LR
    A --> B --> C --> D

Параллельные связи

terminalbash
graph LR
    A & B --> C & D

Диаграммы состояний

Заголовок: stateDiagram-v2

Базовые состояния

terminalbash
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Complete: done
    Processing --> Error: fail
    Complete --> [*]
    Error --> Idle: retry

Описания состояний

terminalbash
stateDiagram-v2
    state "Waiting for input" as Waiting
    Waiting --> Processing

Композитные состояния

terminalbash
stateDiagram-v2
    state "Active" as Active {
        Running --> Paused: pause
        Paused --> Running: resume
    }
    [*] --> Active
    Active --> [*]: complete

Переопределение направления

terminalbash
stateDiagram-v2
    direction LR
    [*] --> A --> B --> [*]

Диаграммы последовательностей

Заголовок: sequenceDiagram

Типы сообщений

СинтаксисЗначение
->>Сплошная линия, сплошной наконечник
-->>Пунктирная линия, сплошной наконечник
-)Сплошная линия, открытый наконечник (асинхронный)
--)Пунктирная линия, открытый наконечник
-xСплошная линия с X (потерянное сообщение)
--xПунктирная линия с X

Участники

terminalbash
sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database

    C->>S: POST /api/users
    S->>DB: INSERT user
    DB-->>S: OK
    S-->>C: 201 Created

Активации

terminalbash
sequenceDiagram
    Client->>+Server: Request
    Server->>+Database: Query
    Database-->>-Server: Results
    Server-->>-Client: Response

Заметки

terminalbash
sequenceDiagram
    Alice->>Bob: Hello
    Note right of Bob: Bob thinks
    Bob-->>Alice: Hi!
    Note over Alice,Bob: Conversation complete

Циклы

terminalbash
sequenceDiagram
    loop Every minute
        Client->>Server: Heartbeat
        Server-->>Client: ACK
    end

Альтернативы

terminalbash
sequenceDiagram
    Client->>Server: Request
    alt Success
        Server-->>Client: 200 OK
    else Failure
        Server-->>Client: 500 Error
    end

Необязательный блок

terminalbash
sequenceDiagram
    opt If cached
        Server-->>Client: Cached response
    end

Параллельный блок

terminalbash
sequenceDiagram
    par Parallel requests
        Client->>ServiceA: Request A
    and
        Client->>ServiceB: Request B
    end

Диаграммы классов

Заголовок: classDiagram

Классы с членами

terminalbash
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
        +move(distance) void
    }

Модификаторы видимости

СимволЗначение
+Публичный
-Приватный
#Защищённый
~Пакет/внутренний

Связи

СинтаксисЗначение
<\|--Наследование (extends)
*--Композиция (contains)
o--Агрегация (has)
-->Ассоциация
..>Зависимость
..\|>Реализация (implements)
--Связь (сплошная)
..Связь (пунктирная)

Кардинальность

terminalbash
classDiagram
    Customer "1" --> "*" Order : places
    Order "1" *-- "1..*" LineItem : contains

Полный пример

terminalbash
classDiagram
    class Animal {
        <<abstract>>
        +String name
        +int age
        +makeSound()* void
    }

    class Dog {
        +String breed
        +bark() void
    }

    class Cat {
        +bool indoor
        +meow() void
    }

    Animal <|-- Dog
    Animal <|-- Cat

Аннотации

terminalbash
classDiagram
    class Service {
        <<interface>>
        +start() void
        +stop() void
    }

    class Logger {
        <<singleton>>
        -instance Logger
        +log(msg) void
    }

Диаграммы ER

Заголовок: erDiagram

Базовые связи

terminalbash
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "is in"

Обозначение кардинальности

СлеваСправаЗначение
||||Ровно один к ровно одному
||o|Ровно один к нулю или одному
||o{Ровно один к нулю или многим
|||{Ровно один к одному или многим
o|o|Ноль или один к нулю или одному
o|o{Ноль или один к нулю или многим
o{o{Ноль или много к нулю или многим

Атрибуты сущностей

terminalbash
erDiagram
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        date created_at
    }

    USER ||--o{ ORDER : places

Типы атрибутов

Основные маркеры атрибутов:

  • PK — первичный ключ
  • FK — внешний ключ
  • UK — уникальный ключ

Полный пример

terminalbash
erDiagram
    CUSTOMER {
        int id PK
        string email UK
        string name
        string phone
    }

    ORDER {
        int id PK
        int customer_id FK
        date order_date
        string status
    }

    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }

    LINE_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }

    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "included in"

XY-диаграммы

Заголовок: xychart-beta (вертикальные диаграммы) или xychart-beta horizontal (горизонтальные диаграммы)

Используйте XY-диаграммы для метрик, трендов, сравнений и простых столбчатых/линейных визуализаций.

Директивы

СинтаксисЗначение
title "Chart Title"Необязательный заголовок диаграммы
x-axis [A, B, C]Категориальная ось X
x-axis "Label" [A, B, C]Категориальная ось X с заголовком
x-axis 0 --> 100Числовой диапазон оси X
x-axis "Label" 0 --> 100Числовая ось X с заголовком
y-axis "Label" 0 --> 100Числовая ось Y с заголовком/диапазоном
bar [10, 20, 30]Столбчатая серия
line [12, 18, 28]Линейная серия

Столбчатая диаграмма

terminalbash
xychart-beta
    title "Monthly Revenue"
    x-axis [Jan, Feb, Mar, Apr]
    y-axis "Revenue ($k)" 0 --> 100
    bar [25, 45, 60, 80]

Линейная диаграмма

terminalbash
xychart-beta
    title "Latency Trend"
    x-axis [Mon, Tue, Wed, Thu, Fri]
    y-axis "Latency (ms)" 0 --> 500
    line [320, 280, 240, 210, 180]

Смешанная столбчатая и линейная диаграмма

terminalbash
xychart-beta
    title "Signups vs Activations"
    x-axis [Week 1, Week 2, Week 3, Week 4]
    y-axis "Users" 0 --> 1000
    bar [420, 560, 690, 820]
    line [210, 330, 520, 700]

Горизонтальная столбчатая диаграмма

terminalbash
xychart-beta horizontal
    title "Issue Counts by Severity"
    x-axis [Low, Medium, High, Critical]
    y-axis "Issues" 0 --> 50
    bar [42, 28, 12, 4]

Лучшие практики

Предпочитайте горизонтальную (альбомную) ориентацию

ВАЖНО: Используйте горизонтальные макеты (LR, RL) везде, где возможно. Горизонтальные диаграммы значительно удобнее просматривать и навигировать в UI.

  • Диаграммы потоков: используйте graph LR (слева направо), а не graph TD (сверху вниз)
  • Диаграммы состояний: добавьте direction LR после заголовка
  • Диаграммы последовательностей: по умолчанию горизонтальные, изменения не нужны
  • Диаграммы классов: для широких иерархий рассмотрите разбиение на несколько горизонтальных диаграмм
  • Диаграммы ER: по умолчанию горизонтальные, изменения не нужны

Используйте вертикальные макеты (TD, BT) только когда:

  • Диаграмма по своей природе иерархическая (оргструктуры, древовидные структуры)
  • Вертикальный макет значительно понятнее горизонтального
  • В диаграмме очень мало узлов (не более 3–4)

Держите диаграммы сфокусированными

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

Используйте описательные подписи

terminalbash
graph LR
    A[User submits form] --> B{Validation}
    B -->|Valid| C[Save to database]
    B -->|Invalid| D[Show errors]

Выбирайте правильное направление

Горизонтальное (предпочтительно):

  • LR (слева направо): ПО УМОЛЧАНИЮ — используйте для потоков, конвейеров, автоматов состояний, процессов и большинства диаграмм
  • RL (справа налево): обратные потоки (когда это имеет смысловое значение)

Вертикальное (используйте умеренно):

  • TD (сверху вниз): только для иерархий, наследования, оргструктур, где вертикальная структура необходима
  • BT (снизу вверх): только для зависимостей, направленных вверх

Проверяйте сложные диаграммы

Используйте инструмент mermaid_validate, чтобы проверить синтаксис перед выводом сложных диаграмм:

terminalbash
mermaid_validate({ code: "graph TD\n  A --> B" })

Устранение неполадок

Частые ошибки

  1. Отсутствует направление: всегда указывайте направление в диаграммах потоков (graph TD, а не просто graph)
  2. Несбалансированные скобки: убедитесь, что все [, (, { правильно закрыты
  3. Специальные символы в подписях: используйте кавычки для подписей со специальными символами
  4. Неверный синтаксис стрелок: проверьте таблицу типов стрелок выше

Экранирование специальных символов

Для подписей со специальными символами заключайте их в кавычки:

terminalbash
graph LR
    A["Label with (parentheses)"] --> B["Label with [brackets]"]

Нужен такой агент в вашей компании?

Устанавливаем под ключ: настройка на компьютерах сотрудников, единый аккаунт, интеграция с 1С и внутренними системами, обучение команды. Подробнее о внедрении →