Excalidraw Diagram

用 Excalidraw 生成能够“解释问题”的图，而不是把文字机械摆成卡片。

适用场景

当用户要你生成以下内容时使用本 skill：

• 流程图、架构图、协议图、系统关系图
• 把复杂概念可视化
• 需要 .excalidraw 源文件，后续还要继续编辑
• 需要先导出 PNG 预览，再迭代布局与视觉层次

输出要求

默认产出两份文件：

1. *.excalidraw：可继续编辑的源文件
2. *.png：本地渲染预览图

不要只交付 JSON。 生成后必须本地渲染一次，并根据预览修正明显问题。

首次阅读顺序

开始画图前按需读取：

任务	先读什么
所有任务	references/color-palette.md
需要写元素 JSON	references/element-templates.md
不确定 Excalidraw 文件结构	references/json-schema.md
准备渲染和排查布局	references/rendering-workflow.md

核心方法

1. 先判断深度

先决定这张图属于哪一类：

• 概念图：强调关系、层次、因果，不必塞太多技术细节
• 技术图：要展示真实事件名、接口名、请求结构、代码片段、输入输出样例

如果是技术图，先查真实资料，再开画。不要用“Service A → Service B”这种空标签糊弄过去。

2. 结构先行，不要先写样式

先确定这张图真正想表达什么：

• 是顺序？用时间线或分阶段布局
• 是聚合？用汇聚结构
• 是分发？用扇出结构
• 是对比？用左右并列
• 是层级？用树形或分区

形状必须服务含义。 不要默认所有节点都是同尺寸卡片。

3. 默认少容器、多层级文字

不是每段文字都需要矩形包住。默认优先：

• 标题、注释、说明：直接用文字
• 只有需要承载语义或承接箭头时，才加形状
• 同一张图里，尽量让容器节点少于总文本节点的三分之一

4. 技术图必须给“证据”

技术图至少加入一种真实证据：

• 真实事件名
• JSON payload 样例
• API / method 名称
• 关键代码片段
• 真实输入输出格式

这样图本身就能用于教学，而不是只做装饰。

推荐工作流

Step 1：定义视觉论点

先用一句话写清楚这张图想证明什么。

示例：

• “事件流是从 AI agent 单向推送到前端，而不是轮询”
• “系统的复杂度主要集中在中间编排层”
• “用户看到的是单入口，但底层是多阶段处理”

Step 2：列出区块

先把图拆成 3-6 个区块，再决定每块内部怎么画。大图一定要分区写，别一次性生成全部元素。

常见分区方式：

• 按阶段：输入 / 处理 / 输出
• 按角色：用户 / 客户端 / 服务端 / 外部系统
• 按层级：界面层 / 编排层 / 数据层

Step 3：选择视觉模式

按概念选择模式：

概念	建议模式
顺序流程	时间线 / 横向流程
一对多分发	扇出
多对一聚合	汇聚
层级结构	树形 / 分区
对比分析	左右并列
循环反馈	回环箭头

Step 4：生成 .excalidraw

写文件时遵守三条：

1. 使用可读的字符串 ID
2. 大图按区块逐段补元素
3. 坐标和尺寸以可读性优先，不追求“程序算出来”

Step 5：本地渲染并回看

生成 JSON 后，必须执行本地渲染：

uv sync --project {baseDir}/scripts
uv run --project {baseDir}/scripts playwright install chromium
uv run --project {baseDir}/scripts python {baseDir}/scripts/render_excalidraw.py /absolute/path/to/diagram.excalidraw --output /absolute/path/to/diagram.png

然后读取 PNG，检查：

• 文字有没有被裁切
• 箭头是否落在正确对象上
• 重要节点是否足够醒目
• 区块之间是否太挤或太散
• 是否出现大片无意义空白

Step 6：修正后再交付

如果预览里出现以下任何问题，先修再交：

• 文本溢出或重叠
• 箭头穿过不该穿过的内容
• 节点尺寸失衡
• 色彩层次混乱
• 技术图没有真实证据片段

视觉默认值

• 背景：纯白 #FFFFFF
• 线条：干净、克制，默认 roughness: 0
• 强调方式：用尺寸、间距、颜色层级，不用透明度堆效果
• 配色：全部从 references/color-palette.md 取，不临时发明新颜色

安装与依赖

渲染链路依赖 uv 和 Playwright。

推荐安装

brew install uv
uv sync --project {baseDir}/scripts
uv run --project {baseDir}/scripts playwright install chromium

依赖说明

• uv：管理 Python 运行环境
• playwright：驱动无头 Chromium 把 .excalidraw 渲染成 PNG
• 浏览器资源首次安装较慢，属于正常现象

交付格式建议

给用户交付时，尽量同时说明：

• 这张图的核心论点
• 你采用的结构（例如分区、时间线、扇出）
• 如为技术图，指出证据片段在哪一块
• 提供 .excalidraw 与 .png 路径

常见误区

误区 1：所有节点都画成一样的卡片

这样会让图只剩“排版”，没有论证。

误区 2：技术图只写概念，不给实物

如果没有真实事件、接口、数据格式，教学价值会很弱。

误区 3：只看 JSON 不看渲染结果

坐标在 JSON 里看着没问题，不代表视觉上真的成立。

误区 4：把颜色当装饰

颜色应该承担语义分层，而不是随机好看。

最终检查清单

交付前确认：

• 已生成 .excalidraw
• 已渲染 PNG 预览
• 没有明显裁切、重叠、错连
• 结构和论点一致
• 技术图包含真实证据片段
• 使用了统一配色与文字层级