tldraw-skill

tldraw 白板图表

概述

生成现代白板风格的图表，保存为 .tldr JSON 文件，并使用 @kitschpatrol/tldraw-cli 导出为 PNG/SVG。tldraw 可生成简洁的手绘风格图表，提供丰富的形状库和平滑的箭头路径，非常适合休闲或白板风格的可视化。

格式： .tldr JSON
导出： PNG、SVG（通过 @kitschpatrol/tldraw-cli）
风格： 默认采用手绘白板风格；可通过 font 属性切换为简洁字体。

适用场景

明确触发词： 用户说“diagram”“flowchart”“draw”“visualize”“whiteboard diagram”“tldraw diagram”“architecture diagram”或“sketch this out”。

主动触发场景：

• 解释包含 3 个或更多相互作用组件的系统
• 描述多步骤流程、数据流或管道
• 展示服务/模块之间的关系
• 架构概览、时序流程、决策树、ML 模型层

以下情况跳过： 简单列表或表格就足够；用户需要精致的商务演示图表（优先使用 drawio-skill）；或者用户正在进行快速问答。

以下情况不适用——改用其他工具：

• Logo／纯色图形／实心图标：tldraw 不支持不透明填充（solid = 浅色调；无法复现深色背景上的白色图形）→ 使用 drawio 技能或原始矢量文件。
• 精确矢量几何图形或严格的（空心箭头）UML → 使用 drawio（或使用 plantuml 绘制 UML）。
• 许多节点的自动布局 → 使用 mermaid（tldraw 需要手动设置坐标）。
• 像素级忠实复刻现有图像 → 这不属于图表技能的任务。

前置条件

# Install tldraw-cli
npm install -g @kitschpatrol/tldraw-cli

# Verify
tldraw --version

在 macOS、Windows 和 Linux 上的操作完全相同。

首次导出说明： tldraw export 通过 puppeteer 使用固定版本的 Chrome 进行渲染。首次导出可能会失败，并提示 Could not find Chrome (ver. <x>)。错误信息会指出所需的确切版本——安装一次后，后续导出即可正常进行：

# The error message names the version; substitute it here
npx puppeteer browsers install chrome@<version-from-error>

（安装到 ~/.cache/puppeteer；每个 CLI 版本只需安装一次。）

工作流

开始前，先评估用户的请求是否足够具体。如果缺少关键信息，请提出 1～3 个有针对性的问题：

• 图表类型——使用哪个预设？（架构图、流程图、时序图、ML/DL、ERD、UML 或通用图表）
• 输出格式——PNG（默认）、SVG？
• 输出位置——默认是用户的工作目录；如果用户明确指定了路径（例如“放到 ./artifacts/”），请遵循。用户未提及时不要询问。
• 范围/保真度——有多少个组件？是否有指定的技术或标签？

如果请求已经说明这些细节，或者显然很简单（例如“绘制 X 的流程图”），则跳过澄清。

1. 检查依赖——确认 tldraw --version 能正常运行；如果缺少，则运行 npm install -g @kitschpatrol/tldraw-cli。
2. 规划——确定形状（每个节点对应的几何类型）、连接（含源节点/目标节点的箭头）和布局（TB 或 LR，按层级/角色分组）。编写 JSON 前先绘制坐标网格草图。
3. 生成——编写 .tldr JSON 文件。默认输出目录是用户的工作目录；如果用户指定了路径或目录（例如 ./artifacts/），先运行 mkdir -p 创建目录，再将文件写入该目录。步骤 4 和 7 导出 PNG/SVG 时也使用同一目录。
4. 导出草稿——运行 CLI，生成 PNG 以供预览。
5. 自检——使用 Agent 内置的视觉能力查看导出的 PNG，发现明显问题后自动修复，再向用户展示（需要支持视觉功能的模型，例如 Claude Sonnet/Opus）。如果无法使用视觉功能，则跳过此步骤。
6. 审核循环——向用户展示图像，收集反馈，针对性地修改 JSON，重新导出并重复此流程，直到用户批准。
7. 最终导出——将获批版本导出为所有要求的格式；报告 .tldr 源文件和导出图像的文件路径。

步骤 5：自检

导出草稿 PNG 后，使用 Agent 的视觉能力（例如 Claude 的图像输入）读取图像，并在展示给用户前检查以下问题。如果 Agent 不支持视觉能力，请跳过自检，直接展示 PNG。

tldraw 自带的 AI Agent 会准确标出三种结构缺陷——文本溢出（框太小，放不下标签）、文本重叠和孤立箭头（箭头有一端未绑定）。下表前三行针对这些问题；提前正确设置框的大小（参见“调整框大小以适应标签”），就很少会出现这些问题。

检查项	检查内容	自动修复操作
文本溢出	标签超出形状边框，或框看起来比设定的更高（tldraw 会自动增大尺寸不足的框）	增大 w/h 以适应标签——参见下方的尺寸公式
文本重叠	两个带文本形状的标签接触或重叠，影响可读性	将形状间距拉开 ≥200px
孤立箭头	箭头有一端未连接到形状（悬空）	绑定两端：每个箭头的 start 和 end 都需要一个与现有形状匹配的 boundShapeId
画布外形状	形状位于负坐标处或远离主要分组	将其移到分组附近的正坐标处
箭头与形状重叠	箭头在视觉上穿过了无关形状	调整 bend 值，或将端点移到不同的 normalizedAnchor 边
箭头堆叠	多个箭头在同一路径上相互重叠	将 normalizedAnchor 分散到形状周边（使用不同的 x/y 值）

• 最多进行 2 轮自检——修复 2 次后如果问题仍然存在，也请展示给用户。
• 每次修复后重新导出，并重新读取新 PNG。

步骤 6：审核循环

自检后，展示导出的图像并征求用户反馈。

定向编辑规则——针对每类反馈，应用最小限度的 JSON 更改：

用户请求	JSON 编辑操作
更改 X 的颜色	查找 props.text 与 X 匹配的形状，更新 props.color
添加新节点	追加一个使用下一个可用索引的新形状记录，并放置在相关节点附近
删除节点	删除该形状记录以及所有绑定到它的箭头记录
移动形状 X	更新该形状的 x/y 字段
调整形状 X 的大小	更新 props.w/props.h
添加从 A 指向 B 的箭头	追加一个绑定到 A 和 B 的形状 ID 的新箭头记录
更改标签文本	更新匹配形状或箭头上的 props.text
更改布局方向	完全重新生成——重新规划网格并重建

规则：

• 对于单个元素的更改：直接编辑现有 JSON——保留前几轮迭代的布局调整。
• 对于整个布局的更改（例如，切换 LR↔TB、“重新开始”）：重新生成完整 JSON。
• 每轮迭代都覆盖同一个 {name}.png——不要创建 v1、v2、v3 文件。
• 应用编辑后，重新导出并展示更新后的图像。
• 持续循环，直到用户表示已批准／完成／LGTM。
• **安全措施：**迭代 5 轮后，建议用户在 tldraw.com 或桌面应用中打开 .tldr 文件，以进行精细调整。

---

文件格式

完整的 .tldr 骨架

{
  "tldrawFileFormatVersion": 1,
  "schema": {
    "schemaVersion": 1,
    "storeVersion": 4,
    "recordVersions": {
      "asset": {"version": 1, "subTypeKey": "type", "subTypeVersions": {"image": 2, "video": 2, "bookmark": 0}},
      "camera": {"version": 1},
      "document": {"version": 2},
      "instance": {"version": 17},
      "instance_page_state": {"version": 3},
      "page": {"version": 1},
      "shape": {"version": 3, "subTypeKey": "type", "subTypeVersions": {"group": 0, "embed": 4, "bookmark": 1, "image": 2, "text": 1, "draw": 1, "geo": 7, "line": 0, "note": 4, "frame": 0, "arrow": 1, "highlight": 0, "video": 1}},
      "instance_presence": {"version": 4},
      "pointer": {"version": 1}
    }
  },
  "records": [
    {"id": "document:document", "typeName": "document", "gridSize": 10, "name": "", "meta": {}},
    {"id": "page:page1", "typeName": "page", "name": "Page 1", "index": "a1", "meta": {}}
    /* shapes and arrows go here */
  ]
}

关键规则：

• document:document 和 page:page1 记录始终必需。
• 所有形状都放在页面记录之后的 records 数组中。
• 所有形状的 "parentId": "page:page1"。
• 形状 ID 使用 "shape:xxx" 格式，并带有唯一后缀（例如，"shape:s1"、"shape:a1"）。
• index 值是分数索引键。使用 "a" 加 一个 base-62 字符，并按以下顺序排列："a0"–"a9"，然后是 "aA"–"aZ"，再然后是 "aa"–"az"（62 个有序键，足以满足任何常规图表的需要）。
• 不要追加第二个字符："a10" 无效。 也不要使用以 "b"/"c" 开头的键（"b1"、"c1"、"b0"）——这些键编码了更长的整数部分，因此是格式错误的分数键，会触发 invalidRecords。请使用上面单字符的 "a*" 键。

---

几何形状记录

{
  "id": "shape:s1",
  "typeName": "shape",
  "type": "geo",
  "parentId": "page:page1",
  "index": "a1",
  "x": 100,
  "y": 100,
  "rotation": 0,
  "isLocked": false,
  "opacity": 1,
  "meta": {},
  "props": {
    "w": 180,
    "h": 60,
    "geo": "rectangle",
    "color": "blue",
    "labelColor": "black",
    "fill": "semi",
    "dash": "draw",
    "size": "m",
    "font": "draw",
    "text": "API Gateway",
    "align": "middle",
    "verticalAlign": "middle",
    "growY": 0,
    "url": ""
  }
}

几何类型

geo 值	用途
rectangle	服务、模块、组件
ellipse	数据库、起始/结束节点
oval	药丸形起始/结束终止符（流程图）
diamond	决策点
cloud	外部服务、基础设施
hexagon	事件中心、消息总线
triangle	网关、负载均衡器
star	突出项、关键功能
pentagon	阶段、里程碑
octagon	停止 / 终止 / 阻塞状态
trapezoid	手动操作、转换
rhombus / rhombus-2	平行四边形——I/O 步骤（向左/向右倾斜）
arrow-right / arrow-left / arrow-up / arrow-down	定向流程块、数据移动
x-box	失败 / 无效 / 拒绝状态（带 ✕ 的方框）
check-box	通过 / 已验证 / 完成状态（带 ✓ 的方框）
heart	点缀（技术图表中很少需要）

全部 20 种 geo 值均有效；以上是适用于技术图表的常用子集。

调色板

color	用途
blue	客户端、核心服务
green	成功、数据库、存储
orange	队列、事件总线、警告
red	外部 API、错误、警报
light-red	轻度警报、次要警告
violet	网关、安全、身份验证
yellow	决策、缓存
grey	中性、背景、旧版
light-blue	次要服务、元数据
light-violet	轻度身份验证/安全、次要网关
light-green	轻度成功、次要存储
white	空白/空节点、占位符（搭配 fill: solid 使用）
black	标题、强调

完整调色板（13 种）：black、grey、light-violet、violet、blue、light-blue、yellow、orange、green、light-green、light-red、red、white。

样式选项

属性	值	说明
fill	semi、solid、none、pattern	semi = 淡色填充（推荐）
dash	draw、solid、dashed、dotted	draw = 手绘默认样式
size	s、m、l、xl	m = 默认值
font	draw、sans、serif、mono	draw = 默认白板样式

---

箭头记录

{
  "id": "shape:a1",
  "typeName": "shape",
  "type": "arrow",
  "parentId": "page:page1",
  "index": "aG",
  "x": 0,
  "y": 0,
  "rotation": 0,
  "isLocked": false,
  "opacity": 1,
  "meta": {},
  "props": {
    "dash": "draw",
    "size": "m",
    "fill": "none",
    "color": "black",
    "labelColor": "black",
    "bend": 0,
    "start": {
      "type": "binding",
      "boundShapeId": "shape:s1",
      "normalizedAnchor": {"x": 0.5, "y": 1},
      "isExact": false
    },
    "end": {
      "type": "binding",
      "boundShapeId": "shape:s2",
      "normalizedAnchor": {"x": 0.5, "y": 0},
      "isExact": false
    },
    "arrowheadStart": "none",
    "arrowheadEnd": "arrow",
    "text": "",
    "font": "draw"
  }
}

箭头连接规则

• 箭头记录的 x 和 y 始终为 0, 0。
• 使用 "type": "binding" 和 boundShapeId 连接到特定形状。
• normalizedAnchor 指定箭头在目标形状上的连接位置（范围为 0–1）：
  • {x: 0.5, y: 0} = 顶部中心
  • {x: 0.5, y: 1} = 底部中心
  • {x: 0, y: 0.5} = 左侧中心
  • {x: 1, y: 0.5} = 右侧中心
  • {x: 0.5, y: 0.5} = 中心
• 在箭头属性中添加 "text": "label"，为连接添加标签。
• 使用 "bend": 20（或 -20）绘制轻微弯曲的箭头，以避免与其他箭头重叠。
• 对于虚线/点线箭头（例如异步流程、可选链接），设置 "dash": "dashed" 或 "dotted"。
• 设置 "spline": "cubic" 绘制平滑的曲线箭头（默认的 "line" 为直线/折线）。适用于跳过连接和回边。

箭头

arrowheadStart 和 arrowheadEnd 均可接受以下 9 个值（在 @kitschpatrol/tldraw-cli 中都会正常渲染）：

值	外观	用途
none	（无箭头）	单向箭头的起点
arrow	开口 V 形	默认流向
triangle	实心 ▶	UML 继承／“是……的一种”
diamond	实心 ◆	UML 组合／聚合（位于所有者一端）
dot	●	序列图的消息端点
square	■	终端／固定端点
bar	|	“停止”／边界标记
pipe	||	备选边界标记
inverted	空心 V 形	弱化方向的强调

默认箭头使用 "arrowheadStart": "none"、"arrowheadEnd": "arrow"。要设置双向链接，请将两端都设为 "arrow"。

在形状上分散箭头

多个箭头连接到同一形状时，分配不同的 normalizedAnchor 点，以避免堆叠：

位置	x	y	使用场景
顶部中心	0.5	0	连接上方节点
左上	0.25	0	来自顶部的第 2 个连接
右上	0.75	0	来自顶部的第 3 个连接
右侧中心	1	0.5	连接右侧节点
底部中心	0.5	1	连接下方节点
左侧中心	0	0.5	连接左侧节点

**规则：**如果形状的一侧有 N 个连接，应均匀分布（例如，底部有 3 个连接 → x = 0.25、0.5、0.75）。

同一对节点之间的多个箭头

上述锚点分布规则适用于连接到不同节点的箭头。当 N 个箭头连接同一对节点时（例如，双向请求／响应，或 A↔B 之间的多个关系），锚点无法将它们分开；应改为对称地分配 bend 值，让箭头展开为不同的弧线：

• 选择一个最大弯曲 amount（≈ 30–60；节点距离越远，数值越大）。
• 将 N 个箭头的弯曲值均匀分布在 −amount 到 +amount 之间：
  • 2 个箭头 → bend: -amount、bend: +amount
  • 3 个箭头 → bend: -amount、0、+amount
  • 通用公式：bend[i] = -amount + i * (2*amount / (N-1))，其中 i = 0..N-1
• 对请求／响应箭头对而言，一条直箭头加一条弯曲箭头（bend: 0 和 bend: 40）清晰易读。

---

容器和注释形状

除 geo 和 arrow 外，还有两种形状类型适用于技术图表。

Frame（带标签的容器——层级、子系统、泳道）

frame 是带标题的原生矩形容器。可用它将某个层级或子系统归组并显示边界；堆叠多个 frame 可模拟泳道。

{
  "id": "shape:frame1", "typeName": "shape", "type": "frame",
  "parentId": "page:page1", "index": "a1",
  "x": 60, "y": 60, "rotation": 0, "isLocked": false, "opacity": 1, "meta": {},
  "props": { "w": 360, "h": 220, "name": "Backend Tier", "color": "black" }
}

• props.name 是显示在 frame 左上角的标题。
• 子形状设置 "parentId": "shape:frame1"（而非 page:page1），其 x／y 坐标相对于 frame 的左上角，而非页面。子形状位于 x: 40, y: 60 时，表示从 frame 的原点向右 40px、向下 60px。
• Frame 会渲染为简洁的（非手绘）矩形，适合用于结构分组。箭头仍可正常跨 frame 绑定。

Note（便签注释／标注）

note 是便签，适合用于在图表上叠加 TODO、标注和评论。

{
  "id": "shape:n1", "typeName": "shape", "type": "note",
  "parentId": "page:page1", "index": "a4",
  "x": 480, "y": 80, "rotation": 0, "isLocked": false, "opacity": 1, "meta": {},
  "props": { "color": "yellow", "size": "m", "text": "TODO: add retry\nlogic here",
    "font": "draw", "align": "middle", "verticalAlign": "middle",
    "growY": 0, "fontSizeAdjustment": 0, "url": "", "scale": 1, "labelColor": "black" }
}

• Note 没有 w／h，它是固定大小的正方形（约 200px），文本较长时会自动增大。不要添加 w／h。
• yellow 是经典便签颜色；调色板中的任何颜色都可使用。
• 少量使用 note——用于添加关于图表的注释，而非作为主要节点（主要节点请使用 geo）。

---

索引排序规则

索引控制 z 轴顺序（堆叠顺序）。按以下顺序排列：

a1, a2, a3, a4, a5, a6, a7, a8, a9,
aA, aB, aC, aD, aE, aF, aG, aH, aI, aJ, aK, aL, aM,
aN, aO, aP, aQ, aR, aS, aT, aU, aV, aW, aX, aY, aZ,
aa, ab, ac, ... az          ← continue here past aZ; never "a10"

• Geo 形状在前：从 a1 到 aF（或按需添加）。
• Arrow 形状在后：aG、aH 等。
• 每个形状的索引必须唯一。

---

布局提示

间距——根据复杂度调整：

图表复杂度	节点数	水平间距	垂直间距
简单	≤5	200px	150px
中等	6–10	280px	200px
复杂	>10	350px	250px

调整方框尺寸以适应标签（提前完成，不要留到自检时）： draw 字体较宽。根据标签计算 w/h，避免文本被截断。默认 draw 字体的每字符宽度和行高近似值：

size	字符宽度（px）	行高（px）
s	11	18
m（默认）	15	28
l	22	40
xl	32	56

每边的 padding = 16：

• w = ceil(最长行字符数 * 字符宽度 + 2*padding)，然后向上取整到下一个 10 的倍数。
• h = ceil(行数 * 行高 + 2*padding)，然后向上取整到 10 的倍数。

示例：标签为 "API Gateway" 的 size-m 方框（11 个字符，1 行）→ w ≈ 11*15 + 32 = 197 → 200，h ≈ 28 + 32 = 60。多行标签（含 \n）的 w 按最长一行计算，h 按行数计算。尺寸略大一些没关系——多余的留白看起来不错，而方框太窄会在单词中间强制换行。

为何重要：如果方框高度不足以容纳文本，tldraw 会在渲染时悄悄将其增高（设置图形的 growY），因此方框最终会比你填写的 h 更大，并与下方放置的元素重叠。提前正确设置尺寸可让 growY 保持为 0，从而维持布局。这是导出后“图表显得拥挤／方框重叠”最常见的原因。

**连线路径：**在形状行／列之间额外留出约 80px 的空白通道，供箭头通过，避免穿过其他形状。不要在箭头需要经过的间隙中放置形状。

**网格对齐：**将所有 x、y、w、h 值对齐到 10 的倍数——这与 tldraw 的默认 gridSize: 10 一致，也便于手动编辑。

通用规则：

• 先规划网格，再分配 x/y 坐标——首先在脑中勾勒节点位置。
• 将相关节点分组放置在同一水平或垂直带。
• 将连接较多的“枢纽”节点放在中央，让箭头向外辐射，而不是彼此交叉。
• 对于较宽的形状（例如跨越多个下游服务的 API Gateway），将 w 设为覆盖整个范围。
• 将子节点居中放在父节点下方（中心 x 相同），避免斜向连线。
• 事件总线模式：将总线（六边形）放在服务行的中央，而不是下方——两侧的服务通过较短的水平箭头连接到它（左侧使用 normalizedAnchor.x = 1，右侧使用 0），从而避免交叉。
• 同一行中的水平连线不会穿过垂直节点；可用于对等连接和发布连接。

避免箭头与形状重叠：

• 确定坐标前，在脑中描绘每条箭头的路径——如果箭头必须穿过无关形状，就移动该形状，或使用 bend 绕开。
• 对于树形／分层布局：将节点分配到各层（行），只连接相邻层，以尽量减少交叉。
• 对于星形／枢纽布局：将枢纽放在中心，卫星节点围绕它排列——箭头保持短而呈放射状。

---

图表类型预设

当用户请求特定类型的图表时，请应用下方匹配的预设来设置形状、颜色和布局惯例。

架构图

元素	geo	color	说明
客户端（Web/移动端）	rectangle	blue	顶部一行，按客户端类型标注
服务 / 模块	rectangle	blue	中间各行，按层级分组
数据库	ellipse	green	底部，每个服务一个
缓存	ellipse	yellow	放在所属服务旁边
队列 / 事件总线	hexagon	orange	枢纽模式下位于服务行中央
网关 / 负载均衡器	triangle	violet	服务上方
外部 API	cloud	red	画布边缘，使用虚线箭头指向内部
身份验证 / 安全	rectangle	violet	通常靠近网关

布局： 根据层级数量选择 TB 或 LR；层级数 ≥4 时使用 TB。枢纽节点居中。间距随复杂度调整（见上表）。

流程图

元素	geo	color	说明
开始 / 结束	ellipse	green	始终位于顶部和底部
处理步骤	rectangle	blue	默认的操作框
判定	diamond	yellow	始终为出向箭头添加标签（是 / 否）
输入 / 输出	rectangle（带 dash: dashed）	orange	用虚线边框与处理步骤区分
子流程	rectangle	violet	表示可调用的子流程

布局： 使用 TB，垂直间距约为 200px。判定分支向左 / 右延伸，然后汇合回中央。始终在箭头的 props.text 中标注判定分支。

时序图

tldraw 没有原生生命线形状。可使用以下方式近似表示：

元素	geo	color	说明
参与者 / 对象标题	rectangle	blue	位于列顶部
生命线	rectangle（w: 2、fill: solid、color: grey）	grey	每个参与者标题下方的细竖线
同步消息	带 arrowheadEnd: arrow 的箭头	black	实线水平箭头
异步消息	带 dash: dashed 的箭头	black	虚线水平箭头
返回消息	带 dash: dashed、color: grey 的箭头	grey	灰色虚线

布局： 参与者按 LR 排列（间距 200–280px），时间按 TB 排列。每条消息都是两条生命线之间的水平箭头，y 值逐渐增加。

机器学习 / 深度学习模型图

用于神经网络架构图，适合论文插图和说明图。

元素	geo	color	说明
输入 / 输出	rectangle	green	位于堆栈顶部和底部
卷积 / 池化	rectangle	blue	标准层模块
注意力 / Transformer	rectangle	violet	为自注意力模块使用区别明显的颜色
RNN / LSTM / GRU	rectangle	yellow	循环层
全连接 / 线性层	rectangle	orange	稠密投影层
损失 / 激活	rectangle	red	最终损失 / softmax / 激活
跳跃连接	带 bend: 30、dash: dashed 的箭头	grey	弯曲的虚线旁路

张量形状标注： 在 props.text 中用第二行注明维度。tldraw 会在 JSON 字符串中按原样渲染 \n，因此请使用实际换行符（JSON 编码器会写入 \n）：

"text": "Conv2D\n(B, 64, 32, 32)"

布局： 使用 TB（数据从上 → 下流动），层间距约为 150px。跳跃连接沿主堆栈弯曲绕行。

ER 图（ERD）

tldraw 不提供原生的表格／行形状。可用高矩形和多行文本近似表示每个实体。

元素	geo	color	备注
实体	rectangle（fill: solid，color: light-blue）	light-blue	将标题和列作为一个多行文本标签
列表	嵌入 props.text，各行之间用 \n 分隔	—	用 * 前缀标记 PK，用 > 标记 FK
关系	箭头，arrowheadStart: arrow，arrowheadEnd: arrow	black	多对多关系的两端都使用箭头
可选／弱关系	箭头，dash: dashed	grey	可选 FK 使用虚线

通过 props.text 为箭头标注基数（例如 1..*、0..1）。

**布局：**采用 TB 或网格布局；实体间距至少为 300px，为列清单留出空间。

UML 类图

元素	geo	color	备注
类	rectangle（fill: solid，color: light-blue）	light-blue	将标题、属性和方法作为一个多行 text
继承	箭头，arrowheadEnd: triangle	black	tldraw 会渲染实心的 triangle 箭头；箭头指向父类
组合	箭头，arrowheadStart: diamond，arrowheadEnd: none	black	tldraw 会渲染实心的 diamond 箭头；将其放在所有者（整体）端
聚合	箭头，arrowheadStart: diamond	black	使用相同的菱形箭头；通过标签或备注与组合区分
关联	箭头，arrowheadEnd: arrow	black	标准箭头

注意：tldraw 的 triangle／diamond 箭头是实心的，而严格的 UML 使用空心三角形（继承）以及实心或空心菱形（组合／聚合）。这些形状适用于草图和说明图；若要绘制带空心箭头的出版级 UML，drawio-skill（独立技能）更合适。

**布局：**采用 TB 布局，类间距约为 250px，接口位于实现类上方。

---

导出命令

# Check CLI version
tldraw --version

# PNG at 2x scale (recommended) — outputs diagram.png in ./
tldraw export diagram.tldr -f png --scale 2 -o ./

# SVG — outputs diagram.svg in ./
tldraw export diagram.tldr -f svg -o ./

# Transparent background
tldraw export diagram.tldr -f png --scale 2 --transparent -o ./

# Dark theme
tldraw export diagram.tldr -f png --scale 2 --dark -o ./

# Custom output directory (e.g. CI artifacts dir) — create if missing, then export there
mkdir -p ./artifacts && tldraw export diagram.tldr -f png --scale 2 -o ./artifacts/

注意：-o 是输出目录，而非文件路径。输出文件以输入文件命名（diagram.tldr → diagram.png）。

导出后自动启动

提供选项，将 .tldr 文件在用户的默认 tldraw 查看器／编辑器中打开：

操作系统	命令
macOS	open diagram.tldr
Linux	xdg-open diagram.tldr
Windows	start diagram.tldr

或者上传到 https://tldraw.com（拖放 .tldr 文件）以在浏览器中编辑。

---

常见错误

错误	修复方法
找不到 tldraw 命令	运行 npm install -g @kitschpatrol/tldraw-cli
导出时出现 Could not find Chrome (ver. X)	安装指定版本的构建：npx puppeteer browsers install chrome@X（使用错误信息中的确切版本）
导出时出现 invalidRecords	使用单字符 a 键（a1…a9、aA…aZ、aa…az）；a10、b1、c1 是格式错误的分数索引键
导出结果为空	确认存在 document:document 和 page:page1 记录
找不到输出文件	-o 指定的是目录；文件名与输入文件一致：tldraw export foo.tldr -o ./ → ./foo.png
箭头未显示	使用 "type": "binding" 和 boundShapeId；将箭头的 x/y 设为 0,0
形状重叠	分配 x/y 前，先规划间距至少为 200px 的网格；根据复杂程度调整间距
方框比预期更高／与下方内容重叠	标签超出尺寸过小的方框，导致 tldraw 自动增高方框（growY）。请预先使用尺寸计算公式，根据标签设置 w/h
文本不可见	检查是否设置了 props.text；如果 fill: "none"，请确保文本颜色有足够的对比度
索引冲突	所有形状都必须使用唯一的 index 值
形状 ID 冲突	使用唯一 ID："shape:s1"、"shape:s2"、"shape:a1" 等
导出失败	确保 .tldr 文件是有效的 JSON：python3 -m json.tool file.tldr > /dev/null
多行标签	在 JSON 字符串中使用实际换行符（"text": "Line1\nLine2"）；tldraw 会正确处理 \n
箭头穿过形状	使用 bend 绕开形状弯曲，或将端点移至不同的 normalizedAnchor
迭代循环始终无法结束	迭代 5 轮后，建议用户在 tldraw.com 中打开 .tldr 进行微调

---

备用方案

工具不可用时，请采取适当的降级方案：

场景	处理方式
缺少 tldraw-cli	仅生成 .tldr JSON；告知用户将其拖放到 https://tldraw.com，或安装 CLI
无法使用视觉功能进行自检	跳过自检（步骤 5）；直接向用户展示导出的 PNG
导出失败	使用 python3 -m json.tool 验证 JSON；提供 .tldr 文件，并建议用户在 tldraw.com 中打开