agent-canvas

Agent Canvas

用于与 Excalidraw 画布交互，以创建图表和可视化内容的 CLI 工具。

安装

使用前，请检查是否已安装 CLI：

which agent-canvas && agent-canvas --version

• 如果尚未安装：询问用户偏好使用哪种包管理器（bun 或 npm），然后安装：

  bun add -g @agent-canvas/[email protected]
  # or
  npm install -g @agent-canvas/[email protected]
  

• 如果已安装，但版本与 0.13.0 不同：使用相同的包管理器升级：

  • 路径包含 .bun → bun add -g @agent-canvas/[email protected]
  • 否则 → npm install -g @agent-canvas/[email protected]

• 安装/升级后：运行 agent-canvas --version 验证，确认版本为 0.13.0

快速开始

1. 启动画布（在浏览器中打开）：

   agent-canvas start &
   

2. 使用 CLI 命令在画布上绘图。

端口配置

默认端口：39820（WebSocket）、39821（HTTP）。如果端口冲突，可通过以下方式配置：

agent-canvas config set port 39820         # Set WebSocket port
agent-canvas config set http-port 39821    # Set HTTP port
agent-canvas config list                   # Show all config (value + source)
agent-canvas config get port               # Show current port
agent-canvas config reset port             # Reset to default

配置将保存到 ~/.agent-canvas/config.json。也可在运行 start 时进行一次性覆盖：

agent-canvas start --port 8000 --http-port 8001 &

优先级：--port 标志 > 环境变量 AGENT_CANVAS_WS_PORT > 配置文件 > 默认值。

命令参考

启动画布

agent-canvas start &                  # Start server in the background (will close automatically when no action for a while)

加载文件

agent-canvas load file.excalidraw     # Load .excalidraw file into current canvas

从文件加载时：记住文件路径，并使用 agent-canvas save <original-file> 保存回该文件。

画布管理

画布支持多个画布。每个画布独立存储，并且可以在画布之间切换。

agent-canvas list                     # List all canvases ([U]=User active, [A]=Agent active, [F]=Folder)
agent-canvas new -n "Name" [--use]    # Create new canvas, optionally switch to it
agent-canvas use "Name"               # Switch to canvas by name
agent-canvas rename "New Name"        # Rename current canvas

文件夹管理 — 将画布整理到文件夹中：

agent-canvas create-folder -n "Name"              # Create a new folder
agent-canvas delete-folder "Name"                  # Delete folder (canvases become ungrouped)
agent-canvas move-to-folder "Canvas" "Folder"      # Move canvas into a folder
agent-canvas move-to-folder "Canvas" --ungrouped   # Remove canvas from its folder

注意：

• 画布名称不区分大小写，且必须唯一
• 通过 UI 删除画布（将鼠标悬停在侧边栏中的画布上，然后点击“...”菜单）
• 每个画布都有自己的场景数据；切换画布时会自动保存当前画布
• 删除文件夹不会删除其中的画布——这些画布会变为未分组状态

添加文本

agent-canvas add-text -t "<text>" --ax <x> --ay <y> [options]

• 选项：--font-size <size>、--text-align <left|center|right>、-a/--anchor <anchor>、--stroke-color <hex>、-n/--note <text>

• 字号：S=16、M=20（默认）、L=28、XL=36

• 锚点（-a）：由于文本大小要到渲染后才能确定，锚点可指定文本边界框的哪个点与（--ax、--ay）对齐，从而精确控制位置。默认值：bottomLeft。

  锚点	常见文本类型
  topLeft	徽章、标签、图标标签
  topCenter	副标题、形状下方的描述
  topRight	时间戳、版本、状态
  leftCenter	侧边注释（形状右侧）
  center	居中标题、主要标签
  rightCenter	侧边注释（形状左侧）
  bottomLeft	脚注、备注
  bottomCenter	标题、形状上方的页眉
  bottomRight	脚注、签名

• 返回：Text created (id: <id>, x: <x>, y: <y>, <width>x<height>) — 实际左上角位置和尺寸，便于精确布局

添加绘图元素

所有绘图命令都支持以下通用样式选项：

• 描边：--stroke-color <hex>（默认值：#1e1e1e）、--stroke-width <1-4>（默认值：2）、--stroke-style <solid|dashed|dotted>（默认值：solid）
• 填充（仅限形状）：--background-color <hex>（默认值：透明）、--fill-style <solid|hachure|cross-hatch>（默认值：solid）
• 元数据：-n/--note <text> — 元素的语义描述。请尽量使用——备注有助于日后回看时理解图表意图。
• 动画：--animated — 自动滚动视口以显示新添加的元素。小元素会放大显示，大元素会缩小显示，普通元素只会轻微滚动。

推荐颜色（来自 Excalidraw 调色板）：

颜色	描边（深色）	背景（浅色）
红色	#e03131	#ffc9c9
蓝色	#1971c2	#a5d8ff
绿色	#2f9e44	#b2f2bb
黄色	#f08c00	#ffec99
青色	#0c8599	#99e9f2
紫罗兰色	#6741d9	#b197fc
灰色	#495057	#dee2e6

形状

agent-canvas add-shape -t <type> -x <x> -y <y> [-w <width>] [-h <height>] [-l <label>]

• 类型：rectangle、ellipse、diamond
• 使用 -l/--label 在形状内添加文本（默认 fontSize: 16），使用 --label-font-size <n> 调整字号
• 默认情况下，标签颜色继承自 --stroke-color；使用 --label-stroke-color <hex> 覆盖
• 返回：Shape created (id: <id> x=<x> y=<y> w=<width> h=<height>) — 为标签自动调整大小后的实际尺寸

⚠️ 标签尺寸 — 至关重要：绘制前先计算

如果形状尺寸过小，Excalidraw 会自动扩展形状，导致箭头坐标错位。你必须：

1. 使用以下公式计算最小尺寸
2. 直接使用计算结果 — 切勿估算或使用更小的值

Step 1: Calculate text dimensions (fontSize=16 by default)
  textWidth = charCount × fontSize × 0.6  (English/numbers)
  textWidth = charCount × fontSize        (CJK characters)
  textHeight = lineCount × fontSize × 1.35

Step 2: Calculate minimum shape size (use these values, not smaller!)
  rectangle: width = textWidth + 50,  height = textHeight + 50
  ellipse:   width = textWidth × 1.42 + 55,  height = textHeight × 1.42 + 55
  diamond:   width = textWidth × 2 + 60,  height = textHeight × 2 + 60

示例：在椭圆中添加标签“Message Queue”（13 个字符）

textWidth = 13 × 16 × 0.6 = 124.8
textHeight = 1 × 16 × 1.35 = 21.6
ellipse width = 124.8 × 1.42 + 55 = 232
ellipse height = 21.6 × 1.42 + 55 = 86
→ Use: -w 232 -h 86 (or round up to -w 240 -h 90)

提示：对于较长的标签，可手动插入 \n，然后根据更新后的 lineCount 重新计算。

线条和箭头

agent-canvas add-line -x <x1> -y <y1> --end-x <x2> --end-y <y2>
agent-canvas add-arrow -x <x1> -y <y1> --end-x <x2> --end-y <y2>

• 箭头专用选项：--start-arrowhead、--end-arrowhead（arrow、bar、dot、triangle、diamond、none）

箭头类型（--arrow-type）：

类型	说明	用途
sharp	直线（默认）	直接连接
round	带控制点的曲线	自然流向、避免重叠
elbow	直角转弯（90°）	流程图、电路图

中间点（--via）： 使用 --via 以 "x1,y1;x2,y2;..." 格式指定绝对坐标的中间点：

# Round arrow: one control point determines curve direction
# Vertical arrow curving left (control point at x=50, left of the line)
agent-canvas add-arrow -x 100 -y 100 --end-x 100 --end-y 300 --arrow-type round --via "50,200"

# Elbow arrow: multiple points for 90° turns
# Loop back pattern: down → left → up (for flowchart iterations)
agent-canvas add-arrow -x 175 -y 520 --end-x 175 --end-y 280 --arrow-type elbow --via "120,520;120,280"

提示：

• 对于 round：曲线朝控制点弯曲（控制点偏离直线路径）
• 对于 elbow：各点定义 90° 路径的拐角

多边形

agent-canvas add-polygon -p '[{"x":0,"y":0},{"x":100,"y":0},{"x":50,"y":100}]'

图像

agent-canvas add-image -f <path> -x <x> -y <y> [-w <width>] [-h <height>] [-n <note>]

• 支持的格式：PNG、JPEG、GIF、SVG、WebP
• 宽度和高度默认采用原始图像尺寸；指定其中一个即可按比例缩放
• 图像数据以 base64 格式嵌入画布（存储在浏览器的 IndexedDB 中）
• 返回：Image added (id: <id>, x: <x>, y: <y>, <width>x<height>)

操作元素

agent-canvas delete-elements -i <id1>,<id2>,...
agent-canvas rotate-elements -i <id1>,<id2>,... -a <degrees>
agent-canvas move-elements -i <id1>,<id2>,... --delta-x <dx> --delta-y <dy>
agent-canvas resize-elements -i <id1>,<id2>,... [--top <n>] [--bottom <n>] [--left <n>] [--right <n>]
agent-canvas group-elements -i <id1>,<id2>,...
agent-canvas ungroup-element -i <id>

调整元素大小（resize-elements）： 扩展或收缩元素边缘（rectangle、ellipse、diamond、image）。数值采用元素的局部坐标系（考虑旋转）。

示例：

# Expand bottom edge by 50px (increase height)
agent-canvas resize-elements -i abc123 --bottom 50

# Expand both right and bottom (like dragging bottom-right corner)
agent-canvas resize-elements -i abc123 --right 50 --bottom 30

# Contract left edge by 20px (decrease width)
agent-canvas resize-elements -i abc123 --left -20

# Expand all sides uniformly
agent-canvas resize-elements -i abc123 --top 25 --bottom 25 --left 25 --right 25

读取场景

agent-canvas read                # TOON format (compact, ~7% of JSON size)
agent-canvas read --with-style   # Include stroke/bg colors
agent-canvas read --json         # Raw Excalidraw scene JSON

TOON 输出结构：

shapes[N]{id,type,x,y,w,h,angle,labelId,note}       # rectangle, ellipse, diamond, polygon
lines[N]{id,type,x,y,endX,endY,via,angle,note}      # line, arrow
labels[N]{id,containerId,content,x,y,w,h}           # text bound to shapes (via labelId)
texts[N]{id,content,x,y,w,h,angle,note}              # standalone text elements
groups[N]{id,elementIds}                             # element groupings

• 形状中的 labelId 指向标签中的 id
• via 以与 --via 输入相同的格式显示中间点（"x1,y1;x2,y2"；如果没有，则为 null）
• --with-style 会添加 stroke、bg 字段
• --json 返回完整的 Excalidraw 格式（配合 jq 查询特定元素）

保存、导出和清除

agent-canvas save file.excalidraw
agent-canvas export -o out.png [--scale 2] [--dark] [--no-background]
agent-canvas clear                # Clear all elements from the canvas, use with caution!

注意：运行 clear 前，询问用户是否要先保存或导出当前画布。 ⚠️始终优先使用 agent-canvas new，而不是 agent-canvas clear；仅在用户确认后才使用 clear！⚠️

设计理念

你是一个完美主义者。只要看起来有一点不对，就确实不对。请修正。

核心原则：一致性体现含义。

• 相同关系 → 相同对齐方式和间距

  • 关系相同的元素应采用完全相同的对齐方式
  • 同一层级元素之间的间距应始终相等
  • 对齐网格（例如，以 10px 为单位）以确保精确

• 相同类型 → 相同颜色和尺寸

  • 同类型节点的尺寸应完全一致
  • 相同颜色 = 相同含义；最多使用 3–4 种颜色；少即是多
  • 重要元素 = 更大的尺寸

• 细节很重要

  • 箭头应精准连接到形状边缘
  • 通过 export 检查并修正任何不完美之处

操作指南

1. 坐标：原点（0,0）位于左上角。X→右，Y→下。颜色使用十六进制格式（#FF5733）或 transparent。

2. 工作流：读取画布 → 规划布局 → 绘制形状 → 添加箭头/线条（如有必要）→ 调整。

   • 重要：画布内容会自动保存到浏览器的 localStorage。绘制前务必先运行 agent-canvas read，检查是否已有内容。
   • 如果存在旧内容，询问用户是要：（a）继续编辑，（b）清空并重新开始，还是（c）先保存/导出，然后清空。
   • 形状定义布局并提供精确坐标
   • 箭头端点取决于形状的位置——先画箭头会导致对齐不准
   • 调整：完成初稿后，运行 read 和 export 进行检查。根据设计理念检查：
     • 对齐有问题？→ 使用 move-elements 吸附到网格
     • 间距不一致？→ 使用 move-elements 均匀调整间距
     • 元素重叠？→ 使用 move-elements，或使用 delete-elements 删除后重新绘制
     • 尺寸不正确？→ 使用 delete-elements 删除后重新绘制
     • 箭头未对齐？→ 使用 delete-elements 删除后使用正确端点重新绘制
     • 容器尺寸有问题？→ 使用 resize-elements 调整到合适尺寸

3. 渐进式画布读取：

   • read - 从这里开始。紧凑的 TOON 格式（约为 JSON 大小的 7%）
   • read --with-style - 需要设置样式时，添加颜色信息
   • export -o canvas.png + 查看图像 - 用于视觉/空间理解
   • read --json | jq '.elements[] | select(.id=="<id>")' - 查询特定元素的详细信息

4. 批量命令：使用 && 串联以提高效率。绘图命令中不要写 Bash 注释

   agent-canvas add-shape -t rectangle -x 100 -y 100 -l "A" && \
   agent-canvas add-shape -t rectangle -x 300 -y 100 -l "B" && \
   agent-canvas add-arrow -x 220 -y 130 --end-x 300 --end-y 130
   

绘图教程

绘图前，先确定图表类型并查看教程：

1. 确定用户需要的图表类型（流程图、架构图、思维导图、UI 模型图等）
2. 阅读 references/REFERENCE.md — 这是教程索引，列出了所有可用的图表教程
3. 如果存在匹配的教程：绘图前先阅读对应教程——教程包含特定类型的规则、布局模式和最佳实践
4. 绘图时遵循教程指南