Files

T

Ubuntu 32b43f85bd a

2026-07-03 16:58:28 +08:00

14 KiB

Raw Blame History

name, description

name	description
hand-drawn-diagram	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 首选）

```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 编辑器都支持。

🎨 高级功能

分组容器（虚线框）

Container("FastAPI Backend", x=260, y=30, width=300, height=180, color="#34d399")

效果：虚线圆角框 + 左上角标签

自定义连接

Connection("A", "B", style="dashed", color="#fb7185", label="auth", type="auth")

参数	选项
`style`	`solid` / `dashed` / `dotted`
`type`	`data` / `auth` / `config` / `frontend` / `backend` / `database`

组件多行文字

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: 简单分层架构

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: 高级架构图（分组容器 + 技术栈卡片）

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（推荐）

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

输出示例：

### 博客系统 架构

| 层级 | 组件 | 类型 |
|------|------|------|
| 前端层 | 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: 金字塔图（优先级分析）

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: 象限图（优先级矩阵）

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: 泳道图（跨职能流程）

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: 时间线（路线图）

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）

from generator import to_svg_only

svg_code = to_svg_only("系统架构", [...])
# 直接粘贴到 Markdown HTML 块

语法支持

简单文本描述 → 我可以理解并绘制：

用户输入用户名密码 → 校验 → 成功/失败
          ↓
      生成 JWT
          ↓
      返回 Token

结构化数据 → 更精确的控制：

{
  "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 模板引擎：

# 伪代码
from templates import ArchitectureTemplate

def generate_diagram(data):
    svg = ArchitectureTemplate.render(
        components=data.components,
        connections=data.connections,
        theme="dark"
    )
    return wrap_in_html(svg)

零外部调用，纯本地计算。

🧪 回归测试

修改代码后运行测试，防止改坏现有功能：

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。

14 KiB Raw Blame History Unescape Escape