♻️ refactor(agent): 重构 Agent 状态管理与执行器流程，优化 Token 预估与自愈反思机制 (#2150)

- 统一使用 `run_context.run.messages` 作为消息历史的单一数据源，清理 `AgentState` 冗余字段
- 将工具消息装配逻辑 `assemble_tool_message` 提取并重构至 `ToolExecutor`
- 引入 `token_drift` 动态校准偏移量，并精确计算工具与系统提示词的 Token 开销
- 重构 `ReflexionCapability` 自愈反思引擎，基于异常多态与模板字典动态生成反馈提示词
- 支持通过 `resolve_model_capabilities` 解析并合并用户自定义的模型能力覆盖
- 在执行器循环中支持 `should_reset_cycle`，以优雅处理外部干预（如用户追加指示）
- 扩展 `capabilities` 中对 `gpt-[5-9]*` 等新型号模型的能力定义与上下文限制

Co-authored-by: webjoin111 <455457521@qq.com>

zhenxun/services/ai/core/engine/structured_parser.py

@@ -8,21 +8,12 @@ from pydantic import BaseModel, Field, ValidationError, create_model
 
 from zhenxun.services.ai.core.exceptions import (
     SchemaParseError,
+    SchemaValidationError,
 )
 from zhenxun.services.ai.core.messages.types import OutputDataT
 from zhenxun.services.ai.utils.logger import log_core as logger
 from zhenxun.utils.pydantic_compat import model_json_schema, model_validate
 
-DEFAULT_IVR_TEMPLATE = (
-    "### ❌ [输出内容或格式验证失败]\n"
-    "你的上一次输出未能通过系统的校验与规则检查。请立即启动修正流程：\n\n"
-    "**错误反馈报告：**\n"
-    "> {error_msg}\n\n"
-    "**修正要求：** 请结合反馈报告，"
-    "仔细反思你的输出内容或格式，\n"
-    "并重新生成正确的数据以满足所有的规则与规范。"
-)
-
 
 class BaseOutputProcessor(Generic[OutputDataT]):
     """
@@ -47,7 +38,7 @@ class BaseOutputProcessor(Generic[OutputDataT]):
                 如果不为 None 则跳过根据 response_model 生成，默认 None。
         """  # noqa: E501
         self.original_model = response_model
-        self.error_template = error_template or DEFAULT_IVR_TEMPLATE
+        self.error_template = error_template
         self.raw_schema = raw_schema
         self.target_model = None
         self.is_union_wrapped = False
@@ -120,7 +111,7 @@ class BaseOutputProcessor(Generic[OutputDataT]):
                         msg = err.get("msg", "")
                         error_msgs.append(f"字段 `{loc}`: {msg}")
                     clean_error_str = "\n".join(error_msgs)
-                    raise SchemaParseError(
+                    raise SchemaValidationError(
                         f"数据内容未通过规则校验:\n{clean_error_str}"
                     )
 

zhenxun/services/ai/core/engine/token_counter.py

@@ -3,6 +3,7 @@ LLM Token 动态预估与上下文管理模块
 """
 
 from collections.abc import Sequence
+import json
 import math
 import re
 from typing import Any
@@ -56,17 +57,11 @@ class TokenCounter:
     @classmethod
     def count_tools_schema(cls, obj: dict | list | str | Any) -> int:
         """递归计算 JSON Schema 结构在被大模型作为工具时的 Token 开销。"""
-        if isinstance(obj, dict):
-            cost = len(obj.keys()) * 12
-            for k, v in obj.items():
-                if k == "description" and isinstance(v, str):
-                    cost += int(len(v) * 0.3)
-                else:
-                    cost += cls.count_tools_schema(v)
-            return cost
-        elif isinstance(obj, list):
-            return sum(cls.count_tools_schema(item) for item in obj)
-        return 0
+        try:
+            json_str = json.dumps(obj, ensure_ascii=False)
+            return int(cls._count_text(json_str) * 1.2) + 15
+        except Exception:
+            return 50
 
     @classmethod
     def count_message(cls, msg: LLMMessage, model_name: str) -> int:

zhenxun/services/ai/core/exceptions.py

@@ -8,41 +8,70 @@ from typing import Any
 class ModelRetry(Exception):
     """用于通知大模型修正并重试的异常"""
 
-    def __init__(self, message: str):
+    def __init__(self, message: str, payload: dict[str, Any] | None = None):
         """
         初始化用于通知大模型重试的异常。
 
         参数：
             message: 用于提示大模型的具体重试和自我纠错信息。
+            payload: 携带产生错误时的上下文状态字典，用于渲染反馈提示词。
         """
         self.message = message
-        super().__init__(message)
+        self.payload = payload or {}
+        super().__init__(self.message)
+
+    def get_template_name(self) -> str:
+        """多态：子类告诉渲染引擎，自己应该使用哪个 Prompt 模板标识"""
+        return "default_retry"
+
+    def get_feedback_context(self) -> dict[str, Any]:
+        """多态：子类提供渲染模板所需的领域数据上下文"""
+        return {"error_msg": self.message, **self.payload}
 
 
 class SchemaParseError(ModelRetry):
     """格式解析异常。当大模型返回的 JSON 损坏或不符合 Schema 时抛出。"""
 
-    def __init__(self, message: str):
+    def __init__(self, message: str, payload: dict[str, Any] | None = None):
         """
         初始化 Schema 格式解析错误异常。
 
         参数：
             message: 详细的 JSON 解析失败或 Schema 校验报错信息。
         """
-        super().__init__(message)
+        super().__init__(message, payload)
+
+    def get_template_name(self) -> str:
+        return "schema_parse_error"
+
+
+class SchemaValidationError(ModelRetry):
+    """数据校验异常。当大模型返回的 JSON 格式正确，但业务字段约束不满足时抛出。"""
+
+    def __init__(self, message: str, payload: dict[str, Any] | None = None):
+        """
+        初始化 Schema 业务字段约束验证错误异常。
+        """
+        super().__init__(message, payload)
+
+    def get_template_name(self) -> str:
+        return "schema_validation_error"
 
 
 class GuardrailViolationError(ModelRetry):
     """护栏违规异常。当大模型返回的数据格式正确，但违反业务规则时抛出。"""
 
-    def __init__(self, message: str):
+    def __init__(self, message: str, payload: dict[str, Any] | None = None):
         """
         初始化安全护栏校验未通过的异常。
 
         参数：
             message: 触发业务护栏违规拦截的详细原因说明。
         """
-        super().__init__(message)
+        super().__init__(message, payload)
+
+    def get_template_name(self) -> str:
+        return "guardrail_violation"
 
 
 class ControlFlowExit(BaseException):