| name | excalidraw-diagram |
| description | Generate animated Excalidraw diagrams from text content. Triggers on "Excalidraw动画", "Excalidraw animate", "动画图", "分镜配图". |
| metadata | {"version":"1.4.0"} |
Excalidraw Diagram Generator
路径约定: 本 Skill 使用 {SKILL_DIR} 表示 Skill 安装目录,{WORKSPACE_DIR} 表示当前工作目录(执行目录)
Create animated Excalidraw diagrams from text content with stable JSON output.
Goal
根据用户输入内容,生成可直接导入 Excalidraw 的 .excalidraw 文件,并为每个元素附带动画顺序
分镜配图模式(与 product-storyboard 配合)
输入格式
为分镜 {scene} 生成 Excalidraw 配图
| 参数 | 说明 | 示例 |
|---|
scene | 分镜文件名(不含 .md) | 01 |
路径推导(固定结构)
public/storyboard/ ← 固定输出目录
├── index.md ← 分镜大纲
├── visual-spec.md ← 全局视觉规范(独立文件)
├── scenes/
│ └── {scene}.md ← 分镜内容
└── assets/
└── {scene}.excalidraw ← 输出位置
分镜配图流程
- 解析输入: 提取
scene。
- 读取规范: 从
public/storyboard/visual-spec.md 提取配色、字号、画布尺寸(YAML frontmatter)。
- 读取分镜: 从
public/storyboard/scenes/{scene}.md 提取 ## 视觉元素 和 ## 关键信息。
- 选择图表类型: 参考规范中的「推荐图表类型」,结合分镜
type。
- 应用规范: 用全局规范覆盖默认样式(见下方「视觉规范映射」)。
- 生成 JSON: 输出 Excalidraw JSON。
- 保存文件: 输出到
public/storyboard/assets/{scene}.excalidraw。
- Post-process: 执行
{SKILL_DIR}/scripts/postprocess.py --visual-spec public/storyboard/visual-spec.md 修复结构性问题并强制视觉规范一致性(见下方 Post-process 章节)。
视觉规范映射
| 全局视觉规范字段 | Excalidraw 应用 |
|---|
| 画布尺寸 | 布局范围 |
| 主色 | 主节点 backgroundColor |
| 次色 | 中间节点 backgroundColor |
| 强调色 | 突出元素 backgroundColor |
| 标题色/正文色 | text strokeColor |
| 字号设定 | fontSize |
| 动画节奏 | customData.animate.duration |
未指定的字段使用 {SKILL_DIR}/references/style-guide.md 默认值。
独立模式(默认)
直接从用户输入文本生成图表,使用内置默认样式。
Workflow
- Analyze content: 提取概念、关系、层级、时序。
- Choose diagram type: 从下方类型表中选最匹配的一类。
- Plan layout: 先定画布范围、主节点位置、连线方向,再写元素。
- Generate JSON: 输出合法 Excalidraw JSON,且每个元素包含
customData.animate.order。
- Validate JSON: 执行保存前校验(见
{SKILL_DIR}/references/validation.md)。
- Auto-save file: 自动写入当前工作目录。
- Post-process: 执行
{SKILL_DIR}/scripts/postprocess.py 修复结构性问题(见下方 Post-process 章节)。
- User handoff: 说明图表类型选择、动画顺序和预览方法。
Diagram Types & Selection Guide
| 类型 | 英文 | 使用场景 | 做法 |
|---|
| 流程图 | Flowchart | 步骤说明、工作流、任务顺序 | 用箭头连接步骤,主流程单向清晰 |
| 思维导图 | Mind Map | 概念发散、主题分类 | 中心主题向外辐射 |
| 层级图 | Hierarchy | 组织结构、系统分层 | 自上而下或自左向右分层 |
| 关系图 | Relationship | 依赖、影响、互动 | 多节点连线并标注关系 |
| 对比图 | Comparison | 多方案对照 | 左右分栏或矩阵对比 |
| 时间线 | Timeline | 事件发展、里程碑 | 沿时间轴布局关键节点 |
| 矩阵图 | Matrix | 双维度分类、优先级 | X/Y 维度坐标化放置 |
| 自由布局 | Freeform | 早期梳理、信息草图 | 允许弱结构但保持可读 |
References
统一从以下入口读取规范,避免重复定义:
- 结构契约(MUST/MUST NOT):
{SKILL_DIR}/references/contract.md
- 风格建议(SHOULD):
{SKILL_DIR}/references/style-guide.md
- 保存前校验:
{SKILL_DIR}/references/validation.md
- 最小示例:
{SKILL_DIR}/references/examples/minimal-animated.md
- 可选绑定示例:
{SKILL_DIR}/references/examples/bindings.md
Post-process(自动修复)
保存文件后立即执行一次 {SKILL_DIR}/scripts/postprocess.py,修复结构性问题并强制视觉规范一致性后,文件即为最终版本,后续不会再被修改。
使用方式
python3 {SKILL_DIR}/scripts/postprocess.py <file.excalidraw>
python3 {SKILL_DIR}/scripts/postprocess.py <file.excalidraw> --visual-spec public/storyboard/visual-spec.md
python3 {SKILL_DIR}/scripts/postprocess.py <file.excalidraw> --dry-run
python3 {SKILL_DIR}/scripts/postprocess.py <file.excalidraw> --verbose
自动修复项
| 问题类型 | 修复方式 |
|---|
width/height ≤ 0 | 设置最小值 |
| 绑定不一致 | 同步 boundElements ↔ containerId |
animate.order 不连续 | 重新排序为连续整数 |
| 禁用字段存在 | 删除 frameId/index/versionNonce/rawText |
| 必填字段缺失 | 补充默认值 |
fontFamily 错误 | 强制设为 5(支持中文) |
points 为空 | 根据宽度自动计算 |
id 重复 | 生成新 UUID |
| 文本宽高不匹配 | 根据内容重新估算(区分中英文) |
| 文本未居中 | 根据同组容器计算正确的 x 坐标 |
视觉规范一致性(依赖 visual-spec.md)
当检测到 visual-spec.md(自动探测或 --visual-spec 指定)时,额外执行以下强制校正:
| 问题类型 | 修复方式 |
|---|
| 文本颜色偏离规范 | 标题字号 → title 色,正文字号 → text 色 |
| 填充色不在调色板 | 映射为 RGB 距离最近的规范色 |
roughness 与风格基调不一致 | 根据 style_tone 统一(简洁专业/科技感 → 0) |
| 字号低于规范最小值 | 强制为 caption 字号下限 |
返回码
File Naming & Auto-save
分镜配图模式
格式:{scene}.excalidraw
示例:01.excalidraw
保存位置:public/storyboard/assets/
独立模式
格式:[主题].[类型].excalidraw
示例:商业模式.relationship.excalidraw
保存位置:当前工作目录
Save Behavior
- 使用当前代理可用的文件写入能力自动保存。
- 不要硬编码绝对路径。
- 文件名非法字符替换为
-。
- 若同名已存在,按
-v2, -v3 追加后缀。
User Response Template
完成后向用户反馈:
- 图表已生成。
- 文件保存路径(精确到文件名)。
- 选择了哪种图表类型及原因(1-2 句)。
- 动画顺序概览(例如:
标题(1) -> 框架(2-4) -> 连线(5-7))。
- 预览方式:
- 打开
https://dai-shi.github.io/excalidraw-animate/
- 加载
.excalidraw 文件
- 预览并导出 SVG 或 WebM
Maintenance Convention
- 结构字段与 JSON 契约变更仅修改
{SKILL_DIR}/references/contract.md。
- 风格建议仅修改
{SKILL_DIR}/references/style-guide.md。
- 校验规则仅修改
{SKILL_DIR}/references/validation.md。
- 示例仅修改
{SKILL_DIR}/references/examples/*。
SKILL.md 只维护流程与引用,不重复定义结构规范。