512 lines
14 KiB
Markdown
512 lines
14 KiB
Markdown
---
|
||
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
|
||
<div align="center">
|
||
<svg>...</svg>
|
||
</div>
|
||
```
|
||
**优点**: 样式可控,不依赖外部渲染
|
||
|
||
### 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 `<details>` 折叠块
|
||
|
||
## 🆚 与 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。
|