bdpan-cli 0.1.0__py3-none-any.whl

bdpan_cli/file_manager.py

@@ -0,0 +1,389 @@
+"""文件与目录管理客户端，封装创建、重命名、移动等能力。"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+from bdpan_cli._vendor import openapi_client
+from bdpan_cli._vendor.openapi_client.api.fileinfo_api import FileinfoApi
+from bdpan_cli._vendor.openapi_client.api.filemanager_api import FilemanagerApi
+from bdpan_cli._vendor.openapi_client.api.fileupload_api import FileuploadApi
+from bdpan_cli._vendor.openapi_client.rest import ApiException
+
+logger = logging.getLogger(__name__)
+
+WalkResult = tuple[list[tuple[int, dict[str, Any]]], list[tuple[str, str]]]
+
+
+class FileManagerError(RuntimeError):
+    """文件管理异常基类。"""
+
+
+def _validate_filemanager_result(res: Any, prefix: str) -> dict[str, Any]:
+    """统一校验 filemanager 四原语（copy/move/rename/delete）的响应。
+
+    响应形如 ``{"errno": 0, "info": [{"errno": 0, ...}, ...]}``，批量场景下
+    存在顶层 errno=0 但个别条目 info[].errno != 0 的部分失败形态，仅校验
+    顶层会漏报，故逐项复核；任一非零即抛 FileManagerError。部分响应可能
+    无 info 字段或缺省条目 errno，视作通过以免对未记载形态误报。
+    """
+    if not isinstance(res, dict) or res.get("errno") != 0:
+        raise FileManagerError(f"{prefix}: {res}")
+    info = res.get("info")
+    if isinstance(info, list):
+        for idx, item in enumerate(info, 1):
+            if isinstance(item, dict) and item.get("errno") not in (0, None):
+                raise FileManagerError(f"{prefix}: 第 {idx} 项失败 errno={item['errno']} ({item})")
+    return res
+
+
+class FileManager:
+    """网盘文件与目录管理封装。"""
+
+    def __init__(self, access_token: str, api_client: openapi_client.ApiClient | None = None) -> None:
+        self.access_token = access_token
+        self.api_client = api_client or openapi_client.ApiClient()
+        self._fileinfo_api = FileinfoApi(self.api_client)
+        self._filemanager_api = FilemanagerApi(self.api_client)
+        self._fileupload_api = FileuploadApi(self.api_client)
+
+    def list_dir(self, dir_path: str, limit: int = 1000) -> list[dict[str, Any]]:
+        """全量列出指定目录下的条目。"""
+        all_entries: list[dict[str, Any]] = []
+        start = 0
+        page_size = min(limit, 1000)
+        while True:
+            try:
+                res = self._fileinfo_api.xpanfilelist(
+                    access_token=self.access_token,
+                    dir=dir_path,
+                    start=str(start),
+                    limit=page_size,
+                    web="1",
+                    order="name",
+                )
+            except ApiException as e:
+                raise FileManagerError(f"读取目录失败 [{dir_path}]: {e.status} {e.body}") from e
+
+            entries = res.get("list", [])
+            if not entries:
+                break
+            all_entries.extend(entries)
+            if len(entries) < page_size:
+                break
+            start += len(entries)
+        return all_entries
+
+    def get_file_info(self, path: str) -> dict[str, Any] | None:
+        """获取指定网盘文件/目录的元信息。
+
+        通过探测其父目录条目列表，按 path 精确匹配返回单条 entry；
+        若不存在则返回 None。
+        """
+        path = "/" + path.strip("/") if not path.startswith("/") else path
+        if path == "/":
+            return {"fs_id": 0, "path": "/", "server_filename": "", "isdir": 1, "size": 0}
+        parent = os.path.dirname(path) or "/"
+        try:
+            entries = self.list_dir(parent)
+            for entry in entries:
+                if entry.get("path") == path:
+                    return entry
+            return None
+        except FileManagerError:
+            return None
+
+    def walk(self, root: str, max_depth: int | None = None) -> WalkResult:
+        """深度优先递归遍历网盘子树。
+
+        引擎说明：SDK 的 MultimediafileApi.xpanfilelistall 在当前应用权限下
+        对所有路径均返回 errno=20020「该路径不在允许的访问范围内」（实测，
+        含应用自建目录），故采用已验证可用的 xpanfilelist 客户端侧逐层递归，
+        每个子目录一次 API 调用。
+
+        Args:
+            root: 遍历起点目录。
+            max_depth: 最大遍历深度（root 直接子项为深度 0）；None 为不限。
+
+        Returns:
+            (entries, errors) 二元组：
+            - entries: (depth, entry) 列表，DFS 先序，depth 相对 root；
+            - errors: (path, errmsg) 列表，记录不可读目录；单个子目录
+              读取失败不中断遍历（降级可观测），root 失败时 entries 为空。
+        """
+        entries: list[tuple[int, dict[str, Any]]] = []
+        errors: list[tuple[str, str]] = []
+        self._walk_recursive(root, 0, max_depth, entries, errors)
+        return entries, errors
+
+    def _walk_recursive(
+        self,
+        path: str,
+        depth: int,
+        max_depth: int | None,
+        entries: list[tuple[int, dict[str, Any]]],
+        errors: list[tuple[str, str]],
+    ) -> None:
+        try:
+            children = self.list_dir(path)
+        except FileManagerError as e:
+            logger.warning("遍历跳过不可读目录 [%s]: %s", path, e)
+            errors.append((path, str(e)))
+            return
+        for entry in children:
+            entries.append((depth, entry))
+            if entry.get("isdir") == 1 and (max_depth is None or depth + 1 < max_depth):
+                self._walk_recursive(entry["path"], depth + 1, max_depth, entries, errors)
+
+    def search(
+        self,
+        key: str,
+        dir_path: str | None = None,
+        recursion: bool = True,
+        page: int = 1,
+        num: int = 100,
+    ) -> list[dict[str, Any]]:
+        """按关键词搜索网盘文件（单页结果）。
+
+        Args:
+            key: 搜索关键词。
+            dir_path: 限定搜索目录（None 为全盘）。
+            recursion: 是否递归子目录。
+            page: 页码（从 1 起）。
+            num: 每页条数。
+
+        Returns:
+            当前页条目列表，条目字段同 list_dir（fs_id/path/server_filename/size/isdir 等）。
+        """
+        kwargs: dict[str, Any] = {
+            "web": "1",
+            "num": str(num),
+            "page": str(page),
+            "recursion": "1" if recursion else "0",
+        }
+        if dir_path:
+            kwargs["dir"] = dir_path
+        try:
+            res = self._fileinfo_api.xpanfilesearch(
+                access_token=self.access_token,
+                key=key,
+                **kwargs,
+            )
+        except ApiException as e:
+            raise FileManagerError(f"搜索失败 [{key}]: {e.status} {e.body}") from e
+        return res.get("list", []) if isinstance(res, dict) else []
+
+    def mkdir(self, path: str) -> dict[str, Any]:
+        """创建目录。若目录已存在，视作正常成功。"""
+        try:
+            res = self._fileupload_api.xpanfilecreate(
+                access_token=self.access_token,
+                path=path,
+                isdir=1,
+                size=0,
+                uploadid="",
+                block_list="[]",
+                rtype=1,
+            )
+            # errno=-8 代表文件/目录已存在
+            if isinstance(res, dict) and res.get("errno") not in (0, -8, None):
+                raise FileManagerError(f"创建目录服务端返回异常 [{path}]: {res}")
+            return res if isinstance(res, dict) else {}
+        except ApiException as e:
+            raise FileManagerError(f"创建目录失败 [{path}]: {e.status} {e.body}") from e
+
+    def rename(self, path: str, new_name: str) -> dict[str, Any]:
+        """重命名单个文件或目录。"""
+        filelist = json.dumps([{"path": path, "newname": new_name}], ensure_ascii=False)
+        try:
+            res = self._filemanager_api.filemanagerrename(
+                access_token=self.access_token,
+                _async=0,
+                filelist=filelist,
+            )
+        except ApiException as e:
+            raise FileManagerError(f"重命名失败 [{path} -> {new_name}]: {e.status} {e.body}") from e
+
+        return _validate_filemanager_result(res, f"重命名返回错误 [{path} -> {new_name}]")
+
+    def batch_rename(
+        self,
+        items: list[tuple[str, str]],
+        batch_size: int = 50,
+    ) -> list[dict[str, Any]]:
+        """批量重命名文件或目录。
+
+        Args:
+            items: 包含 (src_path, new_name) 的元组列表。
+            batch_size: 每批请求的最大数量（默认 50）。
+
+        Returns:
+            各批次成功结果列表。
+        """
+        results: list[dict[str, Any]] = []
+        for i in range(0, len(items), batch_size):
+            chunk = items[i : i + batch_size]
+            payload = [{"path": src, "newname": newname} for src, newname in chunk]
+            filelist = json.dumps(payload, ensure_ascii=False)
+            try:
+                res = self._filemanager_api.filemanagerrename(
+                    access_token=self.access_token,
+                    _async=0,
+                    filelist=filelist,
+                )
+            except ApiException as e:
+                raise FileManagerError(f"批量重命名批次 {i // batch_size + 1} 失败: {e.status} {e.body}") from e
+
+            _validate_filemanager_result(res, f"批量重命名批次 {i // batch_size + 1} 返回错误")
+            results.append(res)
+        return results
+
+
+    def batch_move(
+        self,
+        items: list[tuple[str, str, str]],
+        batch_size: int = 50,
+    ) -> list[dict[str, Any]]:
+        """批量移动文件或目录。
+
+        Args:
+            items: 包含 (src_path, dest_dir, new_name) 的元组列表。
+            batch_size: 每批请求的最大数量（默认 50，避免接口超时或截断）。
+
+        Returns:
+            各批次成功结果列表。
+        """
+        results: list[dict[str, Any]] = []
+        for i in range(0, len(items), batch_size):
+            chunk = items[i : i + batch_size]
+            payload = [
+                {"path": src, "dest": dest, "newname": name}
+                for src, dest, name in chunk
+            ]
+            filelist = json.dumps(payload, ensure_ascii=False)
+            try:
+                res = self._filemanager_api.filemanagermove(
+                    access_token=self.access_token,
+                    _async=0,
+                    filelist=filelist,
+                )
+            except ApiException as e:
+                raise FileManagerError(f"批量移动批次 {i // batch_size + 1} 失败: {e.status} {e.body}") from e
+
+            _validate_filemanager_result(res, f"批量移动批次 {i // batch_size + 1} 返回错误")
+            results.append(res)
+        return results
+
+    def copy(self, path: str, dest_dir: str, new_name: str) -> dict[str, Any]:
+        """复制单个文件或目录到目标目录。
+
+        与 batch_copy 共用同一请求与校验通道，但不经批量入口，错误文案
+        按单项语境表述（不出现"批量复制批次 N"字样）。
+        """
+        payload = [{"path": path, "dest": dest_dir, "newname": new_name}]
+        return self._copy_request(
+            payload,
+            api_ctx=f"复制 [{path} -> {dest_dir}/{new_name}]",
+            err_prefix=f"复制返回错误 [{path} -> {dest_dir}/{new_name}]",
+        )
+
+    def batch_copy(
+        self,
+        items: list[tuple[str, str, str]],
+        batch_size: int = 50,
+    ) -> list[dict[str, Any]]:
+        """批量复制文件或目录。
+
+        Args:
+            items: 包含 (src_path, dest_dir, new_name) 的元组列表。
+            batch_size: 每批请求的最大数量（默认 50，避免接口超时或截断）。
+
+        Returns:
+            各批次成功结果列表。
+        """
+        results: list[dict[str, Any]] = []
+        for i in range(0, len(items), batch_size):
+            chunk = items[i : i + batch_size]
+            payload = [
+                {"path": src, "dest": dest, "newname": name}
+                for src, dest, name in chunk
+            ]
+            res = self._copy_request(
+                payload,
+                api_ctx=f"批量复制批次 {i // batch_size + 1}",
+                err_prefix=f"批量复制批次 {i // batch_size + 1} 返回错误",
+            )
+            results.append(res)
+        return results
+
+    def _copy_request(
+        self,
+        payload: list[dict[str, str]],
+        api_ctx: str,
+        err_prefix: str,
+    ) -> dict[str, Any]:
+        """执行单次 filemanagercopy 请求并统一校验。
+
+        api_ctx 用于 ApiException 文案（"…失败"），err_prefix 用于
+        响应校验文案（"…返回错误"），二者分离以保持既有文案逐字不变。
+        """
+        filelist = json.dumps(payload, ensure_ascii=False)
+        try:
+            res = self._filemanager_api.filemanagercopy(
+                access_token=self.access_token,
+                _async=0,
+                filelist=filelist,
+            )
+        except ApiException as e:
+            raise FileManagerError(f"{api_ctx}失败: {e.status} {e.body}") from e
+
+        return _validate_filemanager_result(res, err_prefix)
+
+    def batch_delete(
+        self,
+        paths: list[str],
+        batch_size: int = 50,
+    ) -> list[dict[str, Any]]:
+        """批量删除文件或目录（服务端移入回收站）。
+
+        Args:
+            paths: 待删除的文件或目录路径列表。
+            batch_size: 每批请求的最大数量（默认 50，避免接口超时或截断）。
+
+        Returns:
+            各批次成功结果列表。
+        """
+        results: list[dict[str, Any]] = []
+        for i in range(0, len(paths), batch_size):
+            chunk = paths[i : i + batch_size]
+            filelist = json.dumps(chunk, ensure_ascii=False)
+            try:
+                res = self._filemanager_api.filemanagerdelete(
+                    access_token=self.access_token,
+                    _async=0,
+                    filelist=filelist,
+                )
+            except ApiException as e:
+                raise FileManagerError(f"批量删除批次 {i // batch_size + 1} 失败: {e.status} {e.body}") from e
+
+            _validate_filemanager_result(res, f"批量删除批次 {i // batch_size + 1} 返回错误")
+            results.append(res)
+        return results
+
+    def delete(self, path: str) -> dict[str, Any]:
+        """删除单个文件或目录。"""
+        filelist = json.dumps([path], ensure_ascii=False)
+        try:
+            res = self._filemanager_api.filemanagerdelete(
+                access_token=self.access_token,
+                _async=0,
+                filelist=filelist,
+            )
+        except ApiException as e:
+            raise FileManagerError(f"删除失败 [{path}]: {e.status} {e.body}") from e
+
+        return _validate_filemanager_result(res, f"删除返回错误 [{path}]")
+

bdpan_cli/foldering.py

@@ -0,0 +1,181 @@
+"""散落电影/视频/压缩包文件自动规整：识别并创建方案 A 规范目录并将文件移入。"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import Any
+
+from bdpan_cli.file_manager import FileManager
+from bdpan_cli.preview_scrape import is_already_conforming
+from bdpan_cli.scraper import MovieScraper
+
+logger = logging.getLogger(__name__)
+
+MEDIA_EXTENSIONS = {
+    ".mkv",
+    ".mp4",
+    ".avi",
+    ".mov",
+    ".wmv",
+    ".ts",
+    ".iso",
+    ".zip",
+    ".7z",
+    ".rar",
+}
+
+SUBTITLE_EXTENSIONS = {
+    ".srt",
+    ".ass",
+    ".sub",
+    ".vtt",
+}
+
+ALLOWED_EXTENSIONS = MEDIA_EXTENSIONS | SUBTITLE_EXTENSIONS
+
+
+def plan_foldering(
+    dir_path: str,
+    mgr: FileManager,
+    scraper: MovieScraper | None = None,
+    name_format: str | None = None,
+) -> list[dict[str, Any]]:
+    """扫描目标目录下散落的音视频、字幕与非规范子目录，生成方案 A 规范目录归集计划。
+
+    返回列表中的每一项表示一个待创建的独立电影目录及归入其中的文件清单。
+    支持自定义命名模板 name_format。
+    """
+    if scraper is None:
+        scraper = MovieScraper()
+
+    logger.info("正在扫描目录 %s 中的待整理媒体与子目录...", dir_path)
+    entries = mgr.list_dir(dir_path)
+
+    # 1. 过滤散落媒体文件与非规范子目录
+    media_groups: list[dict[str, Any]] = []
+    for item in entries:
+        if item.get("isdir") == 1:
+            subdir_name = item.get("server_filename", "")
+            # 若子目录已经严格符合方案 A 规范，跳过不处理（未指定自定义模板时）
+            if not name_format and is_already_conforming(subdir_name):
+                continue
+            # 否则扫描非规范子目录内部的媒体文件与字幕
+            sub_path = item.get("path", f"{dir_path}/{subdir_name}")
+            try:
+                sub_entries = mgr.list_dir(sub_path)
+            except Exception as e:
+                logger.warning("扫描子目录失败 [%s]: %s", subdir_name, e)
+                continue
+
+            sub_media = []
+            for sub_item in sub_entries:
+                if sub_item.get("isdir") == 1:
+                    continue
+                sfname = sub_item.get("server_filename", "")
+                _, sext = os.path.splitext(sfname)
+                if sext.lower() in ALLOWED_EXTENSIONS:
+                    sub_media.append(sub_item)
+
+            if sub_media:
+                media_groups.append({
+                    "query_name": subdir_name,
+                    "files": sub_media,
+                    "source_dir": sub_path,
+                })
+        else:
+            fname = item.get("server_filename", "")
+            _, ext = os.path.splitext(fname)
+            if ext.lower() in ALLOWED_EXTENSIONS:
+                base_name, _ = os.path.splitext(fname)
+                media_groups.append({
+                    "query_name": base_name,
+                    "files": [item],
+                    "source_dir": None,
+                })
+
+    logger.info("共发现 %d 组待整理媒体项", len(media_groups))
+
+    # 2. 逐一识别并匹配方案 A 规范目录名
+    folder_groups: dict[str, list[dict[str, Any]]] = {}
+
+    for group in media_groups:
+        query_name = group["query_name"]
+        base_name, _ = os.path.splitext(query_name)
+        is_trailer = bool(re.search(r"Theatrical\s*Trailer|Trailer|预告片?", base_name, re.IGNORECASE))
+        query = base_name
+        if is_trailer:
+            query = re.sub(r"Theatrical\s*Trailer|Trailer|预告片?", " ", query, flags=re.IGNORECASE).strip()
+
+        # 特殊情况消歧：例如张艺谋《狙击手》无年份标注但打包于2022
+        if "狙击手" in query and not re.search(r"\b(19\d{2}|20\d{2})\b", query):
+            query = f"{query} 2022"
+
+        meta = scraper.scrape_folder_name(query)
+        if meta and meta.formatted_name:
+            target_name = meta.format_name(name_format)
+            if not name_format:
+                # 方案 A 默认：净化中英文标点与逗号
+                target_name = re.sub(r"[\/\\:\*\?\"<>\|\s_,]+", ".", target_name.strip())
+                target_name = re.sub(r"\.{2,}", ".", target_name).strip(".")
+            if is_trailer and not target_name.endswith(".Trailer"):
+                target_name = f"{target_name}.Trailer"
+        else:
+            # 无法识别时回退为原文件名（去除扩展名）
+            target_name = base_name.strip(".")
+
+        if target_name not in folder_groups:
+            folder_groups[target_name] = []
+
+        for f_item in group["files"]:
+            fname = f_item.get("server_filename", "")
+            fpath = f_item.get("path", f"{dir_path}/{fname}")
+            folder_groups[target_name].append({
+                "filename": fname,
+                "path": fpath,
+                "size": f_item.get("size", 0),
+                "is_trailer": is_trailer,
+            })
+
+    # 3. 组织为计划清单
+    plan: list[dict[str, Any]] = []
+    for folder_name, files in folder_groups.items():
+        plan.append({
+            "target_folder_name": folder_name,
+            "target_folder_path": f"{dir_path}/{folder_name}",
+            "files": files,
+        })
+
+    return plan
+
+
+def execute_foldering(
+    dir_path: str,
+    plan: list[dict[str, Any]],
+    mgr: FileManager,
+    batch_size: int = 25,
+) -> dict[str, int]:
+    """依据整理计划执行目录创建与文件原子移动。"""
+    created_count = 0
+    items_to_move: list[tuple[str, str, str]] = []
+
+    # 1. 批量创建目标方案 A 电影目录
+    for group in plan:
+        target_dir = group["target_folder_path"]
+        logger.info("创建电影规范目录: %s", target_dir)
+        mgr.mkdir(target_dir)
+        created_count += 1
+
+        for f in group["files"]:
+            items_to_move.append((f["path"], target_dir, f["filename"]))
+
+    # 2. 批量将散落文件移入对应的电影目录
+    logger.info("正在批量移动 %d 个文件至对应规范电影目录...", len(items_to_move))
+    mgr.batch_move(items_to_move, batch_size=batch_size)
+
+    logger.info("完成规整！共创建 %d 个目录，移动 %d 个文件", created_count, len(items_to_move))
+    return {
+        "folders_created": created_count,
+        "files_moved": len(items_to_move),
+    }

bdpan_cli/logger.py

@@ -0,0 +1,101 @@
+"""bdpan-cli 日志治理模块 (BK-0041).
+
+实现方案 A 日志体系：
+1. 终端与日志流解耦：控制台日志输出至 sys.stderr，保留 sys.stdout 给表格、进度与 --json 机器信封；
+2. 动态级别控制：支持全局 --debug / -v（输出详细诊断与异常追踪）与 --quiet / -q（静音非错误输出）；
+3. 本地滚动日志双写：自动将完整诊断日志（DEBUG 级别）持久化写入 ~/.config/bdpan/logs/bdpan.log（10MB x 5 轮转备份）。
+"""
+
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+from pathlib import Path
+import sys
+
+DEFAULT_LOG_DIR = Path.home() / ".config" / "bdpan" / "logs"
+DEFAULT_LOG_FILE = DEFAULT_LOG_DIR / "bdpan.log"
+
+_LOGGING_INITIALIZED = False
+
+
+def get_log_file_path() -> Path:
+    """获取默认日志落盘路径，支持 BDPAN_LOG_FILE 环境变量覆盖。"""
+    env_path = os.environ.get("BDPAN_LOG_FILE")
+    if env_path:
+        return Path(env_path)
+    return DEFAULT_LOG_FILE
+
+
+def setup_logging(
+    debug: bool = False,
+    quiet: bool = False,
+    log_file: Path | str | None = None,
+) -> None:
+    """初始化并配置全局日志系统。
+    
+    :param debug: 是否开启调试模式（详细 Traceback、代码行号与请求响应体）
+    :param quiet: 是否开启静音模式（仅打印 ERROR 及以上）
+    :param log_file: 自定义日志文件路径，为 None 时使用默认 ~/.config/bdpan/logs/bdpan.log
+    """
+    global _LOGGING_INITIALIZED
+
+    target_log_file = Path(log_file) if log_file else get_log_file_path()
+
+    # 确定控制台输出级别
+    if quiet:
+        console_level = logging.ERROR
+    elif debug:
+        console_level = logging.DEBUG
+    else:
+        console_level = logging.INFO
+
+    # 确定格式
+    if debug:
+        console_fmt = "%(asctime)s [%(levelname)s] [%(name)s:%(lineno)d] %(message)s"
+    else:
+        console_fmt = "%(asctime)s [%(levelname)s] %(message)s"
+    file_fmt = "%(asctime)s [%(levelname)s] [%(name)s:%(lineno)d] %(message)s"
+
+    # 配置根 bdpan_cli logger
+    logger = logging.getLogger("bdpan_cli")
+    logger.setLevel(logging.DEBUG)  # 保持最低级别，由 handlers 分别过滤
+
+    # 清理既有 handlers 避免重复添加
+    for handler in list(logger.handlers):
+        logger.removeHandler(handler)
+
+    # 1. 控制台 Handler (输出至 stderr，确保 stdout 纯净)
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(console_level)
+    console_handler.setFormatter(logging.Formatter(console_fmt))
+    logger.addHandler(console_handler)
+
+    # 2. 文件 Handler (自动滚动记录，始终保留完整 DEBUG 诊断细节)
+    try:
+        target_log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = RotatingFileHandler(
+            target_log_file,
+            maxBytes=10 * 1024 * 1024,  # 10 MB
+            backupCount=5,
+            encoding="utf-8",
+        )
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(logging.Formatter(file_fmt))
+        logger.addHandler(file_handler)
+    except OSError as err:
+        # 权限或文件系统异常时降级处理，不阻断主业务
+        logger.warning("无法创建本地日志文件 %s: %s", target_log_file, err)
+
+    # 调整底层 HTTP 客户端日志级别
+    urllib3_logger = logging.getLogger("urllib3")
+    if debug:
+        urllib3_logger.setLevel(logging.DEBUG)
+    else:
+        urllib3_logger.setLevel(logging.WARNING)
+
+    _LOGGING_INITIALIZED = True
+
+
+def get_logger(name: str = "bdpan_cli") -> logging.Logger:
+    """获取标准命名空间 logger。"""
+    return logging.getLogger(name)