Add Comments

ReportEngine/nodes/chapter_generation_node.py

@@ -64,6 +64,7 @@ class ChapterContentError(ValueError):
         narrative_characters: int = 0,
         non_heading_blocks: int = 0,
     ):
+        """保存本次异常的正文特征，供重试与兜底策略参考。"""
         super().__init__(message)
         self.chapter_payload: Optional[Dict[str, Any]] = chapter
         self.body_characters: int = int(body_characters or 0)
@@ -1018,6 +1019,7 @@ class ChapterGenerationNode(BaseNode):
         """
 
         def walk(node: Any) -> int:
+            """递归遍历叙述性节点，忽略图表/目录等非正文结构"""
             if node is None:
                 return 0
             if isinstance(node, list):

ReportEngine/renderers/chart_to_svg.py

@@ -797,6 +797,7 @@ class ChartToSVGConverter:
             colors = self._get_colors(datasets)
 
             def _safe_radius(raw) -> float:
+                """将输入半径安全转为浮点并设置最小阈值，避免气泡完全消失"""
                 try:
                     val = float(raw)
                     return max(val, 0.5)

ReportEngine/renderers/html_renderer.py

@@ -1764,6 +1764,7 @@ class HTMLRenderer:
     ) -> str:
         """为词云提供表格兜底，避免WordCloud渲染失败后页面空白"""
         def _collect_items(raw: Any) -> list[dict]:
+            """将多种词云输入格式（数组/对象/元组/纯文本）规整为统一的词条列表"""
             collected: list[dict] = []
             if isinstance(raw, list):
                 for item in raw:
@@ -1812,6 +1813,7 @@ class HTMLRenderer:
             return ""
 
         def _format_weight(value: Any) -> str:
+            """统一格式化权重，支持百分比/数值与字符串回退"""
             if isinstance(value, (int, float)) and not isinstance(value, bool):
                 if 0 <= value <= 1.5:
                     return f"{value * 100:.1f}%"

ReportEngine/renderers/pdf_renderer.py

@@ -667,6 +667,7 @@ class PDFRenderer:
                 fallback_pattern = rf'<div class="chart-fallback"([^>]*data-widget-id="{re.escape(widget_id)}"[^>]*)>'
 
                 def _hide_fallback(m: re.Match) -> str:
+                    """为匹配到的图表fallback添加隐藏类，防止PDF中重复渲染"""
                     tag = m.group(0)
                     if 'svg-hidden' in tag:
                         return tag
@@ -712,6 +713,7 @@ class PDFRenderer:
             fallback_pattern = rf'<div class="chart-fallback"([^>]*data-widget-id="{re.escape(widget_id)}"[^>]*)>'
 
             def _hide_fallback(m: re.Match) -> str:
+                """匹配词云表格兜底并打上隐藏标记，避免SVG/图片重复显示"""
                 tag = m.group(0)
                 if 'svg-hidden' in tag:
                     return tag

ReportEngine/utils/chart_validator.py

@@ -87,7 +87,7 @@ class ChartValidator:
     }
 
     def __init__(self):
-        pass
+        """初始化验证器并预留缓存结构，便于后续复用验证/修复结果"""
 
     def validate(self, widget_block: Dict[str, Any]) -> ValidationResult:
         """
@@ -136,6 +136,7 @@ class ChartValidator:
 
         # 检测是否使用了{x, y}形式的数据点（通常用于时间轴/散点）
         def contains_object_points(ds_list: List[Any] | None) -> bool:
+            """检查数据集中是否包含以x/y键表示的对象点，用于切换验证分支"""
             if not isinstance(ds_list, list):
                 return False
             for point in ds_list:
@@ -432,6 +433,7 @@ class ChartRepairer:
             return copy.deepcopy(cached)
 
         def _cache_and_return(res: RepairResult) -> RepairResult:
+            """写入修复结果缓存并返回，避免重复调用下游修复逻辑"""
             try:
                 self._result_cache[cache_key] = copy.deepcopy(res)
             except Exception:

ReportEngine/utils/dependency_check.py

@@ -27,6 +27,7 @@ def _get_platform_specific_instructions():
     system = platform.system()
 
     def _box_lines(lines):
+        """批量将多行文本包装成带边框的提示块"""
         return "".join(_box_line(line) for line in lines)
 
     if system == "Darwin":  # macOS
@@ -107,6 +108,7 @@ def _ensure_windows_gtk_paths():
     seen = set()
 
     def _add_candidate(path_like):
+        """收集可能的GTK安装路径，避免重复并兼容用户自定义目录"""
         if not path_like:
             return
         p = Path(path_like)