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 LR\n A --> B --> C"))
# 彩色渲染
from termaid import render_rich
from rich import print as rprint
rprint(render_rich("graph LR\n A --> B", theme="terra"))
# Textual TUI 组件
from termaid import MermaidWidget
widget = MermaidWidget("graph LR\n 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
🎨 主题系统
内置主题
- default - 青色节点，黄色箭头，白色标签
- terra - 温暖的地球色调（棕色、橙色）
- neon - 霓虹色调（品红色节点，绿色箭头）
- mono - 单色（白色/灰色）
- amber - 琥珀色 CRT 风格
- phosphor - 绿色磷光终端风格
使用主题
termaid diagram.mmd --theme neon
termaid diagram.mmd --theme phosphor
rprint(render_rich(source, theme="amber"))
🔧 CLI 选项
| 选项 | 描述 |
|---|---|
--tui | 交互式 TUI 查看器 |
--ascii | ASCII 纯文本输出（无 Unicode） |
--theme NAME | 颜色主题：default, terra, neon, mono, amber, phosphor |
--padding-x N | 框内水平填充（默认：4） |
--padding-y N | 框内垂直填充（默认：2） |
--sharp-edges | 边角使用锐角而非圆角 |
💡 使用场景
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 LR\n 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 TD\n Error[渲染错误] --> Help[检查语法]")
性能优化
# 预加载常用图表
from termaid import render
import functools
@functools.lru_cache(maxsize=100)
def cached_render(source: str) -> str:
"""缓存渲染结果"""
return render(source)
🛠️ 故障排除
常见问题
-
编码问题
# 确保终端支持 UTF-8 export LANG=en_US.UTF-8 export LC_ALL=en_US.UTF-8 -
颜色不显示
# 安装 rich 扩展 pip install termaid[rich] # 或使用 ASCII 模式 termaid diagram.mmd --ascii -
图表过大
# 调整填充 termaid diagram.mmd --padding-x 2 --padding-y 1 -
渲染失败
# 检查 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 实现
最佳实践
- 保持简单：终端图表适合简单架构
- 使用主题：选择合适的主题提高可读性
- ASCII 备用：为不支持 Unicode 的环境提供回退
- 缓存结果：重复使用的图表可以缓存渲染结果
🎯 适用场景
推荐使用
- ✅ 终端文档和演示
- ✅ 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"""
<div class="terminal-diagram">
<pre>{termaid_output}</pre>
<details>
<summary>Mermaid 源代码</summary>
<pre>{mermaid_source}</pre>
</details>
</div>
"""
return html
3. 集成其他工具
# 与 Graphviz 结合
termaid diagram.mmd | dot -Tpng > diagram.png
许可证: MIT
Python 要求: >= 3.11
作者: Fabio Souto (@fasouto)
项目状态: Alpha（积极开发中）