fix: 修复保存toml时偶发的空行累计bug和注释丢失问题

src/common/toml_utils.py

@@ -4,6 +4,7 @@ TOML 工具函数
 提供 TOML 文件的格式化保存功能，确保数组等元素以美观的多行格式输出。
 """
 
+import re
 from typing import Any
 import tomlkit
 from tomlkit.items import AoT, Table, Array
@@ -54,14 +55,71 @@ def _format_toml_value(obj: Any, threshold: int, depth: int = 0) -> Any:
     return obj
 
 
-def save_toml_with_format(data: Any, file_path: str, multiline_threshold: int = 1) -> None:
-    """格式化 TOML 数据并保存到文件"""
+def _update_toml_doc(target: Any, source: Any) -> None:
+    """
+    递归合并字典，将 source 的值更新到 target 中，保留 target 的注释和格式。
+    - 已存在的键：更新值（递归处理嵌套字典）
+    - 新增的键：添加到 target
+    - 跳过 version 字段
+    """
+    if isinstance(source, list) or not isinstance(source, dict) or not isinstance(target, dict):
+        return
+
+    for key, value in source.items():
+        if key == "version":
+            continue
+        if key in target:
+            # 已存在的键：递归更新或直接赋值
+            target_value = target[key]
+            if isinstance(value, dict) and isinstance(target_value, dict):
+                _update_toml_doc(target_value, value)
+            else:
+                try:
+                    target[key] = tomlkit.item(value)
+                except (TypeError, ValueError):
+                    target[key] = value
+        else:
+            # 新增的键：添加到 target
+            try:
+                target[key] = tomlkit.item(value)
+            except (TypeError, ValueError):
+                target[key] = value
+
+
+def save_toml_with_format(
+    data: Any, file_path: str, multiline_threshold: int = 1, preserve_comments: bool = True
+) -> None:
+    """
+    格式化 TOML 数据并保存到文件。
+
+    Args:
+        data: 要保存的数据（dict 或 tomlkit 文档）
+        file_path: 保存路径
+        multiline_threshold: 数组多行格式化阈值，-1 表示不格式化
+        preserve_comments: 是否保留原文件的注释和格式（默认 True）
+            若为 True 且文件已存在且 data 不是 tomlkit 文档，会先读取原文件，再将 data 合并进去
+    """
+    import os
+    from tomlkit import TOMLDocument
+
+    # 如果需要保留注释、文件存在、且 data 不是已有的 tomlkit 文档，先读取原文件再合并
+    if preserve_comments and os.path.exists(file_path) and not isinstance(data, TOMLDocument):
+        with open(file_path, "r", encoding="utf-8") as f:
+            doc = tomlkit.load(f)
+        _update_toml_doc(doc, data)
+        data = doc
+
     formatted = _format_toml_value(data, multiline_threshold) if multiline_threshold >= 0 else data
+    output = tomlkit.dumps(formatted)
+    # 规范化：将 3+ 连续空行压缩为 1 个空行，防止空行累积
+    output = re.sub(r'\n{3,}', '\n\n', output)
     with open(file_path, "w", encoding="utf-8") as f:
-        tomlkit.dump(formatted, f)
+        f.write(output)
 
 
 def format_toml_string(data: Any, multiline_threshold: int = 1) -> str:
     """格式化 TOML 数据并返回字符串"""
     formatted = _format_toml_value(data, multiline_threshold) if multiline_threshold >= 0 else data
-    return tomlkit.dumps(formatted)
+    output = tomlkit.dumps(formatted)
+    # 规范化：将 3+ 连续空行压缩为 1 个空行，防止空行累积
+    return re.sub(r'\n{3,}', '\n\n', output)