agent-draw

一个以智能体（agent）为先的技术画布。人类负责排列和检视 tldraw 画布；智能体则读取和修补一个与渲染器无关、带版本号的图文档。

Alpha 阶段： 文档边界是经过深思熟虑的；插件 SDK 和兼容性保证仍在演进中。

第一个纵向切片包括：

• 基于 tldraw 的技术画布，包含 API、服务、数据库、表、文件和外部系统块；

• 可检视的表列，以及用于数据库归属、服务读取和外键引用的语义边；

• 自定义 React 节点形状，带有具名输入/输出句柄和带类型、可吸附的连接；

• 规范的 agent-draw/0.1 JSON，包含稳定 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. 从 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 执行、实时数据库检视和其他更丰富的工具保留了类型化的逃生舱口。