Refactor agent persona runtime layering

app/agent/prompt/__init__.py

@@ -1,13 +1,16 @@
 """提示词管理器"""
 
 import socket
+from dataclasses import dataclass, field
 from pathlib import Path
+from string import Formatter
 from time import strftime
-from typing import Dict
+from typing import Any, Dict, Optional
+
+import yaml
 
 from app.core.config import settings
 from app.log import logger
-from app.agent.runtime import agent_runtime_manager
 from app.schemas import (
     ChannelCapability,
     ChannelCapabilities,
@@ -16,6 +19,37 @@ from app.schemas import (
 )
 from app.utils.system import SystemUtils
 
+SYSTEM_TASKS_FILE = "System Tasks.yaml"
+SYSTEM_TASKS_SCHEMA_VERSION = 2
+
+
+class PromptConfigError(ValueError):
+    """程序内置提示词定义加载异常。"""
+
+
+@dataclass
+class SystemTaskTypeDefinition:
+    """单个后台系统任务定义。"""
+
+    header: str
+    objective: str
+    context_title: Optional[str] = None
+    context_lines: list[str] = field(default_factory=list)
+    steps_title: Optional[str] = None
+    steps: list[str] = field(default_factory=list)
+    task_rules: list[str] = field(default_factory=list)
+    empty_result: Optional[str] = None
+
+
+@dataclass
+class SystemTasksDefinition:
+    """程序内置后台系统任务定义。"""
+
+    path: Path
+    version: int
+    shared_rules: list[str]
+    task_types: dict[str, SystemTaskTypeDefinition]
+
 
 class PromptManager:
     """
@@ -28,6 +62,8 @@ class PromptManager:
         else:
             self.prompts_dir = Path(prompts_dir)
         self.prompts_cache: Dict[str, str] = {}
+        self._system_tasks_cache: Optional[SystemTasksDefinition] = None
+        self._system_tasks_signature: Optional[tuple[int, int]] = None
 
     def load_prompt(self, prompt_name: str) -> str:
         """
@@ -60,11 +96,9 @@ class PromptManager:
         :param prefer_voice_reply: 是否优先使用语音回复
         :return: 提示词内容
         """
-        # 根层运行时配置由独立装配器负责，避免人格/工作流继续硬编码在单文件 prompt 中。
-        runtime_config = agent_runtime_manager.load_runtime_config()
-        runtime_sections = runtime_config.render_prompt_sections()
-
         # 基础提示词只保留 MoviePilot 运行时和渠道能力相关约束。
+        # 根层运行时配置由 RuntimeConfigMiddleware 在每次模型调用前动态注入，
+        # 这样人格切换可以在同一轮 Agent 执行里立即生效。
         base_prompt = self.load_prompt("System Core Prompt.txt")
 
         # 识别渠道
@@ -109,11 +143,119 @@ class PromptManager:
             moviepilot_info=moviepilot_info,
             voice_reply_spec=voice_reply_spec,
             button_choice_spec=button_choice_spec,
-            runtime_sections=runtime_sections,
         )
 
         return base_prompt
 
+    def load_system_tasks_definition(self) -> SystemTasksDefinition:
+        """加载程序内置的后台系统任务定义。"""
+        system_tasks_path = self.prompts_dir / SYSTEM_TASKS_FILE
+        try:
+            stat = system_tasks_path.stat()
+        except FileNotFoundError as err:
+            logger.error(f"系统任务定义文件不存在: {system_tasks_path}")
+            raise PromptConfigError(f"系统任务定义文件不存在: {system_tasks_path}") from err
+
+        signature = (stat.st_mtime_ns, stat.st_size)
+        if (
+            self._system_tasks_signature == signature
+            and self._system_tasks_cache is not None
+        ):
+            return self._system_tasks_cache
+
+        try:
+            content = system_tasks_path.read_text(encoding="utf-8")
+        except Exception as err:  # noqa: BLE001
+            logger.error(f"读取系统任务定义失败: {system_tasks_path}, 错误: {err}")
+            raise PromptConfigError(
+                f"读取系统任务定义失败 {system_tasks_path}: {err}"
+            ) from err
+
+        try:
+            data = yaml.safe_load(content) or {}
+        except yaml.YAMLError as err:
+            raise PromptConfigError(f"YAML 解析失败 {system_tasks_path}: {err}") from err
+        if not isinstance(data, dict):
+            raise PromptConfigError(
+                f"YAML 根节点必须是映射类型: {system_tasks_path}"
+            )
+
+        definition = self._parse_system_tasks_definition(system_tasks_path, data)
+        self._system_tasks_signature = signature
+        self._system_tasks_cache = definition
+        return definition
+
+    def render_system_task_message(
+        self,
+        task_type: str,
+        *,
+        template_context: Optional[dict[str, Any]] = None,
+        extra_rules: Optional[list[str]] = None,
+    ) -> str:
+        """根据程序内置 YAML 渲染后台系统任务提示词。"""
+        system_tasks = self.load_system_tasks_definition()
+        task_definition = system_tasks.task_types.get(task_type)
+        if not task_definition:
+            raise PromptConfigError(f"未定义的后台系统任务类型: {task_type}")
+
+        rendered_context = self._render_template_lines(
+            task_definition.context_lines,
+            template_context,
+            task_type,
+            "context_lines",
+        )
+        rendered_steps = self._render_template_lines(
+            task_definition.steps,
+            template_context,
+            task_type,
+            "steps",
+        )
+        rendered_task_rules = self._render_template_lines(
+            task_definition.task_rules,
+            template_context,
+            task_type,
+            "task_rules",
+        )
+
+        sections = [
+            self._render_template_text(
+                task_definition.header,
+                template_context,
+                task_type,
+                "header",
+            ).strip(),
+            self._render_template_text(
+                task_definition.objective,
+                template_context,
+                task_type,
+                "objective",
+            ).strip(),
+        ]
+        if rendered_context:
+            sections.append(
+                self._format_titled_lines(
+                    task_definition.context_title or "Task context",
+                    rendered_context,
+                )
+            )
+        if rendered_steps:
+            sections.append(
+                self._format_titled_lines(
+                    task_definition.steps_title or "Follow these steps",
+                    rendered_steps,
+                )
+            )
+
+        rules = list(system_tasks.shared_rules)
+        if task_definition.empty_result:
+            rules.append(task_definition.empty_result)
+        rules.extend(rendered_task_rules)
+        if extra_rules:
+            rules.extend(rule.strip() for rule in extra_rules if rule and rule.strip())
+        if rules:
+            sections.append(self._format_numbered_rules("IMPORTANT", rules))
+        return "\n\n".join(section for section in sections if section).strip()
+
     @staticmethod
     def _get_moviepilot_info() -> str:
         """
@@ -214,11 +356,172 @@ class PromptManager:
             )
         return "- User questions: When you truly need user input, ask briefly in plain text."
 
+    def _parse_system_tasks_definition(
+        self,
+        path: Path,
+        data: dict[str, Any],
+    ) -> SystemTasksDefinition:
+        """把 YAML 结构转换成系统任务定义对象。"""
+        version = self._normalize_positive_int(data.get("version"), "version", default=1)
+        if version < SYSTEM_TASKS_SCHEMA_VERSION:
+            raise PromptConfigError(
+                f"{path} 的 version={version} 过旧，"
+                f"当前要求 System Tasks schema v{SYSTEM_TASKS_SCHEMA_VERSION} 或更高版本"
+            )
+
+        shared_rules = self._normalize_string_list(data.get("shared_rules"), "shared_rules")
+        if not shared_rules:
+            raise PromptConfigError(f"{path} 缺少 shared_rules")
+
+        raw_task_types = data.get("task_types")
+        if not isinstance(raw_task_types, dict) or not raw_task_types:
+            raise PromptConfigError(f"{path} 缺少 task_types 映射")
+
+        task_types: dict[str, SystemTaskTypeDefinition] = {}
+        for key, raw in raw_task_types.items():
+            if not isinstance(raw, dict):
+                raise PromptConfigError(f"task_types.{key} 必须是映射")
+
+            header = str(raw.get("header") or "").strip()
+            objective = str(raw.get("objective") or "").strip()
+            if not header or not objective:
+                raise PromptConfigError(f"task_types.{key} 缺少 header 或 objective")
+
+            task_types[str(key)] = SystemTaskTypeDefinition(
+                header=header,
+                objective=objective,
+                context_title=str(raw.get("context_title") or "").strip() or None,
+                context_lines=self._normalize_string_list(
+                    raw.get("context_lines"),
+                    f"task_types.{key}.context_lines",
+                ),
+                steps_title=str(raw.get("steps_title") or "").strip() or None,
+                steps=self._normalize_string_list(
+                    raw.get("steps"),
+                    f"task_types.{key}.steps",
+                ),
+                task_rules=self._normalize_string_list(
+                    raw.get("task_rules"),
+                    f"task_types.{key}.task_rules",
+                ),
+                empty_result=str(raw.get("empty_result") or "").strip() or None,
+            )
+        return SystemTasksDefinition(
+            path=path,
+            version=version,
+            shared_rules=shared_rules,
+            task_types=task_types,
+        )
+
+    @classmethod
+    def _render_template_text(
+        cls,
+        text: str,
+        template_context: Optional[dict[str, Any]],
+        task_type: str,
+        field_name: str,
+    ) -> str:
+        if not text:
+            return ""
+
+        formatter = Formatter()
+        required_fields = {
+            placeholder_name
+            for _, placeholder_name, _, _ in formatter.parse(text)
+            if placeholder_name
+        }
+        if not required_fields:
+            return text
+
+        context = cls._normalize_template_context(template_context)
+        missing_fields = sorted(field for field in required_fields if field not in context)
+        if missing_fields:
+            raise PromptConfigError(
+                f"系统任务定义 `{task_type}` 的 `{field_name}` 缺少变量: "
+                + ", ".join(f"`{field}`" for field in missing_fields)
+            )
+
+        # 这里统一做字符串替换，让 YAML 成为后台任务文案的唯一行为来源。
+        return text.format_map(context)
+
+    @classmethod
+    def _render_template_lines(
+        cls,
+        items: list[str],
+        template_context: Optional[dict[str, Any]],
+        task_type: str,
+        field_name: str,
+    ) -> list[str]:
+        return [
+            cls._render_template_text(
+                item,
+                template_context,
+                task_type,
+                f"{field_name}[{index}]",
+            ).rstrip()
+            for index, item in enumerate(items, start=1)
+            if item and item.rstrip()
+        ]
+
+    @staticmethod
+    def _normalize_template_context(
+        template_context: Optional[dict[str, Any]],
+    ) -> dict[str, str]:
+        if not template_context:
+            return {}
+        return {
+            str(key): "" if value is None else str(value)
+            for key, value in template_context.items()
+        }
+
+    @staticmethod
+    def _format_numbered_rules(title: str, items: list[str]) -> str:
+        return "\n".join(
+            [f"{title}:"] + [f"{index}. {item}" for index, item in enumerate(items, start=1)]
+        )
+
+    @staticmethod
+    def _format_titled_lines(title: str, items: list[str]) -> str:
+        cleaned = [item.rstrip() for item in items if item and item.rstrip()]
+        return "\n".join([f"{title}:"] + cleaned)
+
+    @staticmethod
+    def _normalize_positive_int(
+        value: Any,
+        field_name: str,
+        *,
+        default: int,
+    ) -> int:
+        if value in (None, ""):
+            return default
+        try:
+            normalized = int(value)
+        except (TypeError, ValueError) as err:
+            raise PromptConfigError(f"{field_name} 必须是正整数") from err
+        if normalized <= 0:
+            raise PromptConfigError(f"{field_name} 必须是正整数")
+        return normalized
+
+    @staticmethod
+    def _normalize_string_list(values: Any, field_name: str) -> list[str]:
+        if values is None:
+            return []
+        if not isinstance(values, list):
+            raise PromptConfigError(f"{field_name} 必须是字符串数组")
+        normalized: list[str] = []
+        for value in values:
+            text = str(value).strip()
+            if text:
+                normalized.append(text)
+        return normalized
+
     def clear_cache(self):
         """
         清空缓存
         """
         self.prompts_cache.clear()
+        self._system_tasks_cache = None
+        self._system_tasks_signature = None
         logger.info("提示词缓存已清空")