dgv

Тридцать секунд

git clone https://github.com/ShAInyXYZ/Dia-GramV.git && cd Dia-GramV
npm install && npm run build
node packages/mcp/bin/dgv.mjs doctor                        # checks Node + the build, prints the lines below with your path
claude mcp add dgv -s user -- node "$PWD/packages/mcp/bin/dgv.mjs" mcp
ln -s "$PWD/skill" ~/.claude/skills/dgv                     # optional: teaches the agent the workflow

Затем в любом проекте скажите агенту:

Опиши эту систему в DGV, прежде чем мы начнём.

Он читает каталог, записывает dgv/<name>.dgv.json, получает отчёт линтера после каждой записи, исправляет то, что сломал, раскладывает диаграмму и открывает её на http://127.0.0.1:7710. С этого момента файл — это карта: каждая последующая сессия читает его раньше, чем читает код.

Требуется Node 20.19+ или 22.12+. npm install загружает всё (~100 МБ, ничего глобального); npm run build компилирует просмотрщик один раз. Сборку можно пропустить, если вам нужны только MCP-инструменты, — всё работает и без неё, кроме dgv_open.

Related MCP server: mermaid-mcp-server

Что это такое

Один файл. dgv/<name>.dgv.json содержит фреймы (границы), узлы (компоненты) и рёбра (соединения). У каждого узла есть kind из фиксированного каталога — ui, service, api, db, queue, bridge, external… — и он может объявлять порты. Каждое ребро называет порт, на который оно встаёт, и протокол, на котором говорит. Обычный JSON в вашем репозитории, рядом с кодом, который он описывает.

Два способа входа. MCP-сервер — для агента: он создаёт, изменяет и читает файл и при каждой записи получает отчёт линтера — стабильный код, элемент и конкретные исправления. Просмотрщик — ваш: холст Svelte Flow, где kind'ы имеют формы, а провода несут свой протокол, с инспектором для каждого поля и тем же линтером в боковой панели. Когда агент изменяет файл, страница перезагружается.

Почему это важно, когда код пишет ИИ

Рисунок — наименее важная часть. Важно то, что модель системы — это файл, который программа может читать, проверять и изменять.

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

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

Если вы — агент, это разница между grep'ом и знанием. В незнакомом репозитории вы восстанавливаете картину, открывая файлы. dgv_read выдаёт вам картину целиком. Его полный вывод для приложения заметок ниже, дословно:

# Notes app
frames 3 · nodes 6 · edges 5 · updated 2026-08-27

## frame browser: Browser
- web [ui] Notes UI — SvelteKit
## frame server: Server · one process
- api [api] HTTP API — /api/notes ports: rest:http/in
- jobs [worker] Job runner — thumbnails, exports
## frame data: Data
- pg [db] Postgres — notes, users ports: sql:sql/in
- redis [queue] Job queue — Redis lists ports: jobs:redis/in
- s3 [storage] Object store — uploads ports: put:s3/in

## edges
- web-api: web → api [sync http] fetch ports ·→rest
- api-pg: api → pg [data sql] ports ·→sql
- api-redis: api → redis [async redis] enqueue ports ·→jobs
- jobs-redis: jobs → redis [async redis] consume ports ·→jobs
- jobs-s3: jobs → s3 [data s3] ports ·→put

Агент, который может прочитать api → pg [data sql] ·→sql, не выдумает REST-эндпоинт на базе данных. Двести токенов заменяют обход дерева проекта.

Что это даёт — четыре случая

1 · Планируйте до начала разработки и узнавайте, когда план не сработает

Агент описывает небольшое приложение заметок одним вызовом dgv_apply. В нём две обычные ошибки: порт объектного хранилища называется put на узле и upload на ребре, а база данных вызывает API в обратную сторону.

dgv_apply({ name: "notes-app",
  nodes: [ { id: "s3", kind: "storage", label: "Object store", frame: "data",
             ports: [ { id: "put", protocol: "s3", dir: "in" } ] }, … ],
  edges: [ { id: "jobs-s3", source: "jobs", target: "s3", kind: "data", protocol: "s3", targetPort: "upload" },
           { id: "pg-api",  source: "pg",   target: "api", kind: "sync", protocol: "http", label: "notify on change" }, … ] })

Запись проходит, и в том же ходе возвращается отчёт:

{ "ok": false, "lint": { "error": 1, "warning": 2, "info": 0 },
  "diagnostics": [
    { "code": "port/undeclared", "severity": "error",
      "message": "edge \"jobs-s3\" uses target port \"upload\" but node \"s3\" does not declare it",
      "subject": { "type": "edge", "id": "jobs-s3", "field": "targetPort" },
      "fixes": [ "add port {id:\"upload\"} to node \"s3\"", "point the edge at one of: put" ] },
    { "code": "kind/store-initiates", "severity": "warning",
      "message": "\"pg\" is a db; stores do not initiate sync calls to \"api\"",
      "subject": { "type": "edge", "id": "pg-api" },
      "fixes": [ "reverse the edge and mark it kind:\"data\"",
                 "if it is a trigger/CDC stream, add a worker or queue between them" ] }, … ] }

Тот же отчёт в просмотрщике — неисправный провод красный, и каждая запись переходит к своему элементу:

Первая ошибка — опечатка, которая стала бы багом. Вторая — архитектура, которую агент реализовал бы не задумываясь. Обе возвращаются в виде id, кода и исправления, так что план чинится до того, как появится хоть какой-то код:

dgv_apply({ name: "notes-app",
            edges: [ { id: "jobs-s3", targetPort: "put" } ],       // partial: id + the field that changes
            remove: { edges: [ "pg-api" ] } })
→ { "ok": true, "lint": { "error": 0, "warning": 0, "info": 0 } }

2 · Картируйте уже существующую систему

Наведите агента на репозиторий — опиши архитектуру Cerveau в DGV по коду — и он прочитает точки входа, слушатели, клиенты и конфигурацию, а затем запишет то, что нашёл. Локальная ИИ-обвязка ниже — это 13 компонентов в четырёх границах: панель и телефон, управляющие Go-ядром, сервер llama.cpp, Typesense для памяти, Python-сайдкар для эмбеддингов.

В полном размере — сам Cerveau, 35 компонентов в 7 границах, каждый вызов привязан к объявленному порту:

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

3 · Отслеживайте разработку на той же диаграмме

Узел может нести status — todo wip done blocked failed update. Нажмите 2 — и холст раскрашивается по статусу вместо kind; файл теперь — доска разработки. Агент подхватывает с того места, где остановилась прошлая сессия, читая, что ещё todo, а note на заблокированном узле объясняет почему:

4 · Узнавайте, когда она перестаёт быть правдой

Линт говорит, что план согласован. Он не может сказать, что план правдив — что код на диске всё ещё тот код, который описывает диаграмма. Дайте узлу path (файл, каталог, glob, список) — и dgv_drift обойдёт проект (git ls-files, так что .gitignore соблюдается) и сообщит о path, которому ничто не соответствует (drift/missing), о каталоге кода, не принадлежащем ни одному узлу (drift/unclaimed), и о двух узлах, претендующих на один и тот же файл (drift/shared).

Этот репозиторий так поддерживает собственную архитектуру — у каждого узла есть path:

Когда drift запустили на нём впервые, он кое-что нашёл:

$ node packages/mcp/bin/dgv.mjs drift dia-gramv
warning drift/unclaimed  packages/mcp/ — 1 of 5 files belong to no node
        fix: add a node with this path | widen an existing node's path to cover it | add it to meta.driftIgnore if it is not part of the system

packages/mcp/package.json, на который никто не претендовал, потому что path узла MCP был одним файлом. Расширили — и чисто.

Два опциональных хука Claude Code замыкают цикл (hooks/; doctor печатает блок настроек с вашим путём):

• SessionStart печатает в контекст обзор каждой диаграммы в ./dgv вместе со сводкой drift — первое, что узнаёт агент, это форма системы и не устарела ли карта.

• Stop запускает drift после каждого хода и, только когда есть что сказать, оставляет одну строку: DGV · app: 1 node path no longer exists (old). Он никогда не блокирует.

Просмотрщик

node packages/mcp/bin/dgv.mjs serve → http://127.0.0.1:7710 — или dgv_open от агента.

Перетащите узел во фрейм — и он присоединится к нему; фреймы растягиваются под содержимое. Ctrl+Z отменяет. Ctrl+S сохраняет — а если агент изменил файл, пока у вас были несохранённые правки, страница сообщит об этом и даст выбрать. L переключает стиль проводов: плавающий безье, обход вокруг карточек, прямой. Shift+S сохраняет то, что на экране, как самодостаточный SVG — именно так сделана каждая диаграмма в этом README.

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

Справочник

Диаграммы сохраняются в ./dgv в каталоге, из которого был запущен агент; DGV_DIR помещает их в другое место.

Сначала форма (schema/invalid), затем ссылки (ref/missing-node, ref/missing-frame, ref/duplicate-id), затем правила ниже. Ошибки блокируют ok; предупреждения и информация — это советы.

Ошибки — исправьте, прежде чем двигаться дальше.

Предупреждения — в плане, вероятно, есть дыра.

Информация — стоит взглянуть, не учитывается в счётчиках: kind/store-access, kind/module-loose, kind/external-inside, graph/shared-store, layout/unplaced.

Преднамеренное предупреждение получает ack: "<reason>" на своём элементе: оно становится информацией с прикреплённой причиной, и причина путешествует вместе с файлом. Ошибки нельзя подтвердить.

{ "dgv": 1,
  "meta":   { "title": "Notes app", "description": "…", "colorBy": "kind", "edgeStyle": "routed" },
  "frames": [ { "id": "server", "label": "Server · one process", "tone": "amber",
                "position": { "x": 480, "y": 60 }, "size": { "width": 380, "height": 300 } } ],
  "nodes":  [ { "id": "api", "kind": "api", "label": "HTTP API", "sublabel": "/api/notes",
                "frame": "server", "status": "done", "path": "src/api", "position": { "x": 520, "y": 120 },
                "ports": [ { "id": "rest", "protocol": "http", "dir": "in" } ] } ],
  "edges":  [ { "id": "web-api", "source": "web", "target": "api",
                "kind": "sync", "protocol": "http", "targetPort": "rest", "label": "fetch" } ] }

kind обязателен для узла. Для ребра он выводится из протокола, если опущен: data для sql redis s3 fs smb, async для kafka nats amqp mqtt sse ws, в остальных случаях sync. Позиции сохраняются, поэтому ваша раскладка остаётся такой, какой вы её сделали. Полный каталог — каждый вид, протокол и код линтера — в skill/references/format.md.

node packages/mcp/bin/dgv.mjs serve  [--dir d] [--port p] [--no-open]      # viewer, default http://127.0.0.1:7710
node packages/mcp/bin/dgv.mjs lint   <name|file> [--json]
node packages/mcp/bin/dgv.mjs layout <name|file> [--direction TB|LR]
node packages/mcp/bin/dgv.mjs export <name|file> [--format markdown|mermaid|summary|svg]
node packages/mcp/bin/dgv.mjs drift  <name|file> [--root dir] [--json]
node packages/mcp/bin/dgv.mjs list | catalog | doctor | open <name>

npm test — ядро: схема, правила линтера, семантика патчей, вложенность раскладки, свёртывание, экспорт, SVG, drift.

Ограничения

DGV не разбирает ваш исходный код. Линтер может сказать, что план согласован; drift может сказать, что каждый узел по-прежнему указывает на существующий код и у каждого каталога кода есть узел. Ни один из них не может сказать, что вызовы, изображённые на диаграмме, — это вызовы, которые делает код: это по-прежнему читает человек или агент, и именно файл, живущий в репозитории, делает такое чтение проверяемым.

Здесь нет: совместной работы или хостинга, диаграмм последовательности и жизненного цикла, обнаружения структуры репозитория. Формат версионируется (dgv: 1), поэтому всё это можно добавить, не ломая существующие файлы.

Откуда это взялось

Cerveau — это локально-ориентированный агентный каркас для разработки кода. В его папке docs хранился приватный черновик под названием arch-viewer: холст Svelte Flow, читающий Diagram.json его архитектуры — 99 узлов, 127 рёбер, узлы с видом, рёбра с подписью. Прочитать его мог только браузер, поэтому агент, который вёл разработку, никогда его не видел. DGV сохраняет холст, рамки и раскладку и кладёт под них контракт: каталог, порты и протоколы, объявленную принадлежность, линтер и MCP, чтобы агент читал и писал один и тот же файл. archify дал идею типизированного промежуточного представления с исправимой диагностикой.

MIT © Mounir Belahbib