fix(template-utils): str.format -> string.Template (#149)

* feat: upgrade prompt templates from str.format to string.Template for improved compatibility

* fix(get_astrbot_data_path): fallback 到 get_astrbot_data_path 方法

* feat: upgrade prompt templates from str.format to string.Template for improved compatibility

* fix: strict mode

* fix: 补齐文件名格式的自动迁移

* fix(ChatQualityAnalyzer): 删除无效的 prompt 提示语句

* ruff

---------

Co-authored-by: SXP-Simon <sxp20061207@163.com>

Author: lekoOwO

_conf_schema.json

@@ -220,6 +220,12 @@ async def _run_initialization(self, source: str):
 
                 logger.info(f"正在执行插件初始化 (来源: {source})...")
 
+                # 0. 自动升级旧版 prompt 模板（str.format -> string.Template）并回写配置
+                try:
+                    self.config_manager.upgrade_prompt_templates()
+                except Exception as e:
+                    logger.warning(f"自动升级 prompt 模板失败: {e}")
+
                 # 1. 尝试发现 bot 实例
                 await self.bot_manager.initialize_from_config()
 

main.py

@@ -7,6 +7,7 @@
 
 from ....domain.models.data_models import QualityDimension, QualityReview, TokenUsage
 from ....utils.logger import logger
+from ...utils.template_utils import render_template
 from ..utils import InfoUtils
 from ..utils.json_utils import extract_quality_with_regex, parse_json_object_response
 from ..utils.llm_utils import (
@@ -85,8 +86,10 @@ def build_prompt(self, data: list[dict]) -> str:
 
         prompt_template = self.config_manager.get_quality_analysis_prompt()
 
-        if not prompt_template:
-            prompt_template = """你是一个毒舌且幽默的群聊质量分析师。
+        if prompt_template:
+            return render_template(prompt_template, messages_text=messages_text)
+
+        prompt_template = """你是一个毒舌且幽默的群聊质量分析师。
 请分析以下群聊记录，输出一份"聊天质量锐评"。
 
 ## 任务目标：
@@ -120,10 +123,10 @@ def build_prompt(self, data: list[dict]) -> str:
 ```
 
 群聊记录：
-{messages_text}
+${messages_text}
 """
 
-        return prompt_template.format(messages_text=messages_text)
+        return render_template(prompt_template, messages_text=messages_text)
 
     def extract_with_regex(self, result_text: str, max_count: int) -> list[dict]:
         """
@@ -291,10 +294,10 @@ async def summarize_batch_reviews(
                 )
                 reviews_text += f"\n批次 {i + 1} [{title}]:\n- 维度表现: {dims}\n- 核心摘要: {summary}\n"
 
-            prompt_template = self.config_manager.get_quality_summary_prompt()
-
-            if not prompt_template:
-                prompt_template = """你是一个毒舌且幽默的群聊质量分析师。
+            # 获取配置中的汇总提示词模板，如果没有则使用默认模板
+            prompt_template = (
+                self.config_manager.get_quality_summary_prompt()
+                or """你是一个毒舌且幽默的群聊质量分析师。
 你现在有一份今天全天分散时间段的多个“增量批次点评笔记”。
 你的任务是将这些分散的笔记汇总成一份最终的“全天聊天质量终极锐评”。
 
@@ -327,7 +330,8 @@ async def summarize_batch_reviews(
 }}
 ```
 """
-            prompt = prompt_template.format(reviews_text=reviews_text)
+            )
+            prompt = render_template(prompt_template, reviews_text=reviews_text)
 
             # 调用 LLM 进行汇总
             system_prompt = await self._build_system_prompt(umo)

src/infrastructure/analysis/analyzers/chat_quality_analyzer.py

@@ -7,6 +7,7 @@
 
 from ....domain.models.data_models import GoldenQuote, TokenUsage
 from ....utils.logger import logger
+from ...utils.template_utils import render_template
 from ..utils import InfoUtils
 from ..utils.json_utils import extract_golden_quotes_with_regex
 from ..utils.response_validation import validate_golden_quote_items
@@ -64,15 +65,14 @@ def build_prompt(self, data: list[dict]) -> str:
         prompt_template = self.config_manager.get_golden_quote_analysis_prompt()
 
         if prompt_template:
-            # 使用配置中的 prompt 并替换变量
             try:
-                prompt = prompt_template.format(
-                    max_golden_quotes=max_golden_quotes, messages_text=messages_text
+                prompt = render_template(
+                    prompt_template,
+                    max_golden_quotes=max_golden_quotes,
+                    messages_text=messages_text,
                 )
                 logger.info("使用配置中的金句分析提示词")
                 return prompt
-            except KeyError as e:
-                logger.warning(f"金句分析提示词变量格式错误: {e}")
             except Exception as e:
                 logger.warning(f"应用金句分析提示词失败: {e}")
 

src/infrastructure/analysis/analyzers/golden_quote_analyzer.py

@@ -8,6 +8,7 @@
 
 from ....domain.models.data_models import SummaryTopic, TokenUsage
 from ....utils.logger import logger
+from ...utils.template_utils import render_template
 from ..utils import InfoUtils
 from ..utils.json_utils import extract_topics_with_regex
 from ..utils.response_validation import validate_topic_items
@@ -162,15 +163,14 @@ def build_prompt(self, data: list[dict]) -> str:
         prompt_template = self.config_manager.get_topic_analysis_prompt()
 
         if prompt_template:
-            # 使用配置中的 prompt 并替换变量
             try:
-                prompt = prompt_template.format(
-                    max_topics=max_topics, messages_text=messages_text
+                prompt = render_template(
+                    prompt_template,
+                    max_topics=max_topics,
+                    messages_text=messages_text,
                 )
                 logger.info("使用配置中的话题分析提示词")
                 return prompt
-            except KeyError as e:
-                logger.warning(f"话题分析提示词变量格式错误: {e}")
             except Exception as e:
                 logger.warning(f"应用话题分析提示词失败: {e}")
 

src/infrastructure/analysis/analyzers/topic_analyzer.py

@@ -5,6 +5,7 @@
 
 from ....domain.models.data_models import TokenUsage, UserTitle
 from ....utils.logger import logger
+from ...utils.template_utils import render_template
 from ..utils.json_utils import extract_user_titles_with_regex
 from ..utils.response_validation import validate_user_title_items
 from ..utils.structured_output_schema import JSONObject, build_user_titles_schema
@@ -65,13 +66,10 @@ def build_prompt(self, data: dict) -> str:
         prompt_template = self.config_manager.get_user_title_analysis_prompt()
 
         if prompt_template:
-            # 使用配置中的 prompt 并替换变量
             try:
-                prompt = prompt_template.format(users_text=users_text)
+                prompt = render_template(prompt_template, users_text=users_text)
                 logger.info("使用配置中的用户称号分析提示词")
                 return prompt
-            except KeyError as e:
-                logger.warning(f"用户称号分析提示词变量格式错误: {e}")
             except Exception as e:
                 logger.warning(f"应用用户称号分析提示词失败: {e}")
 

src/infrastructure/analysis/analyzers/user_title_analyzer.py

@@ -9,6 +9,7 @@
 from astrbot.api.star import StarTools
 
 from ...utils.logger import logger
+from ..utils.template_utils import upgrade_str_format_template
 
 
 class ConfigManager:
@@ -332,6 +333,80 @@ def set_quality_analysis_prompt(self, prompt: str):
         prompts["quality_analysis_prompts"]["quality_v2_prompt"] = prompt
         self.config.save_config()
 
+    def _upgrade_config_item(self, group: str, key: str, setter_func):
+        """升级指定配置项的值（从 str.format -> string.Template），并回写。"""
+        # 如果是 prompts，则先取 prompts 分组，再取子分组 (group)
+        if group in (
+            "quality_analysis_prompts",
+            "topic_analysis_prompts",
+            "user_title_analysis_prompts",
+            "golden_quote_analysis_prompts",
+        ):
+            target_group = self._get_group("prompts").get(group, {})
+        else:
+            target_group = self._get_group(group)
+
+        val = target_group.get(key, "")
+        if not val or not isinstance(val, str):
+            return False
+
+        upgraded_val, upgraded = upgrade_str_format_template(val)
+        if upgraded and upgraded_val != val:
+            setter_func(upgraded_val)
+            logger.info(
+                f"配置项 {group}.{key} 发现旧版语法并已自动升级为 string.Template 格式。"
+            )
+            return True
+        return False
+
+    def upgrade_prompt_templates(self):
+        """启动时调用，扫描并升级所有可配置的模板（含 prompt 和文件名）。"""
+        modified = False
+        # 1. 提示词模板升级
+        modified |= self._upgrade_config_item(
+            "quality_analysis_prompts",
+            "quality_v2_prompt",
+            self.set_quality_analysis_prompt,
+        )
+        modified |= self._upgrade_config_item(
+            "quality_analysis_prompts",
+            "quality_summary_prompt",
+            self.set_quality_summary_prompt,
+        )
+        modified |= self._upgrade_config_item(
+            "topic_analysis_prompts",
+            "topic_prompt",
+            self.set_topic_analysis_prompt,
+        )
+        modified |= self._upgrade_config_item(
+            "user_title_analysis_prompts",
+            "user_title_prompt",
+            self.set_user_title_analysis_prompt,
+        )
+        modified |= self._upgrade_config_item(
+            "golden_quote_analysis_prompts",
+            "golden_quote_v2_prompt",
+            self.set_golden_quote_analysis_prompt,
+        )
+
+        # 2. 文件名格式升级
+        modified |= self._upgrade_config_item(
+            "pdf",
+            "pdf_filename_format",
+            self.set_pdf_filename_format,
+        )
+        modified |= self._upgrade_config_item(
+            "html",
+            "html_filename_format",
+            self.set_html_filename_format,
+        )
+
+        if modified:
+            logger.info(
+                "已完成所有配置模板从 str.format 到 string.Template 的安全迁移。（已自动回写配置）"
+            )
+        return modified
+
     def get_quality_summary_prompt(self, style: str = "quality_summary_prompt") -> str:
         """获取聊天质量汇总分析提示词模板"""
         prompts_config = self._get_group("prompts").get("quality_analysis_prompts", {})
@@ -542,6 +617,11 @@ def set_pdf_filename_format(self, format_str: str):
         self._ensure_group("pdf")["pdf_filename_format"] = format_str
         self.config.save_config()
 
+    def set_html_filename_format(self, format_str: str):
+        """设置HTML文件名格式"""
+        self._ensure_group("html")["html_filename_format"] = format_str
+        self.config.save_config()
+
     def get_report_template(self) -> str:
         """获取报告模板名称"""
         return self._get_group("basic").get("report_template", "scrapbook")

src/infrastructure/config/config_manager.py

@@ -21,6 +21,7 @@
 
 from ...domain.repositories.report_repository import IReportGenerator
 from ...utils.logger import logger
+from ..utils.template_utils import render_template
 from ..visualization.activity_charts import ActivityVisualizer
 from .templates import HTMLTemplates
 
@@ -94,9 +95,9 @@ def _build_safe_report_path(
         }
 
         try:
-            formatted = filename_format.format(**safe_context)
+            formatted = render_template(filename_format, strict=True, **safe_context)
         except Exception as e:
-            raise ValueError(f"文件名格式化失败: {e}") from e
+            raise ValueError(f"文件名模板渲染失败: {e}") from e
 
         if os.path.isabs(formatted):
             raise ValueError("文件名格式不得为绝对路径")

src/infrastructure/reporting/generators.py

@@ -0,0 +1,106 @@
+"""安全模板渲染工具（String Template 兼容）"""
+
+import re
+from string import Template
+
+from ...utils.logger import logger
+
+# 统一默认 placeholder
+PLACEHOLDERS = {
+    # 分析类核心变量
+    "messages_text": "${messages_text}",
+    "reviews_text": "${reviews_text}",
+    "max_topics": "${max_topics}",
+    "users_text": "${users_text}",
+    "max_golden_quotes": "${max_golden_quotes}",
+    # 文件名渲染类变量
+    "group_id": "${group_id}",
+    "date": "${date}",
+    "ulid": "${ulid}",
+}
+
+
+def is_str_format_template(template: str) -> bool:
+    """判断模板是否为 str.format 风格。
+
+    只认为满足：
+    1) 不包含 String Template `${var}` 或 `$var`
+    2) 包含 str.format `{var}`（非 `{{...}}`）
+    """
+    if not template:
+        return False
+
+    # 1. 預先建立排除模式 (匹配 ${var} 或 $var)
+    # 使用 set 去重並組合
+    dollar_patterns = [re.escape(v) for v in PLACEHOLDERS.values()] + [
+        rf"\${re.escape(k)}" for k in PLACEHOLDERS.keys()
+    ]
+    exclude_regex = "|".join(dollar_patterns)
+
+    # 如果包含任何 $ 相關的佔位符，則不視為 str.format 模板
+    if re.search(exclude_regex, template):
+        return False
+
+    # 2. 檢查是否包含標準的 {key}，確保匹配單個花括號包裹的 Key
+    for key in PLACEHOLDERS.keys():
+        # (?<!\{)  前面不能有 {
+        # \{{key}\} 匹配 {key}
+        # (?!\})   後面不能有 }
+        # (?<!\$)  前面不能有 $
+        pattern = rf"(?<![\{{\$])\{{{key}\}}(?!\}})"
+        if re.search(pattern, template):
+            return True
+    return False
+
+
+def upgrade_str_format_template(template: str) -> tuple[str, bool]:
+    """如果模板是 str.format 风格，则自动升级为 string.Template。
+
+    返回 (升级后的模板, 是否升级)
+    """
+    if template is None:
+        return "", False
+
+    if not is_str_format_template(template):
+        return template, False
+
+    # 先转义原文中的 $，避免被 Template 误解释为占位符
+    safe_template = template.replace("$", "$$")
+
+    # 将 {var} 转为 ${var}
+    safe_template = re.sub(
+        r"(?<![\{\$])\{([_a-zA-Z][_a-zA-Z0-9]*)\}(?!\})",
+        lambda m: f"${{{m.group(1)}}}",
+        safe_template,
+    )
+
+    # 将双括号回退为单括号（str.format 里表示字面量大括号）
+    safe_template = safe_template.replace("{{", "{").replace("}}", "}")
+
+    return safe_template, True
+
+
+def render_template(template: str, strict: bool = False, **kwargs) -> str:
+    """渲染模板（String Template）。
+
+    Args:
+        template: 模板字符串
+        strict: 是否使用严格模式（变量缺失则抛出异常）
+        **kwargs: 渲染变量
+
+    由于插件启动时已完成 str.format 兼容升级，运行时直接按 string.Template 渲染。
+    """
+    if template is None:
+        return ""
+
+    try:
+        t = Template(template)
+        return t.substitute(**kwargs) if strict else t.safe_substitute(**kwargs)
+    except Exception as e:
+        if strict:
+            raise
+        logger.warning(
+            f"[template_utils] 模板渲染失败，返回原始文本，错误: {e}",
+            exc_info=True,
+        )
+        return template