docs: update docs, comments and blog for v0.6.2

Author: xt765

README.md

@@ -211,13 +211,11 @@ login("admin")
 Run the built-in CLI tool to preview in real-time (with hot-reload):
 
 ```bash
-# Basic preview
+# Preview a single file (Auto-reload, Pan/Zoom supported)
 mermaid-trace serve my_flow.mmd
 
-# Master mode (Directory browsing, zoom, multi-file switching)
-mermaid-trace serve . --master
-# Or preview a specific file in Master mode
-mermaid-trace serve .\mermaid_diagrams\examples\08-log-rotation.mmd --master
+# Preview a directory (File browser, Multi-file switching)
+mermaid-trace serve .
 ```
 
 ### 🔗 LangChain Integration

README_CN.md

@@ -235,13 +235,11 @@ login("admin")
 运行代码后，使用内置 CLI 工具实时预览（支持热重载）：
 
 ```bash
-# 基础预览
+# 预览单个文件（支持热重载、缩放平移）
 mermaid-trace serve my_flow.mmd
 
-# Master 模式 (支持目录浏览、缩放、多文件切换)
-mermaid-trace serve . --master
-# 或者在 Master 模式下预览特定文件
-mermaid-trace serve .\mermaid_diagrams\examples\08-log-rotation.mmd --master
+# 预览目录（支持文件浏览、多文件切换）
+mermaid-trace serve .
 ```
 
 ### 🔗 LangChain 集成

docs/zh/BLOG.md

@@ -0,0 +1,61 @@
+# MermaidTrace v0.6.2 发布：统一预览体验与分布式追踪支持
+
+**日期**: 2026-02-24  
+**作者**: 玄同765
+
+我们很高兴地宣布 MermaidTrace v0.6.2 正式发布！本次更新主要集中在统一命令行工具体验、增强 Web 预览功能以及扩展高级应用场景。
+
+## 🚀 核心亮点
+
+### 1. 统一的 CLI 预览体验
+
+在之前的版本中，我们提供了基础的 `http.server` 预览和基于 FastAPI 的 `--master` 模式预览。这种区分不仅增加了用户的学习成本，也导致了功能体验的不一致。
+
+在 v0.6.2 中，我们彻底重构了 CLI：
+
+- **单一入口**：现在只需运行 `mermaid-trace serve`，无论目标是单个文件还是目录，都会默认启动增强型 Web 服务器。
+- **全功能体验**：即使只预览一个简单的脚本输出，也能享受到**实时热重载**、**交互式缩放/平移**以及**美观的 UI**。
+- **智能降级**：如果未安装 `fastapi` 和 `uvicorn`，CLI 会给出清晰的安装提示（`pip install mermaid-trace[server]`）。
+
+```bash
+# 预览单个文件（实时刷新）
+mermaid-trace serve my_trace.mmd
+
+# 预览项目目录（文件浏览器）
+mermaid-trace serve .
+```
+
+### 2. 分布式追踪模拟
+
+随着微服务架构的普及，跨服务的调用追踪变得至关重要。我们在 `examples/10_distributed_trace_simulation.py` 中新增了一个完整的分布式追踪示例，演示了如何：
+
+- 在服务间传递 Trace ID。
+- 使用 `MermaidTrace` 记录跨服务的调用链路。
+- 生成包含多个服务的统一时序图。
+
+### 3. LangChain 集成增强
+
+我们优化了 `LangChain` 集成模块，使其更加健壮和易用：
+
+- **Mock 模式**：即使没有安装 `langchain` 库，用户也可以运行示例代码体验集成效果。
+- **类型安全**：修复了与 `langchain-core` 的类型兼容性问题，通过了严格的 Mypy 检查。
+
+### 4. 渲染引擎修复
+
+针对 Python 对象表示中可能包含特殊字符（如 `<User object at 0x...>` 中的 `<` 和 `>`）导致 Mermaid 语法解析错误的问题，我们引入了自动 HTML 实体转义机制。现在的图表渲染更加稳定，不再受特殊字符干扰。
+
+## 📚 下一步计划
+
+我们将继续探索更多高级场景，包括：
+
+- **性能分析视图**：在时序图中集成函数执行耗时热力图。
+- **更丰富的框架支持**：计划增加对 Django 和 Flask 的原生支持。
+
+感谢所有社区贡献者的支持！欢迎在 GitHub 上提交 Issue 或 PR。
+
+---
+
+*立即升级体验：*
+```bash
+pip install -U mermaid-trace[server]
+```

docs/zh/UPDATE_LOG.md

@@ -1,5 +1,30 @@
 # 更新日志 (UPDATE_LOG)
 
+## [2026-02-24] - CLI 重构、Web 预览增强与生态扩展
+
+### 核心架构升级
+- **CLI 统一重构**: 
+  - 彻底重写了命令行接口，废弃了基于 `http.server` 的简易实现，统一使用基于 FastAPI 的增强型服务器。
+  - 移除了 `--master` 参数，现在 `mermaid-trace serve` 默认开启全功能 Web 预览（支持热重载、缩放、平移）。
+  - 支持单文件模式：`mermaid-trace serve file.mmd` 也能享受完整的 Web UI 体验。
+- **Mermaid 渲染修复**: 
+  - 修复了 Python 对象表示（如 `<User>`）包含特殊字符导致 Mermaid 语法解析错误的问题。
+  - 实现了 HTML 实体转义机制，确保 `<`、`>` 等字符在图表中正确显示。
+
+### 生态集成与示例
+- **LangChain 集成增强**: 
+  - 优化了 `examples/09_langchain_integration.py`，支持在未安装 LangChain 环境下的 Mock 运行模式，方便用户体验。
+  - 修复了类型检查问题，确保集成代码的健壮性。
+- **新增高级示例**:
+  - `10_distributed_trace_simulation.py`: 演示了如何在分布式系统中传递 Trace Context。
+  - `11_custom_masking.py`: 展示了如何自定义数据脱敏逻辑（如递归脱敏）。
+  - `12_config_from_file.py`: 演示了从 JSON 文件加载配置。
+
+### 文档与规范
+- **中英文文档同步**: 更新了 `README` 和 `USER_GUIDE`，反映了 CLI 的最新用法。
+- **代码注释**: 全面更新了 `cli.py` 和 `server.py` 的中文代码注释，详细解释了服务器实现原理。
+- **依赖管理**: 在 `pyproject.toml` 中新增了 `server` extras，方便用户一键安装服务器依赖 (`pip install mermaid-trace[server]`)。
+
 ## [2026-02-02] - QA 强化与文档精化 (Refinement)
 
 ### 代码质量强化

examples/01_basic_usage.py

@@ -53,5 +53,9 @@ def main() -> None:
 if __name__ == "__main__":
     print("Running basic example...")
     main()
-    print("Done! Open 'basic_flow.mmd' to see the diagram.")
+    print("Done! Open 'mermaid_diagrams/examples/basic_flow.mmd' to see the diagram.")
     print("Check the file content to verify 'password' and 'secret_key' are masked!")
+    print(
+        "\n💡 TIP: Run the live preview server to see the diagram update in real-time:"
+    )
+    print("        mermaid-trace serve mermaid_diagrams/examples/basic_flow.mmd")

examples/09_langchain_integration.py

@@ -26,10 +26,10 @@
 
 def demo_with_mock_langchain() -> None:
     """
-    Since we don't want to require langchain-core to run this example,
-    we mock the behavior of a LangChain chain calling the handler.
+    Mock behavior of a LangChain chain calling the handler.
+    Used when langchain is not installed.
     """
-    print("🚀 Starting LangChain Mock Trace...")
+    print("🚀 Starting LangChain Mock Trace (No langchain installed)...")
 
     # Initialize the handler
     handler = MermaidTraceCallbackHandler(host_name="MyApp")
@@ -67,25 +67,59 @@ def __init__(self) -> None:
     print("--- Chain End ---")
     handler.on_chain_end(outputs={"answer": "MermaidTrace is a visualization tool."})
 
-    print(
-        "\n✅ Done! Check 'mermaid_diagrams/examples/langchain_trace.mmd' for the result."
-    )
+
+def demo_with_real_langchain() -> None:
+    """
+    Runs a real LangChain chain if dependencies are present.
+    """
+    try:
+        from langchain_openai import ChatOpenAI  # type: ignore
+        from langchain_core.prompts import ChatPromptTemplate
+        from langchain_core.output_parsers import StrOutputParser
+    except ImportError:
+        print("❌ LangChain dependencies missing for real demo.")
+        return
+
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        print("⚠️  OPENAI_API_KEY not found. Skipping real API call.")
+        print("   Run: set OPENAI_API_KEY=sk-... to try the real demo.")
+        # Fallback to mock if no key
+        demo_with_mock_langchain()
+        return
+
+    print("🚀 Starting REAL LangChain Trace...")
+
+    # 1. Setup Chain
+    handler = MermaidTraceCallbackHandler(host_name="LangChainApp")
+    llm = ChatOpenAI(api_key=api_key, model="gpt-3.5-turbo")
+    prompt = ChatPromptTemplate.from_template("Tell me a short joke about {topic}")
+    chain = prompt | llm | StrOutputParser()
+
+    # 2. Invoke with Handler
+    print("Invoking chain...")
+    result = chain.invoke({"topic": "debugging"}, config={"callbacks": [handler]})
+    print(f"Result: {result}")
 
 
 if __name__ == "__main__":
-    demo_with_mock_langchain()
+    # Check for LangChain availability
+    try:
+        import langchain_core  # noqa: F401
+        import langchain_openai  # noqa: F401
+
+        HAS_LANGCHAIN = True
+    except ImportError:
+        HAS_LANGCHAIN = False
+
+    if HAS_LANGCHAIN:
+        demo_with_real_langchain()
+    else:
+        demo_with_mock_langchain()
+        print(
+            "\n💡 TIP: Install 'langchain-openai' and set OPENAI_API_KEY to run the real demo!"
+        )
 
-    # Instructions for real LangChain usage:
-    """
-    # To use with real LangChain:
-    from langchain_openai import ChatOpenAI
-    from langchain_core.prompts import ChatPromptTemplate
-    
-    handler = MermaidTraceCallbackHandler()
-    llm = ChatOpenAI()
-    prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
-    chain = prompt | llm
-    
-    # Just pass the handler to the invoke method
-    chain.invoke({"topic": "bears"}, config={"callbacks": [handler]})
-    """
+    print(
+        "\n✅ Done! Check 'mermaid_diagrams/examples/langchain_trace.mmd' for the result."
+    )

examples/10_distributed_trace_simulation.py

@@ -0,0 +1,97 @@
+"""
+Distributed Tracing Simulation.
+Demonstrates:
+1. Simulating a microservices architecture (Service A calling Service B).
+2. Propagating the Trace ID across service boundaries (e.g., via HTTP headers).
+3. Linking distributed logs into a single coherent Mermaid diagram.
+"""
+
+import time
+import uuid
+from typing import Dict, Any
+from mermaid_trace import trace, configure_flow
+from mermaid_trace.core.context import LogContext
+
+# Setup tracing to a single file to see the full picture
+configure_flow("mermaid_diagrams/examples/distributed_trace.mmd")
+
+
+# --- Simulated Network Layer ---
+
+
+class NetworkClient:
+    """
+    Simulates an HTTP client that automatically injects the current Trace ID header.
+    """
+
+    @trace(source="ServiceA", target="Network", action="HTTP POST")
+    def post(self, url: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        # 1. Get current trace ID
+        current_trace_id = LogContext.current_trace_id()
+
+        # 2. Inject into headers (simulation)
+        headers = {"X-Trace-ID": current_trace_id}
+        print(f"[Network] Sending request to {url} with Trace ID: {current_trace_id}")
+
+        # 3. Simulate network call to Service B
+        if url == "http://service-b/api/process":
+            return service_b_entrypoint(headers, data)
+        return {"error": "404 Not Found"}
+
+
+# --- Service B (The Called Service) ---
+
+
+@trace(source="Network", target="ServiceB", action="Handle Request")
+def service_b_entrypoint(
+    headers: Dict[str, str], payload: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Simulates the entry point (e.g., FastAPI middleware) of Service B.
+    It extracts the Trace ID and restores the context.
+    """
+    # 1. Extract Trace ID from headers
+    incoming_trace_id = headers.get("X-Trace-ID")
+
+    if incoming_trace_id:
+        # 2. RESTORE CONTEXT: Important!
+        # This links Service B's actions to the original trace started in Service A.
+        LogContext.set_trace_id(incoming_trace_id)
+        print(f"[ServiceB] Resumed context with Trace ID: {incoming_trace_id}")
+    else:
+        # Fallback: Start a new trace if no ID provided
+        new_id = str(uuid.uuid4())
+        LogContext.set_trace_id(new_id)
+        print(f"[ServiceB] No Trace ID found, started new: {new_id}")
+
+    # 3. Call internal business logic
+    return process_data(payload)
+
+
+@trace(target="ServiceB.Logic")
+def process_data(data: Dict[str, Any]) -> Dict[str, Any]:
+    time.sleep(0.1)
+    return {"status": "processed", "result": f"Processed {data['item']}"}
+
+
+# --- Service A (The Caller Service) ---
+
+
+@trace(source="Client", target="ServiceA", action="Start Job")
+def run_job() -> None:
+    client = NetworkClient()
+
+    print("[ServiceA] Starting job...")
+    item = {"item": "Order-123", "amount": 99.9}
+
+    # This call will propagate the trace ID internally via our simulated client
+    response = client.post("http://service-b/api/process", item)
+
+    print(f"[ServiceA] Got response: {response}")
+
+
+if __name__ == "__main__":
+    print("Simulating distributed tracing between Service A and Service B...")
+    run_job()
+    print("\nCheck 'mermaid_diagrams/examples/distributed_trace.mmd'.")
+    print("You should see a continuous flow from Client -> ServiceA -> ServiceB.")