--- name: hand-drawn-diagram description: Create diagrams instantly without AI tokens - flowcharts, architecture diagrams, sequence diagrams. ZERO cost, pure SVG generation. Use for ANY diagram request unless user explicitly asks for AI-generated or complex auto-layout diagrams. --- # Hand-Drawn Diagram Generator **零成本、即时生成**的图表绘制工具。基于纯 SVG 模板,**不调用任何 AI API**,适合日常使用。 ## 🎯 为什么用这个 skill? | 方式 | 速度 | 成本 | 质量 | |------|------|------|------| | **本 skill** | ⚡ 即时 | **¥0** | 精美统一 | | AI 生成 | ⏱️ 2-5秒 | ¥0.003-0.02 | 不稳定 | | Mermaid 文本 | ⚡ 即时 | ¥0 | 需渲染器 | **最佳场景**: 快速展示架构、画流程图、技术分享配图 ## 📊 输出格式 ### 1. HTML 文件(独立可视化) 自包含的 `.html` 文件,可直接浏览器打开,支持: - 深色主题 + 网格背景 - **分组容器**(虚线框) - **自定义连接**(实线/虚线/不同颜色) - **多行文字**(端口、描述) - **增强图例**(组件类型 + 连接类型) ### 2. Mermaid 语法(Markdown 首选) ```markdown ```mermaid graph TD N1["React"] --> N3["FastAPI"] class N1 frontend class N3 backend ``` ``` **优点**: GitHub/GitLab/Notion 原生支持渲染 ### 3. 纯 SVG(嵌入 HTML) 可直接插入 Markdown 的 HTML 块: ```markdown
...
``` **优点**: 样式可控,不依赖外部渲染 ### 4. Markdown 表格(纯文本) 最通用的格式,任何 Markdown 编辑器都支持。 --- ## 🎨 高级功能 ### 分组容器(虚线框) ```python Container("FastAPI Backend", x=260, y=30, width=300, height=180, color="#34d399") ``` 效果:虚线圆角框 + 左上角标签 ### 自定义连接 ```python Connection("A", "B", style="dashed", color="#fb7185", label="auth", type="auth") ``` | 参数 | 选项 | |------|------| | `style` | `solid` / `dashed` / `dotted` | | `type` | `data` / `auth` / `config` / `frontend` / `backend` / `database` | ### 组件多行文字 ```python Component("API Gateway", "backend", x=100, y=100, sublabel="Port 8889", # 端口号(灰色小字) description="REST API\\nGraphQL") # 描述(多行支持) ``` --- ## 🎯 支持的图表类型 ### 1. 流程图 (flowchart) ``` 节点 A → 节点 B → 节点 C 条件判断: 菱形 开始/结束: 圆角矩形 ``` ### 2. 架构图 (architecture) ``` 分层展示:前端 → 后端 → 数据库 → 外部服务 支持:组件框、连接箭头、图例 配色:深色主题,语义化颜色 ``` ### 3. 时序图 (sequence) ``` 参与者 A ↔ 参与者 B 的交互流程 时间轴从上到下 ``` ### 4. 类图 (class) ``` 类名 - 属性 + 方法() 继承/关联关系 ``` ### 5. 金字塔/漏斗图 (pyramid) ``` 层级递减:顶层窄 → 底层宽 用途:优先级、MoSCoW分析、漏斗转化 ``` ### 6. 象限图/矩阵 (quadrant) ``` 2×2 矩阵:X轴 × Y轴 用途:优先级矩阵、SWOT、风险评估 ``` ### 7. 泳道图 (swimlane) ``` 跨职能流程:不同角色/系统的协作流程 用途:业务流程、系统交互 ``` ### 8. 时间线 (timeline) ``` 水平或垂直时间轴 用途:产品路线图、里程碑、版本历史 ``` ## 🎨 设计系统 ### 配色方案 (深色主题) | 类型 | 填充 | 边框 | 用途 | |------|------|------|------| | 用户/前端 | `rgba(8, 51, 68, 0.4)` | `#22d3ee` | 青色 | | 处理/后端 | `rgba(6, 78, 59, 0.4)` | `#34d399` | 绿色 | | 数据/存储 | `rgba(76, 29, 149, 0.4)` | `#a78bfa` | 紫色 | | 外部/API | `rgba(120, 53, 15, 0.3)` | `#fbbf24` | 琥珀色 | | 安全/认证 | `rgba(136, 19, 55, 0.4)` | `#fb7185` | 玫瑰色 | | 通用 | `rgba(30, 41, 59, 0.5)` | `#94a3b8` | 灰色 | ### 视觉规范 - **背景**: `#020617` 深蓝黑 + 网格图案 - **字体**: JetBrains Mono (技术感) - **组件**: 圆角矩形 (rx=6),半透明填充 - **连线**: 灰色箭头 `#64748b` - **动画**: 脉冲指示器 (CSS animation) ## 🚀 使用方法 ### 方式 1: 简单分层架构 ```python from generator import quick_architecture quick_architecture( "个人博客系统", [ {"name": "前端层", "items": ["React 18", "Tailwind"], "color": "frontend"}, {"name": "后端层", "items": ["FastAPI", "JWT Auth"], "color": "backend"}, {"name": "数据层", "items": ["SQLite", "Redis"], "color": "database"}, ], "/tmp/blog_arch.html" ) ``` ### 方式 2: 高级架构图(分组容器 + 技术栈卡片) ```python from generator import DiagramGenerator, Component, Connection, Container gen = DiagramGenerator() # ⚠️ 注意:手动设置坐标时,确保组件不重叠 # 推荐垂直间距 >= 110px,水平间距 >= 40px components = [ # 第1层 (y=60) Component("React Frontend", "frontend", 100, 60, 130, 55, sublabel="Port 8888", description="UI / State"), # 第2层 (y=180) - 与第1层间隔 120px Component("FastAPI Core", "backend", 100, 180, 130, 60, sublabel="Port 8889", description="REST API"), Component("Auth Service", "security", 450, 180, 120, 55), # 第3层 (y=300) Component("JWT Auth", "security", 100, 300, 110, 55), Component("Pydantic", "backend", 260, 300, 110, 50), Component("fumamxAuth", "cloud", 450, 300, 120, 55), # 第4层 (y=420) Component("SQLite", "database", 280, 420, 110, 50), Component("Redis", "database", 100, 420, 100, 50), ] # 分组容器包围对应组件 containers = [ Container("FastAPI Backend", 80, 160, 310, 210, "#34d399"), Container("Auth Module", 430, 160, 160, 210, "#fb7185"), ] # 自定义连接(支持不同样式和标签) connections = [ Connection("React Frontend", "FastAPI Core", "solid", "#64748b"), Connection("FastAPI Core", "JWT Auth", "dashed", "#fb7185", "verify", "auth"), Connection("FastAPI Core", "SQLite", "solid", "#64748b"), Connection("Auth Service", "fumamxAuth", "dashed", "#fb7185", "OAuth", "auth"), ] # 技术栈卡片 - 带彩色圆点和列表项 cards = [ { "title": "前端组件 (Port 10000)", "color": "cyan", # 圆点颜色: cyan/green/purple/yellow/rose "items": [ "React 18 + Vite + Tailwind CSS", "HashRouter SPA 架构", "页面: Login / Customers / Discover / Settings", "axios HTTP 客户端" ] }, { "title": "后端服务 (Port 10001)", "color": "green", "items": [ "FastAPI + SQLAlchemy + SQLite", "JWT 认证中间件", "7 个 API 路由模块", "CORS 跨域配置" ] }, { "title": "数据层", "color": "purple", "items": [ "SQLite 本地数据库", "8 张核心数据表", "SQLAlchemy ORM", "fumamxCLI 外部数据集成" ] } ] gen.create_architecture( "系统架构图", components, connections, "/tmp/output.html", containers=containers, cards=cards, # 新增技术栈卡片 auto_layout=False # 使用手动坐标 ) ``` **坐标设置要点:** - `x`: 水平位置(从左到右) - `y`: 垂直位置(从上到下,值越大越靠下) - 同层组件 Y 相同,X 间隔至少 `width + 40` - 不同层 Y 间隔至少 `height + 50` - `auto_layout=True` 会根据连接关系自动计算位置(但可能不符合预期分组) ### 方式 2: Markdown Mermaid(推荐) ```python from generator import to_mermaid, MarkdownDiagramHelper # 纯 Mermaid 语法 mermaid_code = to_mermaid("博客系统", [ {"name": "前端", "items": ["React"], "color": "frontend"}, {"name": "后端", "items": ["FastAPI"], "color": "backend"}, ]) # 或一键生成完整文档片段 helper = MarkdownDiagramHelper("博客系统", [...]) full_doc = helper.full_document() # 包含表格 + Mermaid + SVG ``` 输出示例: ````markdown ### 博客系统 架构 | 层级 | 组件 | 类型 | |------|------|------| | 前端层 | React 18 | 前端 | | 后端层 | FastAPI | 后端 | ```mermaid graph TD N1["React 18"] --> N2["FastAPI"] class N1 frontend class N2 backend classDef frontend fill:#083344,stroke:#22d3ee,stroke-width:2px,color:#fff classDef backend fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#fff ``` ```` ### 方式 3: 金字塔图(优先级分析) ```python from generator import quick_pyramid quick_pyramid( "需求优先级", [ {"label": "必须有", "value": "20%", "color": "security"}, {"label": "应该有", "value": "30%", "color": "frontend"}, {"label": "可以有", "value": "35%", "color": "backend"}, {"label": "暂不需要", "value": "15%", "color": "generic"}, ], "/tmp/pyramid.html" ) ``` ### 方式 4: 象限图(优先级矩阵) ```python from generator import quick_quadrant quick_quadrant( "项目优先级", ("低影响", "高影响"), # X轴 ("低成本", "高成本"), # Y轴 [ {"name": "快速获胜", "x": 0.2, "y": 0.8, "color": "backend", "size": 3}, {"name": "重大项目", "x": 0.8, "y": 0.9, "color": "security", "size": 3}, {"name": "避坑", "x": 0.9, "y": 0.1, "color": "cloud", "size": 1}, ], "/tmp/quadrant.html" ) ``` ### 方式 5: 泳道图(跨职能流程) ```python from generator import quick_swimlane quick_swimlane( "用户注册流程", [ {"name": "前端", "color": "frontend"}, {"name": "后端", "color": "backend"}, {"name": "外部", "color": "cloud"}, ], [ {"lane": 0, "step": 0, "label": "填写表单", "type": "process"}, {"lane": 0, "step": 1, "label": "提交", "type": "process"}, {"lane": 1, "step": 1, "label": "验证", "type": "decision"}, {"lane": 1, "step": 2, "label": "创建用户", "type": "process"}, {"lane": 0, "step": 3, "label": "成功页", "type": "process"}, ], "/tmp/swimlane.html" ) ``` ### 方式 6: 时间线(路线图) ```python from generator import quick_timeline # 水平时间线 quick_timeline( "产品路线图", [ {"date": "Q1", "label": "MVP", "color": "backend", "side": "top"}, {"date": "Q2", "label": "增长", "color": "frontend", "side": "bottom"}, {"date": "Q3", "label": "企业版", "color": "security", "side": "top"}, ], "/tmp/timeline.html" ) # 垂直时间线 quick_timeline("里程碑", events, "/tmp/timeline_v.html", orientation="vertical") ``` ### 方式 7: 纯 SVG(嵌入 Markdown) ```python from generator import to_svg_only svg_code = to_svg_only("系统架构", [...]) # 直接粘贴到 Markdown HTML 块 ``` ### 语法支持 **简单文本描述** → 我可以理解并绘制: ``` 用户输入用户名密码 → 校验 → 成功/失败 ↓ 生成 JWT ↓ 返回 Token ``` **结构化数据** → 更精确的控制: ```python { "type": "architecture", "title": "My System", "layers": [ {"name": "Frontend", "items": ["React", "Vue"]}, {"name": "Backend", "items": ["API", "Worker"]}, {"name": "Database", "items": ["PostgreSQL", "Redis"]} ] } ``` ## 📁 输出格式对比 | 格式 | 代码示例 | 适用场景 | 兼容性 | |------|---------|---------|--------| | **HTML** | `quick_architecture()` | 独立页面、演示、截图 | 浏览器 | | **Mermaid** | `to_mermaid()` | GitHub README、技术文档 | ⭐⭐⭐ 通用 | | **SVG** | `to_svg_only()` | 需要精确控制样式 | HTML Markdown | | **表格** | `MarkdownDiagramHelper.table()` | 纯文本、打印文档 | ⭐⭐⭐⭐⭐ 最通用 | ### HTML 文件 - 自包含(无外部依赖,除 Google Fonts) - 可直接浏览器打开 - 可截图分享(小红书、公众号、PPT) - 可嵌入 iframe ### Mermaid 代码 - GitHub/GitLab/Notion 原生支持 - 支持交互(点击展开) - 版本控制友好(纯文本) ### 纯 SVG - 样式完全可控 - 不依赖外部渲染器 - 可嵌入 HTML `
` 折叠块 ## 🆚 与 architecture-diagram skill 的区别 | | hand-drawn-diagram | architecture-diagram | |--|-------------------|---------------------| | **成本** | ¥0 (零 token) | 消耗 AI token | | **速度** | 即时 (<1s) | 2-5s (API 延迟) | | **复杂度** | 适合 <20 组件 | 适合复杂拓扑 | | **布局** | 我手动设计 | AI 自动布局 | | **使用频率** | **默认首选** | 按需使用 | ## 💡 最佳实践 ### 我应该用这个 skill 当: - ✅ 用户要"画个图" - ✅ 快速展示系统架构 - ✅ 技术博客配图 - ✅ 会议演示材料 - ✅ 小红书/公众号技术分享 ### 我应该用 AI 生成当: - ❓ 用户明确要求"AI 生成" - ❓ 组件太多 (>20) 手动布局困难 - ❓ 需要自动计算最优布局 - ❓ 拓扑结构极其复杂 ## 🔧 技术实现 基于 Python + Jinja2 模板引擎: ```python # 伪代码 from templates import ArchitectureTemplate def generate_diagram(data): svg = ArchitectureTemplate.render( components=data.components, connections=data.connections, theme="dark" ) return wrap_in_html(svg) ``` **零外部调用**,纯本地计算。 ## 🧪 回归测试 修改代码后运行测试,防止改坏现有功能: ```bash cd skills/hand-drawn-diagram python3 tests/run_tests.py ``` 测试覆盖: - sketch / flat 两种风格正常生成 - 语义节点映射(double/cylinder/hexagon/cloud) - 组件连接(Connection) - 分组容器(Container) - SVG / HTML 两种输出格式 添加新 fixture:在 `tests/fixtures/` 创建 JSON,参考已有文件格式。 ## 📝 示例输出 参见 `/home/ubuntu/fumamxCRM_architecture.html` - 完全手写 SVG,无 AI 参与。 --- **原则**: 先简单、零成本、快速交付。复杂场景再升级 AI。