drawiodo: draw.io 自动做图 Skill

触发条件

正向触发： 当用户提出以下意图时触发：

• "画一个 xxx 图"、"生成 xxx 图"、"做一个图表"
• "架构图"、"流程图"、"UML 类图"、"ER 图"、"时序图"、"思维导图"
• "用 draw.io 画"、"生成 drawio 文件"
• "画网络拓扑"、"画组织架构"、"画系统架构"
• "按照这个示例改成..."、"参照这个图改..."、"基于这个样式做一个..."
• 用户提供截图/示例文件并要求生成类似图表
• 任何涉及 draw.io / diagrams.net 的需求

否定条件： 以下情况不触发本技能：

• 用户只是问"你会画图吗"、"有什么画图工具"——闲聊
• 用户明确要求用其他工具（如"用 mermaid 画流程图"）
• 用户只是提到"图"字但没有画图意图（如"这个图怎么读"）
• 用户要求编辑已有的图片文件（如 .png/.jpg）——本技能生成的是 .drawio 文件

核心能力

📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为入口（≤230行），详细内容拆分到 references/*.md 按需加载。

1. 自然语言 → 图表：理解用户描述，自动判断图表类型，生成 .drawio 文件
2. 统一布局引擎：拓扑排序分层 → 重心排序层内排列 → 动态间距计算 → 障碍感知路径路由，不区分图类型
3. 多形状支持：UML 类表、ER 实体、圆柱体、菱形、六边形、云朵、文档、便签等，用户指定即可
4. 5 主题配色：default/tech/business/bw/nature，节点和边颜色统一轮换
5. 迭代更新：在现有文件基础上精确更新，支持版本回溯（最多 5 版本）
6. 思考-确认-执行工作流：先分析需求、展示方案、等待确认，再动手画图
7. 本地预览：生成后用 draw.io.exe 打开，即时查看结果

渐进式文件索引

工作流程

1. 思考分析（Think）
   • 输入：用户自然语言描述 + 可选的参考图/截图
   • 输出：结构化图表分析结果（类型、节点、关系、布局）
2. 方案确认（Confirm）
   • 输入：结构化分析结果
   • 输出：用 AskUserQuestion 向用户展示方案，等待确认
3. 迭代更新（Iterate）
   • 输入：用户确认的方案
   • 输出：生成的 .drawio 文件，每次更新前自动保存版本
4. 版本回溯（Version Control）
   • 输入：已保存的历史版本（v1~v5）
   • 输出：恢复指定版本的文件

→ 各阶段详细说明见核心能力的渐进式文件索引

各阶段要点：

• Think：分析用户需求，判断图表类型和输入类型，输出结构化思考结果
• Confirm：向用户展示方案，用 AskUserQuestion 等待确认（必须确认后才能动手）
• Iterate：在现有文件基础上精确更新，每次更新前保存版本（v1→v2→v3...）
• Version Control：最多保留 5 个版本，支持随时回溯

快捷模式（可跳过确认）：

• 简单流程图（3-5 个步骤的线性流程）
• 明确的模板调用（用户给出完整的 JSON spec）
• 已确认方案后的迭代更新

版本管理命令：

python {SKILL_DIR}/scripts/drawio_version.py init <文件.drawio> "初始版本"
python {SKILL_DIR}/scripts/drawio_version.py save <文件.drawio> "更新了 XX"
python {SKILL_DIR}/scripts/drawio_version.py list <文件.drawio>
python {SKILL_DIR}/scripts/drawio_version.py restore <文件.drawio> v2

钩子系统（强制约束）

关键操作由 Python 端自动执行，不依赖 LLM 自觉。 备份、版本管理初始化、版本上限清理均由钩子在脚本层直接完成， LLM 无权跳过这些操作。

→ 各参考文档详见核心能力的渐进式文件索引

8 个 Hook Point

执行规则

• abort=True -> 立即阻断流程（LLM 无权绕过）
• success=False 但不 abort -> 记录警告，不阻塞
• 所有操作由 Python 端算法强制完成

在阶段代码中调用

from drawio_hooks import hooks

# 在阶段开始时
results = hooks('pre_iterate', {
    'output_path': output_path,
    'is_update': True,          # 会触发自动备份
})
for r in results:
    if r.abort:
        return  # 钩子已处理，阻断并返回
    if not r.success:
        print(f'Warning: {r.message}')

# 在阶段结束时
results = hooks('post_iterate', {
    'output_path': output_path,  # 会触发自动 init 版本管理
})

注册/注销自定义钩子

from drawio_hooks import register, unregister

@register('pre_think', name='my_check', description='自定义校验')
def my_hook(ctx):
    if 'special' not in ctx.get('user_input', ''):
        return {'success': False, 'message': '缺少特殊参数', 'abort': True}
    return {'success': True, 'message': 'ok'}

unregister('post_iterate', 'preview_trigger')  # 禁用自动预览

CLI 管理命令

python {SKILL_DIR}/scripts/drawio_hooks.py list     # 查看所有注册钩子
python {SKILL_DIR}/scripts/drawio_hooks.py check    # 全流程自检
python {SKILL_DIR}/scripts/drawio_hooks.py history  # 查看执行历史

生成图表

→ 详见核心能力的渐进式文件索引

API 参考

→ 详见核心能力的渐进式文件索引

坐标系与布局规则

→ 详见核心能力的渐进式文件索引

已知问题与修复记录

→ 详见核心能力的渐进式文件索引

→ 反模式和常见问题详见核心能力的渐进式文件索引

输出规范

• 文件命名：{类型}_{描述}.drawio，如 architecture_microservice.drawio
• 生成后自动用 draw.io 打开预览
• 交付附件给用户
• 每次生成/更新后初始化或更新版本管理
• 路径信息见 _meta.json data_dir 声明 + frontmatter data_dir 字段

核心文件

使用示例

场景 1：生成架构图

用户：帮我画一个微服务架构图，包含 API 网关、用户服务、订单服务和数据库
drawiodo：正在分析需求 → 判断为"架构图" → 输出方案：4 个容器+连线+数据库图标
用户确认后 → 生成 architecture_microservice.drawio → 自动打开预览

场景 2：迭代更新

用户：在上次的系统架构图里加一个消息队列，在订单服务和用户服务之间
drawiodo：读取已存在的文件 → 自动备份(v2) → 在订单服务和用户服务之间插入消息队列节点和连线
→ 更新文件 → 自动打开预览展示变化