agent-draw

에이전트 우선 기술 캔버스. 인간은 tldraw 캔버스를 배치하고 검사합니다. 에이전트는 렌더러 독립적인 버전 관리 그래프 문서를 읽고 패치합니다.

알파: 문서 경계는 의도적입니다. 플러그인 SDK와 호환성 보장은 아직 진화 중입니다.

첫 번째 수직 슬라이스에는 다음이 포함됩니다:

• API, 서비스, 데이터베이스, 테이블, 파일, 외부 시스템 블록을 갖춘 tldraw 기반 기술 캔버스;

• 검사 가능한 테이블 열과 데이터베이스 소유권, 서비스 읽기, 외래 키 참조를 위한 의미적 엣지;

• 이름 있는 입출력 핸들과 타입이 지정된 스냅 연결을 갖춘 사용자 정의 React 노드 셰이프;

• 안정적인 ID, 의미적 엣지, 이름 있는 뷰, 기능, 전방 호환 가능한 확장을 포함하는 표준 agent-draw/0.1 JSON;

• 낙관적 리비전 검사를 포함하는 agent-draw-patch/0.1 연산;

• 네임스페이스화된 노드 타입과 선언된 기능을 사용한 빌드 타임 플러그인 등록;

• 보호된 로컬 기능 런타임을 통해 HTTP 요청을 편집하고 실행하는 API 인스펙터;

• 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. UI에서 .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. 에이전트 도구를 참조하세요.

보안 모델

다이어그램 파일에는 자격 증명이 아닌 기능 참조만 포함됩니다. 호스트가 기능 부여를 소유합니다. MVP HTTP 런타임은 다음을 수행합니다:

• 명시적 HTTP 메서드만 지원;

• localhost, 사설, 링크-로컬, .local, 포함된 자격 증명, 리디렉션, 비 HTTP 스킴을 차단;

• 입력/본문 크기, 응답 크기, 지속 시간을 제한;

• 사용자가 요청 실행을 누른 후에만 실행.

이는 유용한 기준선이지 프로덕션급 네트워크 샌드박스가 아닙니다. 배포 버전은 실행을 격리하고, 연결 시 DNS를 다시 확인하고, 공간별 허용 목록을 추가하고, 감사 가능한 부여를 저장해야 합니다.

아키텍처

src/model은 소스 오브 트루스입니다. src/canvasAdapter.ts는 tldraw 어댑터입니다. src/plugins에는 매니페스트와 의미적 헬퍼가 포함됩니다. src/runtime은 브라우저 클라이언트이고, server는 신뢰할 수 있는 로컬 기능 런타임입니다.

캔버스는 React Flow의 유용한 상호작용 의미론(보이는 핸들, 호환 가능한 엔드포인트, 타입이 지정된 연결)을 차용하되 두 번째 씬 그래프는 채택하지 않습니다. tldraw는 선택, 카메라, 공간 변환, 렌더링을 담당합니다. 표준 Agent Draw 문서는 노드 ID, 포트, 엣지, 리비전을 소유합니다. UI 제스처는 CLI와 MCP 서버에서 사용하는 것과 동일한 agent-draw-patch/0.1 제안으로 변환됩니다.

플러그인 경계는 선언적 매니페스트, 프런트엔드 표면, 제한된 호스트 기능 사이의 BB의 유용한 분리를 차용합니다. 의도적으로 tldraw 저장소를 플러그인 계약으로 노출하지 않습니다.

구성 가능성 방향

현재 블록은 프로세스 내 TypeScript 플러그인입니다. 의도된 다음 단계는 표준 모델을 약화시키지 않으면서 대부분의 블록을 선언적으로 만드는 것입니다:

1. 블록 스키마: 매니페스트는 필드, 포트, 기본값, 모양, 호환 관계를 선언합니다.

2. 생성된 인스펙터: 호스트는 해당 스키마에서 일반 필드 편집기를 렌더링합니다. 플러그인은 진정으로 특수화된 상호작용에 대해서만 사용자 정의 React 패널을 제공합니다.

3. 임포터와 어댑터: SQL/ORM/OpenAPI/저장소 스캐너는 외부 시스템을 출처가 있는 안정적인 노드와 패치로 변환합니다.

4. 호스트 기능: 블록은 커넥터 또는 시크릿 ID를 참조하고, 신뢰할 수 있는 호스트는 자격 증명을 소유하며 런타임 작업을 승인합니다.

5. 에이전트 도구: MCP는 UI와 동일한 스키마 카탈로그 및 패치 연산을 노출하므로 에이전트가 작성한 다이어그램은 계속 검사하고 검토할 수 있습니다.

이를 통해 일반 블록에는 로우 코드 경로를 제공하면서 API 실행, 실시간 데이터베이스 검사, 기타 더 풍부한 유틸리티를 위한 타입이 지정된 이스케이프 해치는 유지됩니다.