mermaid-trace 0.3.1__tar.gz → 0.4.1__tar.gz

{mermaid_trace-0.3.1 → mermaid_trace-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mermaid-trace
-Version: 0.3.1
+Version: 0.4.1
 Summary: Visualize your Python code execution flow as Mermaid Sequence Diagrams.
 Project-URL: Documentation, https://github.com/xt765/mermaid-trace#readme
 Project-URL: Changelog, https://github.com/xt765/mermaid-trace/blob/main/docs/en/CHANGELOG.md
@@ -38,6 +38,8 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development :: Debuggers
@@ -61,17 +63,31 @@ Description-Content-Type: text/markdown
 
 # MermaidTrace: The Python Logger That Draws Diagrams
 
-[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
-[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
+🌐 **Language**: [English](README.md) | [中文](README_CN.md)
+
+[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
 [![License](https://img.shields.io/github/license/xt765/mermaid-trace?style=flat-square)](LICENSE)
 [![CI Status](https://img.shields.io/github/actions/workflow/status/xt765/mermaid-trace/ci.yml?style=flat-square&label=CI)](https://github.com/xt765/mermaid-trace/actions/workflows/ci.yml)
 [![Codecov](https://img.shields.io/codecov/c/github/xt765/mermaid-trace?style=flat-square&logo=codecov)](https://codecov.io/gh/xt765/mermaid-trace)
 
+---
+
+## 📋 Overview
+
 **Stop reading logs. Start watching them.**
 
 MermaidTrace is a specialized logging tool that automatically generates [Mermaid JS](https://mermaid.js.org/) sequence diagrams from your code execution. It's perfect for visualizing complex business logic, microservice interactions, or asynchronous flows.
 
-## ✨ Features
+---
+
+## 📚 Documentation
+
+[User Guide](docs/en/USER_GUIDE.md) · [API Reference](docs/en/API.md) · [Contributing Guidelines](docs/en/CONTRIBUTING.md) · [Changelog](docs/en/CHANGELOG.md) · [License](docs/en/LICENSE)
+
+---
+
+## ✨ Key Features
 
 - **Decorator-Driven**: Just add `@trace` or `@trace_interaction` to your functions.
 - **Auto-Diagramming**: Generates `.mmd` files that can be viewed in VS Code, GitHub, or Mermaid Live Editor.
@@ -80,6 +96,8 @@ MermaidTrace is a specialized logging tool that automatically generates [Mermaid
 - **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing.
 - **CLI Tool**: Built-in viewer to preview diagrams in your browser.
 
+---
+
 ## 🚀 Quick Start
 
 ### Installation
@@ -149,15 +167,14 @@ Visualize your generated `.mmd` files instantly:
 mermaid-trace serve my_flow.mmd
 ```
 
-## 📂 Documentation
-
-- [English Documentation](docs/en/README.md)
-- [中文文档](README_CN.md)
+---
 
 ## 🤝 Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
 
+---
+
 ## 📄 License
 
 MIT

{mermaid_trace-0.3.1 → mermaid_trace-0.4.1}/README.md

@@ -1,16 +1,30 @@
 # MermaidTrace: The Python Logger That Draws Diagrams
 
-[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
-[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
+🌐 **Language**: [English](README.md) | [中文](README_CN.md)
+
+[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
 [![License](https://img.shields.io/github/license/xt765/mermaid-trace?style=flat-square)](LICENSE)
 [![CI Status](https://img.shields.io/github/actions/workflow/status/xt765/mermaid-trace/ci.yml?style=flat-square&label=CI)](https://github.com/xt765/mermaid-trace/actions/workflows/ci.yml)
 [![Codecov](https://img.shields.io/codecov/c/github/xt765/mermaid-trace?style=flat-square&logo=codecov)](https://codecov.io/gh/xt765/mermaid-trace)
 
+---
+
+## 📋 Overview
+
 **Stop reading logs. Start watching them.**
 
 MermaidTrace is a specialized logging tool that automatically generates [Mermaid JS](https://mermaid.js.org/) sequence diagrams from your code execution. It's perfect for visualizing complex business logic, microservice interactions, or asynchronous flows.
 
-## ✨ Features
+---
+
+## 📚 Documentation
+
+[User Guide](docs/en/USER_GUIDE.md) · [API Reference](docs/en/API.md) · [Contributing Guidelines](docs/en/CONTRIBUTING.md) · [Changelog](docs/en/CHANGELOG.md) · [License](docs/en/LICENSE)
+
+---
+
+## ✨ Key Features
 
 - **Decorator-Driven**: Just add `@trace` or `@trace_interaction` to your functions.
 - **Auto-Diagramming**: Generates `.mmd` files that can be viewed in VS Code, GitHub, or Mermaid Live Editor.
@@ -19,6 +33,8 @@ MermaidTrace is a specialized logging tool that automatically generates [Mermaid
 - **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing.
 - **CLI Tool**: Built-in viewer to preview diagrams in your browser.
 
+---
+
 ## 🚀 Quick Start
 
 ### Installation
@@ -88,15 +104,14 @@ Visualize your generated `.mmd` files instantly:
 mermaid-trace serve my_flow.mmd
 ```
 
-## 📂 Documentation
-
-- [English Documentation](docs/en/README.md)
-- [中文文档](README_CN.md)
+---
 
 ## 🤝 Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
 
+---
+
 ## 📄 License
 
 MIT

{mermaid_trace-0.3.1 → mermaid_trace-0.4.1}/README_CN.md

@@ -1,16 +1,41 @@
 # MermaidTrace: 能画图的 Python 日志工具
 
-[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
-[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
+🌐 **语言**: [English](README.md) | [中文](README_CN.md)
+
+[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
 [![License](https://img.shields.io/github/license/xt765/mermaid-trace?style=flat-square)](LICENSE)
 [![CI Status](https://img.shields.io/github/actions/workflow/status/xt765/mermaid-trace/ci.yml?style=flat-square&label=CI)](https://github.com/xt765/mermaid-trace/actions/workflows/ci.yml)
 [![Codecov](https://img.shields.io/codecov/c/github/xt765/mermaid-trace?style=flat-square&logo=codecov)](https://codecov.io/gh/xt765/mermaid-trace)
 
+---
+
+## 📋 概述
+
 **别再干读日志了。开始“看”懂它们吧。**
 
 MermaidTrace 是一个专业的日志工具，能从你的代码执行中自动生成 [Mermaid JS](https://mermaid.js.org/) 时序图。它非常适合可视化复杂的业务逻辑、微服务交互或异步流程。
 
-## ✨ 特性
+---
+
+## 📚 文档
+
+### 主要文档
+
+[用户指南](docs/zh/USER_GUIDE.md) · [API 参考](docs/zh/API.md) · [贡献指南](docs/zh/CONTRIBUTING.md) · [更新日志](docs/zh/CHANGELOG.md) · [许可证](docs/zh/LICENSE)
+
+### 代码注释文档
+
+| 类别               | 链接                                                                                                                                                                                                                                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **核心模块** | [Context](docs/zh/code_comments/src/mermaid_trace/core/context.md) · [Decorators](docs/zh/code_comments/src/mermaid_trace/core/decorators.md) · [Events](docs/zh/code_comments/src/mermaid_trace/core/events.md) · [Formatter](docs/zh/code_comments/src/mermaid_trace/core/formatter.md) |
+| **处理器**   | [Async Handler](docs/zh/code_comments/src/mermaid_trace/handlers/async_handler.md) · [Mermaid Handler](docs/zh/code_comments/src/mermaid_trace/handlers/mermaid_handler.md)                                                                                                           |
+| **集成**     | [FastAPI](docs/zh/code_comments/src/mermaid_trace/integrations/fastapi.md)                                                                                                                                                                                                          |
+| **其他**     | [init](docs/zh/code_comments/src/mermaid_trace/__init__.md) · [CLI](docs/zh/code_comments/src/mermaid_trace/cli.md)                                                                                                                                                         |
+
+---
+
+## ✨ 核心特性
 
 - **装饰器驱动**：只需在函数上添加 `@trace` 或 `@trace_interaction` 即可。
 - **自动绘图**：生成 `.mmd` 文件，可在 VS Code、GitHub 或 Mermaid Live Editor 中查看。
@@ -19,6 +44,8 @@ MermaidTrace 是一个专业的日志工具，能从你的代码执行中自动
 - **FastAPI 集成**：内置中间件，实现零配置的 HTTP 请求追踪。
 - **CLI 工具**：内置查看器，可在浏览器中即时预览图表。
 
+---
+
 ## 🚀 快速开始
 
 ### 安装
@@ -88,15 +115,14 @@ async def root():
 mermaid-trace serve my_flow.mmd
 ```
 
-## 📂 文档
-
-- [英文文档](docs/en/README.md)
-- [中文文档](README_CN.md)
+---
 
 ## 🤝 贡献
 
 欢迎贡献！详情请参阅 [CONTRIBUTING.md](docs/zh/CONTRIBUTING.md)。
 
+---
+
 ## 📄 许可证
 
 MIT

mermaid_trace-0.4.1/docs/en/API.md

@@ -0,0 +1,157 @@
+# API Reference
+
+## Table of Contents
+
+- [Core](#core)
+  - [trace / trace_interaction](#trace--trace_interaction)
+  - [configure_flow](#configure_flow)
+  - [LogContext](#logcontext)
+  - [Event (Abstract Base Class)](#event-abstract-base-class)
+  - [FlowEvent](#flowevent)
+  - [BaseFormatter (Abstract Base Class)](#baseformatter-abstract-base-class)
+  - [MermaidFormatter](#mermaidformatter)
+  - [MermaidFileHandler](#mermaidfilehandler)
+  - [AsyncMermaidHandler](#asyncmermaidhandler)
+- [Integrations](#integrations)
+  - [MermaidTraceMiddleware (FastAPI)](#mermaidtracemiddleware-fastapi)
+
+## Core
+
+### `trace` / `trace_interaction`
+
+Decorator to trace function execution. Can be used with or without arguments.
+
+```python
+# Simple usage
+@trace
+def my_func(): ...
+
+# Detailed usage
+@trace(source="Client", target="Server", action="Login", capture_args=False)
+def login(username): ...
+```
+
+**Arguments:**
+- `source` (Optional[str]): The caller participant name. If `None`, inferred from `contextvars`.
+- `target` (Optional[str]): The callee participant name. If `None`, inferred from class name (if method) or module name.
+- `name` (Optional[str]): Alias for `target`. Explicitly sets the participant name.
+- `action` (Optional[str]): Description of the interaction. If `None`, defaults to formatted function name (e.g., `process_payment` -> "Process Payment").
+- `capture_args` (bool): Whether to log arguments and return values. Defaults to `True`. Set to `False` for sensitive data.
+- `max_arg_length` (int): Maximum length of string representation for arguments. Defaults to 50.
+- `max_arg_depth` (int): Maximum depth for nested structures in argument representation. Defaults to 1.
+
+### `configure_flow`
+
+Configures the global logger to output to a Mermaid file. This should be called once at application startup.
+
+```python
+def configure_flow(
+    output_file: str = "flow.mmd",
+    handlers: Optional[List[logging.Handler]] = None,
+    append: bool = False,
+    async_mode: bool = False
+) -> logging.Logger
+```
+
+**Arguments:**
+- `output_file` (str): Path to the `.mmd` output file. Defaults to "flow.mmd".
+- `handlers` (List[logging.Handler]): Optional list of custom logging handlers. If provided, `output_file` is ignored unless you include `MermaidFileHandler` manually.
+- `append` (bool): If `True`, adds new handlers without removing existing ones. Defaults to `False`.
+- `async_mode` (bool): If `True`, uses a non-blocking background thread for logging (QueueHandler). Recommended for production. Defaults to `False`.
+
+### `LogContext`
+
+Manages execution context (like thread-local storage) to track caller/callee relationships and trace IDs across async tasks and threads.
+
+**Methods:**
+- `LogContext.current_trace_id() -> str`: Get or generate the current Trace ID.
+- `LogContext.current_participant() -> str`: Get the current active participant.
+- `LogContext.scope(data)`: Synchronous context manager to temporarily update context.
+- `LogContext.ascope(data)`: Asynchronous context manager (`async with`) to temporarily update context.
+
+### `Event` (Abstract Base Class)
+
+Abstract base class for all event types, providing a common interface for different types of events.
+
+**Methods:**
+- `get_source() -> str`: Get the source of the event.
+- `get_target() -> str`: Get the target of the event.
+- `get_action() -> str`: Get the action name of the event.
+- `get_message() -> str`: Get the message text of the event.
+- `get_timestamp() -> float`: Get the timestamp of the event.
+- `get_trace_id() -> str`: Get the trace ID of the event.
+
+### `FlowEvent`
+
+Represents a single interaction or step in the execution flow, inheriting from `Event`.
+
+**Attributes:**
+- `source` (str): The name of the participant initiating the action.
+- `target` (str): The name of the participant receiving the action.
+- `action` (str): A short, human-readable name for the operation.
+- `message` (str): The actual text label displayed on the diagram arrow.
+- `trace_id` (str): Unique identifier for the trace session.
+- `timestamp` (float): Unix timestamp of when the event occurred.
+- `is_return` (bool): Flag indicating if this is a response arrow.
+- `is_error` (bool): Flag indicating if an exception occurred.
+- `error_message` (Optional[str]): Detailed error text if `is_error` is True.
+- `params` (Optional[str]): Stringified representation of function arguments.
+- `result` (Optional[str]): Stringified representation of the return value.
+
+### `BaseFormatter` (Abstract Base Class)
+
+Abstract base class for all event formatters, providing a common interface for different output formats.
+
+**Methods:**
+- `format_event(event: Event) -> str`: Format an Event into the desired output string.
+- `format(record: logging.LogRecord) -> str`: Format a logging record containing an event.
+
+### `MermaidFormatter`
+
+Custom formatter to convert Events into Mermaid sequence diagram syntax, inheriting from `BaseFormatter`.
+
+**Methods:**
+- `format_event(event: Event) -> str`: Converts an Event into a Mermaid syntax string.
+
+### `MermaidFileHandler`
+
+A custom logging handler that writes `Event` objects to a Mermaid (.mmd) file.
+
+**Features:**
+- Thread-safe file writing using locks
+- Automatic Mermaid header management
+- Support for both overwrite and append modes
+- Delay writing support for better performance
+
+### `AsyncMermaidHandler`
+
+A non-blocking logging handler that uses a background thread to write logs.
+
+**Arguments:**
+- `handlers` (List[logging.Handler]): A list of handlers that should receive the logs from the queue.
+- `queue_size` (int): The maximum size of the queue. Default is 1000.
+
+**Features:**
+- Queue-based logging with configurable size limit
+- Built-in drop policy for when queue is full
+- Automatic queue flushing on application exit
+
+## Integrations
+
+### `MermaidTraceMiddleware` (FastAPI)
+
+Middleware for automatic HTTP request tracing. Captures request path, method, status code, and timing.
+
+```python
+from mermaid_trace.integrations.fastapi import MermaidTraceMiddleware
+
+app.add_middleware(MermaidTraceMiddleware, app_name="MyAPI")
+```
+
+**Arguments:**
+- `app`: The FastAPI/Starlette application.
+- `app_name` (str): The name of the participant representing this application in the diagram.
+
+**Headers Support:**
+- `X-Source`: If sent by the client, sets the source participant name.
+- `X-Trace-ID`: If sent, uses this ID for the trace session; otherwise generates a new UUID.

{mermaid_trace-0.3.1 → mermaid_trace-0.4.1}/docs/en/CHANGELOG.md

@@ -5,12 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-01-26
+
+### Added
+- **Abstract Event Model**: Introduced `Event` abstract base class and `BaseFormatter` interface for better extensibility and support for multiple output formats.
+- **Enhanced Async Handler**: Added queue size limit (`queue_size=1000`) with drop policy to prevent memory overflow in high-traffic scenarios.
+- **Improved Exception Handling**: Enhanced exception logging to include full stack traces and error details.
+
+### Fixed
+- **Context Loss Issue**: Fixed `LogContext._get_store()` method to properly initialize `contextvar` when no context exists, preventing subsequent `LookupError` exceptions.
+- **Concurrency Safety**: Added thread locks in `MermaidFileHandler._write_header()` to prevent race conditions when writing file headers with `delay=True`.
+
+### Improved
+- **Architecture Design**: Decoupled components by introducing abstract interfaces, reducing tight coupling between `FlowEvent` and Mermaid-specific formatting.
+- **Test Coverage**: Increased test coverage to 90.17% by adding comprehensive test cases for the new abstract classes.
+- **Code Maintainability**: Added detailed English annotations to all code files, improving readability and developer experience.
+
+## [0.4.0] - 2026-01-26
+
+### Added
+- **Async Mode**: Introduced `async_mode=True` in `configure_flow` to offload log writing to a background thread, eliminating I/O blocking in the main application loop.
+- **Data Privacy**: Added `capture_args=False` to `@trace` to prevent sensitive arguments from being logged.
+- **Argument Truncation**: Added `max_arg_length` and `max_arg_depth` to `@trace` to control the size of logged data structures.
+- **Explicit Naming**: Added `name` (or `target` alias) parameter to `@trace` for explicitly setting the participant name, overriding automatic inference.
+- **Flexible Configuration**: Updated `configure_flow` to accept a list of custom handlers and an `append` flag, allowing better integration with existing logging setups.
+
+### Improved
+- **Test Coverage**: Achieved >90% test coverage with a comprehensive new test suite covering unit, integration, and concurrency scenarios.
+- **PyPI Compliance**: Switched to dynamic versioning via `hatch-vcs` and improved package metadata and artifact inclusion.
+
 ## [0.3.1] - 2026-01-26
 
 ### Fixed
 - **CI/CD**: Resolved test coverage reporting issues in GitHub Actions by standardizing on editable installs (`pip install -e .[dev]`) across all workflows.
 - **CI/CD**: Aligned coverage configuration in `pyproject.toml` to correctly target the source directory (`src/mermaid_trace`).
 - **Docs**: Fixed badge links in README to use consistent style and valid sources.
+- **Compatibility**: Officially added support for Python 3.13 and 3.14 in project classifiers and CI workflows.
 
 ## [0.3.0] - 2026-01-26
 

{mermaid_trace-0.3.1 → mermaid_trace-0.4.1}/docs/en/CONTRIBUTING.md

@@ -29,7 +29,12 @@ The following is a set of guidelines for contributing to MermaidTrace and its pa
 
 4.  **Run tests**:
     ```bash
+    # Run all tests
     pytest
+
+    # Run tests across multiple Python versions (requires tox)
+    pip install tox
+    tox
     ```
 
 ## Styleguides
@@ -38,12 +43,17 @@ The following is a set of guidelines for contributing to MermaidTrace and its pa
 
 - All Python code is linted with `ruff`.
 - All Python code is type-checked with `mypy`.
+- We use `hatch` for build management and `hatch-vcs` for dynamic versioning.
 
 To run checks locally:
 
 ```bash
+# Using tox (recommended)
+tox -e lint
+
+# Or manually
 ruff check src tests
-mypy src
+mypy src/mermaid_trace
 ```
 
 ## Pull Requests

{mermaid_trace-0.3.1 → mermaid_trace-0.4.1}/docs/en/USER_GUIDE.md

@@ -1,5 +1,18 @@
 # User Guide
 
+## Table of Contents
+
+- [Introduction](#introduction)
+- [How It Works](#how-it-works)
+- [Concurrency & Trace IDs](#concurrency--trace-ids)
+- [Context Inference](#context-inference)
+- [Advanced Configuration](#advanced-configuration)
+  - [Async Mode (Performance)](#async-mode-performance)
+  - [Data Capture Control](#data-capture-control)
+  - [Explicit Naming](#explicit-naming)
+  - [Flexible Handler Configuration](#flexible-handler-configuration)
+- [CLI Viewer](#cli-viewer)
+
 ## Introduction
 
 MermaidTrace bridges the gap between code execution and architectural visualization. Unlike static analysis tools, it traces *actual* runtime calls, giving you a true picture of your system's behavior.
@@ -41,6 +54,47 @@ MermaidTrace uses Python's `contextvars` to track the "Current Participant".
 
 This means you usually only need to set the `source` on the *entry point* (the first function).
 
+## Advanced Configuration
+
+### Async Mode (Performance)
+For high-throughput production environments, enable `async_mode` to offload file writing to a background thread. This ensures your application's main thread is never blocked by disk I/O.
+
+```python
+configure_flow("flow.mmd", async_mode=True)
+```
+
+### Data Capture Control
+You can control how function arguments and return values are recorded to keep diagrams clean and secure.
+
+```python
+# Hide sensitive data
+@trace(capture_args=False)
+def login(password):
+    pass
+
+# Truncate long strings (default: 50 chars)
+@trace(max_arg_length=10)
+def process_large_data(data):
+    pass
+```
+
+### Explicit Naming
+If the automatic class/function name inference isn't what you want, you can explicitly name the participant.
+
+```python
+@trace(name="AuthService")  # "AuthService" will appear in the diagram
+def login():
+    pass
+```
+
+### Flexible Handler Configuration
+You can add MermaidTrace to an existing logging setup or append multiple handlers.
+
+```python
+# Append to existing handlers instead of clearing them
+configure_flow("flow.mmd", append=True)
+```
+
 ## CLI Viewer
 
 To view your diagrams, use the CLI:

mermaid_trace-0.4.1/docs/zh/API.md

@@ -0,0 +1,157 @@
+# API 参考文档
+
+## 目录
+
+- [核心功能 (Core)](#核心功能-core)
+  - [trace / trace_interaction](#trace--trace_interaction)
+  - [configure_flow](#configure_flow)
+  - [LogContext](#logcontext)
+  - [Event（抽象基类）](#event抽象基类)
+  - [FlowEvent](#flowevent)
+  - [BaseFormatter（抽象基类）](#baseformatter抽象基类)
+  - [MermaidFormatter](#mermaidformatter)
+  - [MermaidFileHandler](#mermaidfilehandler)
+  - [AsyncMermaidHandler](#asyncmermaidhandler)
+- [集成 (Integrations)](#集成-integrations)
+  - [MermaidTraceMiddleware (FastAPI)](#mermaidtracemiddleware-fastapi)
+
+## 核心功能 (Core)
+
+### `trace` / `trace_interaction`
+
+用于追踪函数执行的装饰器。可以带参数使用，也可以不带参数使用。
+
+```python
+# 简单用法
+@trace
+def my_func(): ...
+
+# 详细用法
+@trace(source="Client", target="Server", action="Login", capture_args=False)
+def login(username): ...
+```
+
+**参数：**
+- `source` (Optional[str]): 调用方参与者名称。如果为 `None`，则从 `contextvars` 推断。
+- `target` (Optional[str]): 被调用方参与者名称。如果为 `None`，则从类名（如果是方法）或模块名推断。
+- `name` (Optional[str]): `target` 的别名。显式设置参与者名称。
+- `action` (Optional[str]): 交互描述。如果为 `None`，默认为格式化后的函数名（例如 `process_payment` -> "Process Payment"）。
+- `capture_args` (bool): 是否记录参数和返回值。默认为 `True`。对于敏感数据可设置为 `False`。
+- `max_arg_length` (int): 参数字符串表示的最大长度。默认为 50。
+- `max_arg_depth` (int): 参数嵌套结构表示的最大深度。默认为 1。
+
+### `configure_flow`
+
+配置全局日志记录器以输出到 Mermaid 文件。应在应用程序启动时调用一次。
+
+```python
+def configure_flow(
+    output_file: str = "flow.mmd",
+    handlers: Optional[List[logging.Handler]] = None,
+    append: bool = False,
+    async_mode: bool = False
+) -> logging.Logger
+```
+
+**参数：**
+- `output_file` (str): `.mmd` 输出文件的路径。默认为 "flow.mmd"。
+- `handlers` (List[logging.Handler]): 可选的自定义日志处理器列表。如果提供，`output_file` 将被忽略，除非您手动包含了 `MermaidFileHandler`。
+- `append` (bool): 如果为 `True`，则添加新的处理器而不移除现有的。默认为 `False`。
+- `async_mode` (bool): 如果为 `True`，使用非阻塞后台线程进行日志记录 (QueueHandler)。推荐用于生产环境。默认为 `False`。
+
+### `LogContext`
+
+管理执行上下文（类似线程本地存储），用于在异步任务和线程之间追踪调用方/被调用方关系和 Trace ID。
+
+**方法：**
+- `LogContext.current_trace_id() -> str`: 获取或生成当前的 Trace ID。
+- `LogContext.current_participant() -> str`: 获取当前活跃的参与者。
+- `LogContext.scope(data)`: 同步上下文管理器，用于临时更新上下文。
+- `LogContext.ascope(data)`: 异步上下文管理器 (`async with`)，用于临时更新上下文。
+
+### `Event`（抽象基类）
+
+所有事件类型的抽象基类，为不同类型的事件提供通用接口。
+
+**方法：**
+- `get_source() -> str`: 获取事件的来源。
+- `get_target() -> str`: 获取事件的目标。
+- `get_action() -> str`: 获取事件的动作名称。
+- `get_message() -> str`: 获取事件的消息文本。
+- `get_timestamp() -> float`: 获取事件的时间戳。
+- `get_trace_id() -> str`: 获取事件的追踪 ID。
+
+### `FlowEvent`
+
+表示执行流程中的单个交互或步骤，继承自 `Event`。
+
+**属性：**
+- `source` (str): 发起动作的参与者名称。
+- `target` (str): 接收动作的参与者名称。
+- `action` (str): 操作的简短可读名称。
+- `message` (str): 显示在图表箭头上的实际文本标签。
+- `trace_id` (str): 追踪会话的唯一标识符。
+- `timestamp` (float): 事件发生时的 Unix 时间戳。
+- `is_return` (bool): 指示这是否为响应箭头的标志。
+- `is_error` (bool): 指示是否发生异常的标志。
+- `error_message` (Optional[str]): 如果 `is_error` 为 True，则包含详细的错误文本。
+- `params` (Optional[str]): 函数参数的字符串表示。
+- `result` (Optional[str]): 返回值的字符串表示。
+
+### `BaseFormatter`（抽象基类）
+
+所有事件格式化器的抽象基类，为不同的输出格式提供通用接口。
+
+**方法：**
+- `format_event(event: Event) -> str`: 将事件格式化为所需的输出字符串。
+- `format(record: logging.LogRecord) -> str`: 格式化包含事件的日志记录。
+
+### `MermaidFormatter`
+
+将事件转换为 Mermaid 时序图语法的自定义格式化器，继承自 `BaseFormatter`。
+
+**方法：**
+- `format_event(event: Event) -> str`: 将事件转换为 Mermaid 语法字符串。
+
+### `MermaidFileHandler`
+
+将 `Event` 对象写入 Mermaid (.mmd) 文件的自定义日志处理器。
+
+**特性：**
+- 使用锁确保线程安全的文件写入
+- 自动管理 Mermaid 文件头
+- 支持覆盖和追加两种模式
+- 支持延迟写入以提高性能
+
+### `AsyncMermaidHandler`
+
+使用后台线程写入日志的非阻塞日志处理器。
+
+**参数：**
+- `handlers` (List[logging.Handler]): 应该从队列接收日志的处理器列表。
+- `queue_size` (int): 队列的最大大小。默认为 1000。
+
+**特性：**
+- 基于队列的日志记录，具有可配置的大小限制
+- 队列已满时的内置丢弃策略
+- 应用程序退出时自动刷新队列
+
+## 集成 (Integrations)
+
+### `MermaidTraceMiddleware` (FastAPI)
+
+用于自动 HTTP 请求追踪的中间件。捕获请求路径、方法、状态码和耗时。
+
+```python
+from mermaid_trace.integrations.fastapi import MermaidTraceMiddleware
+
+app.add_middleware(MermaidTraceMiddleware, app_name="MyAPI")
+```
+
+**参数：**
+- `app`: FastAPI/Starlette 应用程序实例。
+- `app_name` (str): 在图表中代表此应用程序的参与者名称。
+
+**Headers 支持：**
+- `X-Source`: 如果客户端发送此 Header，则设置源参与者名称。
+- `X-Trace-ID`: 如果发送此 Header，则使用此 ID 进行追踪会话；否则生成一个新的 UUID。