tldraw终于把基于AI的无限画布方案开源出来了

tldraw终于把基于AI的无限画布方案开源出来了

中文 (Chinese) English

如昨天消息预告的一样等待tldraw放大招了，tldraw没让大家多等待，把全套可以基于AI的解决方案放出来了。

在官网上，tldraw称之为Starter kits，包括workflow, chat, agent, branching chat, multiplayer。

对应github上五个项目，我把它们集中到了一起，统称为flow。目的是为了整合进自己目前的各项目中。

自从与gemini-2.0共同发布的tldraw compute发布以来，已经过去了九个月时间，昨天“预告”里也说了：9个月等于恍若隔世了。

Gemini 2.0加持下的最佳AI应用已经出现，还完全免费

我一直认为这套解决方案藏着AI超级助手在脱离“显示交互”前的终极形态，如今tldraw终于更新了，还进行了更细的分类和交互优化。当然，如何整合，就是用户的工作了。

我让codex进行了完整的项目分析，分析报告留在最后。

先只做一个案例的展示，一段录屏可能可以非常好的解释，为什么我认为这里藏着终极钥匙。

以下是使用codex一键生成的项目分析：从内容到所有架构图，最终输出一篇docx文档（上面那张模版全景图也属于它）。就是一句提示词而已。Claude Code正式下岗。

Flow 模板全景

Flow 模板全景

1. 项目集总体概览

定位：flow 根目录下收录了 5 套以 tldraw 生态为核心的前端/全栈模板，覆盖 AI 白板代理、可视化对话、同步服务、白板增强聊天与工作流编排等场景。

共同特性：均采用 React 生态，强调 tldraw 的自定义 shape、工具链与 Cloudflare Workers、Vercel AI SDK 等第三方集成功能。

差异化：从轻量前端模版（workflow-template）到含 Durable Object 与 R2 持久化的重型实时系统（tldraw-sync-cloudflare），复杂度层次分明，便于按需选型。

目录结构：各模板独立维护依赖与构建配置，可单独运行。docs/diagrams 下为本文生成的架构配图，scripts/generate_diagrams.py 可复现。

2. agent-template —— AI 代理驱动的画布自动化

agent-template 架构

agent-template 架构

2.1 项目概述

目标：构建能够理解画布上下文、规划操作并执行的 AI Agent，用户通过右侧对话面板驱动代理操作 tldraw 画布。

技术栈：Vite + React + tldraw 前端，Cloudflare Worker + Durable Object 后端，AI 侧接入 OpenAI / Anthropic / Google（三方可选）。

核心思想：前端只负责交互与状态同步，将能力拆分成「能看到什么」与「能做什么」两大列表，通过 shared 目录统一配置，可扩展、可裁剪。

2.2 关键代码结构

  • client/App.tsx：装配 、初始化代理、注册工具、自定义 UI。
  • client/agent/TldrawAgent.ts：封装代理生命周期、消息循环，提供 prompt/cancel/reset 等接口。
  • shared/AgentUtils.ts：汇总 PROMPT_PART_UTILS 与 AGENT_ACTION_UTILS，是扩展视野/动作的核心入口。
  • shared/parts/*：面向模型的上下文拼装，如 ScreenshotPartUtil、TodoListPartUtil 等。
  • shared/actions/*：具体动作实现，例如 PenActionUtil 绘制笔迹、StackActionUtil 处理批量排布。
  • worker/worker.ts：使用 itty-router 暴露 /stream SSE 接口，负责跨域与预检。
  • worker/do/AgentDurableObject.ts：Durable Object 负责与模型交互，保证同一用户会话状态一致。
  • worker/do/AgentService.ts：封装 Vercel AI SDK 的 streamText，统一抽象多模型配置、事件流拆解。

2.3 运行流程

  1. 用户在前端触发对话或操作，TldrawAgent 根据当前画布状态构造 AgentPrompt。
  2. Prompt 通过 /stream POST 到 Cloudflare Worker，Worker 将请求转发至 Durable Object。
  3. Durable Object 调用 AgentService.stream，利用 buildSystemPrompt 与 buildMessages 拼装上下文。
  4. streamText 返回逐步构造的 JSON 片段，closeAndParseJson 尝试补全，构成流式 AgentAction。
  5. 动作事件通过 SSE 回到前端，TldrawAgent 根据类型执行（创建/移动/批量操作/外部查询等）。

2.4 开发与扩展建议

  • 新增感知能力：在 shared/parts 新建 util 并注册到 PROMPT_PART_UTILS。
  • 新增动作：定义 Zod schema、实现 AgentActionUtil 子类，放入 AGENT_ACTION_UTILS。
  • 调整模型：在 worker/models.ts 声明新模型 id，更新 wrangler.toml 注入 API Key。
  • 外部 API：参考 CountryInfoActionUtil、RandomWikipediaArticleActionUtil 定义业务集成。
  • 避免 JSON 崩溃：动作返回需满足 { actions: [{ _type: string, ...}] } 规范，可借助 UnknownActionUtil 容错。

2.5 运维要点

  • SSE 长连接需配置 Cache-Control: no-transform，防止代理缓存。
  • Durable Object 以名称 anonymous 进行聚合，可根据用户身份拆分房间。
  • 大模型调用应限制返回 token（模板默认 8192），并针对 Gemini 配置 thinkingBudget。

3. branching-chat-template —— 可视化分支对话工作台

branching-chat-template 数据流

branching-chat-template 数据流

3.1 项目概述

定位：在无限画布上构建「对话节点」和「连接线」，形成可视化的分支会话树，适合聊天机器人设计、互动小说等场景。

技术栈：前端使用 tldraw 自定义 shape、binding、toolbar；后端为 Cloudflare Worker + Durable Object；AI 服务通过 Vercel AI SDK（默认 Google Gemini）。

亮点：

  • 自定义节点渲染 MessageNode，支持流式响应填充。
  • 连接系统 ConnectionShapeUtil + ConnectionBindingUtil 保证线条层级与绑定寿命。
  • PointingPort 扩展 select tool，实现端口拖拽建连。

3.2 核心模块

  • client/App.tsx：注入自定义 toolbar、注册 shape/binding，并在 onMount 钩子里添加工具状态。
  • client/nodes/types/MessageNode.tsx：定义消息节点结构、AI 回调逻辑、动态高度计算。
  • client/connection/keepConnectionsAtBottom.tsx：监听事件把连接保持在底层，避免遮挡。
  • client/ports/PointingPort.tsx：把端口交互注册到 tldraw 状态机，支持「拖出连线」「点击新增节点」。
  • worker/routes/stream.ts：Worker 将请求转发到 Durable Object，并升级为 SSE。
  • worker/do.ts：Durable Object 管理分支上下文、调用 AI 并流式回传。

3.3 对话构建与推理流程

  1. 用户在画布添加/连接节点，每个节点保留消息文本与 AI 回复区。
  2. 发送消息时，前端根据连接关系回溯路径，合成完整对话历史，打包发送给 Worker。
  3. Durable Object 接管会话状态，调用 Vercel AI SDK，按片段推送至前端。
  4. 前端流式补全节点内容，节点完成后可以继续演化为多个分支。

3.4 开发注意事项

  • 自定义节点需在 nodeTypes.tsx 注册，包含 Component、getPorts、getDefaultProps 等。
  • 连接线为独立 shape，需要正确设置 parentId 和 meta 保持画布层次。
  • Durable Object 可通过 room id 划分多会话；当前模板使用默认 DO 实例，可扩展持久化。
  • 流式错误处理：SSE 返回 error 字段时需在前端妥善提示。

3.5 可扩展方向

  • 增加节点类型：例如条件分支、变量节点、插图节点。
  • 存储导出：将节点与连线序列化为 JSON，支持下载/导入。
  • 协作增强：结合 tldraw-sync-cloudflare 的同步能力，实现多人同时编辑对话树。

4. chat-template —— 聊天 + 白板协同体验

chat-template 交互流程

chat-template 交互流程

4.1 项目概述

定位：Next.js 模板，提供常规聊天界面与嵌入式白板模态框，用户可随时进入 tldraw 绘制草图并回填到聊天流。

技术栈：Next.js（App Router）+ Vercel AI SDK + tldraw；默认调用 @ai-sdk/google 的 Gemini 2.5 Flash 模型。

核心交互：

  • useChat Hook 管理消息队列，实现输入、流式响应、加载态。
  • WhiteboardModal 调用 editor.toImageDataUrl 将白板快照插入聊天。
  • API Route src/app/api/chat/route.ts 负责服务端推理与 SSE 响应。

4.2 关键文件说明

  • src/app/page.tsx：初始化聊天界面，组合 Chat 组件。
  • src/components/Chat.tsx：整合消息列表、输入框、白板开关。
  • src/components/WhiteboardModal.tsx：处理白板编辑、文件注入、toast 提示。
  • src/app/api/chat/route.ts：调用 streamText，并限制响应时长 60 秒。

4.3 请求流程

  1. 用户发送文本或提交白板生成的 PNG；前端将 UIMessage[] 传给 API。
  2. API route 将历史消息转换为模型格式，附加系统提示词，调用 Gemini。
  3. streamText 返回流式内容，通过 Next.js Response 直接推到客户端。
  4. 前端 useChat Hook 接收流式片段，更新消息列表，保持光标与滚动状态。

4.4 修改与扩展

  • 替换模型：调整 google('gemini-2.5-flash') 为其他 provider，例如 openai('gpt-4o-mini')。
  • 白板再编辑：WhiteboardModal 保存 TLEditorSnapshot，可在历史消息中再次打开并修改。
  • 多模态增强：利用 notifyIfFileNotAllowed 控制图片上传类型，支持截图、拍照等输入渠道。

5. tldraw-sync-cloudflare —— 生产级实时同步后端

tldraw-sync-cloudflare 同步架构

tldraw-sync-cloudflare 同步架构

5.1 项目概述

定位：官方给出的生产级 tldraw Sync 服务端实现，基于 Cloudflare Workers、Durable Objects、R2 打造多房间实时协作。

主要能力：

  • 每个白板房间对应一个 Durable Object，处理 WebSocket 消息广播。
  • 定时持久化到 R2 存储，支持自动恢复。
  • 附带资源上传、书签预览 API，使图像/视频和链接可无缝使用。

5.2 核心模块

  • worker/worker.ts：定义 HTTP/WebSocket 路由，入口托管。
  • worker/TldrawDurableObject.ts：实现 TLSocketRoom 接入、心跳、持久化逻辑。
  • worker/assetUploads.ts：提供资源上传/下载，结合 Cloudflare 缓存策略。
  • worker/bookmarkUnfurling.ts：抓取 URL 元数据，供书签形状展示。
  • wrangler.toml：声明 Worker 名称、Durable Object 绑定、R2 桶配置。

5.3 数据流详解

  1. 用户进入房间，前端通过 wrangler 暴露的 /socket 建立 WebSocket。
  2. Worker 将连接分配到对应 Durable Object（按房间 id 哈希），保证单房间单实例。
  3. 客户端操作通过 WebSocket 发送 patch，Durable Object 更新内存文档并广播给所有连线。
  4. DO 周期性（或按变更阈值）将房间状态写入 R2，掉线后可恢复。

5.4 运维与扩展

  • 扩容：Durable Object 自带水平扩展能力；需监测房间并发（约 50 并发/房间经验值）。
  • 安全：assetUploads.ts 需增加鉴权；示例实现偏 Demo，可引入 JWT/签名校验。
  • 监控：结合 Cloudflare Analytics 观察 WebSocket 连接、存储读写费用。

6. workflow-template —— 可执行工作流编辑器

workflow-template 核心组件

workflow-template 核心组件

6.1 项目概述

定位：纯前端模板，演示如何在 tldraw 上实现可执行的「节点-连接-端口」工作流编辑器。

特性亮点：

  • 端口驱动交互：端口点击/拖拽自动创建节点或连接。
  • 数值流动：通过 ExecutionGraph 演示节点值实时计算与异步执行。
  • 自定义 UI：替换默认工具栏，加入画布内节点选择器、工作区包围框等。

6.2 代码结构

  • src/App.tsx：注册自定义 shape、binding、工具栏等，是应用入口。
  • src/nodes/NodeShapeUtil.tsx：定义节点渲染与几何信息，处理端口布局、尺寸计算。
  • src/nodes/types/*：具体节点类型（加减乘除、Slider、条件判断等）。
  • src/execution/ExecutionGraph.tsx：维护工作流拓扑排序、执行状态。

6.3 交互流程

  1. 用户在画布上拖拽创建节点，通过端口连线形成 DAG。
  2. NodeShapeUtil 根据节点配置绘制端口，并响应 hover/click 事件。
  3. 值变化后触发 ExecutionGraph 计算，实时刷新节点显示；点击 play 演示异步执行序列。

6.4 扩展建议

  • 新增节点类型：在 src/nodes/types 创建文件并注册到 nodeTypes、WorkflowToolbar。
  • 增加数据类型：目前以数字为主，可扩展为字符串、对象或 API 调用节点。

7. 文档与图表生成说明

本文档 docs/flow_documentation.md 由手工撰写（中文），引用的所有配图位于 docs/diagrams。

使用 scripts/generate_diagrams.py 可以重新生成 PNG 图表，脚本依赖 Pillow 并采用系统字体 STHeiti 以保证中文显示。

8. 建议的后续工作

  • 统一依赖管理：可引入 pnpm workspace 管理多项目依赖。
  • 自动化部署示例：为 Cloudflare / Vercel 配置 CI 脚本。
  • 多语言国际化：在前端引入 i18n 模块。

本白皮书内容和图表均为离线生成，可直接使用 pandoc 转换为 PDF/Docx。示例命令：

pandoc docs/flow_documentation.md \ --from markdown \ --to docx \ --output docs/flow_documentation.docx \ --resource-path=docs

← Back to Blog