PR Lens

Рисует изменения кода как анимированные SVG-диаграммы архитектуры и потоков данных.

Метаданные навыка

Справочник: полный SKILL.md

Навык PR Lens

PR Lens рисует код в виде насыщенных анимированных диаграмм: диффы, архитектура, потоки данных. Вы описываете дифф или кодовую базу одним JSON-документом (дорожки, узлы, рёбра, упорядоченные потоки), а CLI рендерит его в анимированные SVG. Линзы «находок» нет — PR Lens помогает понять код, а не ревьюит его. Поля для бага, риска или замечания по безопасности не существует; документ, который такое поле придумывает, отклоняется.

Когда использовать

• Просят нарисовать диаграмму, визуализировать или объяснить изменение кода или систему.
• Pull request должен нести диаграмму архитектуры или потока данных.
• Ключевые слова: PR Lens, diagram, architecture, data flow, visualise, pull request.

Требования

• Node.js с npx (CLI запускается через npx @coldtea/pr-lens-cli@latest; шага установки нет).
• gh (GitHub CLI) — необязательно, только чтобы прикреплять диаграммы к PR.
• Необязательная публикация на канвас обращается к стороннему сервису prlens.dev (см. шаг 4b).

Как запускать

Все команды выполняйте инструментом terminal из корня репозитория.

1. Прочитайте дифф. Если нужно отобразить изменение кода: git diff --find-renames <base>...<head>. База — это merge base, а не вершина базовой ветки. Если дифф не нужен, прочитайте код, который предстоит визуализировать.

2. Напишите документ в .pr-lens/graph.json, следуя references/graph-document.md. references/example.graph.json — валидный образец с тремя дорожками, всеми четырьмя состояниями delta, hero-ребром, потоком из семи шагов, вложенным деревом детализации и walkthrough из шести шагов. Прочитайте его перед тем, как писать первый документ, — это быстрее, чем читать справочник.

3. Провалидируйте и исправьте.

   npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json

   Исправьте каждую ошибку и запустите снова. Не рендерите невалидный документ; не «обходите» ошибку удалением элемента, который она называет.

4. Отрендерите.

   npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light

   По умолчанию рендерите светлую тему, если пользователь не просит другую. SVG, манифест и drawn.graph.json попадают в .pr-lens/, который CLI добавляет в .gitignore репозитория. Ничего из этого не коммитьте — эти файлы пересобираются из диффа по запросу. Каждый SVG назван по своему представлению, теме и хешу содержимого; manifest.json перечисляет их по линзам и представлениям.

4b. Публикация на канвас — НЕОБЯЗАТЕЛЬНО, только по явному согласию. Только когда пользователь прямо просит ссылку, которой можно поделиться. Это публикует .pr-lens/drawn.graph.json на стороннем сервисе prlens.dev:

npx @coldtea/pr-lens-cli@latest canvas push

Команда печатает три ссылки. Пользователю отдайте ссылку для просмотра (https://prlens.dev/c/{id}): полноэкранная диаграмма, все представления на одной странице, без логина. Ссылка для редактирования (оканчивается на #w=…) даёт её владельцу право перезаписать канвас — это секрет: не включайте её в ответ без запроса, никогда не вставляйте в публичные места. Ссылка для встраивания отдаёт верхнее представление как SVG для README. Повторная публикация того же файла обновляет тот же канвас, так что «переименуй вот тот узел» — это: поправить, провалидировать, отрендерить, опубликовать; ссылка остаётся прежней. Если публикация не удалась, скажите об этом и сообщите пользователю, где лежат локальные SVG и какой из них — верхнее представление.

5. Прикрепите к PR, если он есть. В апстриме задокументирован gh pr create/edit/comment --attach <path>, но --attach появился в GitHub CLI 2.99 — сначала проверьте gh --version (например, у gh 2.97 его НЕТ). С gh ≥ 2.99: напишите тело с Markdown-картинкой ![alt](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/pr-lens/.pr-lens/<view>.svg) (HTML-тег <img> остаётся как написан, а файл вместо этого добавляется внизу; alt-текст — подпись в одну строку, которую увидит читатель без картинок), затем повторите --attach <path> для каждой упомянутой диаграммы:

   gh pr create --title "…" --body-file .pr-lens/body.md --attach .pr-lens/overview-light-<hash>.svg

   Без --attach используйте путь без коммитов:

   • Загрузите SVG в gist: gh gist create .pr-lens/<view>.svg, затем сошлитесь на raw-URL gist в теле или комментарии PR, или
   • Опубликуйте через ссылку на канвас (шаг 4b, с согласия пользователя) и дайте ссылку на представление, или
   • Укажите локальный путь .pr-lens/ в теле PR, чтобы ревьюеры могли пересобрать.

   Когда диаграммы опубликованы где-то надолго, пусть CLI соберёт markdown комментария:

   npx @coldtea/pr-lens-cli@latest comment \
     --graph .pr-lens/drawn.graph.json \
     --manifest .pr-lens/manifest.json \
     --asset-base-url <where you published the SVGs>

   --graph принимает drawn.graph.json, а не документ, который вы написали, — CLI отказывается от документа, который его манифест не описывает. Опустите --asset-base-url — и markdown будет указывать на локальные пути, которые никакой читатель не откроет. Markdown уходит в stdout; публиковать его — ваша забота.

   Прикрепляйте те представления, что нужны ревьюеру, остальное оставляйте в .pr-lens/: сначала верхнее архитектурное представление, затем поток данных, если в изменении есть последовательность, за которой стоит проследить. Две диаграммы обычно лучше четырёх.

6. Необязательная автоматизация: npx @coldtea/pr-lens-cli@latest analyze --base <ref> выполняет шаги 1–2, обращаясь к провайдеру (Gemini, OpenAI или любой эндпоинт /chat/completions) с вашим собственным ключом. Это единственный путь здесь, которому нужен ключ; обычно документ вы пишете сами.

Что делает документ достойным чтения

• Включайте то, что не менялось. Нетронутые соседи, которых касается изменение, — это контекст; помечайте их delta: "unchanged".
• Дорожки — это ментальная модель читателя (runtime, уровень, граница), а не дерево папок.
• Одно hero-ребро, максимум два: та связь, о которой изменение на самом деле.
• Добавляйте поток только там, где есть последовательность, которую стоит анимировать. Один хороший поток лучше трёх жидких.
• Прикрепляйте ссылки на файлы: они становятся пермалинками, по которым кликает ревьюер.
• Архитектурные представления — дерево решений в духе C4: контекст системы → контейнер → компонент, каждый потомок заметно уже. Пропускайте пустые или повторяющиеся уровни; представления потоков данных держите отдельными корнями; ставьте defaultOpen: true на самом верхнем полезном архитектурном представлении.
• Walkthrough (2–12 шагов, цельтесь в 3–7): пишите его для всего нетривиального. Каждый шаг = одно изменение (добавлено/удалено/перемещено), главное изменение первым, обзор последним. Заголовки ≤48 символов, собранные из слов об изменении; тексты ≤140 символов о поведении, обязательны. Пишите для смышлёного двенадцатилетнего; никаких «leverages»/«orchestrates». Соседние шаги держите на одной сцене. Поле walkthrough требует CLI ≥ 0.4.0 (контракт 0.1.1).
• Исправление неверной карты: никогда не правьте сгенерированный документ — записывайте поправки в .github/pr-lens.yml (см. references/config.md), затем провалидируйте его: npx @coldtea/pr-lens-cli@latest validate .github/pr-lens.yml. Предпочитайте глобы путей совпадениям по id:.

Краткая справка

Коды ошибок валидатора:

Подводные камни

• Шесть правил проверяет только парсер, в JSON Schema их нет (ссылочная целостность, перевёрнутые диапазоны строк, несогласованные концы self, одинаковые коммиты патча, слишком много представлений для манифеста, фокус шага потока не на той сцене) — всегда запускайте validate, одного структурированного вывода недостаточно.
• Ничего в .pr-lens/ не коммитьте; каталог пересоздаётся и добавлен CLI в gitignore.
• Флагу --attach в gh нужен gh ≥ 2.99; в более старом gh его просто нет, без предупреждения — проверьте, прежде чем строить тело PR вокруг него.
• Ссылка редактирования канваса (#w=…) — это учётные данные на запись: никогда не делитесь ею без запроса и не вставляйте публично.
• Сохранённая карта никогда не несёт walkthrough; walkthrough рассказывает историю одного изменения.
• pr-lens render сообщает о поправках в .github/pr-lens.yml, которые ни с чем не совпали, — это дрейф, который стоит починить, а не ошибка.

Проверка

Smoke-тест (проверен вживую 2026-09-12 с @coldtea/pr-lens-cli через npx, node на Linux):

cp references/example.graph.json ~/.hermes/cache/scratch/prlens-smoke/ && cd ~/.hermes/cache/scratch/prlens-smoke
npx -y @coldtea/pr-lens-cli@latest validate example.graph.json
# ✓ example.graph.json — graph document · 3 lanes, 10 nodes, 13 edges, 1 flow · 6 walkthrough steps
npx -y @coldtea/pr-lens-cli@latest render example.graph.json --theme light
# ✓ .pr-lens/manifest.json — 4 SVGs across 4 diagrams

Ожидайте код выхода 0 в обоих случаях и четыре файла *-light-<hash>.svg плюс manifest.json и drawn.graph.json в .pr-lens/.

Адаптировано из coldteadotai/pr-lens (packages/agent-skill, закреплён 0993b4d), лицензия MIT, Copyright (c) 2026 Coldtea AI. См. LICENSE.txt.