feat: make context compression threshold configurable

Author: Fronut

astrbot/core/agent/context/config.py

@@ -1,5 +1,10 @@
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal, TypedDict
+
+from astrbot.core.utils.config_number import (
+    coerce_float_config,
+    coerce_int_config,
+)
 
 from .compressor import ContextCompressor
 from .token_counter import TokenCounter
@@ -8,12 +13,101 @@
     from astrbot.core.provider.provider import Provider
 
 
+DEFAULT_FALLBACK_MAX_CONTEXT_TOKENS = 128_000
+
+
+CompressionThresholdMode = Literal["percentage", "output_reserve", "min", "max"]
+
+
+class CompressionThresholdResult(TypedDict):
+    """Resolved compression threshold shared by runtime and dashboard."""
+
+    mode: CompressionThresholdMode
+    percentage: float
+    output_tokens: int
+    output_threshold: float | None
+    effective_threshold: float
+    fallback_reason: str | None
+
+
+def resolve_compression_threshold(
+    mode: str,
+    percentage: float,
+    max_context_tokens: int,
+    max_output_tokens: int,
+) -> CompressionThresholdResult:
+    """Resolve the effective context compression threshold.
+
+    Args:
+        mode: Threshold strategy: percentage, output_reserve, min, or max.
+        percentage: User-defined context usage threshold.
+        max_context_tokens: Effective model context window.
+        max_output_tokens: Effective maximum output budget, or zero when unknown.
+
+    Returns:
+        The normalized inputs and effective threshold used by the compressor.
+    """
+    normalized_mode: CompressionThresholdMode = (
+        mode if mode in {"percentage", "output_reserve", "min", "max"} else "percentage"
+    )
+    normalized_percentage = coerce_float_config(
+        percentage,
+        default=0.82,
+        min_value=0.01,
+        max_value=1.0,
+        field_name="compression_threshold_percentage",
+    )
+    normalized_context_tokens = coerce_int_config(
+        max_context_tokens,
+        default=0,
+        min_value=0,
+        field_name="max_context_tokens",
+    )
+    normalized_output_tokens = coerce_int_config(
+        max_output_tokens,
+        default=0,
+        min_value=0,
+        field_name="compression_max_output_tokens",
+    )
+    output_threshold = None
+    fallback_reason = None
+
+    if normalized_context_tokens > 0 and normalized_output_tokens > 0:
+        output_threshold = max(
+            0.0,
+            1.0 - normalized_output_tokens / normalized_context_tokens,
+        )
+
+    if normalized_mode == "percentage":
+        effective_threshold = normalized_percentage
+    elif output_threshold is None:
+        effective_threshold = normalized_percentage
+        fallback_reason = "max_output_tokens_unavailable"
+    elif normalized_mode == "output_reserve":
+        effective_threshold = output_threshold
+    elif normalized_mode == "min":
+        effective_threshold = min(normalized_percentage, output_threshold)
+    else:
+        effective_threshold = max(normalized_percentage, output_threshold)
+
+    return {
+        "mode": normalized_mode,
+        "percentage": normalized_percentage,
+        "output_tokens": normalized_output_tokens,
+        "output_threshold": output_threshold,
+        "effective_threshold": effective_threshold,
+        "fallback_reason": fallback_reason,
+    }
+
+
 @dataclass
 class ContextConfig:
     """Context configuration class."""
 
     max_context_tokens: int = 0
     """Maximum number of context tokens. <= 0 means no limit."""
+    compression_threshold: float = 0.82
+    """Effective context usage ratio that triggers compression."""
     enforce_max_turns: int = -1  # -1 means no limit
     """Maximum number of conversation turns to keep. -1 means no limit. Executed before compression."""
     truncate_turns: int = 1

astrbot/core/agent/context/manager.py

@@ -36,10 +36,12 @@ def __init__(
                 keep_recent_ratio=config.llm_compress_keep_recent_ratio,
                 instruction_text=config.llm_compress_instruction,
                 token_counter=self.token_counter,
+                compression_threshold=config.compression_threshold,
             )
         else:
             self.compressor = TruncateByTurnsCompressor(
-                truncate_turns=config.truncate_turns
+                truncate_turns=config.truncate_turns,
+                compression_threshold=config.compression_threshold,
             )
 
     async def process(

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -46,6 +46,7 @@
     sanitize_contexts_by_modalities,
 )
 from astrbot.core.provider.provider import Provider
+from astrbot.core.utils.config_number import coerce_int_config
 
 from ..context.compressor import ContextCompressor
 from ..context.config import ContextConfig
@@ -214,6 +215,7 @@ async def reset(
         # enforce max turns, will discard older turns when exceeded BEFORE compression
         # -1 means no limit
         enforce_max_turns: int = -1,
+        compression_threshold: float = 0.82,
         # llm compressor
         llm_compress_instruction: str | None = None,
         llm_compress_keep_recent_ratio: float = 0.15,
@@ -233,6 +235,7 @@ async def reset(
         self.req = request
         self.streaming = streaming
         self.enforce_max_turns = enforce_max_turns
+        self.compression_threshold = compression_threshold
         self.llm_compress_instruction = llm_compress_instruction
         self.llm_compress_keep_recent_ratio = llm_compress_keep_recent_ratio
         self.llm_compress_provider = llm_compress_provider
@@ -245,7 +248,14 @@ async def reset(
         self._tool_result_token_counter = EstimateTokenCounter()
         self.request_context_manager_config = ContextConfig(
             # <=0 disables token-based guarding.
-            max_context_tokens=provider.provider_config.get("max_context_tokens", 0),
+            max_context_tokens=coerce_int_config(
+                provider.provider_config.get("max_context_tokens", 0),
+                default=0,
+                min_value=0,
+                field_name="max_context_tokens",
+                source="provider config",
+            ),
+            compression_threshold=self.compression_threshold,
             # Enforce max turns before token-based guarding.
             enforce_max_turns=self.enforce_max_turns,
             truncate_turns=self.truncate_turns,

astrbot/core/astr_main_agent.py

@@ -12,6 +12,10 @@
 from pathlib import Path
 
 from astrbot.core import logger
+from astrbot.core.agent.context.config import (
+    DEFAULT_FALLBACK_MAX_CONTEXT_TOKENS,
+    resolve_compression_threshold,
+)
 from astrbot.core.agent.handoff import HandoffTool
 from astrbot.core.agent.mcp_client import MCPTool
 from astrbot.core.agent.message import TextPart
@@ -97,6 +101,7 @@
     get_astrbot_system_tmp_path,
     get_astrbot_workspaces_path,
 )
+from astrbot.core.utils.config_number import coerce_int_config
 from astrbot.core.utils.file_extract import extract_file_moonshotai
 from astrbot.core.utils.llm_metadata import LLM_METADATAS
 from astrbot.core.utils.media_utils import (
@@ -178,6 +183,12 @@ class MainAgentBuildConfig:
     """The API key for Moonshot AI file extraction provider."""
     context_limit_reached_strategy: str = "truncate_by_turns"
     """The strategy to handle context length limit reached."""
+    compression_threshold_mode: str = "percentage"
+    """How percentage and output-reserve compression thresholds are combined."""
+    compression_threshold_percentage: float = 0.82
+    """User-defined context usage threshold."""
+    compression_max_output_tokens: int = 0
+    """Maximum output budget override. Zero uses model metadata."""
     llm_compress_instruction: str = ""
     """The instruction for compression in llm_compress strategy."""
     llm_compress_keep_recent_ratio: float = 0.15
@@ -189,7 +200,7 @@ class MainAgentBuildConfig:
     This enforce max turns before compression"""
     dequeue_context_length: int = 10
     """The number of oldest turns to remove when context length limit is reached."""
-    fallback_max_context_tokens: int = 128000
+    fallback_max_context_tokens: int = DEFAULT_FALLBACK_MAX_CONTEXT_TOKENS
     """Fallback max context tokens. When max_context_tokens is 0 and the model is not in LLM_METADATAS, use this value."""
     llm_safety_mode: bool = True
     """This will inject healthy and safe system prompt into the main agent,
@@ -1593,17 +1604,59 @@ async def build_main_agent(
             req.model = None
         fallback_providers = [p for p in fallback_providers if p is not provider]
 
-    if provider.provider_config.get("max_context_tokens", 0) <= 0:
-        model = provider.get_model()
-        if model_info := LLM_METADATAS.get(model):
-            provider.provider_config["max_context_tokens"] = model_info["limit"][
-                "context"
-            ]
-        else:
-            # fallback: default to configured fallback value
-            provider.provider_config["max_context_tokens"] = (
-                config.fallback_max_context_tokens
-            )
+    configured_context_tokens = coerce_int_config(
+        provider.provider_config.get("max_context_tokens", 0),
+        default=0,
+        min_value=0,
+        field_name="max_context_tokens",
+        source="provider config",
+    )
+    model_info = LLM_METADATAS.get(provider.get_model())
+    metadata_limit = (model_info.get("limit") or {}) if model_info else {}
+    metadata_context_tokens = coerce_int_config(
+        metadata_limit.get("context", 0),
+        default=0,
+        min_value=0,
+        field_name="model context limit",
+        source="model metadata",
+    )
+    fallback_context_tokens = coerce_int_config(
+        config.fallback_max_context_tokens,
+        default=DEFAULT_FALLBACK_MAX_CONTEXT_TOKENS,
+        min_value=1,
+        field_name="fallback_max_context_tokens",
+    )
+    provider.provider_config["max_context_tokens"] = (
+        configured_context_tokens or metadata_context_tokens or fallback_context_tokens
+    )
+
+    metadata_output_tokens = coerce_int_config(
+        metadata_limit.get("output", 0),
+        default=0,
+        min_value=0,
+        field_name="model output limit",
+        source="model metadata",
+    )
+    configured_output_tokens = coerce_int_config(
+        config.compression_max_output_tokens,
+        default=0,
+        min_value=0,
+        field_name="compression_max_output_tokens",
+    )
+    threshold_result = resolve_compression_threshold(
+        mode=config.compression_threshold_mode,
+        percentage=config.compression_threshold_percentage,
+        max_context_tokens=provider.provider_config["max_context_tokens"],
+        max_output_tokens=configured_output_tokens or metadata_output_tokens,
+    )
+    if threshold_result["fallback_reason"]:
+        logger.warning(
+            "Compression threshold mode %s requires max output tokens, but no "
+            "override or model metadata is available for %s; using %.0f%%.",
+            threshold_result["mode"],
+            provider.get_model(),
+            threshold_result["effective_threshold"] * 100,
+        )
 
     if event.get_platform_name() == "webchat":
         asyncio.create_task(_handle_webchat(event, req, provider))
@@ -1645,6 +1698,7 @@ async def build_main_agent(
         tool_executor=FunctionToolExecutor(),
         agent_hooks=MAIN_AGENT_HOOKS,
         streaming=config.streaming_response,
+        compression_threshold=threshold_result["effective_threshold"],
         llm_compress_instruction=config.llm_compress_instruction,
         llm_compress_keep_recent_ratio=config.llm_compress_keep_recent_ratio,
         llm_compress_provider=_get_compress_provider(config, plugin_context, event),

astrbot/core/config/default.py

@@ -125,6 +125,9 @@
         "persona_pool": ["*"],
         "prompt_prefix": "{{prompt}}",
         "context_limit_reached_strategy": "llm_compress",  # or truncate_by_turns
+        "compression_threshold_mode": "percentage",
+        "compression_threshold_percentage": 0.82,
+        "compression_max_output_tokens": 0,
         "llm_compress_instruction": (
             "Based on our full conversation history, produce a concise summary of key takeaways and/or project progress.\n"
             "The primary goal of this summary is to enable seamless continuation of the work that follows.\n"
@@ -3592,6 +3595,38 @@
                             "provider_settings.agent_runner_type": "local",
                         },
                     },
+                    "provider_settings.compression_threshold_mode": {
+                        "description": "上下文压缩阈值模式",
+                        "type": "string",
+                        "options": ["percentage", "output_reserve", "min", "max"],
+                        "labels": [
+                            "仅按百分比",
+                            "上下文窗口减去最大输出",
+                            "两者取较小值（更早压缩）",
+                            "两者取较大值（更晚压缩）",
+                        ],
+                        "hint": "输出上限未知时，依赖输出预留的模式会自动退化为百分比阈值。",
+                        "condition": {
+                            "provider_settings.agent_runner_type": "local",
+                        },
+                    },
+                    "provider_settings.compression_threshold_percentage": {
+                        "description": "上下文压缩百分比阈值",
+                        "type": "float",
+                        "slider": {"min": 0.01, "max": 1, "step": 0.01},
+                        "hint": "0.82 表示上下文使用率超过 82% 时触发压缩。",
+                        "condition": {
+                            "provider_settings.agent_runner_type": "local",
+                        },
+                    },
+                    "provider_settings.compression_max_output_tokens": {
+                        "description": "压缩策略使用的最大输出 Token",
+                        "type": "int",
+                        "hint": "0 表示自动读取当前模型元数据；元数据也不可用时退化为百分比阈值。大于 0 时覆盖模型元数据。",
+                        "condition": {
+                            "provider_settings.agent_runner_type": "local",
+                        },
+                    },
                     "provider_settings.context_limit_reached_strategy": {
                         "description": "历史超限或上下文接近上限时的处理方式",
                         "type": "string",