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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mermaid-trace
-Version: 0.4.0
+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
@@ -63,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.
@@ -82,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
@@ -151,15 +167,14 @@ Visualize your generated `.mmd` files instantly:
 mermaid-trace serve my_flow.mmd
 ```
 
-## 📂 Documentation
-
-- [English Documentation](docs/en/USER_GUIDE.md)
-- [中文文档](README_CN.md)
+---
 
 ## 🤝 Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
 
+---
+
 ## 📄 License
 
 MIT

{mermaid_trace-0.4.0 → 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/USER_GUIDE.md)
-- [中文文档](README_CN.md)
+---
 
 ## 🤝 Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
 
+---
+
 ## 📄 License
 
 MIT

{mermaid_trace-0.4.0 → 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/USER_GUIDE.md)
-- [中文文档](docs/zh/USER_GUIDE.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.4.0 → mermaid_trace-0.4.1}/docs/en/CHANGELOG.md

@@ -5,6 +5,22 @@ 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

{mermaid_trace-0.4.0 → 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.

{mermaid_trace-0.4.0 → mermaid_trace-0.4.1}/docs/zh/API.md

@@ -1,5 +1,20 @@
 # 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`
@@ -54,6 +69,73 @@ def configure_flow(
 - `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)

{mermaid_trace-0.4.0 → mermaid_trace-0.4.1}/docs/zh/CHANGELOG.md

@@ -5,6 +5,22 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
 并且本项目遵守 [Semantic Versioning](https://semver.org/lang/zh-CN/)（语义化版本控制）。
 
+## [0.4.1] - 2026-01-26
+
+### 新增
+- **抽象事件模型**: 引入了 `Event` 抽象基类和 `BaseFormatter` 接口，以提高扩展性并支持多种输出格式。
+- **增强型异步处理器**: 添加了队列大小限制 (`queue_size=1000`) 和丢弃策略，以防止高流量场景下的内存溢出。
+- **改进的异常处理**: 增强了异常日志记录，包括完整的堆栈跟踪和错误详情。
+
+### 修复
+- **上下文丢失问题**: 修复了 `LogContext._get_store()` 方法，在没有上下文时正确初始化 `contextvar`，防止后续 `LookupError` 异常。
+- **并发安全性**: 在 `MermaidFileHandler._write_header()` 中添加了线程锁，以防止在 `delay=True` 时写入文件头的竞争条件。
+
+### 改进
+- **架构设计**: 通过引入抽象接口解耦组件，减少了 `FlowEvent` 与 Mermaid 特定格式之间的紧密耦合。
+- **测试覆盖率**: 通过为新抽象类添加全面的测试用例，将测试覆盖率提高到 90.17%。
+- **代码可维护性**: 为所有代码文件添加了详细的英文注释，提高了可读性和开发体验。
+
 ## [0.4.0] - 2026-01-26
 
 ### 新增

mermaid_trace-0.4.1/docs/zh/UPDATE_SUMMARY.md

@@ -0,0 +1,99 @@
+# 文档与代码注释更新汇总
+
+## 版本: v0.4.1
+
+### 一、文档更新
+
+#### 1. 变更日志 (CHANGELOG.md)
+
+- **英文版本**: 新增 v0.4.1 版本记录，包含所有新增功能和修复
+- **中文版本**: 同步更新中文变更日志，确保与英文内容一致
+
+#### 2. API 参考文档 (API.md)
+
+- **英文版本**:
+
+  - 新增 `Event` 抽象基类文档
+  - 新增 `BaseFormatter` 抽象基类文档
+  - 更新 `FlowEvent` 文档，显示其继承关系
+  - 更新 `AsyncMermaidHandler` 文档，包含队列大小限制和丢弃策略
+  - 更新 `MermaidFileHandler` 文档，包含线程安全说明
+  - 新增 `MermaidFormatter` 继承关系说明
+- **中文版本**: 同步更新所有中文 API 文档，确保术语翻译准确，内容与英文一致
+
+### 二、代码注释更新 (docs/zh/code_comments/)
+
+#### 1. 核心模块 (core/)
+
+- **context.md**: 更新 `_get_store` 方法注释，说明新增的 `contextvar` 初始化逻辑，解决上下文丢失问题
+- **events.md**: 新增 `Event` 抽象基类注释，更新 `FlowEvent` 注释，显示其继承关系和新增的抽象方法实现
+- **formatter.md**: 新增 `BaseFormatter` 抽象基类注释，更新 `MermaidFormatter` 注释，说明其继承关系和新增的 `format_event` 方法
+
+#### 2. 处理器模块 (handlers/)
+
+- **async_handler.md**: 更新异步处理器注释，说明新增的队列大小限制 (默认 1000) 和丢弃策略，以及改进的 `emit` 方法
+- **mermaid_handler.md**: 更新 `_write_header` 方法注释，说明新增的线程锁机制，确保并发安全
+
+### 三、关键功能变更说明
+
+#### 1. 抽象层设计
+
+- 引入 `Event` 抽象基类，为不同类型的事件提供通用接口
+- 引入 `BaseFormatter` 抽象基类，为不同输出格式的格式化器提供通用接口
+- 改进组件间的解耦，降低 `FlowEvent` 与 Mermaid 特定格式的耦合度
+
+#### 2. 并发安全性
+
+- 修复 `MermaidFileHandler._write_header` 方法的并发安全问题，添加线程锁保护
+- 改进 `LogContext._get_store` 方法，正确初始化 `contextvar`，解决上下文丢失问题
+
+#### 3. 性能优化
+
+- 为 `AsyncMermaidHandler` 添加队列大小限制 (默认 1000)，防止内存溢出
+- 实现智能丢弃策略，在队列满时避免阻塞主程序
+- 添加超时机制，确保日志记录不会长时间阻塞应用程序
+
+#### 4. 错误处理
+
+- 增强异常日志记录，包含完整堆栈跟踪和错误详情
+- 改进 `emit` 方法的错误处理，避免无限递归
+- 添加队列满时的警告机制，提高系统可观测性
+- 修复 `AsyncMermaidHandler.stop()` 方法中的 `queue.Full` 异常，确保在队列满时能够优雅停止
+
+### 四、质量保证
+
+#### 1. 交叉校对
+
+- 所有英文文档和中文文档进行了交叉校对，确保内容一致
+- 术语翻译统一，遵循项目现有的文档规范
+- 格式统一，保持良好的可读性
+
+#### 2. 代码注释质量
+
+- 注释准确、清晰，重点解释实现思路和设计决策
+- 避免过度注释，仅针对关键逻辑和复杂代码段添加注释
+- 遵循项目现有的注释风格
+
+### 五、更新范围
+
+| 模块       | 英文文档 | 中文文档 | 中文代码注释 |
+| ---------- | -------- | -------- | ------------ |
+| CHANGELOG  | ✅       | ✅       | ❌           |
+| API 参考   | ✅       | ✅       | ❌           |
+| 核心模块   | ❌       | ❌       | ✅           |
+| 处理器模块 | ❌       | ❌       | ✅           |
+| 集成模块   | ❌       | ❌       | ❌           |
+| 测试模块   | ✅       | ✅       | ❌           |
+
+### 六、后续建议
+
+1. **定期更新**：建议在每次版本发布时同步更新文档和代码注释
+2. **社区贡献**：鼓励社区成员参与文档翻译和注释改进
+3. **自动化检查**：考虑添加文档链接检查和格式验证工具
+4. **用户反馈**：收集用户对文档的反馈，持续改进文档质量
+
+---
+
+**更新日期**: 2026-01-26
+**更新人员**: 系统自动生成
+**更新范围**: 完整中英文文档集及代码注释

{mermaid_trace-0.4.0 → mermaid_trace-0.4.1}/docs/zh/USER_GUIDE.md

@@ -1,5 +1,18 @@
 # 用户指南
 
+## 目录
+
+- [简介](#简介)
+- [工作原理](#工作原理)
+- [并发与 Trace ID](#并发与-trace-id)
+- [上下文推断 (Context Inference)](#上下文推断-context-inference)
+- [高级配置](#高级配置)
+  - [异步模式 (性能优化)](#异步模式-性能优化)
+  - [数据捕获控制](#数据捕获控制)
+  - [显式命名](#显式命名)
+  - [灵活的 Handler 配置](#灵活的-handler-配置)
+- [CLI 查看器](#cli-查看器)
+
 ## 简介
 
 MermaidTrace 弥合了代码执行与架构可视化之间的鸿沟。与静态分析工具不同，它追踪的是**实际**的运行时调用，为您提供系统行为的真实写照。

{mermaid_trace-0.4.0 → mermaid_trace-0.4.1}/docs/zh/code_comments/src/mermaid_trace/__init__.md

@@ -118,5 +118,5 @@ except PackageNotFoundError:
 
 
 # 导出公共 API 以方便访问
-__all__ = ["trace_interaction", "trace", "configure_flow", "MermaidFileHandler", "AsyncMermaidHandler", "LogContext", "FlowEvent", "MermaidFormatter"]
+__all__ = ["trace_interaction", "trace", "configure_flow", "MermaidFileHandler", "AsyncMermaidHandler", "LogContext", "Event", "FlowEvent", "BaseFormatter", "MermaidFormatter"]
 ```