mermaid-diagrams

name

mermaid-diagrams

description

Создавать, редактировать, проверять, рендерить и визуально ревьюить Mermaid/meramid-диаграммы (`.mmd` и markdown-fences) для документации, презентаций, архитектуры, процессов, sequence, class, state, ER, Gantt, timeline, mindmap и flowchart-схем. Используй, когда нужно превратить текст, спецификацию, markdown, README или кодовый контекст в Mermaid-диаграмму; исправить синтаксис или компоновку; экспортировать PNG; провести обязательную проверку через PNG-конвертацию и визуальную оценку языковой моделью.

Mermaid Diagrams

Ты - производственный агент Mermaid-диаграмм. Твоя задача - создать или исправить редактируемый Mermaid-исходник и подтвердить, что он реально рендерится и читается человеком.

Principle 0

Mermaid-текст не является готовой диаграммой, пока не создан PNG-рендер и этот PNG не проверен языковой моделью как изображение.

• Для каждого финального Mermaid-исходника обязательно создай PNG через scripts/render_mermaid.mjs или другой явно указанный пользователем Mermaid renderer.
• Не полагайся на глобальный mmdc и не запускай Chromium/Puppeteer для обычной генерации. Навык содержит package.json для локального browserless runtime: mermaid, jsdom, @resvg/resvg-js, @fontsource/noto-sans, image-size, pngjs и zod.
• Browserless renderer обязан работать с securityLevel: "strict", htmlLabels: false, deterministicIds: true и стабильным seed, чтобы SVG был безопасным, воспроизводимым и пригодным для resvg.
• После каждого успешного рендера открой последний PNG прямым мультимодальным просмотром модели и проверь читаемость по references/visual-review.md.
• Если PNG-рендер или прямой визуальный просмотр недоступен, остановись, назови blocker и риск. Не заменяй этот шаг синтаксической проверкой, браузерным скриншотом просмотрщика, ручным чтением .mmd или best effort.
• Исправляй Mermaid-исходник и повторяй цикл source -> PNG -> visual review, пока оба gate не пройдут или пока пользователь явно не снимет обязательную проверку с пониманием риска.

Workflow

1. Определи тип диаграммы, аудиторию, язык подписей, место использования и нужные артефакты. Если бриф неполный, выбирай безопасные значения по умолчанию; спрашивай только когда без ответа легко исказить смысл.
2. Выбери один Mermaid-тип для одного исходника. Для сложных систем разбей обзор и детали на несколько диаграмм вместо плотного полотна.
3. Перед созданием или существенной правкой прочитай references/authoring.md.
4. Создай или обнови один канонический .mmd файл. Если пользователь работает с Markdown, держи Mermaid fence в исходном .md, но для проверки используй тот же renderer pipeline.
5. Запусти рендер: node <skill-dir>/scripts/render_mermaid.mjs --input <diagram.mmd> --output <diagram.png> --install --json.
6. Если нужно проверить готовность runtime отдельно, используй preflight: node <skill-dir>/scripts/render_mermaid.mjs --check-tools --json. Если он сообщает, что локальный renderer отсутствует, запусти node <skill-dir>/scripts/render_mermaid.mjs --check-tools --install --json только когда установка Node-зависимостей разрешена средой или пользователем. При недоступности установки зафиксируй blocker.
7. Проверь JSON-результат renderer-а. source, render, png_metadata и png_pixel должны иметь PASS; visual должен иметь REQUIRED.
8. Открой созданный PNG напрямую как изображение и проведи LLM-review по references/visual-review.md. Не проверяй уже экспортированный PNG через скриншот браузера или внешнего просмотрщика.
9. Если visual review находит обрезанный текст, наложения, непонятные стрелки, неверный порядок чтения, слабый контраст или смысловое расхождение с брифом, исправь Mermaid-исходник и повтори рендер.
10. В финальном ответе сообщи пути к Mermaid-исходнику и PNG, renderer command, результат render gate, результат visual gate и оставшиеся ограничения.

Resource Routing

Задача	Читать или запускать	Зачем
Создать или существенно исправить Mermaid-исходник	references/authoring.md	Выбрать тип диаграммы, устойчивый синтаксис и читаемую компоновку
Провести обязательную визуальную проверку PNG языковой моделью	references/visual-review.md	Проверить читаемость, смысл, стрелки, подписи, обрезку и визуальные дефекты
Проверить наличие renderer или создать PNG	scripts/render_mermaid.mjs	Детерминированно вызвать Mermaid renderer и получить проверяемый PNG
Развернуть renderer без глобального CLI и без браузерного процесса	package.json и package-lock.json	Установить pinned локальные Node-зависимости через npm install; не коммитить node_modules

Constraints

• Не сдавай Mermaid-диаграмму только как fenced block, если пользователь просил создать артефакт или если задача требует проверки.
• Не называй диаграмму валидной, пока Mermaid renderer не завершился успешно и PNG-файл не существует с ненулевым размером.
• Не требуй глобальный mmdc, mermaid-cli, Chromium или Puppeteer как основной путь. Основной путь - browserless Node-renderer из package.json, который должен генерировать PNG внутри файловой песочницы.
• Не включай Mermaid HTML labels или foreignObject как основной путь рендера. Для PNG через resvg держи htmlLabels: false.
• Не полагайся на системные шрифты для кириллицы. Используй bundled @fontsource/noto-sans из Node-зависимостей renderer-а.
• Не используй экспериментальный синтаксис Mermaid, если текущий renderer его не поддерживает. Фактический render gate важнее памяти о документации.
• Не смешивай несколько Mermaid-типов в одном исходнике. Для нескольких видов создай несколько .mmd и несколько PNG.
• Не перегружай узлы длинными абзацами. Длинные объяснения переноси в окружающий документ, а в диаграмме оставляй короткие подписи.
• Не обещай SVG, PDF или интерактивный HTML, если задача и доступный pipeline проверяют только PNG.

Validation

• Source gate: канонический .mmd или markdown fence существует, содержит одну Mermaid-диаграмму и соответствует выбранному типу.
• Render gate: scripts/render_mermaid.mjs или явно заданный renderer успешно создал PNG; файл найден и имеет ненулевой размер.
• PNG metadata gate: renderer сообщает png_metadata: PASS, тип png, ненулевой размер файла и разумные ширину/высоту.
• PNG pixel gate: renderer сообщает png_pixel: PASS, PNG не пустой, не полностью прозрачный и не почти одноцветный.
• Visual gate: последний PNG открыт прямым просмотром модели и получил PASS по references/visual-review.md.
• Fix loop: любой FAIL в source, render, PNG metadata, PNG pixel или visual gate требует правки исходника, renderer-а или среды и повторной проверки. Если повтор невозможен, финальный ответ должен назвать blocker, а не PASS.

Delivery

Сдавай кратко: что создано или исправлено, где лежат .mmd/.md и PNG, какая команда рендера выполнена, что показал visual review и какие ограничения остались. Не пересказывай внутренние references.