# 中文注释：
# 文件：echobot/utils/helpers.py
# 说明：通用工具函数。

"""Utility functions for echobot."""

from pathlib import Path
from datetime import datetime


def ensure_dir(path: Path) -> Path:
    """Ensure a directory exists, creating it if necessary."""
    path.mkdir(parents=True, exist_ok=True)
    return path


def get_data_path(instance: str | None = None) -> Path:
    """
    Get the echobot data directory.

    如果不指定 instance，返回默认数据目录 ~/.echobot。
    如果指定 instance，返回该实例的数据目录 ~/.echobot/instances/{instance}。

    此函数支持多实例隔离架构，每个实例拥有独立的数据目录，
    包括配置、会话、工作区等。

    参数:
        instance: 可选的实例名称。如果提供，返回该实例的数据目录；
                 如果为 None，返回默认数据目录。

    返回:
        Path: 数据目录的路径

    示例:
        >>> get_data_path()
        PosixPath('/home/user/.echobot')
        >>> get_data_path("admin")
        PosixPath('/home/user/.echobot/instances/admin')
    """
    if instance:
        # 返回实例特定的数据目录
        return ensure_dir(Path.home() / ".echobot" / "instances" / instance)
    # 返回默认数据目录（向后兼容）
    return ensure_dir(Path.home() / ".echobot")


def get_workspace_path(workspace: str | None = None, instance: str | None = None) -> Path:
    """
    Get the workspace path.

    支持多实例隔离架构。如果不指定 instance，返回默认工作区目录；
    如果指定 instance，返回该实例的工作区目录。

    参数:
        workspace: 可选的工作区路径。如果提供，使用该路径；
                  如果为 None，使用默认或实例特定的工作区。
        instance: 可选的实例名称。如果提供，返回该实例的工作区目录；
                 如果为 None，返回默认工作区目录。

    Returns:
        Expanded and ensured workspace path.

    示例:
        >>> get_workspace_path()
        PosixPath('/home/user/.echobot/workspace')
        >>> get_workspace_path(instance="admin")
        PosixPath('/home/user/.echobot/instances/admin/workspace')
    """
    if workspace:
        # 如果显式指定了工作区路径，使用它
        path = Path(workspace).expanduser()
    elif instance:
        # 如果指定了实例，使用实例的工作区
        path = get_data_path(instance) / "workspace"
    else:
        # 默认工作区（向后兼容）
        path = Path.home() / ".echobot" / "workspace"
    return ensure_dir(path)


def get_sessions_path(instance: str | None = None) -> Path:
    """
    Get the sessions storage directory.

    支持多实例隔离架构。如果不指定 instance，返回默认会话目录；
    如果指定 instance，返回该实例的会话目录。

    参数:
        instance: 可选的实例名称。如果提供，返回该实例的会话目录；
                 如果为 None，返回默认会话目录。

    返回:
        Path: 会话存储目录的路径

    示例:
        >>> get_sessions_path()
        PosixPath('/home/user/.echobot/sessions')
        >>> get_sessions_path(instance="admin")
        PosixPath('/home/user/.echobot/instances/admin/sessions')
    """
    return ensure_dir(get_data_path(instance) / "sessions")


def get_memory_path(workspace: Path | None = None) -> Path:
    """Get the memory directory within the workspace."""
    ws = workspace or get_workspace_path()
    return ensure_dir(ws / "memory")


def get_skills_path(workspace: Path | None = None) -> Path:
    """Get the skills directory within the workspace."""
    ws = workspace or get_workspace_path()
    return ensure_dir(ws / "skills")


def today_date() -> str:
    """Get today's date in YYYY-MM-DD format."""
    return datetime.now().strftime("%Y-%m-%d")


def timestamp() -> str:
    """Get current timestamp in ISO format."""
    return datetime.now().isoformat()


def truncate_string(s: str, max_len: int = 100, suffix: str = "...") -> str:
    """Truncate a string to max length, adding suffix if truncated."""
    if len(s) <= max_len:
        return s
    return s[: max_len - len(suffix)] + suffix


def safe_filename(name: str) -> str:
    """Convert a string to a safe filename."""
    # Replace unsafe characters
    unsafe = '<>:"/\\|?*'
    for char in unsafe:
        name = name.replace(char, "_")
    return name.strip()


def parse_session_key(key: str) -> tuple[str, str]:
    """
    Parse a session key into channel and chat_id.

    Args:
        key: Session key in format "channel:chat_id"

    Returns:
        Tuple of (channel, chat_id)
    """
    parts = key.split(":", 1)
    if len(parts) != 2:
        raise ValueError(f"Invalid session key: {key}")
    return parts[0], parts[1]
