diff --git a/ReportEngine/core/chapter_storage.py b/ReportEngine/core/chapter_storage.py index 04e1cd8..c8bb330 100644 --- a/ReportEngine/core/chapter_storage.py +++ b/ReportEngine/core/chapter_storage.py @@ -68,7 +68,7 @@ class ChapterStorage: self.base_dir.mkdir(parents=True, exist_ok=True) self._manifests: Dict[str, Dict[str, object]] = {} - # ======== 会话 & manifest ======== + # ======== 会话与清单 ======== def start_session(self, report_id: str, metadata: Dict[str, object]) -> Path: """ diff --git a/ReportEngine/core/template_parser.py b/ReportEngine/core/template_parser.py index 9b29b38..2278a30 100644 --- a/ReportEngine/core/template_parser.py +++ b/ReportEngine/core/template_parser.py @@ -51,19 +51,19 @@ class TemplateSection: } -# The parsing expressions intentionally avoid `.*` to keep matching deterministic and -# eliminate easy Regular-Expression-DoS gadgets on untrusted template text. +# 解析表达式刻意避免使用 `.*`，以保持匹配的确定性， +# 并规避不可信模板文本中常见的正则DoS风险。 heading_pattern = re.compile( r""" - (?P\#{1,6}) # Markdown heading markers - [ \t]+ # required whitespace - (?P[^\r\n]+) # heading text without newline characters + (?P<marker>\#{1,6}) # Markdown标题标记 + [ \t]+ # 必需的空白字符 + (?P<title>[^\r\n]+) # 不包含换行的标题文本 """, re.VERBOSE, ) bullet_pattern = re.compile( r""" - (?P<marker>[-*+]) # list bullet symbol + (?P<marker>[-*+]) # 列表项目符号 [ \t]+ (?P<title>[^\r\n]+) """, @@ -130,7 +130,7 @@ def parse_template_sections(template_md: str) -> List[TemplateSection]: order += SECTION_ORDER_STEP continue - # outline + # 提纲条目 if current: current.outline.append(meta["title"]) diff --git a/ReportEngine/nodes/chapter_generation_node.py b/ReportEngine/nodes/chapter_generation_node.py index eda6900..655ea71 100644 --- a/ReportEngine/nodes/chapter_generation_node.py +++ b/ReportEngine/nodes/chapter_generation_node.py @@ -26,7 +26,7 @@ from .base_node import BaseNode try: from json_repair import repair_json as _json_repair_fn -except ImportError: # pragma: no cover - optional dependency +except ImportError: # pragma: no cover - 可选依赖 _json_repair_fn = None @@ -552,7 +552,7 @@ class ChapterGenerationNode(BaseNode): return None try: fixed = _json_repair_fn(text) - except Exception as exc: # pragma: no cover - library failure + except Exception as exc: # pragma: no cover - 库级故障 logger.warning(f"json_repair 修复章节JSON失败: {exc}") return None if fixed == text: diff --git a/ReportEngine/renderers/html_renderer.py b/ReportEngine/renderers/html_renderer.py index ac629ae..43f1608 100644 --- a/ReportEngine/renderers/html_renderer.py +++ b/ReportEngine/renderers/html_renderer.py @@ -100,7 +100,7 @@ class HTMLRenderer: body = self._render_body() return f"<!DOCTYPE html>\n<html lang=\"zh-CN\" class=\"no-js\">\n{head}\n{body}\n</html>" - # ====== Head / Body ====== + # ====== 头部 / 正文 ====== def _resolve_color_value(self, value: Any, fallback: str) -> str: """从颜色token中提取字符串值""" @@ -219,7 +219,7 @@ class HTMLRenderer: {hydration} </body>""".strip() - # ====== Header / Meta / TOC ====== + # ====== 页眉 / 元信息 / 目录 ====== def _render_header(self) -> str: """ @@ -653,7 +653,7 @@ class HTMLRenderer: words += numerals[ones] return words - # ====== 章节 & Block 渲染 ====== + # ====== 章节与块级渲染 ====== def _render_chapter(self, chapter: Dict[str, Any]) -> str: """ @@ -1074,7 +1074,7 @@ class HTMLRenderer: """ return table_html - # ====== Front-matter guards ====== + # ====== 前置信息防护 ====== def _kpi_signature_from_items(self, items: Any) -> tuple | None: """将KPI数组转换为可比较的签名""" @@ -1124,7 +1124,7 @@ class HTMLRenderer: return False return block_signature == self.hero_kpi_signature - # ====== Inline 渲染 ====== + # ====== 行内渲染 ====== def _normalize_inline_payload(self, run: Dict[str, Any]) -> tuple[str, List[Dict[str, Any]]]: """将嵌套inline node展平成基础文本与marks""" @@ -1326,7 +1326,7 @@ class HTMLRenderer: escaped = html.escape(self._safe_text(value), quote=True) return escaped.replace("\n", " ").replace("\r", " ") - # ====== CSS / JS ====== + # ====== CSS / JS（样式与脚本） ====== def _build_css(self, tokens: Dict[str, Any]) -> str: """根据主题token拼接整页CSS，包括响应式与打印样式"""