Skip to main content
Glama

三十秒

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,每次写入都会收到 lint 报告,修复它弄坏的东西,对图进行布局,并在 http://127.0.0.1:7710 打开它。从此以后,这个文件就是地图:之后的每个会话在读取代码之前都会先读取它。

需要 Node 20.19+ 或 22.12+。npm install 会获取所有内容(约 100 MB,不安装全局包);npm run build 编译一次查看器。如果你只需要 MCP 工具,可以跳过构建——除了 dgv_open 之外,没有它一切都能工作。

Related MCP server: arch7

它是什么

一个文件。 dgv/<name>.dgv.json 保存帧(边界)、节点(组件)和边(连接)。每个节点都有一个来自固定目录的 kind——ui、service、api、db、queue、bridge、external……——并且可以声明 ports。每条边都指明它落地的端口以及它使用的 protocol。纯 JSON,放在你的仓库里,就在它所描述的代码旁边。

两种接入方式。 MCP server 是代理的:它创建、修改和读取文件,每次写入都会得到一份 lint 报告——一个稳定的代码、相关元素和具体的修复。viewer 是你的:一个 Svelte Flow 画布,kind 有形状,连线携带它们的 protocol,每个字段都有检查器,同样的 lint 实时显示在侧边栏。当代理更改文件时,页面会重新加载。

为什么当 AI 编写代码时这很重要

绘图是最不重要的部分。重要的是系统的模型是一个程序可以读取、检查和更改的文件。

如果你 vibecode,系统增长的速度会超过你脑子里能记住的速度,而你以为它有的形状会偏离它实际的形状。DGV 给这个形状一个安身之处,并提供一个 linter,当它不再合理时提出异议。

如果你身边有 AI 一起开发,图就是你在代码还无法表达意图时陈述意图的地方——worker 消费队列;API 从不直接写入 bucket——只需一次,以每个后续会话都会继承的形式。

如果你是代理,这就是 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 端点。两百个 token 取代了对代码树的浏览。

它做什么——四种场景

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" ] }, … ] }

查看器中的同一份报告——失败的连线是红色的,每个条目都会跳转到它的元素:

第一个错误是一个本来会变成 bug 的拼写错误。第二个是代理会不假思索就实现的架构。两者都以 id、code 和 fix 的形式返回,因此在任何代码存在之前计划就被修复了:

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 · 绘制你已经拥有的系统

把代理指向一个仓库——从代码出发,用 DGV 绘制 Cerveau 的架构——它会读取入口点、监听器、客户端和配置,然后写出它发现的内容。下面的本地 AI harness 是四个边界中的 13 个组件:一个面板和一个手机驱动一个 Go 核心、一个 llama.cpp 服务器、Typesense 用于记忆、一个 Python 嵌入 sidecar。

完整尺寸——Cerveau 本身,7 个边界中的 35 个组件,每次调用都绑定到一个声明的端口:

按下 S,每个帧折叠成一个节点,穿过它的连线合并成一条带标签的链接。同一个文件;没有第二个概览图需要与第一个保持同步:

3 · 在同一张图上跟踪构建

节点可以携带 status——todo wip done blocked failed update。按下 2,画布按状态而不是 kind 着色;这个文件现在就是构建看板。代理通过读取仍然 todo 的内容来从上次会话停止的地方继续,而阻塞节点上的 note 说明了原因:

4 · 知道它何时不再为真

Lint 能说明计划是连贯的。它不能说明计划是真的——即磁盘上的代码仍然是图所描述的代码。给节点一个 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,没有被任何人认领,因为 MCP 节点的 path 只是一个文件。扩大之后,就干净了。

两个可选的 Claude Code hooks 形成闭环(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 中的每张图都是这样制作的。

A / double-click

添加节点,选择其种类

从节点右侧手柄拖出

连接;拖放到端口芯片上可将边绑定到该端口

G

将所选内容包裹到新框架中

1 / 2

按种类着色 / 按状态着色

L

连线样式:浮动、路由、直线

S

将所有框架折叠为一个节点;再次按下可展开。悬停单个框架可只折叠该框架

Shift+S

将屏幕上的内容保存为 SVG

F 适应 · I 检查器 · P 问题 · Esc 关闭 · Del 删除 · Ctrl+S 保存 · Ctrl+Z 撤销

折叠视图在浏览器中为每个图保留各自的排列,绝不会写入文件。

参考

tool

作用

dgv_catalog

节点种类(形状与含义)、边种类、协议和状态——每个会话读取一次

dgv_list

目录中的图,附带计数

dgv_read

读取一张图:mode: "summary"(上面的概要,默认)或 mode: "json"

dgv_create

新建一张空图

dgv_apply

按 id 更新或插入框架、节点和边;按 id 删除;放置新节点;返回 lint 报告。部分更新:要更改现有元素上的一个字段,发送其 id 和该字段即可

dgv_lint

诊断信息:code、severity、subject、fixes

dgv_drift

图是否仍然描述代码?每个 path 必须存在,每个代码目录必须属于某个节点

dgv_layout

dagre 布局,TB 或 LR;覆盖位置

dgv_open

如果查看器未运行则启动它,并打开该图

dgv_export

markdown(表格)、mermaid、summary(概要)或 svg

图会保存到代理启动时所在目录下的 ./dgv 中;设置 DGV_DIR 可将它们放到其他位置。

先检查形状(schema/invalid),再检查引用(ref/missing-node、ref/missing-frame、ref/duplicate-id),然后检查下面的规则。错误会阻止 ok;警告和信息只是建议。

错误 —— 继续之前先修复。

code

触发条件

port/undeclared

边命名了节点未声明的端口

port/protocol-mismatch

边的协议不是该端口的协议

port/direction

边进入 out 端口,或从 in 端口离开

graph/import-cycle

模块循环相互导入

frame/nested

框架带有 parent —— 框架不能嵌套;单层结构让折叠、布局和文件保持简单

警告 —— 计划很可能有漏洞。

code

触发条件

port/unbound

目标声明了端口,但调用边没有命名任何端口

contract/unspecified

不同种类之间的边既没有协议也没有标签

kind/store-initiates

数据库、缓存或存储桶是调用的来源

kind/import-across-programs

导入跨越框架边界——两个进程无法共享同一个导入

kind/api-unused

没有任何东西调用的 API

kind/bridge-one-sided

只与少于两个其他节点相连的桥接节点

graph/orphan

没有边的节点

layout/overlap, layout/outside-frame

卡片重叠,或位于其框架之外——dgv_layout 可修复两者

信息 —— 值得一看,计数中不显示: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。边省略 kind 时会根据协议推断——sql redis s3 fs smb 对应 data,kafka nats amqp mqtt sse ws 对应 async,否则为 sync。位置会被保存,因此你排好的布局会一直保持。完整种类目录——所有种类、协议和 lint 代码——见 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>

path

说明

packages/core

纯 ESM,无 DOM:catalog、schema、lint、dagre 布局、正交连线路由器、折叠、导出、drift、文件存储

packages/mcp

dgv CLI、MCP 服务器,以及查看器背后的本地 HTTP/SSE 服务器

packages/viewer

Svelte 5 + Svelte Flow:带形状的节点、框架、折叠、检查器、实时问题

skill/

一个教授工作流程的 Claude Code 技能(SKILL.md)

hooks/

用于 Claude Code 的 SessionStart 和 Stop 钩子

dgv/

本仓库自己的图,已通过 drift 检查

examples/

notes-app · notes-app-broken · shop-platform · local-ai-harness

npm test —— core:schema、lint 规则、补丁语义、布局包含、折叠、导出、SVG、drift。

限制

DGV 不解析你的源代码。Lint 能告诉你计划是否连贯;drift 能告诉你每个节点仍然指向存在的代码,并且每个代码目录都有对应的节点。但两者都无法告诉你图中绘制的调用就是代码实际发出的调用——这仍然需要人来阅读,或由代理来阅读,而文件存放在仓库中正是让这种阅读可被审查的原因。

这里不包含:协作或托管、时序图和生命周期图、仓库结构发现。格式带有版本号(dgv: 1),因此这些功能可以在不破坏现有文件的情况下添加。

来源

Cerveau 是一个本地优先的代理式编码工具。它的 docs 文件夹中保存着一份名为 arch-viewer 的私有草稿:一个 Svelte Flow 画布,读取其架构的 Diagram.json——99 个节点、127 条边,节点带有种类,边带有标签。除了浏览器之外没有任何东西能读取它,所以负责构建的代理从未看到过它。DGV 保留了画布、框架和布局,并在底层放置了一份契约:种类目录、端口和协议、声明的成员关系、linter,以及一个 MCP,让代理读写同一个文件。archify 提供了带可修复诊断的类型化中间表示这一思路。

MIT © Mounir Belahbib

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Generates Excalidraw architecture diagrams with support for 60+ components including GCP, Kafka, and AI/Agentic shapes. Provides MCP tools for creating, modifying, and converting diagrams from structured input or Mermaid syntax.
      4
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP agents to validate architecture descriptions and scaffold complete, interactive React Flow diagram applications with multiple visual dialects, themes, exports, and verification probes.
      4
      Apache 2.0