Files
nanocode/skills/hand-drawn-diagram/SKILL.md
T
Ubuntu 32b43f85bd a
2026-07-03 16:58:28 +08:00

512 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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。