# 用户指南

## 简介

MermaidTrace 弥合了代码执行与架构可视化之间的鸿沟。与静态分析工具不同，它追踪的是**实际**的运行时调用，为您提供系统行为的真实写照。

## 工作原理

1.  **装饰**：在您希望出现在图表中的函数上添加 `@trace`。
2.  **拦截**：当函数运行时，MermaidTrace 记录一个“请求”事件 (`->>`)。
3.  **执行**：函数体执行。
4.  **返回**：MermaidTrace 记录一个“返回”事件 (`-->>`) 以及返回值。
5.  **可视化**：事件被写入 `.mmd` 文件，渲染为时序图。

## 并发与 Trace ID

MermaidTrace 专为现代异步应用程序打造。它通过为每个流程分配唯一的 **Trace ID** 来自动处理并发请求。

- **自动生成**：当流程开始时（如果不存在），会生成一个新的 Trace ID。
- **传播**：ID 存储在 `contextvars` 中，确保它自动跟随 `await` 调用和后台任务。
- **FastAPI**：中间件会自动从 Headers 中提取 `X-Trace-ID` 或生成一个新的。

*注意：目前，所有追踪都写入同一个文件。如果需要，可以使用日志中的 Trace ID 过滤特定会话。*

## 上下文推断 (Context Inference)

最强大的功能之一是 **上下文推断**。

在时序图中，每个箭头都有一个 `Source`（源）和一个 `Target`（目标）。
- `Target` 很容易确定：就是被调用的函数或类。
- `Source` 很难确定：它是 *谁调用了* 该函数。

MermaidTrace 使用 Python 的 `contextvars` 来追踪“当前参与者”。

**示例：**
1.  `A` 调用 `B`。
2.  在 `A` 内部，上下文被设置为 "A"。
3.  当 `B` 被 `@trace` 装饰时，它看到上下文是 "A"，因此绘制 `A ->> B`。
4.  在 `B` 内部，上下文更新为 "B"。
5.  如果 `B` 调用 `C`，`C` 看到上下文是 "B"，因此绘制 `B ->> C`。

这意味着通常您只需要在 *入口点*（第一个函数）设置 `source`。

## CLI 查看器

要查看您的图表，请使用 CLI：

```bash
mermaid-trace serve flow.mmd --port 8000
```

这将启动本地服务器并打开浏览器。它会监控文件更改并立即自动刷新页面。
