agent-draw

Технический холст, где агенты — на первом месте. Люди размещают и проверяют элементы на холсте tldraw; агенты читают и модифицируют патчами независимый от рендерера версионированный граф-документ.

Alpha: граница документа задана намеренно; SDK плагинов и гарантии совместимости всё ещё развиваются.

Первый вертикальный срез включает:

• технический холст на базе tldraw с блоками API, сервисов, баз данных, таблиц, файлов и внешних систем;

• инспектируемые колонки таблиц и семантические рёбра для владения базами данных, чтений сервисами и ссылок по внешним ключам;

• пользовательские React-узлы с именованными входными и выходными портами и типизированными соединениями с привязкой;

• канонический JSON agent-draw/0.1 со стабильными ID, семантическими рёбрами, именованными представлениями, возможностями и расширениями с прямой совместимостью;

• операции agent-draw-patch/0.1 с оптимистичной проверкой ревизий;

• регистрацию плагинов на этапе сборки с типами узлов в пространствах имён и объявленными возможностями;

• API-инспектор, который редактирует и выполняет HTTP-запросы через защищённую локальную среду выполнения возможностей;

• импорт/экспорт JSON и локальное в браузере постоянное хранение;

• TypeScript CLI и stdio MCP-сервер для чтения, импорта, предложений соединений и оптимистичных патчей, создаваемых агентами.

Запуск

Требования: Node 20+ и pnpm.

pnpm install
pnpm dev

Откройте http://127.0.0.1:4173. Среда выполнения холста слушает только 127.0.0.1:4174, а Vite проксирует /api на неё.

Используйте выбор примеров в шапке страницы или откройте пример напрямую:

• /?sample=system-map

• /?sample=agent-loop

• /?sample=plugin-system

• /?sample=openapi-projects

pnpm test
pnpm typecheck
pnpm build

Related MCP server: tldraw MCP Server

Рабочий процесс агента

1. Экспортируйте документ .agent-draw.json из интерфейса или прочитайте его из проекта.

2. Сохраняйте ID и неизвестные поля extensions.

3. Предпочитайте небольшое предложение agent-draw-patch/0.1 переписыванию всего документа.

4. Установите baseRevision в ревизию исходного документа.

5. Изменяйте семантические поля отдельно от компоновки (setLayout).

6. Проверяйте перед применением. Устаревший патч должен быть пересоздан на основе последней ревизии.

См. пример патча и справочник по формату.

CLI предоставляет те же операции с моделью, что и холст:

pnpm agent-draw validate path/to/map.agent-draw.json
pnpm agent-draw import-openapi openapi.yaml -o map.agent-draw.json
pnpm agent-draw connect map.agent-draw.json \
  --source service-api/calls \
  --target database-projects/query \
  -o connection.agent-draw-patch.json
pnpm agent-draw apply map.agent-draw.json connection.agent-draw-patch.json --write

MCP-сервер

pnpm mcp запускает TypeScript stdio-сервер. Укажите MCP-клиенту на проект и ограничьте его доступ к файлам с помощью AGENT_DRAW_ROOT:

{
  "mcpServers": {
    "agent-draw": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/agent-draw", "mcp"],
      "env": { "AGENT_DRAW_ROOT": "/absolute/path/to/your/project" }
    }
  }
}

Первый набор инструментов намеренно работает на уровне графа: read_document, list_plugins, propose_connection, apply_patch и import_openapi. См. Инструменты агента.

Модель безопасности

Файлы диаграмм содержат ссылки на возможности, но никогда — учётные данные. Хост предоставляет разрешения на возможности. HTTP-среда выполнения MVP:

• поддерживает только явные HTTP-методы;

• блокирует localhost, частные адреса, link-local, .local, встроенные учётные данные, редиректы и не-HTTP схемы;

• ограничивает размер входных данных и тела, размер ответа и длительность;

• выполняется только после того, как человек нажимает Run request.

Это полезный базовый уровень, а не производственная сетевая песочница. В развёрнутой версии также необходимо изолировать выполнение, заново разрешать DNS при подключении, добавлять списки разрешений для каждого пространства и хранить аудируемые разрешения.

Архитектура

src/model — источник истины. src/canvasAdapter.ts — адаптер для tldraw. В src/plugins содержатся манифесты и семантические помощники. src/runtime — браузерный клиент; server — доверенная локальная среда выполнения возможностей.

Холст использует полезную семантику взаимодействий react-flow — видимые порты, совместимые конечные точки и типизированные соединения — не вводя при этом второй граф сцены. tldraw владеет выделением, камерой, пространственными трансформациями и рендерингом. Канонический документ Agent Draw владеет ID узлов, портами, рёбрами и ревизиями. Жест в интерфейсе транслируется в то же предложение agent-draw-patch/0.1, которое используют CLI и MCP-сервер.

Граница плагинов заимствует у BB полезную разделение между декларативным манифестом, фронтенд-поверхностями и ограниченными возможностями хоста. Она намеренно не раскрывает хранилище tldraw как контракт плагинов.

Направление конфигурируемости

Текущие блоки — внутрипроцессные TypeScript-плагины. Следующий цель — сделать большинство блоков декларативными, не ослабляя каноническую модель:

1. Схема блока: манифесты объявляют поля, порты, значения по умолчанию, внешний вид и совместимые отношения.

2. Генерируемый инспектор: хост рендерит обычные редакторы полей на основе этой схемы; плагины предоставляют сложные React-панели только для действительно специализированных взаимодействий.

3. Импортёры и адаптеры: сканеры SQL/ORM/OpenAPI/репозиториев переводят внешние системы в стабильные узлы и патчи с информацией о происхождении.

4. Возможности хоста: блоки ссылаются на идентификаторы коннекторов или секретов, а доверенный хост владеет учётными данными и одобряет действия.

5. Инструменты агентов: MCP предоставляет тот же каталог схем и операции патчей, что и интерфейс, поэтому диаграммы, создаваемые агентами, остаются инспектируемыми и проверяемыми.

Это даёт обычным блокам путь с низким кодом, сохраняя типизированные обходные механизмы для выполнения API, инспектирования живых баз данных и других более расширенных инструментов.