Termaid - Terminal Mermaid Diagram Renderer

概述

Termaid 是一个纯 Python 的 Mermaid 图表渲染工具，可以在终端或 Python 应用中直接渲染 Mermaid 图表为 ASCII/Unicode 字符图形。

核心价值

• 零依赖：纯 Python 实现，无需浏览器或外部服务
• 终端友好：在 SSH、CI 日志、TUI 应用中直接渲染图表
• 多图表支持：9 种 Mermaid 图表类型
• 彩色主题：6 种内置颜色主题
• ASCII 回退：支持最基本的终端环境

🚀 快速开始

安装

# 基本安装
pip install termaid

# 带彩色输出
pip install termaid[rich]

# 带 TUI 界面
pip install termaid[textual]

# 试用（无需安装）
uvx termaid diagram.mmd

基本使用

# 渲染文件
termaid diagram.mmd

# 管道输入
echo "graph LR; A-->B-->C" | termaid

# 使用主题
termaid diagram.mmd --theme neon

# ASCII 模式
termaid diagram.mmd --ascii

# TUI 交互界面
termaid diagram.mmd --tui

Python API

from termaid import render

# 基础渲染
print(render("graph LRn A --> B --> C"))

# 彩色渲染
from termaid import render_rich
from rich import print as rprint
rprint(render_rich("graph LRn A --> B", theme="terra"))

# Textual TUI 组件
from termaid import MermaidWidget
widget = MermaidWidget("graph LRn A --> B")

📊 支持的图表类型

1. 流程图 (Flowcharts)

graph TD
    A[Start] --> B{Is valid?}
    B -->|Yes| C(Process)
    C --> D([Done])
    B -->|No| E[Error]

特性：

• 所有方向：LR, RL, TD/TB, BT
• 多种节点形状：矩形、圆角矩形、菱形、圆形等
• 边样式：实线、虚线、粗线、带标签等

2. 序列图 (Sequence Diagrams)

sequenceDiagram
    Alice->>Bob: Hello Bob
    Bob-->>Alice: Hi Alice
    Alice->>Bob: How are you?
    Bob-->>Alice: Great!

3. 类图 (Class Diagrams)

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    Animal <|-- Dog

4. ER 图 (Entity-Relationship)

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

5. 状态图 (State Diagrams)

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : start
    Processing --> Done : complete
    Done --> [*]

6. 块图 (Block Diagrams)

block-beta
    columns 3
    A["Frontend"] B["API"] C["Database"]

7. Git 图 (Git Graphs)

gitGraph
    commit id: "init"
    commit id: "feat"
    branch develop
    commit id: "dev-1"
    checkout main
    merge develop id: "merge"

8. 饼图 (Pie Charts)

pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

注意：饼图以水平条形图形式渲染，更易于终端阅读

9. 树状图 (Treemaps)

treemap-beta
    "Frontend"
        "React": 40
        "CSS": 15
    "Backend"
        "API": 35
        "Auth": 10

🎨 主题系统

内置主题

1. default - 青色节点，黄色箭头，白色标签
2. terra - 温暖的地球色调（棕色、橙色）
3. neon - 霓虹色调（品红色节点，绿色箭头）
4. mono - 单色（白色/灰色）
5. amber - 琥珀色 CRT 风格
6. phosphor - 绿色磷光终端风格

使用主题

termaid diagram.mmd --theme neon
termaid diagram.mmd --theme phosphor

rprint(render_rich(source, theme="amber"))

🔧 CLI 选项

💡 使用场景

1. 文档生成

# 在 Markdown 文档中嵌入 Mermaid 图表的终端版本
termaid architecture.mmd >> README.md

2. CI/CD 日志

# 在 CI 日志中显示架构图
echo "graph LR; Frontend-->API-->Database" | termaid --ascii

3. 代码审查

# 在代码中动态生成图表
from termaid import render
print(render(class_diagram_source))

4. TUI 应用

# 在 Textual 应用中显示动态图表
from termaid import MermaidWidget
from textual.app import App

class DiagramApp(App):
    def compose(self):
        yield MermaidWidget("graph LRn A --> B")

5. SSH 会话

# 在远程服务器上查看图表
ssh user@server "cat diagram.mmd | termaid"

🔄 集成 OpenClaw

自动化工作流

#!/bin/bash
# 自动生成架构文档

# 1. 从代码生成 Mermaid 图
python generate_architecture_mmd.py > arch.mmd

# 2. 渲染为终端友好的格式
termaid arch.mmd --theme neon > terminal_arch.txt

# 3. 嵌入到文档中
cat terminal_arch.txt >> ARCHITECTURE.md

AI Agent 集成

# 在 AI Agent 中使用 Termaid 可视化架构
def visualize_architecture(agent_response):
    """
    将 AI 生成的架构描述转换为可视化图表
    """
    mermaid_source = agent_response.get('mermaid', '')
    if mermaid_source:
        from termaid import render
        return render(mermaid_source)
    return "No diagram to render"

📝 实用脚本

批量转换脚本

#!/bin/bash
# 批量转换 Mermaid 文件

for file in *.mmd; do
    output="${file%.mmd}.txt"
    echo "Converting $file to $output"
    termaid "$file" --theme terra > "$output"
done

监控脚本

#!/bin/bash
# 监控架构变化并重新渲染

WATCH_DIR="./diagrams"
RENDER_DIR="./rendered"

inotifywait -m -e modify "$WATCH_DIR" |
while read -r directory events filename; do
    if [[ "$filename" == *.mmd ]]; then
        echo "Rendering $filename..."
        termaid "$WATCH_DIR/$filename" 
            --theme phosphor 
            > "$RENDER_DIR/${filename%.mmd}.txt"
    fi
done

🔍 高级用法

自定义渲染

from termaid import render

# 带自定义参数
result = render(
    mermaid_source,
    padding_x=8,
    padding_y=4,
    sharp_edges=True
)

错误处理

from termaid import render
import sys

try:
    output = render(invalid_mermaid_source)
except Exception as e:
    print(f"渲染失败: {e}", file=sys.stderr)
    # 提供降级方案
    print("graph TDn Error[渲染错误] --> Help[检查语法]")

性能优化

# 预加载常用图表
from termaid import render
import functools

@functools.lru_cache(maxsize=100)
def cached_render(source: str) -> str:
    """缓存渲染结果"""
    return render(source)

🛠️ 故障排除

常见问题

1. 编码问题

   # 确保终端支持 UTF-8
   export LANG=en_US.UTF-8
   export LC_ALL=en_US.UTF-8
   

2. 颜色不显示

   # 安装 rich 扩展
   pip install termaid[rich]
   # 或使用 ASCII 模式
   termaid diagram.mmd --ascii
   

3. 图表过大

   # 调整填充
   termaid diagram.mmd --padding-x 2 --padding-y 1
   

4. 渲染失败

   # 检查 Mermaid 语法
   # 确保使用支持的图表类型
   

调试模式

import termaid
import logging

# 启用调试日志
logging.basicConfig(level=logging.DEBUG)

# 或查看内部状态
diagram = termaid.parse_mermaid(source)
print(f"图表类型: {diagram.type}")
print(f"节点数: {len(diagram.nodes)}")

📚 学习资源

官方链接

• GitHub: https://github.com/fasouto/termaid
• 在线试用: https://termaid.com
• PyPI: https://pypi.org/project/termaid/

相关工具

• Mermaid.js - 原始 Mermaid 库
• mermaid-ascii - Go 实现的终端渲染
• beautiful-mermaid - TypeScript 实现

最佳实践

1. 保持简单：终端图表适合简单架构
2. 使用主题：选择合适的主题提高可读性
3. ASCII 备用：为不支持 Unicode 的环境提供回退
4. 缓存结果：重复使用的图表可以缓存渲染结果

🎯 适用场景

推荐使用

• ✅ 终端文档和演示
• ✅ CI/CD 日志可视化
• ✅ SSH 远程架构查看
• ✅ TUI 应用集成
• ✅ 代码生成工具

不推荐使用

• ❌ 复杂的多层图表
• ❌ 需要精确布局的场景
• ❌ 需要交互式编辑
• ❌ 打印输出（分辨率不足）

📈 扩展可能性

1. 自定义主题

# 创建自定义颜色主题
custom_theme = {
    "node_color": "#FF5733",
    "edge_color": "#33FF57",
    "label_color": "#FFFFFF"
}

2. 导出格式

# 导出为其他格式
def export_as_html(mermaid_source, termaid_output):
    html = f"""
    

        
{termaid_output}
        

            
Mermaid 源代码
            
{mermaid_source}
        
    
    """
    return html

3. 集成其他工具

# 与 Graphviz 结合
termaid diagram.mmd | dot -Tpng > diagram.png

许可证: MIT
Python 要求: >= 3.11
作者: Fabio Souto (@fasouto)
项目状态: Alpha（积极开发中）