Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(config): warn when unknown config fields are ignored (#5193)
Johnny1f1c46e11bf6
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.mdindex f26bc455e..c632bc078 100644--- a/docs/en/configuration/01-server.md+++ b/docs/en/configuration/01-server.md@@ -36,7 +36,7 @@ The server reads the file at startup. Restart the server after changing models,}```-Optional sections use their defaults when omitted. Unknown fields in `ov.conf` and persisted account settings are ignored for upgrade compatibility. Known fields still validate types and values; misspelled field names are also ignored.+Optional sections use their defaults when omitted. Unknown fields in `ov.conf` and persisted account settings are ignored for upgrade compatibility. Known fields still validate types and values. Misspelled field names are also ignored, but the server logs a warning listing every field it did not apply.## Top-Level Settingsdiff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.mdindex 956de6ce8..4d835023d 100644--- a/docs/zh/configuration/01-server.md+++ b/docs/zh/configuration/01-server.md@@ -36,7 +36,7 @@ openviking-server --config /path/to/ov.conf}```-未配置的可选模块使用默认值。`ov.conf` 及账户配置会忽略未知字段,兼容旧版本遗留配置;已知字段仍校验类型和取值。字段名拼写错误也会被忽略。+未配置的可选模块使用默认值。`ov.conf` 及账户配置会忽略未知字段,兼容旧版本遗留配置;已知字段仍校验类型和取值。字段名拼写错误也会被忽略,但服务端会输出 WARNING,逐项列出未被采用的字段。## 顶层配置diff --git a/openviking/config/binding.py b/openviking/config/binding.pyindex 4d4dbe016..4f90e70fa 100644--- a/openviking/config/binding.py+++ b/openviking/config/binding.py@@ -21,7 +21,11 @@ from openviking.config.source.file_source import FileConfigSourcefrom openviking.config.validate import validate_patchfrom openviking.pyagfs import AsyncAGFSClientfrom openviking_cli.utils.config import get_openviking_config, set_openviking_config+from openviking_cli.utils.config.config_utils import warn_unknown_config_fieldsfrom openviking_cli.utils.config.open_viking_config import OpenVikingConfig, RuntimeConfigSettings+from openviking_cli.utils.logger import get_logger++logger = get_logger(__name__)# The concrete manager type this module hands back.OpenVikingRuntimeConfigManager = RuntimeConfigManager[OpenVikingConfig, AccountConfig]@@ -49,8 +53,16 @@ def _build_cluster(old: OpenVikingConfig, override: dict) -> OpenVikingConfig:def _build_account(override: Optional[dict]) -> AccountConfig:- """Construct (and thereby validate) an account config from its sparse override."""- return AccountConfig.model_validate(override or {})+ """Construct (and thereby validate) an account config from its sparse override.++ A persisted account override may carry fields this binary does not declare --+ a retired ``namespace`` block, or a section written by a newer binary. They+ stay ignored so legacy settings keep loading, and the warning keeps the drop+ visible. Only field names are logged, never values.+ """+ sparse = override or {}+ warn_unknown_config_fields(data=sparse, model=AccountConfig, logger=logger)+ return AccountConfig.model_validate(sparse)def _validate_request(patch: dict, is_account: bool, creating: bool) -> None:diff --git a/openviking/server/config.py b/openviking/server/config.pyindex 99e2a7e2d..fa75c8eb9 100644--- a/openviking/server/config.py+++ b/openviking/server/config.py@@ -18,7 +18,10 @@ from openviking_cli.utils.config.config_loader import (load_json_config,resolve_config_path,)-from openviking_cli.utils.config.config_utils import format_validation_error+from openviking_cli.utils.config.config_utils import (+ format_validation_error,+ warn_unknown_config_fields,+)from openviking_cli.utils.config.consts import (DEFAULT_CONFIG_DIR,DEFAULT_OV_CONF,@@ -479,6 +482,13 @@ def load_server_config(config_path: Optional[str] = None) -> ServerConfig:"See documentation for more details.")+ warn_unknown_config_fields(+ data=server_data,+ model=ServerConfig,+ path_prefix="server",+ logger=logger,+ )+try:config = ServerConfig.model_validate(server_data)except ValidationError as e:diff --git a/openviking_cli/utils/config/config_utils.py b/openviking_cli/utils/config/config_utils.pyindex 11251a02e..e2a4d2637 100644--- a/openviking_cli/utils/config/config_utils.py+++ b/openviking_cli/utils/config/config_utils.py@@ -3,6 +3,8 @@"""Shared helpers for config validation and error formatting."""import difflib+import logging+from collections.abc import Mappingfrom typing import Any, Optional, get_args, get_originfrom pydantic import BaseModel, ValidationError@@ -46,6 +48,86 @@ def _get_model_at_path(return current_model+def warn_unknown_fields(+ *,+ data: Mapping[str, Any],+ valid_fields: set[str],+ logger: logging.Logger,+ path_prefix: str = "",+) -> None:+ """Warn about keys the owner of one config section does not declare.++ Unknown fields stay ignored so legacy configuration keeps loading; the+ warning keeps the mismatch visible to whoever wrote the file. Only field+ names are logged, never values.+ """+ messages = []+ for key in data:+ if key in valid_fields:+ continue+ field_path = f"{path_prefix}.{key}" if path_prefix else key+ # Config files are JSON, but from_dict() is also called programmatically;+ # a diagnostic must never be the reason loading fails.+ messages.append(f"Ignoring unknown config field '{field_path!s}'")+ if messages:+ logger.warning("%s", "\n".join(messages))+++def _child_model_type(annotation: Any) -> Optional[type[BaseModel]]:+ """Return the model nested values must validate against, when unambiguous."""+ if isinstance(annotation, type) and issubclass(annotation, BaseModel):+ return annotation++ args = get_args(annotation)+ if not args or any(get_origin(arg) in (dict, Mapping) for arg in args):+ return None++ models = {model for model in (_unwrap_model_type(arg) for arg in args) if model is not None}+ if len(models) == 1:+ return models.pop()+ return None+++def warn_unknown_config_fields(+ *,+ data: Mapping[str, Any],+ model: type[BaseModel],+ logger: logging.Logger,+ path_prefix: str = "",+ extra_valid_fields: Optional[set[str]] = None,+) -> None:+ """Warn about config keys the model does not declare, recursing into sub-models.++ ``extra_valid_fields`` lists keys consumed by another owner (for example the+ ``server`` section) so they are not reported as unknown.+ """+ warn_unknown_fields(+ data=data,+ valid_fields=set(model.model_fields) | (extra_valid_fields or set()),+ logger=logger,+ path_prefix=path_prefix,+ )++ for key, value in data.items():+ field = model.model_fields.get(key)+ if field is None:+ continue+ child_model = _child_model_type(field.annotation)+ if child_model is None:+ continue+ child_prefix = f"{path_prefix}.{key}" if path_prefix else key+ is_sequence = isinstance(value, (list, tuple))+ for index, item in enumerate(value if is_sequence else (value,)):+ if not isinstance(item, Mapping):+ continue+ warn_unknown_config_fields(+ data=item,+ model=child_model,+ logger=logger,+ path_prefix=f"{child_prefix}[{index}]" if is_sequence else child_prefix,+ )++def format_validation_error(*,root_model: type[BaseModel],diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.pyindex e8dbf082d..b418bc6fc 100644--- a/openviking_cli/utils/config/open_viking_config.py+++ b/openviking_cli/utils/config/open_viking_config.py@@ -14,7 +14,11 @@ from openviking_cli.session.user_id import UserIdentifierfrom .agent_evolution_config import AgentEvolutionConfigfrom .cache_config import CacheConfigfrom .config_loader import resolve_config_path-from .config_utils import format_validation_error+from .config_utils import (+ format_validation_error,+ warn_unknown_config_fields,+ warn_unknown_fields,+)from .consts import (DEFAULT_CONFIG_DIR,DEFAULT_OV_CONF,@@ -477,6 +481,13 @@ class OpenVikingConfig(BaseModel):"webfeed",]+ warn_unknown_config_fields(+ data=config_copy,+ model=cls,+ extra_valid_fields={"server", "bot", "parsers"},+ logger=_get_config_logger(),+ )+# Remove sections managed by other loaders (e.g. server config)config_copy.pop("server", None)config_copy.pop("bot", None)@@ -496,6 +507,12 @@ class OpenVikingConfig(BaseModel):"Config field 'parsers.excel' was removed and is ignored; ""spreadsheet parsing now uses 'parsers.anydoc'.")+ warn_unknown_fields(+ data=parser_configs,+ valid_fields=set(parser_types),+ path_prefix="parsers",+ logger=_get_config_logger(),+ )for parser_type in parser_types:if parser_type in config_copy:parser_configs[parser_type] = config_copy.pop(parser_type)@@ -534,6 +551,13 @@ class OpenVikingConfig(BaseModel):if parser_type in parser_configs:parser_data = parser_configs[parser_type]config_class = getattr(instance, parser_type).__class__+ if isinstance(parser_data, dict):+ warn_unknown_fields(+ data=parser_data,+ valid_fields=set(config_class.__dataclass_fields__),+ path_prefix=f"parsers.{parser_type}",+ logger=_get_config_logger(),+ )setattr(instance, parser_type, config_class.from_dict(parser_data))# Check dimension consistencydiff --git a/tests/test_config_loader.py b/tests/test_config_loader.pyindex 132ad93c3..c6cefcce5 100644--- a/tests/test_config_loader.py+++ b/tests/test_config_loader.py@@ -309,11 +309,14 @@ def test_openviking_config_handles_nested_parser_compatibility(monkeypatch):OpenVikingConfigSingleton.reset_instance()-def test_openviking_config_ignores_unknown_fields(monkeypatch):+def test_openviking_config_ignores_unknown_fields(monkeypatch, caplog):monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")+ logger = logging.getLogger("openviking_cli.utils.config.open_viking_config")+ monkeypatch.setattr(logger, "handlers", [*logger.handlers, caplog.handler])+ caplog.set_level(logging.WARNING, logger=logger.name)config = OpenVikingConfig.from_dict({- "retired_section": {"enabled": True},+ "retired_section": {"api_key": "test-secret"},"default_user": "alice","glob": {"retired_field": True, "engine": "fs"},"memory": {"unknown_memory_field": "value", "session_skill_extraction_enabled": True},@@ -339,6 +342,9 @@ def test_openviking_config_ignores_unknown_fields(monkeypatch):assert "retired_field" not in dumped["glob"]assert "unknown_memory_field" not in dumped["memory"]assert "cache" not in dumped["storage"]["agfs"]+ assert "Ignoring unknown config field 'storage.agfs.cache'" in caplog.text+ assert "Ignoring unknown config field 'parsers.markdown.unknown_field'" in caplog.text+ assert "test-secret" not in caplog.textdef test_memory_extraction_output_format_defaults_to_python_and_accepts_json(monkeypatch):