Excalidraw Diagram Skill

“大多数 AI 生成的图表只是‘展示’——一堆方框和箭头。但真正的工程图表应该‘论证’——用视觉语言讲述逻辑故事。”

Excalidraw Diagram Skill 是一个专为编码智能体（如 Claude Code, OpenCode）设计的高级技能。它不仅能根据自然语言描述生成美观的 Excalidraw 图表，更引入了一套视觉论证（Visual Argumentation）的设计哲学。

在这里，图表不再是千篇一律的卡片网格，而是能够清晰表达系统逻辑、数据流向和架构关系的证据性工件。

核心理念：图表即论证

与传统绘图工具不同，Excalidraw Diagram Skill 强调形式追随功能：

• 语义化布局：
  • 一对多关系 → 自动采用**扇出（Fan-out）**结构，直观展示分发逻辑。
  • 时间序列 → 自动排列为时间线，清晰呈现事件顺序。
  • 数据聚合 → 自动使用**汇聚（Convergence）**形态，体现收集与处理过程。
• 拒绝通用模板：没有固定的“三列式”或“金字塔”模板。每个形状、每组元素都镜像了它所代表的概念本身。

四大核心亮点

1. 证据性工件 (Evidentiary Artifacts)

这不仅仅是示意图，更是可执行的文档。

• 真实内容：技术图表中会自动嵌入真实的代码片段、实际的 JSON 负载示例、具体的 API 端点。
• 所见即所得：图表本身就是系统设计的一部分，可直接用于开发参考或技术评审。

2. 内置视觉验证闭环 (Built-in Visual Verification)

这是该技能最强大的功能。它引入了一个基于 Playwright 的渲染管道，让智能体能够“看见”自己的作品：

• 自我审查：智能体生成 JSON 后，自动渲染为图片。
• 问题检测：自动识别文本重叠、箭头未对齐、间距不平衡、颜色冲突等布局问题。
• 迭代修复：发现问题后，智能体自动修改 JSON 配置，重新渲染，直到输出完美为止。
• 结果：交付给用户的永远是经过视觉验证的高质量图表，无需人工二次调整。

3. 品牌一键定制 (Brand Customization)

企业级应用最头疼的风格统一问题，在这里迎刃而解。

• 单文件控制：所有颜色、字体、线条样式都定义在 references/color-palette.md 文件中。
• 全局生效：只需替换这一个文件，所有后续生成的图表将自动遵循你的品牌规范（Logo 色、主色调、辅助色）。
• 灵活适配：轻松切换“深色模式”、“极简风”或“企业 VI”风格。

4. 通用兼容

• 无缝集成：兼容任何支持 .claude/skills/ 目录读取的智能体。
• 零配置上手：对于 Claude Code 用户，只需放入目录即可立即调用。

快速安装与设置

第一步：安装技能

# 克隆仓库
git clone https://github.com/coleam00/excalidraw-diagram-skill.git

# 复制到技能目录
cp -r excalidraw-diagram-skill .claude/skills/excalidraw-diagram

第二步：配置渲染环境（视觉验证必需）

该技能依赖 Playwright 进行截图验证。你有两种设置方式：

选项 A：让智能体自己搞定（推荐）
直接对你的智能体说：

"请按照 SKILL.md 中的说明，为我设置 Excalidraw Diagram Skill 的渲染环境。"
智能体会自动运行必要的命令安装依赖。

选项 B：手动设置

cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium

实战用法

安装完成后，你可以用自然语言下达极其复杂的绘图指令：

场景 1：架构设计

“创建一个 Excalidraw 图表，展示 AG-UI 协议如何将事件从 AI 智能体流式传输到前端 UI。请包含具体的 WebSocket 消息负载示例，并用扇出结构表示多客户端订阅。”

场景 2：数据库模型

“画出电商系统的 ER 图，重点展示订单、商品和用户的一对多关系。请在实体框内列出关键字段类型，并使用汇聚线条表示统计报表的数据来源。”

场景 3：品牌定制

“编辑 color-palette.md，将主色调改为我们的品牌蓝 (#0052CC)，背景设为深灰。然后重新生成上一张架构图。”

智能体将自动执行：

1. 概念映射：理解需求，确定布局策略。
2. JSON 生成：编写 Excalidraw 场景数据。
3. 渲染验证：调用 Playwright 截图，检查布局。
4. 自动修复：如有重叠或错位，自动调整坐标并重试。
5. 最终交付：输出完美的 .excalidraw 文件和预览图。