pr-lens-diagrams v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/6ade94574d698a10.

---
name: pr-lens-diagrams
description: "Анимированные диаграммы архитектуры и потоков данных через PR Lens (@coldtea/pr-lens-cli): пишем graph.json руками, валидируем, рендерим анимированный SVG и записываем бесшовный GIF/MP4 для чатов (Telegram). Use when asked to draw a diagram, схему, архитектуру, связи сервисов или ботов, sequence/data-flow, animated diagram. Triggers: pr lens, prlens, диаграмма, схема, нарисуй, architecture diagram, data flow, animated svg, gif."
version: 1.0.0
author: NorD (nordz0r)
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [diagrams, pr-lens, architecture, data-flow, svg, gif]
---

# PR Lens diagrams

English version: [SKILL.en.md](SKILL.en.md).

[PR Lens](https://github.com/coldteadotai/pr-lens) (MIT, сайт https://prlens.dev) превращает JSON-документ графа в самодостаточный **анимированный SVG** без скриптов. Анимация сделана на SMIL `<animateMotion>`. Ключ модели нужен только команде `analyze`, которая строит граф по git diff. Произвольную схему агент пишет сам, ключ для этого не нужен.

## Быстрый старт

```bash
# зависимости: Node >= 20.11, npm, ffmpeg; Chromium ставит setup-скрипт
bash scripts/pr-lens-setup.sh                      # в $PR_LENS_HOME (по умолчанию ~/.cache/pr-lens-diagrams)
bash scripts/pr-lens-build.sh my.graph.json out/   # → out/architecture.{svg,gif,mp4}, out/data-flow.{svg,gif,mp4}
```

Начинайте с копии `examples/bots.graph.json`: в ней 4 колонки, 12 узлов, 12 связей и один поток.

- `pr-lens-build.sh` проверяет документ (`pr-lens validate`), рендерит его в нужной теме (`dark` по умолчанию, `light` третьим аргументом) и записывает кадры через Playwright с `deviceScaleFactor: 2`. Из кадров собираются GIF без дизеринга и MP4 (`crf 18`).
- Переменные окружения: `PR_LENS_HOME`, `FPS` (20), `MIN_WIDTH` (1600), `PR_LENS_CLI_VERSION`, `PLAYWRIGHT_VERSION`.
- `npx skills add coldteadotai/pr-lens` на Node 20 падает: `fs/promises` не экспортирует `glob`. Этот скилл официальный не требует. Справку по установленной версии CLI выдаёт `npx pr-lens skill` и `npx pr-lens skill references`; запускать в `$PR_LENS_HOME`.
- **Не публиковать без явного согласия пользователя.** `pr-lens canvas push` выкладывает схему на prlens.dev, и ссылку на просмотр может открыть любой, у кого она есть.

## Документ (schemaVersion 0.2.0)

Обязательные поля: `schemaVersion`, `kind: "graph"`, `title`, `lenses`, `provenance`, `lanes`, `nodes`. Связи задаются в `edges`, потоки в `flows`.

- `provenance` обязателен даже без репозитория: подойдут условные owner/name и sha из 40 нулей.
- `lanes` — **колонки слева направо** по `order`. «Наверх» узел не поставить: верх схемы — это левая колонка.
- `nodes[].kind`: `service|app|module|function|route|job|queue|datastore|cache|external|ui|config|test|package|other`.
- `edges[].kind`: `call|http|rpc|event|queue|data|dependency|render|other`.
- `edges[].emphasis`: `normal|hero|muted`. `animated: true` запускает бегущую точку.
- `delta` (`added|modified|removed|unchanged`) раскрашивает изменения. Для обычной схемы везде ставим `unchanged`.
- `layout`: `{ "direction": "right", "laneOrder": [...], "rank": { "<node>": N } }`. Это подсказки, не абсолютные координаты.

## Как устроена анимация

1. **Архитектура.** По связи с `animated: true` бежит точка, цикл 1,6 с. Связь с `emphasis: "hero"` получает «поезд» из трёх точек (2,1 с, интервал 0,7 с) и свечение. Узор повторяется через НОК(1,6; 0,7) = **11,2 с**, поэтому петля такой длины бесшовная.
2. **Поток (data-flow).** Нужно `"data-flow"` в `lenses` и `flows[]`: в `participants` id узлов, в `messages` шаги с kind `sync|async|return|self`. Шаги загораются по порядку массива. Длина петли берётся из `dur="…s"` в SVG: для 7 шагов это 9,8 с, максимум 16 с.
3. **Тур (`walkthrough`) и примеры трафика (`payload`)** проигрываются только на канвасе prlens.dev. Локально их нет.
4. Растеризаторы (resvg, cairosvg, rsvg) анимацию не видят и дают статичный PNG. Кадры нужно снимать в браузере: `pauseAnimations()` + `setCurrentTime(t)`, это делает `scripts/record.mjs`.

## Уроки по красоте и качеству

- **Не больше 10–12 узлов и ~12 связей.** Однородные сущности объединяйте в узлы-группы, состав группы перечисляйте в `subtitle` через запятую. 25 узлов и 59 связей превращаются в кашу.
- «Все → X» не рисуйте отдельными связями: напишите это в `subtitle` узла X или заведите один сводный узел.
- **3–4 колонки**, поток слева направо: вход → оркестратор → исполнители → результат. Без пустых и перегруженных колонок.
- **Карточки по одной в ряд.** Если в колонке два узла с одинаковым рангом, PR Lens ставит их парой, карточки сужаются и подписи обрезаются многоточием. Лечится через `layout.rank` с отдельным рангом для каждого узла колонки.
  - Ранг — это «пол»: узел не встанет выше того, кто в него ведёт (ранг ≥ ранг источника + 1). Поэтому ранги задаём лесенкой 0, 1, 2, 3…
  - Ряды общие для всех колонок. Связанным узлам соседних колонок давайте один ранг, тогда связь пойдёт прямо.
- **Подписи короткие:** на узкой карточке subtitle до ~20 символов, на широкой до ~45.
- **`hero` только для 1–2 главных путей.** Редкие связи делайте `muted`. Подписи у очевидных связей (оркестратор → группа) не нужны.
- **Ширина data-flow** растёт примерно на 320 px за участника. 6 участников ≈ 1940 px, больше будет мелко. Держите до 6–7 участников.
- **Тема:** по умолчанию `dark` на фоне `#0d1117`, в чатах тёмные схемы читаются лучше.
- **Запись:** `deviceScaleFactor: 2`, ширина CSS не меньше ширины viewBox и не меньше 1600 px, 20 fps.
- **GIF:** `palettegen=max_colors=128:stats_mode=diff` + `paletteuse=dither=none:diff_mode=rectangle`, масштаб `lanczos` до ширины CSS. Текст получается чистым, 11 с архитектуры весят ≈ 1 МБ. MP4 пишется в полном 2x.
- В Telegram и большинстве чатов SVG-анимация не видна, отправляйте GIF или MP4. В комментарии к GitHub PR анимированный SVG показывается.
- **Перед сдачей проверьте кадры:** вырежьте кусок кадра GIF в натуральном размере и посмотрите глазами. Уменьшенное превью скрывает мутность.
  ```bash
  ffmpeg -i out/architecture.gif -vf "select=eq(n\,60),crop=800:500:0:0" -frames:v 1 check.png
  ```
- Имена SVG в выводе `render` содержат хеш и меняются при каждом рендере. `pr-lens-build.sh` копирует их в стабильные `<lens>.svg`.

## Порядок работы агента

1. Выпишите сущности и сгруппируйте их до 10–12 узлов. Решите, какие 1–2 пути главные (`hero`).
2. Скопируйте `examples/bots.graph.json` и правьте его: `lanes`, `nodes` с `layout.rank` лесенкой, `edges`, при необходимости `flows`.
3. Запустите `bash scripts/pr-lens-build.sh graph.json out/`. Если `validate` назовёт поле с ошибкой, исправьте его.
4. Проверьте кадры: нет обрезанных подписей, пар карточек и пересечений. При необходимости поправьте ранги и подписи.
5. Отдайте пользователю GIF или MP4, исходник `graph.json` и SVG.