Drawiodo

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 打开，即时查看结果

渐进式文件索引

文件名	分类	包含内容	审计关联
references/LICENSE.md	许可协议	开源许可证声明（MIT）。包含：MIT 许可证完整文本。	R-26
references/antipatterns.md	规范指南	skill 编写中的常见反模式。包含：错误做法示例、正确做法示例、避坑指引。	R-18
references/api_reference.md	参考文档	- DrawIOBuilder(name) - 创建画布	无
references/changelog.md	版本管理	版本更新日志。包含：版本号、变更类型、修复项、升级说明。	R-24
references/faq.md	常见问题	常见疑问与解答。包含：问题分类、原因分析、解决方案。	R-19, R-25 C-19
references/generation.md	参考文档	路径信息见 _meta.json data_dir 声明 + frontmatter data_dir 字段。	无
references/guide.md	使用指南	三种执行模式操作教程。包含：audit/create/refactor 流程、参数说明、注意事项。	无
references/hooks.md	参考文档	本技能的所有关键约束由 Python 端强制执行，不依赖 LLM 自觉。	无
references/known_issues.md	参考文档	问题：子节点使用极坐标计算位置，导致：	无
references/layout_rules.md	参考文档	- 画布坐标：左上角(0,0)，X向右增大，Y向下增大	无
references/permissions.md	权限与测试	权限扫描说明与测试结论。包含：风险等级、高权限操作说明、测试概览、计时统计。	R-15, R-16
references/test-report.md	测试报告	skill-function-test 全量测试结论	无
---	---	---	---
scripts/drawio_unified.py	核心引擎	统一图生成：拓扑分层 → 重心排序 → 位置计算 → 路由	无
scripts/drawio_module.py	模块基类	DiagramModule 抽象接口 + LayoutResult + 渲染层	无
scripts/drawio_modules.py	模块注册	GraphModule / GanttModule 注册表	无
scripts/drawio_gen.py	XML 生成	Node / Edge / DrawIOBuilder + build_xml()	无
scripts/drawio_route.py	路径路由	Rect / CollisionResolver / ObstacleRouter	无
scripts/drawio_layout.py	布局辅助	text_width / auto_node_size / 间距常量	无
scripts/drawio_hooks.py	钩子系统	8 个 Hook Point 实现	无
scripts/drawio_version.py	版本管理	VersionManager CLI：init/save/list/restore/diff	无
scripts/drawio.py	CLI 入口	模板式图表生成 CLI（流程图/架构图/类图/ER/树/思维导图）	无
scripts/drawio_agent.py	CLI 入口	自然语言驱动的图表生成 CLI（--json 接收结构化数据）	无
scripts/drawio_regen_all.py	批量生成	一次性生成全部示例图的脚本	无
scripts/drawio_templates.py	模板生成	旧版按图类型生成模板（flowchart/architecture/class/er/tree/mindmap）	无
scripts/build_network.py	网络构建	网络拓扑图专用构建函数	无

工作流程

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

Hook Point	强制操作	说明
pre_think	输入非空校验（阻断）	空输入直接阻断
post_think	分析结果校验	缺失字段仅警告
pre_confirm	选项完整性校验（阻断）+ 快捷跳过（清除选项）	不足 2 项或快捷跳转均阻断/跳过
post_confirm	用户选择解析	-
pre_iterate	自动创建目录 + 自动备份	备份由 Python 调用 VersionManager
post_iterate	输出校验 + 自动初始化版本管理 + 自动打开预览	init 和预览都由 Python 执行
pre_vc	自动清理超限版本	删除最旧版本由 Python 执行
post_vc	版本状态报告	-

执行规则

• 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 字段

核心文件

文件	路径	说明
核心库	scripts/drawio_gen.py	节点/连线/容器/XML 生成
模板库	scripts/drawio_templates.py	8 种图表模板
Agent 入口	scripts/drawio_agent.py	CLI/自然语言解析
版本管理	scripts/drawio_version.py	5 版本回溯系统

使用示例

场景 1：生成架构图

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

场景 2：迭代更新

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