excalidraw-diagram

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   ← 输出位置

分镜配图流程

0. 解析输入: 提取 scene。
1. 读取规范: 从 public/storyboard/visual-spec.md 提取配色、字号、画布尺寸（YAML frontmatter）。
2. 读取分镜: 从 public/storyboard/scenes/{scene}.md 提取 ## 视觉元素 和 ## 关键信息。
3. 选择图表类型: 参考规范中的「推荐图表类型」，结合分镜 type。
4. 应用规范: 用全局规范覆盖默认样式（见下方「视觉规范映射」）。
5. 生成 JSON: 输出 Excalidraw JSON。
6. 保存文件: 输出到 public/storyboard/assets/{scene}.excalidraw。
7. 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

1. Analyze content: 提取概念、关系、层级、时序。
2. Choose diagram type: 从下方类型表中选最匹配的一类。
3. Plan layout: 先定画布范围、主节点位置、连线方向，再写元素。
4. Generate JSON: 输出合法 Excalidraw JSON，且每个元素包含 customData.animate.order。
5. Validate JSON: 执行保存前校验（见 {SKILL_DIR}/references/validation.md）。
6. Auto-save file: 自动写入当前工作目录。
7. Post-process: 执行 {SKILL_DIR}/scripts/postprocess.py 修复结构性问题（见下方 Post-process 章节）。
8. 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，修复结构性问题并强制视觉规范一致性后，文件即为最终版本，后续不会再被修改。

使用方式

# 检测并修复（自动探测同目录下的 visual-spec.md）
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 字号下限

返回码

• 0: 无问题或已全部修复
• 2: 存在未修复问题

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)）。
• 预览方式：
  1. 打开 https://dai-shi.github.io/excalidraw-animate/
  2. 加载 .excalidraw 文件
  3. 预览并导出 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 只维护流程与引用，不重复定义结构规范。