"""系统设置元数据、查询更新语义和敏感值脱敏能力。""" import copy from collections.abc import Awaitable, Callable from dataclasses import dataclass from typing import Any, Optional from app.application.configuration import ( RuntimeSettingsService, SystemConfigService, ) from app.application.plugin.runtime import plugin_system_config_mutation from app.application.security.secrets import is_secret_setting_key from app.runtime.config import Settings from app.schemas.types import SystemConfigKey SystemSettingPublisher = Callable[[Any, Any], Awaitable[None]] @dataclass(frozen=True) class SettingSpec: """描述一个可被 Agent 读写的系统设置项。""" key: str source: str group: str label: str declared_type: str = "unknown" systemconfig_key: Optional[SystemConfigKey] = None class SystemSettingConflictError(ValueError): """表示条件更新所依据的系统配置快照已经过期。""" SYSTEMCONFIG_SETTING_METADATA = { SystemConfigKey.Downloaders.value: { "group": "downloaders", "label": "Downloader configurations", }, SystemConfigKey.MediaServers.value: { "group": "media_servers", "label": "Media-server configurations", }, SystemConfigKey.Notifications.value: { "group": "notifications", "label": "Notification-channel configurations", }, SystemConfigKey.NotificationSwitchs.value: { "group": "notification_switches", "label": "Notification-scenario switches", }, SystemConfigKey.Directories.value: { "group": "directories", "label": "Directory configurations", }, SystemConfigKey.Storages.value: { "group": "storages", "label": "Storage configurations", }, SystemConfigKey.IndexerSites.value: { "group": "search_sites", "label": "Search-site scope", }, SystemConfigKey.RssSites.value: { "group": "subscribe_sites", "label": "Subscription-site scope", }, SystemConfigKey.UserSiteAuthParams.value: { "group": "site_auth", "label": "Site authentication parameters", }, SystemConfigKey.AIAgentConfig.value: { "group": "ai_agent", "label": "AI Agent configuration", }, SystemConfigKey.AIAgentMcpServers.value: { "group": "ai_agent", "label": "AI Agent external MCP servers", }, SystemConfigKey.CustomIdentifiers.value: { "group": "custom_identifiers", "label": "Custom recognition identifiers", }, SystemConfigKey.EpisodeFormatRuleTable.value: { "group": "transfer", "label": "Episode-position rule table", }, SystemConfigKey.CustomReleaseGroups.value: { "group": "customization", "label": "Custom release and subtitle groups", }, SystemConfigKey.Customization.value: { "group": "customization", "label": "Custom placeholders", }, SystemConfigKey.TransferExcludeWords.value: { "group": "transfer", "label": "Transfer exclusion words", }, SystemConfigKey.TorrentsPriority.value: { "group": "filter_rules", "label": "Torrent-priority rules", }, SystemConfigKey.CustomFilterRules.value: { "group": "filter_rules", "label": "User-defined filter rules", }, SystemConfigKey.UserFilterRuleGroups.value: { "group": "filter_rules", "label": "User filter-rule groups", }, SystemConfigKey.SearchFilterRuleGroups.value: { "group": "filter_rules", "label": "Default search filter-rule groups", }, SystemConfigKey.SubscribeFilterRuleGroups.value: { "group": "filter_rules", "label": "Default subscription filter-rule groups", }, SystemConfigKey.BestVersionFilterRuleGroups.value: { "group": "filter_rules", "label": "Default upgrade filter-rule groups", }, SystemConfigKey.SubscribeDefaultParams.value: { "group": "subscribe_defaults", "label": "Default subscription parameters", }, SystemConfigKey.DefaultMovieSubscribeConfig.value: { "group": "subscribe_defaults", "label": "Default movie subscription rules", }, SystemConfigKey.DefaultTvSubscribeConfig.value: { "group": "subscribe_defaults", "label": "Default TV subscription rules", }, SystemConfigKey.DefaultMusicSubscribeConfig.value: { "group": "subscribe_defaults", "label": "Default music subscription rules", }, SystemConfigKey.UserInstalledPlugins.value: { "group": "plugins", "label": "Installed plugin list", }, SystemConfigKey.PluginFolders.value: { "group": "plugins", "label": "Plugin folder grouping", }, SystemConfigKey.PluginInstallReport.value: { "group": "plugins", "label": "Plugin installation report", }, SystemConfigKey.NotificationSendTime.value: { "group": "notifications", "label": "Notification delivery time", }, SystemConfigKey.NotificationTemplates.value: { "group": "notifications", "label": "Notification templates", }, SystemConfigKey.ScrapingSwitchs.value: { "group": "scraping", "label": "Metadata-scraping switches", }, SystemConfigKey.FollowSubscribers.value: { "group": "subscribe_sites", "label": "Followed subscription publishers", }, } LIST_ITEM_MATCH_FIELD_DEFAULTS = { SystemConfigKey.Downloaders.value: "name", SystemConfigKey.MediaServers.value: "name", SystemConfigKey.Notifications.value: "name", SystemConfigKey.NotificationSwitchs.value: "type", SystemConfigKey.Directories.value: "name", SystemConfigKey.Storages.value: "name", } GROUP_ALIASES = { "all": "all", "全部": "all", "settings": "settings", "basic": "settings", "基础设置": "settings", "基础配置": "settings", "systemconfig": "systemconfig", "system_config": "systemconfig", "系统设置": "systemconfig", "系统配置": "systemconfig", "downloaders": "downloaders", "downloader": "downloaders", "下载器": "downloaders", "media_servers": "media_servers", "mediaservers": "media_servers", "media-servers": "media_servers", "媒体服务器": "media_servers", "notifications": "notifications", "notification": "notifications", "消息通知": "notifications", "通知": "notifications", "notification_switches": "notification_switches", "notification_switchs": "notification_switches", "通知开关": "notification_switches", "storages": "storages", "storage": "storages", "存储": "storages", "directories": "directories", "directory": "directories", "目录": "directories", "search_sites": "search_sites", "indexer_sites": "search_sites", "搜索站点": "search_sites", "subscribe_sites": "subscribe_sites", "rss_sites": "subscribe_sites", "订阅站点": "subscribe_sites", "site_auth": "site_auth", "site_auth_params": "site_auth", "站点认证": "site_auth", "ai_agent": "ai_agent", "agent": "ai_agent", "智能体": "ai_agent", "custom_identifiers": "custom_identifiers", "自定义识别词": "custom_identifiers", "filter_rules": "filter_rules", "过滤规则": "filter_rules", "subscribe_defaults": "subscribe_defaults", "订阅默认": "subscribe_defaults", "plugins": "plugins", "插件": "plugins", "customization": "customization", "自定义": "customization", "transfer": "transfer", "整理": "transfer", "scraping": "scraping", "刮削": "scraping", "misc": "misc", "其他": "misc", } # 这些前缀共同组成可启动、推理和扩展 AI Agent 的同一业务配置域。 AI_AGENT_CORE_SETTING_PREFIXES = ( "AI_AGENT_", "LLM_", "AUDIO_INPUT_", "AUDIO_OUTPUT_", "AI_RECOMMEND_", ) def _normalize_token(value: str) -> str: return str(value).strip().lower().replace("-", "_") def _resolve_core_setting_group(key: str) -> str: """根据基础设置的业务归属返回 Agent 可查询的分类。""" if key.startswith(AI_AGENT_CORE_SETTING_PREFIXES): return "ai_agent" return "settings" def _format_declared_type(annotation: Any) -> str: """把 Pydantic 字段注解转换为稳定且便于 Agent 阅读的类型文本。""" rendered = str(annotation).replace("typing.", "") return rendered.replace("", "") def _build_specs() -> tuple[dict[str, SettingSpec], dict[str, SettingSpec]]: core_specs = { key: SettingSpec( key=key, source="settings", group=_resolve_core_setting_group(key), label=key, declared_type=_format_declared_type(field.annotation), ) for key, field in Settings.model_fields.items() } system_specs = {} for item in SystemConfigKey: metadata = SYSTEMCONFIG_SETTING_METADATA.get(item.value, {}) system_specs[item.value] = SettingSpec( key=item.value, source="systemconfig", group=metadata.get("group", "misc"), label=metadata.get("label", item.value), declared_type=( "list[object]" if item.value in LIST_ITEM_MATCH_FIELD_DEFAULTS else "JSON-compatible value" ), systemconfig_key=item, ) return core_specs, system_specs CORE_SETTING_SPECS, SYSTEMCONFIG_SETTING_SPECS = _build_specs() ALL_SETTING_SPECS = {**CORE_SETTING_SPECS, **SYSTEMCONFIG_SETTING_SPECS} SETTING_KEY_ALIASES = {} for key in CORE_SETTING_SPECS: SETTING_KEY_ALIASES[_normalize_token(key)] = key for item in SystemConfigKey: SETTING_KEY_ALIASES[_normalize_token(item.value)] = item.value SETTING_KEY_ALIASES[_normalize_token(item.name)] = item.value SINGLE_KEY_GROUP_ALIASES = { _normalize_token(alias): next( (spec.key for spec in ALL_SETTING_SPECS.values() if spec.group == canonical_group), None, ) for alias, canonical_group in GROUP_ALIASES.items() if canonical_group not in {"all", "settings", "systemconfig"} and len([spec.key for spec in ALL_SETTING_SPECS.values() if spec.group == canonical_group]) == 1 } def normalize_group(group: Optional[str]) -> str: if not group: return "all" normalized = GROUP_ALIASES.get(_normalize_token(group)) if not normalized: raise ValueError( "group 不支持，支持值包括 all/settings/systemconfig 以及" " downloaders、media_servers、notifications、storages、directories、" "search_sites、subscribe_sites、site_auth、ai_agent 等分类别名" ) return normalized def resolve_setting_spec(setting_key: Optional[str]) -> Optional[SettingSpec]: """把精确键名、枚举名或单键分组别名解析为统一的设置定义。""" if not setting_key: return None normalized = _normalize_token(setting_key) resolved_key = SETTING_KEY_ALIASES.get(normalized) or SINGLE_KEY_GROUP_ALIASES.get(normalized) if not resolved_key: return None return ALL_SETTING_SPECS.get(resolved_key) def list_setting_specs(group: Optional[str] = "all", keyword: Optional[str] = None) -> list[SettingSpec]: """按分组和关键字筛选可查询的设置项。""" normalized_group = normalize_group(group) if normalized_group == "all": specs = list(ALL_SETTING_SPECS.values()) elif normalized_group == "settings": specs = list(CORE_SETTING_SPECS.values()) elif normalized_group == "systemconfig": specs = list(SYSTEMCONFIG_SETTING_SPECS.values()) else: specs = [spec for spec in ALL_SETTING_SPECS.values() if spec.group == normalized_group] if keyword: normalized_keyword = _normalize_token(keyword) specs = [ spec for spec in specs if normalized_keyword in _normalize_token(spec.key) or normalized_keyword in _normalize_token(spec.group) or normalized_keyword in _normalize_token(spec.label) ] return sorted(specs, key=lambda spec: (spec.source, spec.group, spec.key)) def get_default_list_match_field(setting_key: str) -> Optional[str]: return LIST_ITEM_MATCH_FIELD_DEFAULTS.get(setting_key) def redact_secret_value(value: Any, *, redact_scalar: bool = False) -> Any: """递归脱敏配置值中的密钥、Cookie、Token 等敏感字段。""" if isinstance(value, dict): return { key: "***" if is_secret_setting_key(str(key)) else redact_secret_value(item, redact_scalar=redact_scalar) for key, item in value.items() } if isinstance(value, list): return [redact_secret_value(item, redact_scalar=redact_scalar) for item in value] if isinstance(value, str): return "***" if value and redact_scalar else value return value def should_redact_setting(spec: SettingSpec, value: Any) -> bool: """判断某项设置在默认查询响应中是否需要脱敏。""" if is_secret_setting_key(spec.key): return True if isinstance(value, dict): return any(is_secret_setting_key(str(key)) for key in value.keys()) if isinstance(value, list): return any(should_redact_setting(spec, item) for item in value if isinstance(item, dict)) return False class SystemSettingsService: """提供 Agent 与管理 API 共用的受控系统设置查询和更新。""" def __init__( self, runtime_settings: RuntimeSettingsService, system_config: SystemConfigService, publish_config_changed: SystemSettingPublisher, ) -> None: """注入部署设置、持久化配置和配置事件发布端口。""" self._runtime_settings = runtime_settings self._system_config = system_config self._publish_config_changed = publish_config_changed def _load(self, spec: SettingSpec) -> Any: """按设置来源读取当前值。""" if spec.source == "settings": return self._runtime_settings.get(spec.key) return self._system_config.get(spec.systemconfig_key) @staticmethod def _summarize(value: Any, *, redacted: bool = False) -> dict[str, Any]: """生成有界值摘要，避免配置列表和字典挤占响应上下文。""" summary: dict[str, Any] = { "has_value": value is not None, "value_type": type(value).__name__, "redacted": redacted, } if isinstance(value, list): summary["item_count"] = len(value) if value: summary["item_type"] = type(value[0]).__name__ elif isinstance(value, dict): keys = list(value) summary["item_count"] = len(keys) summary["keys_preview"] = keys[:10] summary["keys_truncated"] = len(keys) > 10 elif isinstance(value, str): summary["length"] = len(value) summary["value_preview"] = value[:200] summary["value_truncated"] = len(value) > 200 elif value is not None: summary["value_preview"] = value return summary @staticmethod def _definition(spec: SettingSpec, value: Any, *, sensitive: bool) -> dict[str, Any]: """返回当前设置值形状、持久化位置和允许的更新操作。""" default_match_field = get_default_list_match_field(spec.key) if isinstance(value, list) or (value is None and default_match_field): update_operations = ["replace", "upsert_list_item", "remove_list_item"] value_shape = "list" elif isinstance(value, dict): update_operations = ["replace", "merge_dict"] value_shape = "object" else: update_operations = ["replace"] value_shape = type(value).__name__ if value is not None else "unknown" return { "declared_type": spec.declared_type, "value_shape": value_shape, "nullable": value is None, "sensitive": sensitive, "update_operations": update_operations, "default_match_field": default_match_field, "persistence": "app.env" if spec.source == "settings" else "database:systemconfig", } def query( self, *, setting_key: Optional[str] = None, group: Optional[str] = "all", keyword: Optional[str] = None, include_values: Optional[bool] = None, show_secrets: bool = False, ) -> dict[str, Any]: """查询登记设置，并在未授权明文读取时递归脱敏。""" if setting_key: spec = resolve_setting_spec(setting_key) if spec is None: raise ValueError(f"系统设置项 '{setting_key}' 不存在") specs = [spec] else: specs = list_setting_specs(group=group, keyword=keyword) if not specs: raise ValueError("没有找到匹配的系统设置项") should_include_values = include_values if include_values is not None else len(specs) == 1 payload = [] for spec in specs: value = self._load(spec) redacted = should_redact_setting(spec, value) and not show_secrets response_value = ( redact_secret_value( value, redact_scalar=is_secret_setting_key(spec.key), ) if redacted else value ) item = { "setting_key": spec.key, "source": spec.source, "group": spec.group, "label": spec.label, "definition": self._definition( spec, value, sensitive=should_redact_setting(spec, value), ), **self._summarize(response_value, redacted=redacted), } if should_include_values: item["value"] = response_value payload.append(item) return { "matched_count": len(payload), "include_values": should_include_values, "show_secrets": show_secrets, "settings": payload, } @staticmethod def _normalize_systemconfig_value(value: Any) -> Any: """将只含空项的列表折叠为空配置。""" if isinstance(value, list): filtered = [item for item in value if item is not None] return filtered or None return value @classmethod def _normalize_comparison_value(cls, spec: SettingSpec, value: Any) -> Any: """按专用 API 的公开投影规范化条件更新比较值。""" normalized = cls._normalize_systemconfig_value(value) if spec.systemconfig_key == SystemConfigKey.CustomIdentifiers and isinstance(normalized, list): identifiers = [item for item in normalized if isinstance(item, str)] return identifiers or None return normalized @staticmethod def _resolve_list_match( spec: SettingSpec, operation: str, value: Any, match_field: Optional[str], match_value: Any, ) -> tuple[Optional[str], Any]: """解析列表项修改使用的稳定匹配字段和值。""" resolved_field = match_field or get_default_list_match_field(spec.key) resolved_value = match_value if isinstance(value, dict): if not resolved_field: raise ValueError(f"{operation} 需要提供 match_field，或使用带默认匹配字段的系统配置项") if resolved_value is None: resolved_value = value.get(resolved_field) if resolved_value is None: raise ValueError(f"{operation} 缺少匹配值，请在 value.{resolved_field} 或 match_value 中提供") elif resolved_value is None: resolved_value = value return resolved_field, resolved_value @classmethod def _prepare_next_value( cls, spec: SettingSpec, current_value: Any, value: Any, operation: str, remove_keys: Optional[list[str]], match_field: Optional[str], match_value: Any, ) -> Any: """按显式更新语义构造下一配置值。""" if operation == "replace": return value if operation == "merge_dict": if current_value is not None and not isinstance(current_value, dict): raise ValueError("merge_dict 仅支持当前值为 dict 的设置项") if value is not None and not isinstance(value, dict): raise ValueError("merge_dict 的 value 必须是 dict 或 null") next_value = dict(current_value or {}) next_value.update(value or {}) for key in remove_keys or []: next_value.pop(key, None) return next_value if operation not in {"upsert_list_item", "remove_list_item"}: raise ValueError(f"不支持的操作: {operation}") if current_value is not None and not isinstance(current_value, list): raise ValueError(f"{operation} 仅支持当前值为 list 的设置项") next_items = list(copy.deepcopy(current_value or [])) resolved_field, resolved_value = cls._resolve_list_match(spec, operation, value, match_field, match_value) if operation == "upsert_list_item": if value is None: raise ValueError("upsert_list_item 必须提供 value") for index, item in enumerate(next_items): matched = ( isinstance(item, dict) and resolved_field and item.get(resolved_field) == resolved_value ) or (not resolved_field and item == resolved_value) if matched: next_items[index] = value break else: next_items.append(value) return next_items return [ item for item in next_items if not (isinstance(item, dict) and resolved_field and item.get(resolved_field) == resolved_value) and not (not resolved_field and item == resolved_value) ] async def update( self, *, setting_key: str, value: Any = None, operation: str = "replace", remove_keys: Optional[list[str]] = None, match_field: Optional[str] = None, match_value: Any = None, expected_value: Any = None, enforce_expected_value: bool = False, ) -> dict[str, Any]: """更新登记设置，可选校验旧值，并发布统一配置变更事件。""" spec = resolve_setting_spec(setting_key) if spec is None: raise ValueError(f"系统设置项 '{setting_key}' 不存在") if enforce_expected_value and spec.source != "systemconfig": raise ValueError("条件更新仅支持数据库系统配置") mutation_key = spec.systemconfig_key if spec.source == "systemconfig" else None with plugin_system_config_mutation(mutation_key): message = "" if spec.source == "settings": previous_value = self._load(spec) next_value = self._prepare_next_value( spec, previous_value, value, operation, remove_keys, match_field, match_value, ) event_value = next_value success, message = self._runtime_settings.update(spec.key, next_value) if success is False: raise ValueError(message or f"更新设置 {spec.key} 失败") changed = success is True elif enforce_expected_value: normalized_expected = self._normalize_comparison_value(spec, expected_value) def mutate(current_value: Any) -> tuple[tuple[Any, Any, bool], Any]: """在配置写锁内校验旧值并构造本次替换结果。""" normalized_current = self._normalize_comparison_value(spec, current_value) if normalized_current != normalized_expected: raise SystemSettingConflictError( f"系统设置 {spec.key} 已被其他会话更新，请重新加载后再保存" ) next_value = self._prepare_next_value( spec, current_value, value, operation, remove_keys, match_field, match_value, ) normalized_next = self._normalize_systemconfig_value(next_value) return ( current_value, normalized_next, normalized_current != normalized_next, ), normalized_next previous_value, event_value, changed = ( await self._system_config.async_update_atomically( spec.systemconfig_key, mutate, ) ) else: previous_value = self._load(spec) next_value = self._prepare_next_value( spec, previous_value, value, operation, remove_keys, match_field, match_value, ) event_value = self._normalize_systemconfig_value(next_value) write_result = ( await self._system_config.async_set_with_normalized_value( spec.systemconfig_key, event_value, ) ) event_value = write_result.normalized_value changed = bool(write_result.changed) if changed: await self._publish_config_changed(spec.key, event_value) saved_value = self._load(spec) redact_values = should_redact_setting(spec, previous_value) or should_redact_setting(spec, saved_value) return { "message": message or (f"系统设置 {spec.key} 已更新" if changed else "配置值未发生变化"), "changed": changed, "operation": operation, "setting": { "setting_key": spec.key, "source": spec.source, "group": spec.group, "label": spec.label, }, "values_redacted": redact_values, "previous_value": ( redact_secret_value( previous_value, redact_scalar=is_secret_setting_key(spec.key), ) if redact_values else previous_value ), "saved_value": ( redact_secret_value( saved_value, redact_scalar=is_secret_setting_key(spec.key), ) if redact_values else saved_value ), }