+
+
+
+ 会话
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 配置覆盖
+ +
+
+
+
+
+ {{ item.label }}
+
+
+ {{ item.key }}
+
+
+ 全局配置
+ {{ displayValue(globalValues[item.key]) }}
+
+
+ 生效值
+ {{ displayValue(effectiveValue(item.key)) }}
+
+
+
+
+
+ 
- 
'
+
+ content = gap_img.join(img_tags)
+ return f'{content}'
+
+
+async def send_with_filter_chain(
+ images: list[Path],
+ event: AstrMessageEvent,
+ config: Any,
+) -> str:
+ """Send images using filter chain based on config.
+
+ Args:
+ images: List of image file paths
+ event: Message event
+ config: Plugin config
+
+ Returns:
+ Result message string
+ """
+ send_mode = config.delivery.send_mode
+ if send_mode:
+ send_mode_str = (
+ send_mode.value if hasattr(send_mode, "value") else str(send_mode)
+ )
+ else:
+ send_mode_str = "auto"
+
+ # Build filter chain based on send mode
+ if send_mode_str == "forward":
+ chain = [forward_send_filter, direct_send_filter, html_card_filter]
+ elif send_mode_str == "image":
+ chain = [direct_send_filter, html_card_filter]
+ else: # auto or unknown
+ chain = [direct_send_filter, html_card_filter]
+
+ # Try filters in order
+ for filter_func in chain:
+ result = await filter_func(images, event, config)
+ if result.success:
+ return result.message or "发送成功"
+
+ # All filters failed
+ fail_msg = config.msg_send_failed_text if config else None
+ return fail_msg or "图片发送失败"
+
+
+__all__ = [
+ "SendResult",
+ "SendFilter",
+ "direct_send_filter",
+ "forward_send_filter",
+ "html_card_filter",
+ "send_with_filter_chain",
+]
diff --git a/src/infrastructure/sending/send_strategies.py b/src/infrastructure/sending/send_strategies.py
new file mode 100644
index 0000000..7c69f11
--- /dev/null
+++ b/src/infrastructure/sending/send_strategies.py
@@ -0,0 +1,363 @@
+"""Send strategy pattern for image delivery.
+
+Defines the strategy interface and implementations for different send modes:
+- Direct send: send images directly in message chain
+- Forward send: use merge forward (OneBot v11 feature)
+- HTML card fallback: wrap images in HTML cards to bypass censorship
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+import astrbot.api.message_components as Comp
+from astrbot.api.event import AstrMessageEvent
+
+from ...shared import get_logger
+
+logger = get_logger()
+
+
+class SendStrategy(ABC):
+ """Abstract base class for send strategies."""
+
+ @abstractmethod
+ async def send(
+ self,
+ event: AstrMessageEvent,
+ chain: list[Any],
+ auto_revoke: bool = False,
+ ) -> bool:
+ """Send message chain using this strategy.
+
+ Args:
+ event: Message event
+ chain: Message chain (list of components)
+ auto_revoke: Whether to schedule auto-revoke after send
+
+ Returns:
+ True if send succeeded, False otherwise
+ """
+ ...
+
+
+class DirectSendStrategy(SendStrategy):
+ """Direct send strategy — sends images in a single message chain."""
+
+ def __init__(self, plugin_context: Any) -> None:
+ """Initialize direct send strategy.
+
+ Args:
+ plugin_context: Plugin context for sending messages
+ """
+ self._context = plugin_context
+
+ async def send(
+ self,
+ event: AstrMessageEvent,
+ chain: list[Any],
+ auto_revoke: bool = False,
+ ) -> bool:
+ """Send images directly in message chain.
+
+ Args:
+ event: Message event
+ chain: Message chain
+ auto_revoke: Not supported for direct send (ignored)
+
+ Returns:
+ True if send succeeded
+ """
+ try:
+ send_result = await self._send_message(event, chain)
+
+ platform_name = getattr(event.platform, "name", "unknown")
+
+ # Only strict-check return value for OneBot platforms
+ if send_result is None and platform_name == "aiocqhttp":
+ logger.warning(
+ "[send] direct send returned None: platform=%s, chain=%d",
+ platform_name,
+ len(chain),
+ )
+ return False
+
+ logger.info(
+ "[send] direct send completed: platform=%s, chain=%d",
+ platform_name,
+ len(chain),
+ )
+ return True
+ except TimeoutError:
+ logger.warning(
+ "[send] direct send timed out: platform=%s, chain=%d",
+ getattr(event.platform, "name", "unknown"),
+ len(chain),
+ )
+ return False
+ except Exception as exc:
+ logger.exception(
+ "[send] direct send failed: platform=%s, chain=%d, error=%s",
+ getattr(event.platform, "name", "unknown"),
+ len(chain),
+ exc,
+ )
+ return False
+
+ async def _send_message(self, event: AstrMessageEvent, chain: list[Any]) -> Any:
+ if self._requires_onebot_passthrough(event, chain):
+ send_result = await self._send_onebot_image_chain(event, chain)
+ if send_result is not None:
+ return send_result
+ result = event.chain_result(chain)
+ return await self._context.send_message(event.unified_msg_origin, result)
+
+ def _requires_onebot_passthrough(
+ self, event: AstrMessageEvent, chain: list[Any]
+ ) -> bool:
+ platform_name = getattr(getattr(event, "platform", None), "name", "") or ""
+ return "aiocqhttp" in platform_name.lower() and any(
+ self._is_onebot_image_ref(comp)
+ for comp in chain
+ if isinstance(comp, Comp.Image)
+ )
+
+ def _is_onebot_image_ref(self, comp: Comp.Image) -> bool:
+ file_value = getattr(comp, "file", None)
+ return (
+ isinstance(file_value, str)
+ and "://" in file_value
+ and not (
+ file_value.startswith("file:///")
+ or file_value.startswith("http://")
+ or file_value.startswith("https://")
+ or file_value.startswith("base64://")
+ )
+ )
+
+ async def _send_onebot_image_chain(
+ self, event: AstrMessageEvent, chain: list[Any]
+ ) -> Any | None:
+ bot = getattr(event, "bot", None)
+ if bot is None:
+ return None
+
+ message: list[dict[str, Any]] = []
+ for comp in chain:
+ if isinstance(comp, Comp.Image):
+ message.append(
+ {
+ "type": "image",
+ "data": {"file": str(getattr(comp, "file", ""))},
+ }
+ )
+ else:
+ message.append(comp.toDict())
+
+ is_group = bool(event.get_group_id())
+ session_id = event.get_group_id() if is_group else event.get_sender_id()
+ if not session_id or not str(session_id).isdigit():
+ logger.debug(
+ "[send] skip OneBot passthrough: invalid session_id=%s",
+ session_id,
+ )
+ return None
+
+ if is_group:
+ return await bot.send_group_msg(group_id=int(session_id), message=message)
+ return await bot.send_private_msg(user_id=int(session_id), message=message)
+
+
+class ForwardSendStrategy(SendStrategy):
+ """Forward send strategy — uses merge forward (OneBot v11)."""
+
+ def __init__(self, plugin_context: Any) -> None:
+ """Initialize forward send strategy.
+
+ Args:
+ plugin_context: Plugin context for sending messages
+ """
+ self._context = plugin_context
+
+ async def send(
+ self,
+ event: AstrMessageEvent,
+ chain: list[Any],
+ auto_revoke: bool = False,
+ ) -> bool:
+ """Send images using merge forward.
+
+ Args:
+ event: Message event
+ chain: Message chain (list of image components)
+ auto_revoke: Not supported (handled by caller)
+
+ Returns:
+ True if send succeeded
+ """
+ import time
+
+ build_start = time.monotonic()
+ nodes = []
+ for comp in chain:
+ if isinstance(comp, Comp.Image):
+ node = Comp.Node(
+ uin=event.get_self_id(),
+ name="色图",
+ content=[comp],
+ )
+ nodes.append(node)
+
+ build_end = time.monotonic()
+ logger.debug(
+ "[forward] built nodes: count=%d, elapsed=%.3fs",
+ len(nodes),
+ build_end - build_start,
+ )
+
+ return await self._send_nodes_direct(event, nodes)
+
+ async def _send_nodes_direct(
+ self, event: AstrMessageEvent, nodes: list[Comp.Node]
+ ) -> bool:
+ """Send forward nodes directly.
+
+ Args:
+ event: Message event
+ nodes: Forward nodes
+
+ Returns:
+ True if send succeeded
+ """
+ try:
+ forward_chain = [Comp.Forward(node) for node in nodes]
+ result = event.chain_result(forward_chain)
+ await self._context.send_message(event.unified_msg_origin, result)
+
+ logger.info("[forward] send completed: nodes=%d", len(nodes))
+ return True
+ except Exception as exc:
+ logger.exception(
+ "[forward] send failed: nodes=%d, error=%s",
+ len(nodes),
+ exc,
+ )
+ return False
+
+
+class HtmlCardFallbackStrategy(SendStrategy):
+ """HTML card fallback strategy — wraps images in HTML cards."""
+
+ def __init__(
+ self,
+ plugin_context: Any,
+ html_renderer: Any,
+ style_options: dict[str, int] | None = None,
+ ) -> None:
+ """Initialize HTML card fallback strategy.
+
+ Args:
+ plugin_context: Plugin context
+ html_renderer: HtmlCardRenderer instance
+ style_options: Style options (card_padding, card_gap)
+ """
+ self._context = plugin_context
+ self._renderer = html_renderer
+ self._style_options = style_options or {}
+
+ async def send(
+ self,
+ event: AstrMessageEvent,
+ chain: list[Any],
+ auto_revoke: bool = False,
+ ) -> bool:
+ """Send images wrapped in HTML cards.
+
+ Args:
+ event: Message event
+ chain: Message chain (list of image components)
+ auto_revoke: Not supported (ignored)
+
+ Returns:
+ True if send succeeded
+ """
+ if not self._renderer:
+ logger.warning("[html_fallback] renderer unavailable")
+ return False
+
+ images: list[bytes] = []
+ for comp in chain:
+ if not isinstance(comp, Comp.Image):
+ continue
+ if isinstance(comp.file, bytes):
+ images.append(comp.file)
+ continue
+
+ path_value = getattr(comp, "path", None) or getattr(comp, "file", None)
+ if isinstance(path_value, str):
+ candidate = (
+ Path(path_value[8:])
+ if path_value.startswith("file:///")
+ else Path(path_value)
+ )
+ if candidate.exists():
+ try:
+ import asyncio
+
+ data = await asyncio.to_thread(candidate.read_bytes)
+ images.append(data)
+ except OSError:
+ logger.warning(
+ "[html_fallback] failed to read image path=%s",
+ candidate,
+ )
+
+ if not images:
+ logger.warning("[html_fallback] no images available after materialization")
+ return False
+
+ rendered_images = []
+ for i, img_data in enumerate(images):
+ logger.debug("[html_fallback] Rendering image %d/%d", i + 1, len(images))
+ rendered = await self._renderer.render_single_image(
+ context=self._context,
+ image=img_data,
+ style_options=self._style_options,
+ )
+ if rendered:
+ rendered_images.append(rendered)
+ else:
+ logger.warning("[html_fallback] failed to render image index=%d", i + 1)
+
+ if not rendered_images:
+ logger.warning("[html_fallback] renderer produced no images")
+ return False
+
+ # Send rendered images
+ chain = [Comp.Image.fromBytes(img) for img in rendered_images]
+ logger.info("[html_fallback] rendered images: count=%d", len(rendered_images))
+ return await DirectSendStrategy(self._context).send(event, chain, False)
+
+
+def resolve_send_mode(
+ send_mode: str,
+ image_count: int,
+ supports_forward: bool = True,
+) -> str:
+ """Resolve effective send mode.
+
+ Args:
+ send_mode: Configured send mode (image/forward/auto)
+ image_count: Number of images to send
+ supports_forward: Whether platform supports forward
+
+ Returns:
+ Effective send mode (image or forward)
+ """
+ if send_mode == "auto":
+ return "forward" if image_count > 1 else "image"
+ if send_mode == "forward" and not supports_forward:
+ return "image"
+ return send_mode
diff --git a/src/shared/__init__.py b/src/shared/__init__.py
new file mode 100644
index 0000000..f4036e3
--- /dev/null
+++ b/src/shared/__init__.py
@@ -0,0 +1,7 @@
+"""Shared low-level helpers and configuration models."""
+
+from __future__ import annotations
+
+from .logging import PrefixedLogger, clear_logger, get_logger
+
+__all__ = ["PrefixedLogger", "clear_logger", "get_logger"]
diff --git a/src/shared/config/__init__.py b/src/shared/config/__init__.py
new file mode 100644
index 0000000..a13b1b6
--- /dev/null
+++ b/src/shared/config/__init__.py
@@ -0,0 +1,49 @@
+"""Shared configuration models."""
+
+from __future__ import annotations
+
+from .models import (
+ AccessControlModeStr,
+ ApiSectionConfig,
+ ApiTypeStr,
+ AtriConfig,
+ CacheConfig,
+ ContentModeStr,
+ CustomApiConfig,
+ DeliveryConfig,
+ FortuneConfig,
+ HtmlCardConfig,
+ HtmlCardStrategyStr,
+ LoliconConfig,
+ MessagesConfig,
+ MultiApiStrategyStr,
+ NapcatStreamModeStr,
+ PerformanceConfig,
+ ProviderConfig,
+ SendModeStr,
+ SetuGeneralConfig,
+ SetuPluginConfig,
+)
+
+__all__ = [
+ "AccessControlModeStr",
+ "ApiSectionConfig",
+ "ApiTypeStr",
+ "AtriConfig",
+ "CacheConfig",
+ "ContentModeStr",
+ "CustomApiConfig",
+ "DeliveryConfig",
+ "FortuneConfig",
+ "HtmlCardConfig",
+ "HtmlCardStrategyStr",
+ "LoliconConfig",
+ "MessagesConfig",
+ "MultiApiStrategyStr",
+ "NapcatStreamModeStr",
+ "PerformanceConfig",
+ "ProviderConfig",
+ "SendModeStr",
+ "SetuGeneralConfig",
+ "SetuPluginConfig",
+]
diff --git a/src/shared/config/models.py b/src/shared/config/models.py
new file mode 100644
index 0000000..66b48b0
--- /dev/null
+++ b/src/shared/config/models.py
@@ -0,0 +1,595 @@
+"""Pydantic v2 configuration models for Setu plugin.
+
+Replaces the ConfigBase + mixin chain with type-safe, validated models.
+Each section mirrors the _conf_schema.json structure for WebUI compatibility.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ImageSize(str, Enum):
+ """Valid image sizes for Lolicon/Atri APIs."""
+
+ ORIGINAL = "original"
+ REGULAR = "regular"
+ SMALL = "small"
+ THUMB = "thumb"
+ MINI = "mini"
+
+
+class AspectRatio(str, Enum):
+ """Valid aspect ratios for filtering."""
+
+ HORIZONTAL = "horizontal"
+ VERTICAL = "vertical"
+ SQUARE = "square"
+
+
+class ContentModeStr(str, Enum):
+ """Content rating modes."""
+
+ SFW = "sfw"
+ R18 = "r18"
+ MIX = "mix"
+
+
+class ApiTypeStr(str, Enum):
+ """API provider types."""
+
+ LOLICON = "lolicon"
+ ATRI = "atri"
+ SEXNYAN = "sexnyan"
+ CUSTOM = "custom"
+ ALL = "all"
+
+
+class MultiApiStrategyStr(str, Enum):
+ """Multi-API strategy types."""
+
+ ROUND_ROBIN = "round_robin"
+ RANDOM = "random"
+ FAILOVER = "failover"
+
+
+class SendModeStr(str, Enum):
+ """Image send modes."""
+
+ IMAGE = "image"
+ FORWARD = "forward"
+ AUTO = "auto"
+
+
+class NapcatStreamModeStr(str, Enum):
+ """NapCat stream upload modes."""
+
+ DISABLED = "disabled"
+ FALLBACK = "fallback"
+ ALWAYS = "always"
+
+
+class HtmlCardStrategyStr(str, Enum):
+ """HTML card strategies."""
+
+ NEVER = "never"
+ FALLBACK = "fallback"
+ ALWAYS = "always"
+
+
+class AccessControlModeStr(str, Enum):
+ """Access control modes."""
+
+ NONE = "none"
+ BLACKLIST = "blacklist"
+ WHITELIST = "whitelist"
+
+
+class ProviderConfig(BaseModel):
+ """Configuration for a single API provider (Lolicon or Atri)."""
+
+ image_size: ImageSize = ImageSize.ORIGINAL
+ proxy: str = "i.pixiv.re"
+ aspect_ratio: AspectRatio | None = None
+ uid: list[int] = Field(default_factory=list)
+ keyword: str = ""
+ exclude_ai: bool = True
+
+ @field_validator("aspect_ratio", mode="before")
+ @classmethod
+ def normalize_empty_aspect_ratio(cls, value: Any) -> Any:
+ """Treat empty-string aspect ratio from schema/config files as None."""
+ if value == "":
+ return None
+ return value
+
+
+class LoliconConfig(ProviderConfig):
+ """Lolicon API specific configuration."""
+
+ pass
+
+
+class AtriConfig(ProviderConfig):
+ """Atri API specific configuration."""
+
+ pass
+
+
+class CustomApiConfig(BaseModel):
+ """Custom API configuration."""
+
+ name: str = "My custom API"
+ url: str = ""
+ method: str = "GET"
+ timeout: int = 30
+ parser_type: str = "auto"
+ json_path: str = ""
+
+
+class SetuGeneralConfig(BaseModel):
+ """Setu general configuration."""
+
+ api_type: ApiTypeStr = ApiTypeStr.LOLICON
+ multi_api_strategy: MultiApiStrategyStr = MultiApiStrategyStr.ROUND_ROBIN
+ content_mode: ContentModeStr = ContentModeStr.SFW
+ max_count: int = Field(default=10, ge=1, le=10)
+ max_replenish_rounds: int = Field(default=3, ge=1, le=3)
+ tag_alias: str = ""
+
+
+class DeliveryConfig(BaseModel):
+ """Image delivery configuration."""
+
+ send_mode: SendModeStr = SendModeStr.IMAGE
+ r18_docx_mode: bool = True
+ auto_handle_send_failure: bool = True
+ auto_revoke_r18: bool = False
+ auto_revoke_delay: int = Field(default=30, ge=5, le=300)
+ napcat_stream_mode: NapcatStreamModeStr = NapcatStreamModeStr.FALLBACK
+
+
+class HtmlCardConfig(BaseModel):
+ """HTML card wrapping configuration."""
+
+ strategy: HtmlCardStrategyStr = HtmlCardStrategyStr.FALLBACK
+ mode: str = "single"
+ card_padding: int = Field(default=6, ge=0, le=30)
+ card_gap: int = Field(default=6, ge=0, le=30)
+
+
+class FortuneConfig(BaseModel):
+ """Fortune (Today's Luck) configuration."""
+
+ enabled: bool = True
+ api_type: str = "inherit"
+ tags: str = ""
+ content_mode: ContentModeStr = ContentModeStr.SFW
+ allow_user_refresh: bool = False
+ auto_refresh: bool = True
+
+
+class CacheConfig(BaseModel):
+ """Disk cache used before adapter-level image sending."""
+
+ enabled: bool = True
+ ttl_hours: int = Field(default=2, ge=1, le=168)
+ max_items: int = Field(default=200, ge=1, le=1000)
+ cleanup_on_start: bool = True
+
+
+class PerformanceConfig(BaseModel):
+ """Performance tuning configuration."""
+
+ enable_range_download: bool = False
+ range_segments: int = Field(default=3, ge=2, le=6)
+ range_download_threshold: int = Field(default=512, ge=256, le=2048)
+ download_concurrent_limit: int = Field(default=10, ge=1, le=50)
+ download_timeout_seconds: int = Field(default=30, ge=5, le=120)
+
+
+class MessagesFetchingConfig(BaseModel):
+ """Fetching message configuration."""
+
+ enabled: bool = True
+ text: str = "正在获取图片，请稍候..."
+
+
+class MessagesFoundConfig(BaseModel):
+ """Found message configuration."""
+
+ enabled: bool = True
+ text: str = "找到 {count} 张符合要求的图片~"
+
+
+class MessagesSendFailedConfig(BaseModel):
+ """Send failed message configuration."""
+
+ text: str = "图片发送失败，请稍后再试。"
+
+
+class MessagesConfig(BaseModel):
+ """User-facing message configuration."""
+
+ fetching: MessagesFetchingConfig = Field(default_factory=MessagesFetchingConfig)
+ found: MessagesFoundConfig = Field(default_factory=MessagesFoundConfig)
+ send_failed: MessagesSendFailedConfig = Field(
+ default_factory=MessagesSendFailedConfig
+ )
+
+
+class SafetyConfig(BaseModel):
+ """Safety and access control configuration."""
+
+ setu_user_access_control_mode: AccessControlModeStr = AccessControlModeStr.NONE
+ setu_group_access_control_mode: AccessControlModeStr = AccessControlModeStr.NONE
+ setu_blocked_users: list[str] = Field(default_factory=list)
+ setu_whitelist_users: list[str] = Field(default_factory=list)
+ setu_blocked_groups: list[str] = Field(default_factory=list)
+ setu_whitelist_groups: list[str] = Field(default_factory=list)
+ fortune_user_access_control_mode: AccessControlModeStr = AccessControlModeStr.NONE
+ fortune_group_access_control_mode: AccessControlModeStr = AccessControlModeStr.NONE
+ fortune_blocked_users: list[str] = Field(default_factory=list)
+ fortune_whitelist_users: list[str] = Field(default_factory=list)
+ fortune_blocked_groups: list[str] = Field(default_factory=list)
+ fortune_whitelist_groups: list[str] = Field(default_factory=list)
+
+
+class SessionTemplateItem(BaseModel):
+ """Session configuration template item."""
+
+ session_id: str = ""
+ session_type: str = "group"
+ content_mode: str = ""
+ r18_docx_mode: str = ""
+ auto_revoke_r18: str = ""
+ send_mode: str = ""
+
+
+class FortuneSessionTemplateItem(BaseModel):
+ """Fortune session configuration template item."""
+
+ session_id: str = ""
+ session_type: str = "group"
+ tags: str = ""
+ content_mode: str = ""
+
+
+class ApiSectionConfig(BaseModel):
+ """API section configuration."""
+
+ lolicon: LoliconConfig = Field(default_factory=LoliconConfig)
+ atri: AtriConfig = Field(default_factory=AtriConfig)
+ custom_api_configs: list[CustomApiConfig] = Field(default_factory=list)
+
+
+class SetuPluginConfig(BaseModel):
+ """Root Pydantic model for Setu plugin configuration.
+
+ This replaces the ConfigBase + mixin chain with a single validated model.
+ The structure mirrors _conf_schema.json for WebUI compatibility.
+
+ The model can be instantiated directly from AstrBotConfig dict:
+ config = SetuPluginConfig(**astrbot_config)
+ """
+
+ setu_general: SetuGeneralConfig = Field(default_factory=SetuGeneralConfig)
+ delivery: DeliveryConfig = Field(default_factory=DeliveryConfig)
+ html_card: HtmlCardConfig = Field(default_factory=HtmlCardConfig)
+ fortune: FortuneConfig = Field(default_factory=FortuneConfig)
+ cache: CacheConfig = Field(default_factory=CacheConfig)
+ api: ApiSectionConfig = Field(default_factory=ApiSectionConfig)
+ messages: MessagesConfig = Field(default_factory=MessagesConfig)
+ safety: SafetyConfig = Field(default_factory=SafetyConfig)
+ performance: PerformanceConfig = Field(default_factory=PerformanceConfig)
+ session_configs: list[SessionTemplateItem] = Field(default_factory=list)
+ fortune_session_configs: list[FortuneSessionTemplateItem] = Field(
+ default_factory=list
+ )
+
+ @field_validator("session_configs")
+ @classmethod
+ def validate_session_configs(
+ cls, v: list[SessionTemplateItem]
+ ) -> list[SessionTemplateItem]:
+ """Validate session configurations."""
+ for item in v:
+ if item.session_type not in ("group", "private"):
+ raise ValueError(f"Invalid session_type: {item.session_type}")
+ return v
+
+ @field_validator("fortune_session_configs")
+ @classmethod
+ def validate_fortune_session_configs(
+ cls, v: list[FortuneSessionTemplateItem]
+ ) -> list[FortuneSessionTemplateItem]:
+ """Validate fortune session configurations."""
+ for item in v:
+ if item.session_type not in ("group", "private"):
+ raise ValueError(f"Invalid session_type: {item.session_type}")
+ return v
+
+ # Convenience properties for backward compatibility
+ @property
+ def api_type(self) -> str:
+ """Get API type."""
+ return self.setu_general.api_type.value
+
+ @property
+ def multi_api_strategy(self) -> str:
+ """Get multi-API strategy."""
+ return self.setu_general.multi_api_strategy.value
+
+ @property
+ def content_mode(self) -> str:
+ """Get content mode."""
+ return self.setu_general.content_mode.value
+
+ @property
+ def max_count(self) -> int:
+ """Get max count."""
+ return self.setu_general.max_count
+
+ @property
+ def max_replenish_rounds(self) -> int:
+ """Get max replenish rounds."""
+ return self.setu_general.max_replenish_rounds
+
+ @property
+ def tag_alias(self) -> str:
+ """Get tag alias string."""
+ return self.setu_general.tag_alias
+
+ @property
+ def send_mode(self) -> str:
+ """Get send mode."""
+ return self.delivery.send_mode.value
+
+ @property
+ def r18_docx_mode(self) -> bool:
+ """Get R18 DOCX mode."""
+ return self.delivery.r18_docx_mode
+
+ @property
+ def auto_revoke_r18(self) -> bool:
+ """Get auto-revoke R18."""
+ return self.delivery.auto_revoke_r18
+
+ @property
+ def auto_revoke_delay(self) -> int:
+ """Get auto-revoke delay."""
+ return self.delivery.auto_revoke_delay
+
+ @property
+ def napcat_stream_mode(self) -> str:
+ """Get NapCat stream upload mode."""
+ return self.delivery.napcat_stream_mode.value
+
+ @property
+ def html_card_strategy(self) -> str:
+ """Get HTML card strategy."""
+ return self.html_card.strategy.value
+
+ @property
+ def html_card_padding(self) -> int:
+ """Get HTML card padding."""
+ return self.html_card.card_padding
+
+ @property
+ def html_card_gap(self) -> int:
+ """Get HTML card gap."""
+ return self.html_card.card_gap
+
+ @property
+ def cache_enabled(self) -> bool:
+ """Get cache enabled."""
+ return self.cache.enabled
+
+ @property
+ def cache_ttl_hours(self) -> int:
+ """Get cache TTL hours."""
+ return self.cache.ttl_hours
+
+ @property
+ def cache_max_items(self) -> int:
+ """Get cache max items."""
+ return self.cache.max_items
+
+ @property
+ def cache_cleanup_on_start(self) -> bool:
+ """Get cache cleanup on start."""
+ return self.cache.cleanup_on_start
+
+ @property
+ def download_concurrent_limit(self) -> int:
+ """Get download concurrent limit."""
+ return self.performance.download_concurrent_limit
+
+ @property
+ def download_timeout_seconds(self) -> int:
+ """Get download timeout seconds."""
+ return self.performance.download_timeout_seconds
+
+ @property
+ def enable_range_download(self) -> bool:
+ """Get enable range download."""
+ return self.performance.enable_range_download
+
+ @property
+ def range_segments(self) -> int:
+ """Get range segments."""
+ return self.performance.range_segments
+
+ @property
+ def range_threshold(self) -> int:
+ """Get range threshold."""
+ return self.performance.range_download_threshold
+
+ @property
+ def exclude_ai(self) -> bool:
+ """Get exclude AI."""
+ return self.api.lolicon.exclude_ai
+
+ @property
+ def image_size(self) -> str:
+ """Get image size."""
+ return self.api.lolicon.image_size.value
+
+ @property
+ def proxy(self) -> str:
+ """Get proxy."""
+ return self.api.lolicon.proxy
+
+ @property
+ def aspect_ratio(self) -> str:
+ """Get aspect ratio."""
+ return (
+ self.api.lolicon.aspect_ratio.value if self.api.lolicon.aspect_ratio else ""
+ )
+
+ @property
+ def uid(self) -> list[int]:
+ """Get UID list."""
+ return self.api.lolicon.uid
+
+ @property
+ def keyword(self) -> str:
+ """Get keyword."""
+ return self.api.lolicon.keyword
+
+ @property
+ def atri_image_size(self) -> str:
+ """Get Atri image size."""
+ return self.api.atri.image_size.value
+
+ @property
+ def atri_proxy(self) -> str:
+ """Get Atri proxy."""
+ return self.api.atri.proxy
+
+ @property
+ def atri_aspect_ratio(self) -> str:
+ """Get Atri aspect ratio."""
+ return self.api.atri.aspect_ratio.value if self.api.atri.aspect_ratio else ""
+
+ @property
+ def atri_uid(self) -> list[int]:
+ """Get Atri UID list."""
+ return self.api.atri.uid
+
+ @property
+ def atri_keyword(self) -> str:
+ """Get Atri keyword."""
+ return self.api.atri.keyword
+
+ @property
+ def atri_exclude_ai(self) -> bool:
+ """Get Atri exclude AI."""
+ return self.api.atri.exclude_ai
+
+ @property
+ def fortune_api_type(self) -> str:
+ """Get fortune API type."""
+ return self.fortune.api_type
+
+ @property
+ def custom_api(self) -> dict[str, Any]:
+ """Get custom API config."""
+ if self.api.custom_api_configs:
+ cfg = self.api.custom_api_configs[0]
+ return {
+ "url": cfg.url,
+ "method": cfg.method,
+ "timeout": cfg.timeout,
+ }
+ return {"url": "", "method": "GET", "timeout": 30}
+
+ @property
+ def api_response_parser(self) -> dict[str, Any]:
+ """Get API response parser config."""
+ if self.api.custom_api_configs:
+ cfg = self.api.custom_api_configs[0]
+ return {
+ "type": cfg.parser_type,
+ "json_path": cfg.json_path,
+ }
+ return {"type": "auto", "json_path": ""}
+
+ @property
+ def custom_api_configs(self) -> list[dict[str, Any]]:
+ """Get custom API configs."""
+ return [cfg.model_dump() for cfg in self.api.custom_api_configs]
+
+ def get_custom_api_config(self, name: str | None = None) -> dict[str, Any] | None:
+ """Get custom API config by name."""
+ configs = self.api.custom_api_configs
+ if not configs:
+ return None
+ if name:
+ for cfg in configs:
+ if cfg.name == name:
+ return cfg.model_dump()
+ return None
+ return configs[0].model_dump()
+
+ @property
+ def msg_fetching_enabled(self) -> bool:
+ """Get fetching message enabled."""
+ return self.messages.fetching.enabled
+
+ @property
+ def msg_fetching_text(self) -> str:
+ """Get fetching message text."""
+ return self.messages.fetching.text
+
+ @property
+ def msg_found_enabled(self) -> bool:
+ """Get found message enabled."""
+ return self.messages.found.enabled
+
+ @property
+ def msg_found_text(self) -> str:
+ """Get found message text."""
+ return self.messages.found.text
+
+ @property
+ def msg_send_failed_text(self) -> str:
+ """Get send failed message text."""
+ return self.messages.send_failed.text
+
+ @property
+ def setu_user_access_control_mode(self) -> str:
+ """Get Setu user access control mode."""
+ return self.safety.setu_user_access_control_mode.value
+
+ @property
+ def setu_group_access_control_mode(self) -> str:
+ """Get Setu group access control mode."""
+ return self.safety.setu_group_access_control_mode.value
+
+ @property
+ def fortune_user_access_control_mode(self) -> str:
+ """Get Fortune user access control mode."""
+ return self.safety.fortune_user_access_control_mode.value
+
+ @property
+ def fortune_group_access_control_mode(self) -> str:
+ """Get Fortune group access control mode."""
+ return self.safety.fortune_group_access_control_mode.value
+
+ def format_found_message(self, count: int, revoke_delay: int | None = None) -> str:
+ """Format found message with placeholders."""
+ result = self.msg_found_text.replace("{count}", str(count))
+ if revoke_delay is not None:
+ result = result.replace("{revoke_delay}", str(revoke_delay))
+ return result
+
+ def get_effective_fortune_api_type(self) -> str:
+ """Get effective fortune API type."""
+ fortune_api = self.fortune.api_type
+ if fortune_api == "inherit":
+ return self.api_type
+ return fortune_api
diff --git a/src/shared/logging.py b/src/shared/logging.py
new file mode 100644
index 0000000..43cf582
--- /dev/null
+++ b/src/shared/logging.py
@@ -0,0 +1,86 @@
+"""AstrBot Setu Plugin 日志包装器
+
+提供带插件前缀的日志记录器，避免直接导出单例实例。
+
+使用示例:
+ from .logger import get_logger
+
+ logger = get_logger()
+ logger.info("消息")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from astrbot.api import logger as _astrbot_logger
+
+
+class PrefixedLogger:
+ """AstrBot 日志包装器，添加插件前缀并正确显示调用位置。"""
+
+ PREFIX = "[setu] "
+ CALLER_STACKLEVEL = 2
+
+ def _add_prefix(self, msg: object) -> str:
+ """为消息添加前缀。"""
+ return self.PREFIX + str(msg)
+
+ def _with_stacklevel(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+ """确保 stacklevel 参数正确传递以显示真实调用位置。"""
+ copied = dict(kwargs)
+ if "stacklevel" not in copied:
+ copied["stacklevel"] = self.CALLER_STACKLEVEL
+ return copied
+
+ def debug(self, msg: object, *args: Any, **kwargs: Any) -> None:
+ _astrbot_logger.debug(
+ self._add_prefix(msg), *args, **self._with_stacklevel(kwargs)
+ )
+
+ def info(self, msg: object, *args: Any, **kwargs: Any) -> None:
+ _astrbot_logger.info(
+ self._add_prefix(msg), *args, **self._with_stacklevel(kwargs)
+ )
+
+ def warning(self, msg: object, *args: Any, **kwargs: Any) -> None:
+ _astrbot_logger.warning(
+ self._add_prefix(msg), *args, **self._with_stacklevel(kwargs)
+ )
+
+ def error(self, msg: object, *args: Any, **kwargs: Any) -> None:
+ _astrbot_logger.error(
+ self._add_prefix(msg), *args, **self._with_stacklevel(kwargs)
+ )
+
+ def exception(self, msg: object, *args: Any, **kwargs: Any) -> None:
+ _astrbot_logger.exception(
+ self._add_prefix(msg), *args, **self._with_stacklevel(kwargs)
+ )
+
+ def critical(self, msg: object, *args: Any, **kwargs: Any) -> None:
+ _astrbot_logger.critical(
+ self._add_prefix(msg), *args, **self._with_stacklevel(kwargs)
+ )
+
+
+# 内部缓存，禁止直接导出
+_logger_instance: PrefixedLogger | None = None
+
+
+def get_logger() -> PrefixedLogger:
+ """获取插件日志记录器单例。
+
+ Returns:
+ PrefixedLogger 实例
+ """
+ global _logger_instance
+ if _logger_instance is None:
+ _logger_instance = PrefixedLogger()
+ return _logger_instance
+
+
+def clear_logger() -> None:
+ """清除日志记录器单例（用于测试）。"""
+ global _logger_instance
+ _logger_instance = None
diff --git a/src/shared/send_cache.py b/src/shared/send_cache.py
new file mode 100644
index 0000000..64da45f
--- /dev/null
+++ b/src/shared/send_cache.py
@@ -0,0 +1,210 @@
+"""Disk-backed send cache for image delivery."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import mimetypes
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .logging import get_logger
+
+logger = get_logger()
+
+_IMAGE_SUFFIXES = {
+ "image/jpeg": ".jpg",
+ "image/jpg": ".jpg",
+ "image/png": ".png",
+ "image/gif": ".gif",
+ "image/webp": ".webp",
+ "image/bmp": ".bmp",
+}
+
+
+def guess_file_suffix(source: str, content_type: str | None = None) -> str:
+ """Guess a file suffix for an image source."""
+ normalized_type = (content_type or "").split(";", 1)[0].strip().lower()
+ if normalized_type in _IMAGE_SUFFIXES:
+ return _IMAGE_SUFFIXES[normalized_type]
+
+ parsed = urlparse(source)
+ guessed = Path(parsed.path).suffix.lower()
+ if guessed in {".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"}:
+ return ".jpg" if guessed == ".jpeg" else guessed
+
+ fallback = mimetypes.guess_extension(normalized_type) if normalized_type else ""
+ return fallback or ".img"
+
+
+@dataclass(frozen=True)
+class SendCacheWrite:
+ """Reserved file paths for one cache write."""
+
+ temp_path: Path
+ final_path: Path
+
+
+class DiskSendCache:
+ """Small URL-addressed disk cache used before platform image sending."""
+
+ def __init__(
+ self,
+ root: Path,
+ *,
+ enabled: bool = True,
+ ttl_hours: int = 2,
+ max_items: int = 200,
+ ) -> None:
+ self.root = root
+ self.enabled = enabled
+ self.ttl_seconds = max(1, int(ttl_hours)) * 60 * 60
+ self.max_items = max(1, int(max_items))
+ self._lock = asyncio.Lock()
+
+ def _key(self, source: str) -> str:
+ return hashlib.sha256(source.encode("utf-8")).hexdigest()
+
+ async def get(self, source: str) -> Path | None:
+ """Return a fresh cached file for the source URL, if present."""
+ if not self.enabled:
+ return None
+
+ key = self._key(source)
+ now = time.time()
+
+ def find() -> Path | None:
+ if not self.root.exists():
+ return None
+ for path in self.root.glob(f"{key}.*"):
+ if path.suffix == ".part" or not path.is_file():
+ continue
+ if now - path.stat().st_mtime > self.ttl_seconds:
+ continue
+ return path
+ return None
+
+ return await asyncio.to_thread(find)
+
+ async def reserve(
+ self, source: str, content_type: str | None = None
+ ) -> SendCacheWrite:
+ """Reserve a temp path and final path for a source URL."""
+ suffix = guess_file_suffix(source, content_type)
+ key = self._key(source)
+ final_path = self.root / f"{key}{suffix}"
+ temp_path = self.root / f"{key}.{time.monotonic_ns()}{suffix}.part"
+
+ await asyncio.to_thread(self.root.mkdir, parents=True, exist_ok=True)
+ return SendCacheWrite(temp_path=temp_path, final_path=final_path)
+
+ async def commit(self, write: SendCacheWrite) -> Path:
+ """Atomically promote a temp cache file to its final path."""
+
+ def replace() -> None:
+ write.temp_path.replace(write.final_path)
+ write.final_path.touch()
+
+ async with self._lock:
+ await asyncio.to_thread(replace)
+ return write.final_path
+
+ async def discard(self, write: SendCacheWrite) -> None:
+ """Delete a failed temp cache file."""
+
+ def unlink() -> None:
+ if write.temp_path.exists():
+ write.temp_path.unlink()
+
+ await asyncio.to_thread(unlink)
+
+ async def cleanup(self) -> int:
+ """Delete expired and overflow cache files."""
+ now = time.time()
+
+ def clean() -> int:
+ if not self.root.exists():
+ return 0
+
+ removed = 0
+ files: list[Path] = []
+ for path in self.root.iterdir():
+ if not path.is_file():
+ continue
+ try:
+ age = now - path.stat().st_mtime
+ except OSError:
+ continue
+ if path.suffix == ".part" and age > 3600:
+ path.unlink(missing_ok=True)
+ removed += 1
+ continue
+ if age > self.ttl_seconds:
+ path.unlink(missing_ok=True)
+ removed += 1
+ continue
+ files.append(path)
+
+ files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+ for path in files[self.max_items :]:
+ path.unlink(missing_ok=True)
+ removed += 1
+ return removed
+
+ removed = await asyncio.to_thread(clean)
+ if removed:
+ logger.debug("[send_cache] cleaned %d cached files", removed)
+ return removed
+
+
+_send_cache: DiskSendCache | None = None
+
+
+async def init_send_cache(
+ data_dir: Path,
+ *,
+ enabled: bool,
+ ttl_hours: int,
+ max_items: int,
+ cleanup_on_start: bool,
+) -> DiskSendCache:
+ """Initialize the process-wide send cache."""
+ global _send_cache
+ _send_cache = DiskSendCache(
+ data_dir / "send_cache",
+ enabled=enabled,
+ ttl_hours=ttl_hours,
+ max_items=max_items,
+ )
+ if cleanup_on_start:
+ await _send_cache.cleanup()
+ return _send_cache
+
+
+def get_send_cache() -> DiskSendCache | None:
+ """Return the configured send cache, if initialized."""
+ return _send_cache
+
+
+def clear_send_cache() -> None:
+ """Clear the process-wide send cache reference."""
+ global _send_cache
+ _send_cache = None
+
+
+def schedule_send_cache_cleanup(delay_seconds: float = 300.0) -> None:
+ """Schedule a best-effort cache cleanup after current sends settle."""
+ cache = _send_cache
+ if cache is None:
+ return
+
+ async def cleanup_later() -> None:
+ await asyncio.sleep(max(0.0, delay_seconds))
+ await cache.cleanup()
+
+ try:
+ asyncio.create_task(cleanup_later())
+ except RuntimeError:
+ logger.debug("[send_cache] no running loop for delayed cleanup")
diff --git a/templates/fortune.html b/templates/fortune.html
deleted file mode 100644
index 1023ee3..0000000
--- a/templates/fortune.html
+++ /dev/null
@@ -1,219 +0,0 @@
-
-
-
-
-
- 
- {% else %}
-